diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 38e523e..5cf3306 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -74,7 +74,7 @@ Both are FOSS with independent governance (no Big Tech). ### Package Management - **Primary**: Guix (guix.scm) -- **Fallback**: Nix (flake.nix) +- **Fallback**: Guix (flake.guix) - **JS deps**: Deno (deno.json imports) ### Security Requirements diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 7d753c6..9774de0 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -19,7 +19,7 @@ updates: actions: patterns: - "*" - - package-ecosystem: "nix" + - package-ecosystem: "guix" directory: "/" schedule: interval: "weekly" diff --git a/.github/workflows/governance.yml b/.github/workflows/governance.yml index c589f75..25a3fd6 100644 --- a/.github/workflows/governance.yml +++ b/.github/workflows/governance.yml @@ -4,7 +4,7 @@ # in hyperpolymath/standards instead of carrying per-repo copies. # # Replaces the per-repo governance scaffolding removed in the same commit: -# quality.yml, guix-nix-policy.yml, npm-bun-blocker.yml, ts-blocker.yml, +# quality.yml, guix-guix-policy.yml, npm-bun-blocker.yml, ts-blocker.yml, # security-policy.yml, rsr-antipattern.yml, wellknown-enforcement.yml, # workflow-linter.yml # diff --git a/ABI-FFI-README.md b/ABI-FFI-README.adoc similarity index 73% rename from ABI-FFI-README.md rename to ABI-FFI-README.adoc index ada05ff..04be86a 100644 --- a/ABI-FFI-README.md +++ b/ABI-FFI-README.adoc @@ -1,23 +1,22 @@ - -{{~ Aditionally delete this line and fill out the template below ~}} +\{\{~ Aditionally delete this line and fill out the template below ~}} -# {{PROJECT}} ABI/FFI Documentation +== \{\{PROJECT}} ABI/FFI Documentation -## Overview +=== Overview -This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: +This library follows the *Hyperpolymath RSR Standard* for ABI and FFI +design: -- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs -- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility -- **Generated C headers** bridge Idris2 ABI to Zig FFI -- **Any language** can call through standard C ABI +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility +* *Generated C headers* bridge Idris2 ABI to Zig FFI +* *Any language* can call through standard C ABI -## Architecture +=== Architecture -``` +.... ┌─────────────────────────────────────────────┐ │ ABI Definitions (Idris2) │ │ src/abi/ │ @@ -47,13 +46,13 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: ▼ ┌─────────────────────────────────────────────┐ │ Any Language via C ABI │ -│ - Rust, ReScript, Julia, Python, etc. │ +│ - Rust, AffineScript, Julia, Python, etc. │ └─────────────────────────────────────────────┘ -``` +.... -## Directory Structure +=== Directory Structure -``` +.... {{project}}/ ├── src/ │ ├── abi/ # ABI definitions (Idris2) @@ -79,17 +78,19 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: │ └── bindings/ # Language-specific wrappers (optional) ├── rust/ - ├── rescript/ + ├── affinescript/ └── julia/ -``` +.... -## Why Idris2 for ABI? +=== Why Idris2 for ABI? -### 1. **Formal Verification** +==== 1. *Formal Verification* -Idris2's dependent types allow proving properties about the ABI at compile-time: +Idris2’s dependent types allow proving properties about the ABI at +compile-time: -```idris +[source,idris] +---- -- Prove struct size is correct public export exampleStructSize : HasSize ExampleStruct 16 @@ -101,13 +102,14 @@ fieldAligned : Divides 8 (offsetOf ExampleStruct.field) -- Prove ABI is platform-compatible public export abiCompatible : Compatible (ABI 1) (ABI 2) -``` +---- -### 2. **Type Safety** +==== 2. *Type Safety* Encode invariants that C/Zig cannot express: -```idris +[source,idris] +---- -- Non-null pointer guaranteed at type level data Handle : Type where MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle @@ -115,13 +117,14 @@ data Handle : Type where -- Array with length proof data Buffer : (n : Nat) -> Type where MkBuffer : Vect n Byte -> Buffer n -``` +---- -### 3. **Platform Abstraction** +==== 3. *Platform Abstraction* Platform-specific types with compile-time selection: -```idris +[source,idris] +---- CInt : Platform -> Type CInt Linux = Bits32 CInt Windows = Bits32 @@ -129,13 +132,14 @@ CInt Windows = Bits32 CSize : Platform -> Type CSize Linux = Bits64 CSize Windows = Bits64 -``` +---- -### 4. **Safe Evolution** +==== 4. *Safe Evolution* Prove that new ABI versions are backward-compatible: -```idris +[source,idris] +---- -- Compiler enforces compatibility abiUpgrade : ABI 1 -> ABI 2 abiUpgrade old = MkABI2 { @@ -144,71 +148,78 @@ abiUpgrade old = MkABI2 { -- Can add new fields new_features = defaults } -``` +---- -## Why Zig for FFI? +=== Why Zig for FFI? -### 1. **C ABI Compatibility** +==== 1. *C ABI Compatibility* Zig exports C-compatible functions naturally: -```zig +[source,zig] +---- export fn library_function(param: i32) i32 { return param * 2; } -``` +---- -### 2. **Memory Safety** +==== 2. *Memory Safety* Compile-time safety without runtime overhead: -```zig +[source,zig] +---- // Null check enforced at compile time const handle = init() orelse return error.InitFailed; defer free(handle); -``` +---- -### 3. **Cross-Compilation** +==== 3. *Cross-Compilation* Built-in cross-compilation to any platform: -```bash +[source,bash] +---- zig build -Dtarget=x86_64-linux zig build -Dtarget=aarch64-macos zig build -Dtarget=x86_64-windows -``` +---- -### 4. **Zero Dependencies** +==== 4. *Zero Dependencies* No runtime, no libc required (unless explicitly needed): -```zig +[source,zig] +---- // Minimal binary size pub const lib = @import("std"); // Only includes what you use -``` +---- -## Building +=== Building -### Build FFI Library +==== Build FFI Library -```bash +[source,bash] +---- cd ffi/zig zig build # Build debug zig build -Doptimize=ReleaseFast # Build optimized zig build test # Run tests -``` +---- -### Generate C Header from Idris2 ABI +==== Generate C Header from Idris2 ABI -```bash +[source,bash] +---- cd src/abi idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` +---- -### Cross-Compile +==== Cross-Compile -```bash +[source,bash] +---- cd ffi/zig # Linux x86_64 @@ -219,13 +230,14 @@ zig build -Dtarget=aarch64-macos # Windows x86_64 zig build -Dtarget=x86_64-windows -``` +---- -## Usage +=== Usage -### From C +==== From C -```c +[source,c] +---- #include "{{project}}.h" int main() { @@ -241,16 +253,19 @@ int main() { {{project}}_free(handle); return 0; } -``` +---- Compile with: -```bash + +[source,bash] +---- gcc -o example example.c -l{{project}} -L./zig-out/lib -``` +---- -### From Idris2 +==== From Idris2 -```idris +[source,idris] +---- import {{PROJECT}}.ABI.Foreign main : IO () @@ -263,11 +278,12 @@ main = do free handle putStrLn "Success" -``` +---- -### From Rust +==== From Rust -```rust +[source,rust] +---- #[link(name = "{{project}}")] extern "C" { fn {{project}}_init() -> *mut std::ffi::c_void; @@ -286,11 +302,12 @@ fn main() { {{project}}_free(handle); } } -``` +---- -### From Julia +==== From Julia -```julia +[source,julia] +---- const lib{{project}} = "lib{{project}}" function init() @@ -316,27 +333,30 @@ try finally cleanup(handle) end -``` +---- -## Testing +=== Testing -### Unit Tests (Zig) +==== Unit Tests (Zig) -```bash +[source,bash] +---- cd ffi/zig zig build test -``` +---- -### Integration Tests +==== Integration Tests -```bash +[source,bash] +---- cd ffi/zig zig build test-integration -``` +---- -### ABI Verification (Idris2) +==== ABI Verification (Idris2) -```idris +[source,idris] +---- -- Compile-time verification %runElab verifyABI @@ -346,44 +366,44 @@ main = do verifyLayoutsCorrect verifyAlignmentsCorrect putStrLn "ABI verification passed" -``` +---- -## Contributing +=== Contributing When modifying the ABI/FFI: -1. **Update ABI first** (`src/abi/*.idr`) - - Modify type definitions - - Update proofs - - Ensure backward compatibility - -2. **Generate C header** - ```bash - idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h - ``` - -3. **Update FFI implementation** (`ffi/zig/src/main.zig`) - - Implement new functions - - Match ABI types exactly - -4. **Add tests** - - Unit tests in Zig - - Integration tests - - ABI verification tests - -5. **Update documentation** - - Function signatures - - Usage examples - - Migration guide (if breaking changes) - -## License +[arabic] +. *Update ABI first* (`+src/abi/*.idr+`) +* Modify type definitions +* Update proofs +* Ensure backward compatibility +. *Generate C header* ++ +[source,bash] +---- +idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h +---- +. *Update FFI implementation* (`+ffi/zig/src/main.zig+`) +* Implement new functions +* Match ABI types exactly +. *Add tests* +* Unit tests in Zig +* Integration tests +* ABI verification tests +. *Update documentation* +* Function signatures +* Usage examples +* Migration guide (if breaking changes) + +=== License MPL-2.0 -## See Also +=== See Also -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/hyperpolymath/rhodium-standard-repositories) -- [FFI Migration Guide](../ffi-migration-guide.md) -- [ABI Migration Guide](../abi-migration-guide.md) +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard Repositories] +* link:../ffi-migration-guide.md[FFI Migration Guide] +* link:../abi-migration-guide.md[ABI Migration Guide] diff --git a/ARCHITECTURE.adoc b/ARCHITECTURE.adoc new file mode 100644 index 0000000..1c0a7a6 --- /dev/null +++ b/ARCHITECTURE.adoc @@ -0,0 +1,48 @@ +== Architecture + +=== Overview + +This repository follows a modular, maintainable architecture designed +for clarity, scalability, and long-term sustainability. + +=== Directory Structure + +.... +. +├── src/ # Source code +├── tests/ # Test suites +├── docs/ # Documentation +├── scripts/ # Utility scripts +├── config/ # Configuration files +├── LICENSE # License file +├── LICENSES/ # Full license texts +└── README.adoc # Project documentation +.... + +=== Design Principles + +* *Separation of Concerns*: Each module has a single responsibility +* *Testability*: Code is written to be easily testable +* *Documentation*: All public APIs are documented +* *Configuration*: Environment-specific settings are externalized + +=== Dependencies + +* External dependencies are minimized and clearly declared +* Version pinning is used for reproducibility + +=== Security Considerations + +* Sensitive data is never committed to the repository +* Secrets are managed through environment variables or secure vaults +* Regular dependency audits are performed + +=== Maintainability + +* Code follows consistent style guidelines +* Pull requests require review and CI checks +* Issues and discussions are tracked transparently + +''''' + +_Last updated: 2026-07-18_ diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md deleted file mode 100644 index 607e3d8..0000000 --- a/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc new file mode 100644 index 0000000..7fd0e65 --- /dev/null +++ b/CHANGELOG.adoc @@ -0,0 +1,77 @@ +== Changelog + +All notable changes to `+conflow+` will be documented in this file. + +This file is generated from conventional commits by the +https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml[`+changelog-reusable.yml+`] +workflow (`+hyperpolymath/standards#206+`). Adopt the workflow in this +repo’s CI to keep this file in sync automatically — see +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+templates/cliff.toml+`] +for the canonical config. + +The format follows https://keepachangelog.com/en/1.1.0/[Keep a +Changelog]; this project aims to follow +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [Unreleased] + +==== Added + +* feat(crg): add crg-grade and crg-badge justfile recipes +* feat: add tlaiser state machine specs for config validation pipeline +* feat: add k9iser.toml and generate K9 contracts +* feat: add stapeln.toml layer-based container definitionfrom existing +Containerfile to stapeln format.Chainguard base, security hardening, +SBOM generation.-Authored-By: Claude Opus 4.6 (1M context) +noreply@anthropic.com +* feat: deploy UX Manifesto infrastructure +* feat: add V-lang API for configuration orchestration +* feat: add Groove discovery manifest +* feat: add Groove protocol integration +* feat: add CLADE.a2ml — clade taxonomy declaration +* feat(ci): enable Hypatia scanning + +==== Fixed + +* fix(ci): bump a2ml/k9-validate-action pins to canonical (#14) +* fix(ci): sync hypatia-scan.yml to canonical (#13) +* fix(ci): adopt canonical hypatia-scan.yml (#12) +* fix(ci): hypatia-scan workdir ($\{\{ env.HOME }} resolves empty) (#11) +* fix(ci): bump erlef/setup-beam SHA for ubuntu24 runner support (#9) +* fix(ci): move secret-scanner Cargo.toml gate from job-level if: to +step-level (#10) +* fix(ci): replace casket-pages with standard Jekyll Pages workflow +* fix(ci): Resolve workflow-linter self-matching and metadata issues +* fix(ci): Resolve workflow-linter self-matching and metadata issues +* fix: correct email jonathan.jewell → j.d.a.jewell + +==== Changed + +* refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) + +==== Documentation + +* docs: record tech-debt audit findings (2026-05-26) (#22) +* docs: update TEST-NEEDS.md with session 9 bench additions +* docs: substantive CRG C annotation (EXPLAINME.adoc) +* docs: add EXPLAINME.adoc — prove-it file backing README claims +* docs: add checkpoint files for state tracking + +==== CI + +* ci(rust): convert rust-ci.yml to thin wrapper (standards#174) (#19) +* ci: redistribute concurrency-cancel guard to read-only check workflows +(#16) +* ci: bump actions/upload-artifact SHA to current v4 (#8) +* ci: SHA-pin hyperpolymath validate-actions in dogfood-gate +* ci: restore Dependabot security path + wire auto-merge + +=== Pre-history + +Prior commits to this file’s introduction are recorded in git history +but not formally classified into Keep-a-Changelog sections. To backfill, +run `+git cliff -o CHANGELOG.md+` locally using the canonical +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+cliff.toml+`] +— this is one-shot mechanical work. + +''''' diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index a5876df..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,72 +0,0 @@ - -# Changelog - -All notable changes to `conflow` will be documented in this file. - -This file is generated from conventional commits by the -[`changelog-reusable.yml`](https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml) -workflow (`hyperpolymath/standards#206`). Adopt the workflow in this repo's CI to keep this file in sync automatically — see -[`templates/cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) -for the canonical config. - -The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); -this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] - -### Added - -- feat(crg): add crg-grade and crg-badge justfile recipes -- feat: add tlaiser state machine specs for config validation pipeline -- feat: add k9iser.toml and generate K9 contracts -- feat: add stapeln.toml layer-based container definition\n\nConverted from existing Containerfile to stapeln format.\nIncludes Chainguard base, security hardening, SBOM generation.\n\nCo-Authored-By: Claude Opus 4.6 (1M context) -- feat: deploy UX Manifesto infrastructure -- feat: add V-lang API for configuration orchestration -- feat: add Groove discovery manifest -- feat: add Groove protocol integration -- feat: add CLADE.a2ml — clade taxonomy declaration -- feat(ci): enable Hypatia scanning - -### Fixed - -- fix(ci): bump a2ml/k9-validate-action pins to canonical (#14) -- fix(ci): sync hypatia-scan.yml to canonical (#13) -- fix(ci): adopt canonical hypatia-scan.yml (#12) -- fix(ci): hypatia-scan workdir (${{ env.HOME }} resolves empty) (#11) -- fix(ci): bump erlef/setup-beam SHA for ubuntu24 runner support (#9) -- fix(ci): move secret-scanner Cargo.toml gate from job-level if: to step-level (#10) -- fix(ci): replace casket-pages with standard Jekyll Pages workflow -- fix(ci): Resolve workflow-linter self-matching and metadata issues -- fix(ci): Resolve workflow-linter self-matching and metadata issues -- fix: correct email jonathan.jewell → j.d.a.jewell - -### Changed - -- refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) - -### Documentation - -- docs: record tech-debt audit findings (2026-05-26) (#22) -- docs: update TEST-NEEDS.md with session 9 bench additions -- docs: substantive CRG C annotation (EXPLAINME.adoc) -- docs: add EXPLAINME.adoc — prove-it file backing README claims -- docs: add checkpoint files for state tracking - -### CI - -- ci(rust): convert rust-ci.yml to thin wrapper (standards#174) (#19) -- ci: redistribute concurrency-cancel guard to read-only check workflows (#16) -- ci: bump actions/upload-artifact SHA to current v4 (#8) -- ci: SHA-pin hyperpolymath validate-actions in dogfood-gate -- ci: restore Dependabot security path + wire auto-merge - -## Pre-history - -Prior commits to this file's introduction are recorded in git history but not formally classified into Keep-a-Changelog sections. To backfill, run `git cliff -o CHANGELOG.md` locally using the canonical [`cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) — this is one-shot mechanical work. - ---- - - diff --git a/CLAUDE.md b/CLAUDE.md index 5aeca8d..1f86094 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -194,7 +194,7 @@ let result = generator.generate("kubernetes", target_dir, &variables)?; This project aims for RSR Silver compliance: -- [x] Nix flake for reproducible builds +- [x] Guix flake for reproducible builds - [x] Justfile for task running - [x] Dual MIT/Apache-2.0 license - [x] Comprehensive documentation @@ -206,7 +206,7 @@ This project aims for RSR Silver compliance: ### Common Issues -1. **CUE/Nickel not found**: Ensure they're in PATH or use Nix +1. **CUE/Nickel not found**: Ensure they're in PATH or use Guix 2. **Cache issues**: Run `conflow cache clear` 3. **Pipeline validation errors**: Check `conflow validate` diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..a606916 --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,145 @@ +== Contributor Covenant Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +our community a harassment-free experience for everyone, regardless of +age, body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, caste, color, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +=== Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our +mistakes, and learning from the experience +* Focusing on what is best not just for us as individuals, but for the +overall community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or +advances of any kind +* Trolling, insulting or derogatory comments, and personal or political +attacks +* Public or private harassment +* Publishing others’ private information, such as a physical or email +address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a +professional setting + +=== Emotional Safety + +In alignment with RSR principles, we specifically commit to: + +* *Reversibility*: Mistakes can be undone; no permanent shame +* *Safe Experimentation*: Trying new approaches is encouraged +* *No Blame Culture*: Focus on problems, not people +* *Constructive Critique*: Feedback targets code, not character + +=== Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our +standards of acceptable behavior and will take appropriate and fair +corrective action in response to any behavior that they deem +inappropriate, threatening, offensive, or harmful. + +Community leaders have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other +contributions that are not aligned to this Code of Conduct, and will +communicate reasons for moderation decisions when appropriate. + +=== Scope + +This Code of Conduct applies within all community spaces, and also +applies when an individual is officially representing the community in +public spaces. Examples of representing our community include using an +official email address, posting via an official social media account, or +acting as an appointed representative at an online or offline event. + +=== Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may +be reported to the community leaders responsible for enforcement at: + +* Email: conduct@conflow.dev +* GitLab: Confidential issue with ~conduct label + +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security +of the reporter of any incident. + +=== Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in +determining the consequences for any action they deem in violation of +this Code of Conduct: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behavior +deemed unprofessional or unwelcome in the community. + +*Consequence*: A private, written warning from community leaders, +providing clarity around the nature of the violation and an explanation +of why the behavior was inappropriate. A public apology may be +requested. + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period of +time. This includes avoiding interactions in community spaces as well as +external channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behavior. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No +public or private interaction with the people involved, including +unsolicited interaction with those enforcing the Code of Conduct, is +allowed during this period. Violating these terms may lead to a +permanent ban. + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +=== Attribution + +This Code of Conduct is adapted from the +https://www.contributor-covenant.org[Contributor Covenant], version 2.1, +available at +https://www.contributor-covenant.org/version/2/1/code_of_conduct.html. + +Community Impact Guidelines were inspired by +https://github.com/mozilla/diversity[Mozilla’s code of conduct +enforcement ladder]. + +For answers to common questions about this code of conduct, see the FAQ +at https://www.contributor-covenant.org/faq. Translations are available +at https://www.contributor-covenant.org/translations. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index eb96f8f..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,148 +0,0 @@ - -# Contributor Covenant Code of Conduct - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in our -community a harassment-free experience for everyone, regardless of age, body -size, visible or invisible disability, ethnicity, sex characteristics, gender -identity and expression, level of experience, education, socio-economic status, -nationality, personal appearance, race, caste, color, religion, or sexual -identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, -diverse, inclusive, and healthy community. - -## Our Standards - -Examples of behavior that contributes to a positive environment for our -community include: - -* Demonstrating empathy and kindness toward other people -* Being respectful of differing opinions, viewpoints, and experiences -* Giving and gracefully accepting constructive feedback -* Accepting responsibility and apologizing to those affected by our mistakes, - and learning from the experience -* Focusing on what is best not just for us as individuals, but for the overall - community - -Examples of unacceptable behavior include: - -* The use of sexualized language or imagery, and sexual attention or advances of - any kind -* Trolling, insulting or derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or email address, - without their explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Emotional Safety - -In alignment with RSR principles, we specifically commit to: - -* **Reversibility**: Mistakes can be undone; no permanent shame -* **Safe Experimentation**: Trying new approaches is encouraged -* **No Blame Culture**: Focus on problems, not people -* **Constructive Critique**: Feedback targets code, not character - -## Enforcement Responsibilities - -Community leaders are responsible for clarifying and enforcing our standards of -acceptable behavior and will take appropriate and fair corrective action in -response to any behavior that they deem inappropriate, threatening, offensive, -or harmful. - -Community leaders have the right and responsibility to remove, edit, or reject -comments, commits, code, wiki edits, issues, and other contributions that are -not aligned to this Code of Conduct, and will communicate reasons for moderation -decisions when appropriate. - -## Scope - -This Code of Conduct applies within all community spaces, and also applies when -an individual is officially representing the community in public spaces. -Examples of representing our community include using an official email address, -posting via an official social media account, or acting as an appointed -representative at an online or offline event. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported to the community leaders responsible for enforcement at: - -* Email: conduct@conflow.dev -* GitLab: Confidential issue with ~conduct label - -All complaints will be reviewed and investigated promptly and fairly. - -All community leaders are obligated to respect the privacy and security of the -reporter of any incident. - -## Enforcement Guidelines - -Community leaders will follow these Community Impact Guidelines in determining -the consequences for any action they deem in violation of this Code of Conduct: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behavior deemed -unprofessional or unwelcome in the community. - -**Consequence**: A private, written warning from community leaders, providing -clarity around the nature of the violation and an explanation of why the -behavior was inappropriate. A public apology may be requested. - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of -actions. - -**Consequence**: A warning with consequences for continued behavior. No -interaction with the people involved, including unsolicited interaction with -those enforcing the Code of Conduct, for a specified period of time. This -includes avoiding interactions in community spaces as well as external channels -like social media. Violating these terms may lead to a temporary or permanent -ban. - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including -sustained inappropriate behavior. - -**Consequence**: A temporary ban from any sort of interaction or public -communication with the community for a specified period of time. No public or -private interaction with the people involved, including unsolicited interaction -with those enforcing the Code of Conduct, is allowed during this period. -Violating these terms may lead to a permanent ban. - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community -standards, including sustained inappropriate behavior, harassment of an -individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the -community. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], -version 2.1, available at -[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. - -Community Impact Guidelines were inspired by -[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. - -For answers to common questions about this code of conduct, see the FAQ at -[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at -[https://www.contributor-covenant.org/translations][translations]. - -[homepage]: https://www.contributor-covenant.org -[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html -[Mozilla CoC]: https://github.com/mozilla/diversity -[FAQ]: https://www.contributor-covenant.org/faq -[translations]: https://www.contributor-covenant.org/translations diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000..403b5df --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,108 @@ +== Clone the repository + +git clone https://github.com/hyperpolymath/conflow.git cd conflow + +== Using Guix (recommended for reproducibility) + +guix develop + +== Or using toolbox/distrobox + +toolbox create conflow-dev toolbox enter conflow-dev # Install +dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +conflow/ ├── src/ # Source code (Perimeter 1-2) ├── lib/ # Library code +(Perimeter 1-2) ├── extensions/ # Extensions (Perimeter 2) ├── plugins/ +# Plugins (Perimeter 2) ├── tools/ # Tooling (Perimeter 2) ├── docs/ # +Documentation (Perimeter 3) │ ├── architecture/ # ADRs, specs (Perimeter +2) │ └── proposals/ # RFCs (Perimeter 3) ├── examples/ # Examples +(Perimeter 3) ├── spec/ # Spec tests (Perimeter 3) ├── tests/ # Test +suite (Perimeter 2-3) ├── .well-known/ # Protocol files (Perimeter 1-3) +├── .github/ # GitHub config (Perimeter 1) │ ├── ISSUE_TEMPLATE/ │ └── +workflows/ ├── CHANGELOG.md ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md # +This file ├── GOVERNANCE.md ├── LICENSE ├── MAINTAINERS.md ├── +README.adoc ├── SECURITY.md ├── flake.guix # Guix flake (Perimeter 1) +└── Justfile # Task runner (Perimeter 1) + +.... + +--- + +## How to Contribute + +### Reporting Bugs + +**Before reporting**: +1. Search existing issues +2. Check if it's already fixed in `main` +3. Determine which perimeter the bug affects + +**When reporting**: + +Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: + +- Clear, descriptive title +- Environment details (OS, versions, toolchain) +- Steps to reproduce +- Expected vs actual behaviour +- Logs, screenshots, or minimal reproduction + +### Suggesting Features + +**Before suggesting**: +1. Check the [roadmap](ROADMAP.md) if available +2. Search existing issues and discussions +3. Consider which perimeter the feature belongs to + +**When suggesting**: + +Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: + +- Problem statement (what pain point does this solve?) +- Proposed solution +- Alternatives considered +- Which perimeter this affects + +### Your First Contribution + +Look for issues labelled: + +- [`good first issue`](https://github.com/hyperpolymath/conflow/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/conflow/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/conflow/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/conflow/labels/perimeter-3) — Community sandbox scope + +--- + +## Development Workflow + +### Branch Naming +.... + +docs/short-description # Documentation (P3) test/what-added # Test +additions (P3) feat/short-description # New features (P2) +fix/issue-number-description # Bug fixes (P2) refactor/what-changed # +Code improvements (P2) security/what-fixed # Security fixes (P1-2) + +.... + +### Commit Messages + +We follow [Conventional Commits](https://www.conventionalcommits.org/): +.... + +(): + +{empty}[optional body] + +{empty}[optional footer] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index f421194..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,120 +0,0 @@ - -# Clone the repository -git clone https://github.com/hyperpolymath/conflow.git -cd conflow - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create conflow-dev -toolbox enter conflow-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -conflow/ -├── src/ # Source code (Perimeter 1-2) -├── lib/ # Library code (Perimeter 1-2) -├── extensions/ # Extensions (Perimeter 2) -├── plugins/ # Plugins (Perimeter 2) -├── tools/ # Tooling (Perimeter 2) -├── docs/ # Documentation (Perimeter 3) -│ ├── architecture/ # ADRs, specs (Perimeter 2) -│ └── proposals/ # RFCs (Perimeter 3) -├── examples/ # Examples (Perimeter 3) -├── spec/ # Spec tests (Perimeter 3) -├── tests/ # Test suite (Perimeter 2-3) -├── .well-known/ # Protocol files (Perimeter 1-3) -├── .github/ # GitHub config (Perimeter 1) -│ ├── ISSUE_TEMPLATE/ -│ └── workflows/ -├── CHANGELOG.md -├── CODE_OF_CONDUCT.md -├── CONTRIBUTING.md # This file -├── GOVERNANCE.md -├── LICENSE -├── MAINTAINERS.md -├── README.adoc -├── SECURITY.md -├── flake.nix # Nix flake (Perimeter 1) -└── Justfile # Task runner (Perimeter 1) -``` - ---- - -## How to Contribute - -### Reporting Bugs - -**Before reporting**: -1. Search existing issues -2. Check if it's already fixed in `main` -3. Determine which perimeter the bug affects - -**When reporting**: - -Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: - -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour -- Logs, screenshots, or minimal reproduction - -### Suggesting Features - -**Before suggesting**: -1. Check the [roadmap](ROADMAP.md) if available -2. Search existing issues and discussions -3. Consider which perimeter the feature belongs to - -**When suggesting**: - -Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: - -- Problem statement (what pain point does this solve?) -- Proposed solution -- Alternatives considered -- Which perimeter this affects - -### Your First Contribution - -Look for issues labelled: - -- [`good first issue`](https://github.com/hyperpolymath/conflow/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/conflow/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/conflow/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/conflow/labels/perimeter-3) — Community sandbox scope - ---- - -## Development Workflow - -### Branch Naming -``` -docs/short-description # Documentation (P3) -test/what-added # Test additions (P3) -feat/short-description # New features (P2) -fix/issue-number-description # Bug fixes (P2) -refactor/what-changed # Code improvements (P2) -security/what-fixed # Security fixes (P1-2) -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): -``` -(): - -[optional body] - -[optional footer] diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc index e41020d..9a9bfe9 100644 --- a/GOVERNANCE.adoc +++ b/GOVERNANCE.adoc @@ -1,162 +1,125 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell -= Governance Model -:toc: preamble +== Governance -This document describes the governance model for this repository. +This document describes the governance model for conflow. -== Overview +=== Project Structure -This repository follows a **Sole Maintainer Governance Model**: +==== Roles -* Single maintainer (@hyperpolymath) has full authority over the project -* All contributions are welcome and reviewed by the maintainer -* Decisions are made transparently through GitHub issues and discussions -* The project adheres to the hyperpolymath estate policies where applicable +===== Maintainers -== Core Principles +Maintainers have full access to the repository and are responsible for: -[cols="1,2"] -|=== -| Principle | Description +* Reviewing and merging contributions +* Release management +* Security response +* Strategic direction +* Community health -| **Benevolent Dictatorship** | Maintainer has final decision authority but seeks community input +Current maintainers are listed in MAINTAINERS.md. -| **Meritocracy** | Contributions are judged on technical merit, not contributor identity +===== Contributors -| **Transparency** | All significant decisions are documented publicly +Anyone who has had a contribution merged. Contributors are recognized in +release notes and `+humans.txt+`. -| **Consensus-Seeking** | Maintainer prefers consensus but will decide when necessary +===== Community Members -| **Open Contribution** | Anyone can contribute via fork and pull request +Anyone who participates in issues, discussions, or uses the project. -|=== +=== Decision Making -== Roles and Permissions +==== Consensus-Based -[cols="1,2,2"] -|=== -| Role | Permissions | Assignment +We aim for consensus on all significant decisions: -| **Maintainer** | Write access, merge rights, admin | @hyperpolymath -| **Contributors** | Read access, fork, submit PRs | All GitHub users -| **Users** | Use the software, report issues | All GitHub users +[arabic] +. *Proposal*: Open an issue describing the change +. *Discussion*: Community feedback period (minimum 1 week for major +changes) +. *Decision*: Maintainers evaluate feedback and decide +. *Documentation*: Decision is documented in the issue -|=== +==== Lazy Consensus -== Decision Making Framework +For minor changes (typos, small fixes), maintainers may merge without +extended discussion. If anyone objects, the change can be reverted and +discussed. -=== Routine Decisions +==== Voting -* Bug fixes -* Documentation improvements -* Minor feature additions -* Dependency updates +If consensus cannot be reached: -**Process**: Maintainer reviews and merges PRs that meet quality standards. +* Each maintainer gets one vote +* Simple majority wins +* Ties are broken by the lead maintainer +* Voting period: 1 week minimum -=== Significant Changes +=== Becoming a Maintainer -* New major features -* API changes -* Architecture modifications -* Breaking changes +==== Path to Maintainership -**Process**: -. Open issue describing the change -. Discuss with community (minimum 72 hours) -. Maintainer makes final decision -. Document rationale in issue/PR +[arabic] +. Sustained, high-quality contributions over 6+ months +. Demonstrated understanding of project goals +. Positive community interactions +. Nomination by existing maintainer +. Approval by majority of maintainers -=== Structural Decisions +==== Maintainer Responsibilities -* Repository purpose/renaming -* License changes -* Ownership transfer -* Deprecation/archival +* Review contributions in a timely manner +* Participate in security response +* Uphold Code of Conduct +* Mentor new contributors +* Participate in governance decisions -**Process**: -. Extended discussion (minimum 1 week) -. Maintainer makes final decision -. Document in CHANGELOG and governance docs +==== Stepping Down -== Contribution Lifecycle +Maintainers may step down at any time by notifying other maintainers. +Inactive maintainers (6+ months no activity) may be moved to emeritus +status. -[cols="1,2"] -|=== -| Stage | Process +=== Changes to Governance -| **Ideation** | Open issue, discuss feasibility +This governance model can be amended by: -| **Development** | Fork, implement, test thoroughly +[arabic] +. Opening an issue with proposed changes +. Minimum 2-week discussion period +. Approval by 2/3 of maintainers -| **Review** | Submit PR, maintainer reviews within 7 days +=== Conflict Resolution -| **Merge** | Maintainer merges or requests changes +==== Technical Disputes -| **Release** | Maintainer publishes according to project conventions +[arabic] +. Discuss in issue/MR +. Seek input from additional maintainers +. If unresolved, maintainer vote -|=== +==== Code of Conduct Violations -== Conflict Resolution +See CODE_OF_CONDUCT.md for enforcement procedures. -In case of disagreements: +==== Governance Disputes -. Discuss in the relevant GitHub issue or PR -. Provide technical justification for positions -. Maintainer mediates and makes final decision -. Decision is documented and can be revisited later +Escalate to full maintainer group for resolution. -== Project Policies +=== RSR Alignment -This repository adheres to hyperpolymath estate-wide policies: +This governance model aligns with RSR principles: -* **License**: MPL-2.0 for code, CC-BY-SA-4.0 for prose (per standards/LICENCE-POLICY.adoc) -* **Code of Conduct**: Follows hyperpolymath CODE_OF_CONDUCT.md -* **Security**: Follows hyperpolymath SECURITY.md -* **Contributing**: Follows hyperpolymath CONTRIBUTING.adoc conventions +* *Emotional Safety*: No-blame culture, safe to make mistakes +* *Community Over Ego*: Consensus-based decisions +* *Transparency*: All decisions documented publicly +* *Accountability*: Clear roles and responsibilities -== Repository-Specific Conventions +=== Contact -[cols="1,2"] -|=== -| Convention | Description +* Governance questions: governance@conflow.dev +* General inquiries: maintainers@conflow.dev -| **Signing** | All commits must be signed (SSH or GPG) +''''' -| **SPDX Headers** | All source files must have SPDX license identifiers - -| **Contractiles** | Mustfile, Trustfile, Intendfile, Adjustfile in root - -| **Machine Readable** | META.a2ml in .machine_readable/6a2/ - -| **CI/CD** | GitHub Actions workflows in .github/workflows/ - -|=== - -== Governance Evolution - -As the project grows, this governance model may evolve: - -* **Adding Co-Maintainers**: When contribution volume warrants it -* **Forming a Team**: For complex multi-maintainer projects -* **Adopting TPCF**: For large, multi-repository projects (see rhodium-standard-repositories) - -Changes to this document require the same process as Significant Changes above. - -== See Also - -* link:MAINTAINERS.adoc[Maintainers] -* link:CODE_OF_CONDUCT.md[Code of Conduct] -* link:CONTRIBUTING.adoc[Contributing Guide] -* link:https://github.com/hyperpolymath/standards/blob/main/LICENCE-POLICY.adoc[Estate License Policy] -* link:https://github.com/hyperpolymath/standards[rhodium-standard-repositories (TPCF)] - -== Changelog - -[cols="1,1,1"] -|=== -| Date | Change | By - -| 2026-06-07 | Initial governance model established | @hyperpolymath -|=== +_Effective Date: 2025-01-01_ _Last Updated: 2025-01-01_ diff --git a/GOVERNANCE.md b/GOVERNANCE.md deleted file mode 100644 index 94f4a04..0000000 --- a/GOVERNANCE.md +++ /dev/null @@ -1,124 +0,0 @@ - -# Governance - -This document describes the governance model for conflow. - -## Project Structure - -### Roles - -#### Maintainers - -Maintainers have full access to the repository and are responsible for: - -- Reviewing and merging contributions -- Release management -- Security response -- Strategic direction -- Community health - -Current maintainers are listed in [MAINTAINERS.md](MAINTAINERS.md). - -#### Contributors - -Anyone who has had a contribution merged. Contributors are recognized in -release notes and `humans.txt`. - -#### Community Members - -Anyone who participates in issues, discussions, or uses the project. - -## Decision Making - -### Consensus-Based - -We aim for consensus on all significant decisions: - -1. **Proposal**: Open an issue describing the change -2. **Discussion**: Community feedback period (minimum 1 week for major changes) -3. **Decision**: Maintainers evaluate feedback and decide -4. **Documentation**: Decision is documented in the issue - -### Lazy Consensus - -For minor changes (typos, small fixes), maintainers may merge without -extended discussion. If anyone objects, the change can be reverted and -discussed. - -### Voting - -If consensus cannot be reached: - -- Each maintainer gets one vote -- Simple majority wins -- Ties are broken by the lead maintainer -- Voting period: 1 week minimum - -## Becoming a Maintainer - -### Path to Maintainership - -1. Sustained, high-quality contributions over 6+ months -2. Demonstrated understanding of project goals -3. Positive community interactions -4. Nomination by existing maintainer -5. Approval by majority of maintainers - -### Maintainer Responsibilities - -- Review contributions in a timely manner -- Participate in security response -- Uphold Code of Conduct -- Mentor new contributors -- Participate in governance decisions - -### Stepping Down - -Maintainers may step down at any time by notifying other maintainers. -Inactive maintainers (6+ months no activity) may be moved to emeritus status. - -## Changes to Governance - -This governance model can be amended by: - -1. Opening an issue with proposed changes -2. Minimum 2-week discussion period -3. Approval by 2/3 of maintainers - -## Conflict Resolution - -### Technical Disputes - -1. Discuss in issue/MR -2. Seek input from additional maintainers -3. If unresolved, maintainer vote - -### Code of Conduct Violations - -See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for enforcement procedures. - -### Governance Disputes - -Escalate to full maintainer group for resolution. - -## RSR Alignment - -This governance model aligns with RSR principles: - -- **Emotional Safety**: No-blame culture, safe to make mistakes -- **Community Over Ego**: Consensus-based decisions -- **Transparency**: All decisions documented publicly -- **Accountability**: Clear roles and responsibilities - -## Contact - -- Governance questions: governance@conflow.dev -- General inquiries: maintainers@conflow.dev - ---- - -*Effective Date: 2025-01-01* -*Last Updated: 2025-01-01* diff --git a/MAINTAINERS.adoc b/MAINTAINERS.adoc index aa23a55..3f2f2a9 100644 --- a/MAINTAINERS.adoc +++ b/MAINTAINERS.adoc @@ -1,48 +1,54 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) Jonathan D.A. Jewell -= Maintainers -:toc: preamble +== Maintainers -This document lists the maintainers of this project and their responsibilities. +This file lists the maintainers of conflow. -== Current Maintainers +=== Current Maintainers -[cols="2,3,2",options="header"] -|=== -| Name | Role | Contact +==== Lead Maintainer -| Jonathan D.A. Jewell -| Lead Maintainer -| https://github.com/hyperpolymath[@hyperpolymath] -|=== +* *Jonathan D.A. Jewell* (@hyperpolymath) +** GitLab: https://gitlab.com/hyperpolymath +** Role: Project founder, lead maintainer +** Areas: All areas -== Responsibilities +=== Emeritus Maintainers -Maintainers are responsible for: +_None yet_ -* Reviewing and merging pull requests -* Triaging issues and feature requests -* Ensuring code quality and security standards -* Managing releases and versioning -* Upholding the project's code of conduct +=== Becoming a Maintainer -== Becoming a Maintainer +See GOVERNANCE.md for the path to maintainership. -Contributors who demonstrate: +=== Responsibilities -* Consistent, high-quality contributions -* Understanding of the project's goals and standards -* Constructive participation in discussions -* Commitment to the project's long-term health +Maintainers are expected to: -May be invited to become maintainers at the discretion of existing maintainers. +[arabic] +. *Review Contributions* +* Respond to MRs within 1 week +* Provide constructive feedback +* Merge approved changes +. *Triage Issues* +* Label and prioritize issues +* Close stale/duplicate issues +* Guide contributors +. *Security Response* +* Monitor security reports +* Coordinate vulnerability fixes +* Manage disclosure timeline +. *Community Health* +* Enforce Code of Conduct +* Welcome new contributors +* Foster inclusive environment +. *Release Management* +* Prepare release notes +* Tag releases +* Update documentation -== Decision Making +=== Contact -* Routine decisions (bug fixes, minor improvements) can be made by any maintainer -* Significant changes require discussion and consensus among maintainers -* Breaking changes or major features should be discussed in issues before implementation +For maintainer-specific inquiries: maintainers@conflow.dev -== Contact +''''' -For questions about project governance, open an issue or contact the maintainers listed above. +_This file is updated when maintainers are added or removed._ diff --git a/MAINTAINERS.md b/MAINTAINERS.md deleted file mode 100644 index 995bc48..0000000 --- a/MAINTAINERS.md +++ /dev/null @@ -1,61 +0,0 @@ - -# Maintainers - -This file lists the maintainers of conflow. - -## Current Maintainers - -### Lead Maintainer - -- **Jonathan D.A. Jewell** (@hyperpolymath) - - GitLab: https://gitlab.com/hyperpolymath - - Role: Project founder, lead maintainer - - Areas: All areas - -## Emeritus Maintainers - -*None yet* - -## Becoming a Maintainer - -See [GOVERNANCE.md](GOVERNANCE.md) for the path to maintainership. - -## Responsibilities - -Maintainers are expected to: - -1. **Review Contributions** - - Respond to MRs within 1 week - - Provide constructive feedback - - Merge approved changes - -2. **Triage Issues** - - Label and prioritize issues - - Close stale/duplicate issues - - Guide contributors - -3. **Security Response** - - Monitor security reports - - Coordinate vulnerability fixes - - Manage disclosure timeline - -4. **Community Health** - - Enforce Code of Conduct - - Welcome new contributors - - Foster inclusive environment - -5. **Release Management** - - Prepare release notes - - Tag releases - - Update documentation - -## Contact - -For maintainer-specific inquiries: maintainers@conflow.dev - ---- - -*This file is updated when maintainers are added or removed.* diff --git a/PROOF-NEEDS.adoc b/PROOF-NEEDS.adoc new file mode 100644 index 0000000..6abfea0 --- /dev/null +++ b/PROOF-NEEDS.adoc @@ -0,0 +1,39 @@ +== Proof Requirements + +=== Current state + +* `+src/abi/Types.idr+` (232 lines) — Configuration flow types +* `+src/abi/Layout.idr+` (177 lines) — Memory layout +* `+src/abi/Foreign.idr+` (217 lines) — FFI declarations +* No dangerous patterns in ABI layer +* Claims: "`type-safe`", "`memory-safe`" (Rust) + +=== What needs proving + +* *Configuration DAG acyclicity*: Prove the configuration dependency +graph is always a DAG (no circular dependencies that cause infinite +loops) +* *Merge conflict resolution determinism*: Prove that configuration +merges produce deterministic results regardless of evaluation order +* *Rollback safety*: Prove that configuration rollback restores the +exact previous state (no partial rollback) +* *Schema validation completeness*: Prove that all configuration values +passing validation conform to their declared schema (no type confusion) + +=== Recommended prover + +* *Idris2* — Dependent types naturally express DAG properties and schema +conformance; already used for ABI + +=== Priority + +* *MEDIUM* — Configuration errors can cascade to downstream services. +The type-safety claim should be backed by proofs, especially for merge +determinism and rollback correctness. + +=== Template ABI Cleanup (2026-03-29) + +Template ABI removed – was creating false impression of formal +verification. The removed files (Types.idr, Layout.idr, Foreign.idr) +contained only RSR template scaffolding with unresolved +\{\{PROJECT}}/\{\{AUTHOR}} placeholders and no domain-specific proofs. diff --git a/PROOF-NEEDS.md b/PROOF-NEEDS.md deleted file mode 100644 index 2177924..0000000 --- a/PROOF-NEEDS.md +++ /dev/null @@ -1,30 +0,0 @@ - -# Proof Requirements - -## Current state -- `src/abi/Types.idr` (232 lines) — Configuration flow types -- `src/abi/Layout.idr` (177 lines) — Memory layout -- `src/abi/Foreign.idr` (217 lines) — FFI declarations -- No dangerous patterns in ABI layer -- Claims: "type-safe", "memory-safe" (Rust) - -## What needs proving -- **Configuration DAG acyclicity**: Prove the configuration dependency graph is always a DAG (no circular dependencies that cause infinite loops) -- **Merge conflict resolution determinism**: Prove that configuration merges produce deterministic results regardless of evaluation order -- **Rollback safety**: Prove that configuration rollback restores the exact previous state (no partial rollback) -- **Schema validation completeness**: Prove that all configuration values passing validation conform to their declared schema (no type confusion) - -## Recommended prover -- **Idris2** — Dependent types naturally express DAG properties and schema conformance; already used for ABI - -## Priority -- **MEDIUM** — Configuration errors can cascade to downstream services. The type-safety claim should be backed by proofs, especially for merge determinism and rollback correctness. - -## Template ABI Cleanup (2026-03-29) - -Template ABI removed -- was creating false impression of formal verification. -The removed files (Types.idr, Layout.idr, Foreign.idr) contained only RSR template -scaffolding with unresolved {{PROJECT}}/{{AUTHOR}} placeholders and no domain-specific proofs. diff --git a/README.adoc b/README.adoc index c03138e..2a02299 100644 --- a/README.adoc +++ b/README.adoc @@ -202,8 +202,8 @@ conflow rsr check --badge badge.svg [source,bash] ---- -# Using Nix (recommended) -nix develop +# Using Guix (recommended) +guix develop # Using just just build # Build @@ -226,7 +226,7 @@ This project follows link:https://gitlab.com/hyperpolymath/rhodium-standard-repo * ✅ Memory-safe language (Rust) * ✅ Offline-first design -* ✅ Reproducible builds (Nix) +* ✅ Reproducible builds (Guix) * ✅ Comprehensive documentation * ✅ SPDX license headers * ✅ Security policy diff --git a/RSR_OUTLINE.adoc b/RSR_OUTLINE.adoc index 9cc05ec..d07b9d8 100644 --- a/RSR_OUTLINE.adoc +++ b/RSR_OUTLINE.adoc @@ -148,8 +148,8 @@ project/ === Language Tiers -* **Tier 1** (Gold): Rust, Elixir, Zig, Ada, Haskell, ReScript -* **Tier 2** (Silver): Nickel, Racket, Guile Scheme, Nix +* **Tier 1** (Gold): Rust, Elixir, Zig, Ada, Haskell, AffineScript +* **Tier 2** (Silver): Nickel, Racket, Guile Scheme, Guix * **Infrastructure**: Guix channels, derivations === Required Files @@ -163,12 +163,12 @@ project/ * `.well-known/security.txt` * `.well-known/ai.txt` * `.well-known/humans.txt` -* `guix.scm` OR `flake.nix` +* `guix.scm` OR `flake.guix` === Prohibited * Python outside `salt/` directory -* TypeScript/JavaScript (use ReScript) +* TypeScript/JavaScript (use AffineScript) * CUE (use Guile/Nickel) * `Dockerfile` (use `Containerfile`) diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..c050a20 --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,98 @@ +== Security Policy + +=== Supported Versions + +[cols=",",options="header",] +|=== +|Version |Supported +|0.1.x |:white_check_mark: +|=== + +=== Reporting a Vulnerability + +We take security vulnerabilities seriously. If you discover a security +issue, please report it responsibly. + +==== How to Report + +[arabic] +. *Do NOT* open a public issue for security vulnerabilities +. Email security concerns to: `+security@conflow.dev+` (or create a +confidential issue) +. Include as much detail as possible: +* Description of the vulnerability +* Steps to reproduce +* Potential impact +* Suggested fix (if any) + +==== What to Expect + +* *Acknowledgment*: Within 48 hours of your report +* *Initial Assessment*: Within 7 days +* *Resolution Timeline*: Depends on severity +** Critical: 24-48 hours +** High: 7 days +** Medium: 30 days +** Low: 90 days + +==== Disclosure Policy + +* We follow coordinated disclosure +* We will credit reporters (unless anonymity is requested) +* We aim to fix vulnerabilities before public disclosure + +=== Security Measures + +==== Build Security + +* All releases are built with `+cargo build --release+` +* Dependencies are audited using `+cargo audit+` +* Binary stripping enabled to reduce attack surface + +==== Supply Chain Security + +* Dependencies are pinned via `+Cargo.lock+` +* Minimal dependency footprint +* No runtime network access required (offline-first design) + +==== Code Security + +* Written in Rust for memory safety +* No `+unsafe+` blocks in core functionality +* Input validation on all user-provided data +* Path traversal protection in file operations + +=== Security-Related Configuration + +==== Safe Defaults + +conflow is designed with security-conscious defaults: + +* No automatic code execution without explicit pipeline definition +* Cache is local-only (no network sync) +* No telemetry or data collection +* Sandboxed execution where possible + +==== Permissions + +conflow requires: - Read access to configuration files - Write access to +output directories and cache - Execute access for CUE and Nickel +binaries + +=== Known Limitations + +* Pipeline definitions can execute arbitrary shell commands via the +`+shell+` tool type +* Users should review `+.conflow.yaml+` files from untrusted sources +before running + +=== Security Contacts + +* Primary: security@conflow.dev +* GitLab Issues: Use confidential issue feature +* PGP Key: Available upon request + +=== Acknowledgments + +We thank all security researchers who responsibly disclose +vulnerabilities. diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 306ed12..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,96 +0,0 @@ - -# Security Policy - -## Supported Versions - -| Version | Supported | -| ------- | ------------------ | -| 0.1.x | :white_check_mark: | - -## Reporting a Vulnerability - -We take security vulnerabilities seriously. If you discover a security issue, -please report it responsibly. - -### How to Report - -1. **Do NOT** open a public issue for security vulnerabilities -2. Email security concerns to: `security@conflow.dev` (or create a confidential issue) -3. Include as much detail as possible: - - Description of the vulnerability - - Steps to reproduce - - Potential impact - - Suggested fix (if any) - -### What to Expect - -- **Acknowledgment**: Within 48 hours of your report -- **Initial Assessment**: Within 7 days -- **Resolution Timeline**: Depends on severity - - Critical: 24-48 hours - - High: 7 days - - Medium: 30 days - - Low: 90 days - -### Disclosure Policy - -- We follow coordinated disclosure -- We will credit reporters (unless anonymity is requested) -- We aim to fix vulnerabilities before public disclosure - -## Security Measures - -### Build Security - -- All releases are built with `cargo build --release` -- Dependencies are audited using `cargo audit` -- Binary stripping enabled to reduce attack surface - -### Supply Chain Security - -- Dependencies are pinned via `Cargo.lock` -- Minimal dependency footprint -- No runtime network access required (offline-first design) - -### Code Security - -- Written in Rust for memory safety -- No `unsafe` blocks in core functionality -- Input validation on all user-provided data -- Path traversal protection in file operations - -## Security-Related Configuration - -### Safe Defaults - -conflow is designed with security-conscious defaults: - -- No automatic code execution without explicit pipeline definition -- Cache is local-only (no network sync) -- No telemetry or data collection -- Sandboxed execution where possible - -### Permissions - -conflow requires: -- Read access to configuration files -- Write access to output directories and cache -- Execute access for CUE and Nickel binaries - -## Known Limitations - -- Pipeline definitions can execute arbitrary shell commands via the `shell` tool type -- Users should review `.conflow.yaml` files from untrusted sources before running - -## Security Contacts - -- Primary: security@conflow.dev -- GitLab Issues: Use confidential issue feature -- PGP Key: Available upon request - -## Acknowledgments - -We thank all security researchers who responsibly disclose vulnerabilities. diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..043ebe3 --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,115 @@ +== Test & Benchmark Requirements + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Current State + +* Unit tests: BUILD FAILS — cargo test cannot complete (1 compilation +error + 22 warnings) +* Integration tests: 1 Zig integration test (template) +* E2E tests: NONE +* Benchmarks: NONE +* panic-attack scan: NEVER RUN + +=== What’s Missing + +==== Point-to-Point (P2P) + +45 Rust source files with 22 files containing #[cfg(test)] / #[test] — +but none can run because the build is broken. + +===== Modules (organized by subsystem): + +*Analyzer (5 files):* - complexity.rs — has inline tests (BLOCKED) - +config_detector.rs — has inline tests (BLOCKED) - patterns.rs — has +inline tests (BLOCKED) - recommender.rs — likely has tests (BLOCKED) - +mod.rs + +*Cache (3 files):* - filesystem.rs — needs tests - hash.rs — needs tests +- mod.rs + +*CLI (8 files):* - analyze.rs, cache.rs, graph.rs, init.rs, run.rs, +validate.rs, watch.rs, rsr.rs - CLI commands need integration tests + +*Errors (3 files):* - educational.rs — error message quality tests - +recovery.rs — recovery path tests - mod.rs + +*Executors (4 files):* - cue.rs, nickel.rs, shell.rs — executor +correctness tests - mod.rs + +*Pipeline (5 files):* - dag.rs — DAG construction and cycle detection +tests - definition.rs — pipeline definition parsing tests - executor.rs +— pipeline execution tests - validation.rs — *THIS IS WHERE THE BUILD +ERROR IS* (unused field `+flags+`, `+shell+`) - mod.rs + +*RSR (multiple files):* - badges.rs + others — RSR generation tests + +==== End-to-End (E2E) + +* Full pipeline: define -> validate -> execute -> cache results +* CLI: init project -> define pipeline -> run -> watch for changes +* Analyzer: scan project -> detect configs -> recommend pipeline +* Cache: execute -> cache -> re-execute (cache hit) +* Graph generation and visualization +* Error recovery: introduce error -> recover -> resume + +==== Aspect Tests + +* [ ] Security (shell executor command injection, path traversal in +cache, untrusted pipeline definitions) +* [ ] Performance (DAG resolution on large pipelines, cache lookup +speed) +* [ ] Concurrency (parallel pipeline stages, file watching races) +* [ ] Error handling (executor failures, missing tools, invalid configs) +* [ ] Accessibility (N/A — CLI tool) + +==== Build & Execution + +* [ ] cargo build — *FAILS* (compilation error in +pipeline/validation.rs) +* [ ] cargo test — *FAILS* (blocked by build error) +* [ ] Binary runs — *BLOCKED* +* [ ] CLI –help — *BLOCKED* +* [ ] Self-diagnostic — none + +==== Benchmarks Needed + +* Pipeline execution throughput +* DAG resolution for complex dependency graphs +* Cache hit/miss ratio under typical workloads +* File watching latency +* Analyzer scan speed on large projects + +==== Self-Tests + +* [ ] panic-attack assail on own repo +* [ ] Fix compilation error first (pipeline/validation.rs) +* [ ] Built-in doctor/check command (if applicable) + +=== Priority + +* *HIGH* — 45 Rust source files that CANNOT EVEN COMPILE. The build is +broken. ~20 files have inline test modules but none can run. Fix the +compilation error in pipeline/validation.rs first, then verify test +coverage. A configuration flow tool with shell execution needs security +testing as a top priority. + +=== Session 9 additions (2026-04-04) + +==== What Was Added + +[width="100%",cols="22%,44%,34%",options="header",] +|=== +|Area |Tests Added |Location +|Benchmarks |Extended `+benches/conflow_bench.rs+` with +`+bench_analyzer_nickel+` and `+bench_analyzer_cue+` added to +`+format_benches+` group |`+benches/conflow_bench.rs+` +|=== + +==== Updated Test Counts + +[cols=",,",options="header",] +|=== +|Suite |Count |Status +|Benchmarks (analyzer) |2 new |Added to format_benches group +|=== diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index 09e51f7..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,105 +0,0 @@ - -# Test & Benchmark Requirements - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Current State -- Unit tests: BUILD FAILS — cargo test cannot complete (1 compilation error + 22 warnings) -- Integration tests: 1 Zig integration test (template) -- E2E tests: NONE -- Benchmarks: NONE -- panic-attack scan: NEVER RUN - -## What's Missing -### Point-to-Point (P2P) -45 Rust source files with 22 files containing #[cfg(test)] / #[test] — but none can run because the build is broken. - -#### Modules (organized by subsystem): -**Analyzer (5 files):** -- complexity.rs — has inline tests (BLOCKED) -- config_detector.rs — has inline tests (BLOCKED) -- patterns.rs — has inline tests (BLOCKED) -- recommender.rs — likely has tests (BLOCKED) -- mod.rs - -**Cache (3 files):** -- filesystem.rs — needs tests -- hash.rs — needs tests -- mod.rs - -**CLI (8 files):** -- analyze.rs, cache.rs, graph.rs, init.rs, run.rs, validate.rs, watch.rs, rsr.rs -- CLI commands need integration tests - -**Errors (3 files):** -- educational.rs — error message quality tests -- recovery.rs — recovery path tests -- mod.rs - -**Executors (4 files):** -- cue.rs, nickel.rs, shell.rs — executor correctness tests -- mod.rs - -**Pipeline (5 files):** -- dag.rs — DAG construction and cycle detection tests -- definition.rs — pipeline definition parsing tests -- executor.rs — pipeline execution tests -- validation.rs — **THIS IS WHERE THE BUILD ERROR IS** (unused field `flags`, `shell`) -- mod.rs - -**RSR (multiple files):** -- badges.rs + others — RSR generation tests - -### End-to-End (E2E) -- Full pipeline: define -> validate -> execute -> cache results -- CLI: init project -> define pipeline -> run -> watch for changes -- Analyzer: scan project -> detect configs -> recommend pipeline -- Cache: execute -> cache -> re-execute (cache hit) -- Graph generation and visualization -- Error recovery: introduce error -> recover -> resume - -### Aspect Tests -- [ ] Security (shell executor command injection, path traversal in cache, untrusted pipeline definitions) -- [ ] Performance (DAG resolution on large pipelines, cache lookup speed) -- [ ] Concurrency (parallel pipeline stages, file watching races) -- [ ] Error handling (executor failures, missing tools, invalid configs) -- [ ] Accessibility (N/A — CLI tool) - -### Build & Execution -- [ ] cargo build — **FAILS** (compilation error in pipeline/validation.rs) -- [ ] cargo test — **FAILS** (blocked by build error) -- [ ] Binary runs — **BLOCKED** -- [ ] CLI --help — **BLOCKED** -- [ ] Self-diagnostic — none - -### Benchmarks Needed -- Pipeline execution throughput -- DAG resolution for complex dependency graphs -- Cache hit/miss ratio under typical workloads -- File watching latency -- Analyzer scan speed on large projects - -### Self-Tests -- [ ] panic-attack assail on own repo -- [ ] Fix compilation error first (pipeline/validation.rs) -- [ ] Built-in doctor/check command (if applicable) - -## Priority -- **HIGH** — 45 Rust source files that CANNOT EVEN COMPILE. The build is broken. ~20 files have inline test modules but none can run. Fix the compilation error in pipeline/validation.rs first, then verify test coverage. A configuration flow tool with shell execution needs security testing as a top priority. - -## Session 9 additions (2026-04-04) - -### What Was Added - -| Area | Tests Added | Location | -|------|-------------|----------| -| Benchmarks | Extended `benches/conflow_bench.rs` with `bench_analyzer_nickel` and `bench_analyzer_cue` added to `format_benches` group | `benches/conflow_bench.rs` | - -### Updated Test Counts - -| Suite | Count | Status | -|-------|-------|--------| -| Benchmarks (analyzer) | 2 new | Added to format_benches group | diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 86% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index 1809496..b9ef67f 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,15 +1,8 @@ - - - +== conflow — Project Topology -# conflow — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ OPERATOR / CLI │ │ (conflow run / init / watch) │ @@ -46,14 +39,14 @@ Copyright (c) Jonathan D.A. Jewell ┌─────────────────────────────────────────┐ │ REPO INFRASTRUCTURE │ - │ Justfile / Nix .machine_readable/ │ + │ Justfile / Guix .machine_readable/ │ │ ClusterFuzzLite RSR Silver Tier │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE ORCHESTRATOR @@ -68,31 +61,32 @@ RSR INTEGRATION Badge Generation ██████████ 100% SVG templates stable REPO INFRASTRUCTURE - Justfile / Nix ██████████ 100% Reproducible build env + Justfile / Guix ██████████ 100% Reproducible build env .machine_readable/ ██████████ 100% STATE.a2ml tracking Fuzz Testing ████████░░ 80% ClusterFuzzLite active ───────────────────────────────────────────────────────────────────────────── OVERALL: █████████░ ~90% v0.1.0 RSR Silver Compliant -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... conflow.yaml ───► Dependency Graph ───► Nickel Export ───► CUE Vet │ │ │ │ ▼ ▼ ▼ ▼ Cache Store ─────► Action Plan ───────► JSON Output ────► Deployment -``` +.... -## Update Protocol +=== Update Protocol This file is maintained by both humans and AI agents. When updating: -1. **After completing a component**: Change its bar and percentage -2. **After adding a component**: Add a new row in the appropriate section -3. **After architectural changes**: Update the ASCII diagram -4. **Date**: Update the `Last updated` comment at the top of this file +[arabic] +. *After completing a component*: Change its bar and percentage +. *After adding a component*: Add a new row in the appropriate section +. *After architectural changes*: Update the ASCII diagram +. *Date*: Update the `+Last updated+` comment at the top of this file -Progress bars use: `█` (filled) and `░` (empty), 10 characters wide. -Percentages: 0%, 10%, 20%, ... 100% (in 10% increments). +Progress bars use: `+█+` (filled) and `+░+` (empty), 10 characters wide. +Percentages: 0%, 10%, 20%, … 100% (in 10% increments). diff --git a/docs/tech-debt-2026-05-26.adoc b/docs/tech-debt-2026-05-26.adoc new file mode 100644 index 0000000..49f2cc9 --- /dev/null +++ b/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,71 @@ +== Tech-Debt Audit — conflow — 2026-05-26 + +*Source:* estate-wide automated scan 2026-05-26. *Companion:* +https://github.com/hyperpolymath/standards/tree/main/docs/audits[`+hyperpolymath/standards+` +2026-05-26-estate-*-debt audits]. *Combined severity:* `+MEDIUM+`. + +This file records the _raw findings_ — it does not by itself fix the +debt. Each section ends with a '`Recommended next move`' line; closing +the debt is follow-up work. + +=== 1. Proof debt + +No proof-bearing files (`+*.v+`, `+*.lean+`, `+*.agda+`, `+*.idr+`, +`+*.idr2+`, `+*.fst+`, `+*.dfy+`, `+*.tla+`, `+*.ads+`, `+*.adb+`) found +in this repo. + +*Recommended next move:* none. + +=== 2. Licence debt + +[cols=",",options="header",] +|=== +|Field |Value +|LICENSE file |`+LICENSE+` +|SPDX header |`+MPL-2.0+` +|Manifest licence |`+MIT OR Apache-2.0+` +|Body classifier |`+Palimp-MPL-2.0+` +|Severity |`+ok+` +|=== + +*Recommended next move:* none for licence. + +=== 3. Documentation debt + +[cols=",",options="header",] +|=== +|Field |Value +|README lines |255 +|`+docs/+` files |1 +|`+docs/+` LoC |36 +|CHANGELOG.md |N +|CONTRIBUTING.md |Y +|CODE_OF_CONDUCT.md |Y +|SECURITY.md |Y +|Severity |`+MEDIUM+` +|=== + +*Recommended next move:* introduce a `+docs/+` directory. The README at +255 lines has likely grown to do the work of `+docs/+` — split it into a +thin README + `+docs/architecture.md+`, `+docs/usage.md+`, etc. +Heavy-wiki exemplars to copy from: `+affinescript+`, `+boj-server+`, +`+echidna+`, `+hypatia+`. + +Additionally: *CHANGELOG.md is missing.* 65% of estate repos lack one — +adopting a CHANGELOG (or auto-generating via `+git-cliff+`) is a +recommended estate-wide follow-up. + +=== Cross-references + +* Estate proof-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md+` +* Estate licence-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md+` +* Estate documentation-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md+` + +''''' + +🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). +This file is informational — closing the debt is follow-up work owned by +the maintainer. diff --git a/docs/tech-debt-2026-05-26.md b/docs/tech-debt-2026-05-26.md deleted file mode 100644 index 07f297c..0000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,56 +0,0 @@ - -# Tech-Debt Audit — conflow — 2026-05-26 - -**Source:** estate-wide automated scan 2026-05-26. -**Companion:** [`hyperpolymath/standards` 2026-05-26-estate-*-debt audits](https://github.com/hyperpolymath/standards/tree/main/docs/audits). -**Combined severity:** `MEDIUM`. - -This file records the *raw findings* — it does not by itself fix the debt. Each section ends with a 'Recommended next move' line; closing the debt is follow-up work. - -## 1. Proof debt - -No proof-bearing files (`*.v`, `*.lean`, `*.agda`, `*.idr`, `*.idr2`, `*.fst`, `*.dfy`, `*.tla`, `*.ads`, `*.adb`) found in this repo. - -**Recommended next move:** none. - -## 2. Licence debt - -| Field | Value | -|---|---| -| LICENSE file | `LICENSE` | -| SPDX header | `MPL-2.0` | -| Manifest licence | `MIT OR Apache-2.0` | -| Body classifier | `Palimp-MPL-2.0` | -| Severity | `ok` | - -**Recommended next move:** none for licence. - -## 3. Documentation debt - -| Field | Value | -|---|---| -| README lines | 255 | -| `docs/` files | 1 | -| `docs/` LoC | 36 | -| CHANGELOG.md | N | -| CONTRIBUTING.md | Y | -| CODE_OF_CONDUCT.md | Y | -| SECURITY.md | Y | -| Severity | `MEDIUM` | - -**Recommended next move:** introduce a `docs/` directory. The README at 255 lines has likely grown to do the work of `docs/` — split it into a thin README + `docs/architecture.md`, `docs/usage.md`, etc. Heavy-wiki exemplars to copy from: `affinescript`, `boj-server`, `echidna`, `hypatia`. - -Additionally: **CHANGELOG.md is missing.** 65% of estate repos lack one — adopting a CHANGELOG (or auto-generating via `git-cliff`) is a recommended estate-wide follow-up. - -## Cross-references - -- Estate proof-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md` -- Estate licence-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md` -- Estate documentation-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md` - ---- - -🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). This file is informational — closing the debt is follow-up work owned by the maintainer. diff --git a/examples/web-project-deno.json b/examples/web-project-deno.json index 5ddd3bd..ee775a4 100644 --- a/examples/web-project-deno.json +++ b/examples/web-project-deno.json @@ -1,17 +1,17 @@ { - "// NOTE": "Example deno.json for ReScript web projects", + "// NOTE": "Example deno.json for AffineScript web projects", "tasks": { - "build": "deno run -A npm:rescript", - "clean": "deno run -A npm:rescript clean", - "watch": "deno run -A npm:rescript -w", + "build": "deno run -A npm:affinescript", + "clean": "deno run -A npm:affinescript clean", + "watch": "deno run -A npm:affinescript -w", "serve": "deno run -A jsr:@std/http/file-server .", "test": "deno test --allow-all" }, "imports": { - "rescript": "^12.0.0", - "@rescript/core": "npm:@rescript/core@^1.6.0", - "safe-dom/": "https://raw.githubusercontent.com/hyperpolymath/rescript-dom-mounter/main/src/", - "proven/": "../proven/bindings/rescript/src/" + "affinescript": "^12.0.0", + "@affinescript/core": "npm:@affinescript/core@^1.6.0", + "safe-dom/": "https://raw.githubusercontent.com/hyperpolymath/affinescript-dom-mounter/main/src/", + "proven/": "../proven/bindings/affinescript/src/" }, "compilerOptions": { "allowJs": true, diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..2cfe78e --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — conflow (Developer) + +=== What is conflow? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-dev.md b/llm-warmup-dev.md deleted file mode 100644 index fa38539..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,20 +0,0 @@ - -# LLM Warmup — conflow (Developer) - -## What is conflow? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.adoc b/llm-warmup-user.adoc new file mode 100644 index 0000000..a3477d0 --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — conflow (User) + +=== What is conflow? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.md b/llm-warmup-user.md deleted file mode 100644 index 7c9f6a2..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,20 +0,0 @@ - -# LLM Warmup — conflow (User) - -## What is conflow? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture