From dc0cd6f09fd5304f7db53ed5163af9421be35f31 Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Sun, 21 Jun 2026 14:53:28 +0100 Subject: [PATCH] Rebuild A2ML coordination hub --- .devcontainer/Containerfile | 32 - .devcontainer/README.adoc | 28 - .devcontainer/devcontainer.json | 69 -- .editorconfig | 65 -- .envrc | 27 - .gitattributes | 55 -- .github/.mailmap | 1 - .github/.nojekyll | 0 .github/0.1-AI-MANIFEST.a2ml | 1 - .github/CODEOWNERS | 14 - .github/CODE_OF_CONDUCT.md | 331 -------- .github/CONTRIBUTING.md | 125 --- .github/DIRECTORY.adoc | 3 - .github/DISCUSSION_TEMPLATE/ideas.yml | 13 - .github/DISCUSSION_TEMPLATE/q-and-a.yml | 13 - .github/FUNDING.yml | 7 - .github/GOVERNANCE.md | 160 ---- .github/ISSUE_TEMPLATE/bug_report.yml | 127 --- .github/ISSUE_TEMPLATE/config.yml | 10 - .github/ISSUE_TEMPLATE/custom.yml | 76 -- .github/ISSUE_TEMPLATE/documentation.yml | 64 -- .github/ISSUE_TEMPLATE/feature_request.yml | 87 -- .github/ISSUE_TEMPLATE/question.yml | 60 -- .github/MAINTAINERS | 10 - .github/SECURITY.md | 410 --------- .github/SUPPORT | 7 - .github/copilot-instructions.md | 60 -- .github/copilot/coding-agent.yml | 6 - .github/dependabot.yml | 57 -- .github/pull_request_template.md | 47 -- .github/settings.yml | 125 --- .github/workflows/anchor-drift.yml | 70 ++ .github/workflows/boj-build.yml | 45 - .github/workflows/codeql.yml | 42 - .github/workflows/dependabot-automerge.yml | 136 --- .github/workflows/dogfood-gate.yml | 386 --------- .github/workflows/e2e.yml | 186 ----- .github/workflows/estate-rules.yml | 31 - .github/workflows/governance.yml | 16 - .github/workflows/guix-nix-policy.yml | 45 - .github/workflows/hypatia-scan.yml | 19 - .github/workflows/instant-sync.yml | 32 - .github/workflows/mirror.yml | 13 - .github/workflows/npm-bun-blocker.yml | 30 - .github/workflows/openssf-compliance.yml | 113 --- .github/workflows/quality.yml | 63 -- .github/workflows/release.yml | 153 ---- .github/workflows/rhodibot.yml | 189 ----- .github/workflows/rsr-antipattern.yml | 13 - .github/workflows/rust-ci.yml | 14 - .github/workflows/scorecard.yml | 16 - .github/workflows/secret-scanner.yml | 26 - .github/workflows/security-policy.yml | 53 -- .github/workflows/static-analysis-gate.yml | 400 --------- .github/workflows/ts-blocker.yml | 35 - .github/workflows/wellknown-enforcement.yml | 91 -- .github/workflows/workflow-linter.yml | 157 ---- .gitignore | 125 --- .gitlab-ci.yml | 154 ---- .gitmodules | 48 ++ .machine_readable/0.1-AI-MANIFEST.a2ml | 30 - .machine_readable/6a2/0-AI-MANIFEST.a2ml | 32 - .machine_readable/6a2/AGENTIC.a2ml | 51 -- .machine_readable/6a2/CLADE.a2ml | 26 - .machine_readable/6a2/ECOSYSTEM.a2ml | 39 - .machine_readable/6a2/META.a2ml | 53 -- .machine_readable/6a2/NEUROSYM.a2ml | 23 - .machine_readable/6a2/PLAYBOOK.a2ml | 137 --- .machine_readable/6a2/README.adoc | 30 - .machine_readable/6a2/STATE.a2ml | 64 -- .../6a2/anchors/0-AI-MANIFEST.a2ml | 21 - .machine_readable/6a2/anchors/ANCHOR.a2ml | 62 -- .machine_readable/6a2/anchors/README.adoc | 25 - .machine_readable/ENSAID_CONFIG.a2ml | 96 --- .machine_readable/README.adoc | 3 - .machine_readable/ai/.clinerules | 43 - .machine_readable/ai/.cursorrules | 47 -- .machine_readable/ai/.windsurfrules | 43 - .machine_readable/ai/0.2-AI-MANIFEST.a2ml | 11 - .machine_readable/ai/AI.a2ml | 37 - .machine_readable/ai/PLACEHOLDERS.adoc | 144 ---- .machine_readable/ai/README.adoc | 24 - .machine_readable/bot_directives/README.adoc | 41 - .../bot_directives/coverage.a2ml | 61 -- .machine_readable/bot_directives/debt.a2ml | 49 -- .../bot_directives/methodology.a2ml | 107 --- .machine_readable/compliance/reuse/dep5 | 54 -- .machine_readable/compliance/rust/deny.toml | 65 -- .../configs/0.2-AI-MANIFEST.a2ml | 11 - .machine_readable/configs/README.adoc | 3 - .machine_readable/configs/eclexiaiser.toml | 26 - .../configs/git-cliff/cliff.toml | 119 --- .machine_readable/configs/selur-compose.toml | 17 - .machine_readable/configs/stapeln.toml | 87 -- .../contractiles/Adjustfile.a2ml | 72 -- .../contractiles/Intentfile.a2ml | 99 --- .machine_readable/contractiles/Justfile | 784 ------------------ .machine_readable/contractiles/Mustfile.a2ml | 102 --- .machine_readable/contractiles/README.adoc | 21 - .machine_readable/contractiles/Trustfile.a2ml | 88 -- .../contractiles/bust/Bustfile.a2ml | 52 -- .../contractiles/dust/Dustfile.a2ml | 62 -- .../integrations/feedback-o-tron.a2ml | 14 - .machine_readable/integrations/groove.a2ml | 38 - .machine_readable/integrations/proven.a2ml | 20 - .machine_readable/integrations/verisimdb.a2ml | 17 - .machine_readable/integrations/vexometer.a2ml | 19 - .../policies/.maintenance-perms-ignore | 5 - .../policies/0.2-AI-MANIFEST.a2ml | 11 - .../policies/MAINTENANCE-AXES.a2ml | 54 -- .../policies/MAINTENANCE-CHECKLIST.a2ml | 159 ---- .machine_readable/policies/README.adoc | 3 - .../SOFTWARE-DEVELOPMENT-APPROACH.a2ml | 53 -- .machine_readable/root-allow.txt | 66 -- .../scripts/0.2-AI-MANIFEST.a2ml | 18 - .../scripts/forge/0.3-AI-MANIFEST.a2ml | 11 - .machine_readable/scripts/forge/README.adoc | 3 - .machine_readable/scripts/forge/forge-sync.sh | 25 - .../scripts/forge/git-cleanup.sh | 8 - .../scripts/lifecycle/0.3-AI-MANIFEST.a2ml | 11 - .../scripts/lifecycle/README.adoc | 3 - .../scripts/lifecycle/install-tools.sh | 27 - .../scripts/maintenance/maint-assault.sh | 44 - .../scripts/verification/0.3-AI-MANIFEST.a2ml | 11 - .../scripts/verification/README.adoc | 3 - .machine_readable/self-validating/README.adoc | 178 ---- .../self-validating/examples/ci-config.k9.ncl | 126 --- .../examples/project-metadata.k9.ncl | 57 -- .../examples/setup-repo.k9.ncl | 167 ---- .../self-validating/methodology-guard.k9.ncl | 67 -- .../self-validating/template-hunt.k9.ncl | 136 --- .../self-validating/template-kennel.k9.ncl | 54 -- .../self-validating/template-yard.k9.ncl | 84 -- .pre-commit-config.yaml | 50 -- .tool-versions | 10 - .well-known/ai.txt | 18 - .well-known/humans.txt | 14 - .well-known/security.txt | 11 - 0-AI-MANIFEST.a2ml | 34 - ANCHOR.a2ml | 27 + AUDIT.adoc | 48 -- CHANGELOG.md | 15 - CONTRIBUTING.md | 12 - ECOSYSTEM.a2ml | 42 + EXPLAINME.adoc | 94 --- GOVERNANCE.adoc | 162 ---- Justfile | 784 ------------------ LICENSE | 373 --------- MAINTAINERS.adoc | 65 -- README.adoc | 108 +-- SECURITY.md | 16 - SETUP.md | 32 + abi.ipkg | 36 - benches/template_bench.sh | 227 ----- build/.guix-channel | 22 - build/Containerfile | 41 - build/contractile.just | 75 -- build/guix.scm | 71 -- build/just/assess.just | 225 ----- build/just/groove.just | 98 --- build/just/init.just | 214 ----- build/just/proofs.just | 154 ---- build/just/validate.just | 130 --- build/setup.sh | 278 ------- conformance/invalid/empty-attestation.a2ml | 9 + conformance/invalid/malformed-heading.a2ml | 6 + conformance/invalid/missing-identity.a2ml | 5 + conformance/invalid/missing-spdx.a2ml | 5 + conformance/invalid/missing-version.a2ml | 5 + conformance/manifest.a2ml | 19 + conformance/valid/attested-agent.a2ml | 9 + conformance/valid/basic-project.a2ml | 6 + conformance/valid/s-expression-state.a2ml | 7 + conformance/valid/sectioned-manifest.a2ml | 12 + container/.gatekeeper.yaml | 122 --- container/0.1-AI-MANIFEST.a2ml | 143 ---- container/Containerfile | 136 --- container/README.adoc | 179 ---- container/compose.example.toml | 135 --- container/compose.toml | 70 -- container/ct-build.sh | 162 ---- container/deploy.k9.ncl | 166 ---- container/entrypoint.sh | 63 -- container/manifest.toml | 62 -- container/vordr.toml | 100 --- coordination.k9 | 43 - docs-template/README.adoc | 66 -- docs-template/architecture.adoc | 79 -- docs-template/contributing.adoc | 91 -- docs-template/decisions/0001-template.adoc | 54 -- docs-template/troubleshooting.adoc | 58 -- docs-template/usage.adoc | 82 -- docs/0.1-AI-MANIFEST.a2ml | 33 - docs/QUICKSTART.adoc | 26 - docs/README.adoc | 16 - docs/RSR_OUTLINE.adoc | 292 ------- docs/STATE-VISUALIZER.adoc | 130 --- docs/architecture/0.2-AI-MANIFEST.a2ml | 17 - docs/architecture/THREAT-MODEL.adoc | 164 ---- docs/architecture/TOPOLOGY.adoc | 36 - docs/attribution/0.2-AI-MANIFEST.a2ml | 11 - docs/attribution/CITATION.cff | 17 - docs/attribution/CITATIONS.adoc | 37 - docs/attribution/CODEOWNERS.adoc | 21 - docs/attribution/MAINTAINERS.adoc | 48 -- docs/attribution/README.adoc | 3 - docs/decisions/0.2-AI-MANIFEST.a2ml | 11 - docs/decisions/0000-template.adoc | 37 - docs/decisions/0001-adopt-rsr-standard.adoc | 88 -- docs/decisions/README.adoc | 3 - docs/developer/0.2-AI-MANIFEST.a2ml | 11 - docs/developer/ABI-FFI-README.adoc | 386 --------- docs/developer/README.adoc | 3 - docs/governance/0.1-AI-MANIFEST.a2ml | 21 - docs/governance/CRG-AUDIT-TEMPLATE.adoc | 288 ------- docs/governance/CRG-CRITERIA.a2ml | 108 --- docs/governance/CRG-CRITERIA.adoc | 41 - docs/governance/MAINTENANCE-CHECKLIST.adoc | 571 ------------- docs/governance/README.adoc | 3 - .../SOFTWARE-DEVELOPMENT-APPROACH.adoc | 65 -- docs/governance/TEMPLATE-STANDARDS-AUDIT.adoc | 179 ---- docs/governance/TSDM.a2ml | 22 - docs/governance/TSDM.adoc | 28 - docs/governance/audit/0.2-AI-MANIFEST.a2ml | 11 - docs/governance/audit/README.adoc | 3 - .../audit/compliance/0.3-AI-MANIFEST.a2ml | 11 - docs/governance/audit/compliance/README.adoc | 3 - .../audit/effects/0.3-AI-MANIFEST.a2ml | 11 - docs/governance/audit/effects/README.adoc | 3 - .../audit/systems/0.3-AI-MANIFEST.a2ml | 11 - docs/governance/audit/systems/README.adoc | 3 - .../maintenance/0.2-AI-MANIFEST.a2ml | 11 - docs/governance/maintenance/README.adoc | 3 - .../maintenance/adaptive/0.3-AI-MANIFEST.a2ml | 11 - .../maintenance/adaptive/README.adoc | 3 - .../corrective/0.3-AI-MANIFEST.a2ml | 11 - .../maintenance/corrective/README.adoc | 3 - .../perfective/0.3-AI-MANIFEST.a2ml | 11 - .../maintenance/perfective/README.adoc | 3 - docs/governance/planning/0.2-AI-MANIFEST.a2ml | 11 - docs/governance/planning/README.adoc | 3 - .../planning/could/0.3-AI-MANIFEST.a2ml | 11 - docs/governance/planning/could/README.adoc | 3 - .../planning/must/0.3-AI-MANIFEST.a2ml | 11 - docs/governance/planning/must/README.adoc | 3 - .../planning/should/0.3-AI-MANIFEST.a2ml | 11 - docs/governance/planning/should/README.adoc | 3 - docs/legal/0.2-AI-MANIFEST.a2ml | 16 - docs/legal/EXHIBIT-A-ETHICAL-USE.txt | 68 -- docs/legal/EXHIBIT-B-QUANTUM-SAFE.txt | 102 --- docs/onboarding/QUICKSTART-DEV.adoc | 112 --- docs/onboarding/QUICKSTART-MAINTAINER.adoc | 130 --- docs/onboarding/QUICKSTART-USER.adoc | 125 --- docs/onboarding/llm-warmup-dev.adoc | 21 - docs/onboarding/llm-warmup-user.adoc | 21 - docs/practice/.gitkeep | 0 docs/practice/0.2-AI-MANIFEST.a2ml | 11 - docs/practice/AI-CONVENTIONS.adoc | 87 -- docs/practice/README.adoc | 3 - docs/practice/STATE-VISUALIZER-GUIDE.adoc | 156 ---- docs/practice/ci-cost-reduction.adoc | 279 ------- docs/proposals/root-cleanup.adoc | 233 ------ docs/reports/0.2-AI-MANIFEST.a2ml | 19 - docs/reports/README.adoc | 3 - .../audit/pillar-audit-2026-04-15.adoc | 23 - docs/reports/compliance/0.3-AI-MANIFEST.a2ml | 11 - docs/reports/compliance/README.adoc | 3 - docs/reports/maintenance/0.3-AI-MANIFEST.a2ml | 11 - docs/reports/maintenance/README.adoc | 3 - docs/reports/performance/0.3-AI-MANIFEST.a2ml | 11 - docs/reports/performance/README.adoc | 3 - docs/reports/quality/0.3-AI-MANIFEST.a2ml | 11 - docs/reports/quality/README.adoc | 3 - docs/reports/security/0.3-AI-MANIFEST.a2ml | 11 - docs/reports/security/README.adoc | 3 - docs/standards/0.2-AI-MANIFEST.a2ml | 11 - docs/standards/README.adoc | 3 - docs/status/PROOF-NEEDS.adoc | 122 --- docs/status/PROOF-STATUS.adoc | 101 --- docs/status/READINESS.adoc | 186 ----- docs/status/ROADMAP.adoc | 23 - docs/status/TEST-NEEDS.adoc | 118 --- docs/tech-debt-2026-05-26.md | 70 -- docs/theory/.gitkeep | 0 docs/theory/0.2-AI-MANIFEST.a2ml | 23 - docs/theory/README.adoc | 3 - docs/theory/computing/0.3-AI-MANIFEST.a2ml | 11 - docs/theory/computing/README.adoc | 3 - docs/theory/formalisms/0.3-AI-MANIFEST.a2ml | 11 - docs/theory/formalisms/README.adoc | 3 - docs/theory/mathematics/0.3-AI-MANIFEST.a2ml | 11 - docs/theory/mathematics/README.adoc | 3 - docs/theory/ontologies/0.3-AI-MANIFEST.a2ml | 11 - docs/theory/ontologies/README.adoc | 3 - docs/theory/other/0.3-AI-MANIFEST.a2ml | 11 - docs/theory/other/README.adoc | 3 - .../socio-technical/0.3-AI-MANIFEST.a2ml | 11 - docs/theory/socio-technical/README.adoc | 3 - docs/whitepapers/0.2-AI-MANIFEST.a2ml | 20 - docs/whitepapers/README.adoc | 3 - docs/whitepapers/academic/.gitkeep | 0 .../whitepapers/academic/0.3-AI-MANIFEST.a2ml | 11 - docs/whitepapers/academic/README.adoc | 3 - docs/whitepapers/industry/.gitkeep | 0 .../whitepapers/industry/0.3-AI-MANIFEST.a2ml | 11 - docs/whitepapers/industry/README.adoc | 3 - .../whitepapers/outreach/0.3-AI-MANIFEST.a2ml | 16 - docs/whitepapers/outreach/README.adoc | 19 - docs/wikis/0.2-AI-MANIFEST.a2ml | 15 - docs/wikis/README.adoc | 17 - examples/0.1-AI-MANIFEST.a2ml | 1 - examples/README.adoc | 3 - examples/web-project-deno.json | 20 - features/0.1-AI-MANIFEST.a2ml | 17 - features/README.adoc | 3 - features/boj-server/0.2-AI-MANIFEST.a2ml | 11 - features/boj-server/README.adoc | 16 - features/panic-attacker/0.2-AI-MANIFEST.a2ml | 11 - features/panic-attacker/README.adoc | 27 - features/ssg/0.2-AI-MANIFEST.a2ml | 11 - features/ssg/README.adoc | 3 - features/ssg/ssg-bootstrap.sh | 54 -- .../Adjustfile.a2ml | 51 -- .../Intentfile.a2ml | 81 -- .../Mustfile.a2ml | 57 -- .../canonical-directory-structure/README.adoc | 108 --- .../Trustfile.a2ml | 58 -- .../bust/Bustfile.a2ml | 24 - .../dust/Dustfile.a2ml | 32 - members/ci/a2ml-pre-commit | 1 + members/ci/a2ml-validate-action | 1 + members/examples/a2ml-showcase | 1 + members/implementations/a2ml-deno | 1 + members/implementations/a2ml-haskell | 1 + members/implementations/a2ml-rs | 1 + members/implementations/a2ml_ex | 1 + members/implementations/a2ml_gleam | 1 + members/tooling/a2mliser | 1 + members/tooling/pandoc-a2ml | 1 + members/tooling/tree-sitter-a2ml | 1 + members/tooling/vscode-a2ml | 1 + scripts/check-membership.sh | 69 ++ scripts/check-no-md-in-docs.sh | 57 -- scripts/check-no-vlang.sh | 81 -- scripts/check-root-shape.sh | 70 -- scripts/init-submodules.sh | 50 ++ scripts/invariant-path.sh | 31 - scripts/validate-template.sh | 384 --------- session/README.md | 46 - session/custom-checks.k9 | 15 - session/dispatch.sh | 137 --- session/local-hooks.sh | 21 - spec/README.adoc | 11 + src/0.1-AI-MANIFEST.a2ml | 27 - src/README.adoc | 3 - src/aspects/0.2-AI-MANIFEST.a2ml | 17 - src/aspects/README.adoc | 56 -- src/aspects/integrity/0.3-AI-MANIFEST.a2ml | 11 - src/aspects/integrity/README.adoc | 3 - .../observability/0.3-AI-MANIFEST.a2ml | 11 - src/aspects/observability/README.adoc | 3 - src/aspects/security/0.3-AI-MANIFEST.a2ml | 11 - src/aspects/security/README.adoc | 3 - src/bridges/0.2-AI-MANIFEST.a2ml | 11 - src/contracts/0.2-AI-MANIFEST.a2ml | 11 - src/contracts/README.adoc | 3 - src/core/0.2-AI-MANIFEST.a2ml | 11 - src/definitions/0.2-AI-MANIFEST.a2ml | 11 - src/definitions/README.adoc | 3 - src/errors/0.2-AI-MANIFEST.a2ml | 11 - src/errors/README.adoc | 3 - src/interface/0.2-AI-MANIFEST.a2ml | 24 - src/interface/Abi/0.3-AI-MANIFEST.a2ml | 11 - src/interface/Abi/Foreign.idr | 83 -- src/interface/Abi/Layout.idr | 128 --- src/interface/Abi/README.adoc | 3 - src/interface/Abi/Types.idr | 112 --- src/interface/README.adoc | 3 - src/interface/ffi/0.3-AI-MANIFEST.a2ml | 11 - src/interface/ffi/README.adoc | 3 - src/interface/ffi/build.zig | 19 - src/interface/ffi/src/0.4-AI-MANIFEST.a2ml | 11 - src/interface/ffi/src/README.adoc | 3 - src/interface/ffi/src/main.zig | 275 ------ src/interface/ffi/test/0.4-AI-MANIFEST.a2ml | 11 - src/interface/ffi/test/README.adoc | 3 - src/interface/ffi/test/integration_test.zig | 66 -- src/interface/generated/0.3-AI-MANIFEST.a2ml | 11 - src/interface/generated/README.adoc | 3 - src/interface/generated/abi/.gitkeep | 0 .../generated/abi/0.4-AI-MANIFEST.a2ml | 11 - src/interface/generated/abi/README.adoc | 3 - tests/aspect_tests.sh | 134 --- tests/e2e.sh | 142 ---- tests/e2e/template_instantiation_test.sh | 268 ------ tests/fuzz/README.adoc | 112 --- tests/workflows/validate_workflows_test.sh | 144 ---- tools/invariant-path/README.adoc | 20 - verification/0.1-AI-MANIFEST.a2ml | 27 - verification/README.adoc | 3 - verification/benchmarks/0.2-AI-MANIFEST.a2ml | 11 - verification/benchmarks/README.adoc | 3 - verification/coverage/0.2-AI-MANIFEST.a2ml | 12 - verification/coverage/README.adoc | 3 - verification/fuzzing/0.2-AI-MANIFEST.a2ml | 11 - verification/fuzzing/README.adoc | 3 - verification/proofs/0.2-AI-MANIFEST.a2ml | 11 - verification/proofs/README.adoc | 60 -- verification/proofs/agda/Properties.agda | 37 - verification/proofs/coq/TypeSafety.v | 73 -- verification/proofs/idris2/ABI/Compliance.idr | 41 - verification/proofs/idris2/ABI/Foreign.idr | 53 -- verification/proofs/idris2/ABI/Layout.idr | 63 -- verification/proofs/idris2/ABI/Platform.idr | 63 -- verification/proofs/idris2/ABI/Pointers.idr | 52 -- verification/proofs/idris2/Types.idr | 38 - verification/proofs/lean4/ApiTypes.lean | 44 - verification/proofs/tlaplus/StateMachine.tla | 91 -- verification/safety_case/0.2-AI-MANIFEST.a2ml | 12 - verification/safety_case/README.adoc | 3 - verification/simulations/0.2-AI-MANIFEST.a2ml | 11 - verification/simulations/README.adoc | 3 - verification/tests/0.2-AI-MANIFEST.a2ml | 1 - verification/tests/README.adoc | 3 - .../traceability/0.2-AI-MANIFEST.a2ml | 12 - verification/traceability/README.adoc | 3 - 426 files changed, 471 insertions(+), 23520 deletions(-) delete mode 100644 .devcontainer/Containerfile delete mode 100644 .devcontainer/README.adoc delete mode 100644 .devcontainer/devcontainer.json delete mode 100644 .editorconfig delete mode 100644 .envrc delete mode 100644 .gitattributes delete mode 100644 .github/.mailmap delete mode 100644 .github/.nojekyll delete mode 100644 .github/0.1-AI-MANIFEST.a2ml delete mode 100644 .github/CODEOWNERS delete mode 100644 .github/CODE_OF_CONDUCT.md delete mode 100644 .github/CONTRIBUTING.md delete mode 100644 .github/DIRECTORY.adoc delete mode 100644 .github/DISCUSSION_TEMPLATE/ideas.yml delete mode 100644 .github/DISCUSSION_TEMPLATE/q-and-a.yml delete mode 100644 .github/FUNDING.yml delete mode 100644 .github/GOVERNANCE.md delete mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml delete mode 100644 .github/ISSUE_TEMPLATE/config.yml delete mode 100644 .github/ISSUE_TEMPLATE/custom.yml delete mode 100644 .github/ISSUE_TEMPLATE/documentation.yml delete mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml delete mode 100644 .github/ISSUE_TEMPLATE/question.yml delete mode 100644 .github/MAINTAINERS delete mode 100644 .github/SECURITY.md delete mode 100644 .github/SUPPORT delete mode 100644 .github/copilot-instructions.md delete mode 100644 .github/copilot/coding-agent.yml delete mode 100644 .github/dependabot.yml delete mode 100644 .github/pull_request_template.md delete mode 100644 .github/settings.yml create mode 100644 .github/workflows/anchor-drift.yml delete mode 100644 .github/workflows/boj-build.yml delete mode 100644 .github/workflows/codeql.yml delete mode 100644 .github/workflows/dependabot-automerge.yml delete mode 100644 .github/workflows/dogfood-gate.yml delete mode 100644 .github/workflows/e2e.yml delete mode 100644 .github/workflows/estate-rules.yml delete mode 100644 .github/workflows/governance.yml delete mode 100644 .github/workflows/guix-nix-policy.yml delete mode 100644 .github/workflows/hypatia-scan.yml delete mode 100644 .github/workflows/instant-sync.yml delete mode 100644 .github/workflows/mirror.yml delete mode 100644 .github/workflows/npm-bun-blocker.yml delete mode 100644 .github/workflows/openssf-compliance.yml delete mode 100644 .github/workflows/quality.yml delete mode 100644 .github/workflows/release.yml delete mode 100644 .github/workflows/rhodibot.yml delete mode 100644 .github/workflows/rsr-antipattern.yml delete mode 100644 .github/workflows/rust-ci.yml delete mode 100644 .github/workflows/scorecard.yml delete mode 100644 .github/workflows/secret-scanner.yml delete mode 100644 .github/workflows/security-policy.yml delete mode 100644 .github/workflows/static-analysis-gate.yml delete mode 100644 .github/workflows/ts-blocker.yml delete mode 100644 .github/workflows/wellknown-enforcement.yml delete mode 100644 .github/workflows/workflow-linter.yml delete mode 100644 .gitignore delete mode 100644 .gitlab-ci.yml create mode 100644 .gitmodules delete mode 100644 .machine_readable/0.1-AI-MANIFEST.a2ml delete mode 100644 .machine_readable/6a2/0-AI-MANIFEST.a2ml delete mode 100644 .machine_readable/6a2/AGENTIC.a2ml delete mode 100644 .machine_readable/6a2/CLADE.a2ml delete mode 100644 .machine_readable/6a2/ECOSYSTEM.a2ml delete mode 100644 .machine_readable/6a2/META.a2ml delete mode 100644 .machine_readable/6a2/NEUROSYM.a2ml delete mode 100644 .machine_readable/6a2/PLAYBOOK.a2ml delete mode 100644 .machine_readable/6a2/README.adoc delete mode 100644 .machine_readable/6a2/STATE.a2ml delete mode 100644 .machine_readable/6a2/anchors/0-AI-MANIFEST.a2ml delete mode 100644 .machine_readable/6a2/anchors/ANCHOR.a2ml delete mode 100644 .machine_readable/6a2/anchors/README.adoc delete mode 100644 .machine_readable/ENSAID_CONFIG.a2ml delete mode 100644 .machine_readable/README.adoc delete mode 100644 .machine_readable/ai/.clinerules delete mode 100644 .machine_readable/ai/.cursorrules delete mode 100644 .machine_readable/ai/.windsurfrules delete mode 100644 .machine_readable/ai/0.2-AI-MANIFEST.a2ml delete mode 100644 .machine_readable/ai/AI.a2ml delete mode 100644 .machine_readable/ai/PLACEHOLDERS.adoc delete mode 100644 .machine_readable/ai/README.adoc delete mode 100644 .machine_readable/bot_directives/README.adoc delete mode 100644 .machine_readable/bot_directives/coverage.a2ml delete mode 100644 .machine_readable/bot_directives/debt.a2ml delete mode 100644 .machine_readable/bot_directives/methodology.a2ml delete mode 100644 .machine_readable/compliance/reuse/dep5 delete mode 100644 .machine_readable/compliance/rust/deny.toml delete mode 100644 .machine_readable/configs/0.2-AI-MANIFEST.a2ml delete mode 100644 .machine_readable/configs/README.adoc delete mode 100644 .machine_readable/configs/eclexiaiser.toml delete mode 100644 .machine_readable/configs/git-cliff/cliff.toml delete mode 100644 .machine_readable/configs/selur-compose.toml delete mode 100644 .machine_readable/configs/stapeln.toml delete mode 100644 .machine_readable/contractiles/Adjustfile.a2ml delete mode 100644 .machine_readable/contractiles/Intentfile.a2ml delete mode 100644 .machine_readable/contractiles/Justfile delete mode 100644 .machine_readable/contractiles/Mustfile.a2ml delete mode 100644 .machine_readable/contractiles/README.adoc delete mode 100644 .machine_readable/contractiles/Trustfile.a2ml delete mode 100644 .machine_readable/contractiles/bust/Bustfile.a2ml delete mode 100644 .machine_readable/contractiles/dust/Dustfile.a2ml delete mode 100644 .machine_readable/integrations/feedback-o-tron.a2ml delete mode 100644 .machine_readable/integrations/groove.a2ml delete mode 100644 .machine_readable/integrations/proven.a2ml delete mode 100644 .machine_readable/integrations/verisimdb.a2ml delete mode 100644 .machine_readable/integrations/vexometer.a2ml delete mode 100644 .machine_readable/policies/.maintenance-perms-ignore delete mode 100644 .machine_readable/policies/0.2-AI-MANIFEST.a2ml delete mode 100644 .machine_readable/policies/MAINTENANCE-AXES.a2ml delete mode 100644 .machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml delete mode 100644 .machine_readable/policies/README.adoc delete mode 100644 .machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml delete mode 100644 .machine_readable/root-allow.txt delete mode 100644 .machine_readable/scripts/0.2-AI-MANIFEST.a2ml delete mode 100644 .machine_readable/scripts/forge/0.3-AI-MANIFEST.a2ml delete mode 100644 .machine_readable/scripts/forge/README.adoc delete mode 100755 .machine_readable/scripts/forge/forge-sync.sh delete mode 100755 .machine_readable/scripts/forge/git-cleanup.sh delete mode 100644 .machine_readable/scripts/lifecycle/0.3-AI-MANIFEST.a2ml delete mode 100644 .machine_readable/scripts/lifecycle/README.adoc delete mode 100755 .machine_readable/scripts/lifecycle/install-tools.sh delete mode 100644 .machine_readable/scripts/maintenance/maint-assault.sh delete mode 100644 .machine_readable/scripts/verification/0.3-AI-MANIFEST.a2ml delete mode 100644 .machine_readable/scripts/verification/README.adoc delete mode 100644 .machine_readable/self-validating/README.adoc delete mode 100644 .machine_readable/self-validating/examples/ci-config.k9.ncl delete mode 100644 .machine_readable/self-validating/examples/project-metadata.k9.ncl delete mode 100644 .machine_readable/self-validating/examples/setup-repo.k9.ncl delete mode 100644 .machine_readable/self-validating/methodology-guard.k9.ncl delete mode 100644 .machine_readable/self-validating/template-hunt.k9.ncl delete mode 100644 .machine_readable/self-validating/template-kennel.k9.ncl delete mode 100644 .machine_readable/self-validating/template-yard.k9.ncl delete mode 100644 .pre-commit-config.yaml delete mode 100644 .tool-versions delete mode 100644 .well-known/ai.txt delete mode 100644 .well-known/humans.txt delete mode 100644 .well-known/security.txt delete mode 100644 0-AI-MANIFEST.a2ml create mode 100644 ANCHOR.a2ml delete mode 100644 AUDIT.adoc delete mode 100644 CHANGELOG.md delete mode 100644 CONTRIBUTING.md create mode 100644 ECOSYSTEM.a2ml delete mode 100644 EXPLAINME.adoc delete mode 100644 GOVERNANCE.adoc delete mode 100644 Justfile delete mode 100644 LICENSE delete mode 100644 MAINTAINERS.adoc delete mode 100644 SECURITY.md create mode 100644 SETUP.md delete mode 100644 abi.ipkg delete mode 100755 benches/template_bench.sh delete mode 100644 build/.guix-channel delete mode 100644 build/Containerfile delete mode 100644 build/contractile.just delete mode 100644 build/guix.scm delete mode 100644 build/just/assess.just delete mode 100644 build/just/groove.just delete mode 100644 build/just/init.just delete mode 100644 build/just/proofs.just delete mode 100644 build/just/validate.just delete mode 100755 build/setup.sh create mode 100644 conformance/invalid/empty-attestation.a2ml create mode 100644 conformance/invalid/malformed-heading.a2ml create mode 100644 conformance/invalid/missing-identity.a2ml create mode 100644 conformance/invalid/missing-spdx.a2ml create mode 100644 conformance/invalid/missing-version.a2ml create mode 100644 conformance/manifest.a2ml create mode 100644 conformance/valid/attested-agent.a2ml create mode 100644 conformance/valid/basic-project.a2ml create mode 100644 conformance/valid/s-expression-state.a2ml create mode 100644 conformance/valid/sectioned-manifest.a2ml delete mode 100644 container/.gatekeeper.yaml delete mode 100644 container/0.1-AI-MANIFEST.a2ml delete mode 100644 container/Containerfile delete mode 100644 container/README.adoc delete mode 100644 container/compose.example.toml delete mode 100644 container/compose.toml delete mode 100755 container/ct-build.sh delete mode 100644 container/deploy.k9.ncl delete mode 100755 container/entrypoint.sh delete mode 100644 container/manifest.toml delete mode 100644 container/vordr.toml delete mode 100644 coordination.k9 delete mode 100644 docs-template/README.adoc delete mode 100644 docs-template/architecture.adoc delete mode 100644 docs-template/contributing.adoc delete mode 100644 docs-template/decisions/0001-template.adoc delete mode 100644 docs-template/troubleshooting.adoc delete mode 100644 docs-template/usage.adoc delete mode 100644 docs/0.1-AI-MANIFEST.a2ml delete mode 100644 docs/QUICKSTART.adoc delete mode 100644 docs/README.adoc delete mode 100644 docs/RSR_OUTLINE.adoc delete mode 100644 docs/STATE-VISUALIZER.adoc delete mode 100644 docs/architecture/0.2-AI-MANIFEST.a2ml delete mode 100644 docs/architecture/THREAT-MODEL.adoc delete mode 100644 docs/architecture/TOPOLOGY.adoc delete mode 100644 docs/attribution/0.2-AI-MANIFEST.a2ml delete mode 100644 docs/attribution/CITATION.cff delete mode 100644 docs/attribution/CITATIONS.adoc delete mode 100644 docs/attribution/CODEOWNERS.adoc delete mode 100644 docs/attribution/MAINTAINERS.adoc delete mode 100644 docs/attribution/README.adoc delete mode 100644 docs/decisions/0.2-AI-MANIFEST.a2ml delete mode 100644 docs/decisions/0000-template.adoc delete mode 100644 docs/decisions/0001-adopt-rsr-standard.adoc delete mode 100644 docs/decisions/README.adoc delete mode 100644 docs/developer/0.2-AI-MANIFEST.a2ml delete mode 100644 docs/developer/ABI-FFI-README.adoc delete mode 100644 docs/developer/README.adoc delete mode 100644 docs/governance/0.1-AI-MANIFEST.a2ml delete mode 100644 docs/governance/CRG-AUDIT-TEMPLATE.adoc delete mode 100644 docs/governance/CRG-CRITERIA.a2ml delete mode 100644 docs/governance/CRG-CRITERIA.adoc delete mode 100644 docs/governance/MAINTENANCE-CHECKLIST.adoc delete mode 100644 docs/governance/README.adoc delete mode 100644 docs/governance/SOFTWARE-DEVELOPMENT-APPROACH.adoc delete mode 100644 docs/governance/TEMPLATE-STANDARDS-AUDIT.adoc delete mode 100644 docs/governance/TSDM.a2ml delete mode 100644 docs/governance/TSDM.adoc delete mode 100644 docs/governance/audit/0.2-AI-MANIFEST.a2ml delete mode 100644 docs/governance/audit/README.adoc delete mode 100644 docs/governance/audit/compliance/0.3-AI-MANIFEST.a2ml delete mode 100644 docs/governance/audit/compliance/README.adoc delete mode 100644 docs/governance/audit/effects/0.3-AI-MANIFEST.a2ml delete mode 100644 docs/governance/audit/effects/README.adoc delete mode 100644 docs/governance/audit/systems/0.3-AI-MANIFEST.a2ml delete mode 100644 docs/governance/audit/systems/README.adoc delete mode 100644 docs/governance/maintenance/0.2-AI-MANIFEST.a2ml delete mode 100644 docs/governance/maintenance/README.adoc delete mode 100644 docs/governance/maintenance/adaptive/0.3-AI-MANIFEST.a2ml delete mode 100644 docs/governance/maintenance/adaptive/README.adoc delete mode 100644 docs/governance/maintenance/corrective/0.3-AI-MANIFEST.a2ml delete mode 100644 docs/governance/maintenance/corrective/README.adoc delete mode 100644 docs/governance/maintenance/perfective/0.3-AI-MANIFEST.a2ml delete mode 100644 docs/governance/maintenance/perfective/README.adoc delete mode 100644 docs/governance/planning/0.2-AI-MANIFEST.a2ml delete mode 100644 docs/governance/planning/README.adoc delete mode 100644 docs/governance/planning/could/0.3-AI-MANIFEST.a2ml delete mode 100644 docs/governance/planning/could/README.adoc delete mode 100644 docs/governance/planning/must/0.3-AI-MANIFEST.a2ml delete mode 100644 docs/governance/planning/must/README.adoc delete mode 100644 docs/governance/planning/should/0.3-AI-MANIFEST.a2ml delete mode 100644 docs/governance/planning/should/README.adoc delete mode 100644 docs/legal/0.2-AI-MANIFEST.a2ml delete mode 100644 docs/legal/EXHIBIT-A-ETHICAL-USE.txt delete mode 100644 docs/legal/EXHIBIT-B-QUANTUM-SAFE.txt delete mode 100644 docs/onboarding/QUICKSTART-DEV.adoc delete mode 100644 docs/onboarding/QUICKSTART-MAINTAINER.adoc delete mode 100644 docs/onboarding/QUICKSTART-USER.adoc delete mode 100644 docs/onboarding/llm-warmup-dev.adoc delete mode 100644 docs/onboarding/llm-warmup-user.adoc delete mode 100644 docs/practice/.gitkeep delete mode 100644 docs/practice/0.2-AI-MANIFEST.a2ml delete mode 100644 docs/practice/AI-CONVENTIONS.adoc delete mode 100644 docs/practice/README.adoc delete mode 100644 docs/practice/STATE-VISUALIZER-GUIDE.adoc delete mode 100644 docs/practice/ci-cost-reduction.adoc delete mode 100644 docs/proposals/root-cleanup.adoc delete mode 100644 docs/reports/0.2-AI-MANIFEST.a2ml delete mode 100644 docs/reports/README.adoc delete mode 100644 docs/reports/audit/pillar-audit-2026-04-15.adoc delete mode 100644 docs/reports/compliance/0.3-AI-MANIFEST.a2ml delete mode 100644 docs/reports/compliance/README.adoc delete mode 100644 docs/reports/maintenance/0.3-AI-MANIFEST.a2ml delete mode 100644 docs/reports/maintenance/README.adoc delete mode 100644 docs/reports/performance/0.3-AI-MANIFEST.a2ml delete mode 100644 docs/reports/performance/README.adoc delete mode 100644 docs/reports/quality/0.3-AI-MANIFEST.a2ml delete mode 100644 docs/reports/quality/README.adoc delete mode 100644 docs/reports/security/0.3-AI-MANIFEST.a2ml delete mode 100644 docs/reports/security/README.adoc delete mode 100644 docs/standards/0.2-AI-MANIFEST.a2ml delete mode 100644 docs/standards/README.adoc delete mode 100644 docs/status/PROOF-NEEDS.adoc delete mode 100644 docs/status/PROOF-STATUS.adoc delete mode 100644 docs/status/READINESS.adoc delete mode 100644 docs/status/ROADMAP.adoc delete mode 100644 docs/status/TEST-NEEDS.adoc delete mode 100644 docs/tech-debt-2026-05-26.md delete mode 100644 docs/theory/.gitkeep delete mode 100644 docs/theory/0.2-AI-MANIFEST.a2ml delete mode 100644 docs/theory/README.adoc delete mode 100644 docs/theory/computing/0.3-AI-MANIFEST.a2ml delete mode 100644 docs/theory/computing/README.adoc delete mode 100644 docs/theory/formalisms/0.3-AI-MANIFEST.a2ml delete mode 100644 docs/theory/formalisms/README.adoc delete mode 100644 docs/theory/mathematics/0.3-AI-MANIFEST.a2ml delete mode 100644 docs/theory/mathematics/README.adoc delete mode 100644 docs/theory/ontologies/0.3-AI-MANIFEST.a2ml delete mode 100644 docs/theory/ontologies/README.adoc delete mode 100644 docs/theory/other/0.3-AI-MANIFEST.a2ml delete mode 100644 docs/theory/other/README.adoc delete mode 100644 docs/theory/socio-technical/0.3-AI-MANIFEST.a2ml delete mode 100644 docs/theory/socio-technical/README.adoc delete mode 100644 docs/whitepapers/0.2-AI-MANIFEST.a2ml delete mode 100644 docs/whitepapers/README.adoc delete mode 100644 docs/whitepapers/academic/.gitkeep delete mode 100644 docs/whitepapers/academic/0.3-AI-MANIFEST.a2ml delete mode 100644 docs/whitepapers/academic/README.adoc delete mode 100644 docs/whitepapers/industry/.gitkeep delete mode 100644 docs/whitepapers/industry/0.3-AI-MANIFEST.a2ml delete mode 100644 docs/whitepapers/industry/README.adoc delete mode 100644 docs/whitepapers/outreach/0.3-AI-MANIFEST.a2ml delete mode 100644 docs/whitepapers/outreach/README.adoc delete mode 100644 docs/wikis/0.2-AI-MANIFEST.a2ml delete mode 100644 docs/wikis/README.adoc delete mode 100644 examples/0.1-AI-MANIFEST.a2ml delete mode 100644 examples/README.adoc delete mode 100644 examples/web-project-deno.json delete mode 100644 features/0.1-AI-MANIFEST.a2ml delete mode 100644 features/README.adoc delete mode 100644 features/boj-server/0.2-AI-MANIFEST.a2ml delete mode 100644 features/boj-server/README.adoc delete mode 100644 features/panic-attacker/0.2-AI-MANIFEST.a2ml delete mode 100644 features/panic-attacker/README.adoc delete mode 100644 features/ssg/0.2-AI-MANIFEST.a2ml delete mode 100644 features/ssg/README.adoc delete mode 100755 features/ssg/ssg-bootstrap.sh delete mode 100644 machine-readable-design/canonical-directory-structure/Adjustfile.a2ml delete mode 100644 machine-readable-design/canonical-directory-structure/Intentfile.a2ml delete mode 100644 machine-readable-design/canonical-directory-structure/Mustfile.a2ml delete mode 100644 machine-readable-design/canonical-directory-structure/README.adoc delete mode 100644 machine-readable-design/canonical-directory-structure/Trustfile.a2ml delete mode 100644 machine-readable-design/canonical-directory-structure/bust/Bustfile.a2ml delete mode 100644 machine-readable-design/canonical-directory-structure/dust/Dustfile.a2ml create mode 160000 members/ci/a2ml-pre-commit create mode 160000 members/ci/a2ml-validate-action create mode 160000 members/examples/a2ml-showcase create mode 160000 members/implementations/a2ml-deno create mode 160000 members/implementations/a2ml-haskell create mode 160000 members/implementations/a2ml-rs create mode 160000 members/implementations/a2ml_ex create mode 160000 members/implementations/a2ml_gleam create mode 160000 members/tooling/a2mliser create mode 160000 members/tooling/pandoc-a2ml create mode 160000 members/tooling/tree-sitter-a2ml create mode 160000 members/tooling/vscode-a2ml create mode 100755 scripts/check-membership.sh delete mode 100644 scripts/check-no-md-in-docs.sh delete mode 100644 scripts/check-no-vlang.sh delete mode 100644 scripts/check-root-shape.sh create mode 100755 scripts/init-submodules.sh delete mode 100755 scripts/invariant-path.sh delete mode 100755 scripts/validate-template.sh delete mode 100644 session/README.md delete mode 100644 session/custom-checks.k9 delete mode 100755 session/dispatch.sh delete mode 100755 session/local-hooks.sh create mode 100644 spec/README.adoc delete mode 100644 src/0.1-AI-MANIFEST.a2ml delete mode 100644 src/README.adoc delete mode 100644 src/aspects/0.2-AI-MANIFEST.a2ml delete mode 100644 src/aspects/README.adoc delete mode 100644 src/aspects/integrity/0.3-AI-MANIFEST.a2ml delete mode 100644 src/aspects/integrity/README.adoc delete mode 100644 src/aspects/observability/0.3-AI-MANIFEST.a2ml delete mode 100644 src/aspects/observability/README.adoc delete mode 100644 src/aspects/security/0.3-AI-MANIFEST.a2ml delete mode 100644 src/aspects/security/README.adoc delete mode 100644 src/bridges/0.2-AI-MANIFEST.a2ml delete mode 100644 src/contracts/0.2-AI-MANIFEST.a2ml delete mode 100644 src/contracts/README.adoc delete mode 100644 src/core/0.2-AI-MANIFEST.a2ml delete mode 100644 src/definitions/0.2-AI-MANIFEST.a2ml delete mode 100644 src/definitions/README.adoc delete mode 100644 src/errors/0.2-AI-MANIFEST.a2ml delete mode 100644 src/errors/README.adoc delete mode 100644 src/interface/0.2-AI-MANIFEST.a2ml delete mode 100644 src/interface/Abi/0.3-AI-MANIFEST.a2ml delete mode 100644 src/interface/Abi/Foreign.idr delete mode 100644 src/interface/Abi/Layout.idr delete mode 100644 src/interface/Abi/README.adoc delete mode 100644 src/interface/Abi/Types.idr delete mode 100644 src/interface/README.adoc delete mode 100644 src/interface/ffi/0.3-AI-MANIFEST.a2ml delete mode 100644 src/interface/ffi/README.adoc delete mode 100644 src/interface/ffi/build.zig delete mode 100644 src/interface/ffi/src/0.4-AI-MANIFEST.a2ml delete mode 100644 src/interface/ffi/src/README.adoc delete mode 100644 src/interface/ffi/src/main.zig delete mode 100644 src/interface/ffi/test/0.4-AI-MANIFEST.a2ml delete mode 100644 src/interface/ffi/test/README.adoc delete mode 100644 src/interface/ffi/test/integration_test.zig delete mode 100644 src/interface/generated/0.3-AI-MANIFEST.a2ml delete mode 100644 src/interface/generated/README.adoc delete mode 100644 src/interface/generated/abi/.gitkeep delete mode 100644 src/interface/generated/abi/0.4-AI-MANIFEST.a2ml delete mode 100644 src/interface/generated/abi/README.adoc delete mode 100755 tests/aspect_tests.sh delete mode 100755 tests/e2e.sh delete mode 100755 tests/e2e/template_instantiation_test.sh delete mode 100644 tests/fuzz/README.adoc delete mode 100755 tests/workflows/validate_workflows_test.sh delete mode 100644 tools/invariant-path/README.adoc delete mode 100644 verification/0.1-AI-MANIFEST.a2ml delete mode 100644 verification/README.adoc delete mode 100644 verification/benchmarks/0.2-AI-MANIFEST.a2ml delete mode 100644 verification/benchmarks/README.adoc delete mode 100644 verification/coverage/0.2-AI-MANIFEST.a2ml delete mode 100644 verification/coverage/README.adoc delete mode 100644 verification/fuzzing/0.2-AI-MANIFEST.a2ml delete mode 100644 verification/fuzzing/README.adoc delete mode 100644 verification/proofs/0.2-AI-MANIFEST.a2ml delete mode 100644 verification/proofs/README.adoc delete mode 100644 verification/proofs/agda/Properties.agda delete mode 100644 verification/proofs/coq/TypeSafety.v delete mode 100644 verification/proofs/idris2/ABI/Compliance.idr delete mode 100644 verification/proofs/idris2/ABI/Foreign.idr delete mode 100644 verification/proofs/idris2/ABI/Layout.idr delete mode 100644 verification/proofs/idris2/ABI/Platform.idr delete mode 100644 verification/proofs/idris2/ABI/Pointers.idr delete mode 100644 verification/proofs/idris2/Types.idr delete mode 100644 verification/proofs/lean4/ApiTypes.lean delete mode 100644 verification/proofs/tlaplus/StateMachine.tla delete mode 100644 verification/safety_case/0.2-AI-MANIFEST.a2ml delete mode 100644 verification/safety_case/README.adoc delete mode 100644 verification/simulations/0.2-AI-MANIFEST.a2ml delete mode 100644 verification/simulations/README.adoc delete mode 100644 verification/tests/0.2-AI-MANIFEST.a2ml delete mode 100644 verification/tests/README.adoc delete mode 100644 verification/traceability/0.2-AI-MANIFEST.a2ml delete mode 100644 verification/traceability/README.adoc diff --git a/.devcontainer/Containerfile b/.devcontainer/Containerfile deleted file mode 100644 index b0a6fd1..0000000 --- a/.devcontainer/Containerfile +++ /dev/null @@ -1,32 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -# -# Dev Container image for {{PROJECT_NAME}} -# Base: Chainguard Wolfi (minimal, supply-chain-secure) -# Build: podman build -t {{PROJECT_NAME}}-dev -f .devcontainer/Containerfile . - -FROM cgr.dev/chainguard/wolfi-base:latest - -# Install common development tools -RUN apk update && apk add --no-cache \ - bash \ - curl \ - git \ - openssh-client \ - ca-certificates \ - build-base \ - posix-libc-utils \ - shadow \ - && rm -rf /var/cache/apk/* - -# Create non-root dev user (matches devcontainer.json remoteUser) -RUN groupadd -g 1000 nonroot || true \ - && useradd -m -u 1000 -g 1000 -s /bin/bash nonroot || true - -# Set workspace directory -WORKDIR /workspaces/{{PROJECT_NAME}} - -# Default shell -ENV SHELL=/bin/bash - -USER nonroot diff --git a/.devcontainer/README.adoc b/.devcontainer/README.adoc deleted file mode 100644 index 7a370f2..0000000 --- a/.devcontainer/README.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Dev Container Usage -:author: {{AUTHOR}} <{{AUTHOR_EMAIL}}> - -== Overview - -This dev container uses `cgr.dev/chainguard/wolfi-base` with git, curl, bash, and just pre-installed. Dev container features add git, just, and nickel automatically. - -== VS Code (Local) - -. Install the *Dev Containers* extension (`ms-vscode-remote.remote-containers`). -. Set `dev.containers.dockerPath` to `podman` in VS Code settings. -. Open the repo folder, then choose **Reopen in Container** from the command palette. - -== GitHub Codespaces - -. From the repository on GitHub, click **Code > Codespaces > New codespace**. -. The container builds automatically from this configuration. - -== Gitpod - -. Prefix the repo URL with `https://gitpod.io/#` to launch a workspace. -. Gitpod reads `devcontainer.json` and builds the environment. - -== Customization - -Replace `{{PROJECT_NAME}}` placeholders in both `devcontainer.json` and `Containerfile` with your actual project name. Run `just deps` to verify the environment after first launch. diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json deleted file mode 100644 index a4b33e0..0000000 --- a/.devcontainer/devcontainer.json +++ /dev/null @@ -1,69 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -// -// Dev Container configuration for {{PROJECT_NAME}} -// Works with: VS Code Dev Containers, GitHub Codespaces, Gitpod -// Container runtime: Podman (recommended) or any OCI-compliant runtime -{ - "name": "{{PROJECT_NAME}}", - - "build": { - "dockerfile": "Containerfile", - "context": ".." - }, - - "features": { - "ghcr.io/devcontainers/features/git:1": { - "ppa": false, - "version": "latest" - }, - "ghcr.io/jdx/devcontainer-features/just:1": {}, - "ghcr.io/nickel-lang/devcontainer-feature:0": {} - }, - - "postCreateCommand": "just deps", - - "remoteUser": "nonroot", - - "containerEnv": { - "EDITOR": "code --wait", - "LANG": "C.UTF-8" - }, - - "customizations": { - "vscode": { - "extensions": [ - "EditorConfig.EditorConfig", - "eamodio.gitlens", - "streetsidesoftware.code-spell-checker", - "timonwong.shellcheck", - "tamasfe.even-better-toml", - "skellock.just", - "redhat.vscode-yaml", - "DavidAnson.vscode-markdownlint", - "asciidoctor.asciidoctor-vscode", - "usernamehw.errorlens" - ], - "settings": { - "editor.formatOnSave": true, - "editor.insertSpaces": true, - "editor.tabSize": 2, - "files.trimTrailingWhitespace": true, - "files.insertFinalNewline": true, - "files.trimFinalNewlines": true, - "[makefile]": { - "editor.insertSpaces": false - } - } - }, - "codespaces": { - "openFiles": [ - "README.adoc" - ] - } - }, - - "forwardPorts": [], - - "shutdownAction": "stopContainer" -} diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index bcdbb4d..0000000 --- a/.editorconfig +++ /dev/null @@ -1,65 +0,0 @@ -# RSR-template-repo - Editor Configuration -# https://editorconfig.org - -root = true - -[*] -charset = utf-8 -end_of_line = lf -indent_size = 2 -indent_style = space -insert_final_newline = true -trim_trailing_whitespace = true - -[*.md] -trim_trailing_whitespace = false - -[*.adoc] -trim_trailing_whitespace = false - -[*.rs] -indent_size = 4 - -[*.ex] -indent_size = 2 - -[*.exs] -indent_size = 2 - -[*.zig] -indent_size = 4 - -[*.ada] -indent_size = 3 - -[*.adb] -indent_size = 3 - -[*.ads] -indent_size = 3 - -[*.hs] -indent_size = 2 - -[*.res] -indent_size = 2 - -[*.resi] -indent_size = 2 - -[*.ncl] -indent_size = 2 - -[*.rkt] -indent_size = 2 - -[*.scm] -indent_size = 2 - -[*.nix] -indent_size = 2 - -[Justfile] -indent_style = space -indent_size = 4 - diff --git a/.envrc b/.envrc deleted file mode 100644 index 0b5b702..0000000 --- a/.envrc +++ /dev/null @@ -1,27 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Activate development environment -# Install direnv: https://direnv.net/ - -# Load .tool-versions if asdf is available -if has asdf; then - use asdf -fi - -# Load Guix shell if guix.scm exists -if has guix && [ -f guix.scm ]; then - use guix -fi - -# Load Nix flake if flake.nix exists -if has nix && [ -f flake.nix ]; then - use flake -fi - -# Project environment variables -export PROJECT_NAME="{{PROJECT_NAME}}" -export RSR_TIER="infrastructure" -# export DATABASE_URL="..." -# export API_KEY="..." - -# Source .env if it exists (gitignored) -dotenv_if_exists diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index c95d5eb..0000000 --- a/.gitattributes +++ /dev/null @@ -1,55 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# RSR-compliant .gitattributes - -* text=auto eol=lf - -# Source -*.rs text eol=lf diff=rust -*.ex text eol=lf diff=elixir -*.exs text eol=lf diff=elixir -*.jl text eol=lf -*.res text eol=lf -*.resi text eol=lf -*.ada text eol=lf diff=ada -*.adb text eol=lf diff=ada -*.ads text eol=lf diff=ada -*.hs text eol=lf -*.chpl text eol=lf -*.scm text eol=lf -*.a2ml text eol=lf linguist-language=TOML -*.ncl text eol=lf -*.nix text eol=lf - -# Docs -*.md text eol=lf diff=markdown -*.adoc text eol=lf -*.txt text eol=lf - -# Data -*.json text eol=lf -*.yaml text eol=lf -*.yml text eol=lf -*.toml text eol=lf - -# Config -.gitignore text eol=lf -.gitattributes text eol=lf -Justfile text eol=lf -Makefile text eol=lf -Containerfile text eol=lf - -# Scripts -*.sh text eol=lf - -# Binary -*.png binary -*.jpg binary -*.gif binary -*.pdf binary -*.woff2 binary -*.zip binary -*.gz binary - -# Lock files -Cargo.lock text eol=lf -diff -flake.lock text eol=lf -diff diff --git a/.github/.mailmap b/.github/.mailmap deleted file mode 100644 index 0ada9de..0000000 --- a/.github/.mailmap +++ /dev/null @@ -1 +0,0 @@ -{{AUTHOR}} <{{AUTHOR_EMAIL}}> <{{AUTHOR_EMAIL_ALT}}> diff --git a/.github/.nojekyll b/.github/.nojekyll deleted file mode 100644 index e69de29..0000000 diff --git a/.github/0.1-AI-MANIFEST.a2ml b/.github/0.1-AI-MANIFEST.a2ml deleted file mode 100644 index 85b2f0f..0000000 --- a/.github/0.1-AI-MANIFEST.a2ml +++ /dev/null @@ -1 +0,0 @@ -# AI Manifest - Level 1: .github diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS deleted file mode 100644 index 611b5a8..0000000 --- a/.github/CODEOWNERS +++ /dev/null @@ -1,14 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# CODEOWNERS - Define code review assignments -# See: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners -# -# Replace {{OWNER}} with your GitHub username or team - -# Default owners for everything -* @{{OWNER}} - -# Security-sensitive files require explicit review -SECURITY.md @{{OWNER}} -.github/workflows/ @{{OWNER}} -Trustfile.a2ml @{{OWNER}} -.machine_readable/ @{{OWNER}} diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md deleted file mode 100644 index 9142f2a..0000000 --- a/.github/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,331 +0,0 @@ - -# Code of Conduct - - - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in {{PROJECT_NAME}} 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, colour, 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. - -We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation. - ---- - -## Our Standards - -### Expected Behaviour - -The following behaviours contribute to a positive environment: - -**Communication** -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Giving and gracefully accepting constructive feedback -- Assuming good intent while addressing impact -- Communicating clearly and patiently, especially with newcomers - -**Collaboration** -- Focusing on what is best for the community -- Showing empathy and kindness toward other community members -- Being collaborative rather than competitive -- Mentoring and supporting less experienced contributors -- Celebrating others' contributions and successes - -**Professionalism** -- Accepting responsibility and apologising to those affected by our mistakes -- Learning from the experience and avoiding repetition -- Respecting others' time and attention -- Staying on topic in project spaces -- Following project guidelines and conventions - -**Accessibility** -- Using plain language and avoiding unnecessary jargon -- Providing alt text for images and transcripts for audio/video -- Being patient with those using assistive technologies -- Accommodating different communication styles and needs -- Recognising that not everyone communicates the same way - -### Unacceptable Behaviour - -The following behaviours are considered harassment and are unacceptable: - -**Harassment** -- The use of sexualised 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 -- Deliberate intimidation, stalking, or following (online or in-person) -- Unwelcome physical contact or simulated physical contact (e.g., emoji) -- Sustained disruption of talks, events, or online discussions - -**Discrimination** -- Discriminatory jokes and language -- Posting or threatening to post others' personally identifying information ("doxing") -- Advocating for, or encouraging, any of the above behaviour -- Microaggressions — subtle, often unintentional, discriminatory comments or actions - -**Professional Misconduct** -- Publishing others' private information without explicit permission -- Misrepresenting affiliation or contributions -- Plagiarism or claiming credit for others' work -- Retaliating against anyone who reports a Code of Conduct violation -- Other conduct which could reasonably be considered inappropriate in a professional setting - -### Grey Areas - -Some situations require judgement. When uncertain: - -- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right. -- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact. -- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask. -- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down. - ---- - -## Scope - -This Code of Conduct applies within all community spaces, including: - -**Online Spaces** -- Repository discussions, issues, and pull/merge requests -- Project chat channels (Matrix, Discord, Slack, IRC) -- Mailing lists and forums -- Social media when representing the project -- Video calls and virtual meetings - -**In-Person Spaces** -- Conferences, meetups, and events -- Workshops and training sessions -- Any gathering where you represent the project - -**Representation** -This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an event -- Speaking on behalf of the project - ---- - -## Enforcement - -### Reporting - -If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible. - -**How to Report** - -| Method | Details | Best For | -|--------|---------|----------| -| **Email** | {{CONDUCT_EMAIL}} | Detailed reports, sensitive matters | -| **Private Message** | Contact any maintainer directly | Quick questions, minor issues | -| **Anonymous Form** | [Link to form if available] | When you need anonymity | - -**What to Include** - -- Your contact information (unless anonymous) -- Names/usernames of those involved -- Description of what happened -- When and where it occurred -- Any witnesses -- Any supporting evidence (screenshots, links) -- How you would like us to respond (if you have a preference) - -**What Happens Next** - -1. You will receive acknowledgment within **{{RESPONSE_TIME}}** -2. The {{CONDUCT_TEAM}} will review the report -3. We may ask for additional information -4. We will determine appropriate action -5. We will inform you of the outcome (respecting others' privacy) - -### Confidentiality - -All reports will be handled with discretion: - -- Reporter identity is protected by default -- Details are shared only with those who need to know -- We will ask before naming you in any communication -- Anonymous reports are accepted and investigated - -### Conflicts of Interest - -If a {{CONDUCT_TEAM}} member is involved in an incident: - -- They will recuse themselves from the process -- Another maintainer or external party will handle the report -- We will disclose any potential conflicts - ---- - -## Enforcement Guidelines - -The {{CONDUCT_TEAM}} will follow these guidelines in determining consequences: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. - -**Duration**: Immediate - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. 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. - -**Duration**: 1-4 weeks - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. 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. - -**Duration**: 1-6 months - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, 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. - -**Duration**: Permanent (with appeal rights after 12 months) - -### Enforcement Across Perimeters - -For contributors with elevated access (Perimeter 2 or 1): - -| Level | Additional Consequence | -|-------|----------------------| -| Correction | Noted in contributor record | -| Warning | Access privileges may be temporarily reduced | -| Temporary Ban | Access reduced to Perimeter 3 for ban duration | -| Permanent Ban | All access revoked | - ---- - -## Appeals - -If you believe an enforcement decision was made in error: - -1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** {{CONDUCT_EMAIL}} with subject line "Appeal: [Original Report ID]" -3. **Explain** why you believe the decision should be reconsidered -4. **Provide** any new information not previously available - -**Appeals Process** - -- Appeals are reviewed by a different {{CONDUCT_TEAM}} member than the original -- You will receive a response within 14 days -- The appeals decision is final -- You may only appeal once per incident - -**Grounds for Appeal** - -- Procedural errors in the original investigation -- New evidence not previously available -- Disproportionate response to the violation -- Misunderstanding of facts - ---- - -## Supporting Those Who Report - -We are committed to supporting those who report violations: - -**We Will** -- Believe and take all reports seriously -- Respect your privacy and confidentiality preferences -- Keep you informed of progress (if you wish) -- Take steps to protect you from retaliation -- Provide resources if you need support - -**We Will Not** -- Require you to confront the person directly -- Dismiss reports without investigation -- Reveal your identity without consent -- Tolerate retaliation against reporters -- Rush you to make decisions - ---- - -## Prevention - -Beyond enforcement, we actively work to prevent issues: - -**Onboarding** -- All contributors are expected to read this Code of Conduct -- Perimeter 2 applicants must confirm they've read and understood it -- Maintainers receive additional training on enforcement - -**Culture** -- We model the behaviour we expect -- We intervene early when we see potential issues -- We thank people for positive contributions -- We create opportunities for diverse voices - -**Review** -- This Code of Conduct is reviewed annually -- Community feedback is welcomed -- Changes are communicated clearly - ---- - -## Acknowledgments - -This Code of Conduct is adapted from: - -- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1 -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) - -We thank these communities for their leadership in creating welcoming spaces. - ---- - -## Questions? - -If you have questions about this Code of Conduct: - -- Open a [Discussion](https://{{FORGE}}/{{OWNER}}/{{REPO}}/discussions) (for general questions) -- Email {{CONDUCT_EMAIL}} (for private questions) -- Contact any maintainer directly - ---- - -## Summary - -**Be kind. Be respectful. Be collaborative.** - -We're all here because we care about this project. Let's make it a place where everyone can do their best work. - ---- - -Last updated: {{CURRENT_YEAR}} · Based on Contributor Covenant 2.1 diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md deleted file mode 100644 index d07b3e9..0000000 --- a/.github/CONTRIBUTING.md +++ /dev/null @@ -1,125 +0,0 @@ - -# Clone the repository -git clone https://{{FORGE}}/{{OWNER}}/{{REPO}}.git -cd {{REPO}} - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create {{REPO}}-dev -toolbox enter {{REPO}}-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -{{REPO}}/ -├── 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) -├── .machine_readable/ # ALL machine-readable content (Perimeter 1) -│ ├── *.a2ml # State files (STATE, META, ECOSYSTEM, etc.) -│ ├── bot_directives/ # Bot configs -│ └── contractiles/ # Policy contracts (k9, dust, lust, must, trust) -├── .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 — fallback (Perimeter 1) -├── guix.scm # Guix package — primary (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_BRANCH}}` -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://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/help%20wanted) — Community help needed -- [`documentation`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/documentation) — Docs improvements -- [`perimeter-3`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/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/.github/DIRECTORY.adoc b/.github/DIRECTORY.adoc deleted file mode 100644 index b4caddf..0000000 --- a/.github/DIRECTORY.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= .github Pillar diff --git a/.github/DISCUSSION_TEMPLATE/ideas.yml b/.github/DISCUSSION_TEMPLATE/ideas.yml deleted file mode 100644 index ef912f8..0000000 --- a/.github/DISCUSSION_TEMPLATE/ideas.yml +++ /dev/null @@ -1,13 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -labels: [enhancement] -body: - - type: textarea - attributes: - label: Idea - description: Describe your idea - validations: - required: true - - type: textarea - attributes: - label: Motivation - description: Why would this be useful? diff --git a/.github/DISCUSSION_TEMPLATE/q-and-a.yml b/.github/DISCUSSION_TEMPLATE/q-and-a.yml deleted file mode 100644 index df4ec20..0000000 --- a/.github/DISCUSSION_TEMPLATE/q-and-a.yml +++ /dev/null @@ -1,13 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -labels: [question] -body: - - type: textarea - attributes: - label: Question - description: What would you like to know? - validations: - required: true - - type: textarea - attributes: - label: Context - description: Any relevant background diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml deleted file mode 100644 index c078261..0000000 --- a/.github/FUNDING.yml +++ /dev/null @@ -1,7 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Funding platforms for {{OWNER}} projects -# See: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/displaying-a-sponsor-button-in-your-repository - -github: {{OWNER}} -ko_fi: {{OWNER}} -liberapay: {{OWNER}} diff --git a/.github/GOVERNANCE.md b/.github/GOVERNANCE.md deleted file mode 100644 index 8ef7166..0000000 --- a/.github/GOVERNANCE.md +++ /dev/null @@ -1,160 +0,0 @@ - -# Project Governance - -This document describes the governance model for **{{PROJECT_NAME}}**. - ---- - -## Project Governance Model - -{{PROJECT_NAME}} follows a **Benevolent Dictator For Life (BDFL)** governance model. -This model is well-suited for solo maintainers and small project teams where rapid, -consistent decision-making is more valuable than formal consensus processes. - -The BDFL has final authority on all project decisions, including technical direction, -release schedules, contributor access, and community standards. - -> **Transition clause:** When the core team exceeds three active maintainers, this -> project should transition to a **consensus-based governance model** with documented -> voting procedures. That transition should itself be recorded as an Architecture -> Decision Record (ADR) in `docs/decisions/`. - ---- - -## Decision Making - -### Day-to-day decisions - -- The BDFL makes final decisions on all matters. -- Routine decisions (bug fixes, dependency updates, minor improvements) may be made - by any maintainer with commit access. -- Maintainers are expected to use good judgement and seek input on non-trivial changes. - -### Proposing changes - -- Contributors can propose changes by opening issues or pull requests. -- Significant changes (new features, breaking changes, architectural shifts) should - be discussed in an issue before implementation begins. -- The BDFL will provide a clear accept/reject decision with reasoning. - -### Architecture Decision Records (ADRs) - -- Significant technical decisions are documented as ADRs in `docs/decisions/`. -- ADR statuses: `proposed`, `accepted`, `deprecated`, `superseded`, `rejected`. -- ADRs provide a historical record of why decisions were made and what alternatives - were considered. -- See `.machine_readable/6a2/META.a2ml` for the machine-readable ADR index. - ---- - -## Roles - -### BDFL (Benevolent Dictator For Life) - -- The project creator and ultimate decision-maker. -- Sets the project's technical direction and long-term vision. -- Has final say on all matters, including maintainer appointments and removals. -- Responsible for ensuring the project adheres to RSR standards. - -### Maintainer - -- Has commit access to the repository. -- Reviews and merges pull requests. -- Triages issues and manages releases. -- Upholds code quality, security standards, and the Code of Conduct. -- Listed in [MAINTAINERS.md](MAINTAINERS.md). - -### Contributor - -- Anyone who submits pull requests, opens issues, or participates in discussions. -- Does not have direct commit access. -- Contributions are reviewed by maintainers before merging. -- All contributors must follow the [Code of Conduct](CODE_OF_CONDUCT.md). - -### Bot - -- Automated agents managed via your bot orchestration system. -- Perform automated code review, security scanning, dependency updates, and - standards enforcement. -- Bot actions are subject to the same quality and review standards as human - contributions. -- Configure your bots in `.machine_readable/bot_directives/`. - ---- - -## Becoming a Maintainer - -A contributor may be nominated to become a maintainer when they demonstrate: - -1. **Sustained quality contributions** -- a track record of well-crafted pull requests - that follow project conventions and require minimal revision. -2. **Understanding of RSR standards** -- familiarity with the Repository Structure - Requirements, security policies, and CI/CD workflows used across the project. -3. **Constructive participation** -- helpful issue triage, thoughtful code review - comments, and mentoring of other contributors. -4. **Reliability** -- consistent engagement over a meaningful period (typically 3+ - months of active contribution). - -### Process - -1. An existing maintainer nominates the candidate by opening a private discussion - with the BDFL. -2. The BDFL reviews the candidate's contribution history and community interactions. -3. The BDFL approves or declines the nomination, with reasoning provided to the - nominator. -4. If approved, the new maintainer is added to [MAINTAINERS.md](MAINTAINERS.md) and - granted appropriate repository access. - ---- - -## Removing a Maintainer - -A maintainer may be removed under the following circumstances: - -- **Inactivity**: No meaningful contributions or reviews for 12 or more consecutive - months. The maintainer will be contacted before removal and offered the option to - move to emeritus status voluntarily. -- **Code of Conduct violation**: Behaviour that violates the - [Code of Conduct](CODE_OF_CONDUCT.md), as determined through the enforcement - process described therein. -- **BDFL discretion**: The BDFL may remove a maintainer for other reasons (e.g., - repeated disregard for project standards, loss of trust). Reasoning will be - documented privately. - -Removed maintainers are moved to the Emeritus section of -[MAINTAINERS.md](MAINTAINERS.md) unless removal was due to a serious Code of Conduct -violation. - ---- - -## Code of Conduct - -All participants in this project are expected to follow the -[Code of Conduct](CODE_OF_CONDUCT.md). The Code of Conduct applies to all project -spaces, including issues, pull requests, discussions, and any forum where the project -is represented. - -Enforcement of the Code of Conduct is described in that document. The BDFL serves as -the final arbiter in conduct disputes. - ---- - -## Amendments - -This governance document may be amended by the BDFL at any time. All amendments will -be: - -1. Documented as an ADR in `docs/decisions/` explaining the rationale for the change. -2. Committed to the repository with a clear commit message. -3. Communicated to existing maintainers and contributors via the project's usual - channels. - -Substantive changes (e.g., changing the governance model itself) should be discussed -with the community before adoption, even though the BDFL retains final authority. - ---- - -Copyright (c) {{CURRENT_YEAR}} {{OWNER}}. Licensed under MPL-2.0. diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml deleted file mode 100644 index ec2aa28..0000000 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ /dev/null @@ -1,127 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Bug report issue template for {{OWNER}}/{{REPO}} -name: Bug Report -description: Create a report to help us improve -title: "[Bug]: " -labels: ["bug", "priority: unset", "triage"] -assignees: [] -body: - - type: markdown - attributes: - value: | - Thank you for taking the time to report a bug. Please fill out the sections below - so we can reproduce and fix the issue. - - - type: textarea - id: description - attributes: - label: Describe the bug - description: A clear and concise description of what the bug is. - placeholder: When I do X, Y happens instead of Z. - validations: - required: true - - - type: textarea - id: reproduction - attributes: - label: Steps to reproduce - description: Detailed steps to reproduce the behavior. - placeholder: | - 1. Go to '...' - 2. Run command '...' - 3. See error - value: | - 1. - 2. - 3. - validations: - required: true - - - type: textarea - id: expected - attributes: - label: Expected behavior - description: A clear and concise description of what you expected to happen. - placeholder: I expected X to happen. - validations: - required: true - - - type: textarea - id: actual - attributes: - label: Actual behavior - description: What actually happened instead. - placeholder: Instead, Y happened. - validations: - required: true - - - type: textarea - id: screenshots - attributes: - label: Screenshots or logs - description: If applicable, add screenshots or paste error logs to help explain the problem. - placeholder: Paste screenshots or error output here. - render: text - validations: - required: false - - - type: dropdown - id: severity - attributes: - label: Severity - description: How severe is this bug? - options: - - Low (cosmetic, minor inconvenience) - - Medium (functionality impaired but workaround exists) - - High (major functionality broken) - - Critical (data loss, security issue, complete failure) - validations: - required: true - - - type: input - id: os - attributes: - label: Operating system - description: What OS are you using? - placeholder: "e.g. Fedora 43, macOS 15.3, Windows 11" - validations: - required: false - - - type: input - id: version - attributes: - label: Version - description: What version of this project are you using? - placeholder: "e.g. 1.2.3, commit abc1234, main branch" - validations: - required: false - - - type: input - id: runtime - attributes: - label: Runtime / toolchain - description: Relevant runtime or toolchain version, if applicable. - placeholder: "e.g. Deno 2.1, Rust nightly 2026-02-10, Gleam 1.8" - validations: - required: false - - - type: textarea - id: additional - attributes: - label: Additional context - description: Add any other context about the problem here. - placeholder: Any other relevant information. - validations: - required: false - - - type: checkboxes - id: checklist - attributes: - label: Pre-submission checklist - options: - - label: I have searched existing issues to ensure this is not a duplicate - required: true - - label: I am using a supported version of this project - required: false - - label: I would be willing to submit a PR to fix this - required: false diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml deleted file mode 100644 index cb7a33c..0000000 --- a/.github/ISSUE_TEMPLATE/config.yml +++ /dev/null @@ -1,10 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Issue template chooser configuration for {{OWNER}}/{{REPO}} -blank_issues_enabled: true -contact_links: - - name: Discussions - url: https://github.com/{{OWNER}}/{{REPO}}/discussions - about: Ask questions, share ideas, or start a conversation in Discussions. - - name: Security Vulnerabilities - url: https://github.com/{{OWNER}}/{{REPO}}/security/advisories/new - about: Report security vulnerabilities privately via GitHub Security Advisories. diff --git a/.github/ISSUE_TEMPLATE/custom.yml b/.github/ISSUE_TEMPLATE/custom.yml deleted file mode 100644 index 6aa9e63..0000000 --- a/.github/ISSUE_TEMPLATE/custom.yml +++ /dev/null @@ -1,76 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Custom issue template for {{OWNER}}/{{REPO}} -name: Other -description: Report an issue that does not fit the other categories -title: "" -labels: ["triage"] -assignees: [] -body: - - type: markdown - attributes: - value: | - Use this template for issues that do not fit into bug reports, feature requests, - documentation, or questions. Please provide as much detail as possible. - - - type: dropdown - id: category - attributes: - label: Issue category - description: What best describes this issue? - options: - - Refactoring - - Technical debt - - Build / CI issue - - Dependency update - - Security concern - - Licensing question - - Ecosystem integration - - Other - validations: - required: true - - - type: textarea - id: description - attributes: - label: Description - description: Clearly describe what this issue is about. - placeholder: Provide a detailed description of the issue. - validations: - required: true - - - type: textarea - id: rationale - attributes: - label: Rationale - description: Why is this important? What is the impact of not addressing it? - placeholder: "This matters because..." - validations: - required: false - - - type: textarea - id: proposal - attributes: - label: Proposed approach - description: If you have a plan or approach in mind, describe it here. - placeholder: "I suggest we..." - validations: - required: false - - - type: textarea - id: additional - attributes: - label: Additional context - description: Add any other context, links, or references. - placeholder: Any supplementary information. - validations: - required: false - - - type: checkboxes - id: checklist - attributes: - label: Pre-submission checklist - options: - - label: I have searched existing issues to ensure this is not a duplicate - required: true - - label: I would be willing to submit a PR to address this - required: false diff --git a/.github/ISSUE_TEMPLATE/documentation.yml b/.github/ISSUE_TEMPLATE/documentation.yml deleted file mode 100644 index 88e0720..0000000 --- a/.github/ISSUE_TEMPLATE/documentation.yml +++ /dev/null @@ -1,64 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Documentation issue template for {{OWNER}}/{{REPO}} -name: Documentation -description: Report unclear, missing, or incorrect documentation -title: "[Docs]: " -labels: ["documentation", "priority: unset", "triage"] -assignees: [] -body: - - type: markdown - attributes: - value: | - Help us improve our documentation by reporting issues or gaps. - - - type: dropdown - id: type - attributes: - label: Documentation issue type - description: What kind of documentation problem is this? - options: - - Missing (documentation doesn't exist) - - Incorrect (information is wrong) - - Unclear (confusing or hard to follow) - - Outdated (no longer accurate) - - Incomplete (partially documented) - - Typo or grammar - validations: - required: true - - - type: input - id: location - attributes: - label: Location - description: Where is this documentation? (URL, file path, or section name) - placeholder: "README.adoc, section \"Installation\"" - validations: - required: true - - - type: textarea - id: description - attributes: - label: Description - description: What is the problem with the current documentation? - placeholder: Describe what is wrong or missing. - validations: - required: true - - - type: textarea - id: suggestion - attributes: - label: Suggested improvement - description: How should the documentation be fixed or improved? - placeholder: "The documentation should say..." - validations: - required: false - - - type: checkboxes - id: contribution - attributes: - label: Contribution - options: - - label: I have searched existing issues to ensure this is not a duplicate - required: true - - label: I would be willing to submit a PR to fix this - required: false diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml deleted file mode 100644 index 6d88090..0000000 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ /dev/null @@ -1,87 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Feature request issue template for {{OWNER}}/{{REPO}} -name: Feature Request -description: Suggest an idea or enhancement for this project -title: "[Feature]: " -labels: ["enhancement", "priority: unset", "triage"] -assignees: [] -body: - - type: markdown - attributes: - value: | - Thank you for suggesting a feature. Please describe your idea clearly so we can - evaluate and prioritize it. - - - type: textarea - id: problem - attributes: - label: Problem statement - description: Is your feature request related to a problem? Describe the pain point. - placeholder: "I'm always frustrated when [...]. Currently there is no way to [...]." - validations: - required: true - - - type: textarea - id: solution - attributes: - label: Proposed solution - description: A clear and concise description of what you want to happen. - placeholder: "I'd like a command/option/feature that [...]." - validations: - required: true - - - type: textarea - id: alternatives - attributes: - label: Alternatives considered - description: Any alternative solutions or features you have considered. - placeholder: "I considered using X, but it doesn't work because [...]." - validations: - required: false - - - type: dropdown - id: category - attributes: - label: Category - description: What area does this feature relate to? - options: - - Core functionality - - Developer experience - - Performance - - Documentation - - CI/CD / Tooling - - Integration / Interop - - Security - - Accessibility - - Other - validations: - required: true - - - type: dropdown - id: priority - attributes: - label: Importance to you - description: How important is this feature for your use case? - options: - - Nice to have - - Important (would improve my workflow) - - Critical (blocking my use case) - validations: - required: true - - - type: textarea - id: additional - attributes: - label: Additional context - description: Add any other context, screenshots, mockups, or references about the feature request. - placeholder: Links, screenshots, related projects, etc. - validations: - required: false - - - type: checkboxes - id: contribution - attributes: - label: Contribution - options: - - label: I would be willing to submit a PR to implement this feature - required: false diff --git a/.github/ISSUE_TEMPLATE/question.yml b/.github/ISSUE_TEMPLATE/question.yml deleted file mode 100644 index 48bb574..0000000 --- a/.github/ISSUE_TEMPLATE/question.yml +++ /dev/null @@ -1,60 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Question issue template for {{OWNER}}/{{REPO}} -name: Question -description: Ask a question about usage or behaviour -title: "[Question]: " -labels: ["question", "triage"] -assignees: [] -body: - - type: markdown - attributes: - value: | - Have a question? You can also ask in - [Discussions](https://github.com/{{OWNER}}/{{REPO}}/discussions) - for broader conversations. - - - type: textarea - id: question - attributes: - label: Your question - description: What would you like to know? - placeholder: "How do I...?" - validations: - required: true - - - type: textarea - id: context - attributes: - label: Context - description: Any relevant context that helps us answer your question. - placeholder: "I'm trying to achieve X and I've tried Y..." - validations: - required: false - - - type: textarea - id: research - attributes: - label: What I have already tried - description: What have you already looked at or attempted? - placeholder: "I've read the README and searched issues but..." - validations: - required: false - - - type: input - id: version - attributes: - label: Version - description: What version of this project are you using? - placeholder: "e.g. 1.2.3, commit abc1234, main branch" - validations: - required: false - - - type: checkboxes - id: checklist - attributes: - label: Pre-submission checklist - options: - - label: I have searched existing issues and discussions - required: true - - label: I have read the available documentation - required: true diff --git a/.github/MAINTAINERS b/.github/MAINTAINERS deleted file mode 100644 index 145c4e9..0000000 --- a/.github/MAINTAINERS +++ /dev/null @@ -1,10 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# MAINTAINERS - Project maintainers and contact information -# -# Format: Name (role) -# Replace placeholders with actual maintainer information. - -{{AUTHOR}} <{{AUTHOR_EMAIL}}> (Lead Maintainer) - -# Additional maintainers: -# Name (role) diff --git a/.github/SECURITY.md b/.github/SECURITY.md deleted file mode 100644 index 09fc7b8..0000000 --- a/.github/SECURITY.md +++ /dev/null @@ -1,410 +0,0 @@ - -# Security Policy - - - -We take security seriously. We appreciate your efforts to responsibly disclose vulnerabilities and will make every effort to acknowledge your contributions. - -## Table of Contents - -- [Reporting a Vulnerability](#reporting-a-vulnerability) -- [What to Include](#what-to-include) -- [Response Timeline](#response-timeline) -- [Disclosure Policy](#disclosure-policy) -- [Scope](#scope) -- [Safe Harbour](#safe-harbour) -- [Recognition](#recognition) -- [Security Updates](#security-updates) -- [Security Best Practices](#security-best-practices) - ---- - -## Reporting a Vulnerability - -### Preferred Method: GitHub Security Advisories - -The preferred method for reporting security vulnerabilities is through GitHub's Security Advisory feature: - -1. Navigate to [Report a Vulnerability](https://github.com/{{OWNER}}/{{REPO}}/security/advisories/new) -2. Click **"Report a vulnerability"** -3. Complete the form with as much detail as possible -4. Submit — we'll receive a private notification - -This method ensures: - -- End-to-end encryption of your report -- Private discussion space for collaboration -- Coordinated disclosure tooling -- Automatic credit when the advisory is published - -### Alternative: Encrypted Email - -If you cannot use GitHub Security Advisories, you may email us directly: - -| | | -|---|---| -| **Email** | {{SECURITY_EMAIL}} | -| **PGP Key** | [Download Public Key]({{PGP_KEY_URL}}) | -| **Fingerprint** | `{{PGP_FINGERPRINT}}` | - -```bash -# Import our PGP key -curl -sSL {{PGP_KEY_URL}} | gpg --import - -# Verify fingerprint -gpg --fingerprint {{SECURITY_EMAIL}} - -# Encrypt your report -gpg --armor --encrypt --recipient {{SECURITY_EMAIL}} report.txt -``` - -> **⚠️ Important:** Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. - ---- - -## What to Include - -A good vulnerability report helps us understand and reproduce the issue quickly. - -### Required Information - -- **Description**: Clear explanation of the vulnerability -- **Impact**: What an attacker could achieve (confidentiality, integrity, availability) -- **Affected versions**: Which versions/commits are affected -- **Reproduction steps**: Detailed steps to reproduce the issue - -### Helpful Additional Information - -- **Proof of concept**: Code, scripts, or screenshots demonstrating the vulnerability -- **Attack scenario**: Realistic attack scenario showing exploitability -- **CVSS score**: Your assessment of severity (use [CVSS 3.1 Calculator](https://www.first.org/cvss/calculator/3.1)) -- **CWE ID**: Common Weakness Enumeration identifier if known -- **Suggested fix**: If you have ideas for remediation -- **References**: Links to related vulnerabilities, research, or advisories - -### Example Report Structure - -```markdown -## Summary -[One-sentence description of the vulnerability] - -## Vulnerability Type -[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] - -## Affected Component -[File path, function name, API endpoint, etc.] - -## Affected Versions -[Version range or specific commits] - -## Severity Assessment -- CVSS 3.1 Score: [X.X] -- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] - -## Description -[Detailed technical description] - -## Steps to Reproduce -1. [First step] -2. [Second step] -3. [...] - -## Proof of Concept -[Code, curl commands, screenshots, etc.] - -## Impact -[What can an attacker achieve?] - -## Suggested Remediation -[Optional: your ideas for fixing] - -## References -[Links to related issues, CVEs, research] -``` - ---- - -## Response Timeline - -We commit to the following response times: - -| Stage | Timeframe | Description | -|-------|-----------|-------------| -| **Initial Response** | 48 hours | We acknowledge receipt and confirm we're investigating | -| **Triage** | 7 days | We assess severity, confirm the vulnerability, and estimate timeline | -| **Status Update** | Every 7 days | Regular updates on remediation progress | -| **Resolution** | 90 days | Target for fix development and release (complex issues may take longer) | -| **Disclosure** | 90 days | Public disclosure after fix is available (coordinated with you) | - -> **Note:** These are targets, not guarantees. Complex vulnerabilities may require more time. We'll communicate openly about any delays. - ---- - -## Disclosure Policy - -We follow **coordinated disclosure** (also known as responsible disclosure): - -1. **You report** the vulnerability privately -2. **We acknowledge** and begin investigation -3. **We develop** a fix and prepare a release -4. **We coordinate** disclosure timing with you -5. **We publish** security advisory and fix simultaneously -6. **You may publish** your research after disclosure - -### Our Commitments - -- We will not take legal action against researchers who follow this policy -- We will work with you to understand and resolve the issue -- We will credit you in the security advisory (unless you prefer anonymity) -- We will notify you before public disclosure -- We will publish advisories with sufficient detail for users to assess risk - -### Your Commitments - -- Report vulnerabilities promptly after discovery -- Give us reasonable time to address the issue before disclosure -- Do not access, modify, or delete data beyond what's necessary to demonstrate the vulnerability -- Do not degrade service availability (no DoS testing on production) -- Do not share vulnerability details with others until coordinated disclosure - -### Disclosure Timeline - -``` -Day 0 You report vulnerability -Day 1-2 We acknowledge receipt -Day 7 We confirm vulnerability and share initial assessment -Day 7-90 We develop and test fix -Day 90 Coordinated public disclosure - (earlier if fix is ready; later by mutual agreement) -``` - -If we cannot reach agreement on disclosure timing, we default to 90 days from your initial report. - ---- - -## Scope - -### In Scope ✅ - -The following are within scope for security research: - -- This repository (`{{OWNER}}/{{REPO}}`) and all its code -- Official releases and packages published from this repository -- Documentation that could lead to security issues -- Build and deployment configurations in this repository -- Dependencies (report here, we'll coordinate with upstream) - -### Out of Scope ❌ - -The following are **not** in scope: - -- Third-party services we integrate with (report directly to them) -- Social engineering attacks against maintainers -- Physical security -- Denial of service attacks against production infrastructure -- Spam, phishing, or other non-technical attacks -- Issues already reported or publicly known -- Theoretical vulnerabilities without proof of concept - -### Qualifying Vulnerabilities - -We're particularly interested in: - -- Remote code execution -- SQL injection, command injection, code injection -- Authentication/authorisation bypass -- Cross-site scripting (XSS) and cross-site request forgery (CSRF) -- Server-side request forgery (SSRF) -- Path traversal / local file inclusion -- Information disclosure (credentials, PII, secrets) -- Cryptographic weaknesses -- Deserialisation vulnerabilities -- Memory safety issues (buffer overflows, use-after-free, etc.) -- Supply chain vulnerabilities (dependency confusion, etc.) -- Significant logic flaws - -### Non-Qualifying Issues - -The following generally do not qualify as security vulnerabilities: - -- Missing security headers on non-sensitive pages -- Clickjacking on pages without sensitive actions -- Self-XSS (requires victim to paste code) -- Missing rate limiting (unless it enables a specific attack) -- Username/email enumeration (unless high-risk context) -- Missing cookie flags on non-sensitive cookies -- Software version disclosure -- Verbose error messages (unless exposing secrets) -- Best practice deviations without demonstrable impact - ---- - -## Safe Harbour - -We support security research conducted in good faith. - -### Our Promise - -If you conduct security research in accordance with this policy: - -- ✅ We will not initiate legal action against you -- ✅ We will not report your activity to law enforcement -- ✅ We will work with you in good faith to resolve issues -- ✅ We consider your research authorised under the Computer Fraud and Abuse Act (CFAA), UK Computer Misuse Act, and similar laws -- ✅ We waive any potential claim against you for circumvention of security controls - -### Good Faith Requirements - -To qualify for safe harbour, you must: - -- Comply with this security policy -- Report vulnerabilities promptly -- Avoid privacy violations (do not access others' data) -- Avoid service degradation (no destructive testing) -- Not exploit vulnerabilities beyond proof-of-concept -- Not use vulnerabilities for profit (beyond bug bounties where offered) - -> **⚠️ Important:** This safe harbour does not extend to third-party systems. Always check their policies before testing. - ---- - -## Recognition - -We believe in recognising security researchers who help us improve. - -### Hall of Fame - -Researchers who report valid vulnerabilities will be acknowledged in our [Security Acknowledgments](SECURITY-ACKNOWLEDGMENTS.md) (unless they prefer anonymity). - -Recognition includes: - -- Your name (or chosen alias) -- Link to your website/profile (optional) -- Brief description of the vulnerability class -- Date of report - -### What We Offer - -- ✅ Public credit in security advisories -- ✅ Acknowledgment in release notes -- ✅ Entry in our Hall of Fame -- ✅ Reference/recommendation letter upon request (for significant findings) - -### What We Don't Currently Offer - -- ❌ Monetary bug bounties -- ❌ Hardware or swag -- ❌ Paid security research contracts - -> **Note:** We're a community project with limited resources. Your contributions help everyone who uses this software. - ---- - -## Security Updates - -### Receiving Updates - -To stay informed about security updates: - -- **Watch this repository**: Click "Watch" → "Custom" → Select "Security alerts" -- **GitHub Security Advisories**: Published at [Security Advisories](https://github.com/{{OWNER}}/{{REPO}}/security/advisories) -- **Release notes**: Security fixes noted in [CHANGELOG](CHANGELOG.md) - -### Update Policy - -| Severity | Response | -|----------|----------| -| **Critical/High** | Patch release as soon as fix is ready | -| **Medium** | Included in next scheduled release (or earlier) | -| **Low** | Included in next scheduled release | - -### Supported Versions - - - -| Version | Supported | Notes | -|---------|-----------|-------| -| `main` branch | ✅ Yes | Latest development | -| Latest release | ✅ Yes | Current stable | -| Previous minor release | ✅ Yes | Security fixes backported | -| Older versions | ❌ No | Please upgrade | - ---- - -## Security Best Practices - -When using {{PROJECT_NAME}}, we recommend: - -### General - -- Keep dependencies up to date -- Use the latest stable release -- Subscribe to security notifications -- Review configuration against security documentation -- Follow principle of least privilege - -### For Contributors - -- Never commit secrets, credentials, or API keys -- Use signed commits (`git config commit.gpgsign true`) -- Review dependencies before adding them -- Run security linters locally before pushing -- Report any concerns about existing code - ---- - -## Additional Resources - -- [Our PGP Public Key]({{PGP_KEY_URL}}) -- [Security Advisories](https://github.com/{{OWNER}}/{{REPO}}/security/advisories) -- [Changelog](CHANGELOG.md) -- [Contributing Guidelines](CONTRIBUTING.md) -- [CVE Database](https://cve.mitre.org/) -- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1) - ---- - -## Contact - -| Purpose | Contact | -|---------|---------| -| **Security issues** | [Report via GitHub](https://github.com/{{OWNER}}/{{REPO}}/security/advisories/new) or {{SECURITY_EMAIL}} | -| **General questions** | [GitHub Discussions](https://github.com/{{OWNER}}/{{REPO}}/discussions) | -| **Other enquiries** | See [README](README.md) for contact information | - ---- - -## Policy Changes - -This security policy may be updated from time to time. Significant changes will be: - -- Committed to this repository with a clear commit message -- Noted in the changelog -- Announced via GitHub Discussions (for major changes) - ---- - -*Thank you for helping keep {{PROJECT_NAME}} and its users safe.* 🛡️ - ---- - -Last updated: {{CURRENT_YEAR}} · Policy version: 1.0.0 diff --git a/.github/SUPPORT b/.github/SUPPORT deleted file mode 100644 index b06c59a..0000000 --- a/.github/SUPPORT +++ /dev/null @@ -1,7 +0,0 @@ -# Support - -For questions, help, and community discussion: - -- GitHub Discussions: https://github.com/{{OWNER}}/{{REPO}}/discussions -- GitHub Issues: https://github.com/{{OWNER}}/{{REPO}}/issues -- Documentation: See README.adoc in the root directory. diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md deleted file mode 100644 index cd2d3fb..0000000 --- a/.github/copilot-instructions.md +++ /dev/null @@ -1,60 +0,0 @@ - - - - -# Copilot Instructions - -## Before Writing Code - -- Read `0-AI-MANIFEST.a2ml` in the repo root for canonical file locations. -- State files (.a2ml) live in `.machine_readable/` ONLY, never the root. - -## License - -- SPDX: `MPL-2.0` on all new files. -- Never use AGPL-3.0. -- Copyright: `{{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}>` - -## Code Style - -- Use descriptive variable names. -- Annotate and document all files. -- Add SPDX header to every source file. -- Use `just` for build/test/lint commands. - -## Banned Patterns - -- Idris2: no `believe_me`, no `assert_total` -- Haskell: no `unsafeCoerce`, no `unsafePerformIO` -- OCaml: no `Obj.magic` -- Coq: no `Admitted` -- Lean: no `sorry` -- Rust: no `transmute` unless FFI with `// SAFETY:` comment - -## Banned Languages - -- No TypeScript (use ReScript) -- No Node.js / npm / bun (use Deno) -- No Go (use Rust) -- No Python (use Julia or Rust) - -## Containers - -- Use Podman, never Docker. -- Name the file `Containerfile`, never `Dockerfile`. -- Base image: `cgr.dev/chainguard/wolfi-base:latest`. - -## ABI/FFI - -- ABI definitions in Idris2 (`src/interface/abi/`). -- FFI implementations in Zig (`src/interface/ffi/`). -- Generated C headers in `src/interface/generated/`. - -## State Files - -Never create these in the repo root: -STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml, AGENTIC.a2ml, NEUROSYM.a2ml, PLAYBOOK.a2ml. -They belong in `.machine_readable/` only. diff --git a/.github/copilot/coding-agent.yml b/.github/copilot/coding-agent.yml deleted file mode 100644 index a719a77..0000000 --- a/.github/copilot/coding-agent.yml +++ /dev/null @@ -1,6 +0,0 @@ -mcp_servers: - boj-server: - command: npx - args: ["-y", "@hyperpolymath/boj-server@latest"] - env: - BOJ_URL: http://localhost:7700 diff --git a/.github/dependabot.yml b/.github/dependabot.yml deleted file mode 100644 index 1af529e..0000000 --- a/.github/dependabot.yml +++ /dev/null @@ -1,57 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Dependabot configuration for RSR-compliant repositories -# Covers common ecosystems - remove unused ones for your project - -version: 2 -updates: - # GitHub Actions - always include - - package-ecosystem: "github-actions" - directory: "/" - schedule: - interval: "weekly" - groups: - actions: - patterns: - - "*" - - # Rust/Cargo - # - # `open-pull-requests-limit: 0` suppresses routine version-update PRs - # (no weekly patch-bump noise) while leaving Dependabot SECURITY PRs - # flowing. Under GitHub's current Dependabot behaviour (2024+), using - # an `ignore:` rule with `version-update:semver-patch` would ALSO - # silence security PRs that happen to be patch-level — historically - # the cause of estate-wide vulns sitting un-PR'd for weeks. - # `open-pull-requests-limit: 0` is the GitHub-endorsed way to say - # "security only, not routine bumps". Pair with the - # dependabot-automerge.yml workflow for low-touch security - # maintenance. - - package-ecosystem: "cargo" - directory: "/" - schedule: - interval: "weekly" - open-pull-requests-limit: 0 - - # Elixir/Mix - - package-ecosystem: "mix" - directory: "/" - schedule: - interval: "weekly" - - # Node.js/npm - - package-ecosystem: "npm" - directory: "/" - schedule: - interval: "weekly" - - # Python/pip - - package-ecosystem: "pip" - directory: "/" - schedule: - interval: "weekly" - - # Nix flakes - - package-ecosystem: "nix" - directory: "/" - schedule: - interval: "weekly" diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md deleted file mode 100644 index 2bd4653..0000000 --- a/.github/pull_request_template.md +++ /dev/null @@ -1,47 +0,0 @@ - -## Summary - - - -## Changes - - - -- - -## RSR Quality Checklist - - - -### Required - -- [ ] Tests pass (`just test` or equivalent) -- [ ] Code is formatted (`just fmt` or equivalent) -- [ ] Linter is clean (no new warnings or errors) -- [ ] No banned language patterns (no TypeScript, no npm/bun, no Go/Python) -- [ ] No `unsafe` blocks without `// SAFETY:` comments -- [ ] No banned functions (`believe_me`, `unsafeCoerce`, `Obj.magic`, `Admitted`, `sorry`) -- [ ] SPDX license headers present on all new/modified source files -- [ ] No secrets, credentials, or `.env` files included - -### As Applicable - -- [ ] `.machine_readable/6a2/STATE.a2ml` updated (if project state changed) -- [ ] `.machine_readable/6a2/ECOSYSTEM.a2ml` updated (if integrations changed) -- [ ] `.machine_readable/6a2/META.a2ml` updated (if architectural decisions changed) -- [ ] Documentation updated for user-facing changes -- [ ] `TOPOLOGY.md` updated (if architecture changed) -- [ ] `CHANGELOG` or release notes updated -- [ ] New dependencies reviewed for license compatibility (MPL-2.0 / MPL-2.0) -- [ ] ABI/FFI changes validated (`src/interface/abi/` and `src/interface/ffi/` consistent) - -## Testing - - - -## Screenshots - - diff --git a/.github/settings.yml b/.github/settings.yml deleted file mode 100644 index 92306c4..0000000 --- a/.github/settings.yml +++ /dev/null @@ -1,125 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# -# Repository settings for probot/settings GitHub App. -# https://github.com/probot/settings -# -# This file defines repository-level configuration that is automatically -# applied by the probot/settings app when changes are pushed to the default -# branch. Install the app at: https://github.com/apps/settings -# -# Template file — replace {{REPO}} and {{DESCRIPTION}} with actual values. - -# ─── Repository Settings ─────────────────────────────────────────────────────── - -repository: - name: "{{REPO}}" - description: "{{DESCRIPTION}}" - homepage: "https://github.com/hyperpolymath/{{REPO}}" - private: false - has_issues: true - has_projects: true - has_wiki: false - has_downloads: true - default_branch: main - allow_squash_merge: true - allow_merge_commit: true - allow_rebase_merge: true - delete_branch_on_merge: true - enable_automated_security_fixes: true - enable_vulnerability_alerts: true - -# ─── Labels ──────────────────────────────────────────────────────────────────── - -labels: - - name: "bug" - color: "d73a4a" - description: "Something isn't working" - - - name: "enhancement" - color: "a2eeef" - description: "New feature or request" - - - name: "documentation" - color: "0075ca" - description: "Improvements or additions to documentation" - - - name: "security" - color: "e4e669" - description: "Security-related issue or vulnerability" - - - name: "good first issue" - color: "7057ff" - description: "Good for newcomers" - - - name: "help wanted" - color: "008672" - description: "Extra attention is needed" - - - name: "question" - color: "d876e3" - description: "Further information is requested" - - - name: "duplicate" - color: "cfd3d7" - description: "This issue or pull request already exists" - - - name: "invalid" - color: "e4e669" - description: "This doesn't seem right" - - - name: "wontfix" - color: "ffffff" - description: "This will not be worked on" - - - name: "dependencies" - color: "0366d6" - description: "Pull requests that update a dependency file" - - - name: "ci/cd" - color: "fbca04" - description: "Continuous integration and deployment" - - - name: "rsr" - color: "006b75" - description: "Rhodium Standard Repository compliance" - - - name: "hypatia" - color: "5319e7" - description: "Hypatia neurosymbolic scanner finding" - - - name: "bot" - color: "b4a8d1" - description: "Automated action by gitbot-fleet" - - - name: "breaking-change" - color: "b60205" - description: "Introduces a breaking change" - - - name: "performance" - color: "f9d0c4" - description: "Performance improvement" - - - name: "refactor" - color: "c5def5" - description: "Code refactoring with no functional change" - -# ─── Branch Protection ───────────────────────────────────────────────────────── - -branches: - - name: "main" - protection: - required_pull_request_reviews: - required_approving_review_count: 1 - dismiss_stale_reviews: true - require_code_owner_reviews: true - required_status_checks: - strict: true - contexts: - - "hypatia-scan" - - "codeql" - - "openssf-compliance" - enforce_admins: true - required_signatures: true - restrictions: null - allow_force_pushes: false - allow_deletions: false diff --git a/.github/workflows/anchor-drift.yml b/.github/workflows/anchor-drift.yml new file mode 100644 index 0000000..4218be1 --- /dev/null +++ b/.github/workflows/anchor-drift.yml @@ -0,0 +1,70 @@ +name: Anchor Drift + +on: + push: + branches: + - main + - claude/gracious-goodall-4vnq77 + pull_request: + branches: + - main + +permissions: + contents: read + +jobs: + membership-integrity: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Check membership manifest and submodule declarations + run: scripts/check-membership.sh + - name: Resolve submodule pins + run: | + git submodule sync --recursive + git submodule update --init --recursive --depth 1 + git submodule status --recursive + + governance-validation: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: hyperpolymath/a2ml-validate-action@main + with: + path: "." + strict: "true" + paths-ignore: | + vendor/ + vendored/ + verified-container-spec/ + .audittraining/ + integration/fixtures/ + test/fixtures/ + tests/fixtures/ + members/ + conformance/ + + conformance-positive: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: hyperpolymath/a2ml-validate-action@main + with: + path: "conformance/valid" + strict: "true" + + conformance-negative: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - id: negative + continue-on-error: true + uses: hyperpolymath/a2ml-validate-action@main + with: + path: "conformance/invalid" + strict: "true" + - name: Require invalid fixtures to fail + if: steps.negative.outcome != 'failure' + run: | + echo "invalid A2ML fixtures unexpectedly passed" + exit 1 diff --git a/.github/workflows/boj-build.yml b/.github/workflows/boj-build.yml deleted file mode 100644 index b203334..0000000 --- a/.github/workflows/boj-build.yml +++ /dev/null @@ -1,45 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# -# OPTIONAL: BoJ Server Build Trigger -# This workflow notifies a BoJ Server instance when code is pushed. -# It is a no-op if BOJ_SERVER_URL is not set or the server is unreachable. -# To enable: set BOJ_SERVER_URL as a repository secret or variable. -# To disable: delete this file or leave BOJ_SERVER_URL unset. -name: BoJ Server Build Trigger -on: - push: - branches: [main, master] - workflow_dispatch: -permissions: - contents: read -jobs: - trigger-boj: - runs-on: ubuntu-latest - timeout-minutes: 15 - if: ${{ vars.BOJ_SERVER_URL != '' || secrets.BOJ_SERVER_URL != '' }} - steps: - - name: Checkout - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - - name: Trigger BoJ Server (Casket/ssg-mcp) - env: - BOJ_URL: ${{ secrets.BOJ_SERVER_URL || vars.BOJ_SERVER_URL }} - REPO_NAME: ${{ github.repository }} - BRANCH_NAME: ${{ github.ref_name }} - run: | - set -euo pipefail - - if [ -z "$BOJ_URL" ]; then - echo "BOJ_SERVER_URL not configured - skipping" - exit 0 - fi - - payload="$(jq -cn \ - --arg repo "$REPO_NAME" \ - --arg branch "$BRANCH_NAME" \ - --arg engine "casket" \ - '{repo:$repo, branch:$branch, engine:$engine}')" - - curl -sf -X POST "${BOJ_URL}/cartridges/ssg-mcp/invoke" \ - -H "Content-Type: application/json" \ - --data "$payload" \ - || echo "BoJ server unreachable - skipping (non-fatal)" diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml deleted file mode 100644 index 349b19f..0000000 --- a/.github/workflows/codeql.yml +++ /dev/null @@ -1,42 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -name: CodeQL Security Analysis -on: - push: - branches: [main, master] - pull_request: - branches: [main, master] - schedule: - - cron: '0 6 * * 1' -permissions: - contents: read -jobs: - analyze: - runs-on: ubuntu-latest - timeout-minutes: 15 - permissions: - contents: read - security-events: write - strategy: - fail-fast: false - matrix: - include: - # Default to `actions` — scaffolded repos rarely have JS/TS - # source; `javascript-typescript` produced "no source files" - # failures on every CodeQL run. The `actions` extractor scans - # workflow files which every repo has. Override per-repo if - # the scaffolded project actually contains JS/TS code. - # Per hypatia rule `codeql_language_matrix_mismatch`. - - language: actions - build-mode: none - steps: - - name: Checkout - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - - name: Initialize CodeQL - uses: github/codeql-action/init@0d579ffd059c29b07949a3cce3983f0780820c98 # v3.28.1 - with: - languages: ${{ matrix.language }} - build-mode: ${{ matrix.build-mode }} - - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@0d579ffd059c29b07949a3cce3983f0780820c98 # v3.28.1 - with: - category: "/language:${{ matrix.language }}" diff --git a/.github/workflows/dependabot-automerge.yml b/.github/workflows/dependabot-automerge.yml deleted file mode 100644 index bce3810..0000000 --- a/.github/workflows/dependabot-automerge.yml +++ /dev/null @@ -1,136 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# -# dependabot-automerge.yml — enable GitHub's native auto-merge on -# Dependabot pull requests that match a declared severity / ecosystem -# policy. Pairs with `.github/dependabot.yml`'s -# `open-pull-requests-limit: 0` + security-only pattern (see the -# cargo block there). -# -# What this does: -# - Triggers on every Dependabot PR. -# - Reads the PR's update-type metadata via the dependabot/fetch-metadata -# action (no free-text parsing). -# - Requires CI to be green before merge (GitHub's auto-merge enforces -# required status checks). -# - Gates merge behind a severity+ecosystem policy table. Default is -# low+medium security updates only. -# -# Why auto-merge on GitHub (not via a bot like rhodibot) is the right -# layer: GitHub enforces branch protection + required checks natively, -# and the PR author is already `dependabot[bot]`. Rhodibot doesn't need -# to know anything about ecosystems — GitHub handles the merge mechanics -# once we approve. -# -# Threat model: -# - A compromised upstream package with a bogus security advisory -# could propose a malicious version bump. Mitigation: require at -# least one non-automated reviewer for HIGH+CRITICAL severity -# (done below — we explicitly refuse to auto-approve those). -# - A compromised Dependabot itself is an Akerlof claim-grounder -# problem. Not in scope here; track under -# `project_claim_grounders_dual_use_akerlof.md`. -# -# Dogfooding: this workflow template is itself subject to the same -# Dependabot config via the github-actions ecosystem block, so SHA -# bumps for dependabot/fetch-metadata flow through the same path. - -name: Dependabot Auto-Merge -on: - pull_request: - types: [opened, reopened, synchronize] -permissions: - contents: write # needed to enable auto-merge - pull-requests: write # needed to approve - # NB: keep narrow — do NOT add secrets: read or id-token: write here. -jobs: - automerge: - # Only run for PRs actually authored by Dependabot. - if: github.actor == 'dependabot[bot]' && github.event.pull_request.user.login == 'dependabot[bot]' - runs-on: ubuntu-latest - timeout-minutes: 15 - steps: - - name: Fetch Dependabot metadata - id: meta - uses: dependabot/fetch-metadata@dbb049abf0d677abbd7f7eee0375145b417fdd34 # v2.2.0 - with: - github-token: ${{ secrets.GITHUB_TOKEN }} - # --- Policy gate ------------------------------------------------------- - # Outputs from fetch-metadata we care about: - # update-type → version-update:semver-{patch,minor,major} - # dependency-type → direct:{development,production} | indirect - # alert-state → AUTO_DISMISSED | DISMISSED | FIXED | OPEN - # ghsa-id → GHSA-... if this is a security PR - # --- Policy ------------------------------------------------------------- - # AUTO-APPROVE + AUTO-MERGE when: - # 1. This is a SECURITY update (ghsa-id present), AND - # 2. Update is patch or minor, AND - # 3. Severity ≤ moderate (Dependabot doesn't expose severity - # directly in fetch-metadata; infer from the absence of - # HIGH/CRITICAL labels added by Dependabot). - # Otherwise: do nothing. Human reviews HIGH+CRITICAL security - # updates and all non-security bumps. - - name: Decide policy outcome - id: policy - env: - GHSA_ID: ${{ steps.meta.outputs.ghsa-id }} - UPDATE_TYPE: ${{ steps.meta.outputs.update-type }} - PR_LABELS: ${{ toJson(github.event.pull_request.labels.*.name) }} - run: | - set -euo pipefail - - is_security=false - is_patch_or_minor=false - is_high_or_critical=false - - [ -n "$GHSA_ID" ] && is_security=true - case "$UPDATE_TYPE" in - version-update:semver-patch|version-update:semver-minor) - is_patch_or_minor=true ;; - esac - - # Dependabot adds severity labels like "severity: high", - # "severity: critical". Look for those in the PR labels JSON. - if echo "$PR_LABELS" | grep -qiE '"(severity: (high|critical))"'; then - is_high_or_critical=true - fi - - if $is_security && $is_patch_or_minor && ! $is_high_or_critical; then - echo "action=automerge" >> "$GITHUB_OUTPUT" - else - echo "action=skip" >> "$GITHUB_OUTPUT" - fi - echo "security=$is_security" >> "$GITHUB_OUTPUT" - echo "update_type=$UPDATE_TYPE" >> "$GITHUB_OUTPUT" - echo "ghsa=$GHSA_ID" >> "$GITHUB_OUTPUT" - - name: Approve PR (if policy allows) - if: steps.policy.outputs.action == 'automerge' - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - PR_URL: ${{ github.event.pull_request.html_url }} - run: | - gh pr review --approve "$PR_URL" \ - --body "Auto-approving Dependabot security update (${{ steps.policy.outputs.ghsa }}, ${{ steps.policy.outputs.update_type }}). Policy: low/moderate security patches/minors only." - - name: Enable auto-merge (if policy allows) - if: steps.policy.outputs.action == 'automerge' - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - PR_URL: ${{ github.event.pull_request.html_url }} - run: | - gh pr merge --auto --squash "$PR_URL" - - name: Write decision to step summary - env: - ACTION: ${{ steps.policy.outputs.action }} - IS_SECURITY: ${{ steps.policy.outputs.security }} - UPDATE_TYPE: ${{ steps.policy.outputs.update_type }} - GHSA: ${{ steps.policy.outputs.ghsa }} - run: | - { - echo "## Dependabot Auto-Merge Decision" - echo "" - echo "| Field | Value |" - echo "|-------|-------|" - echo "| Policy action | \`$ACTION\` |" - echo "| Security update | \`$IS_SECURITY\` |" - echo "| Update type | \`$UPDATE_TYPE\` |" - echo "| GHSA ID | \`${GHSA:-n/a}\` |" - } >> "$GITHUB_STEP_SUMMARY" diff --git a/.github/workflows/dogfood-gate.yml b/.github/workflows/dogfood-gate.yml deleted file mode 100644 index 523b590..0000000 --- a/.github/workflows/dogfood-gate.yml +++ /dev/null @@ -1,386 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# dogfood-gate.yml — Hyperpolymath Dogfooding Quality Gate -# Validates that the repo uses hyperpolymath's own formats and tools. -# Companion to static-analysis-gate.yml (security) — this is for format compliance. -name: Dogfood Gate - -on: - pull_request: - branches: ['**'] - push: - branches: [main, master] - -permissions: - contents: read - -jobs: - # --------------------------------------------------------------------------- - # Job 1: A2ML manifest validation - # --------------------------------------------------------------------------- - a2ml-validate: - name: Validate A2ML manifests - runs-on: ubuntu-latest - timeout-minutes: 15 - - steps: - - name: Checkout repository - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 - - - name: Check for A2ML files - id: detect - run: | - COUNT=$(find . -name '*.a2ml' -not -path './.git/*' | wc -l) - echo "count=$COUNT" >> "$GITHUB_OUTPUT" - if [ "$COUNT" -eq 0 ]; then - echo "::warning::No .a2ml manifest files found. Every RSR repo should have 0-AI-MANIFEST.a2ml" - fi - - - name: Validate A2ML manifests - if: steps.detect.outputs.count > 0 - uses: hyperpolymath/a2ml-validate-action@cb3c1e298169dc5ac2b42e257068b0fb5920cd5e # main - with: - path: '.' - strict: 'false' - - - name: Write summary - run: | - A2ML_COUNT="${{ steps.detect.outputs.count }}" - if [ "$A2ML_COUNT" -eq 0 ]; then - cat <<'EOF' >> "$GITHUB_STEP_SUMMARY" - ## A2ML Validation - - :warning: **No .a2ml files found.** Every RSR-compliant repo should have at least `0-AI-MANIFEST.a2ml`. - - Create one with: `a2mliser init` or copy from [rsr-template-repo](https://github.com/hyperpolymath/rsr-template-repo). - EOF - else - echo "## A2ML Validation" >> "$GITHUB_STEP_SUMMARY" - echo "" >> "$GITHUB_STEP_SUMMARY" - echo "Scanned **${A2ML_COUNT}** .a2ml file(s). See step output for details." >> "$GITHUB_STEP_SUMMARY" - fi - - # --------------------------------------------------------------------------- - # Job 2: K9 contract validation - # --------------------------------------------------------------------------- - k9-validate: - name: Validate K9 contracts - runs-on: ubuntu-latest - timeout-minutes: 15 - - steps: - - name: Checkout repository - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 - - - name: Check for K9 files - id: detect - run: | - COUNT=$(find . \( -name '*.k9' -o -name '*.k9.ncl' \) -not -path './.git/*' | wc -l) - CONFIG_COUNT=$(find . \( -name '*.toml' -o -name '*.yaml' -o -name '*.yml' -o -name '*.json' \) \ - -not -path './.git/*' -not -path './node_modules/*' -not -path './.deno/*' \ - -not -name 'package-lock.json' -not -name 'Cargo.lock' -not -name 'deno.lock' | wc -l) - echo "k9_count=$COUNT" >> "$GITHUB_OUTPUT" - echo "config_count=$CONFIG_COUNT" >> "$GITHUB_OUTPUT" - if [ "$COUNT" -eq 0 ] && [ "$CONFIG_COUNT" -gt 0 ]; then - echo "::warning::Found $CONFIG_COUNT config files but no K9 contracts. Run k9iser to generate contracts." - fi - - - name: Validate K9 contracts - if: steps.detect.outputs.k9_count > 0 - uses: hyperpolymath/k9-validate-action@236f0035cc159051c8dd5dc7cd8af1e8cf961462 # main - with: - path: '.' - strict: 'false' - - - name: Write summary - run: | - K9_COUNT="${{ steps.detect.outputs.k9_count }}" - CFG_COUNT="${{ steps.detect.outputs.config_count }}" - if [ "$K9_COUNT" -eq 0 ]; then - cat <<'EOF' >> "$GITHUB_STEP_SUMMARY" - ## K9 Contract Validation - - :warning: **No K9 contract files found.** Repos with configuration files should have K9 contracts. - - Generate contracts with: `k9iser generate .` - EOF - else - echo "## K9 Contract Validation" >> "$GITHUB_STEP_SUMMARY" - echo "" >> "$GITHUB_STEP_SUMMARY" - echo "Validated **${K9_COUNT}** K9 contract(s) against **${CFG_COUNT}** config file(s)." >> "$GITHUB_STEP_SUMMARY" - fi - - # --------------------------------------------------------------------------- - # Job 3: Empty-linter — invisible character detection - # --------------------------------------------------------------------------- - empty-lint: - name: Empty-linter (invisible characters) - runs-on: ubuntu-latest - timeout-minutes: 15 - - steps: - - name: Checkout repository - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 - - - name: Scan for invisible characters - id: lint - run: | - # Inline invisible character detection (from empty-linter's core patterns). - # Checks for: zero-width spaces, zero-width joiners, BOM, soft hyphens, - # non-breaking spaces, null bytes, and other invisible Unicode in source files. - set +e - PATTERNS='\xc2\xa0|\xe2\x80\x8b|\xe2\x80\x8c|\xe2\x80\x8d|\xef\xbb\xbf|\xc2\xad|\xe2\x80\x8e|\xe2\x80\x8f|\xe2\x80\xaa|\xe2\x80\xab|\xe2\x80\xac|\xe2\x80\xad|\xe2\x80\xae|\x00' - find "$GITHUB_WORKSPACE" \ - -not -path '*/.git/*' -not -path '*/node_modules/*' \ - -not -path '*/.deno/*' -not -path '*/target/*' \ - -not -path '*/_build/*' -not -path '*/deps/*' \ - -not -path '*/external_corpora/*' -not -path '*/.lake/*' \ - -type f \( -name '*.rs' -o -name '*.ex' -o -name '*.exs' -o -name '*.res' \ - -o -name '*.js' -o -name '*.ts' -o -name '*.json' -o -name '*.toml' \ - -o -name '*.yml' -o -name '*.yaml' -o -name '*.md' -o -name '*.adoc' \ - -o -name '*.idr' -o -name '*.zig' -o -name '*.v' -o -name '*.jl' \ - -o -name '*.gleam' -o -name '*.hs' -o -name '*.ml' -o -name '*.sh' \) \ - -exec grep -Prl "$PATTERNS" {} \; > /tmp/empty-lint-results.txt 2>/dev/null - EL_EXIT=$? - set -e - - FINDINGS=$(wc -l < /tmp/empty-lint-results.txt 2>/dev/null || echo 0) - echo "findings=$FINDINGS" >> "$GITHUB_OUTPUT" - echo "exit_code=$EL_EXIT" >> "$GITHUB_OUTPUT" - echo "ready=true" >> "$GITHUB_OUTPUT" - - # Emit annotations for each file with invisible chars - while IFS= read -r filepath; do - [ -z "$filepath" ] && continue - REL_PATH="${filepath#$GITHUB_WORKSPACE/}" - echo "::warning file=${REL_PATH}::Invisible Unicode characters detected (zero-width space, BOM, NBSP, etc.)" - done < /tmp/empty-lint-results.txt - - - name: Write summary - run: | - if [ "${{ steps.lint.outputs.ready }}" = "true" ]; then - FINDINGS="${{ steps.lint.outputs.findings }}" - if [ "$FINDINGS" -gt 0 ] 2>/dev/null; then - echo "## Empty-Linter Results" >> "$GITHUB_STEP_SUMMARY" - echo "" >> "$GITHUB_STEP_SUMMARY" - echo "Found **${FINDINGS}** invisible character issue(s). See annotations above." >> "$GITHUB_STEP_SUMMARY" - else - echo "## Empty-Linter Results" >> "$GITHUB_STEP_SUMMARY" - echo "" >> "$GITHUB_STEP_SUMMARY" - echo ":white_check_mark: No invisible character issues found." >> "$GITHUB_STEP_SUMMARY" - fi - else - echo "## Empty-Linter" >> "$GITHUB_STEP_SUMMARY" - echo "" >> "$GITHUB_STEP_SUMMARY" - echo "Skipped: empty-linter not available." >> "$GITHUB_STEP_SUMMARY" - fi - - # --------------------------------------------------------------------------- - # Job 4: Groove manifest check (for repos that should expose services) - # --------------------------------------------------------------------------- - groove-check: - name: Groove manifest check - runs-on: ubuntu-latest - timeout-minutes: 15 - - steps: - - name: Checkout repository - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 - - - name: Check for Groove manifest - id: groove - run: | - # Check for static or dynamic Groove endpoints - HAS_MANIFEST="false" - HAS_GROOVE_CODE="false" - - if [ -f ".well-known/groove/manifest.json" ]; then - HAS_MANIFEST="true" - # Validate the manifest JSON - if ! jq empty .well-known/groove/manifest.json 2>/dev/null; then - echo "::error file=.well-known/groove/manifest.json::Invalid JSON in Groove manifest" - else - SVC_ID=$(jq -r '.service_id // "unknown"' .well-known/groove/manifest.json) - echo "service_id=$SVC_ID" >> "$GITHUB_OUTPUT" - fi - fi - - # Check for Groove endpoint code (Rust, Elixir, Zig, V) - if grep -rl 'well-known/groove' --include='*.rs' --include='*.ex' --include='*.zig' --include='*.v' --include='*.res' . 2>/dev/null | head -1 | grep -q .; then - HAS_GROOVE_CODE="true" - fi - - # Check if this repo likely serves HTTP (has server/listener code) - HAS_SERVER="false" - if grep -rl 'TcpListener\|Bandit\|Plug.Cowboy\|httpz\|vweb\|axum::serve\|actix_web' --include='*.rs' --include='*.ex' --include='*.zig' --include='*.v' . 2>/dev/null | head -1 | grep -q .; then - HAS_SERVER="true" - fi - - echo "has_manifest=$HAS_MANIFEST" >> "$GITHUB_OUTPUT" - echo "has_groove_code=$HAS_GROOVE_CODE" >> "$GITHUB_OUTPUT" - echo "has_server=$HAS_SERVER" >> "$GITHUB_OUTPUT" - - if [ "$HAS_SERVER" = "true" ] && [ "$HAS_MANIFEST" = "false" ] && [ "$HAS_GROOVE_CODE" = "false" ]; then - echo "::warning::This repo has server code but no Groove endpoint. Add .well-known/groove/manifest.json for service discovery." - fi - - - name: Write summary - run: | - echo "## Groove Protocol Check" >> "$GITHUB_STEP_SUMMARY" - echo "" >> "$GITHUB_STEP_SUMMARY" - echo "| Check | Status |" >> "$GITHUB_STEP_SUMMARY" - echo "|-------|--------|" >> "$GITHUB_STEP_SUMMARY" - echo "| Static manifest (.well-known/groove/manifest.json) | ${{ steps.groove.outputs.has_manifest }} |" >> "$GITHUB_STEP_SUMMARY" - echo "| Groove endpoint in code | ${{ steps.groove.outputs.has_groove_code }} |" >> "$GITHUB_STEP_SUMMARY" - echo "| Has HTTP server code | ${{ steps.groove.outputs.has_server }} |" >> "$GITHUB_STEP_SUMMARY" - - # --------------------------------------------------------------------------- - # Job 5: eclexiaiser manifest validation - # --------------------------------------------------------------------------- - eclexiaiser-validate: - name: Validate eclexiaiser manifest - runs-on: ubuntu-latest - timeout-minutes: 15 - - steps: - - name: Checkout repository - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 - - - name: Check and validate eclexiaiser manifest - id: eclex - run: | - if [ ! -f "eclexiaiser.toml" ]; then - # Check if repo has a Containerfile — if so, recommend eclexiaiser - if [ -f "Containerfile" ]; then - echo "::warning::Containerfile present but no eclexiaiser.toml. Run \`eclexiaiser init\` to scaffold energy/carbon budgets." - fi - echo "has_manifest=false" >> "$GITHUB_OUTPUT" - exit 0 - fi - - echo "has_manifest=true" >> "$GITHUB_OUTPUT" - - # Validate TOML structure using Python 3.11+ tomllib - python3 -c " -import tomllib, sys -with open('eclexiaiser.toml', 'rb') as f: - data = tomllib.load(f) -project = data.get('project', {}) -if not project.get('name', '').strip(): - print('ERROR: project.name is required', file=sys.stderr) - sys.exit(1) -functions = data.get('functions', []) -if not functions: - print('ERROR: at least one [[functions]] entry is required', file=sys.stderr) - sys.exit(1) -for fn in functions: - if not fn.get('name', '').strip(): - print('ERROR: function name cannot be empty', file=sys.stderr) - sys.exit(1) - if not fn.get('source', '').strip(): - print(f'ERROR: function {fn[\"name\"]} has no source path', file=sys.stderr) - sys.exit(1) -print(f'Valid: {project[\"name\"]} ({len(functions)} function(s))') -" || { - echo "::error file=eclexiaiser.toml::Invalid eclexiaiser.toml — see step output for details" - exit 1 - } - - - name: Write summary - run: | - if [ "${{ steps.eclex.outputs.has_manifest }}" = "true" ]; then - echo "## Eclexiaiser Manifest" >> "$GITHUB_STEP_SUMMARY" - echo "" >> "$GITHUB_STEP_SUMMARY" - echo ":white_check_mark: **eclexiaiser.toml** present and valid." >> "$GITHUB_STEP_SUMMARY" - else - echo "## Eclexiaiser Manifest" >> "$GITHUB_STEP_SUMMARY" - echo "" >> "$GITHUB_STEP_SUMMARY" - echo ":ballot_box_with_check: No eclexiaiser.toml. Add one with \`eclexiaiser init\` for energy/carbon tracking." >> "$GITHUB_STEP_SUMMARY" - fi - - # --------------------------------------------------------------------------- - # Job 6: Dogfooding summary - # --------------------------------------------------------------------------- - dogfood-summary: - name: Dogfooding compliance summary - runs-on: ubuntu-latest - timeout-minutes: 15 - needs: [a2ml-validate, k9-validate, empty-lint, groove-check, eclexiaiser-validate] - if: always() - - steps: - - name: Checkout repository - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 - - - name: Generate dogfooding scorecard - run: | - SCORE=0 - MAX=6 - - # A2ML manifest present? - if find . -name '*.a2ml' -not -path './.git/*' | head -1 | grep -q .; then - SCORE=$((SCORE + 1)) - A2ML_STATUS=":white_check_mark:" - else - A2ML_STATUS=":x:" - fi - - # K9 contracts present? - if find . \( -name '*.k9' -o -name '*.k9.ncl' \) -not -path './.git/*' | head -1 | grep -q .; then - SCORE=$((SCORE + 1)) - K9_STATUS=":white_check_mark:" - else - K9_STATUS=":x:" - fi - - # .editorconfig present? - if [ -f ".editorconfig" ]; then - SCORE=$((SCORE + 1)) - EC_STATUS=":white_check_mark:" - else - EC_STATUS=":x:" - fi - - # Groove manifest or code? - if [ -f ".well-known/groove/manifest.json" ] || grep -rl 'well-known/groove' --include='*.rs' --include='*.ex' --include='*.zig' . 2>/dev/null | head -1 | grep -q .; then - SCORE=$((SCORE + 1)) - GROOVE_STATUS=":white_check_mark:" - else - GROOVE_STATUS=":ballot_box_with_check:" - fi - - # VeriSimDB integration? - if grep -rl 'verisimdb\|VeriSimDB' --include='*.toml' --include='*.yaml' --include='*.yml' --include='*.json' --include='*.rs' --include='*.ex' . 2>/dev/null | head -1 | grep -q .; then - SCORE=$((SCORE + 1)) - VSDB_STATUS=":white_check_mark:" - else - VSDB_STATUS=":ballot_box_with_check:" - fi - - # eclexiaiser energy tracking? - if [ -f "eclexiaiser.toml" ]; then - SCORE=$((SCORE + 1)) - ECLEX_STATUS=":white_check_mark:" - else - ECLEX_STATUS=":ballot_box_with_check:" - fi - - cat <> "$GITHUB_STEP_SUMMARY" - ## Dogfooding Scorecard - - **Score: ${SCORE}/${MAX}** - - | Tool/Format | Status | Notes | - |-------------|--------|-------| - | A2ML manifest (0-AI-MANIFEST.a2ml) | ${A2ML_STATUS} | Required for all RSR repos | - | K9 contracts | ${K9_STATUS} | Required for repos with config files | - | .editorconfig | ${EC_STATUS} | Required for all repos | - | Groove endpoint | ${GROOVE_STATUS} | Required for service repos | - | VeriSimDB integration | ${VSDB_STATUS} | Required for stateful repos | - | eclexiaiser | ${ECLEX_STATUS} | Energy/carbon budgets for container services | - - --- - *Generated by the [Dogfood Gate](https://github.com/hyperpolymath/rsr-template-repo) workflow.* - *Dogfooding is guinea pig fooding — we test our tools on ourselves.* - EOF diff --git a/.github/workflows/e2e.yml b/.github/workflows/e2e.yml deleted file mode 100644 index 5cac223..0000000 --- a/.github/workflows/e2e.yml +++ /dev/null @@ -1,186 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# RSR Standard E2E + Aspect + Benchmark Workflow Template -# -# Covers ALL merge requirement test categories: -# - E2E (end-to-end pipeline tests) -# - Aspect (cross-cutting concern validation) -# - Benchmarks (performance regression detection) -# - Readiness (Component Readiness Grade: D/C/B) -# -# INSTRUCTIONS: Uncomment and customise the section matching your stack. -# Delete sections that don't apply. See examples in each job. - -name: E2E + Aspect + Bench -on: - push: - branches: [main, master, develop] - paths: - - 'src/**' - - 'ffi/**' - - 'tests/**' - - '.github/workflows/e2e.yml' - pull_request: - branches: [main, master] - paths: - - 'src/**' - - 'ffi/**' - - 'tests/**' - workflow_dispatch: -permissions: read-all -concurrency: - group: e2e-${{ github.ref }} - cancel-in-progress: true -jobs: -# ─── End-to-End Tests ────────────────────────────────────────────── -# Uncomment ONE of the following e2e job blocks matching your stack. - -## === RUST E2E === -# e2e: -# name: E2E — Full Pipeline -# runs-on: ubuntu-latest -# timeout-minutes: 15 -# steps: -# - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 -# - uses: dtolnay/rust-toolchain@4be9e76fd7c4901c61fb841f559994984270fce7 # stable -# - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2 -# - run: cargo build --release -# - run: bash tests/e2e.sh -# # OR: cargo test --test end_to_end -- --nocapture - -## === ZIG FFI E2E === -# e2e: -# name: E2E — FFI Pipeline -# runs-on: ubuntu-latest -# timeout-minutes: 15 -# steps: -# - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 -# - uses: goto-bus-stop/setup-zig@abea47f85e598557f500fa1fd2ab7464fcb39406 # v2.2.1 -# with: -# version: 0.15.1 -# - run: cd ffi/zig && zig build test -# - run: bash tests/e2e.sh - -## === ELIXIR E2E === -# e2e: -# name: E2E — Full Pipeline -# runs-on: ubuntu-latest -# timeout-minutes: 15 -# steps: -# - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 -# - uses: erlef/setup-beam@fc68ffb90438ef2936bbb3251622353b3dcb2f93 # v1.24.0 -# with: -# otp-version: '27.0' -# elixir-version: '1.17' -# - run: mix deps.get && mix compile --warnings-as-errors -# - run: mix test test/integration/e2e_test.exs --trace - -## === DENO/RESCRIPT E2E === -# e2e: -# name: E2E — Full Pipeline -# runs-on: ubuntu-latest -# timeout-minutes: 15 -# steps: -# - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 -# - uses: denoland/setup-deno@667a34cdef165d8d2b2e98dde39547c9daac7282 # v2.0.4 -# with: -# deno-version: v2.x -# - run: deno install --node-modules-dir=auto -# - run: deno task res:build # ReScript compile -# - run: deno test tests/e2e/ - -## === PLAYWRIGHT (Browser E2E) === -# e2e-playwright: -# name: Playwright — ${{ matrix.project }} -# runs-on: ubuntu-latest -# timeout-minutes: 20 -# strategy: -# fail-fast: false -# matrix: -# project: [chromium-1080p, firefox-1080p, webkit-1080p] -# steps: -# - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 -# - uses: denoland/setup-deno@667a34cdef165d8d2b2e98dde39547c9daac7282 # v2.0.4 -# with: -# deno-version: v2.x -# - run: deno install --node-modules-dir=auto -# - run: npx playwright install --with-deps -# - run: npx playwright test --project=${{ matrix.project }} -# - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 -# if: failure() -# with: -# name: playwright-traces-${{ matrix.project }} -# path: test-results/**/trace.zip -# retention-days: 7 - -## === HASKELL E2E === -# e2e: -# name: E2E — Full Pipeline -# runs-on: ubuntu-latest -# timeout-minutes: 15 -# steps: -# - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 -# - uses: haskell-actions/setup@cd0d9bdd65b20557f41bea4dbe43d0b5fbbfe553 # v2.11.0 -# with: -# ghc-version: '9.6' -# cabal-version: '3.10' -# - run: cabal build all -# - run: bash tests/integration-test.sh - -# ─── Aspect Tests ────────────────────────────────────────────────── -# Cross-cutting concerns: thread safety, ABI contracts, SPDX, dangerous patterns -# Uncomment and customise: - -# aspect-tests: -# name: Aspect — Architectural Invariants -# runs-on: ubuntu-latest -# timeout-minutes: 10 -# steps: -# - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 -# - run: bash tests/aspect_tests.sh - -# ─── Benchmarks ──────────────────────────────────────────────────── -# Performance regression detection. Uncomment matching stack: - -## === RUST BENCH === -# benchmarks: -# name: Bench — Performance Regression -# runs-on: ubuntu-latest -# timeout-minutes: 15 -# steps: -# - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 -# - uses: dtolnay/rust-toolchain@4be9e76fd7c4901c61fb841f559994984270fce7 # stable -# - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2 -# - run: cargo bench 2>&1 | tee /tmp/bench-results.txt -# - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 -# if: always() -# with: -# name: benchmark-results -# path: /tmp/bench-results.txt -# retention-days: 30 - -## === ZIG BENCH === -# benchmarks: -# name: Bench — Performance Regression -# runs-on: ubuntu-latest -# timeout-minutes: 15 -# steps: -# - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 -# - uses: goto-bus-stop/setup-zig@abea47f85e598557f500fa1fd2ab7464fcb39406 # v2.2.1 -# with: -# version: 0.15.1 -# - run: cd ffi/zig && zig build bench - -# ─── Readiness (CRG) ────────────────────────────────────────────── -# Component Readiness Grade: D (runs) → C (correct) → B (edge cases) - -# readiness: -# name: Readiness — Grade D/C/B -# runs-on: ubuntu-latest -# timeout-minutes: 10 -# steps: -# - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 -# - uses: dtolnay/rust-toolchain@4be9e76fd7c4901c61fb841f559994984270fce7 # stable -# - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2 -# - run: cargo test --test readiness -- --nocapture diff --git a/.github/workflows/estate-rules.yml b/.github/workflows/estate-rules.yml deleted file mode 100644 index d85b7ab..0000000 --- a/.github/workflows/estate-rules.yml +++ /dev/null @@ -1,31 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# Estate Rules — enforces hyperpolymath estate-wide conventions: -# * root shape (allowlist of permitted root entries) -# * AsciiDoc-by-default (no .md files under docs/) -# * zig is banned (no zig scaffolding or references) -# -# Each rule is enforced by an executable check script under scripts/. Failures -# are surfaced as workflow errors so the rule can't silently regress. - -name: Estate Rules -on: - push: - branches: [main] - pull_request: -permissions: - contents: read -jobs: - estate-rules: - runs-on: ubuntu-latest - timeout-minutes: 15 - steps: - - name: Checkout - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - - name: Root shape allowlist - run: bash scripts/check-root-shape.sh . - - name: AsciiDoc by default (no .md under docs/) - run: bash scripts/check-no-md-in-docs.sh . - - name: No zig references - run: bash scripts/check-no-vlang.sh . diff --git a/.github/workflows/governance.yml b/.github/workflows/governance.yml deleted file mode 100644 index 8161ec2..0000000 --- a/.github/workflows/governance.yml +++ /dev/null @@ -1,16 +0,0 @@ -# SPDX-License-Identifier: PMPL-1.0-or-later -name: Governance - -on: - push: - branches: [main, master] - pull_request: - branches: [main, master] - workflow_dispatch: - -permissions: - contents: read - -jobs: - governance: - uses: hyperpolymath/standards/.github/workflows/governance-reusable.yml@5a93d9d57cc04de4002d6d0ecd336fc7a8698910 diff --git a/.github/workflows/guix-nix-policy.yml b/.github/workflows/guix-nix-policy.yml deleted file mode 100644 index 3d78b73..0000000 --- a/.github/workflows/guix-nix-policy.yml +++ /dev/null @@ -1,45 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -name: Guix/Nix Package Policy -on: - push: - branches: [main, master] - pull_request: - -# Estate guardrail: scope push to default branches so a PR fires once (not -# push+PR), and cancel superseded runs. Safe — read-only PR-triggered check. -concurrency: - group: ${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: true - -permissions: - contents: read -jobs: - check: - runs-on: ubuntu-latest - timeout-minutes: 15 - permissions: - contents: read - steps: - - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - - name: Enforce Guix primary / Nix fallback - run: | - # Check for package manager files - HAS_GUIX=$(find . -name "*.scm" -o -name ".guix-channel" -o -name "guix.scm" 2>/dev/null | head -1) - HAS_NIX=$(find . -name "*.nix" 2>/dev/null | head -1) - - # Block new package-lock.json, yarn.lock, Gemfile.lock, etc. - NEW_LOCKS=$(git diff --name-only --diff-filter=A HEAD~1 2>/dev/null | grep -E 'package-lock\.json|yarn\.lock|Gemfile\.lock|Pipfile\.lock|poetry\.lock|cargo\.lock' || true) - if [ -n "$NEW_LOCKS" ]; then - echo "⚠️ Lock files detected. Prefer Guix manifests for reproducibility." - fi - - # Prefer Guix, fallback to Nix - if [ -n "$HAS_GUIX" ]; then - echo "✅ Guix package management detected (primary)" - elif [ -n "$HAS_NIX" ]; then - echo "✅ Nix package management detected (fallback)" - else - echo "ℹ️ Consider adding guix.scm or flake.nix for reproducible builds" - fi - - echo "✅ Package policy check passed" diff --git a/.github/workflows/hypatia-scan.yml b/.github/workflows/hypatia-scan.yml deleted file mode 100644 index e715848..0000000 --- a/.github/workflows/hypatia-scan.yml +++ /dev/null @@ -1,19 +0,0 @@ -# SPDX-License-Identifier: PMPL-1.0-or-later -name: Hypatia Security Scan - -on: - push: - branches: [main, master, develop] - pull_request: - branches: [main, master] - schedule: - - cron: '0 0 * * 0' - workflow_dispatch: - -permissions: - contents: read - security-events: read - -jobs: - scan: - uses: hyperpolymath/standards/.github/workflows/hypatia-scan-reusable.yml@5a93d9d57cc04de4002d6d0ecd336fc7a8698910 diff --git a/.github/workflows/instant-sync.yml b/.github/workflows/instant-sync.yml deleted file mode 100644 index 0994325..0000000 --- a/.github/workflows/instant-sync.yml +++ /dev/null @@ -1,32 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Instant Forge Sync - Triggers propagation to all forges on push/release -name: Instant Sync -on: - push: - branches: [main, master] - release: - types: [published] -permissions: - contents: read -jobs: - dispatch: - runs-on: ubuntu-latest - timeout-minutes: 15 - steps: - - name: Trigger Propagation - uses: peter-evans/repository-dispatch@28959ce8df70de7be546dd1250a005dd32156697 # v3 - with: - token: ${{ secrets.FARM_DISPATCH_TOKEN }} - repository: hyperpolymath/.git-private-farm - event-type: propagate - client-payload: |- - { - "repo": "${{ github.event.repository.name }}", - "ref": "${{ github.ref }}", - "sha": "${{ github.sha }}", - "forges": "" - } - - name: Confirm - env: - REPO_NAME: ${{ github.event.repository.name }} - run: echo "::notice::Propagation triggered for ${REPO_NAME}" diff --git a/.github/workflows/mirror.yml b/.github/workflows/mirror.yml deleted file mode 100644 index fcff1f2..0000000 --- a/.github/workflows/mirror.yml +++ /dev/null @@ -1,13 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -name: Mirror to Git Forges -on: - push: - branches: [main] - workflow_dispatch: -permissions: - contents: read -jobs: - mirror: - uses: hyperpolymath/standards/.github/workflows/mirror-reusable.yml@e6b2884722350515934d443daf23442f2195796f - timeout-minutes: 10 - secrets: inherit diff --git a/.github/workflows/npm-bun-blocker.yml b/.github/workflows/npm-bun-blocker.yml deleted file mode 100644 index 153b39d..0000000 --- a/.github/workflows/npm-bun-blocker.yml +++ /dev/null @@ -1,30 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -name: NPM/Bun Blocker -on: - push: - branches: [main, master] - pull_request: - -# Estate guardrail: scope push to default branches so a PR fires once (not -# push+PR), and cancel superseded runs. Safe — read-only PR-triggered check. -concurrency: - group: ${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: true - -permissions: - contents: read -jobs: - check: - runs-on: ubuntu-latest - timeout-minutes: 15 - permissions: - contents: read - steps: - - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - - name: Block npm/bun - run: | - if [ -f "package-lock.json" ] || [ -f "bun.lockb" ] || [ -f ".npmrc" ]; then - echo "❌ npm/bun artifacts detected. Use Deno instead." - exit 1 - fi - echo "✅ No npm/bun violations" diff --git a/.github/workflows/openssf-compliance.yml b/.github/workflows/openssf-compliance.yml deleted file mode 100644 index d688426..0000000 --- a/.github/workflows/openssf-compliance.yml +++ /dev/null @@ -1,113 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# OpenSSF Best Practices compliance gate — blocks PRs and pushes that lack -# required files or still contain unfilled placeholder tokens. -name: OpenSSF Compliance -on: - push: - branches: [main] - pull_request: - branches: [main] - workflow_dispatch: -permissions: - contents: read -jobs: - openssf-compliance: - runs-on: ubuntu-latest - timeout-minutes: 15 - permissions: - contents: read - steps: - - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 - with: - persist-credentials: false - - name: Check SECURITY.md exists and has substance - run: | - SECFILE="" - [ -f "SECURITY.md" ] && SECFILE="SECURITY.md" - [ -f "SECURITY.adoc" ] && SECFILE="SECURITY.adoc" - [ -f ".github/SECURITY.md" ] && SECFILE=".github/SECURITY.md" - - if [ -z "$SECFILE" ]; then - echo "::error::SECURITY.md (or SECURITY.adoc) is required for OpenSSF Best Practices" - exit 1 - fi - - LINES=$(wc -l < "$SECFILE") - if [ "$LINES" -lt 10 ]; then - echo "::error::$SECFILE has only $LINES lines — must have >10 lines of substantive content" - exit 1 - fi - echo "SECURITY file: OK ($SECFILE, $LINES lines)" - - name: Check LICENSE exists - run: | - if [ ! -f "LICENSE" ] && [ ! -f "LICENSE.txt" ] && [ ! -f "LICENSE.md" ]; then - echo "::error::LICENSE file is required for OpenSSF Best Practices" - exit 1 - fi - echo "LICENSE: OK" - - name: Check CONTRIBUTING exists - run: | - if [ ! -f "CONTRIBUTING.md" ] && [ ! -f "CONTRIBUTING.adoc" ]; then - echo "::error::CONTRIBUTING file is required for OpenSSF Best Practices" - exit 1 - fi - echo "CONTRIBUTING: OK" - - name: Check README exists - run: | - if [ ! -f "README.md" ] && [ ! -f "README.adoc" ] && [ ! -f "README.rst" ] && [ ! -f "README.txt" ] && [ ! -f "README" ]; then - echo "::error::README file is required for OpenSSF Best Practices" - exit 1 - fi - echo "README: OK" - - name: Check .machine_readable directory and STATE.a2ml - run: | - if [ ! -d ".machine_readable" ]; then - echo "::error::.machine_readable/ directory is required" - exit 1 - fi - - if [ ! -f ".machine_readable/6a2/STATE.a2ml" ]; then - echo "::error::.machine_readable/6a2/STATE.a2ml is required" - exit 1 - fi - echo ".machine_readable/6a2/STATE.a2ml: OK" - - name: Check CHANGELOG exists - run: | - if [ ! -f "CHANGELOG.md" ] && [ ! -f "CHANGELOG.adoc" ] && [ ! -f "CHANGES.md" ]; then - echo "::error::CHANGELOG.md is required for OpenSSF Best Practices" - exit 1 - fi - echo "CHANGELOG: OK" - - name: Check no unfilled placeholder tokens in required files - run: | - ERRORS=0 - REQUIRED_FILES="" - - # Collect all required files that exist - for f in SECURITY.md SECURITY.adoc .github/SECURITY.md LICENSE LICENSE.txt \ - CONTRIBUTING.md CONTRIBUTING.adoc README.md README.adoc \ - .machine_readable/6a2/STATE.a2ml .machine_readable/6a2/META.a2ml \ - .machine_readable/6a2/ECOSYSTEM.a2ml CHANGELOG.md CHANGELOG.adoc; do - [ -f "$f" ] && REQUIRED_FILES="$REQUIRED_FILES $f" - done - - for f in $REQUIRED_FILES; do - # Match {{ANYTHING}} placeholder tokens - PLACEHOLDERS=$(grep -cE '\{\{[A-Z_]+\}\}' "$f" 2>/dev/null || true) - if [ "$PLACEHOLDERS" -gt 0 ]; then - echo "::error::$f contains $PLACEHOLDERS unfilled {{PLACEHOLDER}} tokens" - grep -nE '\{\{[A-Z_]+\}\}' "$f" | head -5 - ERRORS=$((ERRORS + 1)) - fi - done - - if [ "$ERRORS" -gt 0 ]; then - echo "" - echo "::error::$ERRORS file(s) still contain placeholder tokens — run 'just init' to fill them" - exit 1 - fi - echo "Placeholder check: OK (no unfilled tokens in required files)" - - name: Summary - run: | - echo "=== OpenSSF Best Practices Compliance: PASS ===" - echo "All required files present and placeholder-free." diff --git a/.github/workflows/quality.yml b/.github/workflows/quality.yml deleted file mode 100644 index 3537517..0000000 --- a/.github/workflows/quality.yml +++ /dev/null @@ -1,63 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -name: Code Quality -on: - push: - branches: [main, master] - pull_request: - -# Estate guardrail: scope push to default branches so a PR fires once (not -# push+PR), and cancel superseded runs. Safe — read-only PR-triggered check. -concurrency: - group: ${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: true - - -permissions: - contents: read -jobs: - lint: - runs-on: ubuntu-latest - timeout-minutes: 15 - permissions: - contents: read - steps: - - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - - name: Check file permissions - run: | - find . -type f -perm /111 -name "*.sh" | head -10 || true - - name: Check for secrets - uses: trufflesecurity/trufflehog@6c05c4a00b91aa542267d8e32a8254774799d68d # v3.93.3 - with: - path: ./ - base: ${{ github.event.pull_request.base.sha || github.event.before }} - head: ${{ github.sha }} - continue-on-error: true - - name: Check TODO/FIXME - run: | - echo "=== TODOs ===" - grep -rn "TODO\|FIXME\|HACK\|XXX" --include="*.rs" --include="*.res" --include="*.py" --include="*.ex" . | head -20 || echo "None found" - - name: Check for large files - run: | - find . -type f -size +1M -not -path "./.git/*" | head -10 || echo "No large files" - - name: EditorConfig check - uses: editorconfig-checker/action-editorconfig-checker@4b6cd6190d435e7e084fb35e36a096e98506f7b9 # v2.1.0 - continue-on-error: true - docs: - runs-on: ubuntu-latest - timeout-minutes: 15 - permissions: - contents: read - steps: - - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - - name: Check documentation - run: | - MISSING="" - [ ! -f "README.md" ] && [ ! -f "README.adoc" ] && MISSING="$MISSING README" - [ ! -f "LICENSE" ] && [ ! -f "LICENSE.txt" ] && [ ! -f "LICENSE.md" ] && MISSING="$MISSING LICENSE" - [ ! -f "CONTRIBUTING.md" ] && [ ! -f "CONTRIBUTING.adoc" ] && MISSING="$MISSING CONTRIBUTING" - - if [ -n "$MISSING" ]; then - echo "::warning::Missing docs:$MISSING" - else - echo "✅ Core documentation present" - fi diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml deleted file mode 100644 index 0b50929..0000000 --- a/.github/workflows/release.yml +++ /dev/null @@ -1,153 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# Release workflow — triggered by version tags (v*). -# Builds artifacts, generates changelog via git-cliff, creates a GitHub Release, -# and produces SLSA provenance attestations. -name: Release -on: - push: - tags: - - 'v*' -permissions: - contents: read -jobs: - build: - name: Build Artifacts - runs-on: ubuntu-latest - timeout-minutes: 15 - permissions: - contents: read - steps: - - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - - name: Detect project type and build - id: build - run: | - # Auto-detect build system from project files. - # Order matters: more specific markers checked first. - if [ -f "mix.exs" ]; then - echo "::notice::Detected Elixir/Gleam project (mix.exs)" - echo "build_type=mix" >> "$GITHUB_OUTPUT" - mix local.hex --force --if-missing - mix local.rebar --force --if-missing - mix deps.get --only prod - MIX_ENV=prod mix release - elif [ -f "Cargo.toml" ]; then - echo "::notice::Detected Rust project (Cargo.toml)" - echo "build_type=cargo" >> "$GITHUB_OUTPUT" - cargo build --release - elif [ -f "build.zig" ]; then - echo "::notice::Detected Zig project (build.zig)" - echo "build_type=zig" >> "$GITHUB_OUTPUT" - zig build -Doptimize=ReleaseSafe - elif [ -f "deno.json" ] || [ -f "deno.jsonc" ]; then - echo "::notice::Detected Deno project (deno.json)" - echo "build_type=deno" >> "$GITHUB_OUTPUT" - deno task build - elif [ -f "gossamer.conf.json" ]; then - echo "::notice::Detected Gossamer project (gossamer.conf.json)" - echo "build_type=gossamer" >> "$GITHUB_OUTPUT" - gossamer build - elif [ -f "gleam.toml" ]; then - echo "::notice::Detected Gleam project (gleam.toml)" - echo "build_type=gleam" >> "$GITHUB_OUTPUT" - gleam build - elif [ -f "rebar.config" ]; then - echo "::notice::Detected Erlang/Rebar project (rebar.config)" - echo "build_type=rebar" >> "$GITHUB_OUTPUT" - rebar3 as prod release - elif [ -f "Justfile" ] || [ -f "justfile" ]; then - echo "::notice::Detected Justfile — running 'just build'" - echo "build_type=just" >> "$GITHUB_OUTPUT" - just build - else - echo "::error::No recognised build system found." - echo "Expected one of: mix.exs, Cargo.toml, build.zig, deno.json, gossamer.conf.json, gleam.toml, rebar.config, Justfile" - exit 1 - fi - # TODO: Upload build artifacts if needed - # - uses: actions/upload-artifact@v4 - # with: - # name: release-artifacts - # path: target/release/ - changelog: - name: Generate Changelog - runs-on: ubuntu-latest - timeout-minutes: 15 - permissions: - contents: read - outputs: - changelog: ${{ steps.cliff.outputs.content }} - version: ${{ steps.version.outputs.version }} - steps: - - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - with: - fetch-depth: 0 - - name: Extract version from tag - id: version - run: echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT" - - name: Install git-cliff - run: | - curl -sSfL https://github.com/orhun/git-cliff/releases/latest/download/git-cliff-$(uname -m)-unknown-linux-gnu.tar.gz \ - | tar -xz --strip-components=1 -C /usr/local/bin/ git-cliff-*/git-cliff - - name: Generate changelog for this release - id: cliff - run: | - # Generate changelog for the current tag only - CHANGELOG=$(git cliff --latest --strip header) - # Write to output using delimiter to handle multiline - { - echo "content<> "$GITHUB_OUTPUT" - - name: Update full CHANGELOG.md - run: | - git cliff --output CHANGELOG.md - - name: Upload updated CHANGELOG.md - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 - with: - name: changelog - path: CHANGELOG.md - retention-days: 5 - release: - name: Create GitHub Release - needs: [build, changelog] - runs-on: ubuntu-latest - timeout-minutes: 15 - permissions: - contents: write - steps: - - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - # TODO: Download build artifacts if uploading to the release - # - uses: actions/download-artifact@v4 - # with: - # name: release-artifacts - # path: artifacts/ - - name: Create GitHub Release - uses: softprops/action-gh-release@a06a81a03ee405af7f2048a818ed3f03bbf83c7b # v2 - with: - body: ${{ needs.changelog.outputs.changelog }} - draft: false - prerelease: ${{ contains(github.ref_name, '-rc') || contains(github.ref_name, '-beta') || contains(github.ref_name, '-alpha') }} - generate_release_notes: false - # TODO: Add artifact files to the release - # files: | - # artifacts/* - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - provenance: - name: SLSA Provenance - needs: [build] - permissions: - actions: read - id-token: write - contents: write - # SLSA generator must run in a separate, isolated workflow - # See: https://slsa.dev/spec/v1.0/requirements#build-l3 - uses: slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@f7dd8c54c2067bafc12ca7a55595d5ee9b75204a # v2.1.0 - with: - base64-subjects: "" - # TODO: Replace with actual artifact hashes - # Generate with: sha256sum artifact | base64 -w0 - # base64-subjects: "${{ needs.build.outputs.hashes }}" diff --git a/.github/workflows/rhodibot.yml b/.github/workflows/rhodibot.yml deleted file mode 100644 index d020405..0000000 --- a/.github/workflows/rhodibot.yml +++ /dev/null @@ -1,189 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# rhodibot.yml — Automated RSR compliance enforcement -# -# Reads root-hygiene rules and auto-fixes what it can: -# - Delete banned files (AI.djot, duplicate CONTRIBUTING.adoc, stale snapshots) -# - Rename misnamed files (AI.a2ml → 0-AI-MANIFEST.a2ml) -# - Fix SPDX headers (AGPL → PMPL in dotfiles) -# - Create missing required files (SECURITY.md, CONTRIBUTING.md) -# - Report unfixable issues as PR comments -# -# Runs weekly and on Hypatia scan completion. - -name: "\U0001F916 Rhodibot — RSR Auto-Fix" -on: - schedule: - - cron: '0 6 * * 1' # Every Monday at 06:00 UTC - workflow_dispatch: # Manual trigger - workflow_run: - workflows: ["Hypatia Neurosymbolic Analysis"] - types: [completed] -permissions: - contents: write - pull-requests: write -jobs: - rhodibot: - runs-on: ubuntu-latest - timeout-minutes: 15 - steps: - - name: Checkout - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 - with: - fetch-depth: 1 - - name: Rhodibot — Scan and Fix - id: fix - run: | - set -euo pipefail - FIXES="" - ISSUES="" - CHANGED=false - - # --- 1. Delete banned files --- - for pattern in "AI.djot" "NEXT_STEPS.md" "TODO.md" "NOTES.md" "TASKS.md"; do - if [ -f "$pattern" ]; then - rm "$pattern" - FIXES="$FIXES\n- Deleted \`$pattern\` (superseded)" - CHANGED=true - fi - done - - # Delete stale snapshot files - for f in *-STATUS-*.md *-COMPLETION-*.md *-COMPLETE.md *-VERIFIED-*.md; do - if [ -f "$f" ]; then - rm "$f" - FIXES="$FIXES\n- Deleted stale snapshot \`$f\`" - CHANGED=true - fi - done - - # --- 2. Rename misnamed files --- - if [ -f "AI.a2ml" ] && [ ! -f "0-AI-MANIFEST.a2ml" ]; then - mv AI.a2ml 0-AI-MANIFEST.a2ml - FIXES="$FIXES\n- Renamed \`AI.a2ml\` → \`0-AI-MANIFEST.a2ml\`" - CHANGED=true - fi - - # --- 3. Delete duplicate format files --- - if [ -f "CONTRIBUTING.md" ] && [ -f "CONTRIBUTING.adoc" ]; then - rm CONTRIBUTING.adoc - FIXES="$FIXES\n- Deleted duplicate \`CONTRIBUTING.adoc\` (keeping .md for GitHub)" - CHANGED=true - fi - - if [ -f "README.md" ] && [ -f "README.adoc" ]; then - # Only delete README.md if it's a stub (<5 lines) - lines=$(wc -l < README.md) - if [ "$lines" -lt 5 ]; then - rm README.md - FIXES="$FIXES\n- Deleted stub \`README.md\` (keeping .adoc)" - CHANGED=true - fi - fi - - # --- 4. Fix SPDX headers in dotfiles --- - for dotfile in .gitignore .gitattributes .editorconfig; do - if [ -f "$dotfile" ] && grep -q "AGPL-3.0" "$dotfile" 2>/dev/null; then - sed -i 's/AGPL-3.0-or-later/MPL-2.0/g; s/AGPL-3.0/MPL-2.0/g' "$dotfile" - FIXES="$FIXES\n- Fixed SPDX header in \`$dotfile\` (AGPL → PMPL)" - CHANGED=true - fi - done - - # --- 5. Create missing required files --- - if [ ! -f "SECURITY.md" ]; then - cat > SECURITY.md << 'SECEOF' - - # Security Policy - - ## Reporting a Vulnerability - - **Email:** j.d.a.jewell@open.ac.uk - - **Response timeline:** - - Acknowledgement within 48 hours - - Initial assessment within 7 days - - Fix or mitigation within 90 days - - **Safe harbour:** We will not pursue legal action against security researchers who follow responsible disclosure. - SECEOF - FIXES="$FIXES\n- Created missing \`SECURITY.md\`" - CHANGED=true - fi - - if [ ! -f "CONTRIBUTING.md" ]; then - cat > CONTRIBUTING.md << 'CONTEOF' - - # Contributing - - 1. Fork the repository - 2. Create a feature branch - 3. Ensure SPDX headers on all files - 4. Submit a pull request - - **Author:** Jonathan D.A. Jewell - CONTEOF - FIXES="$FIXES\n- Created missing \`CONTRIBUTING.md\`" - CHANGED=true - fi - - # --- 6. Check for issues we can't auto-fix --- - if [ ! -f "0-AI-MANIFEST.a2ml" ] && [ ! -f "AI.a2ml" ]; then - ISSUES="$ISSUES\n- Missing AI manifest (0-AI-MANIFEST.a2ml)" - fi - - if [ ! -f "LICENSE" ] && [ ! -f "LICENSE.md" ] && [ ! -f "LICENSE.txt" ]; then - ISSUES="$ISSUES\n- Missing LICENSE file" - fi - - if [ ! -f "README.adoc" ] && [ ! -f "README.md" ]; then - ISSUES="$ISSUES\n- Missing README" - fi - - # Check for third-party fork (skip SPDX enforcement) - if [ -f "LICENSE" ] && grep -q "multiple licenses\|LGPL\|Apache" LICENSE 2>/dev/null; then - echo "FORK=true" >> $GITHUB_OUTPUT - fi - - # --- 7. Check dangerous patterns --- - DANGEROUS="" - for pattern in "believe_me" "assert_total" "Admitted" "sorry" "unsafeCoerce" "Obj.magic"; do - count=$(grep -r "$pattern" --include='*.idr' --include='*.v' --include='*.lean' --include='*.hs' --include='*.ml' --include='*.res' . 2>/dev/null | grep -v node_modules | wc -l || echo 0) - if [ "$count" -gt 0 ]; then - DANGEROUS="$DANGEROUS\n- \`$pattern\`: $count occurrences" - fi - done - - # Output results - echo "CHANGED=$CHANGED" >> $GITHUB_OUTPUT - { - echo "FIXES<> $GITHUB_OUTPUT - { - echo "ISSUES<> $GITHUB_OUTPUT - { - echo "DANGEROUS<> $GITHUB_OUTPUT - - name: Create PR with fixes - if: steps.fix.outputs.CHANGED == 'true' - run: "git config user.name \"rhodibot\"\ngit config user.email \"rhodibot@hyperpolymath.dev\"\nBRANCH=\"rhodibot/rsr-compliance-$(date +%Y%m%d)\"\ngit checkout -b \"$BRANCH\"\ngit add -A\ngit commit -m \"fix(rhodibot): automated RSR compliance fixes\n\n${{ steps.fix.outputs.FIXES }}\n\nCo-Authored-By: rhodibot \"\n\ngit push origin \"$BRANCH\"\n\nBODY=\"## \U0001F916 Rhodibot — RSR Compliance Fixes\n\n### Changes Made\n${{ steps.fix.outputs.FIXES }}\n\"\n\nif [ -n \"${{ steps.fix.outputs.ISSUES }}\" ]; then\n BODY=\"$BODY\n### Issues Found (manual fix needed)\n${{ steps.fix.outputs.ISSUES }}\n\"\nfi\n\nif [ -n \"${{ steps.fix.outputs.DANGEROUS }}\" ]; then\n BODY=\"$BODY\n### ⚠️ Dangerous Patterns Detected\n${{ steps.fix.outputs.DANGEROUS }}\n\n_These bypass formal verification. See \\`proven\\` repo for alternatives._\n\"\nfi\n\ngh pr create \\\n --title \"\U0001F916 Rhodibot: RSR compliance fixes\" \\\n --body \"$BODY\" \\\n --base main \\\n --head \"$BRANCH\"\n" - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - - name: Report (no changes needed) - if: steps.fix.outputs.CHANGED != 'true' - run: | - echo "✅ Repository is RSR-compliant. No fixes needed." - if [ -n "${{ steps.fix.outputs.ISSUES }}" ]; then - echo "⚠️ Issues found (manual fix needed):" - echo -e "${{ steps.fix.outputs.ISSUES }}" - fi - if [ -n "${{ steps.fix.outputs.DANGEROUS }}" ]; then - echo "⚠️ Dangerous patterns:" - echo -e "${{ steps.fix.outputs.DANGEROUS }}" - fi diff --git a/.github/workflows/rsr-antipattern.yml b/.github/workflows/rsr-antipattern.yml deleted file mode 100644 index 2df4715..0000000 --- a/.github/workflows/rsr-antipattern.yml +++ /dev/null @@ -1,13 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# RSR Anti-Pattern Check - Uses reusable workflow from standards - -name: RSR Anti-Pattern Check -on: - push: - branches: [main, master, develop] - pull_request: - branches: [main, master, develop] -jobs: - antipattern-check: - uses: hyperpolymath/standards/.github/workflows/rsr-antipattern-reusable.yml@main - timeout-minutes: 10 diff --git a/.github/workflows/rust-ci.yml b/.github/workflows/rust-ci.yml deleted file mode 100644 index 875d30a..0000000 --- a/.github/workflows/rust-ci.yml +++ /dev/null @@ -1,14 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Rust CI — thin wrapper calling the shared estate reusable in -# hyperpolymath/standards. Configure once, propagate everywhere. -# See: docs/CI-REUSABLE-WORKFLOWS.adoc in standards. -name: Rust CI -on: - push: - branches: [main, master] - pull_request: -permissions: - contents: read -jobs: - rust-ci: - uses: hyperpolymath/standards/.github/workflows/rust-ci-reusable.yml@cc5a372af1af1b202c17f1b21efd954e6c038bef diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml deleted file mode 100644 index 47acbb5..0000000 --- a/.github/workflows/scorecard.yml +++ /dev/null @@ -1,16 +0,0 @@ -# SPDX-License-Identifier: PMPL-1.0-or-later -name: OSSF Scorecard - -on: - push: - branches: [main, master] - schedule: - - cron: '0 4 * * *' - workflow_dispatch: - -permissions: - contents: read - -jobs: - scorecard: - uses: hyperpolymath/standards/.github/workflows/scorecard-reusable.yml@5a93d9d57cc04de4002d6d0ecd336fc7a8698910 diff --git a/.github/workflows/secret-scanner.yml b/.github/workflows/secret-scanner.yml deleted file mode 100644 index 10729d0..0000000 --- a/.github/workflows/secret-scanner.yml +++ /dev/null @@ -1,26 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -name: Secret Scanner -on: - pull_request: - push: - branches: [main] -concurrency: - group: ${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: true -permissions: - contents: read -jobs: - scan: - uses: hyperpolymath/standards/.github/workflows/secret-scanner-reusable.yml@3e4bd4c93911750727e2e4c66dff859e00079da0 - timeout-minutes: 10 - secrets: inherit - trufflehog: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - with: - fetch-depth: 0 - - name: TruffleHog Secret Scan - uses: trufflesecurity/trufflehog@main - with: - extra_args: --only-verified --fail diff --git a/.github/workflows/security-policy.yml b/.github/workflows/security-policy.yml deleted file mode 100644 index deafd84..0000000 --- a/.github/workflows/security-policy.yml +++ /dev/null @@ -1,53 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -name: Security Policy -on: - push: - branches: [main, master] - pull_request: - -# Estate guardrail: scope push to default branches so a PR fires once (not -# push+PR), and cancel superseded runs. Safe — read-only PR-triggered check. -concurrency: - group: ${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: true - -permissions: - contents: read -jobs: - check: - runs-on: ubuntu-latest - timeout-minutes: 15 - permissions: - contents: read - steps: - - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - - name: Security checks - run: | - FAILED=false - - # Block MD5/SHA1 for security (allow for checksums/caching) - WEAK_CRYPTO=$(grep -rE 'md5\(|sha1\(' --include="*.py" --include="*.rb" --include="*.js" --include="*.ts" --include="*.go" --include="*.rs" . 2>/dev/null | grep -v 'checksum\|cache\|test\|spec' | head -5 || true) - if [ -n "$WEAK_CRYPTO" ]; then - echo "⚠️ Weak crypto (MD5/SHA1) detected. Use SHA256+ for security:" - echo "$WEAK_CRYPTO" - fi - - # Block HTTP URLs (except localhost) - HTTP_URLS=$(grep -rE 'http://[^l][^o][^c]' --include="*.py" --include="*.js" --include="*.ts" --include="*.go" --include="*.rs" --include="*.yaml" --include="*.yml" . 2>/dev/null | grep -v 'localhost\|127.0.0.1\|example\|test\|spec' | head -5 || true) - if [ -n "$HTTP_URLS" ]; then - echo "⚠️ HTTP URLs found. Use HTTPS:" - echo "$HTTP_URLS" - fi - - # Block hardcoded secrets patterns - SECRETS=$(grep -rEi '(api_key|apikey|secret_key|password)\s*[=:]\s*["\x27][A-Za-z0-9+/=]{20,}' --include="*.py" --include="*.js" --include="*.ts" --include="*.go" --include="*.rs" --include="*.env" . 2>/dev/null | grep -v 'example\|sample\|test\|mock\|placeholder' | head -3 || true) - if [ -n "$SECRETS" ]; then - echo "❌ Potential hardcoded secrets detected!" - FAILED=true - fi - - if [ "$FAILED" = true ]; then - exit 1 - fi - - echo "✅ Security policy check passed" diff --git a/.github/workflows/static-analysis-gate.yml b/.github/workflows/static-analysis-gate.yml deleted file mode 100644 index 8bd1606..0000000 --- a/.github/workflows/static-analysis-gate.yml +++ /dev/null @@ -1,400 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Static Analysis Gate — Required by branch protection rules. -# Runs panic-attack and hypatia, deposits findings for gitbot-fleet learning. -name: Static Analysis Gate -on: - pull_request: - branches: ['**'] - push: - branches: [main, master] -permissions: - contents: read -jobs: - # --------------------------------------------------------------------------- - # Job 1: panic-attack assail - # --------------------------------------------------------------------------- - panic-attack-assail: - name: panic-attack assail - runs-on: ubuntu-latest - timeout-minutes: 15 - steps: - - name: Checkout repository - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - with: - fetch-depth: 0 - - name: Install panic-attack (if available) - id: install - run: | - # Try to fetch the latest release binary from the org - PA_URL="https://github.com/hyperpolymath/panic-attack/releases/latest/download/panic-attack-linux-x86_64" - if curl -fsSL --head "$PA_URL" >/dev/null 2>&1; then - curl -fsSL -o /usr/local/bin/panic-attack "$PA_URL" - chmod +x /usr/local/bin/panic-attack - echo "installed=true" >> "$GITHUB_OUTPUT" - else - echo "::notice::panic-attack binary not available — skipping assail" - echo "installed=false" >> "$GITHUB_OUTPUT" - fi - - name: Run panic-attack assail - id: assail - if: steps.install.outputs.installed == 'true' - run: | - set +e - panic-attack assail --format json . > panic-attack-findings.json 2>&1 - PA_EXIT=$? - set -e - - if [ ! -s panic-attack-findings.json ]; then - echo "[]" > panic-attack-findings.json - fi - - # Parse finding counts - TOTAL=$(jq '. | length' panic-attack-findings.json 2>/dev/null || echo 0) - CRITICAL=$(jq '[.[] | select(.severity == "critical")] | length' panic-attack-findings.json 2>/dev/null || echo 0) - HIGH=$(jq '[.[] | select(.severity == "high")] | length' panic-attack-findings.json 2>/dev/null || echo 0) - MEDIUM=$(jq '[.[] | select(.severity == "medium")] | length' panic-attack-findings.json 2>/dev/null || echo 0) - LOW=$(jq '[.[] | select(.severity == "low")] | length' panic-attack-findings.json 2>/dev/null || echo 0) - - echo "total=$TOTAL" >> "$GITHUB_OUTPUT" - echo "critical=$CRITICAL" >> "$GITHUB_OUTPUT" - echo "high=$HIGH" >> "$GITHUB_OUTPUT" - echo "medium=$MEDIUM" >> "$GITHUB_OUTPUT" - echo "low=$LOW" >> "$GITHUB_OUTPUT" - echo "exit_code=$PA_EXIT" >> "$GITHUB_OUTPUT" - - name: Emit check annotations - if: steps.install.outputs.installed == 'true' - run: | - # Convert JSON findings into GitHub Actions annotations - jq -r '.[] | select(.file != null) | - if .severity == "critical" then - "::error file=\(.file),line=\(.line // 1)::[panic-attack] \(.message)" - elif .severity == "high" then - "::error file=\(.file),line=\(.line // 1)::[panic-attack] \(.message)" - else - "::warning file=\(.file),line=\(.line // 1)::[panic-attack] \(.message)" - end - ' panic-attack-findings.json || true - - name: Write step summary - if: steps.install.outputs.installed == 'true' - run: | - cat <> "$GITHUB_STEP_SUMMARY" - ## panic-attack assail Results - - | Severity | Count | - |----------|-------| - | Critical | ${{ steps.assail.outputs.critical }} | - | High | ${{ steps.assail.outputs.high }} | - | Medium | ${{ steps.assail.outputs.medium }} | - | Low | ${{ steps.assail.outputs.low }} | - | **Total**| ${{ steps.assail.outputs.total }} | - EOF - - name: Create stub findings (when panic-attack unavailable) - if: steps.install.outputs.installed != 'true' - run: | - echo "[]" > panic-attack-findings.json - echo "## panic-attack assail" >> "$GITHUB_STEP_SUMMARY" - echo "" >> "$GITHUB_STEP_SUMMARY" - echo "Skipped: panic-attack not available in this environment." >> "$GITHUB_STEP_SUMMARY" - - name: Upload panic-attack findings - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 - with: - name: panic-attack-findings - path: panic-attack-findings.json - retention-days: 90 - - name: Fail on critical findings - if: steps.install.outputs.installed == 'true' && steps.assail.outputs.critical > 0 - run: | - echo "::error::panic-attack found ${{ steps.assail.outputs.critical }} critical issue(s) — blocking merge" - exit 1 - # --------------------------------------------------------------------------- - # Job 2: hypatia-scan - # --------------------------------------------------------------------------- - hypatia-scan: - name: Hypatia neurosymbolic scan - runs-on: ubuntu-latest - timeout-minutes: 15 - steps: - - name: Checkout repository - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - with: - fetch-depth: 0 - - name: Setup Elixir for Hypatia scanner - id: beam - continue-on-error: true - uses: erlef/setup-beam@e6d7c94229049569db56a7ad5a540c051a010af9 # v1.18.2 - with: - elixir-version: '1.19.4' - otp-version: '28.3' - - name: Clone and build Hypatia - id: build - continue-on-error: true - run: | - git clone https://github.com/hyperpolymath/hypatia.git "$HOME/hypatia" 2>/dev/null || true - if [ -f "$HOME/hypatia/mix.exs" ]; then - cd "$HOME/hypatia" - # Build escript if neither hypatia nor hypatia-v2 exists - if [ ! -f hypatia ] && [ ! -f hypatia-v2 ]; then - mix deps.get - mix escript.build - fi - echo "ready=true" >> "$GITHUB_OUTPUT" - else - echo "::notice::Hypatia scanner not available — skipping scan" - echo "ready=false" >> "$GITHUB_OUTPUT" - fi - - name: Run Hypatia scan - id: scan - if: steps.build.outputs.ready == 'true' - run: | - set +e - HYPATIA_FORMAT=json "$HOME/hypatia/hypatia-cli.sh" scan . > hypatia-findings.json 2>&1 - HYP_EXIT=$? - set -e - - if [ ! -s hypatia-findings.json ] || ! jq empty hypatia-findings.json 2>/dev/null; then - echo "[]" > hypatia-findings.json - fi - - TOTAL=$(jq '. | length' hypatia-findings.json 2>/dev/null || echo 0) - CRITICAL=$(jq '[.[] | select(.severity == "critical")] | length' hypatia-findings.json 2>/dev/null || echo 0) - HIGH=$(jq '[.[] | select(.severity == "high")] | length' hypatia-findings.json 2>/dev/null || echo 0) - MEDIUM=$(jq '[.[] | select(.severity == "medium")] | length' hypatia-findings.json 2>/dev/null || echo 0) - LOW=$(jq '[.[] | select(.severity == "low")] | length' hypatia-findings.json 2>/dev/null || echo 0) - - echo "total=$TOTAL" >> "$GITHUB_OUTPUT" - echo "critical=$CRITICAL" >> "$GITHUB_OUTPUT" - echo "high=$HIGH" >> "$GITHUB_OUTPUT" - echo "medium=$MEDIUM" >> "$GITHUB_OUTPUT" - echo "low=$LOW" >> "$GITHUB_OUTPUT" - - name: Emit check annotations - if: steps.build.outputs.ready == 'true' - run: | - jq -r '.[] | select(.file != null) | - if .severity == "critical" then - "::error file=\(.file),line=\(.line // 1)::[hypatia] \(.message)" - elif .severity == "high" then - "::error file=\(.file),line=\(.line // 1)::[hypatia] \(.message)" - else - "::warning file=\(.file),line=\(.line // 1)::[hypatia] \(.message)" - end - ' hypatia-findings.json || true - - name: Write step summary - if: steps.build.outputs.ready == 'true' - run: | - cat <> "$GITHUB_STEP_SUMMARY" - ## Hypatia Scan Results - - | Severity | Count | - |----------|-------| - | Critical | ${{ steps.scan.outputs.critical }} | - | High | ${{ steps.scan.outputs.high }} | - | Medium | ${{ steps.scan.outputs.medium }} | - | Low | ${{ steps.scan.outputs.low }} | - | **Total**| ${{ steps.scan.outputs.total }} | - EOF - - name: Create stub findings (when Hypatia unavailable) - if: steps.build.outputs.ready != 'true' - run: | - echo "[]" > hypatia-findings.json - echo "## Hypatia Scan" >> "$GITHUB_STEP_SUMMARY" - echo "" >> "$GITHUB_STEP_SUMMARY" - echo "Skipped: Hypatia scanner not available in this environment." >> "$GITHUB_STEP_SUMMARY" - - name: Upload hypatia findings - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 - with: - name: hypatia-findings - path: hypatia-findings.json - retention-days: 90 - - name: Fail on critical security findings - if: steps.build.outputs.ready == 'true' && steps.scan.outputs.critical > 0 - run: | - echo "::error::Hypatia found ${{ steps.scan.outputs.critical }} critical security issue(s) — blocking merge" - exit 1 - # --------------------------------------------------------------------------- - # Job 3: patch-bridge triage (CVE contextual assessment) - # --------------------------------------------------------------------------- - patch-bridge-triage: - name: Patch Bridge CVE triage - runs-on: ubuntu-latest - timeout-minutes: 15 - steps: - - name: Checkout repository - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - with: - fetch-depth: 0 - - name: Install panic-attack (if available) - id: install - run: | - PA_URL="https://github.com/hyperpolymath/panic-attack/releases/latest/download/panic-attack-linux-x86_64" - if curl -fsSL --head "$PA_URL" >/dev/null 2>&1; then - curl -fsSL -o /usr/local/bin/panic-attack "$PA_URL" - chmod +x /usr/local/bin/panic-attack - echo "installed=true" >> "$GITHUB_OUTPUT" - else - echo "::notice::panic-attack binary not available — skipping Patch Bridge" - echo "installed=false" >> "$GITHUB_OUTPUT" - fi - - name: Run Patch Bridge triage - id: triage - if: steps.install.outputs.installed == 'true' - run: | - set +e - panic-attack bridge triage --format json . > bridge-report.json 2>&1 - PB_EXIT=$? - set -e - - if [ ! -s bridge-report.json ] || ! jq empty bridge-report.json 2>/dev/null; then - echo '{"cves":[],"mitigated":0,"unmitigable":0,"concatenative":0,"informational":0}' > bridge-report.json - fi - - UNMITIGABLE=$(jq '.unmitigable // 0' bridge-report.json) - MITIGATED=$(jq '.mitigated // 0' bridge-report.json) - CONCATENATIVE=$(jq '.concatenative // 0' bridge-report.json) - INFORMATIONAL=$(jq '.informational // 0' bridge-report.json) - - echo "unmitigable=$UNMITIGABLE" >> "$GITHUB_OUTPUT" - echo "mitigated=$MITIGATED" >> "$GITHUB_OUTPUT" - echo "concatenative=$CONCATENATIVE" >> "$GITHUB_OUTPUT" - echo "informational=$INFORMATIONAL" >> "$GITHUB_OUTPUT" - - name: Write step summary - if: steps.install.outputs.installed == 'true' - run: | - cat <> "$GITHUB_STEP_SUMMARY" - ## Patch Bridge CVE Triage - - | Classification | Count | - |----------------|-------| - | Unmitigable | ${{ steps.triage.outputs.unmitigable }} | - | Mitigated | ${{ steps.triage.outputs.mitigated }} | - | Concatenative | ${{ steps.triage.outputs.concatenative }} | - | Informational | ${{ steps.triage.outputs.informational }} | - - Unmitigable CVEs require dependency replacement or rearchitecture. - Mitigated CVEs have active controls with soundness proofs. - Concatenative risks are CVE combinations that multiply severity. - EOF - - name: Create stub report (when unavailable) - if: steps.install.outputs.installed != 'true' - run: | - echo '{"cves":[],"mitigated":0,"unmitigable":0,"concatenative":0,"informational":0}' > bridge-report.json - echo "## Patch Bridge CVE Triage" >> "$GITHUB_STEP_SUMMARY" - echo "" >> "$GITHUB_STEP_SUMMARY" - echo "Skipped: panic-attack not available in this environment." >> "$GITHUB_STEP_SUMMARY" - - name: Upload bridge report - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 - with: - name: bridge-report - path: bridge-report.json - retention-days: 90 - - name: Fail on unmitigable CVEs in critical paths - if: steps.install.outputs.installed == 'true' && steps.triage.outputs.unmitigable > 0 - run: | - echo "::warning::Patch Bridge found ${{ steps.triage.outputs.unmitigable }} unmitigable CVE(s) — review required" - # Warning only, not blocking. Unmitigable means the developer needs - # to make an architectural decision, not that the PR is wrong. - # --------------------------------------------------------------------------- - # Job 4: deposit-findings (combines + archives for gitbot-fleet) - # --------------------------------------------------------------------------- - deposit-findings: - name: Deposit findings for gitbot-fleet - runs-on: ubuntu-latest - timeout-minutes: 15 - needs: [panic-attack-assail, hypatia-scan, patch-bridge-triage] - if: always() - steps: - - name: Download panic-attack findings - uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4 - with: - name: panic-attack-findings - path: findings/ - - name: Download hypatia findings - uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4 - with: - name: hypatia-findings - path: findings/ - - name: Download bridge report - uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4 - with: - name: bridge-report - path: findings/ - - name: Combine findings into unified report - id: combine - run: | - PA_FILE="findings/panic-attack-findings.json" - HYP_FILE="findings/hypatia-findings.json" - - # Ensure both files exist and are valid JSON arrays - for f in "$PA_FILE" "$HYP_FILE"; do - if [ ! -s "$f" ] || ! jq empty "$f" 2>/dev/null; then - echo "[]" > "$f" - fi - done - - # Tag each finding with its source scanner - jq '[.[] | . + {"scanner": "panic-attack"}]' "$PA_FILE" > /tmp/pa-tagged.json - jq '[.[] | . + {"scanner": "hypatia"}]' "$HYP_FILE" > /tmp/hyp-tagged.json - - # Read bridge report (CVE triage, not findings array) - BRIDGE_FILE="findings/bridge-report.json" - if [ ! -s "$BRIDGE_FILE" ] || ! jq empty "$BRIDGE_FILE" 2>/dev/null; then - echo '{"cves":[],"mitigated":0,"unmitigable":0,"concatenative":0,"informational":0}' > "$BRIDGE_FILE" - fi - - # Build unified report envelope - jq -n \ - --arg repo "${{ github.repository }}" \ - --arg sha "${{ github.sha }}" \ - --arg ref "${{ github.ref }}" \ - --arg run_id "${{ github.run_id }}" \ - --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \ - --slurpfile pa /tmp/pa-tagged.json \ - --slurpfile hyp /tmp/hyp-tagged.json \ - --slurpfile bridge "$BRIDGE_FILE" \ - '{ - schema_version: "1.1.0", - repository: $repo, - commit_sha: $sha, - ref: $ref, - run_id: $run_id, - timestamp: $ts, - findings: ($pa[0] + $hyp[0]), - patch_bridge: $bridge[0] - }' > findings/unified-findings.json - - TOTAL=$(jq '.findings | length' findings/unified-findings.json) - CRITICAL=$(jq '[.findings[] | select(.severity == "critical")] | length' findings/unified-findings.json) - HIGH=$(jq '[.findings[] | select(.severity == "high")] | length' findings/unified-findings.json) - MEDIUM=$(jq '[.findings[] | select(.severity == "medium")] | length' findings/unified-findings.json) - LOW=$(jq '[.findings[] | select(.severity == "low")] | length' findings/unified-findings.json) - - echo "total=$TOTAL" >> "$GITHUB_OUTPUT" - echo "critical=$CRITICAL" >> "$GITHUB_OUTPUT" - echo "high=$HIGH" >> "$GITHUB_OUTPUT" - echo "medium=$MEDIUM" >> "$GITHUB_OUTPUT" - echo "low=$LOW" >> "$GITHUB_OUTPUT" - - name: Upload unified findings (fleet scanner picks these up) - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 - with: - name: unified-findings - path: findings/unified-findings.json - retention-days: 90 - - name: Write deposit summary - run: | - cat <> "$GITHUB_STEP_SUMMARY" - ## Unified Findings Deposit - - **Repository:** ${{ github.repository }} - **Commit:** \`${{ github.sha }}\` - **Deposited at:** $(date -u +"%Y-%m-%d %H:%M:%S UTC") - - | Severity | Count | - |----------|-------| - | Critical | ${{ steps.combine.outputs.critical }} | - | High | ${{ steps.combine.outputs.high }} | - | Medium | ${{ steps.combine.outputs.medium }} | - | Low | ${{ steps.combine.outputs.low }} | - | **Total**| ${{ steps.combine.outputs.total }} | - - Findings saved as \`unified-findings\` artifact. - The gitbot-fleet scanner will ingest these on its next pass. - EOF diff --git a/.github/workflows/ts-blocker.yml b/.github/workflows/ts-blocker.yml deleted file mode 100644 index 9c6e204..0000000 --- a/.github/workflows/ts-blocker.yml +++ /dev/null @@ -1,35 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -name: TypeScript/JavaScript Blocker -on: - push: - branches: [main, master] - pull_request: - -# Estate guardrail: scope push to default branches so a PR fires once (not -# push+PR), and cancel superseded runs. Safe — read-only PR-triggered check. -concurrency: - group: ${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: true - -permissions: - contents: read -jobs: - check: - runs-on: ubuntu-latest - timeout-minutes: 15 - permissions: - contents: read - steps: - - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - - name: Block new TypeScript/JavaScript - run: | - NEW_TS=$(git diff --name-only --diff-filter=A HEAD~1 2>/dev/null | grep -E '\.(ts|tsx)$' | grep -v '\.gen\.' || true) - NEW_JS=$(git diff --name-only --diff-filter=A HEAD~1 2>/dev/null | grep -E '\.(js|jsx)$' | grep -v '\.res\.js$' | grep -v '\.gen\.' | grep -v 'node_modules' || true) - - if [ -n "$NEW_TS" ] || [ -n "$NEW_JS" ]; then - echo "❌ New TS/JS files detected. Use ReScript instead." - [ -n "$NEW_TS" ] && echo "$NEW_TS" - [ -n "$NEW_JS" ] && echo "$NEW_JS" - exit 1 - fi - echo "✅ ReScript policy enforced" diff --git a/.github/workflows/wellknown-enforcement.yml b/.github/workflows/wellknown-enforcement.yml deleted file mode 100644 index 088e617..0000000 --- a/.github/workflows/wellknown-enforcement.yml +++ /dev/null @@ -1,91 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -name: Well-Known Standards (RFC 9116 + RSR) -on: - push: - branches: [main, master] - paths: - - '.well-known/**' - - 'security.txt' - pull_request: - paths: - - '.well-known/**' - schedule: - # Weekly expiry check - - cron: '0 9 * * *' - workflow_dispatch: -permissions: - contents: read -jobs: - validate: - runs-on: ubuntu-latest - timeout-minutes: 15 - permissions: - contents: read - steps: - - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - - name: RFC 9116 security.txt validation - run: | - SECTXT="" - [ -f ".well-known/security.txt" ] && SECTXT=".well-known/security.txt" - [ -f "security.txt" ] && SECTXT="security.txt" - - if [ -z "$SECTXT" ]; then - echo "::error::No security.txt found — required for OpenSSF Best Practices. See https://github.com/hyperpolymath/well-known-ecosystem" - exit 1 - fi - - # Required: Contact - grep -q "^Contact:" "$SECTXT" || { echo "::error::Missing Contact field"; exit 1; } - - # Required: Expires - if ! grep -q "^Expires:" "$SECTXT"; then - echo "::error::Missing Expires field" - exit 1 - fi - - # Check expiry - EXPIRES=$(grep "^Expires:" "$SECTXT" | cut -d: -f2- | tr -d ' ' | head -1) - if date -d "$EXPIRES" > /dev/null 2>&1; then - DAYS=$(( ($(date -d "$EXPIRES" +%s) - $(date +%s)) / 86400 )) - if [ $DAYS -lt 0 ]; then - echo "::error::security.txt EXPIRED" - exit 1 - elif [ $DAYS -lt 30 ]; then - echo "::warning::security.txt expires in $DAYS days" - else - echo "✅ security.txt valid ($DAYS days)" - fi - fi - - name: RSR well-known compliance - run: | - MISSING="" - [ ! -f ".well-known/security.txt" ] && [ ! -f "security.txt" ] && MISSING="$MISSING security.txt" - [ ! -f ".well-known/ai.txt" ] && MISSING="$MISSING ai.txt" - [ ! -f ".well-known/humans.txt" ] && MISSING="$MISSING humans.txt" - - if [ -n "$MISSING" ]; then - echo "::warning::Missing RSR recommended files:$MISSING" - echo "Reference: https://github.com/hyperpolymath/well-known-ecosystem/.well-known/" - else - echo "✅ RSR well-known compliant" - fi - - name: Mixed content check - run: | - MIXED=$(grep -rE 'src="http://|href="http://' --include="*.html" --include="*.htm" . 2>/dev/null | grep -vE 'localhost|127\.0\.0\.1|example\.com' | head -5 || true) - if [ -n "$MIXED" ]; then - echo "::error::Mixed content (HTTP in HTML)" - echo "$MIXED" - exit 1 - fi - echo "✅ No mixed content" - - name: DNS security records check - if: hashFiles('CNAME') != '' - run: | - DOMAIN=$(cat CNAME 2>/dev/null | tr -d '\n') - if [ -n "$DOMAIN" ]; then - echo "Checking DNS for $DOMAIN..." - # CAA record - dig +short CAA "$DOMAIN" | grep -q "issue" && echo "✅ CAA record" || echo "::warning::No CAA record" - # DNSSEC - dig +dnssec +short "$DOMAIN" | grep -q "RRSIG" && echo "✅ DNSSEC" || echo "::warning::No DNSSEC" - fi diff --git a/.github/workflows/workflow-linter.yml b/.github/workflows/workflow-linter.yml deleted file mode 100644 index f260470..0000000 --- a/.github/workflows/workflow-linter.yml +++ /dev/null @@ -1,157 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# workflow-linter.yml - Validates GitHub workflows against RSR security standards -# This workflow can be copied to other repos for consistent enforcement -name: Workflow Security Linter - -on: - push: - paths: - - '.github/workflows/**' - pull_request: - paths: - - '.github/workflows/**' - workflow_dispatch: - -permissions: - contents: read - -jobs: - lint-workflows: - runs-on: ubuntu-latest - timeout-minutes: 15 - permissions: - contents: read - - steps: - - name: Checkout - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - - - name: Check SPDX Headers - run: | - echo "=== Checking SPDX License Headers ===" - failed=0 - for file in .github/workflows/*.yml .github/workflows/*.yaml; do - [ -f "$file" ] || continue - if ! head -1 "$file" | grep -q "^# SPDX-License-Identifier:"; then - echo "ERROR: $file missing SPDX header" - failed=1 - fi - done - if [ $failed -eq 1 ]; then - echo "Add '# SPDX-License-Identifier: PMPL-1.0' as first line" - exit 1 - fi - echo "All workflows have SPDX headers" - - - name: Check Permissions Declaration - run: | - echo "=== Checking Permissions ===" - failed=0 - for file in .github/workflows/*.yml .github/workflows/*.yaml; do - [ -f "$file" ] || continue - if ! grep -q "^permissions:" "$file"; then - echo "ERROR: $file missing top-level 'permissions:' declaration" - failed=1 - fi - done - if [ $failed -eq 1 ]; then - echo "Add a top-level 'permissions:' block (e.g. contents: read)" - exit 1 - fi - echo "All workflows have permissions declared" - - - name: Check SHA-Pinned Actions - run: | - echo "=== Checking Action Pinning ===" - # Find any uses: lines that don't have @SHA format - # Pattern: uses: owner/repo@<40-char-hex> - unpinned=$(grep -rnE "^[[:space:]]+uses:" .github/workflows/ | \ - grep -v "@[a-f0-9]\{40\}" | \ - grep -v "uses: \./\|uses: docker://\|uses: actions/github-script" || true) - - if [ -n "$unpinned" ]; then - echo "ERROR: Found unpinned actions:" - echo "$unpinned" - echo "" - echo "Replace version tags with SHA pins, e.g.:" - echo " uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.1" - exit 1 - fi - echo "All actions are SHA-pinned" - - - name: Check for Duplicate Workflows - run: | - echo "=== Checking for Duplicates ===" - # Known duplicate patterns - if [ -f .github/workflows/codeql.yml ] && [ -f .github/workflows/codeql-analysis.yml ]; then - echo "ERROR: Duplicate CodeQL workflows found" - echo "Delete codeql-analysis.yml (keep codeql.yml)" - exit 1 - fi - if [ -f .github/workflows/rust.yml ] && [ -f .github/workflows/rust-ci.yml ]; then - echo "WARNING: Potential duplicate Rust workflows" - echo "Consider consolidating rust.yml and rust-ci.yml" - fi - echo "No critical duplicates found" - - - name: Check CodeQL Language Matrix - run: | - echo "=== Checking CodeQL Configuration ===" - if [ ! -f .github/workflows/codeql.yml ]; then - echo "No CodeQL workflow found (optional)" - exit 0 - fi - - # Detect repo languages - has_js=$(find . -name "*.js" -o -name "*.ts" -o -name "*.jsx" -o -name "*.tsx" -path "*/src/*" -o -path "*/lib/*" 2>/dev/null | head -1) - has_py=$(find . -name "*.py" -path "*/src/*" -o -path "*/lib/*" 2>/dev/null | head -1) - has_go=$(find . -name "*.go" -path "*/src/*" -o -path "*/cmd/*" -o -path "*/pkg/*" 2>/dev/null | head -1) - has_rs=$(find . -name "*.rs" -path "*/src/*" 2>/dev/null | head -1) - has_java=$(find . -name "*.java" -path "*/src/*" 2>/dev/null | head -1) - has_rb=$(find . -name "*.rb" -path "*/lib/*" -o -path "*/app/*" 2>/dev/null | head -1) - - echo "Detected languages:" - [ -n "$has_js" ] && echo " - javascript-typescript" - [ -n "$has_py" ] && echo " - python" - [ -n "$has_go" ] && echo " - go" - [ -n "$has_rs" ] && echo " - rust (note: CodeQL rust is limited)" - [ -n "$has_java" ] && echo " - java-kotlin" - [ -n "$has_rb" ] && echo " - ruby" - - # Check for over-reach - if grep -q "language:.*'go'" .github/workflows/codeql.yml && [ -z "$has_go" ]; then - echo "WARNING: CodeQL configured for Go but no Go files found" - fi - if grep -q "language:.*'python'" .github/workflows/codeql.yml && [ -z "$has_py" ]; then - echo "WARNING: CodeQL configured for Python but no Python files found" - fi - if grep -q "language:.*'java'" .github/workflows/codeql.yml && [ -z "$has_java" ]; then - echo "WARNING: CodeQL configured for Java but no Java files found" - fi - if grep -q "language:.*'ruby'" .github/workflows/codeql.yml && [ -z "$has_rb" ]; then - echo "WARNING: CodeQL configured for Ruby but no Ruby files found" - fi - - echo "CodeQL check complete" - - - name: Check Secrets Guards - run: | - echo "=== Checking Secrets Usage ===" - # Look for secrets without conditional guards in mirror workflows - if [ -f .github/workflows/mirror.yml ]; then - if grep -q "secrets\." .github/workflows/mirror.yml; then - if ! grep -q "if:.*vars\." .github/workflows/mirror.yml; then - echo "WARNING: mirror.yml uses secrets without vars guard" - echo "Add 'if: vars.FEATURE_ENABLED == true' to jobs" - fi - fi - fi - echo "Secrets check complete" - - - name: Summary - run: | - echo "" - echo "=== Workflow Linter Summary ===" - echo "All critical checks passed." - echo "" - echo "For more info, see: robot-repo-bot/ERROR-CATALOG.scm" diff --git a/.gitignore b/.gitignore deleted file mode 100644 index cb3cb35..0000000 --- a/.gitignore +++ /dev/null @@ -1,125 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# RSR-compliant .gitignore - -# OS & Editor -.DS_Store -Thumbs.db -*.swp -*.swo -*~ -.idea/ -.vscode/ -.direnv/ - -# Build -/target/ -/_build/ -/dist/ -/out/ - -# Dependencies -/node_modules/ -/vendor/ -/deps/ -/.elixir_ls/ - -# Rust -# Cargo.lock # Keep for binaries - -# Elixir -/cover/ -/doc/ -*.ez -erl_crash.dump - -# Julia -*.jl.cov -*.jl.mem -/Manifest.toml - -# ReScript -/lib/bs/ -/.bsb.lock - -# Python (SaltStack only) -__pycache__/ -*.py[cod] -.venv/ - -# Ada/SPARK -*.ali -/obj/ -/bin/ - -# Nix -# flake.lock is ignored in the template repo because each project should -# generate its own lock file on first use. In derived projects, REMOVE this -# line and track flake.lock for reproducible builds. -flake.lock - -# Haskell -/.stack-work/ -/dist-newstyle/ - -# Chapel -*.chpl.tmp.* - -# Secrets -.env -.env.* -*.pem -*.key -secrets/ - -# Test/Coverage -/coverage/ -htmlcov/ - -# Logs -*.log -/logs/ - -# Maintenance local artifacts -.maintenance-perms-state.tsv -docs/reports/maintenance/*.json - -# Machine-readable locks -.machine_readable/.locks/ - -# Temp -/tmp/ -*.tmp -*.bak - -# Crash recovery artifacts -ai-cli-crash-capture/ - -# KDE metadata -.directory - -# Sync artifacts -sync_report*.txt - -# Hypatia scan cache (local-only) -.hypatia/ -.zig-cache/ -target/ -node_modules/ -_build/ -deps/ -.elixir_ls/ -.cache/ -build/ -dist/ - -# /build/ is a tracked config directory (build orchestration: contractile.just, -# flake.nix, just/*.just, etc.) introduced in chore/root-cleanup. Whitelist -# root-level /build/ so its contents are tracked. The blanket `build/` rule -# above still ignores any nested `build/` directories (e.g. Rust crate -# target/build/) — only the root-level path is exempt. -!/build/ -!/build/** - -# ...but never track Idris2 typecheck output. `idris2 --typecheck abi.ipkg` -# writes compiled .ttc/.ttm under build/ttc/; these are generated artifacts. -/build/ttc/ diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml deleted file mode 100644 index b08314a..0000000 --- a/.gitlab-ci.yml +++ /dev/null @@ -1,154 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Primary CI/CD - GitLab is the source of truth - -stages: - - security - - lint - - test - - build -variables: - CARGO_HOME: ${CI_PROJECT_DIR}/.cargo -cache: - key: ${CI_COMMIT_REF_SLUG} - paths: - - .cargo/ - - target/ -# ================== -# Security Scanning -# ================== -trivy: - stage: security - image: aquasec/trivy:latest - script: - - trivy fs --exit-code 0 --severity HIGH,CRITICAL --format table . - - trivy fs --exit-code 1 --severity CRITICAL . - allow_failure: false -semgrep: - stage: security - image: returntocorp/semgrep - script: - - semgrep --config auto --error . - allow_failure: true -cargo-audit: - stage: security - image: rust:latest - script: - - cargo install cargo-audit - - cargo audit - rules: - - exists: - - Cargo.toml -cargo-deny: - stage: security - image: rust:latest - script: - - cargo install cargo-deny - - cargo deny check - rules: - - exists: - - Cargo.toml - allow_failure: true -mix-audit: - stage: security - image: elixir:latest - script: - - mix local.hex --force - - mix archive.install hex mix_audit --force - - mix deps.get - - mix deps.audit - rules: - - exists: - - mix.exs - allow_failure: true -# ================== -# Linting -# ================== -rustfmt: - stage: lint - image: rust:latest - script: - - rustup component add rustfmt - - cargo fmt -- --check - rules: - - exists: - - Cargo.toml -clippy: - stage: lint - image: rust:latest - script: - - rustup component add clippy - - cargo clippy -- -D warnings - rules: - - exists: - - Cargo.toml - allow_failure: true -mix-format: - stage: lint - image: elixir:latest - script: - - mix format --check-formatted - rules: - - exists: - - mix.exs -credo: - stage: lint - image: elixir:latest - script: - - mix local.hex --force - - mix deps.get - - mix credo --strict - rules: - - exists: - - mix.exs - allow_failure: true -# ================== -# Testing -# ================== -cargo-test: - stage: test - image: rust:latest - script: - - cargo test --all-features - rules: - - exists: - - Cargo.toml -mix-test: - stage: test - image: elixir:latest - script: - - mix local.hex --force - - mix deps.get - - mix test - rules: - - exists: - - mix.exs -# ================== -# Build -# ================== -cargo-build: - stage: build - image: rust:latest - script: - - cargo build --release - artifacts: - paths: - - target/release/ - expire_in: 1 week - rules: - - exists: - - Cargo.toml -mix-build: - stage: build - image: elixir:latest - script: - - mix local.hex --force - - mix deps.get - - MIX_ENV=prod mix compile - rules: - - exists: - - mix.exs -trufflehog: - stage: security - image: trufflesecurity/trufflehog:latest - script: - - trufflehog git file://. --only-verified --fail diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..31fda17 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,48 @@ +[submodule "members/implementations/a2ml-rs"] + path = members/implementations/a2ml-rs + url = https://github.com/hyperpolymath/a2ml-rs.git + branch = main +[submodule "members/implementations/a2ml_ex"] + path = members/implementations/a2ml_ex + url = https://github.com/hyperpolymath/a2ml_ex.git + branch = main +[submodule "members/implementations/a2ml_gleam"] + path = members/implementations/a2ml_gleam + url = https://github.com/hyperpolymath/a2ml_gleam.git + branch = main +[submodule "members/implementations/a2ml-deno"] + path = members/implementations/a2ml-deno + url = https://github.com/hyperpolymath/a2ml-deno.git + branch = main +[submodule "members/implementations/a2ml-haskell"] + path = members/implementations/a2ml-haskell + url = https://github.com/hyperpolymath/a2ml-haskell.git + branch = main +[submodule "members/tooling/tree-sitter-a2ml"] + path = members/tooling/tree-sitter-a2ml + url = https://github.com/hyperpolymath/tree-sitter-a2ml.git + branch = main +[submodule "members/tooling/vscode-a2ml"] + path = members/tooling/vscode-a2ml + url = https://github.com/hyperpolymath/vscode-a2ml.git + branch = main +[submodule "members/tooling/pandoc-a2ml"] + path = members/tooling/pandoc-a2ml + url = https://github.com/hyperpolymath/pandoc-a2ml.git + branch = main +[submodule "members/tooling/a2mliser"] + path = members/tooling/a2mliser + url = https://github.com/hyperpolymath/a2mliser.git + branch = main +[submodule "members/ci/a2ml-validate-action"] + path = members/ci/a2ml-validate-action + url = https://github.com/hyperpolymath/a2ml-validate-action.git + branch = main +[submodule "members/ci/a2ml-pre-commit"] + path = members/ci/a2ml-pre-commit + url = https://github.com/hyperpolymath/a2ml-pre-commit.git + branch = main +[submodule "members/examples/a2ml-showcase"] + path = members/examples/a2ml-showcase + url = https://github.com/hyperpolymath/a2ml-showcase.git + branch = main diff --git a/.machine_readable/0.1-AI-MANIFEST.a2ml b/.machine_readable/0.1-AI-MANIFEST.a2ml deleted file mode 100644 index 7d8ce9e..0000000 --- a/.machine_readable/0.1-AI-MANIFEST.a2ml +++ /dev/null @@ -1,30 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "machine-readable-pillar" -level: 1 -parent: "../0-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Registry for all machine-readable metadata, policies, and internal - automation scripts. - -canonical_locations: - state: "6a2/STATE.a2ml" - meta: "6a2/META.a2ml" - ecosystem: "6a2/ECOSYSTEM.a2ml" - agentic: "6a2/AGENTIC.a2ml" - neurosym: "6a2/NEUROSYM.a2ml" - playbook: "6a2/PLAYBOOK.a2ml" - clade: "6a2/CLADE.a2ml" - anchors: "6a2/anchors/" - policies: "policies/" - ai_configs: "ai/" - compliance: "compliance/" - scripts: "scripts/" - -invariants: - - "Metadata files MUST follow a2ml format" - - "Internal automation MUST live in scripts/ subfolder" diff --git a/.machine_readable/6a2/0-AI-MANIFEST.a2ml b/.machine_readable/6a2/0-AI-MANIFEST.a2ml deleted file mode 100644 index a542ab6..0000000 --- a/.machine_readable/6a2/0-AI-MANIFEST.a2ml +++ /dev/null @@ -1,32 +0,0 @@ -# AI Manifest for 6a2 Directory - -## Purpose - -This manifest declares the AI-assistant context for the 6a2 machine-readable metadata directory. - -## Canonical Locations - -The 7 core A2ML files MUST exist in this directory: -1. AGENTIC.a2ml -2. CLADE.a2ml -3. ECOSYSTEM.a2ml -4. META.a2ml -5. NEUROSYM.a2ml -6. PLAYBOOK.a2ml -7. STATE.a2ml - -## Invariants - -- No duplicate files in root directory -- Single source of truth: this directory is authoritative -- No stale metadata - -## Protocol - -When multiple agents may write to A2ML files concurrently: -1. Read file and record git-sha-at-read in [provenance] section -2. Lock by creating .lock- -3. Write updated file with new [provenance] metadata -4. Release by removing lock file -5. On conflict: re-read and retry if git-sha-at-read does not match HEAD - diff --git a/.machine_readable/6a2/AGENTIC.a2ml b/.machine_readable/6a2/AGENTIC.a2ml deleted file mode 100644 index b21d81b..0000000 --- a/.machine_readable/6a2/AGENTIC.a2ml +++ /dev/null @@ -1,51 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# AGENTIC.a2ml — AI agent constraints and capabilities -# Defines what AI agents can and cannot do in this repository. - -[metadata] -version = "0.1.0" -last-updated = "2026-04-11" - -[agent-permissions] -can-edit-source = true -can-edit-tests = true -can-edit-docs = true -can-edit-config = true -can-create-files = true - -[agent-constraints] -# What AI agents must NOT do: -# - Never use banned language patterns (believe_me, unsafeCoerce, etc.) -# - Never commit secrets or credentials -# - Never use banned languages (TypeScript, Python, Go, etc.) -# - Never place state files in repository root (must be in .machine_readable/) -# - Never use AGPL license (use MPL-2.0) - -[maintenance-integrity] -fail-closed = true -require-evidence-per-step = true -allow-silent-skip = false -require-rerun-after-fix = true -release-claim-requires-hard-pass = true - -# ============================================================================ -# METHODOLOGY (ADR-002) -# ============================================================================ -# Detailed methodology configuration lives in: -# .machine_readable/bot_directives/methodology.a2ml -# .machine_readable/bot_directives/coverage.a2ml -# .machine_readable/bot_directives/debt.a2ml -# -# AGENTIC.a2ml declares WHAT agents can do (permissions, gating). -# bot_directives/ declares HOW agents should work (methodology). - -[methodology] -instructions-dir = ".machine_readable/bot_directives/" -default-mode = "hybrid" - -[automation-hooks] -# on-enter: Read 0-AI-MANIFEST.a2ml, then STATE.a2ml, then bot_directives/ -# on-exit: Update STATE.a2ml, coverage.a2ml, and debt.a2ml with session outcomes -# on-commit: Run just validate-rsr diff --git a/.machine_readable/6a2/CLADE.a2ml b/.machine_readable/6a2/CLADE.a2ml deleted file mode 100644 index b14389c..0000000 --- a/.machine_readable/6a2/CLADE.a2ml +++ /dev/null @@ -1,26 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Clade declaration — part of the gv-clade-index registry -# See: https://github.com/hyperpolymath/gv-clade-index - -[identity] -uuid = "a5ea1382-a34c-5334-8a46-a2ebe904c810" -primary-forge = "github" -primary-owner = "hyperpolymath" -canonical-name = "rsr-template-repo" -prefixed-name = "rm-rsr-template-repo" - -[clade] -primary = "rm" -secondary = ["gv"] -assigned = "2026-03-16" -rationale = "" - -[forges] -github = "hyperpolymath/rsr-template-repo" -gitlab = "hyperpolymath/rsr-template-repo" -bitbucket = "hyperpolymath/rsr-template-repo" - -[lineage] -type = "standalone" -parent = "RSR template — scaffold for new repos" -born = "2026-03-16" diff --git a/.machine_readable/6a2/ECOSYSTEM.a2ml b/.machine_readable/6a2/ECOSYSTEM.a2ml deleted file mode 100644 index cec008d..0000000 --- a/.machine_readable/6a2/ECOSYSTEM.a2ml +++ /dev/null @@ -1,39 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# ECOSYSTEM.a2ml — Ecosystem position (META-TEMPLATE) -# -# This is the ECOSYSTEM file for rsr-template-repo itself. It records the -# TEMPLATE's own position in the estate. When consumed by a new project, -# replace these fields with the target project's ecosystem position and -# related projects (see the NOTE FOR CONSUMERS at the bottom). - -[metadata] -project = "rsr-template-repo" -ecosystem = "hyperpolymath" - -[position] -type = "repository-template" -purpose = "Canonical RSR-compliant repository template: scaffolding (CI/CD, AI manifests, ABI/FFI standards, container ecosystem, governance) that new hyperpolymath projects are instantiated from." - -[pipeline] -position = "foundation" -chain = "standards → rsr-template-repo → (every estate repo)" -notes = "rsr-template-repo turns the RSR standard into runnable scaffolding. New repos are created from it via `just init`, which substitutes the {{PLACEHOLDER}} tokens." -coordination = "standards" - -[related-projects] -projects = [ - { name = "standards", relationship = "standard-source", notes = "Defines the RSR standard, contractile canon, and policies that this template operationalises." }, - { name = "stapeln", relationship = "build-tooling", notes = "Layer-based container build system; the template ships stapeln.toml scaffolding." }, - { name = "selur-compose", relationship = "build-tooling", notes = "Service composition; the template ships selur-compose.toml scaffolding." }, - { name = "k9-svc", relationship = "validation-tooling", notes = "Runs the self-validating k9.ncl checks (.machine_readable/self-validating/)." }, - { name = "cerro-torre", relationship = "signing-tooling", notes = "Container/image signing provider referenced by the container scaffolding." }, - { name = "svalinn", relationship = "verification-tooling", notes = "Supply-chain verification referenced by the container scaffolding." }, - { name = "vordr", relationship = "verification-tooling", notes = "Build/artifact verification referenced by the container scaffolding." }, -] - -# --------------------------------------------------------------------------- -# NOTE FOR CONSUMERS: When using this template to create a new repo, replace -# the project/purpose above and rewrite [related-projects] to describe YOUR -# project's actual ecosystem. The entries above describe the TEMPLATE's own -# position, not yours. -# --------------------------------------------------------------------------- diff --git a/.machine_readable/6a2/META.a2ml b/.machine_readable/6a2/META.a2ml deleted file mode 100644 index d9b09e6..0000000 --- a/.machine_readable/6a2/META.a2ml +++ /dev/null @@ -1,53 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# META.a2ml — Project meta-level information -# Architecture decisions, design rationale, governance. - -[metadata] -version = "0.1.0" -last-updated = "2026-04-11" - -[project-info] -type = "library" # TODO: update type (library|binary|service|website|monorepo) # library | binary | monorepo | service | website -languages = [] # e.g. ["rust", "zig", "idris2"] -license = "MPL-2.0" -author = "Jonathan D.A. Jewell (hyperpolymath)" - -[architecture-decisions] -# ADR format: status = proposed | accepted | deprecated | superseded | rejected -# - { id = "ADR-001", title = "Use Zig for FFI", status = "accepted", date = "2026-02-14" } - -[development-practices] -build-tool = "just" -container-runtime = "podman" -ci-platform = "github-actions" -package-manager = "guix" # guix | nix | cargo | mix - -[maintenance-axes] -scoping-first = true -execution-order = "axis-1 > axis-2 > axis-3" -axis-1 = "must > intend > like" -axis-2 = "corrective > adaptive > perfective" -axis-3 = "systems > compliance > effects" - -[scoping] -sources = "README, roadmap, status docs, maintenance checklist, CI/security docs" -marker-scan = "TODO/FIXME/XXX/HACK/STUB/PARTIAL" -idris-unsound-scan = "believe_me/assert_total" - -[axis-2-maintenance-rules] -corrective-first = true -adaptive-second = true -adaptive-focus = "scope-change reconciliation, stale-reference removal, obsolete-work culling" -perfective-third = true -perfective-source = "axis-1 honest state after corrective/adaptive updates" - -[axis-3-audit-rules] -audit-focus = "systems in place, documentation explains actual state, safety/security accounted for, observed effects reviewed" -compliance-focus = "seams/compromises/exception register, bounded exceptions, anti-drift checks" -drift-risk-example = "single exception broadening into policy violation (e.g. ReScript->TypeScript spread)" -effects-evidence = "benchmark execution/results and maintainer status dialogue/review" - -[design-rationale] -# Key design decisions and their reasoning diff --git a/.machine_readable/6a2/NEUROSYM.a2ml b/.machine_readable/6a2/NEUROSYM.a2ml deleted file mode 100644 index 1acf7a3..0000000 --- a/.machine_readable/6a2/NEUROSYM.a2ml +++ /dev/null @@ -1,23 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# NEUROSYM.a2ml — Neurosymbolic integration metadata -# Configuration for Hypatia scanning and symbolic reasoning. - -[metadata] -version = "0.1.0" -last-updated = "2026-04-11" - -[hypatia-config] -scan-enabled = true -scan-depth = "standard" # quick | standard | deep -report-format = "logtalk" - -[symbolic-rules] -# Custom symbolic rules for this project -# - { name = "no-unsafe-ffi", pattern = "believe_me|unsafeCoerce", severity = "critical" } - -[neural-config] -# Neural pattern detection settings -# confidence-threshold = 0.85 -# model = "hypatia-v2" diff --git a/.machine_readable/6a2/PLAYBOOK.a2ml b/.machine_readable/6a2/PLAYBOOK.a2ml deleted file mode 100644 index 7a55b56..0000000 --- a/.machine_readable/6a2/PLAYBOOK.a2ml +++ /dev/null @@ -1,137 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# PLAYBOOK.a2ml — Operational playbook -# Runbooks, incident response, deployment procedures. - -[metadata] -version = "0.1.0" -last-updated = "2026-04-11" - -[deployment] -# method = "gitops" # gitops | manual | ci-triggered -# target = "container" # container | binary | library | wasm - -[incident-response] -# 1. Check .machine_readable/6a2/STATE.a2ml for current status -# 2. Review recent commits and CI results -# 3. Run `just validate` to check compliance -# 4. Run `just security` to audit for vulnerabilities - -[release-process] -# 1. Update version in STATE.a2ml, META.a2ml, Justfile -# 2. Run `just release-preflight` (validate + quality + security + maint-hard-pass) -# 3. Optional local permission hardening: `just perms-snapshot && just perms-lock` -# 4. Tag and push -# 5. Restore local permissions if needed: `just perms-restore` -# 6. Run `just container-push` if applicable - -[maintenance-operations] -# Baseline audit: -# just maint-audit -# Hard release gate: -# just maint-hard-pass -# Permission audit: -# just perms-audit - -[rsr-repo-skeleton] -# Canonical organisation of any RSR-derived repository. -# Used by tooling, human onboarding, and the scheduled downstream sweep agent. -# The 5-PR cleanup pattern (below) brings a non-conforming repository into -# compliance with this skeleton. -# -# This section is the single source of truth for "what does an RSR repo look -# like?". Other docs (TOPOLOGY, AUDIT, etc.) describe the repo at hand; -# this describes the canonical shape that all RSR repos share. - -skeleton-version = "1.0" -last-updated = "2026-04-30" -authority-allowlist = ".machine_readable/root-allow.txt" -enforcement-workflow = ".github/workflows/estate-rules.yml" - -# === Required at root === -# README.adoc High-level pitch (project entry point) -# AUDIT.adoc Local gate summary (release-readiness) -# EXPLAINME.adoc Developer deep-dive (architecture & invariants) -# 0-AI-MANIFEST.a2ml AI agent work-allocation policy -# LICENSE Repo license (root-bound by convention) -# CHANGELOG.md One of the recognised .md exceptions (see below) -# Justfile Task runner — thin, imports per-section files from build/just/ -# coordination.k9 Repo-local session binding - -# === Required directories === -# .github/ CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, workflows/ -# .machine_readable/ AI manifests (0.1-AI-MANIFEST.a2ml), 6a2/ checkpoints, -# contractiles/, configs/, anchors/, policies/, scripts/, svc/ -# build/ contractile.just, flake.nix, guix.scm, Containerfile, -# just/*.just (Justfile section imports) -# docs/ onboarding/, status/, architecture/, governance/ (all .adoc) -# session/ dispatch.sh, custom-checks.k9, local-hooks.sh -# src/ Project source (Idris2 ABI under abi/, Zig FFI under ffi/) -# tests/, benches/, examples/, features/, scripts/, verification/, container/ - -# === Documentation format rule === -# `.adoc` is the default for all general docs (TOPOLOGY, READINESS, ROADMAP, -# TEST-NEEDS, PROOF-NEEDS, PROOF-STATUS, llm-warmup-*, etc.). -# -# `.md` is reserved ONLY for files GitHub's community-health rules -# special-case by name: -# CONTRIBUTING.md CODE_OF_CONDUCT.md SECURITY.md CHANGELOG.md -# -# Enforcement: `scripts/check-no-md-in-docs.sh` (fails if any *.md under docs/). - -# === Banned: ziguage === -# V (vlang.io) is banned estate-wide. Replaced by `zig-unified-api-adapter` -# (16 endpoints + transaction-based firewall gating). Do not introduce -# zig code, scaffolders, or references. Note that Coq theorem files use -# the same `.v` extension and are unaffected — the rule looks at content -# patterns, not the extension. -# -# Enforcement: `scripts/check-no-vlang.sh`. - -# === Justfile structure (post-split) === -# The root Justfile is thin — it holds `set` directives, project metadata -# variables, and the `default`/`help`/`info` recipes. Each major section -# lives in its own file under build/just/ and is brought in via `import?`. -# -# Imported sections (in the canonical split): -# build/just/init.just INIT recipe (template bootstrap) -# build/just/assess.just self-assess + verify (OpenSSF compliance) -# build/just/validate.just validate-rsr/state/ai-install + aggregate -# build/just/proofs.just proof-check-{all,idris2,lean4,agda,coq}, -# proof-scan-dangerous, proof-status -# build/just/groove.just Groove protocol setup (after zig removed) -# -# Daily-use recipes (BUILD, TEST, LINT, RUN, DEPS, DOCS, CONTAINER, CI, -# SECURITY, STATE, GUIX/NIX, MATRIX, VERSION CONTROL, UTILITIES, SESSION) -# stay in the root Justfile where users expect to find them. - -# === 5-PR cleanup pattern === -# Apply these branches (in order) to bring a non-conforming downstream repo -# into compliance with this skeleton: -# -# 1. chore/root-cleanup Relocate root sprawl per root-allow.txt; add -# scripts/check-root-shape.sh; remove stub -# health files shadowed by .github/ versions. -# 2. chore/remove-zig Purge zig remnants (gen-v-connector recipe, -# "V-TRIPLE" section header, "V-triple -# connectors" comment in groove.a2ml). -# 3. chore/md-to-adoc Port general docs in docs/ from .md to .adoc; -# update validate-template.sh to accept .adoc -# fallbacks. -# 4. chore/estate-rules-ci Add scripts/check-no-md-in-docs.sh + check-no- -# vlang.sh + .github/workflows/estate-rules.yml. -# 5. chore/-hygiene Repo-specific drift cleanup (case collisions, -# template-derivation drift in titles, etc.). - -# === Reference scripts === -# scripts/check-root-shape.sh Root allowlist validator -# scripts/check-no-md-in-docs.sh AsciiDoc-by-default validator -# scripts/check-no-vlang.sh zig ban validator -# scripts/validate-template.sh Aggregate RSR compliance (workflows, SPDX, etc.) - -# === Reference memory entries (for AI agents) === -# feedback_adoc_default_md_for_githealth AsciiDoc-by-default rule -# feedback_v_lang_banned zig ban -# project_zig_unified_api Replacement for v-triple/zig -# feedback_gh_workflow_scope OAuth scope for workflow files diff --git a/.machine_readable/6a2/README.adoc b/.machine_readable/6a2/README.adoc deleted file mode 100644 index bc033d7..0000000 --- a/.machine_readable/6a2/README.adoc +++ /dev/null @@ -1,30 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -# A2ML 6a2 Directory - -This directory contains the 6 core A2ML machine-readable metadata files for this repository. - -## Files - -- `AGENTIC.a2ml` - AI agent operational gating, safety controls -- `ECOSYSTEM.a2ml` - Project ecosystem position, relationships, explicit boundaries -- `META.a2ml` - Architecture decisions (ADRs), development practices, design rationale -- `NEUROSYM.a2ml` - Symbolic semantics, composition algebra -- `PLAYBOOK.a2ml` - Executable plans, operational runbooks -- `STATE.a2ml` - Project state, phase, milestones, session history - -## Standards Compliance - -These files follow the A2ML Format Family specification from: -https://github.com/hyperpolymath/standards/tree/main/a2ml - -## Generation - -These files may be generated from .scm source files using transpilation tools. -Source .scm files should be removed after successful transpilation. - -## See Also - -- [A2ML Repository Template](https://github.com/hyperpolymath/standards/blob/main/A2ML-REPO-TEMPLATE.adoc) -- [6A2 Format Family](https://github.com/hyperpolymath/standards#a2ml-format-family-7-formats) - diff --git a/.machine_readable/6a2/STATE.a2ml b/.machine_readable/6a2/STATE.a2ml deleted file mode 100644 index a76d8dd..0000000 --- a/.machine_readable/6a2/STATE.a2ml +++ /dev/null @@ -1,64 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# STATE.a2ml — Project state checkpoint (META-TEMPLATE) -# -# This is the STATE file for rsr-template-repo itself. -# When consumed by a new project, replace {{PLACEHOLDER}} tokens -# and customize sections below for the target project. - -[metadata] -project = "rsr-template-repo" -version = "0.2.0" -last-updated = "2026-02-28" -status = "active" # active | paused | archived - -[project-context] -name = "rsr-template-repo" -purpose = "Canonical RSR-compliant repository template providing scaffolding for all hyperpolymath projects — including CI/CD, AI manifests, ABI/FFI standards, container ecosystem, and governance infrastructure." -completion-percentage = 95 - -[position] -phase = "maintenance" # design | implementation | testing | maintenance | archived -maturity = "production" # experimental | alpha | beta | production | lts - -[route-to-mvp] -milestones = [ - { name = "Phase 0: Core scaffolding (justfile, CI/CD, .machine_readable)", completion = 100 }, - { name = "Phase 1: ABI/FFI standard (Idris2/Zig templates)", completion = 100 }, - { name = "Phase 1b: AI Gatekeeper Protocol (0-AI-MANIFEST.a2ml)", completion = 100 }, - { name = "Phase 1c: TOPOLOGY.md standard and guide", completion = 100 }, - { name = "Phase 1d: Maintenance gate (axes, checklist, approach)", completion = 100 }, - { name = "Phase 1e: Trustfile / contractiles", completion = 100 }, - { name = "Phase 2: Container ecosystem templates (stapeln)", completion = 100 }, - { name = "Phase 3: Multi-forge sync hardening", completion = 0 }, - { name = "Phase 4: Nix/Guix reproducible shells", completion = 50 }, -] - -[blockers-and-issues] -# No active blockers - -[critical-next-actions] -actions = [ - "Container templates complete — test with `just container-init`", - "Validate container templates across wolfi-base and static Chainguard images", - "Harden multi-forge sync for GitLab/Bitbucket mirroring edge cases", - "Expand Nix/Guix development shell templates", -] - -[maintenance-status] -last-run-utc = "never" -last-report = "docs/reports/maintenance/latest.json" -last-result = "unknown" # unknown | pass | warn | fail -open-warnings = 0 -open-failures = 0 - -[ecosystem] -part-of = ["RSR Framework", "stapeln ecosystem"] -depends-on = ["stapeln", "selur-compose", "cerro-torre", "svalinn", "vordr", "k9-svc"] - -# --------------------------------------------------------------------------- -# NOTE FOR CONSUMERS: When using this template to create a new repo, reset -# the fields above to your project's values and replace all {{PLACEHOLDER}} -# tokens. The milestones above describe the TEMPLATE's evolution, not yours. -# --------------------------------------------------------------------------- diff --git a/.machine_readable/6a2/anchors/0-AI-MANIFEST.a2ml b/.machine_readable/6a2/anchors/0-AI-MANIFEST.a2ml deleted file mode 100644 index 0dd6825..0000000 --- a/.machine_readable/6a2/anchors/0-AI-MANIFEST.a2ml +++ /dev/null @@ -1,21 +0,0 @@ -# AI Manifest for Anchor Directory - -## Purpose - -This manifest declares the AI-assistant context for the anchor machine-readable metadata directory. - -## Canonical Locations - -ANCHOR.a2ml files MUST exist in this directory. - -## Multiple Versions - -Unlike other A2ML files, multiple versions of ANCHOR.a2ml with different dates MAY exist. -Each version represents a specific recalibration point. - -## Invariants - -- Multiple versions with different dates are permitted -- No other A2ML files in this directory -- Single source of truth for anchor documents - diff --git a/.machine_readable/6a2/anchors/ANCHOR.a2ml b/.machine_readable/6a2/anchors/ANCHOR.a2ml deleted file mode 100644 index 8723899..0000000 --- a/.machine_readable/6a2/anchors/ANCHOR.a2ml +++ /dev/null @@ -1,62 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -# -# ANCHOR.a2ml - authoritative anchor for this repository - -[metadata] -version = "1.0.0" -last-updated = "{{CURRENT_DATE}}" - -[anchor] -schema = "hyperpolymath.anchor/1" -repo = "{{OWNER}}/{{REPO}}" -authority = "upstream-canonical" - -purpose = [ - "Define canonical semantics and policy boundaries for this repository.", - "Declare what downstream/satellite repos can extend but not redefine.", - "Provide a stable golden path and invariant contract for release readiness.", -] - -[identity] -project = "{{PROJECT_NAME}}" -kind = "{{PROJECT_KIND}}" # language | library | service | tool -one-sentence = "{{PROJECT_PURPOSE}}" -domain = "{{PROJECT_DOMAIN}}" - -[semantic-authority] -policy = "canonical" - -owns = [ - "Project semantics and specification", - "Invariant definitions and contractiles", - "Reference implementation behavior", -] - -[implementation-policy] -allowed = ["Rust", "Idris2", "Zig", "Scheme", "Shell", "Just", "AsciiDoc", "Markdown"] -forbidden = ["Node.js", "npm"] - -[golden-path] -smoke-test-command = [ - "just test", - "just quality", -] - -success-criteria = [ - "Core tests pass", - "Quality gates pass", - "No unresolved critical security findings", -] - -[satellite-policy] -must-pin-upstream = true -must-declare-authority = true -must-have-anchor = true -must-have-golden-path = true - -[semantic-authority-files] -language-spec = "SPECIFICATION.md" -formal-proofs = "docs/proofs/PROOFS.adoc" -type-theory = "docs/theory/THEORY.adoc" -algorithms = "docs/theory/ALGORITHMS.adoc" diff --git a/.machine_readable/6a2/anchors/README.adoc b/.machine_readable/6a2/anchors/README.adoc deleted file mode 100644 index bd23e35..0000000 --- a/.machine_readable/6a2/anchors/README.adoc +++ /dev/null @@ -1,25 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -# A2ML Anchor Directory - -This directory contains ANCHOR.a2ml files for project recalibration and scope intervention. - -## Files - -- `ANCHOR.a2ml` - Project recalibration, scope intervention, canonical authority - -## Multiple Versions - -Unlike other A2ML files, multiple versions of ANCHOR.a2ml with different dates may exist. -Each version represents a specific recalibration point in the project history. - -## Standards Compliance - -These files follow the ANCHOR.a2ml specification from: -https://github.com/hyperpolymath/standards/tree/main/anchor-a2ml - -## See Also - -- [A2ML Repository Template](https://github.com/hyperpolymath/standards/blob/main/A2ML-REPO-TEMPLATE.adoc) -- [Anchor A2ML Spec](https://github.com/hyperpolymath/standards/tree/main/anchor-a2ml) - diff --git a/.machine_readable/ENSAID_CONFIG.a2ml b/.machine_readable/ENSAID_CONFIG.a2ml deleted file mode 100644 index 1384822..0000000 --- a/.machine_readable/ENSAID_CONFIG.a2ml +++ /dev/null @@ -1,96 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -# -# ENSAID_CONFIG.a2ml — eNSAID Environment Configuration -# Per-repo configuration for PanLL and eNSAID-compatible tools. -# -# Canonical location: .machine_readable/ENSAID_CONFIG.a2ml -# Spec: https://github.com/hyperpolymath/standards/tree/main/ensaid-config -# -# Naming convention: -# - UPPERCASE + underscore = non-executable machine-readable file -# - Lives in .machine_readable/ alongside STATE.a2ml, META.a2ml, etc. - -# ───────────────────────────────────────────────────────────────── -# [ensaid] — Core eNSAID identity and version -# ───────────────────────────────────────────────────────────────── -[ensaid] -version = "1.0.0" -tool = "panll" - -# ───────────────────────────────────────────────────────────────── -# [workspace] — Workspace mode, protection, and execution policy -# ───────────────────────────────────────────────────────────────── -[workspace] -mode = "rhodium" # rhodium | gold | silver | bronze -protection = "open" # open | guarded | locked -execution = "live" # live | dry-run | approval-required - -# ───────────────────────────────────────────────────────────────── -# [preferences] — User/repo-level display and behaviour preferences -# ───────────────────────────────────────────────────────────────── -[preferences] -humidity = "medium" # high | medium | low (drift aura intensity) -default-arrangement = "default-3-panel" # workspace arrangement ID -auto-connect = true # auto-connect panels to backends on load - -# ───────────────────────────────────────────────────────────────── -# [panels] — Panel visibility, enablement, and isolation overrides -# ───────────────────────────────────────────────────────────────── -[panels] -version = "1.0.0" - -# By default, all panels are available. Uncomment to restrict: -# [[panels.enabled]] -# id = "valence-shell" -# isolation = "native" -# auto-connect = true -# -# [[panels.enabled]] -# id = "editor-bridge" -# isolation = "native" -# auto-connect = true - -# Panels to hide for this repo context: -# [panels.disabled] -# ids = [] - -# ───────────────────────────────────────────────────────────────── -# [workflows] — Automation Router event-driven cross-panel rules -# ───────────────────────────────────────────────────────────────── -[workflows] -version = "1.0.0" - -# Example: rebuild on file save -# [[workflows.rule]] -# name = "build-on-save" -# trigger = { event = "file-changed", pattern = "src/**/*.res" } -# condition = { panel = "build-dashboard", field = "watchMode", equals = true } -# action = { panel = "build-dashboard", message = "TriggerBuild", args = { target = "game" } } -# approval = "auto-fire" # auto-fire | require-approval | approve-once | dry-run-first - -# ───────────────────────────────────────────────────────────────── -# [clades] — Panel clade trait and capability overrides -# ───────────────────────────────────────────────────────────────── -[clades] -version = "1.0.0" - -# Example: add a custom capability to a panel clade -# [[clades.override]] -# id = "build-dashboard" -# traits = { has-work-items = true } -# capabilities-add = ["CustomCheck"] - -# ───────────────────────────────────────────────────────────────── -# [portfolios] — Custom panel bundles for this repo's workflow -# ───────────────────────────────────────────────────────────────── -[portfolios] -version = "1.0.0" - -# Example: a custom portfolio for this project -# [[portfolios.custom]] -# id = "{{project}}-dev" -# name = "{{PROJECT_NAME}} Development" -# description = "Panels for {{PROJECT_NAME}} development" -# panels = ["valence-shell", "editor-bridge", "build-dashboard"] -# default-isolation = "native" diff --git a/.machine_readable/README.adoc b/.machine_readable/README.adoc deleted file mode 100644 index e72996d..0000000 --- a/.machine_readable/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= .machine_readable Pillar diff --git a/.machine_readable/ai/.clinerules b/.machine_readable/ai/.clinerules deleted file mode 100644 index 8f38042..0000000 --- a/.machine_readable/ai/.clinerules +++ /dev/null @@ -1,43 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -# Authoritative source: docs/AI-CONVENTIONS.md - -# STARTUP: Read 0-AI-MANIFEST.a2ml first, then .machine_readable/6a2/STATE.a2ml. - -# LICENSE -# All original code: MPL-2.0. -# Never AGPL-3.0. MPL-2.0 only as platform-required fallback. -# SPDX header required on every source file. -# Copyright: {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> - -# STATE FILES (.machine_readable/ ONLY) -# Never create in repo root: STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml, -# AGENTIC.a2ml, NEUROSYM.a2ml, PLAYBOOK.a2ml. -# The .machine_readable/ directory is the single source of truth. - -# BANNED PATTERNS -# Idris2: believe_me, assert_total, assert_smaller, unsafePerformIO -# Haskell: unsafeCoerce, unsafePerformIO, undefined, error -# OCaml: Obj.magic, Obj.repr, Obj.obj -# Coq: Admitted -# Lean: sorry -# Rust: transmute (unless FFI with // SAFETY: comment) - -# BANNED LANGUAGES -# TypeScript -> ReScript -# Node.js / npm / bun -> Deno -# Go -> Rust -# Python -> Julia or Rust - -# CONTAINERS -# Runtime: Podman (never Docker). -# File: Containerfile (never Dockerfile). -# Base: cgr.dev/chainguard/wolfi-base:latest or cgr.dev/chainguard/static:latest. - -# ABI/FFI -# ABI: Idris2 with dependent types (src/interface/abi/). -# FFI: Zig with C ABI (src/interface/ffi/). -# Headers: src/interface/generated/. - -# BUILD: Use just (justfile) for all tasks. -# STYLE: Descriptive names. Document all files. SPDX headers everywhere. diff --git a/.machine_readable/ai/.cursorrules b/.machine_readable/ai/.cursorrules deleted file mode 100644 index c13b393..0000000 --- a/.machine_readable/ai/.cursorrules +++ /dev/null @@ -1,47 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -# Authoritative source: docs/AI-CONVENTIONS.md - -# Read 0-AI-MANIFEST.a2ml in the repo root FIRST for canonical file locations. - -# LICENSE -# All original code: MPL-2.0 (SPDX header required on every file). -# Never use AGPL-3.0. Fallback to MPL-2.0 only when platform requires it. -# Copyright: {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> - -# STATE FILES -# .a2ml metadata files go in .machine_readable/ ONLY. -# Never create STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml, AGENTIC.a2ml, -# NEUROSYM.a2ml, or PLAYBOOK.a2ml in the repository root. - -# BANNED PATTERNS -# Idris2: believe_me, assert_total, assert_smaller, unsafePerformIO -# Haskell: unsafeCoerce, unsafePerformIO, undefined, error -# OCaml: Obj.magic, Obj.repr, Obj.obj -# Coq: Admitted -# Lean: sorry -# Rust: transmute (unless FFI with // SAFETY: comment) - -# BANNED LANGUAGES -# TypeScript -> use ReScript -# Node.js / npm / bun -> use Deno -# Go -> use Rust -# Python -> use Julia or Rust - -# CONTAINERS -# Runtime: Podman (never Docker) -# File: Containerfile (never Dockerfile) -# Base: cgr.dev/chainguard/wolfi-base:latest - -# ABI/FFI STANDARD -# ABI definitions: Idris2 with dependent types (src/interface/abi/) -# FFI implementation: Zig with C ABI (src/interface/ffi/) -# Generated C headers: src/interface/generated/ - -# BUILD SYSTEM -# Use just (justfile) for all build, test, lint, and format tasks. - -# CODE STYLE -# Use descriptive variable names. -# Annotate and document all files. -# Add SPDX-License-Identifier header to every source file. diff --git a/.machine_readable/ai/.windsurfrules b/.machine_readable/ai/.windsurfrules deleted file mode 100644 index 8f38042..0000000 --- a/.machine_readable/ai/.windsurfrules +++ /dev/null @@ -1,43 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -# Authoritative source: docs/AI-CONVENTIONS.md - -# STARTUP: Read 0-AI-MANIFEST.a2ml first, then .machine_readable/6a2/STATE.a2ml. - -# LICENSE -# All original code: MPL-2.0. -# Never AGPL-3.0. MPL-2.0 only as platform-required fallback. -# SPDX header required on every source file. -# Copyright: {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> - -# STATE FILES (.machine_readable/ ONLY) -# Never create in repo root: STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml, -# AGENTIC.a2ml, NEUROSYM.a2ml, PLAYBOOK.a2ml. -# The .machine_readable/ directory is the single source of truth. - -# BANNED PATTERNS -# Idris2: believe_me, assert_total, assert_smaller, unsafePerformIO -# Haskell: unsafeCoerce, unsafePerformIO, undefined, error -# OCaml: Obj.magic, Obj.repr, Obj.obj -# Coq: Admitted -# Lean: sorry -# Rust: transmute (unless FFI with // SAFETY: comment) - -# BANNED LANGUAGES -# TypeScript -> ReScript -# Node.js / npm / bun -> Deno -# Go -> Rust -# Python -> Julia or Rust - -# CONTAINERS -# Runtime: Podman (never Docker). -# File: Containerfile (never Dockerfile). -# Base: cgr.dev/chainguard/wolfi-base:latest or cgr.dev/chainguard/static:latest. - -# ABI/FFI -# ABI: Idris2 with dependent types (src/interface/abi/). -# FFI: Zig with C ABI (src/interface/ffi/). -# Headers: src/interface/generated/. - -# BUILD: Use just (justfile) for all tasks. -# STYLE: Descriptive names. Document all files. SPDX headers everywhere. diff --git a/.machine_readable/ai/0.2-AI-MANIFEST.a2ml b/.machine_readable/ai/0.2-AI-MANIFEST.a2ml deleted file mode 100644 index 869cbee..0000000 --- a/.machine_readable/ai/0.2-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "ai-registry" -level: 2 -parent: "../0.1-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Sub-registry for ai metadata. diff --git a/.machine_readable/ai/AI.a2ml b/.machine_readable/ai/AI.a2ml deleted file mode 100644 index 3754aca..0000000 --- a/.machine_readable/ai/AI.a2ml +++ /dev/null @@ -1,37 +0,0 @@ - -# AI Assistant Instructions - -## Repository Focus -- `rsr-template-repo` is treated as a Rhodium Standard Repository; obey the Rhodium policies and keep `.machine_readable/` authoritative. -- All machine-readable content lives under `.machine_readable/` — state files (a2ml), bot directives, and contractiles. -- Prefer to keep generated files out of source control, and regenerate them with the documented commands before committing. - -## Workflow -1. Inspect `.machine_readable/6a2/STATE.a2ml` for blockers and next actions. -2. Respect any constraints listed inside `.machine_readable/6a2/AGENTIC.a2ml` when tooling changes are requested. -3. After finishing edits, update STATE with your outcomes and commit with a concise, imperative message. - -## Delivery Promises -- Mention in summaries whether STATE, `.machine_readable/contractiles/`, or `.machine_readable/bot_directives/` changed. -- Keep this file in sync with the repository's status; update it if the governance changes. - -[foundational-integrations] -# These tools form the architectural floor for all hyperpolymath repos. -# Integrate them incrementally as the project matures. - -proven = "Formally verified safety library — replace raw string/JSON/URL/crypto ops" -panic-attacker = "Static analysis — run `just assail` before every commit" -feedback-o-tron = "Autonomous bug filing — auto-report upstream dependency failures" -verisimdb = "Cross-repo analytics — emit scan results and build metrics" -vexometer = "Irritation surface analysis — measure friction in CLI/UI tools" -hypatia = "Neurosymbolic CI/CD — safety-triangle routing for automated fixes" -boj-server = "MCP gateway — all external service integrations route through BoJ" - -[floor-raise-checklist] -step-1 = "Ensure 0-AI-MANIFEST.a2ml exists at repo root" -step-2 = "Ensure Mustfile.a2ml + Trustfile.a2ml + Dustfile.a2ml in .machine_readable/contractiles/" -step-3 = "Add `assail` recipe to Justfile and wire into pre-commit hook" -step-4 = "Add proven integration reference in .machine_readable/integrations/" -step-5 = "Add verisimdb feed configuration" -step-6 = "Add feedback-o-tron integration for upstream reporting" -step-7 = "Add vexometer hooks for friction measurement (CLI/UI repos)" diff --git a/.machine_readable/ai/PLACEHOLDERS.adoc b/.machine_readable/ai/PLACEHOLDERS.adoc deleted file mode 100644 index b7073b6..0000000 --- a/.machine_readable/ai/PLACEHOLDERS.adoc +++ /dev/null @@ -1,144 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Template Placeholders -# Template Placeholders - -All placeholders in this template follow the `{{PLACEHOLDER}}` pattern. -After cloning, replace them with your project-specific values. - -## Recommended: Interactive Bootstrap - -```bash -just init -``` - -This interactively prompts for all values, replaces every placeholder, -validates the result, and runs k9-svc checks if available. - -## Manual Replace - -```bash -# If you prefer manual replacement (run from repo root) - -sed -i 's/{{AUTHOR}}/Jane Doe/g' $(grep -rl '{{AUTHOR}}' .) -sed -i 's/{{AUTHOR_EMAIL}}/jane@example.org/g' $(grep -rl '{{AUTHOR_EMAIL}}' .) -sed -i 's/{{OWNER}}/my-org/g' $(grep -rl '{{OWNER}}' .) -sed -i 's/{{PROJECT_NAME}}/my-project/g' $(grep -rl '{{PROJECT_NAME}}' .) -sed -i 's/{{PROJECT}}/MY_PROJECT/g' $(grep -rl '{{PROJECT}}' .) -sed -i 's/{{project}}/my_project/g' $(grep -rl '{{project}}' .) -sed -i 's/{{REPO}}/my-project/g' $(grep -rl '{{REPO}}' .) -sed -i 's/{{FORGE}}/github.com/g' $(grep -rl '{{FORGE}}' .) -sed -i "s/{{CURRENT_YEAR}}/$(date +%Y)/g" $(grep -rl '{{CURRENT_YEAR}}' .) -sed -i "s/{{CURRENT_DATE}}/$(date +%Y-%m-%d)/g" $(grep -rl '{{CURRENT_DATE}}' .) -``` - -## Placeholder Reference - -### Author & Copyright - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{AUTHOR}}` | Full legal name | `Jane Doe` | SPDX headers (all files), MAINTAINERS.md, .mailmap, .reuse/dep5, docs/AI-CONVENTIONS.md | -| `{{AUTHOR_EMAIL}}` | Primary contact email | `jane@example.org` | SPDX headers (all files), .mailmap, .reuse/dep5, .well-known/humans.txt | -| `{{AUTHOR_EMAIL_ALT}}` | Previous/secondary email (for .mailmap) | `old@example.com` | .mailmap | -| `{{AUTHOR_ORG}}` | Author's organization/affiliation | `Acme University` | project-metadata.k9.ncl | -| `{{AUTHOR_LAST}}` | Author surname (for citations) | `Doe` | docs/CITATIONS.adoc | -| `{{AUTHOR_FIRST}}` | Author first name (for citations) | `Jane` | docs/CITATIONS.adoc | -| `{{AUTHOR_INITIALS}}` | Author initials (for citations) | `J.` | docs/CITATIONS.adoc | - -### Project Identity - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{PROJECT_NAME}}` | Human-readable project name | `My Project` | SECURITY.md, CODE_OF_CONDUCT.md, TOPOLOGY.md, STATE.a2ml, Justfile, GOVERNANCE.md, MAINTAINERS.md, flake.nix, devcontainer.json | -| `{{PROJECT_DESCRIPTION}}` | One-line description | `A tool for X` | flake.nix | -| `{{PROJECT}}` | Uppercase identifier (for Idris2 modules, C macros) | `MY_PROJECT` | ABI-FFI-README.md, src/interface/abi/*.idr, src/interface/ffi/*.zig | -| `{{project}}` | Lowercase identifier (for C symbols, filenames) | `my_project` | ABI-FFI-README.md, src/interface/ffi/*.zig | -| `{{REPO}}` | Repository name (slug) | `my-project` | CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md, cliff.toml | -| `{{OWNER}}` | GitHub/GitLab org or username | `my-org` | SPDX headers, CONTRIBUTING.md, SECURITY.md, GOVERNANCE.md, MAINTAINERS.md, CODEOWNERS, mirror.yml, cliff.toml | -| `{{FORGE}}` | Git forge domain | `github.com` | CONTRIBUTING.md | - -### Dates - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{CURRENT_YEAR}}` | Current year | `2026` | SPDX headers (all files), GOVERNANCE.md, MAINTAINERS.md | -| `{{CURRENT_DATE}}` | Current date (ISO) | `2026-02-14` | STATE.a2ml, MAINTAINERS.md | -| `{{DATE}}` | Last updated date | `2026-02-14` | TOPOLOGY.md, THREAT-MODEL.md | - -### Contact & Security - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{SECURITY_EMAIL}}` | Security contact email | `security@example.org` | SECURITY.md | -| `{{PGP_FINGERPRINT}}` | 40-char PGP fingerprint | `ABCD 1234 ...` | SECURITY.md | -| `{{PGP_KEY_URL}}` | URL to public PGP key | `https://keys.openpgp.org/...` | SECURITY.md | -| `{{WEBSITE}}` | Project website | `https://example.org` | SECURITY.md | -| `{{CONDUCT_EMAIL}}` | Conduct reports email | `conduct@example.org` | CODE_OF_CONDUCT.md | -| `{{CONDUCT_TEAM}}` | Conduct committee name | `Code of Conduct Committee` | CODE_OF_CONDUCT.md | -| `{{RESPONSE_TIME}}` | SLA for initial response | `48 hours` | CODE_OF_CONDUCT.md | - -### Git - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{MAIN_BRANCH}}` | Main branch name | `main` | CONTRIBUTING.md | - -### Build - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{LICENSE}}` | License name | `MPL-2.0` | ABI-FFI-README.md | -| `{{PROJECT_PURPOSE}}` | One-line project description | `FFI bridges between languages` | STATE.a2ml | - -### AI Manifest - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `[YOUR-REPO-NAME]` | Repository name | `my-project` | 0-AI-MANIFEST.a2ml | -| `[DATE]` | Creation date | `2026-02-14` | 0-AI-MANIFEST.a2ml | -| `[YOUR-NAME/ORG]` | Maintainer name | `hyperpolymath` | 0-AI-MANIFEST.a2ml | - -### AI Installation Guide - -| Marker | Description | Files | -|---|---|---| -| `[TODO-AI-INSTALL]` | Unfilled section in AI installation guide | `docs/AI_INSTALLATION_GUIDE.adoc`, `docs/AI-INSTALL-README-SECTION.adoc`, `README.adoc` | - -These are **not** standard `{{PLACEHOLDER}}` markers -- they are TODO markers -that must be replaced with project-specific content before release. They mark -sections where the developer (or AI) must fill in: - -- What questions the AI should ask the user -- Exact prerequisite check and install commands -- Privacy notice specific to this project -- Complete installation command block -- Credential setup instructions (URLs, scopes, env vars) -- Verification commands and expected output -- Error handling table -- Example conversation - -**finishbot checks:** `just validate-ai-install` verifies no `[TODO-AI-INSTALL]` markers remain. - -## Deletion Markers - -Some files contain deletion instructions: - -| Marker | Meaning | File | -|---|---|---| -| `{{~ ... ~}}` | Delete this entire line after reading | ABI-FFI-README.md (line 1) | - -## Verification - -After replacing all placeholders, verify none remain: - -```bash -grep -rn '{{' . --include='*.md' --include='*.adoc' --include='*.a2ml' \ - --include='*.scm' --include='*.idr' --include='*.zig' --include='*.res' \ - --include='Justfile' --include='*.nix' --include='*.toml' --include='*.yml' \ - --include='*.yaml' --include='*.hs' --include='*.ncl' --include='*.txt' \ - --include='*.json' --include='Containerfile' --include='dep5' \ - | grep -v 'PLACEHOLDERS.md' | grep -v 'node_modules' -``` - -If the above command produces no output, all placeholders have been replaced. diff --git a/.machine_readable/ai/README.adoc b/.machine_readable/ai/README.adoc deleted file mode 100644 index 7f1a182..0000000 --- a/.machine_readable/ai/README.adoc +++ /dev/null @@ -1,24 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= AI Guidance Directory - -Put AI-facing instructions in this folder. - -Examples: - -* `CLAUDE.md` -* `COPILOT.md` -* `GEMINI.md` -* `AI.a2ml` -* `AI.djot` - -Avoid scattering agent instruction files around the repo root. - -Recommended machine read order: - -* `.machine_readable/6a2/anchors/ANCHOR.a2ml` -* `.machine_readable/policies/MAINTENANCE-AXES.a2ml` -* `.machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml` -* `.machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml` -* `.machine_readable/6a2/STATE.a2ml` -* `.machine_readable/6a2/META.a2ml` diff --git a/.machine_readable/bot_directives/README.adoc b/.machine_readable/bot_directives/README.adoc deleted file mode 100644 index a5315c7..0000000 --- a/.machine_readable/bot_directives/README.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Agent Instructions -:toc: preamble - -Methodology-aware configuration for AI agents. Read by any AI agent -(Claude, Gemini, Copilot, etc.) at session start. - -== Files - -[cols="1,3"] -|=== -| File | Purpose - -| `methodology.a2ml` -| Default mode, invariants, ring ceiling, priority weights, convergent budget - -| `coverage.a2ml` -| Session coverage tracking — what was visited, what was skipped, what has MUSTs - -| `debt.a2ml` -| Meander debt — things found but not fixed, carried between sessions -|=== - -== How Agents Use These - -1. Read `methodology.a2ml` at session start — know mode, invariants, ceiling -2. Read `coverage.a2ml` — know what was visited last time, what was skipped -3. Read `debt.a2ml` — know what's outstanding from previous sessions -4. At session end, update `coverage.a2ml` and `debt.a2ml` - -== Relationship to Other Files - -* `AGENTIC.a2ml` says WHAT agents can do (permissions, gating) -* `bot_directives/` says HOW agents should work (methodology) -* `bot_directives/` says what the gitbot-fleet does (fleet-specific) -* `CLAUDE.md` says how Claude specifically should work (Claude-specific) - -== Reference - -ADR-002 in `standards/agentic-a2ml/docs/ADR-002-methodology-layer.adoc` diff --git a/.machine_readable/bot_directives/coverage.a2ml b/.machine_readable/bot_directives/coverage.a2ml deleted file mode 100644 index 1bd30fa..0000000 --- a/.machine_readable/bot_directives/coverage.a2ml +++ /dev/null @@ -1,61 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -# -# coverage.a2ml — Session coverage tracking -# Updated at the end of each AI agent session. -# Persists what was visited, what was skipped, and what has MUSTs. -# -# Reference: ADR-002 in standards/agentic-a2ml/docs/ - -[metadata] -version = "1.0.0" -last-updated = "{{CURRENT_DATE}}" - -# ============================================================================ -# COVERAGE STATE -# ============================================================================ -# Updated by agents at session end. Tracks which components have been -# visited and which have known MUSTs that were skipped. - -[coverage] -total-components = 0 -visited-components = 0 -coverage-percent = 0 - -# ============================================================================ -# VISITED COMPONENTS -# ============================================================================ -# Component → session date + ring reached -# Agents add entries as they work through components. -# -# Example: -# [coverage.visited.emergency-room] -# date = "2026-03-23" -# ring = 2 -# fixes = 3 -# notes = "boot-guardian built, shutdown-marshal built" - -# ============================================================================ -# SKIPPED COMPONENTS WITH MUSTS -# ============================================================================ -# Components with known MUSTs that were not visited in the most recent session. -# These become P1 inputs for the next session's Phase 0. -# -# Example: -# [coverage.skipped-musts.session-sentinel] -# priority = "P0" -# issue = "56 SIGABRTs in 4 days, D-Bus race condition" -# discovered = "2026-03-23" - -# ============================================================================ -# CHERRY-PICKING AUDIT -# ============================================================================ -# At session end, agents report whether they chose easy work over hard work. -# This is the accountability mechanism for the weighted priority system. -# -# [coverage.cherry-picking] -# easy-high-completed = 3 -# hard-high-completed = 1 -# easy-low-completed = 2 -# hard-low-deferred = 4 -# assessment = "Correctly prioritised — all MUST items addressed before COULDs" diff --git a/.machine_readable/bot_directives/debt.a2ml b/.machine_readable/bot_directives/debt.a2ml deleted file mode 100644 index 3289cbe..0000000 --- a/.machine_readable/bot_directives/debt.a2ml +++ /dev/null @@ -1,49 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -# -# debt.a2ml — Meander debt list -# Things found but not fixed. Carried between sessions. -# Becomes the next session's Phase 0 input. -# -# Reference: ADR-002 in standards/agentic-a2ml/docs/ - -[metadata] -version = "1.0.0" -last-updated = "{{CURRENT_DATE}}" - -# ============================================================================ -# DEBT ITEMS -# ============================================================================ -# Each item has: component, issue, effort (easy|medium|hard), impact (high|medium|low), -# priority (should|could), and discovered date. -# -# Items are consumed (removed) when fixed. New items are added at session end. -# The debt list prevents the "one more wave" loop — found things are persisted, -# not forgotten, and not used as justification for infinite meandering. - -# ============================================================================ -# SHOULD — would fix next wave -# ============================================================================ -# These are inputs for the next session if the user says "keep going". -# -# Example: -# [[debt.should]] -# component = "system-tools/monitoring/observatory" -# issue = "Stale duplicate of root observatory/" -# effort = "easy" -# impact = "medium" -# discovered = "2026-03-23" - -# ============================================================================ -# COULD — would fix eventually -# ============================================================================ -# These are low-priority items that don't justify a session on their own. -# They get picked up when an agent is in the area for other reasons. -# -# Example: -# [[debt.could]] -# component = "cicada" -# issue = "RSR_OUTLINE.adoc references banned AGPL-3.0" -# effort = "easy" -# impact = "low" -# discovered = "2026-03-23" diff --git a/.machine_readable/bot_directives/methodology.a2ml b/.machine_readable/bot_directives/methodology.a2ml deleted file mode 100644 index a88ab49..0000000 --- a/.machine_readable/bot_directives/methodology.a2ml +++ /dev/null @@ -1,107 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -# -# methodology.a2ml — AI agent methodology configuration -# Declares how agents should approach work in this repository. -# Read at session start by any AI agent (Claude, Gemini, Copilot, etc.) -# -# Reference: ADR-002 in standards/agentic-a2ml/docs/ - -[metadata] -version = "1.0.0" -last-updated = "{{CURRENT_DATE}}" -spec = "https://github.com/hyperpolymath/standards/blob/main/agentic-a2ml/docs/ADR-002-methodology-layer.adoc" - -# ============================================================================ -# MODE SELECTION -# ============================================================================ -# convergent: find gaps, fill them, build infrastructure (default for ops/infra) -# divergent: find what's strongest, push it further (for research/creative) -# hybrid: audit 20% of budget, then focus 80% on top MUSTs (default for most) - -[methodology] -default-mode = "hybrid" -ring-ceiling = 2 # Hard ceiling for ring expansion (0-3) -wave-cap = 2 # Max waves before requiring user "keep going" -spike-required = true # Every session must ship code, not just designs - -# ============================================================================ -# PRIORITY WEIGHTS -# ============================================================================ -# MUST (3x): Blocking the current work → fix immediately -# SHOULD (2x): Degrading quality of current work → fix if in zone -# COULD (1x): Improving quality of adjacent work → add to debt list - -[methodology.priority-weights] -must = 3 -should = 2 -could = 1 - -# ============================================================================ -# CONVERGENT BUDGET (when mode = convergent or hybrid) -# ============================================================================ -# How to allocate effort across work types. -# Prevents over-polishing docs while structural work waits. - -[methodology.convergent-budget] -structural = 70 # % for new modules, compilation fixes, wiring, integration -corrective = 20 # % for bugs found, broken imports, stale references -perfective = 10 # % for SPDX headers, doc updates, formatting, style - -# ============================================================================ -# UNIQUE STRENGTH (when mode = divergent) -# ============================================================================ -# What makes this project special. Agents should DEEPEN this, not broaden it. -# Customise this per project — the template default is generic. - -[methodology.unique-strength] -description = "{{PROJECT_UNIQUE_STRENGTH}}" -deepen-not-broaden = true - -# ============================================================================ -# DIVERGENT INVARIANTS -# ============================================================================ -# Constraints that divergent mode must NOT violate. -# These are the riverbanks — diverge within them, not across. -# "Amplify uniqueness" means deepen, not broaden. -# -# Test before any divergent action: -# "Does this deepen the existing strength, or add a parallel strength?" -# If parallel → stop. Note as cross-project insight. - -[methodology.divergent-invariants] -rules = [ - # Customise per project. Examples: - # "Idris2 only for formal verification — no Lean4, Coq, Agda", - # "believe_me count must remain zero", - # "FFI architecture: Idris2 → RefC → Zig → C ABI (no shortcuts)", -] - -# Optional: language invariant for the core strength -# If set, divergent mode will not introduce other languages for this purpose -# language-invariant = "idris2" - -# ============================================================================ -# CONSTRAINT HINTS -# ============================================================================ -# Help Phase 0 find the critical chain faster. -# Updated at session end with newly discovered constraints. - -[methodology.known-constraints] -constraints = [ - # Customise per project. Examples: - # "End-to-end build has never been verified", - # "libproject.so does not exist yet — all bindings call stubs", -] - -# ============================================================================ -# STATE FILE VALIDATION -# ============================================================================ -# Phase 0 reads STATE.a2ml first but it may be broken. -# These rules detect corrupt/template/stale state files. - -[methodology.state-validation] -reject-if-contains = ["{{PLACEHOLDER}}", "{{PROJECT}}", "rsr-template-repo"] -reject-if-project-name-mismatch = true -staleness-threshold-days = 90 -fallback-files = ["TODO.md", "TODO.adoc", "ROADMAP.adoc", "README.adoc"] diff --git a/.machine_readable/compliance/reuse/dep5 b/.machine_readable/compliance/reuse/dep5 deleted file mode 100644 index 49aaed6..0000000 --- a/.machine_readable/compliance/reuse/dep5 +++ /dev/null @@ -1,54 +0,0 @@ -Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/ -Upstream-Name: {{PROJECT_NAME}} -Upstream-Contact: {{AUTHOR}} <{{AUTHOR_EMAIL}}> -Source: https://github.com/{{OWNER}}/{{REPO}} - -# Default: all files are MPL-2.0 -Files: * -Copyright: {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -License: MPL-2.0 - -# Configuration files that cannot carry headers -Files: .editorconfig .gitignore .gitattributes .tool-versions .mailmap -Copyright: {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -License: MPL-2.0 - -# Machine-readable state files -Files: .machine_readable/*.a2ml -Copyright: {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -License: MPL-2.0 - -# Bot directives -Files: .machine_readable/bot_directives/* -Copyright: {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -License: MPL-2.0 - -# Contractiles -Files: .machine_readable/contractiles/* -Copyright: {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -License: MPL-2.0 - -# GitHub/CI configuration -Files: .github/* .github/**/* -Copyright: {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -License: MPL-2.0 - -# Generated files -Files: generated/* -Copyright: {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -License: MPL-2.0 - -# Lockfiles and auto-generated -Files: *.lock Cargo.lock flake.lock -Copyright: {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -License: MPL-2.0 - -# Devcontainer config (JSON, no comments) -Files: .devcontainer/*.json -Copyright: {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -License: MPL-2.0 - -# Git-cliff config -Files: cliff.toml -Copyright: {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -License: MPL-2.0 diff --git a/.machine_readable/compliance/rust/deny.toml b/.machine_readable/compliance/rust/deny.toml deleted file mode 100644 index 0534a85..0000000 --- a/.machine_readable/compliance/rust/deny.toml +++ /dev/null @@ -1,65 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# cargo-deny configuration for RSR-compliant repositories -# Run: cargo deny check -# Docs: https://embarkstudios.github.io/cargo-deny/ - -[graph] -targets = [] -all-features = true - -# --- Advisory database --------------------------------------------------- -[advisories] -db-path = "~/.cargo/advisory-db" -db-urls = ["https://github.com/rustsec/advisory-db"] -# Fail on any known vulnerability -vulnerability = "deny" -unmaintained = "warn" -yanked = "warn" -notice = "warn" - -# --- License policy ------------------------------------------------------- -[licenses] -unlicensed = "deny" -confidence-threshold = 0.8 - -allow = [ - "MPL-2.0", - "MPL-2.0", - "MIT", - "Apache-2.0", - "BSD-2-Clause", - "BSD-3-Clause", - "ISC", - "Zlib", - "Unicode-3.0", - "Unicode-DFS-2016", -] - -deny = [ - "AGPL-3.0-only", - "AGPL-3.0-or-later", -] - -copyleft = "warn" - -[[licenses.exceptions]] -allow = ["OpenSSL"] -name = "ring" - -# --- Crate bans ------------------------------------------------------------ -[bans] -multiple-versions = "warn" -wildcards = "allow" -highlight = "all" - -deny = [ - # Known-bad crates - { name = "openssl", wrappers = ["openssl-sys"] }, -] - -# --- Source restrictions ---------------------------------------------------- -[sources] -unknown-registry = "deny" -unknown-git = "warn" -allow-registry = ["https://github.com/rust-lang/crates.io-index"] -allow-git = [] diff --git a/.machine_readable/configs/0.2-AI-MANIFEST.a2ml b/.machine_readable/configs/0.2-AI-MANIFEST.a2ml deleted file mode 100644 index 6e41e6c..0000000 --- a/.machine_readable/configs/0.2-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "configs-registry" -level: 2 -parent: "../0.1-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Sub-registry for configs metadata. diff --git a/.machine_readable/configs/README.adoc b/.machine_readable/configs/README.adoc deleted file mode 100644 index 2ab097e..0000000 --- a/.machine_readable/configs/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= configs Registry diff --git a/.machine_readable/configs/eclexiaiser.toml b/.machine_readable/configs/eclexiaiser.toml deleted file mode 100644 index abc542e..0000000 --- a/.machine_readable/configs/eclexiaiser.toml +++ /dev/null @@ -1,26 +0,0 @@ -# eclexiaiser manifest — energy/carbon resource budgets -# SPDX-License-Identifier: MPL-2.0 - -[project] -name = "{{REPO}}" - -[[functions]] -name = "build" -source = "src/interface/ffi/build.zig" -energy-budget-mj = 15.0 -carbon-budget-mg = 3.0 - -[[functions]] -name = "setError" -source = "src/interface/ffi/src/main.zig" -energy-budget-mj = 5.0 -carbon-budget-mg = 1.0 - -[carbon] -provider = "static" -region = "GB" -static-intensity = 200.0 - -[report] -format = "text" -include-recommendations = true diff --git a/.machine_readable/configs/git-cliff/cliff.toml b/.machine_readable/configs/git-cliff/cliff.toml deleted file mode 100644 index 5c39b48..0000000 --- a/.machine_readable/configs/git-cliff/cliff.toml +++ /dev/null @@ -1,119 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -# -# git-cliff configuration for conventional commit changelog generation. -# https://git-cliff.org/docs/configuration -# -# Placeholders — replace before first use: -# {{OWNER}} — GitHub organization or username -# {{REPO}} — GitHub repository name - -[changelog] -# Changelog header -header = """ -# Changelog\n -All notable changes to this project will be documented in this file.\n -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n -\n -""" -# Template for the changelog body -# https://keats.github.io/tera/docs/#introduction -body = """ -{%- macro remote_url() -%} - https://github.com/{{OWNER}}/{{REPO}} -{%- endmacro -%} - -{% if version -%} - ## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }} -{% else -%} - ## [Unreleased] -{% endif -%} - -{% for group, commits in commits | group_by(attribute="group") %} - ### {{ group | striptags | trim }} - {% for commit in commits %} - - {% if commit.scope %}**{{ commit.scope }}:** {% endif %}\ - {% if commit.breaking %}[**BREAKING**] {% endif %}\ - {{ commit.message | upper_first }}\ - {%- if commit.links %} \ - ({% for link in commit.links %}[{{ link.text }}]({{ link.href }}){% endfor %}){% endif -%} - {% endfor %} -{% endfor %} - -{%- if github -%} -{% if github.contributors | filter(attribute="is_first_time", value=true) | length != 0 %} - ### New Contributors -{%- for contributor in github.contributors | filter(attribute="is_first_time", value=true) %} - * @{{ contributor.username }} made their first contribution - {%- if contributor.pr_number %} in \ - [#{{ contributor.pr_number }}]({{ self::remote_url() }}/pull/{{ contributor.pr_number }}) - {%- endif %} -{%- endfor %} -{% endif -%} -{% endif -%} - -""" -# Template for the changelog footer -footer = """ -{%- macro remote_url() -%} - https://github.com/{{OWNER}}/{{REPO}} -{%- endmacro -%} - -{% for release in releases -%} - {% if release.version -%} - {% if release.previous.version -%} - [{{ release.version | trim_start_matches(pat="v") }}]: \ - {{ self::remote_url() }}/compare/{{ release.previous.version }}...{{ release.version }} - {% endif -%} - {% else -%} - {% if release.previous.version -%} - [Unreleased]: {{ self::remote_url() }}/compare/{{ release.previous.version }}...HEAD - {% endif -%} - {% endif -%} -{% endfor %} - -""" -# Remove leading and trailing whitespace from templates -trim = true - -[git] -# Parse conventional commits -# https://www.conventionalcommits.org -conventional_commits = true -# Filter out unconventional commits -filter_unconventional = true -# Process each line of a commit as an individual commit -split_commits = false -# Regex for commit preprocessing -commit_preprocessors = [ - # Remove issue numbers from commit messages - { pattern = '\((\w+\s)?#([0-9]+)\)', replace = "" }, -] -# Regex for parsing and grouping commits -commit_parsers = [ - { message = "^feat", group = "Features" }, - { message = "^fix", group = "Bug Fixes" }, - { message = "^security", group = "Security" }, - { message = "^perf", group = "Performance" }, - { message = "^refactor", group = "Refactoring" }, - { message = "^docs", group = "Documentation" }, - { message = "^style", group = "Styling" }, - { message = "^test", group = "Testing" }, - { message = "^ci", group = "CI/CD" }, - { message = "^chore\\(release\\)", skip = true }, - { message = "^chore\\(deps.*\\)", skip = true }, - { message = "^chore\\(pr\\)", skip = true }, - { message = "^chore", group = "Miscellaneous" }, - { body = ".*security", group = "Security" }, -] -# Protect breaking changes from being skipped by a commit parser -protect_breaking_commits = false -# Filter out merge commits -filter_merge_commits = true -# Filter out commits by tag pattern (skip pre-releases) -# tag_pattern = "v[0-9].*" -# Regex for skipping tags -# skip_tags = "beta|alpha" -# Sort commits within each group by oldest first -sort_commits = "oldest" diff --git a/.machine_readable/configs/selur-compose.toml b/.machine_readable/configs/selur-compose.toml deleted file mode 100644 index e7f831a..0000000 --- a/.machine_readable/configs/selur-compose.toml +++ /dev/null @@ -1,17 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# Stapeln service definition for {{SERVICE_NAME}} -# -# Usage: -# podman-compose -f selur-compose.toml up -d -# just stack-up - -[project] -name = "{{SERVICE_NAME}}" - -[services.app] -build = { context = ".", dockerfile = "Containerfile" } -restart = "unless-stopped" -networks = ["default"] -healthcheck = { test = "exit 0", interval = "30s", timeout = "5s", retries = 3 } diff --git a/.machine_readable/configs/stapeln.toml b/.machine_readable/configs/stapeln.toml deleted file mode 100644 index 7bf5d48..0000000 --- a/.machine_readable/configs/stapeln.toml +++ /dev/null @@ -1,87 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# stapeln.toml — Layer-based container build for {{SERVICE_NAME}} -# -# stapeln builds containers as composable layers (German: "to stack"). -# Each layer is independently cacheable, verifiable, and signable. - -[metadata] -name = "{{SERVICE_NAME}}" -version = "0.1.0" -description = "{{SERVICE_NAME}} container service" -author = "Jonathan D.A. Jewell " -license = "MPL-2.0" -registry = "{{REGISTRY}}" - -[build] -containerfile = "Containerfile" -context = "." -runtime = "podman" - -# ── Layer Definitions ────────────────────────────────────────── - -[layers.base] -description = "Chainguard Wolfi minimal base" -from = "cgr.dev/chainguard/wolfi-base:latest" -cache = true -verify = true - -[layers.toolchain] -description = "Build tools" -extends = "base" -packages = [] -cache = true - -[layers.build] -description = "{{SERVICE_NAME}} build" -extends = "toolchain" -commands = [] - -[layers.runtime] -description = "Minimal runtime" -from = "cgr.dev/chainguard/wolfi-base:latest" -packages = ["ca-certificates", "curl"] -copy-from = [ - { layer = "build", src = "/app/", dst = "/app/" }, -] -entrypoint = ["/app/{{SERVICE_NAME}}"] -user = "nonroot" - -# ── Security ─────────────────────────────────────────────────── - -[security] -non-root = true -read-only-root = false -no-new-privileges = true -cap-drop = ["ALL"] -seccomp-profile = "default" - -[security.signing] -algorithm = "ML-DSA-87" -provider = "cerro-torre" - -[security.sbom] -format = "spdx-json" -output = "sbom.spdx.json" -include-deps = true - -# ── Verification ─────────────────────────────────────────────── - -[verify] -vordr = true -svalinn = true -scan-on-build = true -fail-on = ["critical", "high"] - -# ── Targets ──────────────────────────────────────────────────── - -[targets.development] -layers = ["base", "chainguard-toolchain", "build"] -env = { LOG_LEVEL = "debug" } - -[targets.production] -layers = ["runtime"] -env = { LOG_LEVEL = "info" } - -[targets.test] -layers = ["base", "chainguard-toolchain", "build"] -env = { LOG_LEVEL = "debug" } diff --git a/.machine_readable/contractiles/Adjustfile.a2ml b/.machine_readable/contractiles/Adjustfile.a2ml deleted file mode 100644 index 6f01e89..0000000 --- a/.machine_readable/contractiles/Adjustfile.a2ml +++ /dev/null @@ -1,72 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Adjustfile — Drift-tolerance contract for rsr-template-repo -# Author: Jonathan D.A. Jewell -# -# Cumulative-drift catchment: tolerance bands + corrective actions. -# Authority: advisory (Yard) — continue-with-warnings; auto_fix where deterministic. -# Run with: adjust check -# Fix with: adjust fix (applies deterministic patches; advisory otherwise) - -@abstract: -Drift tolerances and corrective actions for rsr-template-repo. Unlike -MUST (hard gate), ADJUST tracks cumulative drift against tolerance bands -and proposes corrective actions. Advisory — it warns and trends, it does -not block. -@end - -## Template Drift - -### placeholder-drift -- description: Template placeholders should be replaced when copied -- tolerance: 0 placeholder markers in copied repos -- corrective: Search and replace all {{PLACEHOLDER}} markers -- severity: advisory -- notes: This check only applies to repos that copied from this template - -### template-version-drift -- description: Template version should match RSR spec version -- tolerance: Template version matches current RSR spec -- corrective: Update template to match latest RSR spec -- severity: advisory - -## Documentation Drift - -### readme-completeness -- description: README should document all template features -- tolerance: README covers all contractiles and directory structure -- corrective: Update README.adoc with missing sections -- severity: advisory - -### example-accuracy -- description: Examples in documentation should match actual template content -- tolerance: All code examples in docs are accurate -- corrective: Audit and fix examples in documentation -- severity: advisory - -## Structural Drift - -### contractile-sync -- description: All contractiles should have matching a2ml and ncl implementations -- tolerance: Every .a2ml has a corresponding .ncl -- corrective: Generate missing .ncl files from .a2ml -- severity: advisory - -### no-broken-symlinks -- description: No broken symbolic links in template structure -- tolerance: 0 broken symlinks -- corrective: Run symlink-check script -- severity: advisory - -## Accessibility Drift - -### adoc-not-md -- description: Template docs should prefer AsciiDoc -- tolerance: New prose docs are *.adoc -- corrective: Convert any new *.md to *.adoc -- severity: advisory - -### spdx-header-consistency -- description: All template files have correct SPDX headers -- tolerance: 0 files missing SPDX-License-Identifier -- corrective: Add SPDX headers to files that need them -- severity: advisory diff --git a/.machine_readable/contractiles/Intentfile.a2ml b/.machine_readable/contractiles/Intentfile.a2ml deleted file mode 100644 index ef74f45..0000000 --- a/.machine_readable/contractiles/Intentfile.a2ml +++ /dev/null @@ -1,99 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Intentfile (A2ML Canonical) — north-star contractile for rsr-template-repo -# Author: Jonathan D.A. Jewell -# -# Paired runner: intend.ncl -# Verb: intend -# -# Semantics: North-star contractile. Declares BOTH concrete committed -# next-actions AND horizon aspirations the project wishes to -# become. Two sections share one file because they answer -# the same question at different ranges: -# [[intents]] — "we WILL do this; track progress" -# status: declared → in_progress → done | -# deferred | retired -# [[wishes]] — "we WISH this were true; revisit later" -# status: declared → in_progress → achieved | -# abandoned -# grouped by horizon: near / mid / far. -# Non-gating — this is a report, not a gate. See the `must` -# contractile for hard gates. - -@abstract: -North-star contractile for rsr-template-repo. This repository is the -canonical template for Rhodium Standard Repository compliance. It provides -the scaffold that all hyperpolymath repos should copy and customize. -@end - -## Purpose - -The rsr-template-repo serves as the master template for all hyperpolymath -repositories. It contains the complete set of contractile files, machine-readable -specifications, and governance documentation that define the Rhodium Standard. - -Every new repository in the hyperpolymath estate should be initialized by -copying this template and substituting the placeholder values with -repo-specific content. - -## Anti-Purpose - -This repository is NOT: -- A general-purpose project scaffold for external use (hyperpolymath-only) -- A replacement for per-repo customization (all files must be bespoke) -- A static template that never changes (evolves with RSR spec) -- A runtime library or framework (build-time only) - -## If In Doubt - -If you are unsure whether a change is in scope, ask. Sensitive areas: -- .machine_readable/ contractile definitions -- RSR specification files -- Governance templates -- License policy documents - -## Committed Next-Actions - -### repo-initialization -- description: Provide just copy-and-substitute template for new repos -- probe: test -f scripts/init-repo.sh -- status: done -- notes: Run with source scripts/init-repo.sh - -### contractile-completeness -- description: Every RSR contractile has an a2ml and ncl implementation -- probe: ls .machine_readable/contractiles/*.a2ml | wc -l | grep -q "^6$" -- status: in_progress -- notes: Currently 6 contractile verbs: intend, must, trust, adjust, bust, dust - -### automation-scripts -- description: All repetitive tasks have just recipes -- probe: grep -c "^# " Justfile | grep -q "^[6-9][0-9]*$" -- status: in_progress - -## Wishes - -### Near Horizon - -#### cross-repo-validation -- description: Tooling to validate all repos against RSR spec -- horizon: near -- status: declared - -#### automated-substitution -- description: Script to automate repo-specific substitution in template -- horizon: near -- status: declared - -### Mid Horizon - -#### formal-verification -- description: Idris2 proofs for all critical contractile invariants -- horizon: mid -- status: declared - -### Far Horizon - -#### ecosystem-visualization -- description: Interactive graph of all hyperpolymath repos and dependencies -- horizon: far -- status: declared diff --git a/.machine_readable/contractiles/Justfile b/.machine_readable/contractiles/Justfile deleted file mode 100644 index 2db3d94..0000000 --- a/.machine_readable/contractiles/Justfile +++ /dev/null @@ -1,784 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# RSR Standard Justfile Template -# https://just.systems/man/en/ -# -# Copy this file to new projects and customize the placeholder values. -# -# Run `just` to see all available recipes -# Run `just cookbook` to generate docs/just-cookbook.adoc -# Run `just combinations` to see matrix recipe options - -set shell := ["bash", "-uc"] -set dotenv-load := true -set positional-arguments := true - -# Import auto-generated contractile recipes (must-check, trust-verify, etc.) -# Re-generate with: contractile gen-just -import? "build/contractile.just" - -# Project metadata — customize these -project := "rsr-template-repo" -OWNER := "hyperpolymath" -REPO := "rsr-template-repo" -version := "0.1.0" -tier := "infrastructure" # 1 | 2 | infrastructure - -# ═══════════════════════════════════════════════════════════════════════════════ -# DEFAULT & HELP -# ═══════════════════════════════════════════════════════════════════════════════ - -# Show all available recipes with descriptions -default: - @just --list --unsorted - -# Show detailed help for a specific recipe -help recipe="": - #!/usr/bin/env bash - if [ -z "{{recipe}}" ]; then - just --list --unsorted - echo "" - echo "Usage: just help " - echo " just cookbook # Generate full documentation" - echo " just combinations # Show matrix recipes" - else - just --show "{{recipe}}" 2>/dev/null || echo "Recipe '{{recipe}}' not found" - fi - -# Show this project's info -info: - @echo "Project: {{project}}" - @echo "Version: {{version}}" - @echo "RSR Tier: {{tier}}" - @echo "Recipes: $(just --summary | wc -w)" - @[ -f ".machine_readable/STATE.a2ml" ] && grep -oP 'phase\s*=\s*"\K[^"]+' .machine_readable/STATE.a2ml | head -1 | xargs -I{} echo "Phase: {}" || true - -# Run Invariant Path overlay tools for this repository -invariant-path *ARGS: - ./scripts/invariant-path.sh {{ARGS}} - -# ═══════════════════════════════════════════════════════════════════════════════ -# INIT — see build/just/init.just -# ═══════════════════════════════════════════════════════════════════════════════ - -import? "build/just/init.just" - -# ═══════════════════════════════════════════════════════════════════════════════ -# GROOVE PROTOCOL — see build/just/groove.just -# ═══════════════════════════════════════════════════════════════════════════════ - -import? "build/just/groove.just" - -# ═══════════════════════════════════════════════════════════════════════════════ -# PROJECT SELF-ASSESSMENT + OPENSSF COMPLIANCE — see build/just/assess.just -# ═══════════════════════════════════════════════════════════════════════════════ - -import? "build/just/assess.just" - -# ═══════════════════════════════════════════════════════════════════════════════ -# BUILD & COMPILE -# ═══════════════════════════════════════════════════════════════════════════════ - -# Build the project (debug mode) -build *args: - @echo "Building {{project}} (debug)..." - # TODO: Replace with your build command - # Examples: - # cargo build {{args}} # Rust - # mix compile {{args}} # Elixir - # zig build {{args}} # Zig - # deno task build {{args}} # Deno/ReScript - @echo "Build complete" - -# Build in release mode with optimizations -build-release *args: - @echo "Building {{project}} (release)..." - # TODO: Replace with your release build command - # Examples: - # cargo build --release {{args}} - # MIX_ENV=prod mix compile {{args}} - # zig build -Doptimize=ReleaseFast {{args}} - @echo "Release build complete" - -# Build and watch for changes (requires entr or similar) -build-watch: - @echo "Watching for changes..." - # TODO: Customize file patterns for your language - # Examples: - # find src -name '*.rs' | entr -c just build - # mix compile --force --warnings-as-errors - # deno task dev - -# Clean build artifacts [reversible: rebuild with `just build`] -clean: - @echo "Cleaning..." - # TODO: Customize for your build system - rm -rf target/ _build/ build/ dist/ out/ obj/ bin/ - -# Deep clean including caches [reversible: rebuild] -clean-all: clean - rm -rf .cache .tmp - -# ═══════════════════════════════════════════════════════════════════════════════ -# TEST & QUALITY -# ═══════════════════════════════════════════════════════════════════════════════ - -# Run all tests -test *args: - @echo "Running tests..." - # TODO: Replace with your test command - # Examples: - # cargo test {{args}} - # mix test {{args}} - # zig build test {{args}} - # deno test {{args}} - @echo "Tests passed!" - -# Run tests with verbose output -test-verbose: - @echo "Running tests (verbose)..." - # TODO: Replace with verbose test command - -# Smoke test -test-smoke: - @echo "Smoke test..." - # TODO: Add basic sanity checks - -# Run end-to-end tests (full pipeline: build → run → verify) -e2e: - @echo "Running E2E tests..." - # TODO: Replace with your E2E test command. Examples: - # bash tests/e2e.sh # Shell-based E2E - # npx playwright test # Browser E2E - # mix test test/integration/e2e_test.exs # Elixir E2E - # cargo test --test end_to_end # Rust E2E - @echo "E2E tests passed!" - -# Run aspect tests (cross-cutting concern validation) -aspect: - @echo "Running aspect tests..." - # TODO: Replace with your aspect test command. Examples: - # bash tests/aspect_tests.sh # Shell-based aspect tests - # cargo test --test aspects # Rust aspect tests - # Aspect tests validate architectural invariants: - # - Thread safety (mutex in FFI modules) - # - ABI/FFI contract (declarations match exports) - # - SPDX compliance (all files have license headers) - # - No dangerous patterns (believe_me, assert_total, etc.) - @echo "Aspect tests passed!" - -# Run benchmarks (performance regression detection) -bench: - @echo "Running benchmarks..." - # TODO: Replace with your benchmark command. Examples: - # cargo bench # Rust criterion - # zig build bench # Zig benchmarks - # mix run bench/benchmarks.exs # Elixir benchee - # deno bench # Deno bench - @echo "Benchmarks complete!" - -# Run readiness tests (Component Readiness Grade: D/C/B) -readiness: - @echo "Running readiness tests..." - # TODO: Replace with your readiness test command. Examples: - # cargo test --test readiness -- --nocapture - @echo "Readiness tests complete!" - -# Print the current CRG grade (reads from READINESS.md '**Current Grade:** X' line) -crg-grade: - @grade=$$(grep -oP '(?<=\*\*Current Grade:\*\* )[A-FX]' READINESS.md 2>/dev/null | head -1); \ - [ -z "$$grade" ] && grade="X"; \ - echo "$$grade" - -# Print a shields.io CRG badge for embedding in README files -# Looks for '**Current Grade:** X' in READINESS.md; falls back to X -crg-badge: - @grade=$$(grep -oP '(?<=\*\*Current Grade:\*\* )[A-FX]' READINESS.md 2>/dev/null | head -1); \ - [ -z "$$grade" ] && grade="X"; \ - case "$$grade" in \ - A) color="brightgreen" ;; \ - B) color="green" ;; \ - C) color="yellow" ;; \ - D) color="orange" ;; \ - E) color="red" ;; \ - F) color="critical" ;; \ - *) color="lightgrey" ;; \ - esac; \ - echo "[![CRG $$grade](https://img.shields.io/badge/CRG-$$grade-$$color?style=flat-square)](https://github.com/hyperpolymath/standards/tree/main/component-readiness-grades)" - -# Run the full merge-requirement test suite (ALL categories) -# Per STANDING rule: P2P + E2E + aspect + execution + lifecycle + bench -test-all: test e2e aspect bench readiness - @echo "All test categories passed — safe to merge!" - -# Run all quality checks -quality: fmt-check lint test - @echo "All quality checks passed!" - -# Fix all auto-fixable issues [reversible: git checkout] -fix: fmt - @echo "Fixed all auto-fixable issues" - -# ═══════════════════════════════════════════════════════════════════════════════ -# LINT & FORMAT -# ═══════════════════════════════════════════════════════════════════════════════ - -# Format all source files [reversible: git checkout] -fmt: - @echo "Formatting source files..." - # TODO: Replace with your formatter - # Examples: - # cargo fmt - # mix format - # gleam format - # deno fmt - -# Check formatting without changes -fmt-check: - @echo "Checking formatting..." - # TODO: Replace with your format check - # Examples: - # cargo fmt --check - # mix format --check-formatted - # gleam format --check - -# Run linter -lint: - @echo "Linting source files..." - # TODO: Replace with your linter - # Examples: - # cargo clippy -- -D warnings - # mix credo --strict - # gleam check - -# ═══════════════════════════════════════════════════════════════════════════════ -# RUN & EXECUTE -# ═══════════════════════════════════════════════════════════════════════════════ - -# Run the application -run *args: build - # TODO: Replace with your run command - echo "Run not configured yet" - -# Run with verbose output -run-verbose *args: build - # TODO: Replace with verbose run command - echo "Run not configured yet" - -# Install to user path -install: build-release - @echo "Installing {{project}}..." - # TODO: Replace with your install command - -# ═══════════════════════════════════════════════════════════════════════════════ -# DEPENDENCIES -# ═══════════════════════════════════════════════════════════════════════════════ - -# Install/check all dependencies -deps: - @echo "Checking dependencies..." - # TODO: Replace with your dependency check - # Examples: - # cargo check - # mix deps.get - # gleam deps download - @echo "All dependencies satisfied" - -# Audit dependencies for vulnerabilities -deps-audit: - @echo "Auditing for vulnerabilities..." - # TODO: Replace with your audit command - # Examples: - # cargo audit - # mix audit - @command -v trivy >/dev/null && trivy fs --severity HIGH,CRITICAL --quiet . || true - @echo "Audit complete" - -# ═══════════════════════════════════════════════════════════════════════════════ -# DOCUMENTATION -# ═══════════════════════════════════════════════════════════════════════════════ - -# Generate all documentation -docs: - @mkdir -p docs/generated docs/man - just cookbook - just man - @echo "Documentation generated in docs/" - -# Generate justfile cookbook documentation -cookbook: - #!/usr/bin/env bash - mkdir -p docs - OUTPUT="docs/just-cookbook.adoc" - echo "= {{project}} Justfile Cookbook" > "$OUTPUT" - echo ":toc: left" >> "$OUTPUT" - echo ":toclevels: 3" >> "$OUTPUT" - echo "" >> "$OUTPUT" - echo "Generated: $(date -Iseconds)" >> "$OUTPUT" - echo "" >> "$OUTPUT" - echo "== Recipes" >> "$OUTPUT" - echo "" >> "$OUTPUT" - just --list --unsorted | while read -r line; do - if [[ "$line" =~ ^[[:space:]]+([a-z_-]+) ]]; then - recipe="${BASH_REMATCH[1]}" - echo "=== $recipe" >> "$OUTPUT" - echo "" >> "$OUTPUT" - echo "[source,bash]" >> "$OUTPUT" - echo "----" >> "$OUTPUT" - echo "just $recipe" >> "$OUTPUT" - echo "----" >> "$OUTPUT" - echo "" >> "$OUTPUT" - fi - done - echo "Generated: $OUTPUT" - -# Generate man page -man: - #!/usr/bin/env bash - mkdir -p docs/man - cat > docs/man/{{project}}.1 << EOF - .TH {{project}} 1 "$(date +%Y-%m-%d)" "{{version}}" "{{project}} Manual" - .SH NAME - {{project}} \- RSR-compliant project - .SH SYNOPSIS - .B just - [recipe] [args...] - .SH DESCRIPTION - RSR (Rhodium Standard Repository) project managed with just. - .SH AUTHOR - $(git config user.name 2>/dev/null || echo "Author") <$(git config user.email 2>/dev/null || echo "email")> - EOF - echo "Generated: docs/man/{{project}}.1" - -# ═══════════════════════════════════════════════════════════════════════════════ -# CONTAINERS (stapeln ecosystem — Podman + Chainguard Wolfi) -# ═══════════════════════════════════════════════════════════════════════════════ - -# Initialise container templates — substitute placeholders with project values -container-init: - #!/usr/bin/env bash - set -euo pipefail - - if [ ! -d "container" ]; then - echo "Error: container/ directory not found." - echo "This repo may not have been created from rsr-template-repo." - exit 1 - fi - - echo "=== Container Template Initialisation ===" - echo "" - - # Load RSR defaults if available - DEFAULTS="${XDG_CONFIG_HOME:-$HOME/.config}/rsr/defaults" - if [ -f "$DEFAULTS" ]; then - echo "Loading defaults from $DEFAULTS" - # shellcheck source=/dev/null - source "$DEFAULTS" - echo "" - fi - - # Prompt for container-specific values - read -rp "Service name (e.g. my-api) [{{project}}]: " _SERVICE_NAME - SERVICE_NAME="${_SERVICE_NAME:-{{project}}}" - - read -rp "Primary port [8080]: " _PORT - PORT="${_PORT:-8080}" - - read -rp "Container registry [ghcr.io/${OWNER:-{{OWNER}}}]: " _REGISTRY - REGISTRY="${_REGISTRY:-ghcr.io/${OWNER:-{{OWNER}}}}" - - echo "" - echo " Service: $SERVICE_NAME" - echo " Port: $PORT" - echo " Registry: $REGISTRY" - echo "" - read -rp "Proceed? [Y/n] " CONFIRM - [[ "${CONFIRM:-Y}" =~ ^[Nn] ]] && echo "Aborted." && exit 0 - - echo "" - echo "Replacing container placeholders..." - - # Brace tokens as variables (hex escapes avoid just interpolation) - LB=$(printf '\x7b\x7b') - RB=$(printf '\x7d\x7d') - - SED_ARGS=( - -e "s|${LB}SERVICE_NAME${RB}|${SERVICE_NAME}|g" - -e "s|${LB}PORT${RB}|${PORT}|g" - -e "s|${LB}REGISTRY${RB}|${REGISTRY}|g" - ) - - find container/ -type f | while read -r file; do - if file --brief "$file" | grep -qi 'text\|ascii\|utf'; then - sed -i "${SED_ARGS[@]}" "$file" - fi - done - - echo "Container templates initialised." - echo "" - echo "Next steps:" - echo " 1. Edit container/Containerfile — add your build commands" - echo " 2. Edit container/entrypoint.sh — set your application binary" - echo " 3. Review container/compose.toml — adjust services and volumes" - echo " 4. Build: just container-build" - -# Build container image via cerro-torre pipeline -container-build *args: - #!/usr/bin/env bash - if [ -f "container/ct-build.sh" ]; then - cd container && ./ct-build.sh {{args}} - elif [ -f "container/Containerfile" ]; then - podman build -t {{project}}:latest -f container/Containerfile . - elif [ -f "build/Containerfile" ]; then - podman build -t {{project}}:latest -f build/Containerfile . - elif [ -f "Containerfile" ]; then - podman build -t {{project}}:latest -f Containerfile . - else - echo "No Containerfile found in container/, build/, or project root" - exit 1 - fi - -# Verify compose configuration -container-verify: - #!/usr/bin/env bash - if [ ! -f "container/compose.toml" ]; then - echo "No container/compose.toml found" - exit 1 - fi - cd container - if command -v selur-compose &>/dev/null; then - selur-compose verify - else - echo "selur-compose not found, falling back to podman compose" - podman compose --file compose.toml config - fi - -# Start container stack -container-up *args: - #!/usr/bin/env bash - if [ ! -f "container/compose.toml" ]; then - echo "No container/compose.toml found" - exit 1 - fi - cd container - if command -v selur-compose &>/dev/null; then - selur-compose up {{args}} - else - podman compose --file compose.toml up {{args}} - fi - -# Stop container stack -container-down: - #!/usr/bin/env bash - cd container 2>/dev/null || { echo "No container/ directory"; exit 1; } - if command -v selur-compose &>/dev/null; then - selur-compose down - else - podman compose --file compose.toml down - fi - -# Sign and verify container bundle (build + pack + sign + verify) -container-sign: - #!/usr/bin/env bash - if [ -f "container/ct-build.sh" ]; then - cd container && ./ct-build.sh - else - echo "No container/ct-build.sh found" - exit 1 - fi - -# Push signed bundle to registry -container-push: - #!/usr/bin/env bash - if [ -f "container/ct-build.sh" ]; then - cd container && ./ct-build.sh --push - else - echo "No container/ct-build.sh found — falling back to podman push" - podman push {{project}}:latest - fi - -# Run container interactively (for debugging) -container-run *args: - podman run --rm -it {{project}}:latest {{args}} - -# ═══════════════════════════════════════════════════════════════════════════════ -# CI & AUTOMATION -# ═══════════════════════════════════════════════════════════════════════════════ - -# Run full CI pipeline locally -ci: deps quality - @echo "CI pipeline complete!" - -# Install git hooks -install-hooks: - @mkdir -p .git/hooks - @cat > .git/hooks/pre-commit << 'HOOKEOF' - #!/bin/bash - just fmt-check || exit 1 - just lint || exit 1 - just assail || exit 1 - HOOKEOF - @chmod +x .git/hooks/pre-commit - @echo "Git hooks installed" - -# ═══════════════════════════════════════════════════════════════════════════════ -# SECURITY -# ═══════════════════════════════════════════════════════════════════════════════ - -# Run security audit -security: deps-audit - @echo "=== Security Audit ===" - @command -v trivy >/dev/null && trivy fs --severity HIGH,CRITICAL . || true - @echo "Security audit complete" - -# Generate SBOM -sbom: - @mkdir -p docs/security - @command -v syft >/dev/null && syft . -o spdx-json > docs/security/sbom.spdx.json || echo "syft not found" - -# ═══════════════════════════════════════════════════════════════════════════════ -# VALIDATION & COMPLIANCE — see build/just/validate.just -# ═══════════════════════════════════════════════════════════════════════════════ - -import? "build/just/validate.just" - -# ═══════════════════════════════════════════════════════════════════════════════ -# STATE MANAGEMENT -# ═══════════════════════════════════════════════════════════════════════════════ - -# Update STATE.a2ml timestamp -state-touch: - @if [ -f ".machine_readable/STATE.a2ml" ]; then \ - sed -i 's/last-updated = "[^"]*"/last-updated = "'"$(date +%Y-%m-%d)"'"/' .machine_readable/STATE.a2ml && \ - echo "STATE.a2ml timestamp updated"; \ - fi - -# Show current phase from STATE.a2ml -state-phase: - @grep -oP 'phase\s*=\s*"\K[^"]+' .machine_readable/STATE.a2ml 2>/dev/null | head -1 || echo "unknown" - -# ═══════════════════════════════════════════════════════════════════════════════ -# GUIX & NIX -# ═══════════════════════════════════════════════════════════════════════════════ - -# Enter Guix development shell (primary) -guix-shell: - guix shell -D -f guix.scm - -# Build with Guix -guix-build: - guix build -f guix.scm - -# Enter Nix development shell (fallback) -nix-shell: - @if [ -f "flake.nix" ]; then nix develop; else echo "No flake.nix"; fi - -# ═══════════════════════════════════════════════════════════════════════════════ -# HYBRID AUTOMATION -# ═══════════════════════════════════════════════════════════════════════════════ - -# Run local automation tasks -automate task="all": - #!/usr/bin/env bash - case "{{task}}" in - all) just fmt && just lint && just test && just docs && just state-touch ;; - cleanup) just clean && find . -name "*.orig" -delete && find . -name "*~" -delete ;; - update) just deps && just validate ;; - *) echo "Unknown: {{task}}. Use: all, cleanup, update" && exit 1 ;; - esac - -# ═══════════════════════════════════════════════════════════════════════════════ -# COMBINATORIC MATRIX RECIPES -# ═══════════════════════════════════════════════════════════════════════════════ - -# Build matrix: [debug|release] x [target] x [features] -build-matrix mode="debug" target="" features="": - @echo "Build matrix: mode={{mode}} target={{target}} features={{features}}" - -# Test matrix: [unit|integration|e2e|all] x [verbosity] x [parallel] -test-matrix suite="unit" verbosity="normal" parallel="true": - @echo "Test matrix: suite={{suite}} verbosity={{verbosity}} parallel={{parallel}}" - -# Container matrix: [build|run|push|shell|scan] x [registry] x [tag] -container-matrix action="build" registry="ghcr.io/{{OWNER}}" tag="latest": - @echo "Container matrix: action={{action}} registry={{registry}} tag={{tag}}" - -# CI matrix: [lint|test|build|security|all] x [quick|full] -ci-matrix stage="all" depth="quick": - @echo "CI matrix: stage={{stage}} depth={{depth}}" - -# Show all matrix combinations -combinations: - @echo "=== Combinatoric Matrix Recipes ===" - @echo "" - @echo "Build Matrix: just build-matrix [debug|release] [target] [features]" - @echo "Test Matrix: just test-matrix [unit|integration|e2e|all] [verbosity] [parallel]" - @echo "Container: just container-matrix [build|run|push|shell|scan] [registry] [tag]" - @echo "CI Matrix: just ci-matrix [lint|test|build|security|all] [quick|full]" - -# ═══════════════════════════════════════════════════════════════════════════════ -# VERSION CONTROL -# ═══════════════════════════════════════════════════════════════════════════════ - -# Show git status -status: - @git status --short - -# Show recent commits -log count="20": - @git log --oneline -{{count}} - -# Generate CHANGELOG.md with git-cliff -changelog: - @command -v git-cliff >/dev/null || { echo "git-cliff not found — install: cargo install git-cliff"; exit 1; } - git cliff --config .machine_readable/configs/git-cliff/cliff.toml --output CHANGELOG.md - @echo "Generated CHANGELOG.md" - -# Preview changelog for unreleased commits (does not write) -changelog-preview: - @command -v git-cliff >/dev/null || { echo "git-cliff not found — install: cargo install git-cliff"; exit 1; } - git cliff --config .machine_readable/configs/git-cliff/cliff.toml --unreleased --strip header - -# Tag a new release (usage: just release-tag 1.2.3) -release-tag version: - #!/usr/bin/env bash - TAG="v{{version}}" - if git rev-parse "$TAG" >/dev/null 2>&1; then - echo "Tag $TAG already exists" - exit 1 - fi - just changelog - git add CHANGELOG.md - git commit -m "chore(release): prepare $TAG" - git tag -a "$TAG" -m "Release $TAG" - echo "Created tag $TAG — push with: git push origin main --tags" - -# ═══════════════════════════════════════════════════════════════════════════════ -# UTILITIES -# ═══════════════════════════════════════════════════════════════════════════════ - -# Count lines of code -loc: - @find . \( -name "*.rs" -o -name "*.ex" -o -name "*.exs" -o -name "*.res" -o -name "*.gleam" -o -name "*.zig" -o -name "*.idr" -o -name "*.hs" -o -name "*.ncl" -o -name "*.scm" -o -name "*.adb" -o -name "*.ads" \) -not -path './target/*' -not -path './_build/*' 2>/dev/null | xargs wc -l 2>/dev/null | tail -1 || echo "0" - -# Show TODO comments -todos: - @grep -rn "TODO\|FIXME\|HACK\|XXX" --include="*.rs" --include="*.ex" --include="*.res" --include="*.gleam" --include="*.zig" --include="*.idr" --include="*.hs" . 2>/dev/null || echo "No TODOs" - -# Open in editor -edit: - ${EDITOR:-code} . - -# Run high-rigor security assault using panic-attacker -maint-assault: - @./.machine_readable/scripts/maintenance/maint-assault.sh - -# Run panic-attacker pre-commit scan (foundational floor-raise requirement) -assail: - @command -v panic-attack >/dev/null 2>&1 && panic-attack assail . || echo "WARN: panic-attack not found — install from https://github.com/hyperpolymath/panic-attacker" - - -# Self-diagnostic — checks dependencies, permissions, paths -doctor: - @echo "Running diagnostics for rsr-template-repo..." - @echo "Checking required tools..." - @command -v just >/dev/null 2>&1 && echo " [OK] just" || echo " [FAIL] just not found" - @command -v git >/dev/null 2>&1 && echo " [OK] git" || echo " [FAIL] git not found" - @echo "Checking for hardcoded paths..." - @grep -rn '$HOME\|$ECLIPSE_DIR' --include='*.rs' --include='*.ex' --include='*.res' --include='*.gleam' --include='*.sh' . 2>/dev/null | head -5 || echo " [OK] No hardcoded paths" - @echo "Diagnostics complete." - -# Guided tour of key features -tour: - @echo "=== rsr-template-repo Tour ===" - @echo "" - @echo "1. Project structure:" - @ls -la - @echo "" - @echo "2. Available commands: just --list" - @echo "" - @echo "3. Read README.adoc for full overview" - @echo "4. Read EXPLAINME.adoc for architecture decisions" - @echo "5. Run 'just doctor' to check your setup" - @echo "" - @echo "Tour complete! Try 'just --list' to see all available commands." - -# Open feedback channel with diagnostic context -help-me: - @echo "=== rsr-template-repo Help ===" - @echo "Platform: $(uname -s) $(uname -m)" - @echo "Shell: $SHELL" - @echo "" - @echo "To report an issue:" - @echo " https://github.com/hyperpolymath/rsr-template-repo/issues/new" - @echo "" - @echo "Include the output of 'just doctor' in your report." - -# ═══════════════════════════════════════════════════════════════════════════════ -# FORMAL VERIFICATION (PROOFS) — see build/just/proofs.just -# ═══════════════════════════════════════════════════════════════════════════════ - -import? "build/just/proofs.just" - -# ═══════════════════════════════════════════════════════════════════════════════ -# SESSION MANAGEMENT (THIN BINDINGS TO CENTRAL STANDARDS) -# ═══════════════════════════════════════════════════════════════════════════════ - -# Show canonical session-management command model -session-help: - @echo "Canonical command model:" - @echo " intake repo " - @echo " checkpoint change " - @echo " verify maintenance " - @echo " verify substantial " - @echo " verify release " - @echo " close planned " - @echo " close urgent " - @echo " recover repo " - @echo " handover full " - @echo " handover split " - @echo " handover model " - @echo " handover human " - @echo "" - @echo "Use Just aliases below (thin wrappers around ./session/dispatch.sh)." - -# Canonical aliases (friendly recipe names that map to canonical commands) -intake-repo path=".": - @./session/dispatch.sh intake repo "{{path}}" - -checkpoint-change path=".": - @./session/dispatch.sh checkpoint change "{{path}}" - -verify-maintenance path=".": - @./session/dispatch.sh verify maintenance "{{path}}" - -verify-substantial path=".": - @./session/dispatch.sh verify substantial "{{path}}" - -verify-release path=".": - @./session/dispatch.sh verify release "{{path}}" - -close-planned path=".": - @./session/dispatch.sh close planned "{{path}}" - -close-urgent path=".": - @./session/dispatch.sh close urgent "{{path}}" - -recover-repo path=".": - @./session/dispatch.sh recover repo "{{path}}" - -handover-full path=".": - @./session/dispatch.sh handover full "{{path}}" - -handover-split path=".": - @./session/dispatch.sh handover split "{{path}}" - -handover-model path=".": - @./session/dispatch.sh handover model "{{path}}" - -handover-human path=".": - @./session/dispatch.sh handover human "{{path}}" - -secret-scan-trufflehog: - @command -v trufflehog >/dev/null && trufflehog filesystem . --only-verified || true diff --git a/.machine_readable/contractiles/Mustfile.a2ml b/.machine_readable/contractiles/Mustfile.a2ml deleted file mode 100644 index 55f8ab4..0000000 --- a/.machine_readable/contractiles/Mustfile.a2ml +++ /dev/null @@ -1,102 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Mustfile — Physical state contract for rsr-template-repo -# Author: Jonathan D.A. Jewell -# -# What MUST be true about this repository. Hard requirements. -# Run with: must check -# Fix with: must fix (where a deterministic fix exists) - -@abstract: -Physical-state invariants for rsr-template-repo. This is the canonical -RSR template repository. These are hard requirements — CI and pre-commit -hooks fail if any check fails. -@end - -## File Presence - -### license-present -- description: LICENSE file must exist -- run: test -f LICENSE -- severity: critical - -### readme-present -- description: README.adoc must exist -- run: test -f README.adoc -- severity: critical - -### security-policy -- description: SECURITY.md must exist -- run: test -f SECURITY.md -- severity: critical - -### ai-manifest -- description: 0-AI-MANIFEST.a2ml must exist -- run: test -f 0-AI-MANIFEST.a2ml -- severity: critical - -### governance-docs -- description: GOVERNANCE.adoc, MAINTAINERS.adoc, CODEOWNERS must exist -- run: test -f GOVERNANCE.adoc && test -f MAINTAINERS.adoc && test -f .github/CODEOWNERS -- severity: critical - -### machine-readable-dir -- description: .machine_readable/ directory must exist -- run: test -d .machine_readable -- severity: critical - -## Directory Structure - -### contractiles-complete -- description: All required contractile directories exist -- run: test -d .machine_readable/contractiles && test -d .machine_readable/contractiles/bust && test -d .machine_readable/contractiles/dust -- severity: critical - -### contractiles-files-present -- description: All four primary contractile files exist -- run: test -f .machine_readable/contractiles/Intentfile.a2ml && test -f .machine_readable/contractiles/Mustfile.a2ml && test -f .machine_readable/contractiles/Trustfile.a2ml && test -f .machine_readable/contractiles/Adjustfile.a2ml -- severity: critical - -### bust-dust-files-present -- description: Bustfile and Dustfile exist in their directories -- run: test -f .machine_readable/contractiles/bust/Bustfile.a2ml && test -f .machine_readable/contractiles/dust/Dustfile.a2ml -- severity: critical - -### six-directory-present -- description: 6a2 directory exists with required files -- run: test -d .machine_readable/6a2 && test -f .machine_readable/6a2/META.a2ml && test -f .machine_readable/6a2/ECOSYSTEM.a2ml && test -f .machine_readable/6a2/STATE.a2ml && test -f .machine_readable/6a2/PLAYBOOK.a2ml && test -f .machine_readable/6a2/AGENTIC.a2ml && test -f .machine_readable/6a2/NEUROSYM.a2ml -- severity: critical - -### anchors-directory -- description: anchors directory exists in 6a2 -- run: test -d .machine_readable/6a2/anchors -- severity: warning - -### self-validating-structure -- description: self-validating directory has k9-svc and examples -- run: test -d .machine_readable/self-validating && test -d .machine_readable/self-validating/k9-svc && test -d .machine_readable/self-validating/examples -- severity: warning - -## Template Integrity - -### no-placeholder-values -- description: No placeholder values remain in template files -- run: test -z "$(grep -r '{{' .machine_readable/contractiles/ 2>/dev/null)" -- severity: critical -- notes: All placeholders must be substituted when copying this template - -### template-readonly -- description: Template marker files are not modified -- run: grep -q 'RSR_TEMPLATE_DO_NOT_EDIT' .machine_readable/0.1-AI-MANIFEST.a2ml -- severity: warning - -## Git State - -### no-untracked-contractiles -- description: All contractile files are tracked in git -- run: test -z "$(git ls-files -o --exclude-standard .machine_readable/contractiles/ 2>/dev/null)" -- severity: critical - -### signed-commits -- description: All commits must be signed -- run: git verify-commit HEAD -- severity: critical diff --git a/.machine_readable/contractiles/README.adoc b/.machine_readable/contractiles/README.adoc deleted file mode 100644 index 2191594..0000000 --- a/.machine_readable/contractiles/README.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Contractiles Template Set -:toc: -:sectnums: - -This directory contains the generalized contractiles templates. Copy the `.machine_readable/contractiles/` directory into a new repo to establish a consistent operational, validation, trust, recovery, and intent framework. - -== Fill-In Instructions - -1. Update the Mustfile to reflect your real invariants (paths, schema versions, ports). -2. Replace Trustfile.hs placeholders with your actual key paths and verification commands. -3. Adjust Dustfile handlers to match your rollback and recovery tooling. -4. Update Intentfile to mirror the roadmap you want the system to evolve toward. - -== Contents - -* `must/Mustfile` - required invariants and validations. -* `trust/Trustfile.hs` - cryptographic verification steps. -* `dust/Dustfile` - rollback and recovery semantics. -* `intend/Intentfile` - future intent and roadmap direction. diff --git a/.machine_readable/contractiles/Trustfile.a2ml b/.machine_readable/contractiles/Trustfile.a2ml deleted file mode 100644 index e2028b5..0000000 --- a/.machine_readable/contractiles/Trustfile.a2ml +++ /dev/null @@ -1,88 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Trustfile — Trust boundaries and integrity invariants for rsr-template-repo -# Author: Jonathan D.A. Jewell -# -# Defines what LLM/SLM agents are trusted to do without asking, and -# integrity invariants that verify the repo has not been tampered with. - -@abstract: -Trust boundaries and integrity checks for rsr-template-repo. This file -combines the trust-level definitions from the original TRUST.contractile -with the integrity invariants from the old Trustfile.a2ml. It defines -what AI agents may do autonomously and what requires human approval, -plus checks that verify repository integrity. -@end - -## Trust Levels - -The rsr-template-repo operates at trust level: maximal - -Trust levels: -- maximal: Agent may read, build, test, lint, format, heal freely. - Only destructive/external actions require approval. -- standard: Agent may read and build. Test/lint need approval. -- restricted: Agent may read only. All modifications need approval. -- minimal: Agent may read specific files only. Everything else blocked. - -Current trust level: maximal - -## Integrity Invariants - -### Secrets - -#### no-secrets-committed -- description: No credential files in repo -- run: test ! -f .env && test ! -f credentials.json && test ! -f .env.local && test ! -f .env.production -- severity: critical - -#### no-private-keys -- description: No private key files committed -- run: "! find . -name '*.pem' -o -name '*.key' -o -name 'id_rsa' -o -name 'id_ed25519' 2>/dev/null | grep -v node_modules | head -1 | grep -q ." -- severity: critical - -#### no-tokens-in-source -- description: No hardcoded API tokens in source -- run: "! grep -rE '(api[_-]?key|secret|token|password)\s*[:=]\s*[\"'\\''][A-Za-z0-9]{16,}' --include='*.js' --include='*.ts' --include='*.res' --include='*.py' . 2>/dev/null | grep -v node_modules | head -1 | grep -q ." -- severity: critical - -## Provenance - -#### author-correct -- description: Git author matches expected identity -- run: "git log -1 --format='%ae' | grep -qE '(hyperpolymath|j\\.d\\.a\\.jewell)'" -- severity: warning - -#### license-content -- description: LICENSE contains expected identifier -- run: grep -q 'PMPL\|MPL\|MIT\|Apache\|LGPL' LICENSE -- severity: warning - -## Template-Specific Trust - -### template-files-readonly -- description: Template scaffold files should not be modified except by maintainer -- run: test -z "$(git status --short .machine_readable/ 2>/dev/null | grep -v '^??' || true)" -- severity: advisory -- notes: Changes to template files require careful review - -### trust-deny-areas -- description: Sensitive areas from INTENT.contractile require explicit approval -- run: echo "Check .machine_readable/ contractiles and governance docs" -- severity: advisory -- areas: - - .machine_readable/ - - GOVERNANCE.adoc - - MAINTAINERS.adoc - - .github/CODEOWNERS - -## Container Security - -#### container-images-pinned -- description: Containerfile uses pinned base images -- run: test ! -f Containerfile || grep -q 'cgr.dev\|@sha256:' Containerfile -- severity: warning - -#### no-dockerfile -- description: No Dockerfile (use Containerfile) -- run: test ! -f Dockerfile -- severity: warning diff --git a/.machine_readable/contractiles/bust/Bustfile.a2ml b/.machine_readable/contractiles/bust/Bustfile.a2ml deleted file mode 100644 index c7fec2b..0000000 --- a/.machine_readable/contractiles/bust/Bustfile.a2ml +++ /dev/null @@ -1,52 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Bustfile — failure mode contractile for rsr-template-repo -# Author: Jonathan D.A. Jewell -# -# Paired runner: bust.ncl -# Verb: bust -# Semantics: Every declared failure mode must have a working recovery path -# that has been exercised. Status moves: -# declared → drilled (probe run) → verified (recovery confirmed) -# or → failing (recovery broken) -# -# CLI: -# contractile bust check → list failure modes + recovery status -# contractile bust drill → inject failures, verify recovery paths -# -# This repository: rsr-template-repo is the canonical template for RSR compliance. -# Failure modes here relate to template distribution and substitution. - -@abstract: -Bustfile for rsr-template-repo. Lists failure modes specific to the template -repository itself, particularly around template distribution, substitution, -and synchronization across the hyperpolymath estate. -@end - -## Failure Modes - -### template-substitution-failure -- class: template_processing -- description: Template substitution fails when initializing a new repo from this template -- injection_probe: "cp -r rsr-template-repo test-repo && cd test-repo && sed -i 's/rsr-template-repo/TEST/g' .machine_readable/contractiles/Intentfile.a2ml && grep -q 'TEST' .machine_readable/contractiles/Intentfile.a2ml" -- recovery_probe: "git -C test-repo diff --quiet .machine_readable/contractiles/Intentfile.a2ml" -- expected_recovery_time_seconds: 10 -- status: declared -- notes: Verify that substitution scripts handle all placeholder replacements correctly - -### sync-drift-between-repos -- class: synchronization -- description: Drift occurs between rsr-template-repo and other repos after template updates -- injection_probe: "echo 'template_updated' > /tmp/test_drift_marker" -- recovery_probe: "test -f /tmp/test_drift_marker && rm /tmp/test_drift_marker" -- expected_recovery_time_seconds: 60 -- status: declared -- notes: The estate-wide sync scripts (see scripts/) should prevent this; verify with scripts/verify-sync.sh - -### contractile-parse-error -- class: contractile_format -- description: A contractile file fails to parse due to syntax errors -- injection_probe: "echo 'invalid syntax' >> rsr-template-repo/.machine_readable/contractiles/Intentfile.a2ml" -- recovery_probe: "git checkout rsr-template-repo/.machine_readable/contractiles/Intentfile.a2ml" -- expected_recovery_time_seconds: 5 -- status: declared -- notes: All .a2ml files should be valid A2ML; use a2ml-validate runner diff --git a/.machine_readable/contractiles/dust/Dustfile.a2ml b/.machine_readable/contractiles/dust/Dustfile.a2ml deleted file mode 100644 index c6bf986..0000000 --- a/.machine_readable/contractiles/dust/Dustfile.a2ml +++ /dev/null @@ -1,62 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Dustfile — Cleanup and hygiene contract for rsr-template-repo -# Author: Jonathan D.A. Jewell -# -# Paired runner: dust.ncl -# Verb: dust -# Semantics: What should be cleaned up. Housekeeping, not blockers. -# -# This repository: rsr-template-repo is the canonical template. -# Cleanup items here ensure the template itself remains pristine. - -@abstract: -Cleanup and hygiene items for rsr-template-repo. These are maintenance tasks -that ensure the template repository remains clean and ready for distribution -to new repositories. -@end - -## Stale Files - -### no-template-artifacts -- description: No generated files from template testing in root -- run: test -z "$(ls template-test-* 2>/dev/null)" -- severity: info -- notes: Template testing should use /tmp or dedicated test directories - -### no-example-placeholders -- description: No example placeholder files (EXAMPLE-, SAMPLE-) in contractiles/ -- run: test -z "$(find .machine_readable/contractiles/ -name 'EXAMPLE-*' -o -name 'SAMPLE-*' 2>/dev/null)" -- severity: warning -- notes: All placeholders should be replaced with actual content or removed - -### no-old-contractile-formats -- description: No old .contractile or .hs files remaining -- run: test -z "$(find .machine_readable/contractiles/ \( -name '*.contractile' -o -name '*.hs' \) 2>/dev/null)" -- severity: warning -- notes: All contractiles should be .a2ml format - -## Format Duplicates - -### no-duplicate-justfile -- description: Only one Justfile (hardlinked from root to .machine_readable/contractiles/) -- run: test $(stat -c '%i' Justfile) = $(stat -c '%i' .machine_readable/contractiles/Justfile 2>/dev/null) -- severity: warning -- notes: Justfile should be hardlinked, not copied - -### no-duplicate-readme-format -- description: Only one README format in contractiles/ (.adoc canonical) -- run: test ! -f .machine_readable/contractiles/README.md -- severity: info - -## Template Hygiene - -### no-stale-template-references -- description: No references to rsr-template-repo in generic template files -- run: test -z "$(grep -r 'rsr-template-repo' machine-readable-design/ 2>/dev/null)" -- severity: warning -- notes: Generic templates should use {{PROJECT_NAME}} or similar placeholders - -### version-sync-checked -- description: Version in canonical-directory-structure matches .machine_readable/contractiles -- verification: compare version identifiers in both locations -- severity: info diff --git a/.machine_readable/integrations/feedback-o-tron.a2ml b/.machine_readable/integrations/feedback-o-tron.a2ml deleted file mode 100644 index 691bb72..0000000 --- a/.machine_readable/integrations/feedback-o-tron.a2ml +++ /dev/null @@ -1,14 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# OPTIONAL: Feedback-o-Tron Integration — Autonomous Bug Reporting -# Delete this file if your project does not use feedback-o-tron. - -[integration] -name = "feedback-o-tron" -type = "bug-reporter" -repository = "https://github.com/hyperpolymath/feedback-o-tron" - -[reporting-config] -platforms = ["github", "gitlab", "bugzilla"] -deduplication = true -audit-logging = true -auto-file-upstream = "on-external-dependency-failure" diff --git a/.machine_readable/integrations/groove.a2ml b/.machine_readable/integrations/groove.a2ml deleted file mode 100644 index ea3fb8b..0000000 --- a/.machine_readable/integrations/groove.a2ml +++ /dev/null @@ -1,38 +0,0 @@ -; SPDX-License-Identifier: MPL-2.0 -; Groove Protocol Manifest — declares API surfaces this project exposes. -; -; Consumed by the Groove bridge / zig-unified-api-adapter for snap-on/snap-off -; service discovery. Edit this file to match your project's actual APIs. -; -; See: https://github.com/hyperpolymath/standards/tree/main/groove-protocol - -(groove-manifest - (version "1.0") - - ; Service identity — replace {{REPO}} with your project name - (service "{{REPO}}") - (service-version "0.1.0") - - ; Primary port — MUST be unique across the ecosystem. - ; Check PORT-REGISTRY.md in the standards repo before assigning. - ; https://github.com/hyperpolymath/standards/blob/main/PORT-REGISTRY.md - (port 0) ; 0 = not assigned yet — run `just groove-setup` to assign - - ; API surfaces this project exposes (dodeca-API) - ; Remove lines for API types you don't use. - (api-surfaces - (rest (enabled true) (path "/api/v1")) - (grpc (enabled false) (port-offset 1)) - (graphql (enabled false) (path "/graphql")) - (websocket (enabled false) (path "/ws")) - (sse (enabled false) (path "/events")) - (groove (enabled true) (path "/.well-known/groove"))) - - ; Health endpoint — used by Groove discovery - (health "/health") - - ; Capabilities — what this service can do for others - (capabilities ()) - - ; Dependencies — what this service needs from others - (dependencies ())) diff --git a/.machine_readable/integrations/proven.a2ml b/.machine_readable/integrations/proven.a2ml deleted file mode 100644 index 96a8a7d..0000000 --- a/.machine_readable/integrations/proven.a2ml +++ /dev/null @@ -1,20 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# OPTIONAL: Proven Integration — Formally Verified Safety Library -# Delete this file if your project does not use the proven library. -# See https://github.com/hyperpolymath/proven for details. - -[integration] -name = "proven" -type = "safety-library" -repository = "https://github.com/hyperpolymath/proven" -version = "1.2.0" - -[binding-policy] -approach = "thin-ffi-wrapper" -unsafe-patterns = "replace-with-proven-equivalent" -modules-available = ["SafeMath", "SafeString", "SafeJSON", "SafeURL", "SafeRegex", "SafeSQL", "SafeFile", "SafeTemplate", "SafeCrypto"] - -[adoption-guidance] -priority = "high" -scope = "all-string-json-url-crypto-operations" -migration = "incremental — replace unsafe patterns as encountered" diff --git a/.machine_readable/integrations/verisimdb.a2ml b/.machine_readable/integrations/verisimdb.a2ml deleted file mode 100644 index 78ca1f0..0000000 --- a/.machine_readable/integrations/verisimdb.a2ml +++ /dev/null @@ -1,17 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# OPTIONAL: VeriSimDB Feed — Cross-Repo Analytics Data Store -# Delete this file if your project does not feed data to VeriSimDB. -# See https://github.com/hyperpolymath/nextgen-databases for details. - -[integration] -name = "verisimdb" -type = "data-feed" -repository = "https://github.com/hyperpolymath/nextgen-databases" -data-store = "verisimdb-data" - -[feed-config] -emit-scan-results = true -emit-build-metrics = true -emit-dependency-graph = true -format = "hexad" -destination = "verisimdb-data/feeds/" diff --git a/.machine_readable/integrations/vexometer.a2ml b/.machine_readable/integrations/vexometer.a2ml deleted file mode 100644 index 2f7ef80..0000000 --- a/.machine_readable/integrations/vexometer.a2ml +++ /dev/null @@ -1,19 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# OPTIONAL: Vexometer Integration — Irritation Surface Analysis -# Delete this file if your project does not use vexometer. - -[integration] -name = "vexometer" -type = "friction-measurement" -repository = "https://github.com/hyperpolymath/vexometer" - -[measurement-config] -dimensions = 10 -emit-isa-reports = true -lazy-eliminator = true -satellite-interventions = true - -[hooks] -cli-tools = "measure-on-error" -ui-panels = "measure-on-interaction" -build-failures = "measure-on-failure" diff --git a/.machine_readable/policies/.maintenance-perms-ignore b/.machine_readable/policies/.maintenance-perms-ignore deleted file mode 100644 index 2c8c409..0000000 --- a/.machine_readable/policies/.maintenance-perms-ignore +++ /dev/null @@ -1,5 +0,0 @@ -# Regex patterns for justified permission-policy exceptions. -# One pattern per line. -# Example: -# ^vendor/ -# ^third_party/ diff --git a/.machine_readable/policies/0.2-AI-MANIFEST.a2ml b/.machine_readable/policies/0.2-AI-MANIFEST.a2ml deleted file mode 100644 index 01a1914..0000000 --- a/.machine_readable/policies/0.2-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "policies-registry" -level: 2 -parent: "../0.1-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Sub-registry for policies metadata. diff --git a/.machine_readable/policies/MAINTENANCE-AXES.a2ml b/.machine_readable/policies/MAINTENANCE-AXES.a2ml deleted file mode 100644 index c251de6..0000000 --- a/.machine_readable/policies/MAINTENANCE-AXES.a2ml +++ /dev/null @@ -1,54 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -# -# Canonical maintenance governance model - -[metadata] -version = "1.0.0" -last-updated = "{{CURRENT_DATE}}" -scope = "repo" - -[discovery] -human-entrypoints = [ - "README.adoc", - "docs/maintenance/MAINTENANCE-CHECKLIST.md", - "docs/practice/SOFTWARE-DEVELOPMENT-APPROACH.adoc", -] -machine-entrypoints = [ - ".machine_readable/policies/MAINTENANCE-AXES.a2ml", - ".machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml", - ".machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml", - ".machine_readable/6a2/META.a2ml", - ".machine_readable/ai/README.adoc", - ".machine_readable/bot_directives/README.scm", -] -bots = ["hypatia", "gitbot-fleet", "repo visitors"] - -[axes] -axis-1 = "must > intend > like" -axis-2 = "corrective > adaptive > perfective" -axis-3 = "systems > compliance > effects" -execution-order = "axis-1 > axis-2 > axis-3" - -[axis-1-scoping] -required = true -sources = "README, roadmap, status docs, maintenance checklist, CI/security docs" -markers = "TODO/FIXME/XXX/HACK/STUB/PARTIAL" -idris-unsound-markers = "believe_me/assert_total" -output = "scoped work assembly in must/intend/like buckets" - -[axis-2-maintenance] -corrective-first = true -adaptive-second = true -adaptive-focus = "scope changes, stale references, obsolete work culling" -perfective-third = true -perfective-source = "honest state from axis-1 after corrective/adaptive updates" - -[axis-3-audit] -systems-check = true -compliance-check = true -effects-check = true -compliance-focus = "seams/compromises/exception register and anti-drift" -compliance-tooling = "panic-attack" -effects-tooling = "ecological checking with sustainabot guidance" -effects-evidence = "benchmark evidence and maintainer dialogue/status review" diff --git a/.machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml b/.machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml deleted file mode 100644 index 05bd4f6..0000000 --- a/.machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml +++ /dev/null @@ -1,159 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Cross-repo maintenance baseline (machine-readable canonical) - -[metadata] -version = "1.1.0" -last-updated = "2026-02-24" -scope = "cross-repo" -source-human = "docs/governance/MAINTENANCE-CHECKLIST.adoc" -companion-human = "docs/governance/SOFTWARE-DEVELOPMENT-APPROACH.adoc" -companion-machine = ".machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml" - -[policy] -single-source = true -notes = "Use this file as canonical machine policy and keep markdown synchronized." - -[maintenance-axes] -scoping-first = true -execution-order = ["scoping", "axis-1", "axis-2", "axis-3"] -axis-1 = "must > intend > like" -axis-2 = "corrective > adaptive > perfective" -axis-3 = "systems > compliance > effects" - -[scoping] -inputs_required = [ - "README", - "roadmap", - "status-docs", - "maintenance-checklist", - "ci-and-security-docs", -] - -marker_scan_required = [ - "TODO", - "FIXME", - "XXX", - "HACK", - "STUB", - "PARTIAL", -] - -idris_unsound_scan_required = [ - "believe_me", - "assert_total", -] - -scope_assembly_buckets = ["must", "intend", "like"] - -[axis-2-maintenance-rules] -corrective-first = true -adaptive-second = true -adaptive_examples = [ - "scope-change reconciliation", - "stale-reference removal", - "obsolete-work culling", -] -perfective-third = true -perfective_source = "axis-1 honest state after corrective/adaptive updates" - -[axis-3-audit-rules] -systems-check = true -documentation-honesty-check = true -safety-security-accounted-check = true -effects-review-check = true -benchmark-evidence-required = true -maintainer-dialogue-review-required = true -compliance-seams-check = true -exception-register-required = true -exception-bounded-scope-required = true -policy-drift-contamination-check = true -example-drift-risk = "single TypeScript exception causing broad ReScript->TypeScript migration" -compliance-tooling = "panic-attack" -effects-tooling = "ecological checking with sustainabot guidance" - -[generic-cleanup-finish-off] -root-cleanup-required = true -stale-work-cull-required = true -docs-parity-required = true -machine-human-sync-required = true -compliance-finish-off-required = true -effects-finish-off-required = true -release-prep-summary-required = true -next-actions-required = ["corrective", "adaptive", "perfective"] - -[must] -root_control_files = [ - ".gitignore", - ".gitattributes", - ".editorconfig", - ".tool-versions", - "Containerfile", - "Justfile", -] - -root_hosting_files = [ - "CNAME", - ".nojekyll", -] - -ownership_files = [ - "MAINTAINER", - ".github/CODEOWNERS", -] - -machine_readable_required = [ - ".machine_readable/6a2/anchors/ANCHOR.a2ml", - ".machine_readable/contractiles/", - ".machine_readable/ai/", - ".machine_readable/bot_directives/", -] - -contractiles_required = [ - "Mustfile", - "Trustfile", - "Intentfile", -] - -security_required = [ - ".well-known/security.txt", - "ci-security-scan", -] - -quality_gate_required = [ - "format", - "lint", - "unit-tests", - "integration-tests", - "p2p-tests", - "e2e-tests", - "bench-smoke", - "docs-check", - "security-scan", -] - -abi_ffi_policy = [ - "ABI Idris2 in src/interface/abi/*.idr", - "FFI Zig in ffi/**/*.zig", -] - -[should] -docs_primary_format = "adoc" -docs_structure = [ - "docs/theory", - "docs/practice", - "docs/whitepapers/academic", - "docs/whitepapers/industry", - "docs/proofs", - "docs/reports", -] - -root_minimization = true -well_known_metadata = true -roadmap_honesty_with_dates = true -ci_doc_format_policy = true - -[could] -generate_human_from_machine = true -mode_aware_bots = ["corrective", "adaptive", "perfective", "audit"] -topology_dashboard = true -exception_registry = true diff --git a/.machine_readable/policies/README.adoc b/.machine_readable/policies/README.adoc deleted file mode 100644 index 045e5af..0000000 --- a/.machine_readable/policies/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= policies Registry diff --git a/.machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml b/.machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml deleted file mode 100644 index d7967d2..0000000 --- a/.machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml +++ /dev/null @@ -1,53 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# General software development approach (machine-readable) - -[metadata] -version = "1.0.0" -last-updated = "2026-02-24" -scope = "cross-repo" -source-human = "docs/governance/SOFTWARE-DEVELOPMENT-APPROACH.adoc" - -[execution] -order = ["axis-1", "axis-2", "axis-3"] - -[axis-1] -name = "scope" -priority = "must > intend > like" -inputs = [ - "README", - "roadmap", - "status-docs", - "ci-and-security-docs", -] -marker-scan = ["TODO", "FIXME", "XXX", "HACK", "STUB", "PARTIAL"] -idris-unsound-scan = ["believe_me", "assert_total"] -output = "scoped-work-assembly" - -[axis-2] -name = "maintenance" -priority = "corrective > adaptive > perfective" -corrective = "defect/regression/safety/security fixes" -adaptive = "scope reconciliation, stale-reference removal, obsolete-work culling" -perfective = "quality improvements derived from axis-1 honest state" - -[axis-3] -name = "audit" -priority = "systems > compliance > effects" -systems = "required systems present and operating" -compliance = "exceptions explicit, bounded, and drift-resistant" -effects = "benchmark/operational impact evidence captured and reviewed" -compliance-tooling = "panic-attack" -effects-tooling = "ecological checking with sustainabot guidance" - -[cleanup-finish-off] -root-cleanup = true -stale-work-cull = true -docs-sync-human-machine = true -compliance-audit = true -effects-audit = true -release-summary = ["must", "should", "could"] -next-actions = ["corrective", "adaptive", "perfective"] - -[collaboration] -maintainer-dialogue-required = true -dialogue-topics = ["what changed", "why", "remaining risks"] diff --git a/.machine_readable/root-allow.txt b/.machine_readable/root-allow.txt deleted file mode 100644 index 2436e1c..0000000 --- a/.machine_readable/root-allow.txt +++ /dev/null @@ -1,66 +0,0 @@ -# Canonical root allowlist for RSR-templated repositories. -# -# Lists every entry permitted at the repository root. -# Anything tracked at root that is not in this list is drift and -# must be moved into the appropriate subdirectory (or added here -# with a justification comment). -# -# Used by: scripts/check-root-shape.sh -# Authority: TEMPLATE-STANDARDS-AUDIT.adoc, "Proposed Final Directory Map" -# -# Format: one entry per line; '#' starts a comment; trailing '/' marks a directory. -# Blank lines and comment-only lines are ignored. - -# ─── Authority files (template-mandated) ───────────────────────────────────── -README.adoc -AUDIT.adoc -EXPLAINME.adoc -AFFIRMATION.adoc # dated/signed honesty snapshot (README/EXPLAINME/AFFIRMATION trio) -0-AI-MANIFEST.a2ml # thin pointer to .machine_readable/0.1-AI-MANIFEST.a2ml -GOVERNANCE.adoc # governance model (validator accepts root or docs/governance/) -MAINTAINERS.adoc # maintainer roster -CONTRIBUTING.md # REQUIRED AT ROOT by scorecard-enforcer/openssf-compliance/quality CI (test -f, no .github fallback). The fuller copy in .github/ is GitHub's auto-discovery convention; dedupe is an owner decision (would need those CI checks updated to accept .github/). -SECURITY.md # REQUIRED AT ROOT by scorecard-enforcer CI + the security-policy contractile (test -f SECURITY.md). See CONTRIBUTING.md note re: the .github/ copy. -LICENSE -CHANGELOG.md - -# ─── Build entry points (must live at root for their tooling) ──────────────── -Justfile # delegates phases to build/just/*.just -coordination.k9 # repo-local session binding (template-mandated) -abi.ipkg # Idris2 package for the ABI seam; sourcedir=src/interface (estate canon: root-level *-abi.ipkg). Single case-consistent src/interface/Abi/ dir. Typecheck: `idris2 --typecheck abi.ipkg`. - -# ─── Conventional dotfiles (tool-required at root) ─────────────────────────── -.editorconfig -.envrc -.gitattributes -.gitignore -.tool-versions - -# ─── Directories ───────────────────────────────────────────────────────────── -.devcontainer/ # VS Code dev container spec; tool-required at root -.git/ -.github/ # CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, workflows/ -.machine_readable/ # AI manifests, contractiles, custom-format configs -.well-known/ -build/ # contractile.just, setup.sh, flake.{nix,lock}, guix.scm, .guix-channel, Containerfile -ci/ # .gitlab-ci.yml, .pre-commit-config.yaml (root shims if tools require) -docs/ # onboarding/, status/, governance/, ... -docs-template/ # template-only: scaffolding docs copied into new repos -machine-readable-design/ # template-only: design rationale for .machine_readable/ layout -session/ # dispatch.sh, custom-checks.k9, local-hooks.sh - -# Source / test / artifact trees (project-specific but conventional) -src/ -tests/ -benches/ -examples/ -features/ -scripts/ -verification/ -container/ # may host Containerfile if not at build/ - -# ─── Tolerated pending follow-up (re-evaluate when item lands) ─────────────── -.gitlab-ci.yml # TODO: relocate to ci/.gitlab-ci.yml after GitLab project-setting update -.pre-commit-config.yaml # TODO: relocate to ci/.pre-commit-config.yaml after invocation pattern decided -affinescript/ # AffineScript source subtree consumed by this template -tools/ # TODO: consolidate with scripts/ or document the split (pending decision) diff --git a/.machine_readable/scripts/0.2-AI-MANIFEST.a2ml b/.machine_readable/scripts/0.2-AI-MANIFEST.a2ml deleted file mode 100644 index 615df84..0000000 --- a/.machine_readable/scripts/0.2-AI-MANIFEST.a2ml +++ /dev/null @@ -1,18 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "automation-scripts-unit" -level: 2 -parent: "../0.1-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Internal automation logic for the project lifecycle, forge sync, - verification triggers, and maintenance. - -canonical_locations: - maintenance: "maintenance/" - lifecycle: "lifecycle/" - forge: "forge/" - verification: "verification/" diff --git a/.machine_readable/scripts/forge/0.3-AI-MANIFEST.a2ml b/.machine_readable/scripts/forge/0.3-AI-MANIFEST.a2ml deleted file mode 100644 index 4bbd6cf..0000000 --- a/.machine_readable/scripts/forge/0.3-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "automation-unit-forge" -level: 3 -parent: "../0.2-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Internal automation logic for project forge. diff --git a/.machine_readable/scripts/forge/README.adoc b/.machine_readable/scripts/forge/README.adoc deleted file mode 100644 index a43f1d2..0000000 --- a/.machine_readable/scripts/forge/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Forge Scripts diff --git a/.machine_readable/scripts/forge/forge-sync.sh b/.machine_readable/scripts/forge/forge-sync.sh deleted file mode 100755 index 330e54b..0000000 --- a/.machine_readable/scripts/forge/forge-sync.sh +++ /dev/null @@ -1,25 +0,0 @@ -#!/usr/bin/env bash -# SPDX-License-Identifier: MPL-2.0 -# -# forge-sync.sh — Multi-forge mirroring script -# -# Synchronises the local repository with GitHub, GitLab, and Codeberg. -# Usage: ./forge-sync.sh - -set -euo pipefail - -REMOTES=("origin" "gitlab" "codeberg") - -echo "=== RSR Forge Synchronisation ===" - -for remote in "${REMOTES[@]}"; do - if git remote | grep -q "^$remote$"; then - echo "Pushing to $remote..." - git push "$remote" --all - git push "$remote" --tags - else - echo "Skip: Remote '$remote' not configured." - fi -done - -echo "Sync complete." diff --git a/.machine_readable/scripts/forge/git-cleanup.sh b/.machine_readable/scripts/forge/git-cleanup.sh deleted file mode 100755 index 4fec1a2..0000000 --- a/.machine_readable/scripts/forge/git-cleanup.sh +++ /dev/null @@ -1,8 +0,0 @@ -#!/usr/bin/env bash -# git-cleanup.sh — Repository hygiene script -set -euo pipefail -echo "Cleaning up merged branches..." -git fetch -p -git branch --merged | grep -v "\*" | grep -v "main" | xargs -n 1 git branch -d || echo "No branches to clean." -echo "Pruning remote tracking branches..." -git remote prune origin diff --git a/.machine_readable/scripts/lifecycle/0.3-AI-MANIFEST.a2ml b/.machine_readable/scripts/lifecycle/0.3-AI-MANIFEST.a2ml deleted file mode 100644 index 3182d17..0000000 --- a/.machine_readable/scripts/lifecycle/0.3-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "automation-unit-lifecycle" -level: 3 -parent: "../0.2-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Internal automation logic for project lifecycle. diff --git a/.machine_readable/scripts/lifecycle/README.adoc b/.machine_readable/scripts/lifecycle/README.adoc deleted file mode 100644 index 481283e..0000000 --- a/.machine_readable/scripts/lifecycle/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Lifecycle Scripts diff --git a/.machine_readable/scripts/lifecycle/install-tools.sh b/.machine_readable/scripts/lifecycle/install-tools.sh deleted file mode 100755 index 408df64..0000000 --- a/.machine_readable/scripts/lifecycle/install-tools.sh +++ /dev/null @@ -1,27 +0,0 @@ -#!/usr/bin/env bash -# SPDX-License-Identifier: MPL-2.0 -# -# install-tools.sh — Developer toolchain installer -# -# Detects and installs the required project toolchain (asdf, nix, or guix). - -set -euo pipefail - -echo "=== RSR Toolchain Installer ===" - -if [ -f "flake.nix" ] && command -v nix &>/dev/null; then - echo "Nix detected. Setting up development shell..." - nix develop --command echo "Nix shell verified." -elif [ -f ".tool-versions" ] && command -v asdf &>/dev/null; then - echo "asdf detected. Installing plugins and tools..." - while read -r line; do - plugin=$(echo "$line" | awk '{print $1}') - asdf plugin add "$plugin" || true - done < .tool-versions - asdf install -else - echo "No standard toolchain (Nix/asdf) detected or installed." - echo "Please refer to README.adoc for manual setup instructions." -fi - -echo "Installer complete." diff --git a/.machine_readable/scripts/maintenance/maint-assault.sh b/.machine_readable/scripts/maintenance/maint-assault.sh deleted file mode 100644 index f170cab..0000000 --- a/.machine_readable/scripts/maintenance/maint-assault.sh +++ /dev/null @@ -1,44 +0,0 @@ -#!/usr/bin/env bash -# SPDX-License-Identifier: MPL-2.0 -# -# maint-assault.sh — High-rigor stress testing using panic-attacker -# -# This script runs a full assault (static + dynamic) on the project binary -# to detect logic-based bug signatures and environmental vulnerabilities. - -set -euo pipefail - -BINARY_NAME="{{project}}" -REPORT_PATH="docs/reports/security/assault-latest.json" -PA_BIN="${PANIC_ATTACK_BIN:-panic-attack}" - -echo "=== High-Rigor Security Assault ===" - -# 1. Verify environment -if ! command -v "$PA_BIN" &>/dev/null; then - echo "Error: panic-attack tool not found." - echo "Please install it or set PANIC_ATTACK_BIN environment variable." - exit 1 -fi - -if [ ! -f "target/release/$BINARY_NAME" ]; then - echo "Warning: Release binary not found at target/release/$BINARY_NAME" - echo "Running build first..." - just build --release -fi - -# 2. Run Assault -echo "Initiating full assault on $BINARY_NAME..." -mkdir -p "$(dirname "$REPORT_PATH")" - -"$PA_BIN" assault "target/release/$BINARY_NAME" - --source . - --intensity medium - --duration 10 - --output "$REPORT_PATH" - -echo "" -echo "=== Assault Complete ===" -echo "Report generated: $REPORT_PATH" -echo "To review interactively, run:" -echo " $PA_BIN tui $REPORT_PATH" diff --git a/.machine_readable/scripts/verification/0.3-AI-MANIFEST.a2ml b/.machine_readable/scripts/verification/0.3-AI-MANIFEST.a2ml deleted file mode 100644 index 460e069..0000000 --- a/.machine_readable/scripts/verification/0.3-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "automation-unit-verification" -level: 3 -parent: "../0.2-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Internal automation logic for project verification. diff --git a/.machine_readable/scripts/verification/README.adoc b/.machine_readable/scripts/verification/README.adoc deleted file mode 100644 index 19fcf01..0000000 --- a/.machine_readable/scripts/verification/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Verification Scripts diff --git a/.machine_readable/self-validating/README.adoc b/.machine_readable/self-validating/README.adoc deleted file mode 100644 index 44a538f..0000000 --- a/.machine_readable/self-validating/README.adoc +++ /dev/null @@ -1,178 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= K9 Contractiles -:toc: left -:icons: font - -== What Are K9 Contractiles? - -K9 contractiles are self-validating components that combine configuration, validation, and deployment logic in a single file format. They implement the RSR principle of "self-describing artifacts" by embedding contracts and orchestration directly in the component. - -== The Three Security Levels - -K9 components declare their trust requirements using "The Leash" security model: - -[horizontal] -`'Kennel`:: Pure data, no execution (safest) -`'Yard`:: Nickel evaluation with contracts (medium trust) -`'Hunt`:: Full execution with Just recipes (requires signature) - -== Example Components - -This directory contains example K9 contractiles for common repository tasks: - -=== Kennel Level (Pure Data) - -**File:** `examples/project-metadata.k9.ncl` - -Pure configuration data with no execution. Safe to include in any repository. - -**Use cases:** -- Project metadata (name, version, description) -- Build configuration -- Tool settings -- Data schemas - -**Security:** No signature required, data-only. - -=== Yard Level (Validated Config) - -**File:** `examples/ci-config.k9.ncl` - -Configuration with Nickel contracts for runtime validation. Evaluated safely without I/O. - -**Use cases:** -- CI/CD configuration with validation -- Deployment parameters -- Database schemas with constraints -- API specifications - -**Security:** Signature recommended, Nickel evaluation only. - -=== Hunt Level (Full Execution) - -**File:** `examples/setup-repo.k9.ncl` - -Full execution with Just recipes. Can run shell commands and modify filesystem. - -**Use cases:** -- Repository setup scripts -- Deployment automation -- System configuration -- Package installation - -**Security:** **Signature required**, full system access. - -== Usage in Your Repository - -=== 1. Create K9 Components - -Choose the appropriate security level for your use case: - -[source,bash] ----- -# Kennel: Pure configuration -cp .machine_readable/contractiles/k9/examples/project-metadata.k9.ncl config/metadata.k9.ncl - -# Yard: Validated configuration -cp .machine_readable/contractiles/k9/examples/ci-config.k9.ncl .github/ci.k9.ncl - -# Hunt: Full automation -cp .machine_readable/contractiles/k9/examples/setup-repo.k9.ncl scripts/setup.k9.ncl ----- - -=== 2. Validate Components - -[source,bash] ----- -# Validate Nickel syntax and contracts -nickel typecheck config/metadata.k9.ncl - -# Verify Hunt-level signature (if signed) -./must verify scripts/setup.k9.ncl ----- - -=== 3. Execute Components - -[source,bash] ----- -# Kennel: Export as JSON -nickel export config/metadata.k9.ncl > metadata.json - -# Yard: Evaluate with validation -nickel eval .github/ci.k9.ncl - -# Hunt: Run with Just (dry-run first!) -./must --dry-run run scripts/setup.k9.ncl -./must run scripts/setup.k9.ncl ----- - -== Integration with RSR - -K9 contractiles integrate with other RSR standards: - -**STATE.a2ml**:: K9 components can generate or validate STATE.a2ml -**ECOSYSTEM.a2ml**:: K9 can automate cross-repo operations -**META.a2ml**:: K9 can enforce architectural decisions - -== Security Best Practices - -=== For Kennel/Yard Components - -✅ **Safe to use without signatures** + -✅ **Review Nickel code before use** + -✅ **Validate contracts match expectations** - -=== For Hunt Components - -⚠️ **ALWAYS verify signatures** + -⚠️ **Review Just recipes carefully** + -⚠️ **Run dry-run mode first** + -⚠️ **Never run as root unless required** + -⚠️ **Sandbox external components** - -**See:** https://github.com/{{OWNER}}/k9-svc/blob/main/docs/SECURITY-BEST-PRACTICES.adoc - -== Template Files - -Use these as starting points for your own K9 components: - -- `template-kennel.k9.ncl` - Pure data template -- `template-yard.k9.ncl` - Validated config template -- `template-hunt.k9.ncl` - Full execution template - -== Dependencies - -To use K9 contractiles in your repository: - -[source,bash] ----- -# Install Nickel (configuration language) -curl -L https://github.com/tweag/nickel/releases/latest/download/nickel-linux-x86_64 -o nickel -chmod +x nickel && sudo mv nickel /usr/local/bin/ - -# Install Just (task runner, for Hunt level) -cargo install just - -# Clone K9-SVC (for must shim and tooling) -git clone https://github.com/{{OWNER}}/k9-svc.git ----- - -== Learn More - -- **K9-SVC Specification:** https://github.com/{{OWNER}}/k9-svc/blob/main/SPEC.adoc -- **K9 User Guide:** https://github.com/{{OWNER}}/k9-svc/blob/main/GUIDE.adoc -- **Security Documentation:** https://github.com/{{OWNER}}/k9-svc/blob/main/docs/SECURITY-FAQ.adoc -- **IANA Media Type:** `application/vnd.k9+nickel` - -== Contributing - -When adding K9 contractiles to your repository: - -1. Use appropriate security level (Kennel > Yard > Hunt) -2. Document what each component does -3. Include validation contracts in Yard/Hunt components -4. Sign Hunt-level components before committing -5. Add K9 validation to CI/CD pipeline - -**Questions?** Open an issue on https://github.com/{{OWNER}}/k9-svc diff --git a/.machine_readable/self-validating/examples/ci-config.k9.ncl b/.machine_readable/self-validating/examples/ci-config.k9.ncl deleted file mode 100644 index 1f38e2d..0000000 --- a/.machine_readable/self-validating/examples/ci-config.k9.ncl +++ /dev/null @@ -1,126 +0,0 @@ -K9! -# SPDX-License-Identifier: MPL-2.0 -# Example Yard-level K9 component: CI/CD configuration with validation -# Security Level: Yard (Nickel evaluation, contract validation) -# Signature recommended but not required - -{ - pedigree = { - schema_version = "1.0.0", - component_type = "ci-configuration", - security = { - leash = 'Yard, - trust_level = "validated-config", - allow_network = false, - allow_filesystem_write = false, - allow_subprocess = false, - }, - metadata = { - name = "ci-config", - version = "1.0.0", - description = "CI/CD configuration with runtime validation", - author = "{{AUTHOR}} <{{AUTHOR_EMAIL}}>", - }, - }, - - # CI/CD configuration with Nickel contracts - ci = { - # Platform must be a known CI provider - platform - | [| 'GitHubActions, 'GitLabCI, 'CircleCI, 'TravisCI |] - = 'GitHubActions, - - # Build matrix with validation - matrix = { - # Operating systems to test on - os - | Array String - | std.array.NonEmpty - = ["ubuntu-latest", "macos-latest"], - - # Language versions to test - versions - | Array String - | std.array.NonEmpty - = ["stable", "beta"], - }, - - # Workflow steps with validation - steps = [ - { - name = "Checkout", - action = "actions/checkout@v4", - # Version must be SHA-pinned for security - sha | String | std.string.NonEmpty = "b4ffde65f46336ab88eb53be808477a3936bae11", - }, - { - name = "Build", - run = "just build", - }, - { - name = "Test", - run = "just test", - }, - { - name = "Lint", - run = "just lint", - }, - ], - - # Deployment configuration - deploy = { - enabled | Bool = false, - - # Only deploy from main branch - branch - | String - | std.contract.from_predicate (fun b => b == "main" || b == "master") - = "main", - - # Deployment requires manual approval - requires_approval | Bool = true, - }, - - # Security scanning - security = { - enabled | Bool = true, - - scanners = [ - { - name = "CodeQL", - languages = ["rust", "javascript"], - }, - { - name = "OSSF Scorecard", - enabled = true, - }, - { - name = "TruffleHog", - scan_for = "secrets", - }, - ], - }, - - # Notification settings - notifications = { - on_success = "never", - on_failure = "always", - channels = ["email"], - }, - }, - - # Validation rules (enforced by Nickel) - validation = { - # At least one OS must be specified - check_os = std.array.length ci.matrix.os > 0, - - # At least one version must be tested - check_versions = std.array.length ci.matrix.versions > 0, - - # Must have at least build and test steps - check_steps = std.array.length ci.steps >= 2, - - # Security scanning must be enabled - check_security = ci.security.enabled == true, - }, -} diff --git a/.machine_readable/self-validating/examples/project-metadata.k9.ncl b/.machine_readable/self-validating/examples/project-metadata.k9.ncl deleted file mode 100644 index c8e6ebf..0000000 --- a/.machine_readable/self-validating/examples/project-metadata.k9.ncl +++ /dev/null @@ -1,57 +0,0 @@ -K9! -# SPDX-License-Identifier: MPL-2.0 -# Example Kennel-level K9 component: Project metadata -# Security Level: Kennel (pure data, no execution) -# No signature required - -{ - pedigree = { - schema_version = "1.0.0", - component_type = "project-metadata", - security = { - leash = 'Kennel, - trust_level = "data-only", - allow_network = false, - allow_filesystem_write = false, - allow_subprocess = false, - }, - metadata = { - name = "project-metadata", - version = "1.0.0", - description = "Pure data configuration for project metadata", - author = "{{AUTHOR}} <{{AUTHOR_EMAIL}}>", - }, - }, - - # Project configuration - project = { - name = "my-project", - version = "0.1.0", - description = "A project following Rhodium Standard Repositories", - - repository = { - url = "https://github.com/{{OWNER}}/my-project", - type = "git", - }, - - author = { - name = "{{AUTHOR}}", - email = "{{AUTHOR_EMAIL}}", - organization = "{{AUTHOR_ORG}}", - }, - - license = "MPL-2.0", - - keywords = [ - "rhodium-standard", - "rsr", - "{{OWNER}}", - ], - }, - - # Export as JSON for other tools - export = { - format = "json", - destination = "project-metadata.json", - }, -} diff --git a/.machine_readable/self-validating/examples/setup-repo.k9.ncl b/.machine_readable/self-validating/examples/setup-repo.k9.ncl deleted file mode 100644 index df79a55..0000000 --- a/.machine_readable/self-validating/examples/setup-repo.k9.ncl +++ /dev/null @@ -1,167 +0,0 @@ -K9! -# SPDX-License-Identifier: MPL-2.0 -# Example Hunt-level K9 component: Repository setup automation -# Security Level: Hunt (full execution with Just recipes) -# ⚠️ SIGNATURE REQUIRED - DO NOT RUN WITHOUT VERIFICATION - -{ - pedigree = { - schema_version = "1.0.0", - component_type = "repository-setup", - security = { - leash = 'Hunt, - trust_level = "full-system-access", - allow_network = true, - allow_filesystem_write = true, - allow_subprocess = true, - signature_required = true, - }, - metadata = { - name = "setup-repo", - version = "1.0.0", - description = "Automated repository setup with RSR standards", - author = "{{AUTHOR}} <{{AUTHOR_EMAIL}}>", - }, - warnings = [ - "This component has full system access", - "Only run from trusted sources with verified signatures", - "Review Just recipes before execution", - "Use dry-run mode first: ./must --dry-run run setup-repo.k9.ncl", - ], - }, - - # Configuration with contracts - config = { - repo_name - | String - | std.string.NonEmpty - = "my-new-repo", - - repo_type - | [| 'Library, 'Application, 'Tool, 'Specification |] - = 'Application, - - primary_language - | String - | std.string.NonEmpty - = "rust", - - # RSR compliance features to enable - features = { - checkpoint_files | Bool = true, # STATE.a2ml, ECOSYSTEM.a2ml, META.a2ml - security_workflows | Bool = true, # CodeQL, Scorecard, etc. - quality_checks | Bool = true, # Linting, formatting - mirroring | Bool = false, # GitLab/Bitbucket mirrors - }, - - # Git configuration - git = { - default_branch = "main", - initial_commit | Bool = true, - remote_url | String = "", - }, - }, - - # Just recipes for execution - # These run when: ./must run setup-repo.k9.ncl - recipes = { - # Main entry point - default = { - recipe = "setup", - description = "Set up RSR-compliant repository", - }, - - # Individual setup tasks - setup = { - dependencies = ["check-env", "create-structure", "init-git", "setup-workflows"], - commands = [ - "echo '✅ Repository setup complete!'", - "echo 'Run: git status to see changes'", - ], - }, - - "check-env" = { - description = "Verify required tools are installed", - commands = [ - "command -v git || (echo 'ERROR: git not found' && exit 1)", - "command -v just || (echo 'ERROR: just not found' && exit 1)", - "command -v nickel || (echo 'ERROR: nickel not found' && exit 1)", - "echo '✓ All required tools present'", - ], - }, - - "create-structure" = { - description = "Create RSR directory structure", - commands = [ - "mkdir -p src/ docs/ tests/ scripts/", - "mkdir -p .github/workflows/", - "mkdir -p .machine_readable/contractiles/k9/", - "echo '✓ Directory structure created'", - ], - }, - - "init-git" = { - description = "Initialize Git repository", - commands = [ - "git init -b %{config.git.default_branch}", - "git config user.name '{{AUTHOR}}'", - "git config user.email '{{AUTHOR_EMAIL}}'", - "echo '✓ Git initialized'", - ], - }, - - "setup-workflows" = { - description = "Add RSR-compliant workflows", - commands = [ - # This would copy workflow templates - # In a real implementation, would fetch from rsr-template-repo - "echo '✓ Workflows configured'", - ], - }, - - "create-checkpoint-files" = { - description = "Create STATE.a2ml, ECOSYSTEM.a2ml, META.a2ml", - commands = [ - "echo '(state (version \"1.0.0\") (project \"%{config.repo_name}\"))' > STATE.a2ml", - "echo '(ecosystem (version \"1.0.0\") (name \"%{config.repo_name}\"))' > ECOSYSTEM.a2ml", - "echo '(meta (version \"1.0.0\") (project \"%{config.repo_name}\"))' > META.a2ml", - "echo '✓ Checkpoint files created'", - ], - }, - - "add-license" = { - description = "Add PMPL-1.0 license", - commands = [ - "curl -sL https://raw.githubusercontent.com/{{OWNER}}/pmpl/main/LICENSE -o LICENSE", - "echo '✓ License added'", - ], - }, - - "add-readme" = { - description = "Create README.adoc from template", - commands = [ - "echo '= %{config.repo_name}' > README.adoc", - "echo '' >> README.adoc", - "echo 'Part of the Hyperpolymath ecosystem.' >> README.adoc", - "echo '✓ README created'", - ], - }, - - clean = { - description = "Remove generated files (careful!)", - commands = [ - "echo '⚠️ This will delete all generated files'", - "echo 'Press Ctrl+C to cancel, or wait 5 seconds...'", - "sleep 5", - "rm -f STATE.a2ml ECOSYSTEM.a2ml META.a2ml", - "echo '✓ Cleaned'", - ], - }, - }, - - # Validation (Yard-level checks before Hunt execution) - validation = { - check_repo_name = std.string.length config.repo_name > 0, - check_language = std.string.length config.primary_language > 0, - }, -} diff --git a/.machine_readable/self-validating/methodology-guard.k9.ncl b/.machine_readable/self-validating/methodology-guard.k9.ncl deleted file mode 100644 index 4c43325..0000000 --- a/.machine_readable/self-validating/methodology-guard.k9.ncl +++ /dev/null @@ -1,67 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -# -# K9 Validator: Methodology Guard -# Checks that agent work respects methodology constraints declared in -# bot_directives/methodology.a2ml. -# -# Usage: k9 validate methodology-guard - -let methodology_guard = { - name = "methodology-guard", - version = "1.0.0", - description = "Validates that agent work respects declared methodology constraints", - - checks = { - divergent_invariant_language = { - description = "No files in languages violating the divergent language invariant", - severity = "error", - # When methodology.divergent-invariants.language-invariant is set, - # check that no new files introduce a different language for that purpose. - # Example: if language-invariant = "idris2", reject new .lean or .v files - # in the proof directories. - check_type = "file-extension-guard", - scope = "src/", - }, - - believe_me_ceiling = { - description = "believe_me count must not exceed declared ceiling", - severity = "error", - pattern = "believe_me", - ceiling_key = "methodology.divergent-invariants.believe-me-ceiling", - default_ceiling = 0, - }, - - assert_total_ceiling = { - description = "assert_total count must not exceed declared ceiling", - severity = "error", - pattern = "assert_total", - ceiling_key = "methodology.divergent-invariants.assert-total-ceiling", - default_ceiling = 0, - }, - - state_not_template = { - description = "STATE.a2ml must not contain template placeholders", - severity = "warning", - file = ".machine_readable/6a2/STATE.a2ml", - # NOTE: the PROJECT token below is written as a Nickel concat - # ("{{" ++ "PROJECT}}") ON PURPOSE. `just init` runs a sed substitution for - # the brace-PROJECT-brace token over EVERY text file, which would otherwise - # rewrite this guard's own pattern into the consumer's name and break the - # check. Splitting the literal across "++" keeps the contiguous token text - # out of the file (in this comment too) so init cannot match it, while - # Nickel still evaluates the element back to the full token. Do not - # "simplify" it to a plain string. (The PLACEHOLDER token and - # "rsr-template-repo" are not init tokens, so they survive as-is.) - reject_patterns = ["{{PLACEHOLDER}}", "{{" ++ "PROJECT}}", "rsr-template-repo"], - }, - - coverage_updated = { - description = "coverage.a2ml should be updated within 30 days", - severity = "info", - file = ".machine_readable/bot_directives/coverage.a2ml", - staleness_days = 30, - }, - }, -} -in methodology_guard diff --git a/.machine_readable/self-validating/template-hunt.k9.ncl b/.machine_readable/self-validating/template-hunt.k9.ncl deleted file mode 100644 index a9cc350..0000000 --- a/.machine_readable/self-validating/template-hunt.k9.ncl +++ /dev/null @@ -1,136 +0,0 @@ -K9! -# SPDX-License-Identifier: MPL-2.0 -# K9 Hunt-level template: Full execution with Just recipes -# Security Level: Hunt (full system access) -# ⚠️ SIGNATURE REQUIRED - Review carefully before use - -{ - pedigree = { - schema_version = "1.0.0", - component_type = "TODO: describe component type (e.g., 'deployment', 'setup-script')", - security = { - leash = 'Hunt, - trust_level = "full-system-access", - allow_network = true, - allow_filesystem_write = true, - allow_subprocess = true, - signature_required = true, - }, - metadata = { - name = "TODO: component-name", - version = "1.0.0", - description = "TODO: Detailed description of what this component does", - author = "{{AUTHOR}} <{{AUTHOR_EMAIL}}>", - }, - warnings = [ - "This component has full system access", - "Only run from trusted sources with verified signatures", - "Review all Just recipes before execution", - "Use dry-run mode first: ./must --dry-run run your-file.k9.ncl", - ], - side_effects = [ - "TODO: List what files/directories this creates or modifies", - "TODO: List what commands this executes", - "TODO: List what network access this requires", - ], - }, - - # Configuration with contracts (Yard-level validation) - config = { - # Add your configuration here with appropriate contracts - target_dir - | String - | std.string.NonEmpty - = "/tmp/k9-output", - - dry_run | Bool = false, - - # Add more config as needed - }, - - # Just recipes for execution - # These run when: ./must run your-file.k9.ncl - recipes = { - # Main entry point (runs by default) - default = { - recipe = "TODO: main-task", - description = "TODO: What the default recipe does", - }, - - # Define your recipes here - "main-task" = { - dependencies = ["check-prerequisites"], - commands = [ - "echo 'TODO: Add your commands here'", - # Example: Create directory - # "mkdir -p %{config.target_dir}", - # Example: Run a command - # "just build", - # Example: Conditional execution - # "@if [ \"%{config.dry_run}\" = \"true\" ]; then echo '[DRY-RUN] Would execute'; else actual-command; fi", - ], - }, - - "check-prerequisites" = { - description = "Verify required tools and permissions", - commands = [ - # Example: Check for required tools - # "command -v git || (echo 'ERROR: git not found' && exit 1)", - # Example: Check permissions - # "[ -w %{config.target_dir} ] || (echo 'ERROR: Cannot write to target directory' && exit 1)", - "echo '✓ Prerequisites checked'", - ], - }, - - # Add more recipes as needed - "build" = { - description = "Build the project", - commands = [ - "echo 'TODO: Add build commands'", - ], - }, - - "deploy" = { - description = "Deploy the application", - dependencies = ["build"], - commands = [ - "echo 'TODO: Add deployment commands'", - ], - }, - - "clean" = { - description = "Clean up generated files", - commands = [ - "echo '⚠️ This will delete files - waiting 3 seconds...'", - "sleep 3", - "echo 'TODO: Add cleanup commands'", - # "rm -rf %{config.target_dir}", - ], - }, - }, - - # Validation (Yard-level checks before Hunt execution) - validation = { - check_target_dir = std.string.length config.target_dir > 0, - # Add more validation as needed - }, -} - -# Usage: -# 1. Fill in TODO items above -# 2. Define configuration with contracts -# 3. Implement Just recipes with your commands -# 4. Test with dry-run: ./must --dry-run run your-file.k9.ncl -# 5. Review dry-run output carefully -# 6. Sign the component: ./must sign your-file.k9.ncl -# 7. Distribute with signature: your-file.k9.ncl.sig -# 8. Users verify and run: ./must verify && ./must run your-file.k9.ncl -# -# Security checklist: -# ✓ All TODO items filled in -# ✓ side_effects documented accurately -# ✓ Commands reviewed for safety -# ✓ No hardcoded secrets or credentials -# ✓ Proper error handling in recipes -# ✓ Tested in dry-run mode -# ✓ Component signed with trusted key diff --git a/.machine_readable/self-validating/template-kennel.k9.ncl b/.machine_readable/self-validating/template-kennel.k9.ncl deleted file mode 100644 index fa7e3f3..0000000 --- a/.machine_readable/self-validating/template-kennel.k9.ncl +++ /dev/null @@ -1,54 +0,0 @@ -K9! -# SPDX-License-Identifier: MPL-2.0 -# K9 Kennel-level template: Pure data configuration -# Security Level: Kennel (data-only, no execution) -# No signature required - safe for any use - -{ - pedigree = { - schema_version = "1.0.0", - component_type = "TODO: describe component type (e.g., 'build-config', 'metadata')", - security = { - leash = 'Kennel, - trust_level = "data-only", - allow_network = false, - allow_filesystem_write = false, - allow_subprocess = false, - }, - metadata = { - name = "TODO: component-name", - version = "1.0.0", - description = "TODO: Brief description of what this component contains", - author = "{{AUTHOR}} <{{AUTHOR_EMAIL}}>", - }, - }, - - # Your configuration data here - config = { - # Example: Pure data values - setting_1 = "value", - setting_2 = 42, - setting_3 = true, - - nested = { - key = "value", - }, - - list = [ - "item1", - "item2", - ], - }, - - # Optional: Export format specification - export = { - format = "json", # or "yaml", "toml" - destination = "output.json", - }, -} - -# Usage: -# 1. Fill in TODO items above -# 2. Add your configuration data to config = { ... } -# 3. Validate: nickel typecheck your-file.k9.ncl -# 4. Export: nickel export your-file.k9.ncl > output.json diff --git a/.machine_readable/self-validating/template-yard.k9.ncl b/.machine_readable/self-validating/template-yard.k9.ncl deleted file mode 100644 index 358671c..0000000 --- a/.machine_readable/self-validating/template-yard.k9.ncl +++ /dev/null @@ -1,84 +0,0 @@ -K9! -# SPDX-License-Identifier: MPL-2.0 -# K9 Yard-level template: Configuration with validation -# Security Level: Yard (Nickel evaluation with contracts) -# Signature recommended but not required - -{ - pedigree = { - schema_version = "1.0.0", - component_type = "TODO: describe component type (e.g., 'validated-config', 'schema')", - security = { - leash = 'Yard, - trust_level = "validated-config", - allow_network = false, - allow_filesystem_write = false, - allow_subprocess = false, - }, - metadata = { - name = "TODO: component-name", - version = "1.0.0", - description = "TODO: Brief description with validation details", - author = "{{AUTHOR}} <{{AUTHOR_EMAIL}}>", - }, - }, - - # Configuration with Nickel contracts for validation - config = { - # Example: String that cannot be empty - name - | String - | std.string.NonEmpty - = "TODO: default value", - - # Example: Number with range constraint - port - | Number - | std.contract.from_predicate (fun p => p > 0 && p < 65536) - = 8080, - - # Example: Boolean flag - enabled | Bool = true, - - # Example: Enum (one of several values) - environment - | [| 'Development, 'Staging, 'Production |] - = 'Development, - - # Example: List with non-empty constraint - items - | Array String - | std.array.NonEmpty - = ["item1", "item2"], - - # Example: Nested object with contracts - database = { - host | String | std.string.NonEmpty = "localhost", - port | Number | std.contract.from_predicate (fun p => p > 0 && p < 65536) = 5432, - name | String | std.string.NonEmpty = "mydb", - }, - }, - - # Validation rules (additional cross-field checks) - validation = { - # Example: Check that at least one item exists - check_items = std.array.length config.items > 0, - - # Example: Check that production has secure settings - check_production = - if config.environment == 'Production then - config.enabled == true - else - true, - - # Add your custom validation rules here - }, -} - -# Usage: -# 1. Fill in TODO items above -# 2. Define your config with appropriate contracts -# 3. Add validation rules in validation = { ... } -# 4. Validate: nickel typecheck your-file.k9.ncl -# 5. Evaluate: nickel eval your-file.k9.ncl -# 6. If validation passes, use in your application diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml deleted file mode 100644 index b048d1c..0000000 --- a/.pre-commit-config.yaml +++ /dev/null @@ -1,50 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Pre-commit hooks for hyperpolymath RSR repos. -# Install: pip install pre-commit && pre-commit install -# Run manually: pre-commit run --all-files - -repos: - # --- Standard hooks --- - - repo: https://github.com/pre-commit/pre-commit-hooks - rev: v5.0.0 - hooks: - - id: trailing-whitespace - - id: end-of-file-fixer - - id: check-yaml - - id: check-json - - id: check-toml - - id: check-merge-conflict - - id: detect-private-key - - id: check-added-large-files - args: ['--maxkb=1024'] - - # --- A2ML manifest validation --- - - repo: https://github.com/hyperpolymath/a2ml-pre-commit - rev: main - hooks: - - id: validate-a2ml - name: Validate A2ML manifests - - # --- K9 contract validation --- - - repo: https://github.com/hyperpolymath/k9-pre-commit - rev: main - hooks: - - id: validate-k9 - name: Validate K9 contracts - - # --- Shell linting --- - - repo: https://github.com/shellcheck-py/shellcheck-py - rev: v0.10.0.1 - hooks: - - id: shellcheck - - # --- EditorConfig --- - - repo: https://github.com/editorconfig-checker/editorconfig-checker.python - rev: 3.2.1 - hooks: - - id: editorconfig-checker - exclude: '(\.git|node_modules|target|_build|deps|\.deno|external_corpora|\.lake)/' - - # --- Secret detection --- - rev: v8.24.3 - hooks: diff --git a/.tool-versions b/.tool-versions deleted file mode 100644 index ce60c32..0000000 --- a/.tool-versions +++ /dev/null @@ -1,10 +0,0 @@ -# Uncomment and customize for your project -# rust nightly -# just 1.40.0 -# nickel 1.10.0 -# gleam 1.8.0 -# elixir 1.18.0 -# erlang 27.2 -# zig 0.14.0 -# idris2 0.7.0 -rust nightly diff --git a/.well-known/ai.txt b/.well-known/ai.txt deleted file mode 100644 index 334b406..0000000 --- a/.well-known/ai.txt +++ /dev/null @@ -1,18 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# ai.txt - AI interaction policy -# See: https://site.spawning.ai/spawning-ai-txt - -User-Agent: * -Disallow-Training: yes -Disallow-Summarization: no -Disallow-Generation: yes - -# This project's code is licensed under MPL-2.0. -# AI agents may read and analyze this code for assisting contributors. -# AI agents must NOT use this code for model training without explicit consent. -# AI agents must preserve Emotional Lineage per PMPL Section 3. -# -# For AI agent integration instructions, see: -# 0-AI-MANIFEST.a2ml (universal AI entry point) -# AI.a2ml (Claude-specific instructions) -# .machine_readable/ (structured project state) diff --git a/.well-known/humans.txt b/.well-known/humans.txt deleted file mode 100644 index e062f4b..0000000 --- a/.well-known/humans.txt +++ /dev/null @@ -1,14 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# humanstxt.org - -/* TEAM */ -Maintainer: {{AUTHOR}} ({{OWNER}}) -Contact: {{AUTHOR_EMAIL}} -From: United Kingdom - -/* SITE */ -Last update: {{CURRENT_DATE}} -Standards: RSR (Rhodium Standard Repository) -License: MPL-2.0 (Palimpsest MPL) -Components: Idris2 ABI, Zig FFI -Tools: just, Podman, Guix diff --git a/.well-known/security.txt b/.well-known/security.txt deleted file mode 100644 index 5414d50..0000000 --- a/.well-known/security.txt +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# RFC 9116 - security.txt -# https://securitytxt.org/ - -Contact: mailto:{{SECURITY_EMAIL}} -Expires: {{CURRENT_YEAR}}-12-31T23:59:59.000Z -Encryption: {{PGP_KEY_URL}} -Preferred-Languages: en -Canonical: https://{{FORGE}}/{{OWNER}}/{{REPO}}/.well-known/security.txt -Policy: https://{{FORGE}}/{{OWNER}}/{{REPO}}/blob/main/SECURITY.md -Hiring: https://{{WEBSITE}}/careers diff --git a/0-AI-MANIFEST.a2ml b/0-AI-MANIFEST.a2ml deleted file mode 100644 index 68aad8c..0000000 --- a/0-AI-MANIFEST.a2ml +++ /dev/null @@ -1,34 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# AI-MANIFEST.a2ml — AI agent work allocation and policy -# -[metadata] -version = "0.1.0" -last-updated = "{{CURRENT_DATE}}" - -[project] -name = "[YOUR-REPO-NAME]" -purpose = "{{PROJECT_DESCRIPTION}}" - -[ai-allocation] -agents = [ - { name = "CLAUDE", role = "proofs, compilers, repo-local implementation, CI/CD, formal verification, Rust/Idris2/Zig" }, - { name = "CHATGPT", role = "prose, papers, publication review, standards docs, outreach drafts, letters" }, - { name = "GEMINI", role = "estate audits, cross-repo sweeps, long-context triage, pattern detection" }, - { name = "VIBE", role = "UI/frontend, PanLL panels, ReScript components, theming, rapid prototyping" }, -] - -[policy] -rules = [ - "Do not duplicate tasks across sections. If a task needs multiple LLMs, note the handoff.", - "Update THIS file during sessions. Do NOT recreate per-repo TODO files.", -] - -[work-allocation] -items = [ - { agent = "CLAUDE", task = "proofs, compilers, repo-local implementation, CI/CD, formal verification, Rust/Idris2/Zig" }, - { agent = "CHATGPT", task = "prose, papers, publication review, standards docs, outreach drafts, letters" }, - { agent = "GEMINI", task = "estate audits, cross-repo sweeps, long-context triage, pattern detection" }, - { agent = "VIBE", task = "UI/frontend, PanLL panels, ReScript components, theming, rapid prototyping" }, -] diff --git a/ANCHOR.a2ml b/ANCHOR.a2ml new file mode 100644 index 0000000..5bde36e --- /dev/null +++ b/ANCHOR.a2ml @@ -0,0 +1,27 @@ +# SPDX-License-Identifier: MPL-2.0 +name = "a2ml-ecosystem" +version = "0.1.0" +authority = "coordination-hub" +updated = "2026-06-21" + +[semantic-authority] +policy = "satellite" +upstream = "hyperpolymath/standards" +local-ownership = [ + "conformance fixtures", + "membership manifest", + "cross-repo drift CI", +] + +[upstream.spec] +repo = "hyperpolymath/standards" +path = "docs/A2ML-SPEC.adoc" +pin = "TODO-tag" + +[upstream.governance] +repo = "hyperpolymath/standards" +path = "GOVERNANCE.adoc" +pin = "TODO-tag" + +[attestation] +proof = "satellite anchor records upstream authority and local coordination scope" diff --git a/AUDIT.adoc b/AUDIT.adoc deleted file mode 100644 index 0f4f5ac..0000000 --- a/AUDIT.adoc +++ /dev/null @@ -1,48 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Audit Gate -Codex -v1.1, 2026-04-07 -:toc: -:toclevels: 2 -:sectnums: - -== Purpose - -This root document exists so humans and bots can see the hard audit posture -without having to discover the standards repository first. - -Canonical source documents live in the `standards` repository. This file is a -repo-local audit gate summary for template users and automated agents. - -== Hard Rules - -* Do not call anything `stable`, `v1.0.0`, or full release unless the stable - release gate has been passed end to end. -* Do not publish implementation-facing work below `B` in CRG unless the work is - genuinely abstract and makes no implementation-readiness claim. -* `D` requires RSR compliance or a documented equivalent repository discipline. -* `C` requires deep code and folder annotation, not just local confidence. -* `B` means `beta-stable`: external breadth and safe broad trial, not merely - public visibility. -* Papers, whitepapers, release notes, and READMEs must not outrun the proofs, - tests, or artefacts that support their claims. -* Release paths must not ship with placeholders, stubs, `FIXME`, `XXX`, - template residue, fake fuzz, fake benches, or partial proof debt hidden as - if it were complete. - -== Canonical Standards - -Read these as the authoritative source: - -* `standards/component-readiness-grades/COMPONENT-READINESS-GRADES.md` -* `standards/release-pre-flight/V1-GATE.adoc` -* `standards/publication-pre-flight/PREFLIGHT.adoc` -* `standards/publication-pre-flight/ESTATE-AUDIT-BASELINE-2026-03-30.adoc` -* `standards/session-management-standards/README.adoc` - -== Bot Requirement - -Bots operating in repositories derived from this template should treat this -document as a key root audit document and should not make optimistic release or -publication claims that conflict with it. diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 66fa7a0..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,15 +0,0 @@ - -# Changelog - -All notable changes to this project will be documented in this file. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - - - - -## [Unreleased] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 8779679..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,12 +0,0 @@ - -# Contributing - -1. Fork the repository -2. Create a feature branch -3. Ensure SPDX headers on all files -4. Submit a pull request - -**Author:** Jonathan D.A. Jewell diff --git a/ECOSYSTEM.a2ml b/ECOSYSTEM.a2ml new file mode 100644 index 0000000..e0445b6 --- /dev/null +++ b/ECOSYSTEM.a2ml @@ -0,0 +1,42 @@ +; SPDX-License-Identifier: MPL-2.0 +(ecosystem + (metadata + (name "a2ml-ecosystem") + (version "0.1.0") + (updated "2026-06-21") + (authority "coordination-hub") + (semantic-authority "satellite")) + + (upstream + (spec + (repo "hyperpolymath/standards") + (path "docs/A2ML-SPEC.adoc") + (pin "TODO-tag")) + (governance + (repo "hyperpolymath/standards") + (path "GOVERNANCE.adoc") + (pin "TODO-tag"))) + + (membership + (implementations + (member "a2ml-rs" (group "implementations") (path "members/implementations/a2ml-rs") (branch "main") (repo "hyperpolymath/a2ml-rs")) + (member "a2ml_ex" (group "implementations") (path "members/implementations/a2ml_ex") (branch "main") (repo "hyperpolymath/a2ml_ex")) + (member "a2ml_gleam" (group "implementations") (path "members/implementations/a2ml_gleam") (branch "main") (repo "hyperpolymath/a2ml_gleam")) + (member "a2ml-deno" (group "implementations") (path "members/implementations/a2ml-deno") (branch "main") (repo "hyperpolymath/a2ml-deno")) + (member "a2ml-haskell" (group "implementations") (path "members/implementations/a2ml-haskell") (branch "main") (repo "hyperpolymath/a2ml-haskell"))) + + (tooling + (member "tree-sitter-a2ml" (group "tooling") (path "members/tooling/tree-sitter-a2ml") (branch "main") (repo "hyperpolymath/tree-sitter-a2ml")) + (member "vscode-a2ml" (group "tooling") (path "members/tooling/vscode-a2ml") (branch "main") (repo "hyperpolymath/vscode-a2ml")) + (member "pandoc-a2ml" (group "tooling") (path "members/tooling/pandoc-a2ml") (branch "main") (repo "hyperpolymath/pandoc-a2ml")) + (member "a2mliser" (group "tooling") (path "members/tooling/a2mliser") (branch "main") (repo "hyperpolymath/a2mliser"))) + + (ci + (member "a2ml-validate-action" (group "ci") (path "members/ci/a2ml-validate-action") (branch "main") (repo "hyperpolymath/a2ml-validate-action")) + (member "a2ml-pre-commit" (group "ci") (path "members/ci/a2ml-pre-commit") (branch "main") (repo "hyperpolymath/a2ml-pre-commit"))) + + (examples + (member "a2ml-showcase" (group "examples") (path "members/examples/a2ml-showcase") (branch "main") (repo "hyperpolymath/a2ml-showcase")))) + + (related + (related "contractiles-a2-lab" (relationship "private-lab-cross-reference") (repo "hyperpolymath/contractiles-a2-lab") (member false)))) diff --git a/EXPLAINME.adoc b/EXPLAINME.adoc deleted file mode 100644 index dee9b62..0000000 --- a/EXPLAINME.adoc +++ /dev/null @@ -1,94 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= RSR Template Repo - Explainme -image:https://img.shields.io/badge/License-MPL_2.0-blue.svg[License: MPL-2.0,link="https://opensource.org/licenses/MPL-2.0"] - -:toc: -:icons: font - -This file explains how the key template claims map to real files. - -== Central Session Protocol Authority - -Claim: -Session protocols are centrally maintained and not duplicated in this template. - -How this is implemented: - -* The local dispatcher (`session/dispatch.sh`) maps canonical commands to central - protocol paths in `standards/session-management-standards`. -* Local files (`session/custom-checks.k9`, `session/local-hooks.sh`, - `coordination.k9`) are integration-only. - -Caveat: - -* If `SESSION_STANDARDS_DIR` is unset and no adjacent standards checkout exists, - the dispatcher records the command but cannot resolve central checklist paths. - -== Canonical Command Surface - -Claim: -Template bindings align to one canonical command model. - -How this is implemented: - -* `Justfile` provides thin aliases (`intake-repo`, `checkpoint-change`, - `verify-maintenance`, `verify-substantial`, `verify-release`, `close-planned`, - `close-urgent`, `recover-repo`, `handover-*`). -* Every alias calls `session/dispatch.sh` with canonical verb-object pairs. - -Caveat: - -* Recipes are wrappers only. They do not replace protocol content from - the central standards repo. - -== Runtime State Is Local - -Claim: -Session state is per-repository runtime output, not standards text. - -How this is implemented: - -* `session/dispatch.sh` writes command and continuity-core capture stubs to - `.session/LAST-CANONICAL-COMMAND.md` in the target repository path. - -Caveat: - -* Runtime files are intentionally lightweight and require human/agent completion. - -== Template Token Policy - -Claim: -Placeholders are explicit template content until initialization. - -How this is implemented: - -* `README.adoc` and bootstrap recipes keep `{{TOKEN}}` placeholders visible. -* `just init` performs token replacement. - -Caveat: - -* Uninitialized placeholders must not be treated as project-specific truth. - -== Julia Registry Packages — Standalone Repo Requirement - -Claim: -If this template is used to create a Julia package, it must remain a standalone repository registered with the Julia package registry. - -How this is implemented: - -* Julia's package registry (General.jl or other) expects each package to be a standalone GitHub repository with `Project.toml` at the repository root. -* Installation via `Pkg.add()`, dependency resolution, and automated CI/CD all depend on this canonical structure. - -Caveat: - -* Do NOT move this repository into a monorepo or subdirectory, as this breaks registry registration and package discoverability. -* See `JULIA-REGISTRY-REQUIREMENT.md` (workspace root) for the complete list of 34 registered Julia packages and enforcement rationale. -* Non-registry Julia packages can be organized differently if they are not published to any registry. - - -== License - -This project is licensed under the Mozilla Public License, v. 2.0. See the `LICENSE` file for details. - -SPDX-License-Identifier: MPL-2.0 diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc deleted file mode 100644 index 8bbf167..0000000 --- a/GOVERNANCE.adoc +++ /dev/null @@ -1,162 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell -= Governance Model -:toc: preamble - -This document describes the governance model for this repository. - -== Overview - -This repository follows a **Sole Maintainer Governance Model**: - -* 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 - -== Core Principles - -[cols="1,2"] -|=== -| Principle | Description - -| **Benevolent Dictatorship** | Maintainer has final decision authority but seeks community input - -| **Meritocracy** | Contributions are judged on technical merit, not contributor identity - -| **Transparency** | All significant decisions are documented publicly - -| **Consensus-Seeking** | Maintainer prefers consensus but will decide when necessary - -| **Open Contribution** | Anyone can contribute via fork and pull request - -|=== - -== Roles and Permissions - -[cols="1,2,2"] -|=== -| Role | Permissions | Assignment - -| **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 - -|=== - -== Decision Making Framework - -=== Routine Decisions - -* Bug fixes -* Documentation improvements -* Minor feature additions -* Dependency updates - -**Process**: Maintainer reviews and merges PRs that meet quality standards. - -=== Significant Changes - -* New major features -* API changes -* Architecture modifications -* Breaking changes - -**Process**: -. Open issue describing the change -. Discuss with community (minimum 72 hours) -. Maintainer makes final decision -. Document rationale in issue/PR - -=== Structural Decisions - -* Repository purpose/renaming -* License changes -* Ownership transfer -* Deprecation/archival - -**Process**: -. Extended discussion (minimum 1 week) -. Maintainer makes final decision -. Document in CHANGELOG and governance docs - -== Contribution Lifecycle - -[cols="1,2"] -|=== -| Stage | Process - -| **Ideation** | Open issue, discuss feasibility - -| **Development** | Fork, implement, test thoroughly - -| **Review** | Submit PR, maintainer reviews within 7 days - -| **Merge** | Maintainer merges or requests changes - -| **Release** | Maintainer publishes according to project conventions - -|=== - -== Conflict Resolution - -In case of disagreements: - -. 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 - -== Project Policies - -This repository adheres to hyperpolymath estate-wide policies: - -* **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 - -== Repository-Specific Conventions - -[cols="1,2"] -|=== -| Convention | Description - -| **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 -|=== diff --git a/Justfile b/Justfile deleted file mode 100644 index 9b2f200..0000000 --- a/Justfile +++ /dev/null @@ -1,784 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# RSR Standard Justfile Template -# https://just.systems/man/en/ -# -# Copy this file to new projects and customize the placeholder values. -# -# Run `just` to see all available recipes -# Run `just cookbook` to generate docs/just-cookbook.adoc -# Run `just combinations` to see matrix recipe options - -set shell := ["bash", "-uc"] -set dotenv-load := true -set positional-arguments := true - -# Import auto-generated contractile recipes (must-check, trust-verify, etc.) -# Re-generate with: contractile gen-just -import? "build/contractile.just" - -# Project metadata — customize these -project := "rsr-template-repo" -OWNER := "hyperpolymath" -REPO := "rsr-template-repo" -version := "0.1.0" -tier := "infrastructure" # 1 | 2 | infrastructure - -# ═══════════════════════════════════════════════════════════════════════════════ -# DEFAULT & HELP -# ═══════════════════════════════════════════════════════════════════════════════ - -# Show all available recipes with descriptions -default: - @just --list --unsorted - -# Show detailed help for a specific recipe -help recipe="": - #!/usr/bin/env bash - if [ -z "{{recipe}}" ]; then - just --list --unsorted - echo "" - echo "Usage: just help " - echo " just cookbook # Generate full documentation" - echo " just combinations # Show matrix recipes" - else - just --show "{{recipe}}" 2>/dev/null || echo "Recipe '{{recipe}}' not found" - fi - -# Show this project's info -info: - @echo "Project: {{project}}" - @echo "Version: {{version}}" - @echo "RSR Tier: {{tier}}" - @echo "Recipes: $(just --summary | wc -w)" - @[ -f ".machine_readable/6a2/STATE.a2ml" ] && grep -oP 'phase\s*=\s*"\K[^"]+' .machine_readable/6a2/STATE.a2ml | head -1 | xargs -I{} echo "Phase: {}" || true - -# Run Invariant Path overlay tools for this repository -invariant-path *ARGS: - ./scripts/invariant-path.sh {{ARGS}} - -# ═══════════════════════════════════════════════════════════════════════════════ -# INIT — see build/just/init.just -# ═══════════════════════════════════════════════════════════════════════════════ - -import? "build/just/init.just" - -# ═══════════════════════════════════════════════════════════════════════════════ -# GROOVE PROTOCOL — see build/just/groove.just -# ═══════════════════════════════════════════════════════════════════════════════ - -import? "build/just/groove.just" - -# ═══════════════════════════════════════════════════════════════════════════════ -# PROJECT SELF-ASSESSMENT + OPENSSF COMPLIANCE — see build/just/assess.just -# ═══════════════════════════════════════════════════════════════════════════════ - -import? "build/just/assess.just" - -# ═══════════════════════════════════════════════════════════════════════════════ -# BUILD & COMPILE -# ═══════════════════════════════════════════════════════════════════════════════ - -# Build the project (debug mode) -build *args: - @echo "Building {{project}} (debug)..." - # TODO: Replace with your build command - # Examples: - # cargo build {{args}} # Rust - # mix compile {{args}} # Elixir - # zig build {{args}} # Zig - # deno task build {{args}} # Deno/ReScript - @echo "Build complete" - -# Build in release mode with optimizations -build-release *args: - @echo "Building {{project}} (release)..." - # TODO: Replace with your release build command - # Examples: - # cargo build --release {{args}} - # MIX_ENV=prod mix compile {{args}} - # zig build -Doptimize=ReleaseFast {{args}} - @echo "Release build complete" - -# Build and watch for changes (requires entr or similar) -build-watch: - @echo "Watching for changes..." - # TODO: Customize file patterns for your language - # Examples: - # find src -name '*.rs' | entr -c just build - # mix compile --force --warnings-as-errors - # deno task dev - -# Clean build artifacts [reversible: rebuild with `just build`] -clean: - @echo "Cleaning..." - # TODO: Customize for your build system - rm -rf target/ _build/ build/ dist/ out/ obj/ bin/ - -# Deep clean including caches [reversible: rebuild] -clean-all: clean - rm -rf .cache .tmp - -# ═══════════════════════════════════════════════════════════════════════════════ -# TEST & QUALITY -# ═══════════════════════════════════════════════════════════════════════════════ - -# Run all tests -test *args: - @echo "Running tests..." - # TODO: Replace with your test command - # Examples: - # cargo test {{args}} - # mix test {{args}} - # zig build test {{args}} - # deno test {{args}} - @echo "Tests passed!" - -# Run tests with verbose output -test-verbose: - @echo "Running tests (verbose)..." - # TODO: Replace with verbose test command - -# Smoke test -test-smoke: - @echo "Smoke test..." - # TODO: Add basic sanity checks - -# Run end-to-end tests (full pipeline: build → run → verify) -e2e: - @echo "Running E2E tests..." - # TODO: Replace with your E2E test command. Examples: - # bash tests/e2e.sh # Shell-based E2E - # npx playwright test # Browser E2E - # mix test test/integration/e2e_test.exs # Elixir E2E - # cargo test --test end_to_end # Rust E2E - @echo "E2E tests passed!" - -# Run aspect tests (cross-cutting concern validation) -aspect: - @echo "Running aspect tests..." - # TODO: Replace with your aspect test command. Examples: - # bash tests/aspect_tests.sh # Shell-based aspect tests - # cargo test --test aspects # Rust aspect tests - # Aspect tests validate architectural invariants: - # - Thread safety (mutex in FFI modules) - # - ABI/FFI contract (declarations match exports) - # - SPDX compliance (all files have license headers) - # - No dangerous patterns (believe_me, assert_total, etc.) - @echo "Aspect tests passed!" - -# Run benchmarks (performance regression detection) -bench: - @echo "Running benchmarks..." - # TODO: Replace with your benchmark command. Examples: - # cargo bench # Rust criterion - # zig build bench # Zig benchmarks - # mix run bench/benchmarks.exs # Elixir benchee - # deno bench # Deno bench - @echo "Benchmarks complete!" - -# Run readiness tests (Component Readiness Grade: D/C/B) -readiness: - @echo "Running readiness tests..." - # TODO: Replace with your readiness test command. Examples: - # cargo test --test readiness -- --nocapture - @echo "Readiness tests complete!" - -# Print the current CRG grade (reads from READINESS.md '**Current Grade:** X' line) -crg-grade: - @grade=$$(grep -oP '(?<=\*\*Current Grade:\*\* )[A-FX]' READINESS.md 2>/dev/null | head -1); \ - [ -z "$$grade" ] && grade="X"; \ - echo "$$grade" - -# Print a shields.io CRG badge for embedding in README files -# Looks for '**Current Grade:** X' in READINESS.md; falls back to X -crg-badge: - @grade=$$(grep -oP '(?<=\*\*Current Grade:\*\* )[A-FX]' READINESS.md 2>/dev/null | head -1); \ - [ -z "$$grade" ] && grade="X"; \ - case "$$grade" in \ - A) color="brightgreen" ;; \ - B) color="green" ;; \ - C) color="yellow" ;; \ - D) color="orange" ;; \ - E) color="red" ;; \ - F) color="critical" ;; \ - *) color="lightgrey" ;; \ - esac; \ - echo "[![CRG $$grade](https://img.shields.io/badge/CRG-$$grade-$$color?style=flat-square)](https://github.com/hyperpolymath/standards/tree/main/component-readiness-grades)" - -# Run the full merge-requirement test suite (ALL categories) -# Per STANDING rule: P2P + E2E + aspect + execution + lifecycle + bench -test-all: test e2e aspect bench readiness - @echo "All test categories passed — safe to merge!" - -# Run all quality checks -quality: fmt-check lint test - @echo "All quality checks passed!" - -# Fix all auto-fixable issues [reversible: git checkout] -fix: fmt - @echo "Fixed all auto-fixable issues" - -# ═══════════════════════════════════════════════════════════════════════════════ -# LINT & FORMAT -# ═══════════════════════════════════════════════════════════════════════════════ - -# Format all source files [reversible: git checkout] -fmt: - @echo "Formatting source files..." - # TODO: Replace with your formatter - # Examples: - # cargo fmt - # mix format - # gleam format - # deno fmt - -# Check formatting without changes -fmt-check: - @echo "Checking formatting..." - # TODO: Replace with your format check - # Examples: - # cargo fmt --check - # mix format --check-formatted - # gleam format --check - -# Run linter -lint: - @echo "Linting source files..." - # TODO: Replace with your linter - # Examples: - # cargo clippy -- -D warnings - # mix credo --strict - # gleam check - -# ═══════════════════════════════════════════════════════════════════════════════ -# RUN & EXECUTE -# ═══════════════════════════════════════════════════════════════════════════════ - -# Run the application -run *args: build - # TODO: Replace with your run command - echo "Run not configured yet" - -# Run with verbose output -run-verbose *args: build - # TODO: Replace with verbose run command - echo "Run not configured yet" - -# Install to user path -install: build-release - @echo "Installing {{project}}..." - # TODO: Replace with your install command - -# ═══════════════════════════════════════════════════════════════════════════════ -# DEPENDENCIES -# ═══════════════════════════════════════════════════════════════════════════════ - -# Install/check all dependencies -deps: - @echo "Checking dependencies..." - # TODO: Replace with your dependency check - # Examples: - # cargo check - # mix deps.get - # gleam deps download - @echo "All dependencies satisfied" - -# Audit dependencies for vulnerabilities -deps-audit: - @echo "Auditing for vulnerabilities..." - # TODO: Replace with your audit command - # Examples: - # cargo audit - # mix audit - @command -v trivy >/dev/null && trivy fs --severity HIGH,CRITICAL --quiet . || true - @echo "Audit complete" - -# ═══════════════════════════════════════════════════════════════════════════════ -# DOCUMENTATION -# ═══════════════════════════════════════════════════════════════════════════════ - -# Generate all documentation -docs: - @mkdir -p docs/generated docs/man - just cookbook - just man - @echo "Documentation generated in docs/" - -# Generate justfile cookbook documentation -cookbook: - #!/usr/bin/env bash - mkdir -p docs - OUTPUT="docs/just-cookbook.adoc" - echo "= {{project}} Justfile Cookbook" > "$OUTPUT" - echo ":toc: left" >> "$OUTPUT" - echo ":toclevels: 3" >> "$OUTPUT" - echo "" >> "$OUTPUT" - echo "Generated: $(date -Iseconds)" >> "$OUTPUT" - echo "" >> "$OUTPUT" - echo "== Recipes" >> "$OUTPUT" - echo "" >> "$OUTPUT" - just --list --unsorted | while read -r line; do - if [[ "$line" =~ ^[[:space:]]+([a-z_-]+) ]]; then - recipe="${BASH_REMATCH[1]}" - echo "=== $recipe" >> "$OUTPUT" - echo "" >> "$OUTPUT" - echo "[source,bash]" >> "$OUTPUT" - echo "----" >> "$OUTPUT" - echo "just $recipe" >> "$OUTPUT" - echo "----" >> "$OUTPUT" - echo "" >> "$OUTPUT" - fi - done - echo "Generated: $OUTPUT" - -# Generate man page -man: - #!/usr/bin/env bash - mkdir -p docs/man - cat > docs/man/{{project}}.1 << EOF - .TH {{project}} 1 "$(date +%Y-%m-%d)" "{{version}}" "{{project}} Manual" - .SH NAME - {{project}} \- RSR-compliant project - .SH SYNOPSIS - .B just - [recipe] [args...] - .SH DESCRIPTION - RSR (Rhodium Standard Repository) project managed with just. - .SH AUTHOR - $(git config user.name 2>/dev/null || echo "Author") <$(git config user.email 2>/dev/null || echo "email")> - EOF - echo "Generated: docs/man/{{project}}.1" - -# ═══════════════════════════════════════════════════════════════════════════════ -# CONTAINERS (stapeln ecosystem — Podman + Chainguard Wolfi) -# ═══════════════════════════════════════════════════════════════════════════════ - -# Initialise container templates — substitute placeholders with project values -container-init: - #!/usr/bin/env bash - set -euo pipefail - - if [ ! -d "container" ]; then - echo "Error: container/ directory not found." - echo "This repo may not have been created from rsr-template-repo." - exit 1 - fi - - echo "=== Container Template Initialisation ===" - echo "" - - # Load RSR defaults if available - DEFAULTS="${XDG_CONFIG_HOME:-$HOME/.config}/rsr/defaults" - if [ -f "$DEFAULTS" ]; then - echo "Loading defaults from $DEFAULTS" - # shellcheck source=/dev/null - source "$DEFAULTS" - echo "" - fi - - # Prompt for container-specific values - read -rp "Service name (e.g. my-api) [{{project}}]: " _SERVICE_NAME - SERVICE_NAME="${_SERVICE_NAME:-{{project}}}" - - read -rp "Primary port [8080]: " _PORT - PORT="${_PORT:-8080}" - - read -rp "Container registry [ghcr.io/${OWNER:-{{OWNER}}}]: " _REGISTRY - REGISTRY="${_REGISTRY:-ghcr.io/${OWNER:-{{OWNER}}}}" - - echo "" - echo " Service: $SERVICE_NAME" - echo " Port: $PORT" - echo " Registry: $REGISTRY" - echo "" - read -rp "Proceed? [Y/n] " CONFIRM - [[ "${CONFIRM:-Y}" =~ ^[Nn] ]] && echo "Aborted." && exit 0 - - echo "" - echo "Replacing container placeholders..." - - # Brace tokens as variables (hex escapes avoid just interpolation) - LB=$(printf '\x7b\x7b') - RB=$(printf '\x7d\x7d') - - SED_ARGS=( - -e "s|${LB}SERVICE_NAME${RB}|${SERVICE_NAME}|g" - -e "s|${LB}PORT${RB}|${PORT}|g" - -e "s|${LB}REGISTRY${RB}|${REGISTRY}|g" - ) - - find container/ -type f | while read -r file; do - if file --brief "$file" | grep -qi 'text\|ascii\|utf'; then - sed -i "${SED_ARGS[@]}" "$file" - fi - done - - echo "Container templates initialised." - echo "" - echo "Next steps:" - echo " 1. Edit container/Containerfile — add your build commands" - echo " 2. Edit container/entrypoint.sh — set your application binary" - echo " 3. Review container/compose.toml — adjust services and volumes" - echo " 4. Build: just container-build" - -# Build container image via cerro-torre pipeline -container-build *args: - #!/usr/bin/env bash - if [ -f "container/ct-build.sh" ]; then - cd container && ./ct-build.sh {{args}} - elif [ -f "container/Containerfile" ]; then - podman build -t {{project}}:latest -f container/Containerfile . - elif [ -f "build/Containerfile" ]; then - podman build -t {{project}}:latest -f build/Containerfile . - elif [ -f "Containerfile" ]; then - podman build -t {{project}}:latest -f Containerfile . - else - echo "No Containerfile found in container/, build/, or project root" - exit 1 - fi - -# Verify compose configuration -container-verify: - #!/usr/bin/env bash - if [ ! -f "container/compose.toml" ]; then - echo "No container/compose.toml found" - exit 1 - fi - cd container - if command -v selur-compose &>/dev/null; then - selur-compose verify - else - echo "selur-compose not found, falling back to podman compose" - podman compose --file compose.toml config - fi - -# Start container stack -container-up *args: - #!/usr/bin/env bash - if [ ! -f "container/compose.toml" ]; then - echo "No container/compose.toml found" - exit 1 - fi - cd container - if command -v selur-compose &>/dev/null; then - selur-compose up {{args}} - else - podman compose --file compose.toml up {{args}} - fi - -# Stop container stack -container-down: - #!/usr/bin/env bash - cd container 2>/dev/null || { echo "No container/ directory"; exit 1; } - if command -v selur-compose &>/dev/null; then - selur-compose down - else - podman compose --file compose.toml down - fi - -# Sign and verify container bundle (build + pack + sign + verify) -container-sign: - #!/usr/bin/env bash - if [ -f "container/ct-build.sh" ]; then - cd container && ./ct-build.sh - else - echo "No container/ct-build.sh found" - exit 1 - fi - -# Push signed bundle to registry -container-push: - #!/usr/bin/env bash - if [ -f "container/ct-build.sh" ]; then - cd container && ./ct-build.sh --push - else - echo "No container/ct-build.sh found — falling back to podman push" - podman push {{project}}:latest - fi - -# Run container interactively (for debugging) -container-run *args: - podman run --rm -it {{project}}:latest {{args}} - -# ═══════════════════════════════════════════════════════════════════════════════ -# CI & AUTOMATION -# ═══════════════════════════════════════════════════════════════════════════════ - -# Run full CI pipeline locally -ci: deps quality - @echo "CI pipeline complete!" - -# Install git hooks -install-hooks: - @mkdir -p .git/hooks - @cat > .git/hooks/pre-commit << 'HOOKEOF' - #!/bin/bash - just fmt-check || exit 1 - just lint || exit 1 - just assail || exit 1 - HOOKEOF - @chmod +x .git/hooks/pre-commit - @echo "Git hooks installed" - -# ═══════════════════════════════════════════════════════════════════════════════ -# SECURITY -# ═══════════════════════════════════════════════════════════════════════════════ - -# Run security audit -security: deps-audit - @echo "=== Security Audit ===" - @command -v trivy >/dev/null && trivy fs --severity HIGH,CRITICAL . || true - @echo "Security audit complete" - -# Generate SBOM -sbom: - @mkdir -p docs/security - @command -v syft >/dev/null && syft . -o spdx-json > docs/security/sbom.spdx.json || echo "syft not found" - -# ═══════════════════════════════════════════════════════════════════════════════ -# VALIDATION & COMPLIANCE — see build/just/validate.just -# ═══════════════════════════════════════════════════════════════════════════════ - -import? "build/just/validate.just" - -# ═══════════════════════════════════════════════════════════════════════════════ -# STATE MANAGEMENT -# ═══════════════════════════════════════════════════════════════════════════════ - -# Update STATE.a2ml timestamp -state-touch: - @if [ -f ".machine_readable/6a2/STATE.a2ml" ]; then \ - sed -i 's/last-updated = "[^"]*"/last-updated = "'"$(date +%Y-%m-%d)"'"/' .machine_readable/6a2/STATE.a2ml && \ - echo "STATE.a2ml timestamp updated"; \ - fi - -# Show current phase from STATE.a2ml -state-phase: - @grep -oP 'phase\s*=\s*"\K[^"]+' .machine_readable/6a2/STATE.a2ml 2>/dev/null | head -1 || echo "unknown" - -# ═══════════════════════════════════════════════════════════════════════════════ -# GUIX & NIX -# ═══════════════════════════════════════════════════════════════════════════════ - -# Enter Guix development shell (primary) -guix-shell: - guix shell -D -f guix.scm - -# Build with Guix -guix-build: - guix build -f guix.scm - -# Enter Nix development shell (fallback) -nix-shell: - @if [ -f "flake.nix" ]; then nix develop; else echo "No flake.nix"; fi - -# ═══════════════════════════════════════════════════════════════════════════════ -# HYBRID AUTOMATION -# ═══════════════════════════════════════════════════════════════════════════════ - -# Run local automation tasks -automate task="all": - #!/usr/bin/env bash - case "{{task}}" in - all) just fmt && just lint && just test && just docs && just state-touch ;; - cleanup) just clean && find . -name "*.orig" -delete && find . -name "*~" -delete ;; - update) just deps && just validate ;; - *) echo "Unknown: {{task}}. Use: all, cleanup, update" && exit 1 ;; - esac - -# ═══════════════════════════════════════════════════════════════════════════════ -# COMBINATORIC MATRIX RECIPES -# ═══════════════════════════════════════════════════════════════════════════════ - -# Build matrix: [debug|release] x [target] x [features] -build-matrix mode="debug" target="" features="": - @echo "Build matrix: mode={{mode}} target={{target}} features={{features}}" - -# Test matrix: [unit|integration|e2e|all] x [verbosity] x [parallel] -test-matrix suite="unit" verbosity="normal" parallel="true": - @echo "Test matrix: suite={{suite}} verbosity={{verbosity}} parallel={{parallel}}" - -# Container matrix: [build|run|push|shell|scan] x [registry] x [tag] -container-matrix action="build" registry="ghcr.io/{{OWNER}}" tag="latest": - @echo "Container matrix: action={{action}} registry={{registry}} tag={{tag}}" - -# CI matrix: [lint|test|build|security|all] x [quick|full] -ci-matrix stage="all" depth="quick": - @echo "CI matrix: stage={{stage}} depth={{depth}}" - -# Show all matrix combinations -combinations: - @echo "=== Combinatoric Matrix Recipes ===" - @echo "" - @echo "Build Matrix: just build-matrix [debug|release] [target] [features]" - @echo "Test Matrix: just test-matrix [unit|integration|e2e|all] [verbosity] [parallel]" - @echo "Container: just container-matrix [build|run|push|shell|scan] [registry] [tag]" - @echo "CI Matrix: just ci-matrix [lint|test|build|security|all] [quick|full]" - -# ═══════════════════════════════════════════════════════════════════════════════ -# VERSION CONTROL -# ═══════════════════════════════════════════════════════════════════════════════ - -# Show git status -status: - @git status --short - -# Show recent commits -log count="20": - @git log --oneline -{{count}} - -# Generate CHANGELOG.md with git-cliff -changelog: - @command -v git-cliff >/dev/null || { echo "git-cliff not found — install: cargo install git-cliff"; exit 1; } - git cliff --config .machine_readable/configs/git-cliff/cliff.toml --output CHANGELOG.md - @echo "Generated CHANGELOG.md" - -# Preview changelog for unreleased commits (does not write) -changelog-preview: - @command -v git-cliff >/dev/null || { echo "git-cliff not found — install: cargo install git-cliff"; exit 1; } - git cliff --config .machine_readable/configs/git-cliff/cliff.toml --unreleased --strip header - -# Tag a new release (usage: just release-tag 1.2.3) -release-tag version: - #!/usr/bin/env bash - TAG="v{{version}}" - if git rev-parse "$TAG" >/dev/null 2>&1; then - echo "Tag $TAG already exists" - exit 1 - fi - just changelog - git add CHANGELOG.md - git commit -m "chore(release): prepare $TAG" - git tag -a "$TAG" -m "Release $TAG" - echo "Created tag $TAG — push with: git push origin main --tags" - -# ═══════════════════════════════════════════════════════════════════════════════ -# UTILITIES -# ═══════════════════════════════════════════════════════════════════════════════ - -# Count lines of code -loc: - @find . \( -name "*.rs" -o -name "*.ex" -o -name "*.exs" -o -name "*.res" -o -name "*.gleam" -o -name "*.zig" -o -name "*.idr" -o -name "*.hs" -o -name "*.ncl" -o -name "*.scm" -o -name "*.adb" -o -name "*.ads" \) -not -path './target/*' -not -path './_build/*' 2>/dev/null | xargs wc -l 2>/dev/null | tail -1 || echo "0" - -# Show TODO comments -todos: - @grep -rn "TODO\|FIXME\|HACK\|XXX" --include="*.rs" --include="*.ex" --include="*.res" --include="*.gleam" --include="*.zig" --include="*.idr" --include="*.hs" . 2>/dev/null || echo "No TODOs" - -# Open in editor -edit: - ${EDITOR:-code} . - -# Run high-rigor security assault using panic-attacker -maint-assault: - @./.machine_readable/scripts/maintenance/maint-assault.sh - -# Run panic-attacker pre-commit scan (foundational floor-raise requirement) -assail: - @command -v panic-attack >/dev/null 2>&1 && panic-attack assail . || echo "WARN: panic-attack not found — install from https://github.com/hyperpolymath/panic-attacker" - - -# Self-diagnostic — checks dependencies, permissions, paths -doctor: - @echo "Running diagnostics for rsr-template-repo..." - @echo "Checking required tools..." - @command -v just >/dev/null 2>&1 && echo " [OK] just" || echo " [FAIL] just not found" - @command -v git >/dev/null 2>&1 && echo " [OK] git" || echo " [FAIL] git not found" - @echo "Checking for hardcoded paths..." - @grep -rn '$HOME\|$ECLIPSE_DIR' --include='*.rs' --include='*.ex' --include='*.res' --include='*.gleam' --include='*.sh' . 2>/dev/null | head -5 || echo " [OK] No hardcoded paths" - @echo "Diagnostics complete." - -# Guided tour of key features -tour: - @echo "=== rsr-template-repo Tour ===" - @echo "" - @echo "1. Project structure:" - @ls -la - @echo "" - @echo "2. Available commands: just --list" - @echo "" - @echo "3. Read README.adoc for full overview" - @echo "4. Read EXPLAINME.adoc for architecture decisions" - @echo "5. Run 'just doctor' to check your setup" - @echo "" - @echo "Tour complete! Try 'just --list' to see all available commands." - -# Open feedback channel with diagnostic context -help-me: - @echo "=== rsr-template-repo Help ===" - @echo "Platform: $(uname -s) $(uname -m)" - @echo "Shell: $SHELL" - @echo "" - @echo "To report an issue:" - @echo " https://github.com/hyperpolymath/rsr-template-repo/issues/new" - @echo "" - @echo "Include the output of 'just doctor' in your report." - -# ═══════════════════════════════════════════════════════════════════════════════ -# FORMAL VERIFICATION (PROOFS) — see build/just/proofs.just -# ═══════════════════════════════════════════════════════════════════════════════ - -import? "build/just/proofs.just" - -# ═══════════════════════════════════════════════════════════════════════════════ -# SESSION MANAGEMENT (THIN BINDINGS TO CENTRAL STANDARDS) -# ═══════════════════════════════════════════════════════════════════════════════ - -# Show canonical session-management command model -session-help: - @echo "Canonical command model:" - @echo " intake repo " - @echo " checkpoint change " - @echo " verify maintenance " - @echo " verify substantial " - @echo " verify release " - @echo " close planned " - @echo " close urgent " - @echo " recover repo " - @echo " handover full " - @echo " handover split " - @echo " handover model " - @echo " handover human " - @echo "" - @echo "Use Just aliases below (thin wrappers around ./session/dispatch.sh)." - -# Canonical aliases (friendly recipe names that map to canonical commands) -intake-repo path=".": - @./session/dispatch.sh intake repo "{{path}}" - -checkpoint-change path=".": - @./session/dispatch.sh checkpoint change "{{path}}" - -verify-maintenance path=".": - @./session/dispatch.sh verify maintenance "{{path}}" - -verify-substantial path=".": - @./session/dispatch.sh verify substantial "{{path}}" - -verify-release path=".": - @./session/dispatch.sh verify release "{{path}}" - -close-planned path=".": - @./session/dispatch.sh close planned "{{path}}" - -close-urgent path=".": - @./session/dispatch.sh close urgent "{{path}}" - -recover-repo path=".": - @./session/dispatch.sh recover repo "{{path}}" - -handover-full path=".": - @./session/dispatch.sh handover full "{{path}}" - -handover-split path=".": - @./session/dispatch.sh handover split "{{path}}" - -handover-model path=".": - @./session/dispatch.sh handover model "{{path}}" - -handover-human path=".": - @./session/dispatch.sh handover human "{{path}}" - -secret-scan-trufflehog: - @command -v trufflehog >/dev/null && trufflehog filesystem . --only-verified || true diff --git a/LICENSE b/LICENSE deleted file mode 100644 index d0a1fa1..0000000 --- a/LICENSE +++ /dev/null @@ -1,373 +0,0 @@ -Mozilla Public License Version 2.0 -================================== - -1. Definitions --------------- - -1.1. "Contributor" - means each individual or legal entity that creates, contributes to - the creation of, or owns Covered Software. - -1.2. "Contributor Version" - means the combination of the Contributions of others (if any) used - by a Contributor and that particular Contributor's Contribution. - -1.3. "Contribution" - means Covered Software of a particular Contributor. - -1.4. "Covered Software" - means Source Code Form to which the initial Contributor has attached - the notice in Exhibit A, the Executable Form of such Source Code - Form, and Modifications of such Source Code Form, in each case - including portions thereof. - -1.5. "Incompatible With Secondary Licenses" - means - - (a) that the initial Contributor has attached the notice described - in Exhibit B to the Covered Software; or - - (b) that the Covered Software was made available under the terms of - version 1.1 or earlier of the License, but not also under the - terms of a Secondary License. - -1.6. "Executable Form" - means any form of the work other than Source Code Form. - -1.7. "Larger Work" - means a work that combines Covered Software with other material, in - a separate file or files, that is not Covered Software. - -1.8. "License" - means this document. - -1.9. "Licensable" - means having the right to grant, to the maximum extent possible, - whether at the time of the initial grant or subsequently, any and - all of the rights conveyed by this License. - -1.10. "Modifications" - means any of the following: - - (a) any file in Source Code Form that results from an addition to, - deletion from, or modification of the contents of Covered - Software; or - - (b) any new file in Source Code Form that contains any Covered - Software. - -1.11. "Patent Claims" of a Contributor - means any patent claim(s), including without limitation, method, - process, and apparatus claims, in any patent Licensable by such - Contributor that would be infringed, but for the grant of the - License, by the making, using, selling, offering for sale, having - made, import, or transfer of either its Contributions or its - Contributor Version. - -1.12. "Secondary License" - means either the GNU General Public License, Version 2.0, the GNU - Lesser General Public License, Version 2.1, the GNU Affero General - Public License, Version 3.0, or any later versions of those - licenses. - -1.13. "Source Code Form" - means the form of the work preferred for making modifications. - -1.14. "You" (or "Your") - means an individual or a legal entity exercising rights under this - License. For legal entities, "You" includes any entity that - controls, is controlled by, or is under common control with You. For - purposes of this definition, "control" means (a) the power, direct - or indirect, to cause the direction or management of such entity, - whether by contract or otherwise, or (b) ownership of more than - fifty percent (50%) of the outstanding shares or beneficial - ownership of such entity. - -2. License Grants and Conditions --------------------------------- - -2.1. Grants - -Each Contributor hereby grants You a world-wide, royalty-free, -non-exclusive license: - -(a) under intellectual property rights (other than patent or trademark) - Licensable by such Contributor to use, reproduce, make available, - modify, display, perform, distribute, and otherwise exploit its - Contributions, either on an unmodified basis, with Modifications, or - as part of a Larger Work; and - -(b) under Patent Claims of such Contributor to make, use, sell, offer - for sale, have made, import, and otherwise transfer either its - Contributions or its Contributor Version. - -2.2. Effective Date - -The licenses granted in Section 2.1 with respect to any Contribution -become effective for each Contribution on the date the Contributor first -distributes such Contribution. - -2.3. Limitations on Grant Scope - -The licenses granted in this Section 2 are the only rights granted under -this License. No additional rights or licenses will be implied from the -distribution or licensing of Covered Software under this License. -Notwithstanding Section 2.1(b) above, no patent license is granted by a -Contributor: - -(a) for any code that a Contributor has removed from Covered Software; - or - -(b) for infringements caused by: (i) Your and any other third party's - modifications of Covered Software, or (ii) the combination of its - Contributions with other software (except as part of its Contributor - Version); or - -(c) under Patent Claims infringed by Covered Software in the absence of - its Contributions. - -This License does not grant any rights in the trademarks, service marks, -or logos of any Contributor (except as may be necessary to comply with -the notice requirements in Section 3.4). - -2.4. Subsequent Licenses - -No Contributor makes additional grants as a result of Your choice to -distribute the Covered Software under a subsequent version of this -License (see Section 10.2) or under the terms of a Secondary License (if -permitted under the terms of Section 3.3). - -2.5. Representation - -Each Contributor represents that the Contributor believes its -Contributions are its original creation(s) or it has sufficient rights -to grant the rights to its Contributions conveyed by this License. - -2.6. Fair Use - -This License is not intended to limit any rights You have under -applicable copyright doctrines of fair use, fair dealing, or other -equivalents. - -2.7. Conditions - -Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted -in Section 2.1. - -3. Responsibilities -------------------- - -3.1. Distribution of Source Form - -All distribution of Covered Software in Source Code Form, including any -Modifications that You create or to which You contribute, must be under -the terms of this License. You must inform recipients that the Source -Code Form of the Covered Software is governed by the terms of this -License, and how they can obtain a copy of this License. You may not -attempt to alter or restrict the recipients' rights in the Source Code -Form. - -3.2. Distribution of Executable Form - -If You distribute Covered Software in Executable Form then: - -(a) such Covered Software must also be made available in Source Code - Form, as described in Section 3.1, and You must inform recipients of - the Executable Form how they can obtain a copy of such Source Code - Form by reasonable means in a timely manner, at a charge no more - than the cost of distribution to the recipient; and - -(b) You may distribute such Executable Form under the terms of this - License, or sublicense it under different terms, provided that the - license for the Executable Form does not attempt to limit or alter - the recipients' rights in the Source Code Form under this License. - -3.3. Distribution of a Larger Work - -You may create and distribute a Larger Work under terms of Your choice, -provided that You also comply with the requirements of this License for -the Covered Software. If the Larger Work is a combination of Covered -Software with a work governed by one or more Secondary Licenses, and the -Covered Software is not Incompatible With Secondary Licenses, this -License permits You to additionally distribute such Covered Software -under the terms of such Secondary License(s), so that the recipient of -the Larger Work may, at their option, further distribute the Covered -Software under the terms of either this License or such Secondary -License(s). - -3.4. Notices - -You may not remove or alter the substance of any license notices -(including copyright notices, patent notices, disclaimers of warranty, -or limitations of liability) contained within the Source Code Form of -the Covered Software, except that You may alter any license notices to -the extent required to remedy known factual inaccuracies. - -3.5. Application of Additional Terms - -You may choose to offer, and to charge a fee for, warranty, support, -indemnity or liability obligations to one or more recipients of Covered -Software. However, You may do so only on Your own behalf, and not on -behalf of any Contributor. You must make it absolutely clear that any -such warranty, support, indemnity, or liability obligation is offered by -You alone, and You hereby agree to indemnify every Contributor for any -liability incurred by such Contributor as a result of warranty, support, -indemnity or liability terms You offer. You may include additional -disclaimers of warranty and limitations of liability specific to any -jurisdiction. - -4. Inability to Comply Due to Statute or Regulation ---------------------------------------------------- - -If it is impossible for You to comply with any of the terms of this -License with respect to some or all of the Covered Software due to -statute, judicial order, or regulation then You must: (a) comply with -the terms of this License to the maximum extent possible; and (b) -describe the limitations and the code they affect. Such description must -be placed in a text file included with all distributions of the Covered -Software under this License. Except to the extent prohibited by statute -or regulation, such description must be sufficiently detailed for a -recipient of ordinary skill to be able to understand it. - -5. Termination --------------- - -5.1. The rights granted under this License will terminate automatically -if You fail to comply with any of its terms. However, if You become -compliant, then the rights granted under this License from a particular -Contributor are reinstated (a) provisionally, unless and until such -Contributor explicitly and finally terminates Your grants, and (b) on an -ongoing basis, if such Contributor fails to notify You of the -non-compliance by some reasonable means prior to 60 days after You have -come back into compliance. Moreover, Your grants from a particular -Contributor are reinstated on an ongoing basis if such Contributor -notifies You of the non-compliance by some reasonable means, this is the -first time You have received notice of non-compliance with this License -from such Contributor, and You become compliant prior to 30 days after -Your receipt of the notice. - -5.2. If You initiate litigation against any entity by asserting a patent -infringement claim (excluding declaratory judgment actions, -counter-claims, and cross-claims) alleging that a Contributor Version -directly or indirectly infringes any patent, then the rights granted to -You by any and all Contributors for the Covered Software under Section -2.1 of this License shall terminate. - -5.3. In the event of termination under Sections 5.1 or 5.2 above, all -end user license agreements (excluding distributors and resellers) which -have been validly granted by You or Your distributors under this License -prior to termination shall survive termination. - -************************************************************************ -* * -* 6. Disclaimer of Warranty * -* ------------------------- * -* * -* Covered Software is provided under this License on an "as is" * -* basis, without warranty of any kind, either expressed, implied, or * -* statutory, including, without limitation, warranties that the * -* Covered Software is free of defects, merchantable, fit for a * -* particular purpose or non-infringing. The entire risk as to the * -* quality and performance of the Covered Software is with You. * -* Should any Covered Software prove defective in any respect, You * -* (not any Contributor) assume the cost of any necessary servicing, * -* repair, or correction. This disclaimer of warranty constitutes an * -* essential part of this License. No use of any Covered Software is * -* authorized under this License except under this disclaimer. * -* * -************************************************************************ - -************************************************************************ -* * -* 7. Limitation of Liability * -* -------------------------- * -* * -* Under no circumstances and under no legal theory, whether tort * -* (including negligence), contract, or otherwise, shall any * -* Contributor, or anyone who distributes Covered Software as * -* permitted above, be liable to You for any direct, indirect, * -* special, incidental, or consequential damages of any character * -* including, without limitation, damages for lost profits, loss of * -* goodwill, work stoppage, computer failure or malfunction, or any * -* and all other commercial damages or losses, even if such party * -* shall have been informed of the possibility of such damages. This * -* limitation of liability shall not apply to liability for death or * -* personal injury resulting from such party's negligence to the * -* extent applicable law prohibits such limitation. Some * -* jurisdictions do not allow the exclusion or limitation of * -* incidental or consequential damages, so this exclusion and * -* limitation may not apply to You. * -* * -************************************************************************ - -8. Litigation -------------- - -Any litigation relating to this License may be brought only in the -courts of a jurisdiction where the defendant maintains its principal -place of business and such litigation shall be governed by laws of that -jurisdiction, without reference to its conflict-of-law provisions. -Nothing in this Section shall prevent a party's ability to bring -cross-claims or counter-claims. - -9. Miscellaneous ----------------- - -This License represents the complete agreement concerning the subject -matter hereof. If any provision of this License is held to be -unenforceable, such provision shall be reformed only to the extent -necessary to make it enforceable. Any law or regulation which provides -that the language of a contract shall be construed against the drafter -shall not be used to construe this License against a Contributor. - -10. Versions of the License ---------------------------- - -10.1. New Versions - -Mozilla Foundation is the license steward. Except as provided in Section -10.3, no one other than the license steward has the right to modify or -publish new versions of this License. Each version will be given a -distinguishing version number. - -10.2. Effect of New Versions - -You may distribute the Covered Software under the terms of the version -of the License under which You originally received the Covered Software, -or under the terms of any subsequent version published by the license -steward. - -10.3. Modified Versions - -If you create software not governed by this License, and you want to -create a new license for such software, you may create and use a -modified version of this License if you rename the license and remove -any references to the name of the license steward (except to note that -such modified license differs from this License). - -10.4. Distributing Source Code Form that is Incompatible With Secondary -Licenses - -If You choose to distribute Source Code Form that is Incompatible With -Secondary Licenses under the terms of this version of the License, the -notice described in Exhibit B of this License must be attached. - -Exhibit A - Source Code Form License Notice -------------------------------------------- - - This Source Code Form is subject to the terms of the Mozilla Public - License, v. 2.0. If a copy of the MPL was not distributed with this - file, You can obtain one at https://mozilla.org/MPL/2.0/. - -If it is not possible or desirable to put the notice in a particular -file, then You may include the notice in a location (such as a LICENSE -file in a relevant directory) where a recipient would be likely to look -for such a notice. - -You may add additional accurate notices of copyright ownership. - -Exhibit B - "Incompatible With Secondary Licenses" Notice ---------------------------------------------------------- - - This Source Code Form is "Incompatible With Secondary Licenses", as - defined by the Mozilla Public License, v. 2.0. diff --git a/MAINTAINERS.adoc b/MAINTAINERS.adoc deleted file mode 100644 index 9910dd8..0000000 --- a/MAINTAINERS.adoc +++ /dev/null @@ -1,65 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell -= Maintainers -:toc: preamble - -== Current Maintainers - -[cols="2,3,2",options="header"] -|=== -| Name | Role | Contact - -| Jonathan D.A. Jewell | Sole Maintainer | https://github.com/hyperpolymath[@hyperpolymath] -|=== - -== Maintainer Responsibilities - -As the sole maintainer, all responsibilities apply to @hyperpolymath: - -* 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 -* Maintaining documentation and examples -* Responding to security vulnerabilities - -== Contribution Process - -This is a sole-maintainer project. All contributions are welcome via: - -1. **Issues**: Report bugs, request features, ask questions -2. **Pull Requests**: Submit improvements for review -3. **Discussions**: Engage in community discussions - -All contributions will be reviewed by the maintainer. - -== Decision Making - -* Routine decisions (bug fixes, minor improvements): Made by maintainer -* Significant changes: Discussed in issues before implementation -* Breaking changes: Announced in advance with migration path - -== Becoming a Maintainer - -This project currently has a single maintainer. If you're interested in becoming a co-maintainer: - -1. Demonstrate consistent, high-quality contributions -2. Show understanding of project goals and standards -3. Participate constructively in discussions -4. Express interest to the current maintainer - -Co-maintainers may be added at the discretion of the current maintainer. - -== Contact - -For questions about project governance: - -* Open a GitHub issue in this repository -* Contact: https://github.com/hyperpolymath - -== See Also - -* link:GOVERNANCE.adoc[Governance Model] -* link:CODE_OF_CONDUCT.md[Code of Conduct] -* link:CONTRIBUTING.adoc[Contributing Guide] diff --git a/README.adoc b/README.adoc index 6eb4a5e..0f88225 100644 --- a/README.adoc +++ b/README.adoc @@ -1,91 +1,37 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -// SPDX-FileCopyrightText: 2024-2026 Jonathan D.A. Jewell (hyperpolymath) -= {{PROJECT_NAME}} -:toc: -:toc-placement: preamble += A2ML Ecosystem Coordination Hub +:toc: preamble -image:https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensourcesecurity[OpenSSF Best Practices,link="https://www.bestpractices.dev/en/projects/new?repo_url=https://{{FORGE}}/{{OWNER}}/{{REPO}}"] -image:https://img.shields.io/badge/License-MPL_2.0-blue.svg[License: MPL-2.0,link="https://opensource.org/licenses/MPL-2.0"] -image:https://api.thegreenwebfoundation.org/greencheckimage/{{FORGE}}[Green Web,link="https://www.thegreenwebfoundation.org/green-web-check/?url={{FORGE}}"] +`hyperpolymath/a2ml-ecosystem` coordinates implementations, tooling, +CI integrations, examples, and conformance fixtures for A2ML. -{{PROJECT_DESCRIPTION}} +This repository is a satellite of `hyperpolymath/standards`. It does not own +the A2ML specification or governance rules. The upstream specification and +governance authority are pinned in link:ANCHOR.a2ml[ANCHOR.a2ml] by tag. -[IMPORTANT] -==== -*This file is a template.* You are reading `README.adoc` from the *RSR template repo* -(or a freshly-cloned copy of it). Run `just init` to replace every `{{PLACEHOLDER}}` -token with your project's details, then delete this admonition. Until you do, the -`{{...}}` markers below are intentional placeholders, not content. -==== +== Owned Here -== What this is +* link:ECOSYSTEM.a2ml[ECOSYSTEM.a2ml] records the member repository manifest. +* link:conformance/manifest.a2ml[conformance/manifest.a2ml] indexes the local + positive and negative fixtures. +* link:scripts/check-membership.sh[scripts/check-membership.sh] checks that + manifest entries, submodule declarations, and gitlinks stay aligned. +* `.github/workflows/anchor-drift.yml` runs anchor drift checks in CI. -A new repository scaffolded from the *Rhodium Standard Repository (RSR)* template: -a batteries-included starting point that ships with CI/CD, machine-readable project -metadata, an AI-agent gatekeeper protocol, a formally-typed ABI/FFI seam -(Idris2 + Zig), container and reproducible-build scaffolding, and governance -infrastructure — all wired and passing the RSR validators on day one. +== Not Owned Here -Replace this section with a description of *your* project once initialised. +The A2ML specification is owned by `hyperpolymath/standards`. This hub points +to `docs/A2ML-SPEC.adoc` there; until the first standards tag is cut, the pin +is intentionally `TODO-tag`. -== Quick start +== Membership Layout -[source,bash] ----- -# 1. Create a repo from this template (or clone it), then from the repo root: -just init # interactive bootstrap: fills every {{PLACEHOLDER}} +Member repositories are pinned as submodules under `members//` on +their `main` branches. The groups are: -# 2. See the available tasks: -just # lists all phases (build, test, validate, audit, ...) +* `implementations` +* `tooling` +* `ci` +* `examples` -# 3. Check the repo still satisfies the RSR shape: -just validate # structure + metadata checks ----- - -`just init` prompts for the project name, owner, author, licence contact, and the -other values listed in `.machine_readable/ai/PLACEHOLDERS.adoc`, substitutes them -across the tree, validates the result, and (if available) runs the `k9-svc` checks. - -== What you get - -* *Machine-readable metadata* (`.machine_readable/6a2/`) — `STATE`, `META`, - `ECOSYSTEM`, `PLAYBOOK`, `AGENTIC`, `NEUROSYM`, `CLADE`, and `anchors/ANCHOR`, - in a2ml, so tools and agents can read the project's state and boundaries. -* *AI gatekeeper protocol* — `0-AI-MANIFEST.a2ml` is the universal entry point that - tells an AI agent how to work in this repo before it touches anything. -* *Typed ABI/FFI seam* — `src/interface/Abi/` (Idris2 type + layout proofs) over - `src/interface/ffi/` (Zig implementation), with generated C headers. -* *CI/CD* — GitHub Actions for quality, security (CodeQL, Scorecard, secret - scanning), multi-forge mirroring, and RSR anti-pattern enforcement. -* *Supply-chain & reproducibility* — container layering (stapeln), Nix/Guix shells, - SBOM, and signing hooks. -* *Governance* — `GOVERNANCE.adoc`, `MAINTAINERS.adoc`, `.github/` community health - files, and a release `AUDIT.adoc` gate. - -== Repository map - -[cols="1,3"] -|=== -| Path | What lives there - -| `0-AI-MANIFEST.a2ml` | Universal entry point for AI agents (read first). -| `.machine_readable/` | Project metadata, policies, contractiles, AI configs. -| `src/interface/` | Typed ABI (Idris2) + FFI (Zig) + generated headers. -| `docs/` | Onboarding, status, governance, practice, decisions. -| `build/`, `Justfile` | Task orchestration (`just` phases delegate to `build/just/*.just`). -| `.github/` | Workflows + community health files. -| `tests/`, `benches/` | Test suites and benchmarks. -|=== - -== Where to go next - -* `EXPLAINME.adoc` — the engineering deep-dive: how the pieces actually work. -* `AFFIRMATION.adoc` — the dated, signed honesty snapshot of the repo's true state. -* `AUDIT.adoc` — the release audit gate. -* `.machine_readable/ai/PLACEHOLDERS.adoc` — the full placeholder reference. - -== Licence - -Released under the link:LICENSE[Mozilla Public License 2.0] unless a per-file -`SPDX-License-Identifier` says otherwise. +`contractiles-a2-lab` is intentionally not a member submodule because it is +private. It is recorded only as a related project in `ECOSYSTEM.a2ml`. diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index de2200f..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,16 +0,0 @@ - -# Security Policy - -## Reporting a Vulnerability - -**Email:** j.d.a.jewell@open.ac.uk - -**Response timeline:** -- Acknowledgement within 48 hours -- Initial assessment within 7 days -- Fix or mitigation within 90 days - -**Safe harbour:** We will not pursue legal action against security researchers who follow responsible disclosure. diff --git a/SETUP.md b/SETUP.md new file mode 100644 index 0000000..7bc456c --- /dev/null +++ b/SETUP.md @@ -0,0 +1,32 @@ +# Setup + +This repository is a coordination hub and satellite of +`hyperpolymath/standards`. + +## Fresh Checkout + +```sh +git clone https://github.com/hyperpolymath/a2ml-ecosystem.git +cd a2ml-ecosystem +git submodule update --init --recursive +``` + +For local estate work, prefer: + +```sh +scripts/init-submodules.sh +scripts/check-membership.sh +``` + +`scripts/init-submodules.sh` initializes from sibling local checkouts when +they are present and skips members that are not available in the local scope. + +## Validation + +```sh +INPUT_PATH=. INPUT_STRICT=true INPUT_PATHS_IGNORE=$'conformance/\nmembers/' ../a2ml/a2ml-validate-action/validate-a2ml.sh +INPUT_PATH=conformance/valid INPUT_STRICT=true ../a2ml/a2ml-validate-action/validate-a2ml.sh +INPUT_PATH=conformance/invalid INPUT_STRICT=true ../a2ml/a2ml-validate-action/validate-a2ml.sh +``` + +The invalid conformance command is expected to fail. diff --git a/abi.ipkg b/abi.ipkg deleted file mode 100644 index 4b62c0b..0000000 --- a/abi.ipkg +++ /dev/null @@ -1,36 +0,0 @@ --- SPDX-License-Identifier: MPL-2.0 --- Copyright (c) Jonathan D.A. Jewell --- --- Idris2 package for the formally-typed ABI seam. --- --- The seam lives in a single, case-consistent directory src/interface/Abi/ --- (uppercase) so the physical path matches the `module Abi.*` namespace on --- EVERY filesystem. Idris2 requires capitalised namespace components, and a --- lowercase abi/ directory cannot satisfy that without a case-twin symlink --- (src/interface/Abi -> abi) that collides on case-insensitive filesystems --- (macOS/Windows). One case-consistent directory has exactly one path identity --- under case-folding, so the collision is impossible by construction. --- --- A bare `idris2 --check src/interface/Abi/Foo.idr` still warns ("module name --- does not match file name") because Idris derives the expected module from the --- full path; that is expected. Use the package for a real typecheck: --- idris2 --typecheck abi.ipkg (or --build) --- --- The RSR validators accept either Abi/ (canonical, case-consistent) or a --- lowercase abi/ for downstream repos that ship lowercase — but never both. - -package abi - -version = 0.1.0 - -authors = "Jonathan D.A. Jewell" - -brief = "Formally-typed ABI/FFI seam (Idris2 type + layout proofs) for an RSR-templated repository" - -sourcedir = "src/interface" - -depends = base - -modules = Abi.Types - , Abi.Layout - , Abi.Foreign diff --git a/benches/template_bench.sh b/benches/template_bench.sh deleted file mode 100755 index 5fb58a8..0000000 --- a/benches/template_bench.sh +++ /dev/null @@ -1,227 +0,0 @@ -#!/bin/bash -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# Template Benchmarks -# Measures performance characteristics of template validation and build system - -set -euo pipefail - -REPO_ROOT="${1:-.}" -OUTPUT_FORMAT="${2:-human}" # human | json | csv - -# ANSI colors -BLUE='\033[0;34m' -GREEN='\033[0;32m' -YELLOW='\033[1;33m' -NC='\033[0m' # No Color - -log_info() { - echo -e "${BLUE}→${NC} $*" -} - -log_pass() { - echo -e "${GREEN}✓${NC} $*" -} - -# Ensure we have required commands -command -v /usr/bin/time >/dev/null 2>&1 || { - echo "Warning: /usr/bin/time not available, using built-in time" - TIME_CMD="time" -} - -TIME_CMD="/usr/bin/time -f %e" 2>/dev/null || TIME_CMD="time" - -echo "" -echo "═══════════════════════════════════════════════════════════════════════════════" -echo "Template Benchmarks" -echo "═══════════════════════════════════════════════════════════════════════════════" -echo "" - -declare -A results - -#============================================================================== -# BENCHMARK 1: Template Validation -#============================================================================== - -log_info "Running template validation benchmark" - -# Warm-up run -if [ -f "$REPO_ROOT/scripts/validate-template.sh" ]; then - bash "$REPO_ROOT/scripts/validate-template.sh" "$REPO_ROOT" 0 > /dev/null 2>&1 || true -fi - -# Timed runs -BENCH_RUNS=3 -TOTAL_TIME=0 - -for i in $(seq 1 $BENCH_RUNS); do - START=$(date +%s%N) - bash "$REPO_ROOT/scripts/validate-template.sh" "$REPO_ROOT" 0 > /dev/null 2>&1 || true - END=$(date +%s%N) - - # Convert to milliseconds - RUN_TIME=$(( (END - START) / 1000000 )) - TOTAL_TIME=$(( TOTAL_TIME + RUN_TIME )) - - [ "$OUTPUT_FORMAT" = "human" ] && echo " Run $i: ${RUN_TIME}ms" -done - -AVG_VALIDATION_TIME=$(( TOTAL_TIME / BENCH_RUNS )) -results[validation]=$AVG_VALIDATION_TIME -log_pass "Validation: ${AVG_VALIDATION_TIME}ms average (${BENCH_RUNS} runs)" - -#============================================================================== -# BENCHMARK 2: Zig Build -#============================================================================== - -log_info "Running Zig build benchmark" - -if ! command -v zig &> /dev/null; then - echo " ⚠ Zig compiler not found - skipping Zig build benchmark" - results[zig_build]="skipped" -else - cd "$REPO_ROOT/src/interface/ffi" - - # Warm-up - zig build --summary off > /dev/null 2>&1 || true - - # Clean build - BENCH_RUNS=2 - TOTAL_TIME=0 - - for i in $(seq 1 $BENCH_RUNS); do - rm -rf zig-cache - - START=$(date +%s%N) - zig build --summary off > /dev/null 2>&1 || true - END=$(date +%s%N) - - RUN_TIME=$(( (END - START) / 1000000 )) - TOTAL_TIME=$(( TOTAL_TIME + RUN_TIME )) - - [ "$OUTPUT_FORMAT" = "human" ] && echo " Run $i: ${RUN_TIME}ms" - done - - AVG_BUILD_TIME=$(( TOTAL_TIME / BENCH_RUNS )) - results[zig_build]=$AVG_BUILD_TIME - log_pass "Zig build: ${AVG_BUILD_TIME}ms average (clean build, ${BENCH_RUNS} runs)" - - cd - > /dev/null -fi - -#============================================================================== -# BENCHMARK 3: Zig Tests -#============================================================================== - -log_info "Running Zig test benchmark" - -if ! command -v zig &> /dev/null; then - echo " ⚠ Zig compiler not found - skipping Zig test benchmark" - results[zig_test]="skipped" -else - cd "$REPO_ROOT/src/interface/ffi" - - # Warm-up - zig build test --summary off > /dev/null 2>&1 || true - - START=$(date +%s%N) - TEST_OUTPUT=$(zig build test --summary off 2>&1 || true) - END=$(date +%s%N) - - TEST_TIME=$(( (END - START) / 1000000 )) - results[zig_test]=$TEST_TIME - log_pass "Zig tests: ${TEST_TIME}ms" - - # Count tests - TEST_COUNT=$(echo "$TEST_OUTPUT" | grep -c "^test " || echo "unknown") - echo " Test count: $TEST_COUNT" - - cd - > /dev/null -fi - -#============================================================================== -# BENCHMARK 4: Workflow Validation -#============================================================================== - -log_info "Running workflow validation benchmark" - -if [ -f "$REPO_ROOT/tests/workflows/validate_workflows_test.sh" ]; then - START=$(date +%s%N) - bash "$REPO_ROOT/tests/workflows/validate_workflows_test.sh" "$REPO_ROOT/.github/workflows" > /dev/null 2>&1 || true - END=$(date +%s%N) - - WORKFLOW_TIME=$(( (END - START) / 1000000 )) - results[workflow_validation]=$WORKFLOW_TIME - log_pass "Workflow validation: ${WORKFLOW_TIME}ms" -fi - -#============================================================================== -# BENCHMARK 5: Template Instantiation -#============================================================================== - -log_info "Running template instantiation benchmark" - -if [ -f "$REPO_ROOT/tests/e2e/template_instantiation_test.sh" ]; then - START=$(date +%s%N) - bash "$REPO_ROOT/tests/e2e/template_instantiation_test.sh" "$REPO_ROOT" > /dev/null 2>&1 || true - END=$(date +%s%N) - - INSTANTIATION_TIME=$(( (END - START) / 1000000 )) - results[instantiation]=$INSTANTIATION_TIME - log_pass "Template instantiation: ${INSTANTIATION_TIME}ms" -fi - -#============================================================================== -# SUMMARY -#============================================================================== - -echo "" -echo "═══════════════════════════════════════════════════════════════════════════════" -echo "BENCHMARK RESULTS" -echo "═══════════════════════════════════════════════════════════════════════════════" -echo "" - -if [ "$OUTPUT_FORMAT" = "json" ]; then - echo "{" - echo " \"timestamp\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"," - echo " \"repo\": \"$REPO_ROOT\"," - echo " \"results\": {" - - count=0 - for key in "${!results[@]}"; do - value="${results[$key]}" - [ $count -gt 0 ] && echo "," - if [ "$value" = "skipped" ]; then - echo -n " \"$key\": \"skipped\"" - else - echo -n " \"$key\": $value" - fi - count=$((count + 1)) - done - echo "" - echo " }" - echo "}" -elif [ "$OUTPUT_FORMAT" = "csv" ]; then - echo "metric,value_ms,timestamp" - for key in "${!results[@]}"; do - value="${results[$key]}" - if [ "$value" != "skipped" ]; then - echo "$key,$value,$(date -u +%Y-%m-%dT%H:%M:%SZ)" - fi - done -else - # Human-readable format - for key in "${!results[@]}"; do - value="${results[$key]}" - if [ "$value" = "skipped" ]; then - printf " %-30s %s\n" "$key:" "SKIPPED" - else - printf " %-30s %5d ms\n" "$key:" "$value" - fi - done -fi - -echo "" -echo "Benchmark complete." -echo "" diff --git a/build/.guix-channel b/build/.guix-channel deleted file mode 100644 index f9bdf68..0000000 --- a/build/.guix-channel +++ /dev/null @@ -1,22 +0,0 @@ -;; SPDX-License-Identifier: MPL-2.0 -;; Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -;; -;; Guix channel definition for {{PROJECT_NAME}} -;; -;; To use this channel, add to ~/.config/guix/channels.scm: -;; -;; (channel -;; (name '{{PROJECT_NAME}}) -;; (url "https://github.com/{{OWNER}}/{{PROJECT_NAME}}") -;; (branch "main")) -;; -;; Then: guix pull - -(channel - (version 0) - (url "https://github.com/{{OWNER}}/{{PROJECT_NAME}}") - (dependencies - (channel - (name 'guix) - (url "https://git.savannah.gnu.org/git/guix.git") - (branch "master")))) diff --git a/build/Containerfile b/build/Containerfile deleted file mode 100644 index d7266bc..0000000 --- a/build/Containerfile +++ /dev/null @@ -1,41 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -# -# Containerfile for {{PROJECT_NAME}} -# Build: podman build -t {{project}}:latest -f Containerfile . -# Run: podman run --rm -it {{project}}:latest -# Seal: selur seal {{project}}:latest - -# --- Build stage --- -FROM cgr.dev/chainguard/wolfi-base:latest AS build - -# TODO: Install build dependencies for your stack -# Examples: -# RUN apk add --no-cache rust cargo # Rust -# RUN apk add --no-cache elixir erlang # Elixir -# RUN apk add --no-cache zig # Zig - -WORKDIR /build -COPY . . - -# TODO: Replace with your build command -# Examples: -# RUN cargo build --release -# RUN mix deps.get && MIX_ENV=prod mix release -# RUN zig build -Doptimize=ReleaseSafe - -# --- Runtime stage --- -FROM cgr.dev/chainguard/static:latest - -# Copy built artifact from build stage -# TODO: Replace with your binary/artifact path -# Examples: -# COPY --from=build /build/target/release/{{project}} /usr/local/bin/ -# COPY --from=build /build/_build/prod/rel/{{project}} /app/ -# COPY --from=build /build/zig-out/bin/{{project}} /usr/local/bin/ - -# Non-root user (chainguard images default to nonroot) -USER nonroot - -# TODO: Replace with your entrypoint -# ENTRYPOINT ["/usr/local/bin/{{project}}"] diff --git a/build/contractile.just b/build/contractile.just deleted file mode 100644 index 9a5827b..0000000 --- a/build/contractile.just +++ /dev/null @@ -1,75 +0,0 @@ -# Auto-generated by: contractile gen-just -# Source directory: contractiles -# Re-generate with: contractile gen-just --dir contractiles -# -# SPDX-License-Identifier: MPL-2.0 - -# === DUST (Recovery & Rollback) === -# Source: Dustfile.a2ml - -# List available dust recovery actions -dust-status: - @echo ' dust-source-rollback: Revert all source changes to last commit [rollback]' - -# Revert all source changes to last commit -dust-source-rollback: - @echo 'Executing rollback for source-rollback' - git checkout HEAD -- . - - -# === INTEND (Declared Future Intent) === -# Source: Intentfile.a2ml - -# Display declared future intents -intend-list: - @echo '=== Declared Intent ===' - @echo '' - @echo 'Features:' - @echo '' - @echo 'Quality:' - - -# === MUST (Physical State Checks) === -# Source: Mustfile.a2ml - -# Run all must checks -must-check: must-license-present must-readme-present must-spdx-headers must-no-banned-files - @echo 'All must checks passed' - -# LICENSE file must exist -must-license-present: - test -f LICENSE - -# README must exist -must-readme-present: - test -f README.adoc || test -f README.md - -# Source files should have SPDX license headers -must-spdx-headers: - find . -name '*.rs' -o -name '*.res' -o -name '*.gleam' | head -20 | xargs -r grep -L 'SPDX-License-Identifier' | wc -l | grep -q '^0$' - -# No Dockerfiles or Makefiles -must-no-banned-files: - test ! -f Dockerfile && test ! -f Makefile - - -# === TRUST (Integrity & Provenance Verification) === -# Source: Trustfile.a2ml - -# Run all trust verifications -trust-verify: trust-license-content trust-no-secrets-committed trust-container-images-pinned - @echo 'All trust verifications passed' - -# LICENSE contains expected SPDX identifier -trust-license-content: - grep -q 'SPDX\|License\|MIT\|Apache\|PMPL\|MPL' LICENSE - -# No .env or credential files in repo -trust-no-secrets-committed: - test ! -f .env && test ! -f credentials.json && test ! -f .env.local - -# Containerfile base images use pinned digests -trust-container-images-pinned: - test ! -f Containerfile || grep -q '@sha256:' Containerfile - - diff --git a/build/guix.scm b/build/guix.scm deleted file mode 100644 index 33b1a9a..0000000 --- a/build/guix.scm +++ /dev/null @@ -1,71 +0,0 @@ -;; SPDX-License-Identifier: MPL-2.0 -;; Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -;; -;; Guix package definition for {{PROJECT_NAME}} -;; -;; Usage: -;; guix shell -D -f guix.scm # Enter development shell -;; guix build -f guix.scm # Build package -;; -;; TODO: Replace {{PROJECT_NAME}} and customize inputs for your language/stack. -;; See: https://guix.gnu.org/manual/en/html_node/Defining-Packages.html - -(use-modules (guix packages) - (guix gexp) - (guix git-download) - (guix build-system gnu) - (guix licenses) - (gnu packages base)) - -(package - (name "{{PROJECT_NAME}}") - (version "0.1.0") - (source (local-file "." "source" - #:recursive? #t - #:select? (lambda (file stat) - (not (string-contains file ".git"))))) - (build-system gnu-build-system) - (arguments - '(#:phases - (modify-phases %standard-phases - ;; TODO: Customize build phases for your project - ;; Examples for common stacks: - ;; - ;; Rust: - ;; (replace 'build (lambda _ (invoke "cargo" "build" "--release"))) - ;; (replace 'check (lambda _ (invoke "cargo" "test"))) - ;; - ;; Elixir: - ;; (replace 'build (lambda _ (invoke "mix" "compile"))) - ;; (replace 'check (lambda _ (invoke "mix" "test"))) - ;; - ;; Zig: - ;; (replace 'build (lambda _ (invoke "zig" "build"))) - ;; (replace 'check (lambda _ (invoke "zig" "build" "test"))) - (delete 'configure) - (delete 'build) - (delete 'check) - (replace 'install - (lambda* (#:key outputs #:allow-other-keys) - (let ((out (assoc-ref outputs "out"))) - (mkdir-p (string-append out "/share/doc")) - (copy-file "README.adoc" - (string-append out "/share/doc/README.adoc")))))))) - (native-inputs - (list - ;; TODO: Add build-time dependencies - ;; Examples: - ;; rust (gnu packages rust) - ;; elixir (gnu packages elixir) - ;; zig (gnu packages zig) - )) - (inputs - (list - ;; TODO: Add runtime dependencies - )) - (home-page "https://github.com/{{OWNER}}/{{PROJECT_NAME}}") - (synopsis "{{PROJECT_PURPOSE}}") - (description "RSR-compliant project. See README.adoc for details.") - (license (list - ;; MPL-2.0 extends MPL-2.0 - mpl2.0))) diff --git a/build/just/assess.just b/build/just/assess.just deleted file mode 100644 index 2417778..0000000 --- a/build/just/assess.just +++ /dev/null @@ -1,225 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# PROJECT SELF-ASSESSMENT + OPENSSF COMPLIANCE VERIFICATION -# -# Imported by ../../Justfile via `import? "build/just/assess.just"`. -# Recipes here advise on what to keep/remove (`self-assess`, read-only) and -# verify that OpenSSF Best Practices prerequisites are present (`verify`, -# called by `init` and CI). - -# Analyse this project and advise what to keep, remove, or leave for later. -# Does NOT modify any files — only prints recommendations. -self-assess: - #!/usr/bin/env bash - set -euo pipefail - - echo "═══════════════════════════════════════════════════" - echo " RSR Project Self-Assessment" - echo "═══════════════════════════════════════════════════" - echo "" - echo "Scanning project structure to identify what's" - echo "relevant, removable, or worth keeping for later..." - echo "" - - # Detect project characteristics - HAS_RUST=false; [ -f "Cargo.toml" ] && HAS_RUST=true - HAS_ELIXIR=false; [ -f "mix.exs" ] && HAS_ELIXIR=true - HAS_RESCRIPT=false; [ -f "rescript.json" ] || [ -f "bsconfig.json" ] && HAS_RESCRIPT=true - HAS_IDRIS=false; ls *.ipkg >/dev/null 2>&1 && HAS_IDRIS=true - HAS_ZIG=false; [ -f "build.zig" ] || [ -d "ffi/zig" ] && HAS_ZIG=true - HAS_GLEAM=false; [ -f "gleam.toml" ] && HAS_GLEAM=true - HAS_CONTAINER=false; [ -f "Containerfile" ] || [ -f "container/Containerfile" ] || [ -f "build/Containerfile" ] && HAS_CONTAINER=true - HAS_TESTS=false; [ -d "test" ] || [ -d "tests" ] || [ -d "__tests__" ] && HAS_TESTS=true - HAS_API=false; grep -rq 'port\|listen\|endpoint' --include="*.exs" --include="*.rs" --include="*.toml" . 2>/dev/null && HAS_API=true - IS_LIBRARY=false; [ -f "Cargo.toml" ] && grep -q '\[lib\]' Cargo.toml 2>/dev/null && IS_LIBRARY=true - - echo "Detected: Rust=$HAS_RUST Elixir=$HAS_ELIXIR ReScript=$HAS_RESCRIPT" - echo " Idris=$HAS_IDRIS Zig=$HAS_ZIG Gleam=$HAS_GLEAM" - echo " Container=$HAS_CONTAINER Tests=$HAS_TESTS API=$HAS_API" - echo "" - - # ── ESSENTIAL (removing these breaks RSR compliance) ────────── - echo "── ESSENTIAL (removing breaks Rhodium Standard) ──────────" - echo "" - - for f in LICENSE SECURITY.md CODE_OF_CONDUCT.md CONTRIBUTING.md .editorconfig .gitignore; do - if [ -f "$f" ]; then - echo " ✓ $f — KEEP (RSR required)" - else - echo " ✗ $f — MISSING (RSR violation!)" - fi - done - - if [ -d ".machine_readable/6a2" ]; then - echo " ✓ .machine_readable/6a2/ — KEEP (SCM checkpoint files)" - else - echo " ✗ .machine_readable/6a2/ — MISSING (RSR violation!)" - fi - - if [ -d ".github/workflows" ]; then - WF_COUNT=$(ls .github/workflows/*.yml 2>/dev/null | wc -l) - echo " ✓ .github/workflows/ — KEEP ($WF_COUNT workflows, RSR CI/CD)" - fi - echo "" - - # ── RELEVANT (useful for your project type) ─────────────────── - echo "── RELEVANT (matches your project) ───────────────────────" - echo "" - - if $HAS_IDRIS && { [ -d "src/interface/abi" ] || [ -d "src/interface/Abi" ]; }; then - echo " ✓ src/interface/abi/ — KEEP (Idris2 ABI definitions)" - elif ! $HAS_IDRIS && { [ -d "src/interface/abi" ] || [ -d "src/interface/Abi" ]; }; then - echo " ? src/interface/abi/ — No Idris2 detected." - echo " → KEEP if you plan to add formal verification later." - echo " → SAFE TO REMOVE if this project will never use Idris2." - echo " ⚠ Consequence: no formally verified interface definitions." - fi - - if $HAS_ZIG && [ -d "src/interface/ffi" ]; then - echo " ✓ src/interface/ffi/ — KEEP (Zig FFI bridge)" - elif ! $HAS_ZIG && [ -d "src/interface/ffi" ]; then - echo " ? src/interface/ffi/ — No Zig detected." - echo " → KEEP if you plan C ABI interop later." - echo " → SAFE TO REMOVE if this is a pure web/scripting project." - echo " ⚠ Consequence: no C-compatible FFI bridge." - fi - - if $HAS_API && [ -f ".machine_readable/integrations/groove.a2ml" ]; then - PORT=$(grep '(port ' .machine_readable/integrations/groove.a2ml 2>/dev/null | sed 's/.*(port \([0-9]*\)).*/\1/') - if [ "$PORT" = "0" ]; then - echo " ⚠ groove.a2ml — Port not assigned. Run 'just groove-setup'." - else - echo " ✓ groove.a2ml — KEEP (Groove discovery on port $PORT)" - fi - elif $HAS_API; then - echo " ✗ groove.a2ml — MISSING. Your project has an API but no Groove manifest." - echo " → Run 'just groove-setup' to enable snap-on/snap-off discovery." - fi - - if $HAS_CONTAINER && [ -d "container" ]; then - echo " ✓ container/ — KEEP (Containerfile + compose)" - elif ! $HAS_CONTAINER && [ -d "container" ]; then - echo " ? container/ — No Containerfile detected in use." - echo " → KEEP if you plan to containerise later." - echo " → SAFE TO REMOVE for libraries and CLI tools." - fi - - echo "" - - # ── SAFE TO REMOVE (not relevant, no consequences) ──────────── - echo "── SAFE TO REMOVE (no RSR consequences) ──────────────────" - echo "" - - if ! $HAS_RESCRIPT && [ -d "examples" ] && ls examples/*.res >/dev/null 2>&1; then - echo " ○ examples/*.res — Template ReScript examples. Not your code." - fi - - if [ -f ".machine_readable/ai/PLACEHOLDERS.adoc" ]; then - echo " ○ .machine_readable/ai/PLACEHOLDERS.adoc — Template doc. Remove after init." - fi - - if { [ -f "build/flake.nix" ] || [ -f "flake.nix" ]; } && ! command -v nix >/dev/null 2>&1; then - echo " ○ flake.nix — Nix flake. Safe to remove if you don't use Nix." - echo " → KEEP if others might build with Nix." - fi - - if { [ -f "build/guix.scm" ] || [ -f "guix.scm" ]; } && ! command -v guix >/dev/null 2>&1; then - echo " ○ guix.scm — Guix package. Safe to remove if you don't use Guix." - echo " → KEEP if others might build with Guix." - fi - - echo "" - - # ── FUTURE VALUE (not needed now, worth keeping) ────────────── - echo "── KEEP FOR FUTURE (not active, but valuable later) ──────" - echo "" - - if [ -d ".machine_readable/contractiles" ]; then - echo " ◆ contractiles/ — Must/Trust/Dust/Lust contracts." - echo " Not enforced until you configure them, but ready when you need" - echo " automated compliance checking. Zero cost to keep." - fi - - if [ -d ".machine_readable/bot_directives" ]; then - echo " ◆ bot_directives/ — Gitbot fleet configuration." - echo " Not active until gitbot-fleet is connected. Keeps your repo" - echo " ready for automated maintenance when the fleet arrives." - fi - - if [ -d ".machine_readable/bot_directives" ]; then - echo " ◆ bot_directives/ — AI agent methodology config." - echo " Guides Claude/Gemini/etc on how to work in this repo." - echo " No cost to keep. Improves AI assistance quality." - fi - - if [ -d "docs/governance" ]; then - echo " ◆ docs/governance/ — TSDM, CRG, maintenance checklists." - echo " Not needed for solo projects. Essential when you add contributors." - fi - - if [ -d "verification" ]; then - echo " ◆ verification/ — Proofs, benchmarks, fuzzing, safety case." - echo " Empty scaffolds until you add formal verification." - echo " Worth keeping for any project that claims safety properties." - fi - - echo "" - echo "═══════════════════════════════════════════════════" - echo " Assessment complete. No files were modified." - echo "═══════════════════════════════════════════════════" - -# Verify OpenSSF Best Practices prerequisites — fails if any required file is missing -verify: - #!/usr/bin/env bash - set -euo pipefail - - echo "=== OpenSSF Best Practices Verification ===" - ERRORS=0 - - check_file() { - if [ ! -f "$1" ]; then - echo " FAIL: $1 missing" - ERRORS=$((ERRORS + 1)) - else - echo " OK: $1" - fi - } - - # Accept either .md or .adoc for documentation files - check_either() { - if [ ! -f "$1" ] && [ ! -f "$2" ]; then - echo " FAIL: $1 (or $2) missing" - ERRORS=$((ERRORS + 1)) - else - local found="$1" - [ -f "$2" ] && found="$2" - [ -f "$1" ] && found="$1" - echo " OK: $found" - fi - } - - check_either "SECURITY.md" "SECURITY.adoc" - check_file "LICENSE" - check_either "CONTRIBUTING.md" "CONTRIBUTING.adoc" - check_either "README.adoc" "README.md" - check_file ".machine_readable/6a2/STATE.a2ml" - check_file ".machine_readable/6a2/META.a2ml" - check_file ".machine_readable/6a2/ECOSYSTEM.a2ml" - check_either "CHANGELOG.md" "CHANGELOG.adoc" - - # Check at least 1 workflow exists - WORKFLOW_COUNT=$(find .github/workflows -name '*.yml' -o -name '*.yaml' 2>/dev/null | wc -l) - if [ "$WORKFLOW_COUNT" -eq 0 ]; then - echo " FAIL: No workflows in .github/workflows/" - ERRORS=$((ERRORS + 1)) - else - echo " OK: .github/workflows/ ($WORKFLOW_COUNT workflows)" - fi - - echo "" - if [ "$ERRORS" -gt 0 ]; then - echo "FAIL: $ERRORS OpenSSF prerequisites missing — repo cannot ship." - exit 1 - fi - echo "PASS: All OpenSSF Best Practices prerequisites satisfied." diff --git a/build/just/groove.just b/build/just/groove.just deleted file mode 100644 index 029a9bd..0000000 --- a/build/just/groove.just +++ /dev/null @@ -1,98 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# GROOVE PROTOCOL -# -# Imported by ../../Justfile via `import? "build/just/groove.just"`. -# Recipes here configure and validate the Groove protocol manifest at -# .machine_readable/integrations/groove.a2ml — port assignment, API surface -# flags (REST/gRPC/GraphQL/WebSocket/SSE), and template-placeholder hygiene. -# The manifest itself is consumed by the Groove bridge / zig-unified-api-adapter. - -# Configure Groove protocol manifest (port assignment, API surfaces) -groove-setup: - #!/usr/bin/env bash - set -euo pipefail - MANIFEST=".machine_readable/integrations/groove.a2ml" - if [ ! -f "$MANIFEST" ]; then - echo "Error: $MANIFEST not found. Run 'just init' first." - exit 1 - fi - - echo "═══════════════════════════════════════════════════" - echo " Groove Protocol Setup" - echo "═══════════════════════════════════════════════════" - echo "" - echo "Check PORT-REGISTRY.md before assigning a port:" - echo " https://github.com/hyperpolymath/standards/blob/main/PORT-REGISTRY.md" - echo "" - - read -rp "Primary port for this service: " PORT - [ -z "$PORT" ] && echo "Error: port required" && exit 1 - - echo "" - echo "Which API surfaces does this project expose?" - read -rp " REST API? [Y/n]: " REST - read -rp " gRPC? [y/N]: " GRPC - read -rp " GraphQL? [y/N]: " GRAPHQL - read -rp " WebSocket? [y/N]: " WS - read -rp " SSE (Server-Sent Events)? [y/N]: " SSE - - # Update port in manifest - sed -i "s/(port 0)/(port ${PORT})/" "$MANIFEST" - - # Update API surface flags - [[ "${GRPC,,}" == "y" ]] && sed -i 's/(grpc.*enabled false)/(grpc (enabled true)/' "$MANIFEST" - [[ "${GRAPHQL,,}" == "y" ]] && sed -i 's/(graphql.*enabled false)/(graphql (enabled true)/' "$MANIFEST" - [[ "${WS,,}" == "y" ]] && sed -i 's/(websocket.*enabled false)/(websocket (enabled true)/' "$MANIFEST" - [[ "${SSE,,}" == "y" ]] && sed -i 's/(sse.*enabled false)/(sse (enabled true)/' "$MANIFEST" - - echo "" - echo "Groove manifest updated: $MANIFEST" - echo "Port ${PORT} assigned. Add to PORT-REGISTRY.md if not already there." - -# Check for template placeholders that haven't been replaced -verify-template: - #!/usr/bin/env bash - set -euo pipefail - echo "Checking for unreplaced template placeholders..." - FOUND=0 - - # Check for double-brace placeholder patterns - HITS=$(grep -rn '{{'{{'}}[A-Z_]*{{'}}'}}' --include="*.adoc" --include="*.md" --include="*.a2ml" \ - --include="*.scm" --include="*.toml" --include="*.yml" --include="*.yaml" \ - . 2>/dev/null | grep -v 'node_modules\|\.git/' | grep -v 'PLACEHOLDERS.adoc' || true) - if [ -n "$HITS" ]; then - echo "" - echo "⚠ Unreplaced placeholders found:" - echo "$HITS" | head -20 - FOUND=1 - fi - - # Check for template defaults still present - if grep -q 'rsr-template-repo' Justfile 2>/dev/null; then - echo "⚠ Justfile still references 'rsr-template-repo' — update project name" - FOUND=1 - fi - - # Check for port 0 in Groove manifest - if grep -q '(port 0)' .machine_readable/integrations/groove.a2ml 2>/dev/null; then - echo "⚠ Groove manifest has port 0 — run 'just groove-setup' to assign a port" - FOUND=1 - fi - - # Check for empty SCM files - for f in .machine_readable/6a2/STATE.a2ml .machine_readable/6a2/META.a2ml .machine_readable/6a2/ECOSYSTEM.a2ml; do - if [ -f "$f" ] && grep -q '{{'{{'}}' "$f" 2>/dev/null; then - echo "⚠ $f still has template placeholders" - FOUND=1 - fi - done - - if [ $FOUND -eq 0 ]; then - echo "✓ No template placeholders found — project is properly customised." - else - echo "" - echo "Run 'just init' to replace placeholders, or edit files manually." - exit 1 - fi diff --git a/build/just/init.just b/build/just/init.just deleted file mode 100644 index 746b4f6..0000000 --- a/build/just/init.just +++ /dev/null @@ -1,214 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# INIT — Bootstrap a new project from this template -# -# Imported by ../../Justfile via `import? "build/just/init.just"`. -# Variables (project, OWNER, REPO, version, tier) and the `set shell` directive -# are inherited from the root Justfile. - -# Interactive project bootstrap — replaces all {{PLACEHOLDER}} tokens -init: - #!/usr/bin/env bash - set -euo pipefail - - echo "═══════════════════════════════════════════════════" - echo " RSR Project Bootstrap" - echo "═══════════════════════════════════════════════════" - echo "" - - # --- Load defaults from config (if exists) --- - # Create yours: ~/.config/rsr/defaults - # Format: OWNER=myorg AUTHOR="My Name" AUTHOR_EMAIL=me@example.org ... - DEFAULTS="${XDG_CONFIG_HOME:-$HOME/.config}/rsr/defaults" - if [ -f "$DEFAULTS" ]; then - echo "Loading defaults from $DEFAULTS" - # shellcheck source=/dev/null - source "$DEFAULTS" - echo "" - fi - - # --- Required values (pre-filled from defaults if available) --- - read -rp "Project name (human-readable, e.g. My Project): " PROJECT_NAME - [ -z "$PROJECT_NAME" ] && echo "Error: project name required" && exit 1 - - read -rp "Repository slug (e.g. my-project): " REPO - [ -z "$REPO" ] && echo "Error: repo slug required" && exit 1 - - read -rp "Owner [${OWNER:-}]: " _OWNER - OWNER="${_OWNER:-${OWNER:-}}" - [ -z "$OWNER" ] && echo "Error: owner required" && exit 1 - - read -rp "Author full name [${AUTHOR:-}]: " _AUTHOR - AUTHOR="${_AUTHOR:-${AUTHOR:-}}" - [ -z "$AUTHOR" ] && echo "Error: author name required" && exit 1 - - read -rp "Author email [${AUTHOR_EMAIL:-}]: " _AUTHOR_EMAIL - AUTHOR_EMAIL="${_AUTHOR_EMAIL:-${AUTHOR_EMAIL:-}}" - [ -z "$AUTHOR_EMAIL" ] && echo "Error: email required" && exit 1 - - # --- Optional values (pre-filled from defaults if available) --- - read -rp "Author organization [${AUTHOR_ORG:-none}]: " _AUTHOR_ORG - AUTHOR_ORG="${_AUTHOR_ORG:-${AUTHOR_ORG:-}}" - - read -rp "Previous/alt email [${AUTHOR_EMAIL_ALT:-none}]: " _AUTHOR_EMAIL_ALT - AUTHOR_EMAIL_ALT="${_AUTHOR_EMAIL_ALT:-${AUTHOR_EMAIL_ALT:-}}" - - read -rp "Project description []: " PROJECT_DESCRIPTION - - read -rp "Forge domain [${FORGE:-github.com}]: " _FORGE - FORGE="${_FORGE:-${FORGE:-github.com}}" - - read -rp "Security contact email [${SECURITY_EMAIL:-$AUTHOR_EMAIL}]: " _SECURITY_EMAIL - SECURITY_EMAIL="${_SECURITY_EMAIL:-${SECURITY_EMAIL:-$AUTHOR_EMAIL}}" - - read -rp "Conduct contact email [${CONDUCT_EMAIL:-$AUTHOR_EMAIL}]: " _CONDUCT_EMAIL - CONDUCT_EMAIL="${_CONDUCT_EMAIL:-${CONDUCT_EMAIL:-$AUTHOR_EMAIL}}" - - read -rp "Project type (library|binary|monorepo|service|website) [library]: " PROJECT_TYPE - PROJECT_TYPE="${PROJECT_TYPE:-library}" - - read -rp "Website URL [https://${FORGE}/${OWNER}/${REPO}]: " WEBSITE - WEBSITE="${WEBSITE:-https://${FORGE}/${OWNER}/${REPO}}" - - # --- Container values (optional — only relevant if container/ exists) --- - if [ -d "container" ]; then - echo "" - echo "── Container configuration (optional) ─────────" - read -rp "Service name [${REPO}]: " _SERVICE_NAME - SERVICE_NAME="${_SERVICE_NAME:-${REPO}}" - read -rp "Primary port [8080]: " _PORT - PORT="${_PORT:-8080}" - read -rp "Container registry [ghcr.io/${OWNER}]: " _REGISTRY - REGISTRY="${_REGISTRY:-ghcr.io/${OWNER}}" - else - SERVICE_NAME="${REPO}" - PORT="8080" - REGISTRY="ghcr.io/${OWNER}" - fi - - # --- Derived values --- - PROJECT_UPPER=$(echo "$REPO" | tr '[:lower:]-' '[:upper:]_') - PROJECT_LOWER=$(echo "$REPO" | tr '[:upper:]-' '[:lower:]_') - CURRENT_YEAR=$(date +%Y) - CURRENT_DATE=$(date +%Y-%m-%d) - VERSION="0.1.0" - - # Derive citation name parts (best-effort split on last space) - AUTHOR_LAST="${AUTHOR##* }" - AUTHOR_FIRST="${AUTHOR% *}" - FIRST_INITIAL="${AUTHOR_FIRST:0:1}." - if [ "$AUTHOR_LAST" = "$AUTHOR_FIRST" ]; then - AUTHOR_FIRST="$AUTHOR" - AUTHOR_LAST="" - FIRST_INITIAL="" - fi - - echo "" - echo "── Summary ──────────────────────────────────────" - echo " Project: $PROJECT_NAME" - echo " Repo: $REPO" - echo " Owner: $OWNER" - echo " Author: $AUTHOR <$AUTHOR_EMAIL>" - [ -n "$AUTHOR_ORG" ] && echo " Organization: $AUTHOR_ORG" - echo " Forge: $FORGE" - echo " Year: $CURRENT_YEAR" - echo "────────────────────────────────────────────────" - echo "" - read -rp "Proceed? [Y/n] " CONFIRM - [[ "${CONFIRM:-Y}" =~ ^[Nn] ]] && echo "Aborted." && exit 0 - - echo "" - echo "Replacing placeholders..." - - # Brace tokens as variables (hex avoids just interpolation) - LB=$(printf '\x7b\x7b') - RB=$(printf '\x7d\x7d') - - # Build the sed expression list - # Note: using | as delimiter since URLs contain / - SED_ARGS=( - -e "s|${LB}PROJECT_NAME${RB}|${PROJECT_NAME}|g" - -e "s|${LB}PROJECT_DESCRIPTION${RB}|${PROJECT_DESCRIPTION}|g" - -e "s|${LB}PROJECT${RB}|${PROJECT_UPPER}|g" - -e "s|${LB}project${RB}|${PROJECT_LOWER}|g" - -e "s|${LB}REPO${RB}|${REPO}|g" - -e "s|${LB}OWNER${RB}|${OWNER}|g" - -e "s|${LB}AUTHOR${RB}|${AUTHOR}|g" - -e "s|${LB}AUTHOR_EMAIL${RB}|${AUTHOR_EMAIL}|g" - -e "s|${LB}AUTHOR_ORG${RB}|${AUTHOR_ORG}|g" - -e "s|${LB}AUTHOR_LAST${RB}|${AUTHOR_LAST}|g" - -e "s|${LB}AUTHOR_FIRST${RB}|${AUTHOR_FIRST}|g" - -e "s|${LB}AUTHOR_INITIALS${RB}|${FIRST_INITIAL}|g" - -e "s|${LB}FORGE${RB}|${FORGE}|g" - -e "s|${LB}CURRENT_YEAR${RB}|${CURRENT_YEAR}|g" - -e "s|${LB}CURRENT_DATE${RB}|${CURRENT_DATE}|g" - -e "s|${LB}DATE${RB}|${CURRENT_DATE}|g" - -e "s|${LB}SECURITY_EMAIL${RB}|${SECURITY_EMAIL}|g" - -e "s|${LB}CONDUCT_EMAIL${RB}|${CONDUCT_EMAIL}|g" - -e "s|${LB}LICENSE${RB}|MPL-2.0|g" - -e "s|${LB}CONDUCT_TEAM${RB}|Code of Conduct Committee|g" - -e "s|${LB}RESPONSE_TIME${RB}|48 hours|g" - -e "s|${LB}MAIN_BRANCH${RB}|main|g" - -e "s|${LB}PROJECT_PURPOSE${RB}|${PROJECT_DESCRIPTION}|g" - -e "s|${LB}PROJECT_ROLE${RB}|${PROJECT_TYPE}|g" - -e "s|${LB}PROJECT_TYPE${RB}|${PROJECT_TYPE}|g" - -e "s|${LB}WEBSITE${RB}|${WEBSITE}|g" - -e "s|${LB}SERVICE_NAME${RB}|${SERVICE_NAME}|g" - -e "s|${LB}PORT${RB}|${PORT}|g" - -e "s|${LB}REGISTRY${RB}|${REGISTRY}|g" - -e "s|${LB}IMAGE${RB}|${REGISTRY}/${SERVICE_NAME}|g" - -e "s|${LB}VERSION${RB}|${VERSION}|g" - -e "s|${LB}EMAIL${RB}|${AUTHOR_EMAIL}|g" - ) - [ -n "$AUTHOR_EMAIL_ALT" ] && SED_ARGS+=(-e "s|${LB}AUTHOR_EMAIL_ALT${RB}|${AUTHOR_EMAIL_ALT}|g") - - # Replace in all text files (skip .git, LICENSE text, and binaries) - find . -type f \ - -not -path './.git/*' \ - -not -name 'MPL-2.0.txt' \ - -not -name '*.png' -not -name '*.jpg' -not -name '*.gif' \ - -not -name '*.woff' -not -name '*.woff2' \ - | while read -r file; do - if file --brief "$file" | grep -qi 'text\|ascii\|utf'; then - sed -i "${SED_ARGS[@]}" "$file" - fi - done - - # Also replace [YOUR-REPO-NAME] and [YOUR-NAME/ORG] in AI manifest - sed -i "s|\[YOUR-REPO-NAME\]|${PROJECT_NAME}|g" 0-AI-MANIFEST.a2ml 2>/dev/null || true - sed -i "s|\[YOUR-NAME/ORG\]|${OWNER}|g" 0-AI-MANIFEST.a2ml 2>/dev/null || true - - echo "" - echo "── Validation ───────────────────────────────────" - - # Check for remaining placeholders - PATTERN="${LB}[A-Z_]*${RB}" - REMAINING=$(grep -rl "$PATTERN" . --include='*.md' --include='*.adoc' --include='*.yml' --include='*.yaml' --include='*.a2ml' --include='*.toml' --include='*.scm' --include='*.ncl' --include='*.nix' --include='*.json' --include='*.sh' 2>/dev/null | grep -v '.git/' | grep -v '.machine_readable/ai/PLACEHOLDERS.adoc' || true) - if [ -n "$REMAINING" ]; then - echo "WARNING: Remaining placeholders in:" - echo "$REMAINING" | sed 's/^/ /' - echo "" - echo "Run: grep -rn '$LB' . --include='*.md' to inspect" - else - echo "All placeholders replaced successfully!" - fi - - # K9-SVC validation (if available) - if command -v k9-svc >/dev/null 2>&1; then - echo "" - echo "Running k9-svc validation..." - k9-svc validate . 2>/dev/null || true - fi - - echo "" - echo "Running OpenSSF compliance verification..." - just verify - - echo "" - echo "Done! Next steps:" - echo " 1. Review changes: git diff" - echo " 2. Remove template cruft: rm .machine_readable/ai/PLACEHOLDERS.adoc" - echo " 3. Customize README.adoc for your project" - echo " 4. Commit: git add -A && git commit -m 'feat: initialize from RSR template'" - echo " 5. Push: git remote add origin git@${FORGE}:${OWNER}/${REPO}.git && git push -u origin main" diff --git a/build/just/proofs.just b/build/just/proofs.just deleted file mode 100644 index b124d7a..0000000 --- a/build/just/proofs.just +++ /dev/null @@ -1,154 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# FORMAL VERIFICATION (PROOFS) -# -# Imported by ../../Justfile via `import? "build/just/proofs.just"`. -# Recipes here check formal proofs across Idris2, Lean4, Agda, and Coq, plus -# scan for dangerous/unsafe constructs and report status. Run via -# `just proof-check-all` for the full sweep. - -# Check all formal proofs (Idris2 + Lean4 + Agda + Coq) -proof-check-all: proof-check-idris2 proof-check-lean4 proof-check-agda proof-check-coq proof-scan-dangerous - @echo "=== All proof checks complete ===" - -# Check Idris2 proofs (ABI, types, dependent type proofs) -proof-check-idris2: - #!/usr/bin/env bash - set -euo pipefail - echo "=== Checking Idris2 proofs ===" - if ! command -v idris2 &>/dev/null; then - echo "SKIP: idris2 not installed" - exit 0 - fi - ERRORS=0 - for f in $(find verification/proofs/idris2 -name '*.idr' 2>/dev/null); do - echo -n " Checking $f ... " - if idris2 --check "$f" 2>/dev/null; then - echo "OK" - else - echo "FAIL" - ERRORS=$((ERRORS + 1)) - fi - done - if [ "$ERRORS" -gt 0 ]; then - echo "FAIL: $ERRORS Idris2 proof(s) failed" - exit 1 - fi - echo "PASS: All Idris2 proofs verified" - -# Check Lean4 proofs -proof-check-lean4: - #!/usr/bin/env bash - set -euo pipefail - echo "=== Checking Lean4 proofs ===" - if ! command -v lean &>/dev/null; then - echo "SKIP: lean not installed" - exit 0 - fi - ERRORS=0 - for f in $(find verification/proofs/lean4 -name '*.lean' 2>/dev/null); do - echo -n " Checking $f ... " - if lean "$f" 2>/dev/null; then - echo "OK" - else - echo "FAIL" - ERRORS=$((ERRORS + 1)) - fi - done - if [ "$ERRORS" -gt 0 ]; then - echo "FAIL: $ERRORS Lean4 proof(s) failed" - exit 1 - fi - echo "PASS: All Lean4 proofs verified" - -# Check Agda proofs -proof-check-agda: - #!/usr/bin/env bash - set -euo pipefail - echo "=== Checking Agda proofs ===" - if ! command -v agda &>/dev/null; then - echo "SKIP: agda not installed" - exit 0 - fi - ERRORS=0 - for f in $(find verification/proofs/agda -name '*.agda' 2>/dev/null); do - echo -n " Checking $f ... " - if agda --safe "$f" 2>/dev/null; then - echo "OK" - else - echo "FAIL" - ERRORS=$((ERRORS + 1)) - fi - done - if [ "$ERRORS" -gt 0 ]; then - echo "FAIL: $ERRORS Agda proof(s) failed" - exit 1 - fi - echo "PASS: All Agda proofs verified" - -# Check Coq proofs -proof-check-coq: - #!/usr/bin/env bash - set -euo pipefail - echo "=== Checking Coq proofs ===" - if ! command -v coqc &>/dev/null; then - echo "SKIP: coqc not installed" - exit 0 - fi - ERRORS=0 - for f in $(find verification/proofs/coq -name '*.v' 2>/dev/null); do - echo -n " Checking $f ... " - if coqc "$f" 2>/dev/null; then - echo "OK" - else - echo "FAIL" - ERRORS=$((ERRORS + 1)) - fi - done - if [ "$ERRORS" -gt 0 ]; then - echo "FAIL: $ERRORS Coq proof(s) failed" - exit 1 - fi - echo "PASS: All Coq proofs verified" - -# Scan for dangerous patterns in proof files (believe_me, sorry, Admitted, etc.) -proof-scan-dangerous: - #!/usr/bin/env bash - set -euo pipefail - echo "=== Scanning for dangerous patterns in proofs ===" - DANGEROUS=0 - PATTERNS="believe_me|assert_total|postulate|sorry|Admitted|unsafeCoerce|Obj\.magic" - for f in $(find verification/proofs -name '*.idr' -o -name '*.lean' -o -name '*.agda' -o -name '*.v' 2>/dev/null); do - MATCHES=$(grep -nE "$PATTERNS" "$f" 2>/dev/null || true) - if [ -n "$MATCHES" ]; then - echo " DANGEROUS: $f" - echo "$MATCHES" | sed 's/^/ /' - DANGEROUS=$((DANGEROUS + 1)) - fi - done - if [ "$DANGEROUS" -gt 0 ]; then - echo "FAIL: $DANGEROUS file(s) contain dangerous patterns" - exit 1 - fi - echo "PASS: No dangerous patterns found in proofs" - -# Show proof status summary -proof-status: - #!/usr/bin/env bash - echo "=== Proof Status ===" - echo "" - echo "Idris2: $(find verification/proofs/idris2 -name '*.idr' 2>/dev/null | wc -l) files" - echo "Lean4: $(find verification/proofs/lean4 -name '*.lean' 2>/dev/null | wc -l) files" - echo "Agda: $(find verification/proofs/agda -name '*.agda' 2>/dev/null | wc -l) files" - echo "Coq: $(find verification/proofs/coq -name '*.v' 2>/dev/null | wc -l) files" - echo "TLA+: $(find verification/proofs/tlaplus -name '*.tla' 2>/dev/null | wc -l) files" - echo "" - # PROOF-STATUS may live at root, docs/status/ (post-#20), .md or .adoc (post-#23) - for candidate in docs/status/PROOF-STATUS.adoc docs/status/PROOF-STATUS.md PROOF-STATUS.adoc PROOF-STATUS.md; do - if [ -f "$candidate" ]; then - grep -E "^\| \*\*Total\*\*|^\| \*Total\*" "$candidate" 2>/dev/null || echo "(No summary row in $candidate)" - exit 0 - fi - done - echo "(No PROOF-STATUS file found at root or docs/status/)" diff --git a/build/just/validate.just b/build/just/validate.just deleted file mode 100644 index 5ef9208..0000000 --- a/build/just/validate.just +++ /dev/null @@ -1,130 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# VALIDATION & COMPLIANCE -# -# Imported by ../../Justfile via `import? "build/just/validate.just"`. -# Recipes here check that this repo conforms to the RSR (Rhodium Standard -# Repository) skeleton: required files, METAdata, AI install guide -# completeness, etc. Run via `just validate`. - -# Validate RSR compliance -validate-rsr: - #!/usr/bin/env bash - echo "=== RSR Compliance Check ===" - MISSING="" - for f in .editorconfig .gitignore Justfile README.adoc LICENSE 0-AI-MANIFEST.a2ml; do - [ -f "$f" ] || MISSING="$MISSING $f" - done - for f in .machine_readable/6a2/STATE.a2ml .machine_readable/6a2/META.a2ml .machine_readable/6a2/ECOSYSTEM.a2ml .machine_readable/6a2/anchors/ANCHOR.a2ml .machine_readable/policies/MAINTENANCE-AXES.a2ml .machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml .machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml; do - [ -f "$f" ] || MISSING="$MISSING $f" - done - for f in licensing/exhibits/EXHIBIT-A-ETHICAL-USE.txt licensing/exhibits/EXHIBIT-B-QUANTUM-SAFE.txt licensing/texts/MPL-2.0.txt; do - [ -f "$f" ] || MISSING="$MISSING $f" - done - if [ ! -d "src/interface/abi" ] && [ ! -d "src/interface/Abi" ]; then - MISSING="$MISSING src/interface/abi" - fi - for f in src/interface/ffi src/interface/generated; do - [ -d "$f" ] || MISSING="$MISSING $f" - done - for f in docs/governance/MAINTENANCE-CHECKLIST.adoc docs/governance/SOFTWARE-DEVELOPMENT-APPROACH.adoc; do - [ -f "$f" ] || MISSING="$MISSING $f" - done - if [ -f ".machine_readable/6a2/META.a2ml" ]; then - grep -q 'axis-1 = "must > intend > like"' .machine_readable/6a2/META.a2ml || MISSING="$MISSING META.a2ml:axis-1" - grep -q 'axis-2 = "corrective > adaptive > perfective"' .machine_readable/6a2/META.a2ml || MISSING="$MISSING META.a2ml:axis-2" - grep -q 'axis-3 = "systems > compliance > effects"' .machine_readable/6a2/META.a2ml || MISSING="$MISSING META.a2ml:axis-3" - grep -q 'scoping-first = true' .machine_readable/6a2/META.a2ml || MISSING="$MISSING META.a2ml:scoping-first" - grep -q 'idris-unsound-scan = "believe_me/assert_total"' .machine_readable/6a2/META.a2ml || MISSING="$MISSING META.a2ml:idris-unsound-scan" - grep -q 'audit-focus = "systems in place, documentation explains actual state, safety/security accounted for, observed effects reviewed"' .machine_readable/6a2/META.a2ml || MISSING="$MISSING META.a2ml:audit-focus" - grep -q 'compliance-focus = "seams/compromises/exception register, bounded exceptions, anti-drift checks"' .machine_readable/6a2/META.a2ml || MISSING="$MISSING META.a2ml:compliance-focus" - grep -q 'effects-evidence = "benchmark execution/results and maintainer status dialogue/review"' .machine_readable/6a2/META.a2ml || MISSING="$MISSING META.a2ml:effects-evidence" - grep -q 'compliance-tooling = "panic-attack"' .machine_readable/policies/MAINTENANCE-AXES.a2ml || MISSING="$MISSING MAINTENANCE-AXES.a2ml:compliance-tooling" - grep -q 'effects-tooling = "ecological checking with sustainabot guidance"' .machine_readable/policies/MAINTENANCE-AXES.a2ml || MISSING="$MISSING MAINTENANCE-AXES.a2ml:effects-tooling" - grep -q 'source-human = "docs/governance/MAINTENANCE-CHECKLIST.adoc"' .machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml || MISSING="$MISSING MAINTENANCE-CHECKLIST.a2ml:source-human" - grep -q 'source-human = "docs/governance/SOFTWARE-DEVELOPMENT-APPROACH.adoc"' .machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml || MISSING="$MISSING SOFTWARE-DEVELOPMENT-APPROACH.a2ml:source-human" - fi - if [ -n "$MISSING" ]; then - echo "MISSING:$MISSING" - exit 1 - fi - echo "RSR compliance: PASS" - -# Validate STATE.a2ml syntax -validate-state: - @if [ -f ".machine_readable/6a2/STATE.a2ml" ]; then \ - grep -q '^\[metadata\]' .machine_readable/6a2/STATE.a2ml && \ - grep -q 'project\s*=' .machine_readable/6a2/STATE.a2ml && \ - echo "STATE.a2ml: valid" || echo "STATE.a2ml: INVALID (missing required sections)"; \ - else \ - echo "No .machine_readable/6a2/STATE.a2ml found"; \ - fi - -# Validate AI installation guide completeness (finishbot pre-release check) -validate-ai-install: - #!/usr/bin/env bash - echo "=== AI Installation Guide Check ===" - GUIDE="docs/AI_INSTALLATION_GUIDE.adoc" - README="README.adoc" - ERRORS=0 - - # Check guide exists - if [ ! -f "$GUIDE" ]; then - echo "MISSING: $GUIDE (create from template: docs/AI_INSTALLATION_GUIDE.adoc)" - ERRORS=$((ERRORS + 1)) - else - # Check for unfilled TODO markers - TODOS=$(grep -c '\[TODO-AI-INSTALL' "$GUIDE" 2>/dev/null || true) - if [ "$TODOS" -gt 0 ]; then - echo "INCOMPLETE: $GUIDE has $TODOS unfilled [TODO-AI-INSTALL] markers:" - grep -n '\[TODO-AI-INSTALL' "$GUIDE" | head -10 - ERRORS=$((ERRORS + 1)) - else - echo "$GUIDE: complete (no TODO markers)" - fi - - # Check AI implementation section exists - if ! grep -q 'ai-implementation' "$GUIDE" 2>/dev/null; then - echo "MISSING: [[ai-implementation]] anchor in $GUIDE" - ERRORS=$((ERRORS + 1)) - fi - - # Check privacy notice exists - if ! grep -qi 'privacy' "$GUIDE" 2>/dev/null; then - echo "MISSING: Privacy notice in $GUIDE" - ERRORS=$((ERRORS + 1)) - fi - - # Check install commands exist (not just placeholders) - if ! grep -q 'git clone' "$GUIDE" 2>/dev/null; then - echo "WARNING: No git clone command found in $GUIDE -- install commands may be incomplete" - fi - fi - - # Check README has AI install section - if [ -f "$README" ]; then - if ! grep -qi 'AI-Assisted Installation' "$README" 2>/dev/null; then - echo "MISSING: AI-Assisted Installation section in $README" - echo " Copy from docs/AI-INSTALL-README-SECTION.adoc" - ERRORS=$((ERRORS + 1)) - fi - - # Check README for unfilled TODO markers - README_TODOS=$(grep -c '\[TODO-AI-INSTALL' "$README" 2>/dev/null || true) - if [ "$README_TODOS" -gt 0 ]; then - echo "INCOMPLETE: $README has $README_TODOS unfilled [TODO-AI-INSTALL] markers" - ERRORS=$((ERRORS + 1)) - fi - fi - - if [ "$ERRORS" -gt 0 ]; then - echo "" - echo "AI install guide: FAIL ($ERRORS issues)" - exit 1 - fi - echo "AI install guide: PASS" - -# Full validation suite -validate: validate-rsr validate-state validate-ai-install - @echo "All validations passed!" diff --git a/build/setup.sh b/build/setup.sh deleted file mode 100755 index 24c7e5e..0000000 --- a/build/setup.sh +++ /dev/null @@ -1,278 +0,0 @@ -#!/bin/sh -# SPDX-License-Identifier: MPL-2.0 -# setup.sh — Universal setup script for rsr-template-repo -# -# Detects your shell, platform, and installs prerequisites. -# Then hands off to `just setup` for project-specific configuration. -# -# Usage: -# curl -fsSL https://raw.githubusercontent.com/hyperpolymath/rsr-template-repo/main/setup.sh | sh -# # or after cloning: -# ./setup.sh -# -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) - -set -eu - -# ── Colours (safe — uses symbols too per ADJUST contractile) ── -if [ -t 1 ] && command -v tput >/dev/null 2>&1; then - RED=$(tput setaf 1 2>/dev/null || true) - GREEN=$(tput setaf 2 2>/dev/null || true) - YELLOW=$(tput setaf 3 2>/dev/null || true) - CYAN=$(tput setaf 6 2>/dev/null || true) - BOLD=$(tput bold 2>/dev/null || true) - RESET=$(tput sgr0 2>/dev/null || true) -else - RED="" GREEN="" YELLOW="" CYAN="" BOLD="" RESET="" -fi - -ok() { printf " %s[OK]%s %s\n" "$GREEN" "$RESET" "$1"; } -fail() { printf " %s[FAIL]%s %s\n" "$RED" "$RESET" "$1"; } -warn() { printf " %s[WARN]%s %s\n" "$YELLOW" "$RESET" "$1"; } -info() { printf " %s[INFO]%s %s\n" "$CYAN" "$RESET" "$1"; } - -# ── Shell Detection ── -detect_shell() { - # Check the actual running shell, not just $SHELL - CURRENT_SHELL="unknown" - - if [ -n "${BASH_VERSION:-}" ]; then CURRENT_SHELL="bash" - elif [ -n "${ZSH_VERSION:-}" ]; then CURRENT_SHELL="zsh" - elif [ -n "${FISH_VERSION:-}" ]; then CURRENT_SHELL="fish" - elif [ -n "${KSH_VERSION:-}" ]; then CURRENT_SHELL="ksh" - # Check by process name for shells that don't set version vars - elif command -v ps >/dev/null 2>&1; then - SHELL_PROC=$(ps -p $$ -o comm= 2>/dev/null || echo "unknown") - case "$SHELL_PROC" in - *dash*) CURRENT_SHELL="dash" ;; - *tcsh*) CURRENT_SHELL="tcsh" ;; - *csh*) CURRENT_SHELL="csh" ;; - *elvish*) CURRENT_SHELL="elvish" ;; - *nu*) CURRENT_SHELL="nushell" ;; - *oil*|*osh*) CURRENT_SHELL="oil" ;; - *xonsh*) CURRENT_SHELL="xonsh" ;; - *murex*) CURRENT_SHELL="murex" ;; - *ion*) CURRENT_SHELL="ion" ;; - *hilbish*) CURRENT_SHELL="hilbish" ;; - *oh*) CURRENT_SHELL="oh" ;; - *vsh*) CURRENT_SHELL="vsh" ;; - *pwsh*|*powershell*) CURRENT_SHELL="powershell" ;; - esac - fi - - # Fallback: check $SHELL env var - if [ "$CURRENT_SHELL" = "unknown" ] && [ -n "${SHELL:-}" ]; then - case "$SHELL" in - */bash) CURRENT_SHELL="bash" ;; - */zsh) CURRENT_SHELL="zsh" ;; - */fish) CURRENT_SHELL="fish" ;; - */dash) CURRENT_SHELL="dash" ;; - */ksh*) CURRENT_SHELL="ksh" ;; - */tcsh) CURRENT_SHELL="tcsh" ;; - */csh) CURRENT_SHELL="csh" ;; - */vsh) CURRENT_SHELL="vsh" ;; - esac - fi - - printf "%s" "$CURRENT_SHELL" -} - -# ── Platform Detection ── -detect_platform() { - OS="unknown" - DISTRO="unknown" - PKG_MGR="unknown" - ARCH=$(uname -m 2>/dev/null || echo "unknown") - - case "$(uname -s 2>/dev/null)" in - Linux*) - OS="linux" - if [ -f /etc/os-release ]; then - DISTRO=$(. /etc/os-release && echo "$ID") - elif [ -f /etc/redhat-release ]; then - DISTRO="rhel" - elif [ -f /etc/debian_version ]; then - DISTRO="debian" - fi - # Detect package manager - if command -v dnf >/dev/null 2>&1; then PKG_MGR="dnf" - elif command -v apt-get >/dev/null 2>&1; then PKG_MGR="apt" - elif command -v pacman >/dev/null 2>&1; then PKG_MGR="pacman" - elif command -v apk >/dev/null 2>&1; then PKG_MGR="apk" - elif command -v zypper >/dev/null 2>&1; then PKG_MGR="zypper" - elif command -v rpm-ostree >/dev/null 2>&1; then PKG_MGR="rpm-ostree" - elif command -v guix >/dev/null 2>&1; then PKG_MGR="guix" - elif command -v nix >/dev/null 2>&1; then PKG_MGR="nix" - fi - ;; - Darwin*) - OS="macos" - DISTRO="macos" - if command -v brew >/dev/null 2>&1; then PKG_MGR="brew" - elif command -v port >/dev/null 2>&1; then PKG_MGR="macports" - fi - ;; - CYGWIN*|MINGW*|MSYS*) - OS="windows" - DISTRO="msys" - if command -v winget >/dev/null 2>&1; then PKG_MGR="winget" - elif command -v scoop >/dev/null 2>&1; then PKG_MGR="scoop" - elif command -v choco >/dev/null 2>&1; then PKG_MGR="choco" - fi - ;; - FreeBSD*) - OS="freebsd" - DISTRO="freebsd" - PKG_MGR="pkg" - ;; - esac -} - -# ── Install just ── -install_just() { - if command -v just >/dev/null 2>&1; then - ok "just already installed: $(just --version 2>/dev/null | head -1)" - return 0 - fi - - info "Installing just (task runner)..." - - case "$PKG_MGR" in - dnf) sudo dnf install -y just ;; - apt) sudo apt-get install -y just 2>/dev/null || { - # just not in older apt repos — use installer - curl -fsSL https://just.systems/install.sh | bash -s -- --to /usr/local/bin - } ;; - pacman) sudo pacman -S --noconfirm just ;; - apk) sudo apk add just ;; - brew) brew install just ;; - scoop) scoop install just ;; - winget) winget install Casey.Just ;; - rpm-ostree) sudo rpm-ostree install just ;; - guix) guix install just ;; - nix) nix-env -iA nixpkgs.just ;; - *) - info "Using just installer script..." - curl -fsSL https://just.systems/install.sh | bash -s -- --to /usr/local/bin - ;; - esac - - if command -v just >/dev/null 2>&1; then - ok "just installed: $(just --version 2>/dev/null | head -1)" - else - fail "Could not install just. Install manually: https://just.systems/" - return 1 - fi -} - -# ── Main ── -main() { - printf "%s=== rsr-template-repo Setup ===%s\n\n" "$BOLD" "$RESET" - - # Detect environment - SHELL_NAME=$(detect_shell) - detect_platform - - info "Shell: $SHELL_NAME" - info "Platform: $OS ($DISTRO)" - info "Arch: $ARCH" - info "Packages: $PKG_MGR" - printf "\n" - - # Warn about exotic shells - case "$SHELL_NAME" in - vsh) - info "Valence Shell detected — experimental support" - info "Falling back to POSIX sh for setup, vsh for post-setup" - ;; - nushell|elvish|murex|ion|hilbish|oil|xonsh|oh) - info "$SHELL_NAME detected — using POSIX sh for setup" - ;; - esac - - # Step 1: Install just - printf "%sStep 1: Install task runner%s\n" "$BOLD" "$RESET" - install_just || { fail "Cannot proceed without just"; exit 1; } - printf "\n" - - # Step 2: Check if we're in the repo directory - if [ ! -f "Justfile" ] && [ ! -f "justfile" ]; then - warn "Not in a repo directory (no Justfile found)" - info "Clone first: git clone https://github.com/hyperpolymath/rsr-template-repo.git" - info "Then: cd rsr-template-repo && ./setup.sh" - exit 1 - fi - - # Step 3: Run just setup - printf "%sStep 2: Project setup%s\n" "$BOLD" "$RESET" - if just --list 2>/dev/null | grep -q "^setup "; then - just setup - elif just --list 2>/dev/null | grep -q "^setup-dev "; then - just setup-dev - else - warn "No 'setup' recipe in Justfile — running 'just doctor' instead" - just doctor 2>/dev/null || true - fi - printf "\n" - - # Step 4: Post-install security snapshot - printf "%sStep 3: Security snapshot%s\n" "$BOLD" "$RESET" - if command -v firewall-cmd >/dev/null 2>&1; then - if firewall-cmd --state 2>/dev/null | grep -q running; then - ok "Firewall: firewalld active" - else - warn "Firewall: firewalld installed but not running" - info " Enable: sudo systemctl enable --now firewalld" - fi - elif command -v ufw >/dev/null 2>&1; then - if ufw status 2>/dev/null | grep -q "Status: active"; then - ok "Firewall: ufw active" - else - warn "Firewall: ufw installed but not active" - info " Enable: sudo ufw enable" - fi - else - warn "Firewall: none detected" - case "$PKG_MGR" in - dnf|rpm-ostree) info " Install: sudo dnf install firewalld && sudo systemctl enable --now firewalld" ;; - apt) info " Install: sudo apt install ufw && sudo ufw enable" ;; - *) info " Install a firewall for your platform" ;; - esac - fi - - if command -v getenforce >/dev/null 2>&1; then - SE_STATUS=$(getenforce 2>/dev/null || echo "unknown") - case "$SE_STATUS" in - Enforcing) ok "SELinux: Enforcing" ;; - Permissive) warn "SELinux: Permissive (recommend Enforcing: sudo setenforce 1)" ;; - *) warn "SELinux: $SE_STATUS" ;; - esac - fi - - # Write report - REPORT_FILE="INSTALL-SECURITY-REPORT.adoc" - { - printf "// SPDX-License-Identifier: MPL-2.0\n" - printf "= Install Security Report\n" - printf ":date: %s\n\n" "$(date -Iseconds 2>/dev/null || date)" - printf "== Platform\n" - printf "* OS: %s (%s)\n" "$OS" "$DISTRO" - printf "* Arch: %s\n" "$ARCH" - printf "* Package manager: %s\n" "$PKG_MGR" - printf "* Shell: %s\n\n" "$SHELL_NAME" - printf "== Security Status\n" - printf "Run \`just doctor\` for full diagnostic.\n" - } > "$REPORT_FILE" - info "Security report: $REPORT_FILE" - printf "\n" - - # Done - printf "%s=== Setup Complete ===%s\n\n" "${BOLD}${GREEN}" "$RESET" - printf "Next steps:\n" - printf " just doctor — verify everything works\n" - printf " just tour — guided tour of the project\n" - printf " just build — build the project\n" - printf " just help-me — get help if stuck\n" -} - -main "$@" diff --git a/conformance/invalid/empty-attestation.a2ml b/conformance/invalid/empty-attestation.a2ml new file mode 100644 index 0000000..423559f --- /dev/null +++ b/conformance/invalid/empty-attestation.a2ml @@ -0,0 +1,9 @@ +# SPDX-License-Identifier: MPL-2.0 +name = "empty-attestation" +version = "1.0.0" + +[attestation] +note = "No proof, signature, or hash key is present." + +[section] +purpose = "Attestation block should warn, and strict mode should fail." diff --git a/conformance/invalid/malformed-heading.a2ml b/conformance/invalid/malformed-heading.a2ml new file mode 100644 index 0000000..71ab122 --- /dev/null +++ b/conformance/invalid/malformed-heading.a2ml @@ -0,0 +1,6 @@ +# SPDX-License-Identifier: MPL-2.0 +name = "malformed-heading" +version = "1.0.0" + +[broken +purpose = "The heading starts with an opening bracket but never closes it." diff --git a/conformance/invalid/missing-identity.a2ml b/conformance/invalid/missing-identity.a2ml new file mode 100644 index 0000000..0b1a4ad --- /dev/null +++ b/conformance/invalid/missing-identity.a2ml @@ -0,0 +1,5 @@ +# SPDX-License-Identifier: MPL-2.0 +version = "1.0.0" + +[section] +purpose = "No identity field is present." diff --git a/conformance/invalid/missing-spdx.a2ml b/conformance/invalid/missing-spdx.a2ml new file mode 100644 index 0000000..3c5f9a0 --- /dev/null +++ b/conformance/invalid/missing-spdx.a2ml @@ -0,0 +1,5 @@ +name = "missing-license-header" +version = "1.0.0" + +[section] +purpose = "The required license marker is absent from the first ten lines." diff --git a/conformance/invalid/missing-version.a2ml b/conformance/invalid/missing-version.a2ml new file mode 100644 index 0000000..54c15e3 --- /dev/null +++ b/conformance/invalid/missing-version.a2ml @@ -0,0 +1,5 @@ +# SPDX-License-Identifier: MPL-2.0 +name = "missing-version" + +[section] +purpose = "Identity exists but no version field is present." diff --git a/conformance/manifest.a2ml b/conformance/manifest.a2ml new file mode 100644 index 0000000..5adff26 --- /dev/null +++ b/conformance/manifest.a2ml @@ -0,0 +1,19 @@ +; SPDX-License-Identifier: MPL-2.0 +(conformance-manifest + (metadata + (name "a2ml-conformance-corpus") + (version "0.1.0") + (updated "2026-06-21")) + + (positive-fixtures + (fixture "valid/basic-project.a2ml" (expect "pass")) + (fixture "valid/attested-agent.a2ml" (expect "pass")) + (fixture "valid/s-expression-state.a2ml" (expect "pass")) + (fixture "valid/sectioned-manifest.a2ml" (expect "pass"))) + + (negative-fixtures + (fixture "invalid/missing-identity.a2ml" (expect "error") (reason "missing identity")) + (fixture "invalid/missing-version.a2ml" (expect "strict-error") (reason "missing version warning")) + (fixture "invalid/missing-spdx.a2ml" (expect "strict-error") (reason "missing license header warning")) + (fixture "invalid/empty-attestation.a2ml" (expect "strict-error") (reason "empty attestation warning")) + (fixture "invalid/malformed-heading.a2ml" (expect "strict-error") (reason "malformed heading warning")))) diff --git a/conformance/valid/attested-agent.a2ml b/conformance/valid/attested-agent.a2ml new file mode 100644 index 0000000..763baff --- /dev/null +++ b/conformance/valid/attested-agent.a2ml @@ -0,0 +1,9 @@ +# SPDX-License-Identifier: MPL-2.0 +agent-id = "fixture-agent" +version = "1.0.0" + +[attestation] +signature = "fixture-signature" + +[section] +purpose = "Valid attestation block with a signature field." diff --git a/conformance/valid/basic-project.a2ml b/conformance/valid/basic-project.a2ml new file mode 100644 index 0000000..d214a58 --- /dev/null +++ b/conformance/valid/basic-project.a2ml @@ -0,0 +1,6 @@ +# SPDX-License-Identifier: MPL-2.0 +name = "basic-project" +version = "1.0.0" + +[section] +purpose = "Minimal valid A2ML fixture with identity, version, and license header." diff --git a/conformance/valid/s-expression-state.a2ml b/conformance/valid/s-expression-state.a2ml new file mode 100644 index 0000000..b28540e --- /dev/null +++ b/conformance/valid/s-expression-state.a2ml @@ -0,0 +1,7 @@ +; SPDX-License-Identifier: MPL-2.0 +(state + (metadata + (name "s-expression-state") + (version "1.0.0")) + (current-position + (status "valid fixture"))) diff --git a/conformance/valid/sectioned-manifest.a2ml b/conformance/valid/sectioned-manifest.a2ml new file mode 100644 index 0000000..e2f47aa --- /dev/null +++ b/conformance/valid/sectioned-manifest.a2ml @@ -0,0 +1,12 @@ +# SPDX-License-Identifier: MPL-2.0 +project = "sectioned-manifest" +schema_version = "1.0.0" + +[metadata] +role = "valid conformance fixture" + +[attestation] +proof = "fixture-proof" + +[section] +heading = "well formed" diff --git a/container/.gatekeeper.yaml b/container/.gatekeeper.yaml deleted file mode 100644 index 4aac671..0000000 --- a/container/.gatekeeper.yaml +++ /dev/null @@ -1,122 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# -# Svalinn gatekeeper policy for {{PROJECT_NAME}} -# -# Controls which operations are permitted through the edge gateway. -# This template provides moderate security defaults — not wide-open test -# mode, but not production-hardened either. Tighten the values below -# before deploying to production. -# -# See: stapeln/container-stack/svalinn/ - -version: "1.0" - -# ============================================================================ -# Authentication -# ============================================================================ -# -# Define which endpoints require authentication and at what level. - -auth: - # Public endpoints — no authentication required. - # Health and readiness probes must always be public so that - # orchestrators (selur, Podman, k8s) can check service status. - public: - - path: "/health" - methods: ["GET"] - - path: "/ready" - methods: ["GET"] - - path: "/metrics" - methods: ["GET"] - - # Endpoints requiring JWT or OAuth2 authentication. - # Svalinn validates the token before forwarding the request. - authenticated: - - path: "/api/v1/*" - methods: ["GET", "POST", "PUT", "DELETE"] - -# ============================================================================ -# Rate Limiting -# ============================================================================ -# -# Protects backend services from overload. Values here are moderate -# defaults — adjust based on your service capacity. - -rate_limits: - # Global limit: applied to all authenticated clients. - global: - requests_per_second: 500 - burst: 1000 - - # Write operations: stricter limit to protect data stores. - writes: - paths: ["/api/v1/*"] - methods: ["POST", "PUT", "DELETE"] - requests_per_second: 100 - burst: 200 - -# ============================================================================ -# Container Trust -# ============================================================================ -# -# Svalinn verifies that all .ctp bundles in the stack are signed by -# trusted keys and carry the required attestations. - -trust: - # Only accept .ctp bundles signed by these keys. - trusted_signers: - - key_id: "{{SERVICE_NAME}}-release" - algorithm: "Ed25519" - public_key_file: "/etc/svalinn/keys/{{SERVICE_NAME}}-release.pub" - - # Require these attestations on all .ctp bundles. - required_attestations: - - "source-signature" - - "sbom-complete" - - # Reject unsigned or untrusted images. - reject_unsigned: true - -# ============================================================================ -# Request Validation -# ============================================================================ -# -# Input validation at the gateway layer — catches malformed requests -# before they reach the application. - -validation: - # Maximum request body size. - max_body_size: "8MB" - - # Reject requests with NaN or Infinity in numeric fields. - reject_nan_inf: true - - # Maximum result limit per list/search query. - max_result_limit: 500 - -# ============================================================================ -# CORS -# ============================================================================ -# -# Cross-Origin Resource Sharing policy. The defaults below allow all -# origins — restrict to your frontend domain(s) in production. - -cors: - allow_origins: ["*"] - allow_methods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"] - allow_headers: ["Content-Type", "Authorization"] - max_age: 3600 - -# ============================================================================ -# Logging -# ============================================================================ -# -# Structured logging for svalinn itself. Audit paths log all requests -# (including body hashes) for post-incident investigation. - -logging: - format: "json" - level: "info" - # Log all write operations for audit trail. - audit_paths: - - "/api/v1/*" diff --git a/container/0.1-AI-MANIFEST.a2ml b/container/0.1-AI-MANIFEST.a2ml deleted file mode 100644 index ccb5bc5..0000000 --- a/container/0.1-AI-MANIFEST.a2ml +++ /dev/null @@ -1,143 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "container-templates" -version: "1.0.0" -context: - - "https://a2ml.org/ns/v2" - - "https://stapeln.dev/ns/v1" - ---- -### [AI_MANIFEST] -description: | - Container templates for the stapeln container ecosystem. This directory - provides Podman-Chainguard-stapeln templates that are customised via - `just container-init` or `just init` during project bootstrap. - - All files use {{PLACEHOLDER}} tokens that are substituted with project- - specific values during initialisation. - -purpose: | - Provide a complete, security-first container deployment story for any - RSR-compliant repository. The templates cover the full lifecycle: - build, sign, verify, deploy, monitor, and govern. - -canonical_locations: - compose: "container/compose.toml" - containerfile: "container/Containerfile" - manifest: "container/manifest.toml" - gatekeeper: "container/.gatekeeper.yaml" - build_pipeline: "container/ct-build.sh" - entrypoint: "container/entrypoint.sh" - monitoring: "container/vordr.toml" - deployment: "container/deploy.k9.ncl" - example: "container/compose.example.toml" - ---- -### [FILE_RELATIONSHIPS] -files: - - name: "compose.toml" - role: "Orchestration" - description: | - selur-compose stack definition. Declares services, volumes, networks, - and health checks. References the Containerfile for image builds and - .gatekeeper.yaml for svalinn policy. - depends_on: ["Containerfile", ".gatekeeper.yaml"] - - - name: "Containerfile" - role: "Image Build" - description: | - Multi-stage OCI container build. Stage 1 compiles the application on - wolfi-base; Stage 2 copies the binary into a minimal runtime image. - Copies entrypoint.sh, .gatekeeper.yaml, and manifest.toml into the - final image. - depends_on: ["entrypoint.sh", ".gatekeeper.yaml", "manifest.toml"] - - - name: "manifest.toml" - role: "Bundle Metadata" - description: | - Cerro-torre .ctp bundle manifest. Describes provenance, dependencies, - attestations, and runtime security profile. Used by `ct pack` and - `ct verify`. - depends_on: [] - - - name: ".gatekeeper.yaml" - role: "Gateway Policy" - description: | - Svalinn edge gateway policy. Controls authentication, rate limiting, - container trust, request validation, CORS, and audit logging. - depends_on: [] - - - name: "ct-build.sh" - role: "Build Pipeline" - description: | - Shell script implementing the 5-stage pipeline: build (Podman), - pack (cerro-torre .ctp), sign (Ed25519), verify, push (optional). - Degrades gracefully when cerro-torre tools are not installed. - depends_on: ["Containerfile", "manifest.toml"] - - - name: "entrypoint.sh" - role: "Container Entrypoint" - description: | - Startup script with signal handling (SIGTERM, SIGINT), logging, and - exec into the main application process. - depends_on: [] - - - name: "vordr.toml" - role: "Runtime Monitoring" - description: | - Vordr monitoring configuration. Health endpoint probing, crash - detection, resource thresholds, and structured log output. - depends_on: [] - - - name: "deploy.k9.ncl" - role: "Deployment Component" - description: | - k9-svc deployment specification at Hunt trust level. Full pedigree - (L1-L5), environment configs, container config, and rolling - deployment strategy. - depends_on: ["compose.toml", "ct-build.sh"] - - - name: "compose.example.toml" - role: "Example" - description: | - Fully-commented multi-service example (Rust API + Elixir worker + - svalinn gateway). Copy to compose.toml and customise. - depends_on: [] - ---- -### [STAPELN_ECOSYSTEM] -overview: | - The stapeln container ecosystem comprises six tools: - - selur — Container orchestration with zero-copy IPC. Reads compose.toml. - cerro-torre — Verified container packaging (.ctp bundles), Ed25519 signing. - svalinn — Policy-driven edge gateway (auth, rate limits, CORS, trust). - vordr — Runtime monitoring (health, crashes, resources, logs). - rokur — Secrets management (runtime injection, no baked secrets). - k9-svc — Nickel deployment components (Kennel/Yard/Hunt trust levels). - -invariants: - - "Base images MUST be cgr.dev/chainguard/wolfi-base or cgr.dev/chainguard/static" - - "Container runtime is Podman — never Docker" - - "Containerfile — never Dockerfile" - - "All images run as non-root (appuser or project-specific user)" - - ".ctp bundles are signed with Ed25519 via cerro-torre" - - "Health endpoints (/health, /ready) must always be public (no auth)" - ---- -### [USAGE] -initialisation: | - Run `just container-init` to substitute all {{PLACEHOLDER}} tokens with - project-specific values. This is also run as part of `just init`. - -development: | - 1. `just container-build` — Build the container image - 2. `just container-verify` — Verify compose configuration - 3. `just container-up` — Start the stack locally - 4. `just container-down` — Stop the stack - -production: | - 1. `just container-sign` — Build, sign, verify .ctp bundle - 2. `just container-push` — Push signed bundle to registry - 3. `selur-compose up` — Deploy on target host diff --git a/container/Containerfile b/container/Containerfile deleted file mode 100644 index ba85260..0000000 --- a/container/Containerfile +++ /dev/null @@ -1,136 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# {{PROJECT_NAME}} Container Image -# -# Multi-stage build template for Chainguard Wolfi base images. -# Customise the builder stage for your language and copy the -# resulting binary/release into the minimal runtime stage. -# -# Build with Podman: -# podman build -t {{SERVICE_NAME}}:latest -f container/Containerfile . -# -# Run: -# podman run -p {{PORT}}:{{PORT}} {{SERVICE_NAME}}:latest -# -# Run with persistent volume: -# podman run -p {{PORT}}:{{PORT}} -v {{SERVICE_NAME}}-data:/data {{SERVICE_NAME}}:latest - -# ============================================================================ -# Stage 1: Builder -# ============================================================================ -# -# Install build tools and compile the application. -# This stage is discarded after the build — only the compiled output -# is copied into the runtime stage. -# -# Language-specific examples (uncomment the one you need): -# -# --- Rust --- -# RUN apk add --no-cache rust pkgconf build-base -# COPY Cargo.toml Cargo.lock ./ -# COPY src/ ./src/ -# RUN cargo build --release -# # Output: /build/target/release/{{SERVICE_NAME}} -# -# --- Elixir --- -# RUN apk add --no-cache erl27-elixir-1.18 erlang-27 erlang-27-dev git build-base -# COPY mix.exs mix.lock ./ -# COPY lib/ ./lib/ -# COPY config/ ./config/ -# ENV MIX_ENV=prod -# RUN mix local.hex --force && mix local.rebar --force && \ -# mix deps.get --only prod && mix compile && mix release -# # Output: /build/_build/prod/rel/{{SERVICE_NAME}}/ -# -# --- Zig --- -# RUN apk add --no-cache zig build-base -# COPY build.zig build.zig.zon ./ -# COPY src/ ./src/ -# RUN zig build -Doptimize=ReleaseFast -# # Output: /build/zig-out/bin/{{SERVICE_NAME}} -# -FROM cgr.dev/chainguard/wolfi-base:latest AS builder - -# TODO: Install your language toolchain -RUN apk add --no-cache build-base - -WORKDIR /build - -# TODO: Copy source files and build -COPY . . -# RUN - -# ============================================================================ -# Stage 2: Runtime -# ============================================================================ -# -# Minimal production image. Only the compiled binary/release and runtime -# dependencies are included. No compilers, no source code, no build tools. -# -FROM cgr.dev/chainguard/wolfi-base:latest - -# OCI image labels (compatible with cerro-torre .ctp bundle metadata) -LABEL org.opencontainers.image.title="{{PROJECT_NAME}}" \ - org.opencontainers.image.description="{{PROJECT_DESCRIPTION}}" \ - org.opencontainers.image.url="https://{{FORGE}}/{{OWNER}}/{{REPO}}" \ - org.opencontainers.image.source="https://{{FORGE}}/{{OWNER}}/{{REPO}}" \ - org.opencontainers.image.vendor="{{OWNER}}" \ - org.opencontainers.image.licenses="{{LICENSE}}" \ - org.opencontainers.image.authors="{{AUTHOR}} <{{AUTHOR_EMAIL}}>" \ - dev.cerrotorre.manifest="container/manifest.toml" \ - dev.cerrotorre.gatekeeper="container/.gatekeeper.yaml" \ - dev.stapeln.compose="container/compose.toml" - -# Install minimal runtime dependencies. -# Adjust this list for your application: -# - ca-certificates: TLS root certificates -# - curl: health check probe -# - libstdc++: C++ standard library (if needed by native deps) -# - ncurses: terminal UI (if needed, e.g. Elixir IEx) -RUN apk add --no-cache ca-certificates curl - -# Create non-root user for the application. -# Running as root inside containers is a security anti-pattern. -RUN addgroup -S appuser && adduser -S appuser -G appuser - -WORKDIR /app - -# TODO: Copy compiled binary/release from builder stage. -# Examples: -# COPY --from=builder /build/target/release/{{SERVICE_NAME}} /app/{{SERVICE_NAME}} -# COPY --from=builder /build/_build/prod/rel/{{SERVICE_NAME}} /app/release/ -# COPY --from=builder /build/zig-out/bin/{{SERVICE_NAME}} /app/{{SERVICE_NAME}} - -# Copy entrypoint script -COPY container/entrypoint.sh /app/entrypoint.sh -RUN chmod +x /app/entrypoint.sh - -# Copy stapeln integration files (svalinn gatekeeper policy, cerro-torre manifest) -COPY container/.gatekeeper.yaml /etc/svalinn/gatekeeper.yaml -COPY container/manifest.toml /app/manifest.toml - -# Create data directory for persistent storage (mountable volume) -RUN mkdir -p /data && chown appuser:appuser /data - -# Set ownership of the application directory -RUN chown -R appuser:appuser /app - -# Environment variables — customise for your application -ENV APP_HOST=[::] -ENV APP_PORT={{PORT}} -ENV APP_LOG_FORMAT=json -ENV APP_DATA_DIR=/data - -# Declare /data as a volume for persistent storage -VOLUME ["/data"] - -# Run as non-root -USER appuser - -# Expose the application port -EXPOSE {{PORT}} - -# Health check — the application must respond 2xx at /health -HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \ - CMD curl -sf http://localhost:${APP_PORT}/health || exit 1 - -ENTRYPOINT ["/app/entrypoint.sh"] diff --git a/container/README.adoc b/container/README.adoc deleted file mode 100644 index 0db8201..0000000 --- a/container/README.adoc +++ /dev/null @@ -1,179 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= {{PROJECT_NAME}} Container Templates -:toc: left -:toclevels: 3 -:sectnums: - -== Overview - -This directory contains container templates for the -https://github.com/hyperpolymath/stapeln[stapeln] container ecosystem. -The stapeln stack provides verified container packaging, edge gateway -policies, runtime monitoring, and supply-chain signing for Podman-based -deployments using https://www.chainguard.dev/[Chainguard] Wolfi base images. - -All files use `{{PLACEHOLDER}}` tokens that are replaced by `just container-init` -(or by the top-level `just init` during project bootstrap). - -== File Reference - -[cols="1,3"] -|=== -| File | Purpose - -| `compose.toml` -| **selur-compose** stack definition. Declares services, volumes, networks, - and health checks. The primary orchestration file for local and production - deployment. Use `selur-compose up` or fall back to `podman compose`. - -| `compose.example.toml` -| Concrete multi-service example with detailed comments. Copy and customise - for your own stack. Not used directly by any tooling. - -| `Containerfile` -| Multi-stage OCI container build specification. Stage 1 builds the - application; Stage 2 produces a minimal runtime image on - `cgr.dev/chainguard/wolfi-base`. Uses Podman (never Docker). - -| `manifest.toml` -| **cerro-torre** bundle metadata. Describes the `.ctp` verified container - package: provenance, dependencies, attestations, and runtime security - profile. Used by `ct pack` and `ct verify`. - -| `.gatekeeper.yaml` -| **svalinn** edge gateway policy. Controls authentication, rate limiting, - container trust, request validation, CORS, and audit logging at the - network boundary. - -| `ct-build.sh` -| Build, sign, and verify pipeline script. Five stages: build (Podman), - pack (cerro-torre `.ctp`), sign (Ed25519), verify, and push (optional). - Gracefully degrades when cerro-torre tools are not installed. - -| `entrypoint.sh` -| Container entrypoint with signal handling (SIGTERM, SIGINT), startup - logging, and `exec` into the main application process. - -| `vordr.toml` -| **vordr** runtime monitoring configuration. Defines health endpoints, - crash detection, resource thresholds, and log output. - -| `deploy.k9.ncl` -| **k9-svc** deployment component at Hunt trust level. Full pedigree - (L1--L5), environment configs (dev/staging/prod), container - configuration, and rolling deployment strategy. - -| `0-AI-MANIFEST.a2ml` -| AI-readable manifest describing the container directory, file - interconnections, and the stapeln ecosystem. -|=== - -== The stapeln Ecosystem - -The stapeln container ecosystem comprises six interconnected tools: - -**selur** (compose):: - Container orchestration with zero-copy IPC for co-located services. - Reads `compose.toml` files. Falls back to standard Podman Compose - when the selur driver is unavailable. - -**cerro-torre** (bundles and signing):: - Verified container packaging. Produces `.ctp` bundles from OCI images, - signs them with Ed25519, and verifies the full chain. Tools: `ct pack`, - `ct sign`, `ct verify`, `ct push`, `ct explain`. - -**svalinn** (edge gateway):: - Policy-driven reverse proxy. Enforces authentication, rate limiting, - CORS, and container trust policies defined in `.gatekeeper.yaml`. - -**vordr** (monitoring):: - Runtime container monitoring. Watches health endpoints, detects crashes, - tracks resource usage, and emits structured logs. - -**rokur** (secrets):: - Secrets management for container deployments. Injects secrets at runtime - without baking them into images. Currently a stub/placeholder. - -**k9-svc** (deployment components):: - Nickel-based deployment specification. Components declare their pedigree - (identity, target, security, validation, recipes) and execute at one of - three trust levels: Kennel (data only), Yard (evaluation), Hunt (full - execution with cryptographic handshake). - -== How to Initialise - -[source,bash] ----- -# Option 1: During project bootstrap (includes all placeholders) -just init - -# Option 2: Container-specific initialisation -just container-init ----- - -The `container-init` recipe prompts for container-specific values -(service name, port, registry) and substitutes all `{{PLACEHOLDER}}` -tokens in the `container/` directory. - -== Development Workflow - -[source,bash] ----- -# 1. Build the container image -just container-build - -# 2. Verify the compose configuration -just container-verify - -# 3. Start the stack locally -just container-up --detach - -# 4. Check logs -podman compose --file container/compose.toml logs -f - -# 5. Stop the stack -just container-down ----- - -== Production Deployment - -[source,bash] ----- -# 1. Build, sign, and verify the .ctp bundle -just container-sign - -# 2. Push the signed bundle to the registry -just container-push - -# 3. Deploy on the target host -selur-compose up --detach ----- - -For k9-svc managed deployments: - -[source,bash] ----- -# Validate the deployment component -nickel typecheck container/deploy.k9.ncl - -# Deploy (requires Hunt-level authorisation) -k9-svc deploy container/deploy.k9.ncl --env production ----- - -== Base Images - -All Containerfiles use Chainguard Wolfi base images: - -* **Builder stage:** `cgr.dev/chainguard/wolfi-base:latest` -* **Runtime stage:** `cgr.dev/chainguard/wolfi-base:latest` (or - `cgr.dev/chainguard/static:latest` for statically-linked binaries) - -Chainguard images are minimal, CVE-free, and rebuilt daily. They use the -`apk` package manager (Alpine-compatible). - -== Container Runtime - -This project uses **Podman** (never Docker). All scripts, compose files, -and documentation reference Podman commands. The OCI Containerfile format -is compatible with Podman, Docker, and nerdctl. diff --git a/container/compose.example.toml b/container/compose.example.toml deleted file mode 100644 index d8d717c..0000000 --- a/container/compose.example.toml +++ /dev/null @@ -1,135 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# -# Example selur-compose configuration — multi-service stack -# -# This is a concrete, fully-commented example showing a Rust API + Elixir -# worker + svalinn gateway deployment. Copy this file to compose.toml and -# customise for your project. -# -# Usage: -# cp compose.example.toml compose.toml -# # Edit service names, ports, images -# selur-compose up --detach - -version = "1.0" - -# ============================================================================ -# Services -# ============================================================================ - -# Rust API service — the primary HTTP/gRPC backend. -# Handles incoming requests, data storage, and core business logic. -[services.rust-api] -image = "ghcr.io/hyperpolymath/myproject-api:latest.ctp" - -# Map host port 8080 to container port 8080. -# Use ["[::]:8080:8080"] for explicit IPv6 binding. -ports = ["8080:8080"] - -# Environment variables passed into the container at startup. -# These override defaults in the Containerfile ENV directives. -environment = { - RUST_LOG = "info", # Rust log level (trace, debug, info, warn, error) - APP_HOST = "[::]", # Listen on all interfaces (IPv4 + IPv6) - APP_PORT = "8080", # Internal container port - APP_LOG_FORMAT = "json", # Structured logging for selur/vordr - APP_DATA_DIR = "/data", # Persistent data directory (matches VOLUME) -} - -# Bind-mount a named volume for persistent data. -# Format: "volume-name:/container/path" -volumes = ["api-data:/data"] - -# Restart policy: "always" ensures the service comes back after crashes. -# Other options: "no", "on-failure", "unless-stopped" -restart = "always" - -# Health check: selur/Podman uses this to determine if the service is ready. -# The service must respond 2xx to this endpoint within the timeout. -healthcheck = { test = "curl -sf http://localhost:8080/health", interval = "30s", timeout = "5s", retries = 3 } - -# --- - -# Elixir worker service — background processing, event handling, coordination. -# Runs as an OTP release with supervision trees for fault tolerance. -[services.elixir-worker] -image = "ghcr.io/hyperpolymath/myproject-worker:latest.ctp" - -# Separate port for the worker's admin/metrics endpoint. -ports = ["4000:4000"] - -# The worker connects to the Rust API over the internal selur network. -# Service names resolve as hostnames within the compose network. -environment = { - API_URL = "http://rust-api:8080/api/v1", # Internal service discovery - MIX_ENV = "prod", # Elixir release mode - APP_LOG_FORMAT = "json", # Match structured logging format - POOL_SIZE = "10", # DB connection pool size -} - -# depends_on ensures the Rust API starts before the worker. -# Note: This only waits for the container to start, not for the health check. -# Use healthcheck + startup probes for true readiness gating. -depends_on = ["rust-api"] - -restart = "always" -healthcheck = { test = "curl -sf http://localhost:4000/health", interval = "30s", timeout = "5s", retries = 3 } - -# --- - -# Svalinn edge gateway — reverse proxy with policy enforcement. -# All external traffic enters through svalinn, which: -# 1. Terminates TLS (auto-provisioned certificates) -# 2. Validates JWT/OAuth2 authentication -# 3. Enforces rate limits from .gatekeeper.yaml -# 4. Routes requests to the appropriate backend service -# 5. Logs all write operations for audit -[services.svalinn] -image = "ghcr.io/hyperpolymath/svalinn:latest.ctp" - -# External-facing ports: HTTPS (443) and HTTP->HTTPS redirect (80). -ports = ["443:443", "80:80"] - -environment = { - # Backend routing: svalinn proxies to internal services. - SVALINN_BACKEND = "http://rust-api:8080", - SVALINN_WORKER_BACKEND = "http://elixir-worker:4000", - - # Policy file: mounted from the svalinn-config volume. - SVALINN_POLICY_FILE = "/etc/svalinn/gatekeeper.yaml", - - # Auto-provision TLS certificates (Let's Encrypt). - SVALINN_TLS_AUTO = "true", -} - -# Mount .gatekeeper.yaml as read-only policy configuration. -volumes = ["svalinn-config:/etc/svalinn:ro"] - -# Svalinn starts last — it needs both backends to be running. -depends_on = ["rust-api", "elixir-worker"] -restart = "always" -healthcheck = { test = "curl -sf http://localhost:80/health", interval = "30s", timeout = "5s", retries = 3 } - -# ============================================================================ -# Volumes -# ============================================================================ - -# Persistent storage for the Rust API (database files, indexes, WAL). -[volumes.api-data] -driver = "local" - -# Read-only policy configuration for svalinn gateway. -# Populate with: cp .gatekeeper.yaml /path/to/svalinn-config/gatekeeper.yaml -[volumes.svalinn-config] -driver = "local" - -# ============================================================================ -# Networks -# ============================================================================ - -# selur network: zero-copy IPC between services on the same host. -# When the selur driver is not installed, falls back to standard bridge -# networking (TCP over localhost). Performance is slightly lower but -# functionality is identical. -[networks.default] -driver = "selur" diff --git a/container/compose.toml b/container/compose.toml deleted file mode 100644 index a14f8a0..0000000 --- a/container/compose.toml +++ /dev/null @@ -1,70 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# -# {{PROJECT_NAME}} selur-compose configuration -# -# Orchestrates the container stack as verified container bundles (.ctp). -# Uses selur zero-copy IPC between services on the same host. -# -# Usage: -# selur-compose up # Start all services -# selur-compose up --detach # Start in background -# selur-compose verify # Verify all .ctp signatures -# selur-compose ps # Check status -# selur-compose logs -f {{SERVICE_NAME}} # Stream logs -# selur-compose down # Stop all services -# -# Fallback (when selur is not installed): -# podman compose --file compose.toml up --detach - -version = "1.0" - -# ============================================================================ -# Services -# ============================================================================ - -# Primary application service -[services.{{SERVICE_NAME}}] -image = "{{REGISTRY}}/{{SERVICE_NAME}}:latest.ctp" -ports = ["{{PORT}}:{{PORT}}"] -environment = { - APP_HOST = "[::]", - APP_PORT = "{{PORT}}", - APP_LOG_FORMAT = "json", - APP_DATA_DIR = "/data", -} -volumes = ["{{SERVICE_NAME}}-data:/data"] -restart = "always" -healthcheck = { test = "curl -sf http://localhost:{{PORT}}/health", interval = "30s", timeout = "5s", retries = 3 } - -# Svalinn edge gateway: validates requests, enforces policies, TLS termination -[services.svalinn] -image = "ghcr.io/hyperpolymath/svalinn:latest.ctp" -ports = ["443:443", "80:80"] -environment = { - SVALINN_BACKEND = "http://{{SERVICE_NAME}}:{{PORT}}", - SVALINN_POLICY_FILE = "/etc/svalinn/gatekeeper.yaml", - SVALINN_TLS_AUTO = "true", -} -volumes = ["svalinn-config:/etc/svalinn:ro"] -depends_on = ["{{SERVICE_NAME}}"] -restart = "always" -healthcheck = { test = "curl -sf http://localhost:80/health", interval = "30s", timeout = "5s", retries = 3 } - -# ============================================================================ -# Volumes -# ============================================================================ - -[volumes.{{SERVICE_NAME}}-data] -driver = "local" - -[volumes.svalinn-config] -driver = "local" - -# ============================================================================ -# Networks -# ============================================================================ - -# Use selur zero-copy IPC for inter-service communication on the same host. -# Falls back to standard bridge networking when selur driver is unavailable. -[networks.default] -driver = "selur" diff --git a/container/ct-build.sh b/container/ct-build.sh deleted file mode 100755 index a54a541..0000000 --- a/container/ct-build.sh +++ /dev/null @@ -1,162 +0,0 @@ -#!/usr/bin/env bash -# SPDX-License-Identifier: MPL-2.0 -# -# {{PROJECT_NAME}} — Cerro Torre build, sign, and verify pipeline -# -# Builds the container image, packages it as a verified .ctp bundle, -# signs it with Ed25519, and verifies the result. Gracefully degrades -# when cerro-torre tools are not installed. -# -# Prerequisites: -# - podman (container build — required) -# - ct (cerro-torre CLI: pack, sign, verify — optional) -# - cerro-sign (Ed25519 signing — optional, ct sign used as fallback) -# -# Usage: -# ./ct-build.sh # Build + sign (local only) -# ./ct-build.sh --push # Build + sign + push to registry -# CT_KEY_ID=my-key ./ct-build.sh # Use specific signing key -# -# Environment variables: -# CT_KEY_ID — Signing key identifier (default: {{SERVICE_NAME}}-release) -# CT_REGISTRY — OCI registry to push to (default: {{REGISTRY}}) -# CT_TAG — Image tag (default: latest) - -set -euo pipefail - -# --------------------------------------------------------------------------- -# Configuration -# --------------------------------------------------------------------------- - -SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" -REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" - -PUSH="" -for arg in "$@"; do - if [ "$arg" = "--push" ]; then - PUSH="--push" - fi -done - -CT_KEY_ID="${CT_KEY_ID:-{{SERVICE_NAME}}-release}" -CT_REGISTRY="${CT_REGISTRY:-{{REGISTRY}}}" -CT_TAG="${CT_TAG:-latest}" - -IMAGE_NAME="{{SERVICE_NAME}}" -FULL_IMAGE="${CT_REGISTRY}/${IMAGE_NAME}:${CT_TAG}" -CTP_FILE="${SCRIPT_DIR}/${IMAGE_NAME}-${CT_TAG}.ctp" - -echo "=== {{PROJECT_NAME}} Cerro Torre Build Pipeline ===" -echo " Image: ${FULL_IMAGE}" -echo " Key: ${CT_KEY_ID}" -echo " Bundle: ${CTP_FILE}" -echo "" - -# --------------------------------------------------------------------------- -# Step 1: Build container image with Podman -# --------------------------------------------------------------------------- - -echo "--- Step 1: Building container image ---" - -podman build \ - -t "${FULL_IMAGE}" \ - -f "${SCRIPT_DIR}/Containerfile" \ - "${REPO_ROOT}" - -echo " Built: ${FULL_IMAGE}" -echo "" - -# --------------------------------------------------------------------------- -# Step 2: Pack into .ctp bundle -# --------------------------------------------------------------------------- - -echo "--- Step 2: Packing into .ctp bundle ---" - -if command -v ct &>/dev/null; then - ct pack "${FULL_IMAGE}" -o "${CTP_FILE}" - echo " Packed: ${CTP_FILE}" -else - echo " SKIP: ct not found (install cerro-torre CLI from stapeln/container-stack/cerro-torre)" - echo " The container image is built and tagged but not packed as a .ctp bundle." - echo " To pack manually: ct pack ${FULL_IMAGE} -o ${CTP_FILE}" - echo "" - if [ "$PUSH" = "--push" ]; then - echo "--- Pushing unsigned OCI image (no .ctp) ---" - podman push "${FULL_IMAGE}" - echo " Pushed: ${FULL_IMAGE} (unsigned OCI — not a .ctp bundle)" - fi - echo "" - echo "=== Build complete (without .ctp signing) ===" - exit 0 -fi - -echo "" - -# --------------------------------------------------------------------------- -# Step 3: Sign the .ctp bundle -# --------------------------------------------------------------------------- - -echo "--- Step 3: Signing .ctp bundle ---" - -if command -v cerro-sign &>/dev/null; then - cerro-sign sign "${CTP_FILE}" --key-id "${CT_KEY_ID}" - echo " Signed: ${CTP_FILE} (key: ${CT_KEY_ID})" -elif command -v ct &>/dev/null; then - ct sign "${CTP_FILE}" --key "${CT_KEY_ID}" - echo " Signed: ${CTP_FILE} (key: ${CT_KEY_ID})" -else - echo " SKIP: cerro-sign not found (install from stapeln/container-stack/cerro-torre)" -fi - -echo "" - -# --------------------------------------------------------------------------- -# Step 4: Verify the .ctp bundle -# --------------------------------------------------------------------------- - -echo "--- Step 4: Verifying .ctp bundle ---" - -if command -v ct &>/dev/null; then - ct verify "${CTP_FILE}" - echo " Verified: ${CTP_FILE}" -else - echo " SKIP: ct not found" -fi - -echo "" - -# --------------------------------------------------------------------------- -# Step 5: Push to registry (optional) -# --------------------------------------------------------------------------- - -if [ "$PUSH" = "--push" ]; then - echo "--- Step 5: Pushing to registry ---" - - if command -v ct &>/dev/null; then - ct push "${CTP_FILE}" "${FULL_IMAGE}" - echo " Pushed: ${FULL_IMAGE}" - else - # Fall back to podman push (unsigned OCI image) - echo " ct not available, falling back to podman push (unsigned)" - podman push "${FULL_IMAGE}" - echo " Pushed: ${FULL_IMAGE} (unsigned OCI — not a .ctp bundle)" - fi - echo "" -fi - -# --------------------------------------------------------------------------- -# Summary -# --------------------------------------------------------------------------- - -echo "=== Build pipeline complete ===" -echo " Image: ${FULL_IMAGE}" -echo " Bundle: ${CTP_FILE}" -echo "" -echo " To deploy with selur-compose:" -echo " cd container && selur-compose up" -echo "" -echo " To verify at any time:" -echo " ct verify ${CTP_FILE}" -echo "" -echo " To explain the verification chain:" -echo " ct explain ${CTP_FILE}" diff --git a/container/deploy.k9.ncl b/container/deploy.k9.ncl deleted file mode 100644 index 0ad0d04..0000000 --- a/container/deploy.k9.ncl +++ /dev/null @@ -1,166 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# deploy.k9.ncl — {{PROJECT_NAME}} deployment component (Hunt level) -# -# k9-svc deployment specification with full pedigree (L1-L5). -# Security Level: 'Hunt (requires cryptographic handshake for execution). -# -# WARNING: This component can execute shell commands! -# It requires explicit authorisation via the Leash system. -# -# Usage: -# nickel typecheck container/deploy.k9.ncl -# k9-svc validate container/deploy.k9.ncl -# k9-svc deploy container/deploy.k9.ncl --env production - -# The component's pedigree (self-description across five layers) -let component_pedigree = { - # ───────────────────────────────────────────────────────────── - # L1: The Snout — Identity - # ───────────────────────────────────────────────────────────── - metadata = { - name = "{{SERVICE_NAME}}-deploy", - version = "{{VERSION}}", - breed = "application/vnd.k9+nickel", - magic_number = "K9!", - description = "{{PROJECT_NAME}} deployment component (Hunt level)", - }, - - # ───────────────────────────────────────────────────────────── - # L2: The Scent — Target Environment - # ───────────────────────────────────────────────────────────── - target = { - os = 'Linux, - is_edge = false, - requires_podman = true, - min_memory_mb = 256, - }, - - # ───────────────────────────────────────────────────────────── - # L3: The Leash — Security - # ───────────────────────────────────────────────────────────── - security = { - trust_level = 'Hunt, - allow_network = true, - allow_filesystem_write = true, - allow_subprocess = true, - # In production, replace with a real Ed25519 signature. - signature = "PLACEHOLDER-SIGNATURE-REQUIRED-FOR-HUNT", - }, - - # ───────────────────────────────────────────────────────────── - # L4: The Gut — Self-Validation - # ───────────────────────────────────────────────────────────── - validation = { - checksum = "sha256:placeholder", - pedigree_version = "1.0.0", - hunt_authorized = false, # Must be set true after handshake - }, - - # ───────────────────────────────────────────────────────────── - # L5: The Muscle — Deployment Recipes - # ───────────────────────────────────────────────────────────── - recipes = { - install = "just container-build", - validate = "just container-verify", - deploy = "just container-up", - migrate = "just container-build && just container-up", - }, -} in - -# Deployment configuration -let deployment = { - # Target environments (dev / staging / production) - environments = { - dev = { - replicas = 1, - memory = "256Mi", - cpu = "100m", - image_tag = "dev", - }, - staging = { - replicas = 2, - memory = "512Mi", - cpu = "250m", - image_tag = "staging", - }, - production = { - replicas = 3, - memory = "1Gi", - cpu = "500m", - image_tag = "latest", - }, - }, - - # Container configuration - container = { - image = "{{REGISTRY}}/{{SERVICE_NAME}}", - port = {{PORT}}, - health_check = "/health", - readiness_check = "/ready", - }, - - # Deployment strategy - strategy = { - type = "rolling", - max_surge = 1, - max_unavailable = 0, - }, -} in - -# Deployment scripts (executed at Hunt level) -let scripts = { - # Pre-deployment validation - pre_deploy = m%" -#!/bin/sh -set -eu -echo "K9: Pre-deployment validation for {{SERVICE_NAME}}..." -cd container && selur-compose verify || podman compose --file compose.toml config -echo "K9: Validation passed." -"%, - - # Deployment script - deploy = m%" -#!/bin/sh -set -eu -ENV="${1:-dev}" -echo "K9: Deploying {{SERVICE_NAME}} to $ENV environment..." -cd container -./ct-build.sh -selur-compose up --detach || podman compose --file compose.toml up --detach -echo "K9: Deployment to $ENV complete." -"%, - - # Rollback script - rollback = m%" -#!/bin/sh -set -eu -echo "K9: Rolling back {{SERVICE_NAME}} deployment..." -cd container -selur-compose down || podman compose --file compose.toml down -echo "K9: Rollback complete." -"%, -} in - -# Export the component -{ - pedigree = component_pedigree, - deployment = deployment, - scripts = scripts, - - # Security check: this component requires Hunt level - required_level = 'Hunt, - - # Warning for users - warning = m%" -WARNING: This is a Hunt-level component. - -It can execute shell commands and modify your system. -Before running, ensure you have: - -1. Reviewed the deployment scripts above -2. Verified the signature (when implemented) -3. Explicitly authorised Hunt-level execution - -Run with: k9-svc authorize container/deploy.k9.ncl && k9-svc deploy container/deploy.k9.ncl -"%, -} diff --git a/container/entrypoint.sh b/container/entrypoint.sh deleted file mode 100755 index a7a0369..0000000 --- a/container/entrypoint.sh +++ /dev/null @@ -1,63 +0,0 @@ -#!/bin/sh -# SPDX-License-Identifier: MPL-2.0 -# {{PROJECT_NAME}} container entrypoint -# -# Handles signal propagation, startup logging, and health check -# preparation before exec-ing into the main application process. - -set -e - -# --------------------------------------------------------------------------- -# Signal handling -# --------------------------------------------------------------------------- -# -# Trap SIGTERM and SIGINT so that the application can shut down gracefully -# when Podman sends stop signals (e.g. `podman stop`, `selur-compose down`). - -cleanup() { - echo "Received shutdown signal — stopping {{SERVICE_NAME}}..." - # If the main process is backgrounded, kill it here: - # kill "$MAIN_PID" 2>/dev/null || true - # wait "$MAIN_PID" 2>/dev/null || true - exit 0 -} -trap cleanup TERM INT - -# --------------------------------------------------------------------------- -# Startup logging -# --------------------------------------------------------------------------- - -echo "Starting {{SERVICE_NAME}}..." -echo " Host: ${APP_HOST:-[::]}" -echo " Port: ${APP_PORT:-{{PORT}}}" -echo " Data: ${APP_DATA_DIR:-/data}" -echo " Log: ${APP_LOG_FORMAT:-json}" - -# --------------------------------------------------------------------------- -# Health check preparation -# --------------------------------------------------------------------------- -# -# Ensure the data directory exists and is writable. -# The VOLUME directive in the Containerfile creates /data, but a bind-mount -# might replace it with an empty directory owned by root. - -if [ -d "${APP_DATA_DIR:-/data}" ]; then - if [ ! -w "${APP_DATA_DIR:-/data}" ]; then - echo "WARNING: ${APP_DATA_DIR:-/data} is not writable by $(whoami)" - fi -fi - -# --------------------------------------------------------------------------- -# Exec into main process -# --------------------------------------------------------------------------- -# -# Replace the entrypoint shell with the application process so that -# signals are delivered directly and PID 1 is the application. -# -# TODO: Replace the command below with your application binary. -# Examples: -# exec /app/{{SERVICE_NAME}} -# exec /app/release/bin/{{SERVICE_NAME}} start -# exec /app/{{SERVICE_NAME}} serve --host "${APP_HOST}" --port "${APP_PORT}" - -exec "$@" diff --git a/container/manifest.toml b/container/manifest.toml deleted file mode 100644 index f55fcb3..0000000 --- a/container/manifest.toml +++ /dev/null @@ -1,62 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# -# Cerro Torre manifest for {{PROJECT_NAME}} .ctp bundle -# -# This manifest describes the container image for verified -# container packaging. Used by `ct pack` to create .ctp bundles. - -[metadata] -name = "{{SERVICE_NAME}}" -version = "{{VERSION}}" -revision = 1 -summary = "{{PROJECT_DESCRIPTION}}" -description = """ -{{PROJECT_NAME}} — containerised service packaged as a verified -cerro-torre .ctp bundle with Ed25519 signing and full provenance -tracking. -""" -license = "{{LICENSE}}" -homepage = "https://{{FORGE}}/{{OWNER}}/{{REPO}}" -maintainer = "{{AUTHOR}} <{{EMAIL}}>" - -[provenance] -upstream = "https://{{FORGE}}/{{OWNER}}/{{REPO}}" -import_date = {{CURRENT_DATE}}T00:00:00Z - -[dependencies] -runtime = ["ca-certificates", "curl"] -build = [] - -[build] -system = "podman" - -[build.environment] -APP_HOST = "[::]" -APP_PORT = "{{PORT}}" - -[outputs] -primary = "{{SERVICE_NAME}}" -split = [] - -[attestations] -require = ["source-signature", "sbom-complete"] -recommend = ["security-audit", "reproducible-build"] - -# Runtime security profile -[security] -user = "appuser" -group = "appuser" -read_only_root = false -no_new_privileges = true - -[security.capabilities] -drop = ["ALL"] -add = ["NET_BIND_SERVICE"] - -[security.network] -listen_tcp = [{{PORT}}] - -[security.filesystem] -read = ["/app/", "/data/"] -write = ["/data/", "/tmp/"] -execute = ["/app/entrypoint.sh"] diff --git a/container/vordr.toml b/container/vordr.toml deleted file mode 100644 index af38fc5..0000000 --- a/container/vordr.toml +++ /dev/null @@ -1,100 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# -# Vordr runtime monitoring configuration for {{PROJECT_NAME}} -# -# Vordr watches container health, detects crashes, tracks resource usage, -# and emits structured logs. It runs alongside the application stack and -# provides runtime observability without requiring in-process agents. -# -# Usage: -# vordr watch --config container/vordr.toml -# vordr status -# vordr report - -[metadata] -name = "{{SERVICE_NAME}}" -version = "{{VERSION}}" - -# ============================================================================ -# Health Monitoring -# ============================================================================ -# -# Vordr periodically probes these endpoints. If a probe fails beyond the -# failure_threshold, vordr emits an alert and (optionally) restarts the -# container via Podman. - -[health] -# Primary health endpoint — must return 2xx. -endpoint = "http://localhost:{{PORT}}/health" -interval = "30s" -timeout = "5s" -failure_threshold = 3 - -# Readiness endpoint — checked during startup and after restarts. -readiness_endpoint = "http://localhost:{{PORT}}/ready" -readiness_timeout = "10s" - -# Action on failure: "alert" (log + notify) or "restart" (alert + podman restart). -on_failure = "alert" - -# ============================================================================ -# Crash Detection -# ============================================================================ -# -# Monitors container state via Podman. Detects OOM kills, segfaults, -# and unexpected exits. - -[crash_detection] -enabled = true -# Maximum restarts within the window before vordr stops restarting. -max_restarts = 5 -restart_window = "10m" - -# ============================================================================ -# Resource Thresholds -# ============================================================================ -# -# Alert when resource usage exceeds these thresholds. Values are percentages -# of the container's cgroup limits (or host limits if uncapped). - -[resources] -cpu_warn = 80 # Percentage — warn at 80% sustained CPU. -cpu_critical = 95 # Percentage — critical alert at 95%. -memory_warn = 75 # Percentage of memory limit. -memory_critical = 90 -disk_warn = 80 # Percentage of volume usage. -disk_critical = 95 - -# Sample interval for resource metrics. -sample_interval = "15s" - -# ============================================================================ -# Log Output -# ============================================================================ -# -# Vordr emits its own logs (not the application's) in structured format. - -[logging] -format = "json" -level = "info" -# Write vordr logs to stdout (captured by Podman) and optionally to file. -output = "stdout" -# file = "/var/log/vordr/{{SERVICE_NAME}}.log" - -# ============================================================================ -# Notifications (optional) -# ============================================================================ -# -# Uncomment and configure to receive alerts via webhook or email. - -# [notifications.webhook] -# url = "https://example.com/hooks/vordr" -# method = "POST" -# headers = { "Content-Type" = "application/json" } -# on = ["failure", "recovery", "resource_critical"] - -# [notifications.email] -# to = "{{EMAIL}}" -# from = "vordr@{{SERVICE_NAME}}.local" -# smtp = "smtp://localhost:25" -# on = ["failure", "resource_critical"] diff --git a/coordination.k9 b/coordination.k9 deleted file mode 100644 index ba31125..0000000 --- a/coordination.k9 +++ /dev/null @@ -1,43 +0,0 @@ -# Thin coordination bindings for central session-management standards - -session_management: - source_of_truth: "standards/session-management-standards" - canonical_commands: - - "intake repo " - - "checkpoint change " - - "verify maintenance " - - "verify substantial " - - "verify release " - - "close planned " - - "close urgent " - - "recover repo " - - "handover full " - - "handover split " - - "handover model " - - "handover human " - -signals: - - name: "session.intake" - command: "intake repo " - - name: "session.checkpoint" - command: "checkpoint change " - - name: "session.verify.maintenance" - command: "verify maintenance " - - name: "session.verify.substantial" - command: "verify substantial " - - name: "session.verify.release" - command: "verify release " - - name: "session.close.planned" - command: "close planned " - - name: "session.close.urgent" - command: "close urgent " - - name: "session.recover" - command: "recover repo " - - name: "session.handover.full" - command: "handover full " - - name: "session.handover.split" - command: "handover split " - - name: "session.handover.model" - command: "handover model " - - name: "session.handover.human" - command: "handover human " diff --git a/docs-template/README.adoc b/docs-template/README.adoc deleted file mode 100644 index 3640e4c..0000000 --- a/docs-template/README.adoc +++ /dev/null @@ -1,66 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) -= Documentation Template -:revdate: 2026-05-26 -:status: SEED - -This directory is the *minimum heavy-wiki seed* for a hyperpolymath repo. - -== How to adopt - -. Copy `docs-template/` → `docs/` in your repo. -. Replace `{{PROJECT_NAME}}`, `{{OWNER}}`, `{{AUTHOR}}`, `{{AUTHOR_EMAIL}}`, - `{{CURRENT_YEAR}}` placeholders. -. Delete any sections that genuinely do not apply (don't leave empty - scaffolding — the 2026-05-26 doc-debt audit flagged 61 estate repos - with empty `docs/` dirs as a separate category of debt). -. Add repo-specific sections as needed. - -== What's in here - -[cols="1,2", options="header"] -|=== -| File | Purpose - -| `README.adoc` | This file. Delete after copying. -| `architecture.adoc` | System overview, component diagram, data flow. -| `usage.adoc` | End-user / consumer perspective. How to invoke / consume / depend on this repo. -| `contributing.adoc` | Developer perspective. Local-dev setup, test running, PR conventions. -| `troubleshooting.adoc` | FAQ-style. Known failure modes + recovery paths. -| `decisions/0001-template.adoc` | ADR (Architecture Decision Record) template. Copy → `0002-...`, `0003-...` etc. -|=== - -== Why these five sections - -The 2026-05-26 estate documentation-debt audit -(link:https://github.com/hyperpolymath/standards/blob/main/docs/audits/2026-05-26-estate-documentation-debt.md[standards#197]) -identified four canonical perspectives every repo should answer: - -. **What is it** — README answers (lives at repo root, not here). -. **How is it built** — `architecture.adoc`. -. **How do I use it** — `usage.adoc`. -. **How do I help build it** — `contributing.adoc`. -. **What goes wrong** — `troubleshooting.adoc`. - -ADRs are the long-running historical record — they don't fit any of -the above but are essential for explaining *why* a particular shape -was chosen. - -== What's intentionally NOT in here - -This seed deliberately omits: - -* `proof-debt.md` — only relevant to proof-bearing repos; see - link:https://github.com/hyperpolymath/standards/blob/main/docs/TRUSTED-BASE-REDUCTION-POLICY.adoc[standards#203]. -* `CHANGELOG.md` — generated automatically by - link:https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml[`changelog-reusable.yml`] - (standards#206), don't write by hand. -* `tech-debt-YYYY-MM-DD.md` — generated by the periodic estate audit. - -== "Heavily-developed wiki" bar (audit definition) - -A repo meets the audit's bar when `docs/` contains ≥ 10 substantive -markdown / asciidoc / rst files with topical organisation. Adopting -this seed gets you to ~5 — add repo-specific deep-dives (typically -one per major component or invariant) to clear the bar. diff --git a/docs-template/architecture.adoc b/docs-template/architecture.adoc deleted file mode 100644 index da49a38..0000000 --- a/docs-template/architecture.adoc +++ /dev/null @@ -1,79 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -// SPDX-FileCopyrightText: {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -= Architecture — {{PROJECT_NAME}} -:revdate: {{CURRENT_YEAR}}-MM-DD - -== System overview - -One paragraph: what this project does and what it does not do. State the -*invariant* — the property that, if violated, would make the whole project -pointless. Future maintainers will read this paragraph first. - -== Component diagram - -Replace this section with an ASCII or Mermaid diagram. Keep it under 20 -lines — anything bigger belongs in `architecture/`. - -[source] ----- -+------------------+ +------------------+ -| Component A | ---> | Component B | -+------------------+ +------------------+ - | - v -+------------------+ -| Component C | -+------------------+ ----- - -== Data flow - -For each external input, describe: - -* **Source**: where it comes from. -* **Validation**: what guarantees we enforce on entry. -* **Transformation**: high-level processing stages. -* **Sink**: where the result goes. - -== Key invariants - -Enumerate the load-bearing invariants of the system. Each should have: - -. A one-line statement. -. The code location(s) that enforce it. -. The failure mode if the invariant is violated. - -Example: - -[cols="1,2,2,2", options="header"] -|=== -| # | Invariant | Enforced at | Failure mode - -| 1 -| All HTTP requests carry a valid `X-Request-ID`. -| `src/middleware/request_id.rs` -| Logs become unjoinable; correlation breaks. - -| 2 -| The output buffer is always flushed before exit. -| `src/main.rs:88-92` (Drop impl) -| Last ~16KB of log lost on crash. -|=== - -== Dependencies - -* **Internal**: list other hyperpolymath repos this depends on. -* **External**: SHA-pinned (see `Cargo.lock` / `deno.lock` / etc.). -* **Build-time**: tools required to build (just, deno, cargo, …). - -== Out of scope - -Explicit non-goals. Things we deliberately do *not* do, with a one-line -reason for each. This section saves more time than the rest combined. - -== See also - -* link:./usage.adoc[Usage] — consumer perspective. -* link:./contributing.adoc[Contributing] — developer setup. -* link:./decisions/[ADRs] — historical record of why this shape. diff --git a/docs-template/contributing.adoc b/docs-template/contributing.adoc deleted file mode 100644 index cb49ce6..0000000 --- a/docs-template/contributing.adoc +++ /dev/null @@ -1,91 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -// SPDX-FileCopyrightText: {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -= Contributing — {{PROJECT_NAME}} -:revdate: {{CURRENT_YEAR}}-MM-DD - -== Audience - -Developers working *on* `{{PROJECT_NAME}}`. For consumers (people calling -or depending on it) see link:./usage.adoc[usage.adoc]. - -== Local-dev setup - -Prerequisites — the minimum versions and where to get them: - -* `` v`` — ``. -* `` v`` — ``. -* GPG signing key configured (estate policy — all commits must be - signed). See - link:https://github.com/hyperpolymath/standards/blob/main/docs/secure-coding-training.md[standards/docs/secure-coding-training.md]. - -One-shot setup: - -[source,bash] ----- -git clone git@github.com:{{OWNER}}/{{PROJECT_NAME}}.git -cd {{PROJECT_NAME}} -just setup # installs deps, sets up hooks -just test # runs the full test suite ----- - -== Running tests - -* **Unit**: `just test-unit` — fast, no I/O. -* **Integration**: `just test-int` — uses real services (database, - HTTP, etc.). Estate policy: prefer real over mocked - (see `feedback_integration_tests_real_db` in maintainer's memory). -* **Property**: `just test-prop` — randomised, slower; budget - documented in `docs/proof-debt.md` if applicable. -* **Full**: `just test` — runs all of the above. - -== Code style - -We enforce style via CI (governance-reusable.yml from hyperpolymath/standards). -Locally: - -[source,bash] ----- -just fmt # auto-format -just lint # static checks ----- - -* All commits must be **GPG-signed** (CI enforces; see - link:https://github.com/hyperpolymath/standards[standards]). -* All source files must carry an **SPDX-License-Identifier** header - (CI enforces). -* Conventional commits — `feat`, `fix`, `chore`, `refactor`, `docs`, - `test`, `ci`, `revert` (CHANGELOG is auto-generated from these - via link:https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml[`changelog-reusable.yml`]). - -== Branching & PR workflow - -. Branch off `main` as `claude/` (for AI agents) or - `/` (for humans). -. Make focused, narrow commits — one logical change per commit. -. Open a PR against `main`. -. **Enable auto-merge immediately** on every PR you open - (`gh pr merge --auto --squash`) — estate standing policy - (see standards#196 audit and policies). -. CI must be green. The PR auto-merges when checks pass + reviews land. - -== Adding a new dependency - -. State the *why* in the PR body — what does this dependency unlock? -. Check provenance (maintained, audited, no malicious history). -. Pin to a SHA, not a tag. -. Update `docs/architecture.adoc#Dependencies`. - -== Adding an ADR - -When you make a non-obvious design decision, write it down: - -. Copy `docs/decisions/0001-template.adoc` → `0002-.adoc`. -. Fill in: Context, Decision, Consequences, Alternatives. -. Link the ADR from the README or relevant code as a comment. - -== Reporting issues - -* Bugs in `{{PROJECT_NAME}}`: file at `{{OWNER}}/{{PROJECT_NAME}}/issues`. -* Estate-wide concerns (policy, conventions, CI): file at - `hyperpolymath/standards/issues`. diff --git a/docs-template/decisions/0001-template.adoc b/docs-template/decisions/0001-template.adoc deleted file mode 100644 index 6b57cbe..0000000 --- a/docs-template/decisions/0001-template.adoc +++ /dev/null @@ -1,54 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -// SPDX-FileCopyrightText: {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -= ADR-0001 — Use Architecture Decision Records -:revdate: {{CURRENT_YEAR}}-MM-DD -:status: ACCEPTED - -== Context - -We need a lightweight way to record significant architectural decisions -and the reasoning behind them, so future maintainers (and AI agents) -can understand *why* the project is shaped as it is. - -== Decision - -Adopt link:https://adr.github.io/[Architecture Decision Records (ADRs)] -in `docs/decisions/`, numbered sequentially (0001, 0002, ...). - -* Each ADR is a single `.adoc` file. -* The first ADR (this one) records the decision to use ADRs. -* Status values: PROPOSED, ACCEPTED, DEPRECATED, SUPERSEDED. -* When a decision is overturned, the new ADR records the supersession - and updates the old one's status to `SUPERSEDED by 00NN`. - -== Consequences - -. **Positive**: future readers see *why* without git-archaeology. -. **Positive**: design alternatives are documented, not just the - winning choice. -. **Positive**: ADRs are reviewable in PRs — the design discussion - happens alongside the code that implements it. -. **Negative**: maintenance burden — every non-obvious decision now - warrants an ADR. (We mitigate by keeping ADRs short; "non-obvious" - is a judgment call.) -. **Negative**: ADRs can rot. We accept this; the SUPERSEDED chain - is the recovery mechanism. - -== Alternatives considered - -. **Comments in code** — too local; doesn't capture cross-cutting - decisions. -. **Wiki / external doc** — drifts from code; not in PR review. -. **Commit messages** — too transient and not discoverable. -. **No record** — discarded; this is how every project ends up with - "I don't know why we do it this way" debt. - -== Companion ADRs - -* (None yet — this is the first ADR.) - -== References - -* MADR template — `https://adr.github.io/madr/` -* Estate convention — `hyperpolymath/standards/docs/RSR_OUTLINE.adoc` diff --git a/docs-template/troubleshooting.adoc b/docs-template/troubleshooting.adoc deleted file mode 100644 index 29f1a74..0000000 --- a/docs-template/troubleshooting.adoc +++ /dev/null @@ -1,58 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -// SPDX-FileCopyrightText: {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -= Troubleshooting — {{PROJECT_NAME}} -:revdate: {{CURRENT_YEAR}}-MM-DD - -This file is a *living FAQ* — known failure modes and recovery paths. -Add a new entry every time you debug something that took more than 15 -minutes; future-you (and other maintainers) will thank you. - -== Known failure modes - -=== `` - -**Symptom**: short reproduction. What does the user see? - -**Cause**: root cause (one or two sentences). - -**Fix**: -[source,bash] ----- - ----- - -**Avoidance**: how to not hit this again (config setting, doc link, etc.). - ---- - -=== `` - -(Replace this and the above example with real entries as you encounter -them.) - -== Diagnostic toolkit - -When something is wrong, run these first: - -[source,bash] ----- -just doctor # runs all available self-checks -just version # prints the version & build hash -just log-tail # last N lines of logs ----- - -== When to escalate - -. Filed an issue with: version, OS, exact command, full error output, - and the symptom in plain English. -. Linked from the issue: the relevant ADR(s) and any related issues. -. For *security*-relevant findings, see - link:./../SECURITY.md[SECURITY.md] — do **not** file public issues. - -== Where to look for more help - -* `docs/architecture.adoc` — internals. -* `docs/decisions/` — historical record of why things are this shape. -* `https://github.com/{{OWNER}}/{{PROJECT_NAME}}/issues?q=is%3Aissue+` — has anyone hit this before? -* `https://github.com/hyperpolymath/standards/issues` — for estate-wide problems. diff --git a/docs-template/usage.adoc b/docs-template/usage.adoc deleted file mode 100644 index 0154cbb..0000000 --- a/docs-template/usage.adoc +++ /dev/null @@ -1,82 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -// SPDX-FileCopyrightText: {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -= Usage — {{PROJECT_NAME}} -:revdate: {{CURRENT_YEAR}}-MM-DD - -== Audience - -This document is for *consumers* of `{{PROJECT_NAME}}` — people who depend -on it, call it, or include it. For developers working *on* it, see -link:./contributing.adoc[contributing.adoc]. - -== Quickstart - -The shortest path from zero to a working call: - -[source,bash] ----- -# 1. Install -just install # or: cargo install --path . / deno task install - -# 2. Configure -cp examples/config.example.toml ./config.toml -# Edit minimal required fields. - -# 3. Run -just run # or the equivalent for your language ----- - -Expected output: - -[source] ----- -{{PROJECT_NAME}} v0.0.0 -Listening on 127.0.0.1:8080 ----- - -== Common use cases - -For each canonical use case, give: - -. A one-line statement of the goal. -. The minimal invocation. -. Expected output / side effect. - -=== Use case 1: - -(Replace with real content.) - -=== Use case 2: - -== Configuration reference - -Document every configurable field. Keep this section authoritative — if -the code grows a new option, this table must grow too (CI can be wired -to enforce this). - -[cols="1,1,1,3", options="header"] -|=== -| Field | Type | Default | Meaning - -| `` | `` | `` | -|=== - -== Stability guarantees - -Be explicit: - -* **Stable**: API surfaces that follow SemVer (breaking change = major bump). -* **Unstable**: behind a flag / pre-1.0 / explicitly marked. -* **Internal**: documented for reference but no compatibility promise. - -== Limits & known constraints - -* Maximum supported ``: ``. -* `` is not yet implemented; track at issue `#`. -* On ``, `` behaves differently because ``. - -== See also - -* link:./architecture.adoc[Architecture] — how it works internally. -* link:./troubleshooting.adoc[Troubleshooting] — when things go wrong. diff --git a/docs/0.1-AI-MANIFEST.a2ml b/docs/0.1-AI-MANIFEST.a2ml deleted file mode 100644 index 7f79301..0000000 --- a/docs/0.1-AI-MANIFEST.a2ml +++ /dev/null @@ -1,33 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "docs-pillar" -level: 1 -parent: "../0-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Technical documentation hub. The root contains high-level orientation - (README, Quickstart, State-Visualizer). Specialized tracks live in - subdirectories. - -canonical_locations: - quickstart: "QUICKSTART.adoc" - state_visualizer: "STATE-VISUALIZER.adoc" - governance: "governance/" - architecture: "architecture/" - decisions: "decisions/" - theory: "theory/" - practice: "practice/" - developer: "developer/" - attribution: "attribution/" - reports: "reports/" - whitepapers: "whitepapers/" - standards: "standards/" - legal: "legal/" - wikis: "wikis/" - -invariants: - - "Primary documentation format MUST be AsciiDoc (.adoc)" - - "Root docs/ MUST only contain pillar entry points" diff --git a/docs/QUICKSTART.adoc b/docs/QUICKSTART.adoc deleted file mode 100644 index 7974257..0000000 --- a/docs/QUICKSTART.adoc +++ /dev/null @@ -1,26 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Quickstart -:toc: preamble - -Get up and running in 60 seconds. - -== Prerequisites - -* Git 2.40+ -* just (command runner) -* Your language toolchain (see Justfile for details) - -== From Template (New Project) - -[source,bash] ----- -git clone https://github.com/{{OWNER}}/rsr-template-repo my-project -cd my-project -rm -rf .git && git init -b main -just init # interactive placeholder replacement ----- - -== Project Structure - -See README.adoc in the root for the Dual-Track architecture summary. diff --git a/docs/README.adoc b/docs/README.adoc deleted file mode 100644 index adf6a02..0000000 --- a/docs/README.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Documentation Layout - -Primary tracks: - -* `theory/` for formal and conceptual material -* `practice/` for operational and implementation material -* `maintenance/` for baseline checklists and release hard-pass runbooks -* `whitepapers/academic/` for research-facing whitepapers -* `whitepapers/industry/` for industry/outreach whitepapers - -Core docs: - -* `maintenance/MAINTENANCE-CHECKLIST.md` -* `practice/SOFTWARE-DEVELOPMENT-APPROACH.adoc` diff --git a/docs/RSR_OUTLINE.adoc b/docs/RSR_OUTLINE.adoc deleted file mode 100644 index dbf90ba..0000000 --- a/docs/RSR_OUTLINE.adoc +++ /dev/null @@ -1,292 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= RSR Template Repository - -image:[Palimpsest-MPL-1.0,link="https://github.com/hyperpolymath/palimpsest-license"] image:[Palimpsest,link="https://github.com/hyperpolymath/palimpsest-license"] -:toc: -:sectnums: - -// Badges -image:https://img.shields.io/badge/RSR-Infrastructure-cd7f32[RSR Infrastructure] -image:https://img.shields.io/badge/Phase-Maintenance-brightgreen[Phase] -image:https://img.shields.io/badge/Guix-Primary-purple?logo=gnu[Guix] - -== Overview - -**The canonical template for RSR (Rhodium Standard Repository) projects.** - -This repository provides the standardized structure, configuration, and tooling for all RSR-compliant repos. Use it to: - -* Bootstrap new projects with RSR compliance -* Reference the standard directory structure -* Copy configuration templates (Justfile, STATE.a2ml, etc.) - -== Quick Start - -[source,bash] ----- -# Clone the template -git clone https://github.com/hyperpolymath/RSR-template-repo my-project -cd my-project - -# Remove template git history -rm -rf .git -git init - -# Interactive bootstrap — replaces all placeholders -just init - -# Enter development environment -guix shell -D -f guix.scm - -# Validate compliance -just validate-rsr ----- - -== What's Included - -[cols="1,3"] -|=== -|File/Directory |Purpose - -|`.editorconfig` -|Editor configuration (indent, charset) - -|`.gitignore` -|Standard ignore patterns - -|`.gitattributes` -|Line endings, diff drivers, binary detection - -|`.guix-channel` -|Guix channel definition - -|`.well-known/` -|RFC-compliant metadata (security.txt, ai.txt, humans.txt) - -|`.machine_readable/` -|All machine-readable content: state files (6 a2ml), `bot_directives/`, `contractiles/` - -|`docs/` -|Documentation directory - -|`guix.scm` -|Guix package definition - -|`Justfile` -|Task runner with 40+ recipes - -|`Containerfile` -|Container build (Wolfi base, Podman) - -|`LICENSE` -|MPL-2.0 (Palimpsest MPL) - -|`EXHIBIT-A-ETHICAL-USE.txt` -|Ethical use guidelines (LICENSE Exhibit A) - -|`EXHIBIT-B-QUANTUM-SAFE.txt` -|Quantum-safe provenance spec (LICENSE Exhibit B) - -|`README.adoc` -|Project overview - -|`TOPOLOGY.md` -|Architecture diagram and completion dashboard - -|`PLACEHOLDERS.md` -|Template variable reference and replacement guide - -|`0-AI-MANIFEST.a2ml` -|Universal AI agent entry point - -|`AI.a2ml` -|Claude-specific instructions - -|`src/abi/` -|Idris2 ABI definitions (Types, Layout, Foreign) - -|`ffi/zig/` -|Zig FFI implementation - -|`generated/abi/` -|Auto-generated C headers from Idris2 ABI -|=== - -== Justfile Features - -The template Justfile provides: - -* **Combinatoric matrix recipes** for build, test, container, CI -* **Cookbook generation**: `just cookbook` -> `docs/just-cookbook.adoc` -* **Man page generation**: `just man` -> `docs/man/project.1` -* **RSR validation**: `just validate-rsr` -* **STATE.a2ml management**: `just state-touch`, `just state-phase` -* **Container support**: `just container-build`, `just container-push` -* **CI matrix**: `just ci-matrix [stage] [depth]` - -=== Key Recipes - -[source,bash] ----- -just # Show all recipes -just help # Detailed help -just info # Project info -just combinations # Show matrix options - -just build # Build (debug) -just test # Run tests -just quality # Format + lint + test -just ci # Full CI pipeline - -just validate # RSR + STATE validation -just docs # Generate all docs -just cookbook # Generate Justfile docs - -just guix-shell # Guix dev environment -just container-build # Build container ----- - -== Directory Structure - -[source] ----- -project/ -├── .editorconfig # Editor settings -├── .gitignore # Git ignore -├── .gitattributes # Line endings, diff drivers -├── .guix-channel # Guix channel -├── .well-known/ # RFC metadata -│ ├── ai.txt -│ ├── humans.txt -│ └── security.txt -├── .machine_readable/ # ALL machine-readable content -│ ├── STATE.a2ml # Project state, progress, blockers -│ ├── META.a2ml # Architecture decisions, governance -│ ├── ECOSYSTEM.a2ml # Ecosystem position, relationships -│ ├── AGENTIC.a2ml # AI agent interaction patterns -│ ├── NEUROSYM.a2ml # Neurosymbolic integration config -│ ├── PLAYBOOK.a2ml # Operational runbook -│ ├── bot_directives/ # Per-bot rules and constraints -│ └── contractiles/ # Policy enforcement contracts -│ ├── k9/ # Security levels (Kennel/Yard/Hunt) -│ ├── dust/Dustfile # Recovery and rollback -│ ├── intend/Intentfile # Future intent declarations -│ ├── must/Mustfile # Invariant checks -│ └── trust/Trustfile.hs # Cryptographic verification -├── docs/ # Documentation -│ ├── CITATIONS.adoc -│ ├── TOPOLOGY-GUIDE.adoc -│ ├── generated/ -│ └── man/ -├── src/abi/ # Idris2 ABI definitions -│ ├── Types.idr -│ ├── Layout.idr -│ └── Foreign.idr -├── ffi/zig/ # Zig FFI implementation -│ ├── build.zig -│ ├── src/main.zig -│ └── test/integration_test.zig -├── generated/abi/ # Auto-generated C headers -├── examples/ # Example code -├── guix.scm # Guix package -├── Justfile # Task runner -├── Containerfile # Container build -├── LICENSE # MPL-2.0 -├── EXHIBIT-A-ETHICAL-USE.txt # Ethical use guidelines -├── EXHIBIT-B-QUANTUM-SAFE.txt # Quantum-safe provenance -├── README.adoc # Overview -├── TOPOLOGY.md # Architecture + completion -├── PLACEHOLDERS.md # Template variable guide -├── 0-AI-MANIFEST.a2ml # Universal AI entry point -└── AI.a2ml # Claude-specific instructions ----- - -== RSR Compliance - -=== Language Tiers - -* **Tier 1** (Gold): Rust, Elixir, Zig, Ada, Haskell, ReScript, Gleam -* **Tier 2** (Silver): Nickel, Guile Scheme, Nix, Idris2, OCaml -* **Infrastructure**: Guix channels, derivations, Julia batch scripts - -=== Required Files - -* `.editorconfig` -* `.gitignore` -* `Justfile` -* `README.adoc` -* `LICENSE` (MPL-2.0) -* `.machine_readable/6a2/STATE.a2ml` -* `.well-known/security.txt` -* `.well-known/ai.txt` -* `.well-known/humans.txt` -* `guix.scm` OR `flake.nix` - -=== Prohibited - -* Python outside `salt/` directory -* TypeScript/JavaScript (use ReScript) -* CUE (use Guile/Nickel) -* `Dockerfile` (use `Containerfile`) -* npm, Bun, pnpm, yarn (use Deno) -* Go (use Rust) - -== STATE.a2ml - -The STATE.a2ml file tracks project state: - -[source] ----- -# STATE — Project State Checkpoint -# Format: a2ml (AI-readable markup) - -project: v-graphql -version: 0.1.0 -last-updated: 2026-02-14 -status: active - -phase: implementation -maturity: beta - -ecosystem: - part-of: RSR Framework - depends-on: [] - -milestones: - - name: Initial setup - completion: 100 - - name: Core implementation - completion: 0 ----- - -== Badge Schema - -Generate badges from STATE.a2ml: - -[source,bash] ----- -just badges standard ----- - -See `docs/BADGE_SCHEMA.adoc` for the full badge taxonomy. - -== Ecosystem Integration - -This template is part of: - -* **STATE.a2ml Ecosystem**: Conversation checkpoints -* **RSR Framework**: Repository standards -* **Consent-Aware-HTTP**: .well-known compliance -* **Hypatia**: Neurosymbolic security scanning -* **gitbot-fleet**: Bot orchestration - -== License - -SPDX-License-Identifier: MPL-2.0 - -== Links - -* https://github.com/hyperpolymath/elegant-STATE[elegant-STATE] - STATE tooling -* https://github.com/hyperpolymath/conative-gating[conative-gating] - Policy enforcement -* https://rhodium.sh[Rhodium Standard] - RSR documentation diff --git a/docs/STATE-VISUALIZER.adoc b/docs/STATE-VISUALIZER.adoc deleted file mode 100644 index 77c0248..0000000 --- a/docs/STATE-VISUALIZER.adoc +++ /dev/null @@ -1,130 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Project State Visualizer -[source] ----- - - - - -# RSR Template Repo — Project Topology - -## System Architecture - -``` - ┌─────────────────────────────────────────┐ - │ NEW REPOSITORY │ - │ (Consumer of this Template) │ - └───────────────────┬─────────────────────┘ - │ Scaffolding - ▼ - ┌─────────────────────────────────────────┐ - │ RSR TEMPLATE HUB │ - │ │ - │ ┌───────────┐ ┌───────────────────┐ │ - │ │ AI Gate- │ │ ABI / FFI │ │ - │ │ keeper │ │ Standard │ │ - │ │ (0-AI-M) │ │ (Idris2/Zig) │ │ - │ └─────┬─────┘ └────────┬──────────┘ │ - │ │ │ │ - │ ┌─────▼─────┐ ┌────────▼──────────┐ │ - │ │ Topology │ │ SCM / 6SCM │ │ - │ │ Guide │ │ Metadata │ │ - │ │ (Visual) │ │ (machine_read) │ │ - │ └─────┬─────┘ └────────┬──────────┘ │ - │ │ │ │ - │ ┌─────▼─────────────────▼──────────┐ │ - │ │ CONTAINER ECOSYSTEM │ │ - │ │ ┌──────────┐ ┌───────────────┐ │ │ - │ │ │ Podman / │ │ selur-compose │ │ │ - │ │ │ OCI │ │ cerro-torre │ │ │ - │ │ │ Build │ │ svalinn/vordr │ │ │ - │ │ └──────────┘ └───────────────┘ │ │ - │ │ ct-build.sh deploy.k9.ncl │ │ - │ └──────────────────────────────────┘ │ - └────────│─────────────────│──────────────┘ - │ │ - ▼ ▼ - ┌─────────────────────────────────────────┐ - │ PLATFORM INTEGRATION │ - │ ┌───────────┐ ┌───────────┐ ┌───────┐│ - │ │ GitHub │ │ GitLab │ │ Nix / ││ - │ │ Workflows │ │ CI/CD │ │ Guix ││ - │ └───────────┘ └───────────┘ └───────┘│ - └─────────────────────────────────────────┘ - - ┌─────────────────────────────────────────┐ - │ REPO INFRASTRUCTURE │ - │ Justfile / Mustfile .machine_readable/ │ - │ Codeowners / Reuse 0-AI-MANIFEST.a2ml │ - └─────────────────────────────────────────┘ -``` - -## Completion Dashboard - -``` -COMPONENT STATUS NOTES -───────────────────────────────── ────────────────── ───────────────────────────────── -CORE STANDARDS - ABI/FFI Standard (Idris2/Zig) ██████████ 100% Universal interface stable - AI Gatekeeper (0-AI-MANIFEST) ██████████ 100% Universal entry point active - TOPOLOGY.md Standard ██████████ 100% Visual summary guide active - 6SCM Metadata Structure ██████████ 100% Machine-readable state stable - -INFRASTRUCTURE - Justfile Automation ██████████ 100% Standard build/verify tasks - CI/CD Workflow Templates ██████████ 100% GH/GL scaffolding verified - Multi-Forge Sync ██████████ 100% Hub-and-spoke mirroring stable - -CONTAINER ECOSYSTEM (Phase 2) - Containerfile (OCI build) ██████████ 100% Multi-stage Chainguard base - selur-compose orchestration ██████████ 100% Template + concrete example - cerro-torre manifest ██████████ 100% Bundle metadata & signing - svalinn gateway policy ██████████ 100% .gatekeeper.yaml active - vordr runtime monitoring ██████████ 100% Runtime config template - k9-svc deployment (Nickel) ██████████ 100% Hunt-level deploy descriptor - ct-build.sh pipeline ██████████ 100% Build/sign/verify script - Justfile container-* recipes ██████████ 100% 8 recipes integrated - Trustfile CONTAINER_SUPPLY_CHAIN ██████████ 100% Supply chain section added - -REPO INFRASTRUCTURE - .machine_readable/ ██████████ 100% STATE/META/ECOSYSTEM active - Governance & License ██████████ 100% PMPL & Ethical use verified - Development Shells (Nix/Guix) ██████████ 100% Reproducible env stable - -───────────────────────────────────────────────────────────────────────────── -OVERALL: ██████████ 100% RSR Template Stable & Certified -``` - -## Key Dependencies - -``` -Philosophy ──────► RSR Standard ──────► Template Scaffolding ──► New Repo - │ │ │ │ - ▼ ▼ ▼ ▼ -CCCP Policy ─────► 0-AI-MANIFEST ────────► Justfile ──────────► Compliance - │ - ▼ - Container Ecosystem - ┌──────────┼──────────┐ - ▼ ▼ ▼ - selur-compose cerro- svalinn/ - (orchestrate) torre vordr - (sign) (monitor) - │ - ▼ - k9-svc deploy -``` - -## 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 - -Progress bars use: `█` (filled) and `░` (empty), 10 characters wide. -Percentages: 0%, 10%, 20%, ... 100% (in 10% increments). ----- diff --git a/docs/architecture/0.2-AI-MANIFEST.a2ml b/docs/architecture/0.2-AI-MANIFEST.a2ml deleted file mode 100644 index 028b503..0000000 --- a/docs/architecture/0.2-AI-MANIFEST.a2ml +++ /dev/null @@ -1,17 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "architecture-track" -level: 2 -parent: "../0.1-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Documentation track for system architecture and threat models. - -canonical_locations: - threat_model: "THREAT-MODEL.adoc" - -invariants: - - "Visual diagrams MUST include ASCII or Mermaid representations" diff --git a/docs/architecture/THREAT-MODEL.adoc b/docs/architecture/THREAT-MODEL.adoc deleted file mode 100644 index 05e1f7c..0000000 --- a/docs/architecture/THREAT-MODEL.adoc +++ /dev/null @@ -1,164 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Threat Model - - - -# Threat Model: {{PROJECT_NAME}} - -## Document Info - -| Field | Value | -|---------------|--------------------------------| -| Project | {{PROJECT_NAME}} | -| Version | 1.0 | -| Last Reviewed | {{DATE}} | -| Author | {{AUTHOR}} | -| Methodology | STRIDE | - -## Scope - -### In Scope - -- Application source code and build pipeline -- CI/CD workflows (GitHub Actions) -- Container images and runtime environment -- Secrets and credential management -- Dependencies (direct and transitive) -- Deployment artifacts (binaries, containers, SBOM) - -### Out of Scope - -- Physical security of hosting infrastructure -- GitHub/GitLab platform-level vulnerabilities -- End-user device security -- Social engineering attacks against maintainers (handled by org policy) - -## System Overview - -Brief description of {{PROJECT_NAME}} and its architecture. - -> See [STATE-VISUALIZER.adoc](../STATE-VISUALIZER.adoc) for the full architecture diagram and completion dashboard. - -## Assets - -| Asset | Classification | Owner | Notes | -|----------------------|----------------|-------------|--------------------------------------------| -| Source code | Internal | Maintainers | Public repos are still internal-integrity | -| Signing keys | Restricted | Release lead | Signing keys (e.g., Ed25519), GPG keys | -| CI/CD secrets | Restricted | Maintainers | GITHUB_TOKEN, deploy tokens, PATs | -| User/contributor data | Confidential | Org | Emails, contributor identity | -| Build artifacts | Internal | CI pipeline | Binaries, WASM bundles | -| Container images | Internal | CI pipeline | Chainguard-based, signed via image signing tool | -| SBOM / provenance | Public | CI pipeline | SLSA attestations | -| Dependencies | Public | Lockfile | Cargo.lock, deno.lock, gleam.toml | -| Infrastructure config | Confidential | Maintainers | Containerfiles, compose files, orchestration config | - -## Trust Boundaries - -| Boundary | From (Lower Trust) | To (Higher Trust) | -|-----------------------------|---------------------------|----------------------------| -| Pull request submission | External contributor | Repository codebase | -| CI/CD workflow execution | Workflow definition | Runner with secrets access | -| Container build boundary | Build stage | Runtime stage | -| External API calls | Third-party service | Application internals | -| User input (CLI/Web) | End user | Application logic | -| Dependency resolution | Package registry | Build environment | -| Forge mirroring | GitHub | GitLab / Bitbucket | - -## Threat Actors - -| Actor | Motivation | Capability | -|--------------------------|-------------------------------|------------| -| Script kiddie | Vandalism, clout | Low | -| Disgruntled contributor | Sabotage, backdoor insertion | Medium | -| Supply chain attacker | Wide-impact compromise | High | -| Nation state | Espionage, disruption | Very High | -| Automated bot | Credential stuffing, spam PRs | Low-Medium | - -## STRIDE Analysis - -### Spoofing - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Unsigned commits impersonate maintainer | Source code | Medium | High | High | Require GPG-signed commits; vigilant code review | -| Forged bot actions (automated agents) | CI/CD pipeline | Low | High | Medium | Bot tokens scoped minimally; audit bot activity | -| Spoofed package registry identity | Dependencies | Low | High | Medium | Pin dependencies by hash; verify provenance | - -### Tampering - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Malicious pull request | Source code | Medium | High | High | Branch protection; required reviews; CodeQL | -| Dependency poisoning (typosquat) | Dependencies | Medium | High | High | Lockfiles; secret-scanner; security scans | -| Tampered container base image | Container images | Low | High | Medium | Chainguard images; image signing verification | -| Workflow file modification | CI/CD pipeline | Low | High | Medium | CODEOWNERS on .github/; workflow-linter | - -### Repudiation - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Unlogged deployment | Build artifacts | Medium | Medium | Medium | SLSA provenance; deployment audit trail | -| Denied merge of vulnerable code | Source code | Low | Medium | Low | Git history is immutable; signed commits | -| Secret rotation without record | CI/CD secrets | Low | Low | Low | Secret rotation logged in STATE.a2ml | - -### Information Disclosure - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Secrets leaked in git history | CI/CD secrets | Medium | High | High | TruffleHog in CI; secret-scanner workflow | -| Verbose error messages in prod | Application logic | Medium | Medium | Medium | Sanitize outputs; structured logging | -| SBOM reveals internal structure | Infrastructure | Low | Low | Low | Accepted risk; SBOM is intentionally public | - -### Denial of Service - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| CI resource exhaustion (fork bomb in PR) | CI/CD pipeline | Medium | Medium | Medium | Concurrency limits; timeout on workflows | -| Spam issues/PRs flooding triage | Maintainer time | Medium | Low | Low | GitHub rate limits; bot auto-close stale | -| Large binary commits bloating repo | Source code | Low | Medium | Low | .gitattributes LFS policy; pre-commit hooks | - -### Elevation of Privilege - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Workflow injection via PR title/body | CI/CD pipeline | Medium | High | High | Never interpolate PR fields in `run:`; use env vars | -| GITHUB_TOKEN over-scoped | CI/CD secrets | Medium | High | High | `permissions: read-all` default; per-job scoping | -| Container escape | Runtime environment | Low | High | Medium | Hardened container runtime; read-only rootfs; no-new-privileges | -| Compromised action dependency | CI/CD pipeline | Medium | High | High | SHA-pin all actions; never use `@latest` tags | - -## Mitigations in Place - -- **SLSA Provenance**: Build attestations via slsa-github-generator -- **Secret Scanning**: TruffleHog + secret-scanner workflow on every push -- **Static Analysis**: CodeQL on supported languages -- **Supply Chain**: OpenSSF Scorecard (scorecard.yml + scorecard-enforcer.yml) -- **Container Signing**: Ed25519 signatures on all published images (optional: use your signing tool) -- **Container Runtime**: Hardened container runtime with formal verification (optional) -- **Dependency Pinning**: All GitHub Actions SHA-pinned; lockfiles committed -- **Workflow Validation**: workflow-linter.yml checks all workflow changes -- **Security Scanning**: Neurosymbolic scanning (hypatia-scan.yml, optional) -- **Bot Governance**: Bot orchestration with confidence thresholds (optional) -- **Edge Security**: Gateway with policy enforcement (optional, where applicable) -- **SBOM**: Generated and published with releases - -## Residual Risks - -| Risk | Accepted Because | Review Trigger | -|-----------------------------------------------|---------------------------------------------------|-------------------------| -| Zero-day in GitHub Actions runner | Platform responsibility; no feasible mitigation | GitHub advisory | -| Maintainer account compromise | Mitigated by 2FA requirement; residual remains | Any suspicious activity | -| Transitive dependency vulnerability (0-day) | Lockfiles limit blast radius; scanning catches known CVEs | CVE database update | -| SBOM exposes internal component names | Transparency is a design goal | Policy change | - -## Review Schedule - -This threat model should be reviewed: - -- **Quarterly** as a standing item -- **When architecture changes** (new services, new trust boundaries, new deployment targets) -- **Before major releases** (v1.0, v2.0, etc.) -- **After any security incident** affecting this project or its dependencies - -Reviewer should update the "Last Reviewed" date and version in Document Info above. diff --git a/docs/architecture/TOPOLOGY.adoc b/docs/architecture/TOPOLOGY.adoc deleted file mode 100644 index 1319ad6..0000000 --- a/docs/architecture/TOPOLOGY.adoc +++ /dev/null @@ -1,36 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -// Last updated: 2026-04-04 -= Architecture Topology - -== System Overview - -RSR (Rhodium Standard Repository) template provides the canonical scaffold for all hyperpolymath projects, with integrated CI/CD, documentation, and service discovery patterns. - -== Component Overview - -[cols="1,1,2", options="header"] -|=== -| Component | Language | Purpose - -| dogfood-gate workflow | YAML | Quality checks (CRG, security, linting) -| eclexiaiser-validate job | YAML | Resource cost awareness scoring -| Groove discovery | JSON | Service endpoint registration -|=== - -== Data Flow - ----- -[Code Push] → [GitHub Actions] → [hypatia scan] → [eclexiaiser validate] → [Results] ----- - -== Integration Points - -* *Upstream*: Hypatia (neurosymbolic CI/CD), eclexiaiser (resource scoring) -* *Downstream*: All RSR-based repositories (500+ instances) - -== Deployment - -* Container: Stapeln Six ecosystem -* CI/CD: GitHub Actions → Hypatia scan → eclexiaiser-validate (6 scorecard dimensions) → Mirror -* Service Discovery: Groove protocol (.well-known/groove/manifest.json) diff --git a/docs/attribution/0.2-AI-MANIFEST.a2ml b/docs/attribution/0.2-AI-MANIFEST.a2ml deleted file mode 100644 index 52beaea..0000000 --- a/docs/attribution/0.2-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "attribution-unit" -level: 2 -parent: "../0.1-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Sub-unit of the docs pillar focusing on attribution. diff --git a/docs/attribution/CITATION.cff b/docs/attribution/CITATION.cff deleted file mode 100644 index 05d36d9..0000000 --- a/docs/attribution/CITATION.cff +++ /dev/null @@ -1,17 +0,0 @@ -cff-version: 1.2.0 -message: "If you use this software, please cite it as below." -authors: -- family-names: "{{AUTHOR_LAST}}" - given-names: "{{AUTHOR_FIRST}}" - orcid: "https://orcid.org/0000-0000-0000-0000" # Placeholder -title: "{{PROJECT_NAME}}" -version: 0.1.0 -date-released: {{CURRENT_DATE}} -url: "https://{{FORGE}}/{{OWNER}}/{{REPO}}" -repository-code: "https://{{FORGE}}/{{OWNER}}/{{REPO}}" -license: MPL-2.0 -keywords: - - "rsr" - - "formal-verification" - - "neurosymbolic" - - "provenance" diff --git a/docs/attribution/CITATIONS.adoc b/docs/attribution/CITATIONS.adoc deleted file mode 100644 index 3273e53..0000000 --- a/docs/attribution/CITATIONS.adoc +++ /dev/null @@ -1,37 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= {{PROJECT_NAME}} - Citation Guide -:toc: - -== BibTeX - -[source,bibtex] ----- -@software{{{PROJECT_NAME}}_{{CURRENT_YEAR}}, - author = {{{AUTHOR_LAST}}, {{AUTHOR_FIRST}}}, - title = {{{PROJECT_NAME}}}, - year = {{{CURRENT_YEAR}}}, - url = {https://github.com/{{OWNER}}/{{PROJECT_NAME}}}, - license = {MPL-2.0} -} ----- - -== Harvard Style - -{{AUTHOR_LAST}}, {{AUTHOR_INITIALS}} ({{CURRENT_YEAR}}) _{{PROJECT_NAME}}_ [Computer software]. Available at: https://github.com/{{OWNER}}/{{PROJECT_NAME}} - -== OSCOLA - -{{AUTHOR}}, '{{PROJECT_NAME}}' ({{CURRENT_YEAR}}) - -== MLA - -{{AUTHOR_LAST}}, {{AUTHOR_FIRST}} "{{PROJECT_NAME}}." {{CURRENT_YEAR}}, github.com/{{OWNER}}/{{PROJECT_NAME}}. - -== APA 7 - -{{AUTHOR_LAST}}, {{AUTHOR_INITIALS}} ({{CURRENT_YEAR}}). _{{PROJECT_NAME}}_ [Computer software]. GitHub. https://github.com/{{OWNER}}/{{PROJECT_NAME}} - -== See Also - -* link:CITATION.cff[CITATION.cff] diff --git a/docs/attribution/CODEOWNERS.adoc b/docs/attribution/CODEOWNERS.adoc deleted file mode 100644 index 668df01..0000000 --- a/docs/attribution/CODEOWNERS.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Code Ownership -:icons: font - -This project utilizes a formally defined code ownership structure to ensure that specific components are reviewed by domain experts. - -== Authority Model - -Our ownership model is based on the "Perimeter" architecture: -* **Perimeter 1 (Core):** Strictly controlled by Lead Maintainers. -* **Perimeter 2 (Extensions):** Maintained by component owners. -* **Perimeter 3 (Community):** Open for broader community participation. - -== Automated Enforcement - -The technical rules for automatic review assignments are maintained in the machine-readable link:../../.github/CODEOWNERS[.github/CODEOWNERS] file. GitHub uses this to automatically notify owners when changes are proposed to their sections. - -== Component Owners - -A full list of maintainers and their contact information can be found in link:MAINTAINERS.adoc[MAINTAINERS.adoc]. diff --git a/docs/attribution/MAINTAINERS.adoc b/docs/attribution/MAINTAINERS.adoc deleted file mode 100644 index c5a4b31..0000000 --- a/docs/attribution/MAINTAINERS.adoc +++ /dev/null @@ -1,48 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Maintainers -:toc: preamble - -This document lists the maintainers of this project and their responsibilities. - -== Current Maintainers - -[cols="2,3,2",options="header"] -|=== -| Name | Role | Contact - -| {{AUTHOR}} -| Lead Maintainer -| https://github.com/{{OWNER}}[@{{OWNER}}] -|=== - -== Responsibilities - -Maintainers are responsible for: - -* 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 - -Contributors who demonstrate: - -* Consistent, high-quality contributions -* Understanding of the project's goals and standards -* Constructive participation in discussions -* Commitment to the project's long-term health - -May be invited to become maintainers at the discretion of existing maintainers. - -== Decision Making - -* 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 - -== Contact - -For questions about project governance, open an issue or contact the maintainers listed above. diff --git a/docs/attribution/README.adoc b/docs/attribution/README.adoc deleted file mode 100644 index 2e50721..0000000 --- a/docs/attribution/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= attribution Unit diff --git a/docs/decisions/0.2-AI-MANIFEST.a2ml b/docs/decisions/0.2-AI-MANIFEST.a2ml deleted file mode 100644 index ac26298..0000000 --- a/docs/decisions/0.2-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "decisions-unit" -level: 2 -parent: "../0.1-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Sub-unit of the docs pillar focusing on decisions. diff --git a/docs/decisions/0000-template.adoc b/docs/decisions/0000-template.adoc deleted file mode 100644 index 07c5453..0000000 --- a/docs/decisions/0000-template.adoc +++ /dev/null @@ -1,37 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Architecture Decision Record: 0000-template - - - -# [NUMBER]. [TITLE] - -Date: YYYY-MM-DD - -## Status - -[Proposed | Accepted | Deprecated | Superseded by [ADR-NNNN](NNNN-title.md) | Rejected] - -## Context - -What is the issue that we're seeing that is motivating this decision or change? - -## Decision - -What is the change that we're proposing and/or doing? - -## Consequences - -What becomes easier or more difficult to do because of this change? - -### Positive - -- ... - -### Negative - -- ... - -### Neutral - -- ... diff --git a/docs/decisions/0001-adopt-rsr-standard.adoc b/docs/decisions/0001-adopt-rsr-standard.adoc deleted file mode 100644 index 7a4fd26..0000000 --- a/docs/decisions/0001-adopt-rsr-standard.adoc +++ /dev/null @@ -1,88 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Architecture Decision Record: 0001-adopt-rsr-standard - - - -# 1. Adopt Rhodium Standard Repository (RSR) Template - -Date: 2026-02-14 - -## Status - -Accepted - -## Context - -Managing multiple repositories with an ad-hoc approach led to significant -inconsistencies across the ecosystem. Common problems included: - -- Missing or incomplete configuration files (SECURITY.md, CONTRIBUTING.md, - .editorconfig, etc.) -- State files (STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml) placed in the repository - root instead of the canonical `.machine_readable/` directory -- Duplicate or conflicting workflow definitions across repos -- No standardized entry point for AI agents interacting with repositories -- Inconsistent bot directive configurations leading to unreliable automation -- No contractile enforcement or Justfile automation - -Without a single source of truth for repository structure, each new repo -required manual setup and inevitably drifted from best practices over time. - -## Decision - -Adopt the Rhodium Standard Repository (RSR) template (`rsr-template-repo`) as -the canonical starting point for all new repositories. Existing repositories -will migrate incrementally as they receive active development. - -The RSR template provides: - -- **Machine-readable state files** in `.machine_readable/` (STATE.a2ml, - ECOSYSTEM.a2ml, META.a2ml, AGENTIC.a2ml, NEUROSYM.a2ml, PLAYBOOK.a2ml) -- **AI manifest** (`0-AI-MANIFEST.a2ml`) as a universal entry point for all - AI agents -- **Bot directives** in `.machine_readable/bot_directives/` for bot orchestration integration -- **Contractiles** in `.machine_readable/contractiles/` (k9, dust, intend, must, trust) for - policy enforcement -- **Standardized workflows** (16+ GitHub Actions workflows, all SHA-pinned) -- **Justfile automation** with standard recipes for common tasks -- **Security and governance files**: SECURITY.md, CONTRIBUTING.md, - CODE_OF_CONDUCT.md, LICENSE (MPL-2.0) -- **Architecture Decision Records** in `docs/decisions/` - -New repositories are created by cloning the template: - -```bash -git clone https://github.com/{{OWNER}}/rsr-template-repo new-repo-name -cd new-repo-name -rm -rf .git && git init -``` - -## Consequences - -### Positive - -- Consistency across all repositories, enforced from creation -- Automated compliance checking via `rsr-antipattern.yml` workflow -- Bot fleet can operate reliably across all repos with predictable structure -- AI agents (Claude, Gemini, etc.) have a standardized entry point via - `0-AI-MANIFEST.a2ml` -- New contributors can onboard faster with familiar, documented structure -- Reduced maintenance burden: fix once in template, propagate to all repos -- Machine-readable state enables tooling and automation pipelines - -### Negative - -- Migration effort for existing repos requires time and attention -- Learning curve for contributors unfamiliar with RSR conventions -- Template updates need propagation mechanism to existing repos -- Some repos may have unique needs that do not fit the standard template - without customization - -### Neutral - -- Existing CI/CD pipelines continue to work; RSR workflows are additive -- Third-party dependencies retain their original licenses regardless of - repo structure -- ADR process itself is part of the template, enabling future decisions - to be recorded consistently diff --git a/docs/decisions/README.adoc b/docs/decisions/README.adoc deleted file mode 100644 index af174f5..0000000 --- a/docs/decisions/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= decisions Unit diff --git a/docs/developer/0.2-AI-MANIFEST.a2ml b/docs/developer/0.2-AI-MANIFEST.a2ml deleted file mode 100644 index c16fcc7..0000000 --- a/docs/developer/0.2-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "developer-unit" -level: 2 -parent: "../0.1-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Sub-unit of the docs pillar focusing on developer. diff --git a/docs/developer/ABI-FFI-README.adoc b/docs/developer/ABI-FFI-README.adoc deleted file mode 100644 index 08d2a72..0000000 --- a/docs/developer/ABI-FFI-README.adoc +++ /dev/null @@ -1,386 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= ABI/FFI Standards -{{~ Aditionally delete this line and fill out the template below ~}} - -# {{PROJECT}} ABI/FFI Documentation - -## Overview - -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 - -## Architecture - -``` -┌─────────────────────────────────────────────┐ -│ ABI Definitions (Idris2) │ -│ src/abi/ │ -│ - Types.idr (Type definitions) │ -│ - Layout.idr (Memory layout proofs) │ -│ - Foreign.idr (FFI declarations) │ -└─────────────────┬───────────────────────────┘ - │ - │ generates (at compile time) - ▼ -┌─────────────────────────────────────────────┐ -│ C Headers (auto-generated) │ -│ generated/abi/{{project}}.h │ -└─────────────────┬───────────────────────────┘ - │ - │ imported by - ▼ -┌─────────────────────────────────────────────┐ -│ FFI Implementation (Zig) │ -│ ffi/zig/src/main.zig │ -│ - Implements C-compatible functions │ -│ - Zero-cost abstractions │ -│ - Memory-safe by default │ -└─────────────────┬───────────────────────────┘ - │ - │ compiled to lib{{project}}.so/.a - ▼ -┌─────────────────────────────────────────────┐ -│ Any Language via C ABI │ -│ - Rust, ReScript, Julia, Python, etc. │ -└─────────────────────────────────────────────┘ -``` - -## Directory Structure - -``` -{{project}}/ -├── src/ -│ ├── abi/ # ABI definitions (Idris2) -│ │ ├── Types.idr # Core type definitions with proofs -│ │ ├── Layout.idr # Memory layout verification -│ │ └── Foreign.idr # FFI function declarations -│ └── lib/ # Core library (any language) -│ -├── ffi/ -│ └── zig/ # FFI implementation (Zig) -│ ├── build.zig # Build configuration -│ ├── build.zig.zon # Dependencies -│ ├── src/ -│ │ └── main.zig # C-compatible FFI implementation -│ ├── test/ -│ │ └── integration_test.zig -│ └── include/ -│ └── {{project}}.h # C header (optional, can be generated) -│ -├── generated/ # Auto-generated files -│ └── abi/ -│ └── {{project}}.h # Generated from Idris2 ABI -│ -└── bindings/ # Language-specific wrappers (optional) - ├── rust/ - ├── rescript/ - └── julia/ -``` - -## Why Idris2 for ABI? - -### 1. **Formal Verification** - -Idris2's dependent types allow proving properties about the ABI at compile-time: - -```idris --- Prove struct size is correct -public export -exampleStructSize : HasSize ExampleStruct 16 - --- Prove field alignment is correct -public export -fieldAligned : Divides 8 (offsetOf ExampleStruct.field) - --- Prove ABI is platform-compatible -public export -abiCompatible : Compatible (ABI 1) (ABI 2) -``` - -### 2. **Type Safety** - -Encode invariants that C/Zig cannot express: - -```idris --- Non-null pointer guaranteed at type level -data Handle : Type where - MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle - --- Array with length proof -data Buffer : (n : Nat) -> Type where - MkBuffer : Vect n Byte -> Buffer n -``` - -### 3. **Platform Abstraction** - -Platform-specific types with compile-time selection: - -```idris -CInt : Platform -> Type -CInt Linux = Bits32 -CInt Windows = Bits32 - -CSize : Platform -> Type -CSize Linux = Bits64 -CSize Windows = Bits64 -``` - -### 4. **Safe Evolution** - -Prove that new ABI versions are backward-compatible: - -```idris --- Compiler enforces compatibility -abiUpgrade : ABI 1 -> ABI 2 -abiUpgrade old = MkABI2 { - -- Must preserve all v1 fields - v1_compat = old, - -- Can add new fields - new_features = defaults -} -``` - -## Why Zig for FFI? - -### 1. **C ABI Compatibility** - -Zig exports C-compatible functions naturally: - -```zig -export fn library_function(param: i32) i32 { - return param * 2; -} -``` - -### 2. **Memory Safety** - -Compile-time safety without runtime overhead: - -```zig -// Null check enforced at compile time -const handle = init() orelse return error.InitFailed; -defer free(handle); -``` - -### 3. **Cross-Compilation** - -Built-in cross-compilation to any platform: - -```bash -zig build -Dtarget=x86_64-linux -zig build -Dtarget=aarch64-macos -zig build -Dtarget=x86_64-windows -``` - -### 4. **Zero Dependencies** - -No runtime, no libc required (unless explicitly needed): - -```zig -// Minimal binary size -pub const lib = @import("std"); -// Only includes what you use -``` - -## Building - -### Build FFI Library - -```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 - -```bash -cd src/abi -idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` - -### Cross-Compile - -```bash -cd ffi/zig - -# Linux x86_64 -zig build -Dtarget=x86_64-linux - -# macOS ARM64 -zig build -Dtarget=aarch64-macos - -# Windows x86_64 -zig build -Dtarget=x86_64-windows -``` - -## Usage - -### From C - -```c -#include "{{project}}.h" - -int main() { - void* handle = {{project}}_init(); - if (!handle) return 1; - - int result = {{project}}_process(handle, 42); - if (result != 0) { - const char* err = {{project}}_last_error(); - fprintf(stderr, "Error: %s\n", err); - } - - {{project}}_free(handle); - return 0; -} -``` - -Compile with: -```bash -gcc -o example example.c -l{{project}} -L./zig-out/lib -``` - -### From Idris2 - -```idris -import {{PROJECT}}.ABI.Foreign - -main : IO () -main = do - Just handle <- init - | Nothing => putStrLn "Failed to initialize" - - Right result <- process handle 42 - | Left err => putStrLn $ "Error: " ++ errorDescription err - - free handle - putStrLn "Success" -``` - -### From Rust - -```rust -#[link(name = "{{project}}")] -extern "C" { - fn {{project}}_init() -> *mut std::ffi::c_void; - fn {{project}}_free(handle: *mut std::ffi::c_void); - fn {{project}}_process(handle: *mut std::ffi::c_void, input: u32) -> i32; -} - -fn main() { - unsafe { - let handle = {{project}}_init(); - assert!(!handle.is_null()); - - let result = {{project}}_process(handle, 42); - assert_eq!(result, 0); - - {{project}}_free(handle); - } -} -``` - -### From Julia - -```julia -const lib{{project}} = "lib{{project}}" - -function init() - handle = ccall((:{{project}}_init, lib{{project}}), Ptr{Cvoid}, ()) - handle == C_NULL && error("Failed to initialize") - handle -end - -function process(handle, input) - result = ccall((:{{project}}_process, lib{{project}}), Cint, (Ptr{Cvoid}, UInt32), handle, input) - result -end - -function cleanup(handle) - ccall((:{{project}}_free, lib{{project}}), Cvoid, (Ptr{Cvoid},), handle) -end - -# Usage -handle = init() -try - result = process(handle, 42) - println("Result: $result") -finally - cleanup(handle) -end -``` - -## Testing - -### Unit Tests (Zig) - -```bash -cd ffi/zig -zig build test -``` - -### Integration Tests - -```bash -cd ffi/zig -zig build test-integration -``` - -### ABI Verification (Idris2) - -```idris --- Compile-time verification -%runElab verifyABI - --- Runtime checks -main : IO () -main = do - verifyLayoutsCorrect - verifyAlignmentsCorrect - putStrLn "ABI verification passed" -``` - -## 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 - -{{LICENSE}} - -## See Also - -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/{{OWNER}}/rhodium-standard-repositories) diff --git a/docs/developer/README.adoc b/docs/developer/README.adoc deleted file mode 100644 index 2b328b4..0000000 --- a/docs/developer/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= developer Unit diff --git a/docs/governance/0.1-AI-MANIFEST.a2ml b/docs/governance/0.1-AI-MANIFEST.a2ml deleted file mode 100644 index 6e373bd..0000000 --- a/docs/governance/0.1-AI-MANIFEST.a2ml +++ /dev/null @@ -1,21 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "governance-pillar" -level: 1 -parent: "../0-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Primary governance pillar implementing the Triaxial Software Development - Methodology (TSDM). Contains planning, maintenance, and audit tracks. - -canonical_locations: - tsdm_spec: "TSDM.adoc" - planning: "planning/" - maintenance: "maintenance/" - audit: "audit/" - crg: "CRG-CRITERIA.adoc" - checklist: "MAINTENANCE-CHECKLIST.adoc" - approach: "SOFTWARE-DEVELOPMENT-APPROACH.adoc" diff --git a/docs/governance/CRG-AUDIT-TEMPLATE.adoc b/docs/governance/CRG-AUDIT-TEMPLATE.adoc deleted file mode 100644 index b409104..0000000 --- a/docs/governance/CRG-AUDIT-TEMPLATE.adoc +++ /dev/null @@ -1,288 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= {{PROJECT_NAME}} — CRG Audit ({{CURRENT_DATE}}) -{{AUTHOR}} -{{CURRENT_DATE}} -:toc: -:sectnums: - -// USAGE -// ----- -// Copy this file to `docs/governance/CRG-AUDIT-YYYY-MM-DD.adoc` in the target -// repo, replace the {{PLACEHOLDER}} tokens, and fill every section with -// *verified-today* evidence. Do not leave "TODO" or "tbd" in a finished audit. -// Worked example of a completed audit: boj-server/docs/governance/CRG-AUDIT-2026-04-18.adoc -// -// The audit must grade the repo *as-is today*, not aspirationally. Per CRG v2.0: -// "honest D > dishonest B". - -== Scope and Standard - -Evaluates the `{{REPO}}` repository against -*Component Readiness Grades v2.0 (STRICT)*, 2026-03-30 revision. - -- Standard: `standards/component-readiness-grades/COMPONENT-READINESS-GRADES.md` -- Template (criteria boilerplate): `rsr-template-repo/docs/governance/CRG-CRITERIA.adoc` -- Self-declared grade (prior art): - * `.machine_readable/6a2/STATE.a2ml` → `grade = ""` - * `docs/READINESS.md` (if present) → per-component grades - * Third-party badges (Glama, OpenSSF, etc.) if any — note date and scope -- Audit date: {{CURRENT_DATE}} -- Auditor: {{AUTHOR}} - -The audit grades the repo *as-is today*, not aspirationally. - -== v2.0 Strictness Recap - -[cols="1,3,4"] -|=== -| Grade | Release Stage | Hard Requirement (v2.0) - -| X | None | Untested. -| F | Reject | Harmful, wasteful, or superseded. -| E | Pre-alpha | >=1 test, failures documented. -| D | Alpha | Test matrix + scope documented + *RSR compliance mandatory*. -| C | Alpha-stable | Dogfooded, CI green, *deep per-file + per-directory annotation*. -| B | Beta | 6+ *diverse* external targets, issues fed back. -| A | Stable | Real-world external feedback confirms value; no harm. -|=== - -Publication requires B+. Long alpha is discipline, not shame. - -== Evidence Inventory (verified {{CURRENT_DATE}}) - -=== Structural compliance (Grade D floor) - -List every RSR-mandated artefact with PRESENT/ABSENT and the concrete source. -Do *not* mark PRESENT without citing the path. - -[cols="2,1,3"] -|=== -| Item | State | Source - -| RSR mandatory workflows (17+) -| PRESENT / PARTIAL (count) / ABSENT -| `.github/workflows/` - -| `.machine_readable/6a2/` canonical A2ML -| PRESENT (STATE, META, ECOSYSTEM, AGENTIC, NEUROSYM, PLAYBOOK) / ABSENT -| Layout matches CLAUDE.md invariant - -| `0-AI-MANIFEST.a2ml` -| PRESENT / ABSENT -| Root - -| `docs/EXPLAINME.adoc`, `docs/READINESS.md`, `docs/RSR_OUTLINE.adoc` -| PRESENT / PARTIAL / ABSENT -| `docs/` - -| `guix.scm` + `flake.nix` -| PRESENT (primary + fallback) / PARTIAL / ABSENT -| Root - -| `.well-known/` (security.txt, ai.txt, humans.txt) -| PRESENT / ABSENT -| Per RSR_OUTLINE.adoc - -| SPDX headers on source -| PRESENT on sampled files (N/N) / PARTIAL / ABSENT -| `LICENSE`, `LICENSE-MPL-2.0` fallback text - -| `Containerfile` (not `Dockerfile`) -| PRESENT / N/A (no container) / VIOLATION (Dockerfile found) -| Container policy - -| Contractile trident -| PRESENT (`INTENT.contractile`, `TRUST.contractile`, `MUST.contractile`, `ADJUST.contractile`) / PARTIAL / ABSENT -| `.machine_readable/` - -| `Justfile` + `Mustfile` (no `Makefile`) -| PRESENT / VIOLATION (Makefile found) -| Build-system policy (RSR R-020) - -| Remote -| `git@{{FORGE}}:{{OWNER}}/{{REPO}}.git` (origin only) / drift -| `git remote -v` -|=== - -RSR compliance verdict: *met* / *partial* / *not met* — Grade D floor satisfied? Yes/No. - -=== Code and proofs - -[cols="2,1,3"] -|=== -| Item | Count | Notes - -| Idris2 ABI modules (`src/abi/**/*.idr`) -| N files, N LOC -| Note any proof modules that typecheck green. - -| Zig FFI modules (`ffi/zig/src/*.zig`) -| N files, N LOC -| Call out largest modules. - -| <> (e.g. cartridges, panels, plugins) -| N directories/files -| Link to manifest. - -| Axiomatic `believe_me` sites -| N irreducible -| Each must have a file-header note justifying it as a documented primitive. - -| Non-axiomatic `believe_me` -| N (should be 0 for C) -| Reference the sweep commit and date. - -| Dangerous-pattern scan (`assert_total`, `Admitted`, `sorry`, `unsafeCoerce`, `Obj.magic`) -| N -| Grepped {{CURRENT_DATE}}. -|=== - -=== Test matrix - -Cite *from authoritative source* (STATE.a2ml or CI log). Do not re-count by -filesystem grep — grade the evidence that already exists. - -- `total-tests = N` (from `.machine_readable/6a2/STATE.a2ml` or CI). -- Breakdown by suite: list each named suite and its count. -- CI: `.github/workflows/.yml` runs on push / tag / schedule. -- Last green run: date + commit SHA. - -=== Annotation depth - -v2.0 C requires **per-file and per-directory orientation**. Evidence checklist: - -- Per-directory orientation docs: which `docs/` subtrees exist - (`docs/architecture/`, `docs/decisions/`, `docs/integration/`, - `docs/specification/`, `docs/wiki/`) and their file counts. -- Per-<> README coverage: *M of N* (percentage). M of N that lack - a README is the single biggest tell for C-readiness. Anything below - ~90% coverage fails the "deep per-file annotation" clause. -- Per-module inline docs: sample-audit the largest/most-important modules - and note whether purpose comments, invariants, and boundary conditions - are documented. -- Per-subtree README: which non-trivial source subtrees lack an orienting - README (e.g. `/`, `.machine_readable/`, `ffi/zig/src/`). - -=== Dogfooding / home-stable evidence - -Cite STATE.a2ml `[dogfooding-status]`. For each line item: -- WHAT was dogfooded (capability), -- HOW (concrete use-path), -- WHEN (date completed), -- WHERE (link to commit / artefact / deployment). - -- <> — <>. DONE / IN-PROGRESS / PLANNED. -- <> — … -- <> — … -- LIVE deployment (if any): URL, health signal, last verified. - -=== External validation (Grade B / A) - -Distinguish carefully — v2.0 B requires **real external users with feedback**, -not catalogue listings. Populate the canonical STATE.a2ml sections named -below; internal-capability items belong under `[grade-b-status]` (legacy) or -a roadmap section, *not* under `[external-targets]`. - -- STATE.a2ml `[external-targets]` — at least 6 diverse entries for B. - Target identity + date + outcome for each. If absent, grade is capped at C. -- STATE.a2ml `[issues-fed-back]` — closed-issue trail with external-reporter - label for B. -- STATE.a2ml `[field-signal]` — multi-source external confirmation for A. -- Awesome-list PRs merged (N). *Catalogue listings, not dogfooders.* -- Directory/registry listings (MCP directory, Glama, etc.) with automated - assessment badges — *third-party automated assessment, not external usage*. -- Seeded/reference nodes: configured but not yet run by third parties. - -NOTE: Legacy `[grade-b-status]` sections (pre-2026-04-18) often mix internal -capabilities with external targets. During audit, re-classify each entry -and either move it to `[external-targets]` or drop it. See the boj-server -audit for a worked example (six items all re-classified as internal). - -== Grade x Evidence Matrix - -[cols="1,1,3,3"] -|=== -| Grade | Met? | Evidence supporting | Evidence against / gaps - -| X -| n/a -| Tests exist -> not X -| — - -| F -| n/a -| Not superseded; no harm signal -| — - -| E -| ✓/✗ -| ... -| ... - -| D -| ✓/✗ -| All RSR structural requirements met; N tests; scope documented in STATE.a2ml, ROADMAP.adoc -| ... - -| C -| ✓/✗ -| Home-stable; CI green; core dogfood demonstrated across N capability lines; deep annotation present for core and architecture docs. -| Per-<> README coverage M/N. Per-directory orientation gaps. READINESS.md schema version. Dogfood-sweep log. - -| B -| ✓/✗ -| — -| N external targets (need 6+). External users. Issues-fed-back pipeline. - -| A -| ✓/✗ -| — -| Field signal of external confirmation. -|=== - -== Verdict - -*Current CRG grade: **<> (<>)**.* - -State how this matches / diverges from the self-declared grade. v2.0 -strictness clause: does stricter evidence standard change the outcome? - -The grade is earned, not conservative-by-default — list the three strongest -*positive* signals: - -1. <> -2. <> -3. <> - -What blocks *immediate* promotion to <>: - -1. <> -2. <> -3. <> - -What blocks promotion to the grade after that: - -1. <> -2. <> - -== Notes on Non-Negotiables Respected by this Audit - -List irreducible / intentional exceptions so future audits don't retread -them. Examples: - -- Documented axiomatic `believe_me` sites at `` are backend primitives, - not proof debt. -- Proof closures declared "done" (e.g. credential-isolation modules) are not - re-audited here. -- Standing rules (e.g. januskey, private-repo exceptions) are respected. - -== Related Files - -- `docs/READINESS.md` — per-component table. Note v1.0-vs-v2.0 schema alignment. -- `.machine_readable/6a2/STATE.a2ml` — authoritative self-declared state. -- `docs/governance/CRG-LIFT-PLAN-{{CURRENT_DATE}}.adoc` — companion plan for - D→C (and medium-term C→B) lifts. -- `docs/governance/CRG-CRITERIA.adoc` — boilerplate criteria doc. - -_End of audit._ diff --git a/docs/governance/CRG-CRITERIA.a2ml b/docs/governance/CRG-CRITERIA.a2ml deleted file mode 100644 index 6162585..0000000 --- a/docs/governance/CRG-CRITERIA.a2ml +++ /dev/null @@ -1,108 +0,0 @@ -; SPDX-License-Identifier: MPL-2.0 -; Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) - -; Component Readiness Grades (CRG) — Machine-readable specification -; Format: A2ML (AI-to-Machine Language) -; Standard: CRG v1.0 - -(standard - (name "Component Readiness Grades") - (abbreviation "CRG") - (version "1.0") - (date "2026-02-28") - (author "Jonathan D.A. Jewell ") - (license "MPL-2.0") - (family "RSR")) - -(grades - (grade - (code X) - (name "Untested") - (release-stage #f) - (ordinal 0) - (description "No testing has been performed. Status unknown.") - (evidence-required "none") - (minimum-for #f)) - (grade - (code F) - (name "Harmful / Wasteful") - (release-stage #f) - (ordinal 1) - (description "Actively harmful, wasteful, or better handled externally. Reject, deprecate, or delegate.") - (evidence-required "documented test results showing harm, waste, or redundancy; comparison with alternatives") - (minimum-for #f)) - (grade - (code E) - (name "Minimal / Salvageable") - (release-stage "pre-alpha") - (ordinal 2) - (description "Does something slight. Barely functional. Needs redesign or major work.") - (evidence-required "at least one successful test case; documented failures and limitations") - (minimum-for #f)) - (grade - (code D) - (name "Partial / Inconsistent") - (release-stage "alpha") - (ordinal 3) - (description "Works on some things but not systematically.") - (evidence-required "matrix of tested scenarios; documented scope vs actual capabilities") - (minimum-for "alpha")) - (grade - (code C) - (name "Self-Validated") - (release-stage "beta") - (ordinal 4) - (description "Tested on the tool/project itself (dogfooding). Reliable in home context.") - (evidence-required "active dogfooding; CI integration or equivalent; no known failures in home context") - (minimum-for "beta")) - (grade - (code B) - (name "Broadly Validated") - (release-stage "release-candidate") - (ordinal 5) - (description "Tested on at least 6 disparate, unrelated targets.") - (evidence-required "list of 6+ diverse targets with test results; evidence of feedback incorporation") - (minimum-for "release-candidate")) - (grade - (code A) - (name "Field-Proven") - (release-stage "stable") - (ordinal 6) - (description "Real-world external feedback confirms value. Does no harm in the wild.") - (evidence-required "real-world usage data; feedback incorporation evidence; no unresolved harm reports") - (minimum-for "stable"))) - -(transitions - (promotion - (from X) (to E) (requirement "Run at least one test. Document results.")) - (promotion - (from X) (to F) (requirement "Evaluate and determine harmful or wasteful.")) - (promotion - (from E) (to D) (requirement "Fix critical failures. Document scope.")) - (promotion - (from D) (to C) (requirement "Dogfood on own project. Fix what breaks.")) - (promotion - (from C) (to B) (requirement "Test on 6+ diverse external targets. Fix what breaks.")) - (promotion - (from B) (to A) (requirement "Ship. Collect external feedback. Demonstrate no harm.")) - (demotion - (from A) (to B) (trigger "External feedback dries up or reveals no longer useful.")) - (demotion - (from A) (to F) (trigger "External feedback reveals component causes harm.")) - (demotion - (from B) (to C) (trigger "Broad validation reveals unfixed failures.")) - (demotion - (from C) (to D) (trigger "Home context changes and component no longer reliable.")) - (demotion - (from C) (to F) (trigger "Dogfooding reveals net negative.")) - (demotion - (from D) (to E) (trigger "Scope narrows to barely functional.")) - (demotion - (from any) (to F) (trigger "Better external alternative makes this pure opportunity cost."))) - -(conformance - (rule "Each assessable component MUST have a grade from {X, F, E, D, C, B, A}.") - (rule "Each grade above X MUST be supported by evidence per section 4.") - (rule "Assessments MUST be recorded in a version-controlled location.") - (rule "Assessments MUST be reviewed at least once per release cycle.") - (rule "Release stages MUST respect minimum grade thresholds.")) diff --git a/docs/governance/CRG-CRITERIA.adoc b/docs/governance/CRG-CRITERIA.adoc deleted file mode 100644 index 926df5a..0000000 --- a/docs/governance/CRG-CRITERIA.adoc +++ /dev/null @@ -1,41 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Component Readiness Grades (CRG) Criteria -:toc: preamble -:icons: font - -This document defines the quality assessment criteria for individual project components. - -== Grade Definitions - -[cols="1,2,3,4",options="header"] -|=== -| Grade | Name | Release Stage | Meaning - -| **A** | Field-Proven | Stable | Real-world feedback amassed; no harm in wild. -| **B** | Broadly Validated | Release Candidate | Tested on 6+ diverse external targets. -| **C** | Self-Validated | Beta | Reliable in home context (dogfooded). -| **D** | Partial | Alpha | Works on some inputs/cases but not systematically. -| **E** | Minimal | Pre-alpha | Barely functional; needs major work. -| **F** | Harmful/Wasteful | Reject/Delegate | Redundant or negative value. -| **X** | Untested | — | Status completely unknown. -|=== - -== Core Principles - -1. **Assess components, not projects:** Each feature gets its own grade. -2. **Evidence over intuition:** Every grade above X requires documented evidence. -3. **Honest assessment:** Grade the component as it is today, not as you hope it will be. -4. **Grades are earned and can be lost:** Regressions lead to demotion. - -== Assessment Checklist - -1. Has it been tested at all? (No → **X**) -2. Does it cause harm or duplicate something better? (Yes → **F**) -3. Does it do something, however slight? (Barely → **E**) -4. Does it work on some things but not others? (Partial → **D**) -5. Does it work reliably on our own project? (Dogfooded → **C**) -6. Has it been tested on 6+ diverse external targets? (Broad → **B**) -7. Do external users confirm it works and is useful? (Field-proven → **A**) - -See link:READINESS.adoc[READINESS.adoc] for the current project assessment. diff --git a/docs/governance/MAINTENANCE-CHECKLIST.adoc b/docs/governance/MAINTENANCE-CHECKLIST.adoc deleted file mode 100644 index 6853378..0000000 --- a/docs/governance/MAINTENANCE-CHECKLIST.adoc +++ /dev/null @@ -1,571 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Maintenance Checklist -# Maintenance Checklist (Cross-Repo) - -Use this as a repeatable maintenance runbook for any repo. - -Companion policy: - -- `docs/practice/SOFTWARE-DEVELOPMENT-APPROACH.adoc` (human-readable) -- `.machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml` (machine-readable) - -## Canonical Repo Baseline (Final) - -Apply this baseline to every repo unless an explicit exception is recorded. - -### Three-Axis Default Model - -- [ ] Axis 1 (scope priority, runs first): `must > intend > like` -- [ ] Axis 2 (maintenance priority): `corrective > adaptive > perfective` -- [ ] Axis 3 (audit priority): `systems > compliance > effects` -- [ ] Perfective items are derived from Axis 1 honest state (not started independently). - -### Axis 1 Scoping Pass (Mandatory) - -Before Axis 2/3 execution, assemble a scoped worklist from evidence: - -- [ ] Read and reconcile: `README`, roadmap, status docs, maintenance checklist, and current CI/security docs. -- [ ] Scan for unfinished markers: `TODO`, `FIXME`, `XXX`, `HACK`, `STUB`, `PARTIAL`. -- [ ] If Idris is present, scan unsoundness markers: `believe_me`, `assert_total`. -- [ ] Identify declared intent vs actual implementation (docs honesty check). -- [ ] Produce a scope assembly artifact with prioritized entries under: - - `must` (release blockers / safety / correctness) - - `intend` (planned near-term) - - `like` (nice-to-have) - -### Axis 2 Maintenance Execution Rules - -- [ ] Corrective first: fix breakage, defects, regressions, safety issues. -- [ ] Adaptive second: reconcile changed scope, remove stale references, cull no-longer-relevant work. -- [ ] Perfective third: only from current honest state established by Axis 1 and updated by corrective/adaptive actions. - -### Axis 3 Audit Rules - -- [ ] Verify systems are in place and actually operating. -- [ ] Verify documentation explains the real/current state (not aspirational-only), including documented exceptions. -- [ ] Verify safety and security controls are present, active, and evidenced. -- [ ] Verify observed effects/impacts are captured and reviewed. -- [ ] Effects audit includes: - - benchmark execution and recorded results (with before/after where relevant) - - explicit maintainer dialogue/status review on what changed, why, and next risks -- [ ] Audit compliance seams/compromises explicitly: - - policy exceptions are recorded with rationale, scope, and expiry/review - - exception does not silently broaden into general policy drift - - language-policy contamination checks run (example: a single TS exception must not trigger broad TypeScript conversion) - - run `panic-attack` as the compliance-audit scanner - - run ecological checking under effects (using sustainabot guidance as current baseline) - -### Generic Cleanup And Finish-Off Pass - -Run this pass at the end of a corrective/adaptive/perfective cycle: - -- [ ] Root cleanup: - - keep only required control/entry files in root - - move non-essential docs/reports/fixtures to canonical folders -- [ ] Remove or archive stale work: - - close out completed TODO/STUB/PARTIAL items - - cull obsolete references, dead files, and superseded plans -- [ ] Documentation finish-off: - - ensure README, roadmap, status, and wiki match actual implementation state - - ensure machine-readable policy/state files match human docs -- [ ] Security/compliance finish-off: - - run compliance scanner (`panic-attack`) and resolve high-priority findings - - verify exception register and seams/compromises are explicitly bounded -- [ ] Effects finish-off: - - run benchmark/effects checks and record evidence - - conduct explicit maintainer review dialogue (what changed, why, remaining risks) -- [ ] Release-prep finish-off: - - produce Must/Should/Could summary - - produce immediate corrective/adaptive/perfective next-actions list - -### Must - -- [ ] Keep required control files at repository root: - - `.gitignore`, `.gitattributes`, `.editorconfig`, `.tool-versions` - - `Containerfile` - - `.containerignore` (or `.dockerignore` only when required for compatibility) - - `CNAME` and `.nojekyll` when using GitHub Pages/custom domain - - `Justfile` (root by convention) -- [ ] Keep ownership/governance files present: - - `MAINTAINER` in root - - `.github/CODEOWNERS` -- [ ] Keep machine-readable canonical structure under `.machine_readable/`: - - state/meta/ecosystem files (`*.a2ml` or repo standard) - - `anchors/ANCHOR.a2ml` - - `contractiles/` (`must`, `trust`, `intend`, and related) - - `ai/` for AI guidance files - - `bot_directives/` for bot control files -- [ ] Keep contractiles/invariants present and wired: - - root `Mustfile` (or equivalent) with enforceable checks - - `Trustfile` and `Intentfile` present -- [ ] Keep security metadata present: - - `.well-known/security.txt` and relevant policy metadata - - CI security scanning configured and runnable -- [ ] Keep docs and navigation coherent: - - single navigation entry point in root (`NAVIGATION.adoc` or equivalent) - - no duplicate conflicting docs for same purpose (for example both `.md` and `.adoc` in root unless intentionally required) -- [ ] Enforce ABI/FFI purity where the policy applies: - - ABI definitions in Idris2 (`src/abi/*.idr`) - - FFI implementations in Zig (`ffi/**/*.zig`) -- [ ] Ensure quality gate includes: formatting, lint, unit/integration tests, p2p/e2e checks, benchmark smoke, docs checks, security scan. - -### Should - -- [ ] Keep human docs primarily in AsciiDoc (`.adoc`) except where ecosystem rules require other formats (GitHub/community health, legal text, tool-specific files). -- [ ] Keep non-essential root files moved into structured folders: - - `docs/` (theory/practice/whitepapers/proofs/reports) - - `tests/` (fixtures/outputs) - - `docs/legal/` (while retaining root `LICENSE` when forge detection needs it) -- [ ] Maintain `.well-known/` for public metadata where applicable (`security.txt`, `humans.txt`, `ads.txt` mirrors if used). -- [ ] Keep CI policy checks for doc-format conventions and canonical file placement. -- [ ] Keep roadmap/status docs honest with dated evidence. - -### Could - -- [ ] Maintain both human and machine views of maintenance policy from a single source (generate one from the other). -- [ ] Add policy bots for corrective/adaptive/perfective/audit modes. -- [ ] Add repo-level architecture map (`TOPOLOGY.md`) and release-readiness dashboards. -- [ ] Add per-repo exception registry for approved policy deviations. - -### Explicit Root-Placement Rule - -Do **not** move the following out of root if you want default tool behavior: - -- `.gitignore`, `.gitattributes`, `.editorconfig`, `.tool-versions` -- `Containerfile` and ignore file (`.containerignore`/`.dockerignore`) -- `CNAME` and `.nojekyll` for GitHub Pages -- `Justfile` - -## Quick Automated Run (Script) - -Use the helper script first, then use the checklist for deeper/manual follow-up. - -Script locations: -- `${REPOS_ROOT:-~/Documents/hyperpolymath-repos}/run-maintenance.sh` -- `~/Desktop/run-maintenance.sh` - -```bash -~/Desktop/run-maintenance.sh --repo /absolute/path/to/repo --output /tmp/maintenance-report.json -jq . /tmp/maintenance-report.json -``` - -Useful flags: - -```bash -# Strict mode: fail process on failed checks -~/Desktop/run-maintenance.sh --repo /absolute/path/to/repo --strict - -# Skip expensive checks when needed -~/Desktop/run-maintenance.sh --repo /absolute/path/to/repo --skip-panic - -# Explicit language selection -~/Desktop/run-maintenance.sh --repo /absolute/path/to/repo --rust --python - -# Release hard-pass mode (fails on warnings or failures) -~/Desktop/run-maintenance.sh --repo /absolute/path/to/repo --fail-on-warn -``` - -Permission policy in script: -- Flags `g+w/o+w` files/dirs -- Flags suspicious executable files -- Flags shebang scripts missing executable bit -- Supports repo-local exceptions via `.maintenance-perms-ignore` (regex per line) -- **Audit-first by default** (non-mutating) -- `--fix-perms` is explicit opt-in only (never implicit) -- For reversible local hardening, pair snapshot/restore scripts where available: - - `scripts/maintenance/perms-state.sh snapshot` - - `scripts/maintenance/perms-state.sh lock` - - `scripts/maintenance/perms-state.sh restore` - -Important git behavior: -- Git generally tracks execute bit, not full UNIX mode matrix. -- Permission hardening audits do not force collaborators to re-unlock every file on pull. -- Keep lock mode opt-in, with restore path documented. - -```bash -# Audit-only (recommended default) -~/Desktop/run-maintenance.sh --repo /absolute/path/to/repo - -# Opt-in permission fixes (review output before commit) -~/Desktop/run-maintenance.sh --repo /absolute/path/to/repo --fix-perms -``` - -## 0) Setup - -```bash -REPO="/absolute/path/to/repo" -cd "$REPO" -``` - -```bash -date -u -git rev-parse --abbrev-ref HEAD -git rev-parse HEAD -git status --porcelain -``` - -## 1) Preflight - -- [ ] Confirm clean intent: note existing unrelated dirty files before edits. -- [ ] Confirm runtime/toolchain versions. -- [ ] Confirm container mode expectation (`podman`/`podman-compose`) if required. - -```bash -command -v rg git jq || true -command -v podman podman-compose || true -``` - -## 2) Dependency/Env Prereqs - -- [ ] Python deps in active interpreter (for Python paths). -- [ ] Language-specific tooling installed. - -```bash -python -c "import sys; print(sys.executable)" -python -c "import pydantic; print(pydantic.__version__)" || echo "pydantic missing" -``` - -## 3) Corrective Maintenance First - -- [ ] Fix regressions, runtime errors, panics, broken commands, failing tests. -- [ ] Re-run failing checks immediately after each fix. - -## 4) Code Health Scans - -- [ ] `TODO/FIXME/XXX/HACK/STUB/PARTIAL` scan. -- [ ] Permission policy scan (`g+w/o+w`, executable hygiene). -- [ ] ABI/FFI policy scan (if applicable: Idris2 ABI, Zig FFI). - -```bash -rg -n "TODO|FIXME|XXX|HACK|STUB|PARTIAL" -g '!**/.git/**' -g '!**/target/**' . -``` - -```bash -# Optional per-repo exceptions (regex per line): -# .maintenance-perms-ignore -# ^vendor/ -# ^third_party/ -``` - -```bash -# Adjust paths for your repo layout -find . -type f \( -name '*.idr' -o -name '*.idris2' -o -name '*.zig' \) -``` - -## 5) Panic/Safety/Security Pass - -- [ ] Run `panic-attacker` assail/assault. -- [ ] Triage findings by severity. -- [ ] Fix high first, then medium. -- [ ] Re-run until acceptable. - -```bash -PANIC_BIN="${REPOS_ROOT:-~/Documents/hyperpolymath-repos}/panic-attacker/target/release/panic-attack" -"$PANIC_BIN" assail "$REPO" --output /tmp/assail.json --output-format json --quiet -jq -r '.weak_points | length' /tmp/assail.json -jq -r '.weak_points[] | "\(.severity)|\(.location)|\(.description)"' /tmp/assail.json -``` - -```bash -# If repo has production-only source builder, prefer this for baseline checks: -./scripts/ci/build-panic-assail-source.sh /tmp/panic-src -"$PANIC_BIN" assail /tmp/panic-src --output /tmp/assail-prod.json --output-format json --quiet -``` - -## 6) Language-Specific Validation - -### Rust - -- [ ] Format -- [ ] Lint -- [ ] Tests -- [ ] Doc tests -- [ ] Benches (where relevant) - -```bash -cargo fmt --all --check -cargo clippy --workspace --all-targets -- -D warnings -cargo test --workspace -cargo test --workspace --doc -# Optional targeted benchmarks: -cargo bench -``` - -### Python - -- [ ] Format/lint -- [ ] Type check -- [ ] Tests - -```bash -ruff check . -ruff format --check . -mypy . -pytest -q -``` - -### Elixir - -- [ ] Format check -- [ ] Lint/static checks -- [ ] Tests - -```bash -mix format --check-formatted -mix credo --strict -mix test -``` - -## 7) Container/Runtime Checks (Podman) - -- [ ] Build container path. -- [ ] Run smoke tests inside containerized flow. -- [ ] Compare host vs container behavior for parity. - -```bash -podman --version -podman compose version || podman-compose --version -``` - -## 8) Benchmark + Regression Check - -- [ ] Capture before/after metrics for touched hot paths. -- [ ] Record command + sample size + output. -- [ ] Fail change if critical path regresses beyond threshold. - -## 9) Adaptive and Perfective Maintenance - -- [ ] Adaptive: compatibility updates (tooling/API/deprecations/config flags). -- [ ] Perfective: clarity, docs parity, developer workflow improvements. -- [ ] Update roadmap/checklist/docs to match actual implementation state. - -## 10) Final QA and Release Hygiene - -- [ ] Re-run full relevant checks one final time. -- [ ] Confirm no unintended file changes. -- [ ] Commit scoped changes with clear message. -- [ ] Push and capture commit SHA. - -```bash -git status --short -git diff --stat -git add -git commit -m "maint: " -git push -``` - -## 11) Maintenance Report Template - -Copy this block per repo run: - -```text -Repo: -Branch: -Start UTC: -End UTC: - -Scope: -- Corrective: -- Adaptive: -- Perfective: - -Checks Run: -- TODO/FIXME scan: -- Panic-attacker: -- Rust/Python/Elixir checks: -- Container checks: -- Benchmark checks: - -Findings: -- High: -- Medium: -- Low: - -Fixes Applied: -1. -2. -3. - -Validation Results: -- Tests: -- Benchmarks: -- Panic-attacker rerun: - -Artifacts: -- assail report: -- benchmark output: -- logs: - -Commit(s): -- SHA: - -Remaining Risks / Follow-ups: -1. -2. -``` - -## 12) Language-Repo Additions (Eclexia-Specific) - -Add these checks for language/compiler repositories with formal ABI/FFI constraints: - -- [x] README structure restored (index/TOC, audience paths, quickstart sanity). -- [x] Wiki split by audience (laypeople/users/developers) and linked from docs index. -- [x] Root-level clutter reduced (archive, analysis, reports relegated to `docs/` subtrees). -- [x] Machine-readable docs synchronized (`STATE.a2ml`, `META.a2ml`, `ECOSYSTEM.a2ml`, contractiles). -- [x] Human-readable docs synchronized (`README`, `QUICK_STATUS`, roadmap, wiki home). -- [x] `Mustfile` invariants present and enforceable in CI. -- [x] `Trustfile` and `Intentfile` present and complete. -- [x] FFI/ABI purity policy enforced (`*.zig` for FFI, `*.idr`/Idris2 for ABI). -- [x] `panic-attack` findings triaged with explicit severity budget for release. -- [x] Point-to-point, end-to-end, and benchmark checks wired in one quality gate. -- [x] CI workflows include quality + security + docs checks with explicit policy. -- [x] Release audit includes corrective/adaptive/perfective + Must/Should/Could. -- [x] Roadmap/status honesty pass completed (dates and current evidence updated). - -## 13) Latest Execution Record (Eclexia, 2026-02-24) - -Repo: `/tmp/eclexia-releaseprep` (branch `release-prep`, base `533ec9e9447f374135cc9e2e81021624ddb3c0ad`) - -### 13.1 Setup/Preflight - -- [x] Captured UTC timestamp and git state. -- [x] Tooling presence verified (`rg`, `git`, `jq`, `cargo`, `rustc`, `just`). -- [x] Runtime/toolchain versions captured. -- [x] Container tooling checked (`podman`, `podman-compose`). - -### 13.2 Corrective Maintenance - -- [x] Fixed `panic-attack` script path handling (`mktemp` output + local fallback binary detection). -- [x] Removed Idris `believe_me` usage from ABI wrappers. -- [x] Fixed conformance crash-noise path by skipping known intentional stack-overflow case in default runner. -- [x] Re-ran affected checks after each fix. - -### 13.3 Code-Health Scans - -- [x] TODO/FIXME/STUB/PARTIAL scan run on active code paths. -- [x] ABI/FFI file inventory run (`*.idr`, `*.zig`). -- [x] Active-code marker count reduced/triaged; remaining items tracked in release audit. - -### 13.4 Security/Panic Pass - -- [x] `panic-attack` run and triaged. -- [x] Critical findings cleared (Idris unsoundness markers removed). -- [x] Current baseline: 0 weak points (Critical 0, High 0, Medium 0, Low 0). -- [x] High/Medium backlog fully eliminated. - -### 13.5 Language Validation - -- [x] Final `just quality-gate` pass completed (docs, fmt, lint, unit, conformance, integration, p2p, e2e, bench). -- [x] Additional targeted reruns completed (`just test-conformance`, `just panic-attack`, `just docs-check`). - -### 13.6 Adaptive/Perfective/Docs - -- [x] README/wiki/docs structure and indexing restored. -- [x] Root tidy/relegation pass executed. -- [x] Roadmap/status honesty update performed with current date and evidence links. -- [x] Release audit created with corrective/adaptive/perfective + Must/Should/Could. -- [x] Full quality-gate rerun passed after hardening updates. -- [x] ABI/FFI extension lane added without breaking stable symbols (`ecl_abi_get_info`, `ecl_tracker_create_ex`, `ecl_tracker_snapshot`). -- [x] CI quality workflow now validates sibling `proven` repo presence and critical binding files. -- [x] Proven roadmap now includes explicit "critical core, not full rewrite" adoption guidance and flowchart. - -### 13.7 Outstanding Items (Explicit) - -- [x] Stable `v1.0.0` technical gate readiness met (quality + panic scan clean). -- [x] Parser/codegen/runtime panic-path hardening completed for scanner-flagged paths. -- [x] Non-eclexia `proven` library checked: already Idris2-first with Zig ABI bridge; no additional integration changes required in this run. -- [ ] Remote push blocked by token scope: GitHub rejected branch updates (`release-prep`, `release-prep-pushable`) due missing `workflow` OAuth scope. - -### 13.8 Artifacts - -- Release audit: `docs/reports/V1-READINESS-AUDIT-2026-02-24.md` -- Panic report: `/tmp/eclexia-panic-attack.KZ1jpC.json` (0 weak points) -- Final quality gate log: `/tmp/eclexia-quality-gate-final2.log` (plus post-change reruns via terminal sessions) -- Local commits: `88fa2af` (`release-prep`), `baa3d1c` (`release-prep-pushable`) + pending new commit from this pass - -## 12) LLM Operator Instructions - -Use this prompt with an LLM agent when you want the process run end-to-end: - -```text -Run the maintenance workflow for this repo using MAINTENANCE-CHECKLIST.md. - -Required behavior: -1. Run ~/Desktop/run-maintenance.sh first and collect the JSON report. -2. Triage report results by severity: fail > warn > pass. -3. Execute corrective maintenance first (fix regressions, panics, broken tests/commands). -4. Run TODO/FIXME/stub scan and address relevant items. -5. Run panic-attacker and fix findings in priority order; rerun to confirm. -6. Run language-specific checks (Rust/Python/Elixir) relevant to this repo. -7. Run benchmark/regression checks for touched hot paths. -8. Enforce permission policy: - - no group/world writable source files unless justified - - executable bit only where intended - - use .maintenance-perms-ignore for justified exceptions -9. Update docs/roadmap/checklist entries to reflect actual state. -10. Produce a final report using the template in MAINTENANCE-CHECKLIST.md. - -Constraints: -- Do not revert unrelated existing dirty changes. -- Stage and commit only scoped intended files. -- If blocked, state exactly what is blocked and why. -``` - -## 13) AI Execution Integrity Contract (Mandatory) - -Use this when delegating maintenance to any AI (Gemini/Claude/ChatGPT/etc.). - -```text -You must execute this maintenance run with strict integrity. - -Non-negotiable rules: -1. Do not claim any step is complete unless you actually ran it. -2. Do not silently skip checklist items. If skipped, state SKIPPED + exact reason. -3. For every check, provide evidence: - - command executed - - pass/fail/warn - - key output summary - - artifact/log path -4. If a command fails, stop claiming success and report the failure clearly. -5. After each fix, re-run the relevant failing check and report the rerun result. -6. Do not hide uncertainty. If unsure, say so and run additional verification. -7. Never mark “all done” while any fail/warn remains unexplained. -8. Do not make destructive or broad permission changes by default. - - permission changes must be audit-first - - use --fix-perms only with explicit intent -9. Final output must include: - - checklist coverage matrix (each item: PASS/FAIL/WARN/SKIPPED) - - unresolved risks - - exact next actions -10. Prioritize user safety and reputation: no “looks fine” claims without evidence. -``` - -Recommended enforcement line for AI prompts: - -```text -Fail closed: if evidence is missing for any checklist item, treat that item as NOT DONE. -``` - -## 14) Fleet Enrollment Automation (Gitbot + Hypatia) - -For centralized coverage across existing and new repos: - -```bash -cd ${REPOS_ROOT:-~/Documents/hyperpolymath-repos}/gitbot-fleet -just enroll-repos -``` - -Optional directive write-back to repos that already have `.machine_readable/`: - -```bash -cd ${REPOS_ROOT:-~/Documents/hyperpolymath-repos}/gitbot-fleet -just enroll-repos /var$REPOS_DIR true -``` - -Release hard gate from fleet: - -```bash -cd ${REPOS_ROOT:-~/Documents/hyperpolymath-repos}/gitbot-fleet -just maintenance-hard-pass /absolute/path/to/repo -``` diff --git a/docs/governance/README.adoc b/docs/governance/README.adoc deleted file mode 100644 index 48cac0d..0000000 --- a/docs/governance/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Governance Pillar (TSDM) diff --git a/docs/governance/SOFTWARE-DEVELOPMENT-APPROACH.adoc b/docs/governance/SOFTWARE-DEVELOPMENT-APPROACH.adoc deleted file mode 100644 index 2bfa0ff..0000000 --- a/docs/governance/SOFTWARE-DEVELOPMENT-APPROACH.adoc +++ /dev/null @@ -1,65 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Software Development Approach (General) -:toc: left -:toclevels: 2 - -This is the general operating policy for software development across repositories. - -== Core Sequence - -Always run work in this order: - -1. Scope first (Axis 1) -2. Maintenance second (Axis 2) -3. Audit third (Axis 3) - -== Axis Definitions - -=== Axis 1: Scope - -Priority order: `must > intend > like` - -Axis 1 output is a scoped assembly of work based on: - -* README, roadmap, status, CI/security docs -* marker scans (`TODO`, `FIXME`, `XXX`, `HACK`, `STUB`, `PARTIAL`) -* Idris unsoundness scan when Idris exists (`believe_me`, `assert_total`) -* docs honesty check (intent vs actual implementation) - -=== Axis 2: Maintenance - -Priority order: `corrective > adaptive > perfective` - -* Corrective: fix defects, regressions, breakage, security/safety failures -* Adaptive: reconcile scope changes, remove stale references, cull obsolete work -* Perfective: improve quality/clarity/performance only from the honest Axis 1 state - -=== Axis 3: Audit - -Priority order: `systems > compliance > effects` - -* Systems: required mechanisms exist and are operating -* Compliance: seams/compromises/exceptions are explicit, bounded, and do not drift -* Effects: benchmark and operational impact evidence is captured and reviewed - -Compliance scanner baseline: `panic-attack` + -Effects/ecological baseline: sustainabot-guided ecological checking - -== Generic Cleanup And Finish-Off - -At cycle end: - -* reduce root clutter to required control/entry files -* archive/remove stale or superseded work -* synchronize human and machine docs -* run compliance and effects audits with evidence capture -* produce Must/Should/Could summary and immediate next-actions list - -== Collaboration Rule - -Effects review must include explicit maintainer dialogue: - -* what changed -* why it changed -* what risks remain diff --git a/docs/governance/TEMPLATE-STANDARDS-AUDIT.adoc b/docs/governance/TEMPLATE-STANDARDS-AUDIT.adoc deleted file mode 100644 index 34b25a1..0000000 --- a/docs/governance/TEMPLATE-STANDARDS-AUDIT.adoc +++ /dev/null @@ -1,179 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Template Standards Audit -Codex -v1.0, 2026-04-07 -:toc: -:toclevels: 3 -:sectnums: - -== Scope And Inventory - -Audit scope: - -* Repository: `rsr-template-repo` -* Focus: root authority docs/manifests, Justfile integration, session bindings -* Recursive inventory method: `rg --files -g '!.git' | sort` - -Inventory snapshot at audit time: - -* `rsr-template-repo` total tracked files discovered: `240` -* Session-local binding files discovered: `4` under `session/` plus `coordination.k9` - -== Claim Vs Actual - -[cols="2,2,3,1,3,3",options="header"] -|=== -| Claimed item | Claimed by | Expected path | Actual status | Notes | Recommended action - -| Placeholder badge tokens in README -| `README.adoc` -| `{{OPENSSF_PROJECT_ID}}`, `{{OWNER}}`, `{{REPO}}` -| placeholder -| Template placeholders are intentional pre-bootstrap content. -| Keep; document clearly as template tokens. - -| Docs links used `.adoc` files not present -| legacy `README.adoc` (pre-migration) -| `CONTRIBUTING.adoc`, `GOVERNANCE.adoc`, `SECURITY.adoc` -| outdated -| Actual files are `CONTRIBUTING.md`, no root `GOVERNANCE.adoc`, `SECURITY.md`. -| Fixed README links to existing files. - -| ABI path lower-case only -| legacy `README.adoc` + legacy checks -| `src/interface/abi/*.idr` -| outdated -| Tree previously shipped `src/interface/Abi/*.idr` (uppercase A); now renamed. -| Renamed to canonical lowercase `src/interface/abi/*.idr` (matches `validate-template.sh` + gossamer). Checks remain tolerant of either case. - -| Root manifest structure with non-existent files -| legacy `0-AI-MANIFEST.a2ml` (pre-migration) -| `GOVERNANCE.adoc`, several strict root assumptions -| outdated -| Manifest claims did not match actual template contents. -| Replaced with accurate authority split + startup checklist. - -| Source-human references maintenance/practice docs -| legacy Justfile + policy A2ML (pre-migration) -| `docs/maintenance/...`, `docs/practice/SOFTWARE-DEVELOPMENT-APPROACH.adoc` -| outdated -| Those paths did not exist in template. -| Updated to `docs/governance/...` paths. - -| Session-management local binding files -| target architecture -| `session/README.md`, `session/custom-checks.k9`, `session/local-hooks.sh`, `coordination.k9` -| exists -| Added as thin integration layer without protocol duplication. -| Keep. - -| Canonical command mapping in local automation -| target architecture -| `Justfile` session aliases + `session/dispatch.sh` -| exists -| All canonical commands map to dispatcher. -| Keep. - -| Central protocols are authoritative -| `README.adoc`, `0-AI-MANIFEST.a2ml`, `AUDIT.adoc` -| `standards/session-management-standards/` -| exists -| Local docs now explicitly defer protocol authority to standards repo. -| Keep. - -| Runtime session artifacts stay per-repo -| `session/README.md`, `session/dispatch.sh` -| `.session/` in target repo path -| exists -| Dispatcher records canonical commands into runtime `.session/` files. -| Keep runtime artifacts out of authoritative standards docs. - -| Local policy hooks remain local -| `session/local-hooks.sh`, `session/custom-checks.k9` -| local session binding layer -| exists -| Policy/hook logic separated from central protocol definitions. -| Keep local-only. -|=== - -== Classification - -=== Authoritative Shared Standard - -* External to this repo: `standards/session-management-standards/*` - -=== Repo-Local Binding/Integration - -* `Justfile` canonical session aliases -* `session/dispatch.sh` -* `session/custom-checks.k9` -* `session/local-hooks.sh` -* `session/README.md` -* `coordination.k9` -* `AUDIT.adoc` (local gate summary) - -=== Generated Runtime Artifact - -* `.session/*` outputs created by local dispatcher per repository path - -=== Obsolete/Duplicate/Drifted - -* Legacy path assumptions (`docs/maintenance/*`, `docs/practice/*` for governance policy references) -* Legacy root-doc claims to files not present in this template -* Legacy lower-case-only ABI path references - -== Move/Stay/Delete Guidance - -=== Move Into `standards` - -* Any future full protocol text drafts should move to - `standards/session-management-standards/`. - -=== Stay In `rsr-template-repo` - -* Local aliases, hooks, coordination wiring, and repo-local checks. - -=== Delete/Archive - -* Archive or remove legacy references to non-existent docs/paths if reintroduced. -* Avoid reintroducing full duplicated protocol definitions. - -== Missing-But-Expected Session Files (Template Repo) - -Template repo expected only thin local integration files. - -Current status: - -* No mandatory thin-binding files are missing. -* Full protocol directories/files are intentionally absent here by design. - -== Proposed Final Directory Map - -[source,text] ----- -rsr-template-repo/ - README.adoc - AUDIT.adoc - 0-AI-MANIFEST.a2ml - EXPLAINME.adoc - Justfile - coordination.k9 - session/ - README.md - dispatch.sh - custom-checks.k9 - local-hooks.sh - docs/ - ... (repo-local human docs) - .machine_readable/ - ... (repo-local machine-readable policy/state) ----- - -== Maintenance Model Note - -* Protocols central: maintained in `standards/session-management-standards/`. -* Policy local: maintained in template/downstream repos (`session/*.k9`, hooks, - coordination bindings). -* State per-repo: generated during execution (`.session/*`) in the active - working repository. diff --git a/docs/governance/TSDM.a2ml b/docs/governance/TSDM.a2ml deleted file mode 100644 index f27036c..0000000 --- a/docs/governance/TSDM.a2ml +++ /dev/null @@ -1,22 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [TSDM_SPEC] -id: "tsdm-standard" -version: "1.0.0" - -axes: - axis_1: - name: "Planning" - levels: ["must", "should", "could"] - axis_2: - name: "Maintenance" - levels: ["corrective", "adaptive", "perfective"] - axis_3: - name: "Audit" - levels: ["systems", "compliance", "effects"] - -invariants: - - "Every task MUST map to at least one TSDM coordinate" - - "Axis 1 priority governs resource allocation" - - "Axis 2 type governs commit categorisation" - - "Axis 3 focus governs audit depth" diff --git a/docs/governance/TSDM.adoc b/docs/governance/TSDM.adoc deleted file mode 100644 index 6bf4ee8..0000000 --- a/docs/governance/TSDM.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Triaxial Software Development Methodology (TSDM) -:toc: preamble -:icons: font - -TSDM is a three-dimensional governance framework designed for high-assurance, long-lived software systems. It ensures that every project decision is mapped across three critical axes: Planning, Maintenance, and Audit. - -== The Three Axes - -=== Axis 1: Planning (Scope Priority) -* **Must:** Non-negotiable core invariants and safety requirements. -* **Should:** Essential features and planned improvements. -* **Could:** Desired enhancements and future-proofing. - -=== Axis 2: Maintenance (Execution Type) -* **Corrective:** Fixing bugs, vulnerabilities, and failures. -* **Adaptive:** Responding to environment or dependency changes. -* **Perfective:** Improving performance, refactoring, and documentation. - -=== Axis 3: Audit (Verification Focus) -* **Systems:** Integrity of tools, infrastructure, and automation. -* **Compliance:** Adherence to standards, licenses, and verified seams. -* **Effects:** Real-world impact, ecological footprint, and user feedback. - -== Integration - -TSDM is the operational core of the Rhodium Standard. Every task in the `Justfile` and every state change in `STATE.a2ml` should be justifiable within this framework. diff --git a/docs/governance/audit/0.2-AI-MANIFEST.a2ml b/docs/governance/audit/0.2-AI-MANIFEST.a2ml deleted file mode 100644 index 4722486..0000000 --- a/docs/governance/audit/0.2-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "governance-axis-audit" -level: 2 -parent: "../0.1-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - TSDM Audit track. diff --git a/docs/governance/audit/README.adoc b/docs/governance/audit/README.adoc deleted file mode 100644 index 02aff13..0000000 --- a/docs/governance/audit/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Audit Axis diff --git a/docs/governance/audit/compliance/0.3-AI-MANIFEST.a2ml b/docs/governance/audit/compliance/0.3-AI-MANIFEST.a2ml deleted file mode 100644 index b13ec69..0000000 --- a/docs/governance/audit/compliance/0.3-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "governance-unit-compliance" -level: 3 -parent: "../0.2-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - TSDM compliance unit within the Audit axis. diff --git a/docs/governance/audit/compliance/README.adoc b/docs/governance/audit/compliance/README.adoc deleted file mode 100644 index 9948dbc..0000000 --- a/docs/governance/audit/compliance/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Compliance Unit diff --git a/docs/governance/audit/effects/0.3-AI-MANIFEST.a2ml b/docs/governance/audit/effects/0.3-AI-MANIFEST.a2ml deleted file mode 100644 index 0bccae0..0000000 --- a/docs/governance/audit/effects/0.3-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "governance-unit-effects" -level: 3 -parent: "../0.2-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - TSDM effects unit within the Audit axis. diff --git a/docs/governance/audit/effects/README.adoc b/docs/governance/audit/effects/README.adoc deleted file mode 100644 index e5620ee..0000000 --- a/docs/governance/audit/effects/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Effects Unit diff --git a/docs/governance/audit/systems/0.3-AI-MANIFEST.a2ml b/docs/governance/audit/systems/0.3-AI-MANIFEST.a2ml deleted file mode 100644 index f97bc9c..0000000 --- a/docs/governance/audit/systems/0.3-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "governance-unit-systems" -level: 3 -parent: "../0.2-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - TSDM systems unit within the Audit axis. diff --git a/docs/governance/audit/systems/README.adoc b/docs/governance/audit/systems/README.adoc deleted file mode 100644 index 00a67de..0000000 --- a/docs/governance/audit/systems/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Systems Unit diff --git a/docs/governance/maintenance/0.2-AI-MANIFEST.a2ml b/docs/governance/maintenance/0.2-AI-MANIFEST.a2ml deleted file mode 100644 index 8e0dff5..0000000 --- a/docs/governance/maintenance/0.2-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "governance-axis-maintenance" -level: 2 -parent: "../0.1-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - TSDM Maintenance track. diff --git a/docs/governance/maintenance/README.adoc b/docs/governance/maintenance/README.adoc deleted file mode 100644 index 7083a83..0000000 --- a/docs/governance/maintenance/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Maintenance Axis diff --git a/docs/governance/maintenance/adaptive/0.3-AI-MANIFEST.a2ml b/docs/governance/maintenance/adaptive/0.3-AI-MANIFEST.a2ml deleted file mode 100644 index 63d1a99..0000000 --- a/docs/governance/maintenance/adaptive/0.3-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "governance-unit-adaptive" -level: 3 -parent: "../0.2-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - TSDM adaptive unit within the Maintenance axis. diff --git a/docs/governance/maintenance/adaptive/README.adoc b/docs/governance/maintenance/adaptive/README.adoc deleted file mode 100644 index 72d0381..0000000 --- a/docs/governance/maintenance/adaptive/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Adaptive Unit diff --git a/docs/governance/maintenance/corrective/0.3-AI-MANIFEST.a2ml b/docs/governance/maintenance/corrective/0.3-AI-MANIFEST.a2ml deleted file mode 100644 index 05cb89d..0000000 --- a/docs/governance/maintenance/corrective/0.3-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "governance-unit-corrective" -level: 3 -parent: "../0.2-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - TSDM corrective unit within the Maintenance axis. diff --git a/docs/governance/maintenance/corrective/README.adoc b/docs/governance/maintenance/corrective/README.adoc deleted file mode 100644 index 9a0ed5d..0000000 --- a/docs/governance/maintenance/corrective/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Corrective Unit diff --git a/docs/governance/maintenance/perfective/0.3-AI-MANIFEST.a2ml b/docs/governance/maintenance/perfective/0.3-AI-MANIFEST.a2ml deleted file mode 100644 index 832762f..0000000 --- a/docs/governance/maintenance/perfective/0.3-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "governance-unit-perfective" -level: 3 -parent: "../0.2-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - TSDM perfective unit within the Maintenance axis. diff --git a/docs/governance/maintenance/perfective/README.adoc b/docs/governance/maintenance/perfective/README.adoc deleted file mode 100644 index 12e3d14..0000000 --- a/docs/governance/maintenance/perfective/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Perfective Unit diff --git a/docs/governance/planning/0.2-AI-MANIFEST.a2ml b/docs/governance/planning/0.2-AI-MANIFEST.a2ml deleted file mode 100644 index 80339e7..0000000 --- a/docs/governance/planning/0.2-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "governance-axis-planning" -level: 2 -parent: "../0.1-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - TSDM Planning track. diff --git a/docs/governance/planning/README.adoc b/docs/governance/planning/README.adoc deleted file mode 100644 index 2694fe9..0000000 --- a/docs/governance/planning/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Planning Axis diff --git a/docs/governance/planning/could/0.3-AI-MANIFEST.a2ml b/docs/governance/planning/could/0.3-AI-MANIFEST.a2ml deleted file mode 100644 index fc17a27..0000000 --- a/docs/governance/planning/could/0.3-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "governance-unit-could" -level: 3 -parent: "../0.2-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - TSDM could unit within the Planning axis. diff --git a/docs/governance/planning/could/README.adoc b/docs/governance/planning/could/README.adoc deleted file mode 100644 index acc41ce..0000000 --- a/docs/governance/planning/could/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Could Unit diff --git a/docs/governance/planning/must/0.3-AI-MANIFEST.a2ml b/docs/governance/planning/must/0.3-AI-MANIFEST.a2ml deleted file mode 100644 index 0987dae..0000000 --- a/docs/governance/planning/must/0.3-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "governance-unit-must" -level: 3 -parent: "../0.2-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - TSDM must unit within the Planning axis. diff --git a/docs/governance/planning/must/README.adoc b/docs/governance/planning/must/README.adoc deleted file mode 100644 index 5759550..0000000 --- a/docs/governance/planning/must/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Must Unit diff --git a/docs/governance/planning/should/0.3-AI-MANIFEST.a2ml b/docs/governance/planning/should/0.3-AI-MANIFEST.a2ml deleted file mode 100644 index f492289..0000000 --- a/docs/governance/planning/should/0.3-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "governance-unit-should" -level: 3 -parent: "../0.2-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - TSDM should unit within the Planning axis. diff --git a/docs/governance/planning/should/README.adoc b/docs/governance/planning/should/README.adoc deleted file mode 100644 index a00f585..0000000 --- a/docs/governance/planning/should/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Should Unit diff --git a/docs/legal/0.2-AI-MANIFEST.a2ml b/docs/legal/0.2-AI-MANIFEST.a2ml deleted file mode 100644 index e547798..0000000 --- a/docs/legal/0.2-AI-MANIFEST.a2ml +++ /dev/null @@ -1,16 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "legal-track" -level: 2 -parent: "../0.1-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Sub-unit for legal and licensing documentation. Contains framework - exhibits and archival license texts. - -canonical_locations: - exhibits: "exhibits/" - texts: "texts/" diff --git a/docs/legal/EXHIBIT-A-ETHICAL-USE.txt b/docs/legal/EXHIBIT-A-ETHICAL-USE.txt deleted file mode 100644 index 0b20fca..0000000 --- a/docs/legal/EXHIBIT-A-ETHICAL-USE.txt +++ /dev/null @@ -1,68 +0,0 @@ -SPDX-License-Identifier: MPL-2.0 - -================================================================================ -EXHIBIT A — ETHICAL USE GUIDELINES -Palimpsest-MPL License Version 1.0 -================================================================================ - -1. PURPOSE - - These guidelines define ethical use expectations for software distributed - under the Palimpsest-MPL License. They are not legally binding restrictions - but represent the community's shared values and expectations. - -2. PRINCIPLES - - 2.1. Respect for Emotional Lineage - Users and distributors should acknowledge and preserve the cultural, - narrative, and symbolic meaning embedded in Covered Software. This - includes protest traditions, cultural heritage, trauma narratives, - and community stories where documented. - - 2.2. Transparency in Automated Processing - When Covered Software is processed by Non-Interpretive Systems - (AI training, content aggregation, automated summarization), such - use should be documented publicly and not misrepresent the - provenance of outputs. - - 2.3. Good Faith Attribution - Contributors should be credited accurately. Derivative works should - maintain the attribution chain and not obscure the origins of - contributions. - - 2.4. Community Benefit - Commercial use of Covered Software should contribute to the broader - community through bug fixes, documentation, or other improvements - where feasible. - -3. SPECIFIC GUIDANCE - - 3.1. AI and Machine Learning - - Training on Covered Software requires disclosure - - Generated outputs must not claim Emotional Lineage of the original - - Model cards should reference source materials - - 3.2. Content Aggregation - - Aggregators must link back to original sources - - Context must not be stripped in ways that distort meaning - - Cultural and narrative context should be preserved - - 3.3. Commercial Products - - Products built on Covered Software should acknowledge it - - Pricing should not exploit communities that created the work - - Support and improvements should flow back to the community - -4. ENFORCEMENT - - These guidelines are enforced through community norms, not legal action. - Disputes should be raised with the Palimpsest Stewardship Council for - non-binding guidance. - -5. AMENDMENTS - - These guidelines may be updated by the Palimpsest Stewardship Council. - Updates apply to new distributions, not retroactively. - -================================================================================ -END OF EXHIBIT A -================================================================================ diff --git a/docs/legal/EXHIBIT-B-QUANTUM-SAFE.txt b/docs/legal/EXHIBIT-B-QUANTUM-SAFE.txt deleted file mode 100644 index 7fba8c9..0000000 --- a/docs/legal/EXHIBIT-B-QUANTUM-SAFE.txt +++ /dev/null @@ -1,102 +0,0 @@ -SPDX-License-Identifier: MPL-2.0 - -================================================================================ -EXHIBIT B — QUANTUM-SAFE PROVENANCE SPECIFICATION -Palimpsest-MPL License Version 1.0 -================================================================================ - -1. PURPOSE - - This exhibit specifies the cryptographic algorithms and procedures for - quantum-safe provenance in software distributed under the Palimpsest-MPL - License. - -2. APPROVED ALGORITHMS - - The following post-quantum cryptographic algorithms are approved for - signing Provenance Metadata: - - 2.1. Digital Signatures - - ML-DSA (FIPS 204, formerly CRYSTALS-Dilithium) - Recommended: ML-DSA-65 (security level 3) or ML-DSA-87 (level 5) - - SLH-DSA (FIPS 205, formerly SPHINCS+) - Recommended: SLH-DSA-SHA2-256f or SLH-DSA-SHAKE-256f - - FALCON (NIST Round 3 finalist) - Recommended: FALCON-1024 - - 2.2. Key Encapsulation (for encrypted provenance) - - ML-KEM (FIPS 203, formerly CRYSTALS-Kyber) - Recommended: ML-KEM-1024 - - 2.3. Hash Functions - - SHA-3 (FIPS 202) - Recommended: SHA3-256 or SHA3-512 - - SHAKE (FIPS 202 extendable output) - Recommended: SHAKE-256 - - 2.4. Key Derivation - - Argon2id (RFC 9106) - Parameters: t=3, m=65536, p=4 (minimum) - -3. PROVENANCE METADATA FORMAT - - Provenance Metadata should include: - - 3.1. Required Fields - - author-identity: Contributor name and contact - - timestamp: ISO 8601 with timezone - - content-hash: SHA3-256 hash of the contribution - - signature: Quantum-safe signature over all fields - - 3.2. Optional Fields - - parent-hash: Hash of the previous contribution in the chain - - emotional-lineage: Narrative context markers - - platform: Build/development environment - - witnesses: Third-party attestation signatures - -4. SIGNATURE PROCEDURE - - 4.1. Signing - a. Compute SHA3-256 hash of the contribution content - b. Construct metadata record with all required fields - c. Serialize metadata in canonical JSON form - d. Sign with ML-DSA-65 (or approved alternative) - e. Attach signature to distribution - - 4.2. Verification - a. Extract metadata and signature from distribution - b. Verify signature against contributor's public key - c. Verify content hash matches actual content - d. Verify timestamp is within acceptable range - e. Verify parent-hash chain if present - -5. KEY MANAGEMENT - - 5.1. Contributors should publish quantum-safe public keys via: - - OpenPGP keyservers (with PQ algorithm support) - - Repository .well-known/keys/ directory - - Contributor's personal website - - 5.2. Key rotation should occur: - - At least annually - - When algorithm recommendations change - - When key compromise is suspected - -6. TRANSITION PERIOD - - During the transition to quantum-safe cryptography: - - 6.1. Classical signatures (Ed25519, RSA) remain valid - 6.2. Hybrid signatures (classical + PQ) are encouraged - 6.3. Pure PQ signatures are preferred for new contributions - 6.4. Classical-only signatures will be deprecated in a future version - -7. COMPLIANCE - - Quantum-safe provenance is OPTIONAL under PMPL-1.0. When present, - it must follow this specification. Stripping quantum-safe signatures - from distributions is prohibited per Section 4.1 of the License. - -================================================================================ -END OF EXHIBIT B -================================================================================ diff --git a/docs/onboarding/QUICKSTART-DEV.adoc b/docs/onboarding/QUICKSTART-DEV.adoc deleted file mode 100644 index 02957ea..0000000 --- a/docs/onboarding/QUICKSTART-DEV.adoc +++ /dev/null @@ -1,112 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -// Template: QUICKSTART-DEV.adoc — clone → build → test → PR -// Replace rsr-template-repo, {{BUILD_CMD}}, {{TEST_CMD}}, {{LANG_STACK}} with actuals -= rsr-template-repo — Quick Start for Developers -:toc: -:toclevels: 2 - -== Tech Stack - -{{LANG_STACK}} - -== Set Up Development Environment - -=== Option A: Guix (preferred) - -[source,bash] ----- -guix shell ----- - -=== Option B: Nix (fallback) - -[source,bash] ----- -nix develop ----- - -=== Option C: Manual - -[source,bash] ----- -git clone https://github.com/hyperpolymath/rsr-template-repo.git -cd rsr-template-repo -just setup-dev ----- - -== Build - -[source,bash] ----- -{{BUILD_CMD}} ----- - -== Test - -[source,bash] ----- -{{TEST_CMD}} ----- - -== Project Structure - -[source] ----- -rsr-template-repo/ -├── src/ # Source code -├── src/abi/ # Idris2 ABI definitions (if applicable) -├── ffi/zig/ # Zig FFI bridge (if applicable) -├── tests/ # Test suite -├── docs/ # Documentation -├── .machine_readable/ # Checkpoint files (STATE, META, ECOSYSTEM) -├── Justfile # Task runner recipes -├── guix.scm # Guix environment -├── flake.nix # Nix environment (fallback) -└── 0-AI-MANIFEST.a2ml # AI agent entry point ----- - -== Key Recipes - -[source,bash] ----- -just build # Build the project -just test # Run tests -just doctor # Self-diagnostic -just lint # Lint and format -just panic-scan # Security scan via panic-attacker -just tour # Guided tour of the codebase ----- - -== Before Submitting a PR - -[source,bash] ----- -just lint # Format and lint -just test # All tests pass -just panic-scan # No new security issues ----- - -== Contractile Invariants - -Read `.machine_readable/MUST.contractile` before making changes. -Key invariants that must never be violated: - -{{MUST_INVARIANTS}} - -== LLM/AI Agent Development - -If using an AI assistant, load the warmup context first: - -[source,bash] ----- -just llm-context # Outputs role-appropriate context ----- - -Or read `0-AI-MANIFEST.a2ml` and `.claude/CLAUDE.md` directly. - -== Get Help - -* **Architecture**: link:EXPLAINME.adoc[EXPLAINME.adoc] -* **Wiki**: https://github.com/hyperpolymath/rsr-template-repo/wiki -* **Report issue**: `just help-me` diff --git a/docs/onboarding/QUICKSTART-MAINTAINER.adoc b/docs/onboarding/QUICKSTART-MAINTAINER.adoc deleted file mode 100644 index b42ffd3..0000000 --- a/docs/onboarding/QUICKSTART-MAINTAINER.adoc +++ /dev/null @@ -1,130 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -// Template: QUICKSTART-MAINTAINER.adoc — packaging, deploying, and maintaining -// Replace rsr-template-repo, {{PACKAGE_NAME}}, {{DEPS}} with actuals -= rsr-template-repo — Quick Start for Platform Maintainers -:toc: -:toclevels: 2 - -== Overview - -This guide covers packaging, deploying, and maintaining rsr-template-repo for -distribution on your platform. - -== Runtime Dependencies - -{{DEPS}} - -== Build from Source - -[source,bash] ----- -git clone https://github.com/hyperpolymath/rsr-template-repo.git -cd rsr-template-repo -just build-release ----- - -Output: `{{BUILD_OUTPUT_PATH}}` - -== Packaging - -=== Guix - -[source,bash] ----- -guix build -f guix.scm ----- - -=== Nix - -[source,bash] ----- -nix build ----- - -=== Container (Stapeln) - -[source,bash] ----- -just stapeln-export # Generates Containerfile -podman build -t rsr-template-repo . ----- - -=== Manual Package - -[source,bash] ----- -just install --prefix=/usr/local ----- - -Files installed: - -[cols="1,2"] -|=== -| Path | Contents - -| `$PREFIX/bin/` -| Executables - -| `$PREFIX/share/{{PACKAGE_NAME}}/` -| Data files, assets - -| `$PREFIX/share/doc/{{PACKAGE_NAME}}/` -| Documentation - -| `$PREFIX/share/applications/` -| .desktop file (Linux, if GUI) - -| `$PREFIX/share/man/man1/` -| Man pages -|=== - -== Configuration - -Default config location: `$XDG_CONFIG_HOME/{{PACKAGE_NAME}}/config.toml` - -Fallback: `$HOME/.config/{{PACKAGE_NAME}}/config.toml` - -== Health Checks - -[source,bash] ----- -just doctor # Full diagnostic -just run --version # Version check -just run --selftest # Built-in self-test ----- - -== Updating - -[source,bash] ----- -git pull -just build-release -just install --prefix=/usr/local ----- - -Or via OPSM: `opsm update {{PACKAGE_NAME}}` - -== Security Notes - -* License: MPL-2.0 (Palimpsest License) -* All dependencies SHA-pinned -* `panic-attacker` scan results: link:INSTALL-SECURITY-REPORT.adoc[] -* OpenSSF Scorecard: see badge in README - -== Multi-Instance Deployment - -For deploying multiple instances (e.g., different users or tenants): - -[source,bash] ----- -just install --prefix=/opt/{{PACKAGE_NAME}}-instance1 --config=/etc/{{PACKAGE_NAME}}/instance1.toml -just install --prefix=/opt/{{PACKAGE_NAME}}-instance2 --config=/etc/{{PACKAGE_NAME}}/instance2.toml ----- - -Each instance has isolated config, data, and logs. - -== Reporting Issues - -* Upstream: https://github.com/hyperpolymath/rsr-template-repo/issues -* With diagnostic: `just help-me` (pre-fills context) diff --git a/docs/onboarding/QUICKSTART-USER.adoc b/docs/onboarding/QUICKSTART-USER.adoc deleted file mode 100644 index 4992e32..0000000 --- a/docs/onboarding/QUICKSTART-USER.adoc +++ /dev/null @@ -1,125 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -// Template: QUICKSTART-USER.adoc — 5-minute path to working software -// Replace rsr-template-repo, Rsr Template Repo — See README.adoc for details., just run, Rsr Template Repo started successfully. with actuals -= rsr-template-repo — Quick Start for Users -:toc: -:toclevels: 2 - -== What is rsr-template-repo? - -Rsr Template Repo — See README.adoc for details. - -== Prerequisites - -Before you begin, ensure you have: - -* **just** — task runner (https://github.com/casey/just[install guide]) -* Platform-specific requirements listed below - -[cols="1,3"] -|=== -| Platform | Additional Requirements - -| Linux -| See README.adoc - -| macOS -| See README.adoc - -| Windows -| See README.adoc -|=== - -== Install - -=== Option 1: Standard Install (recommended) - -[source,bash] ----- -# Clone and set up -git clone https://github.com/hyperpolymath/rsr-template-repo.git -cd rsr-template-repo -just setup ----- - -The setup script will: - -* Detect your platform and shell -* Install missing dependencies (with your permission) -* Configure the application -* Offer install location choices -* Run a self-diagnostic to verify everything works - -=== Option 2: Container (via Stapeln) - -[source,bash] ----- -just stapeln-run ----- - -=== Option 3: Portable (no system changes) - -[source,bash] ----- -just install --portable --prefix=./rsr-template-repo-portable ----- - -== First Run - -[source,bash] ----- -just run ----- - -Expected output: - -[source] ----- -Rsr Template Repo started successfully. ----- - -== Self-Diagnostic - -If something isn't working: - -[source,bash] ----- -just doctor ----- - -This checks all dependencies, permissions, paths, and connectivity. -If it finds issues, it will suggest fixes. - -To attempt automatic repair: - -[source,bash] ----- -just heal ----- - -== Get Help - -* **In-app**: `just run --help` -* **Guided tour**: `just tour` -* **Report a problem**: `just help-me` (pre-fills diagnostic context) -* **Wiki**: https://github.com/hyperpolymath/rsr-template-repo/wiki - -== Uninstall - -[source,bash] ----- -just uninstall ----- - -You will be asked: - -1. Which uninstall tier (Bennett reversible, parameter-based, standard, or secure) -2. Whether to include or exclude your data -3. Whether to clear caches and LLM models - -== Next Steps - -* Read the link:README.adoc[README] for full feature overview -* Read the link:EXPLAINME.adoc[EXPLAINME] for architecture and design decisions -* Try `just tour` for a guided walkthrough diff --git a/docs/onboarding/llm-warmup-dev.adoc b/docs/onboarding/llm-warmup-dev.adoc deleted file mode 100644 index e8b157f..0000000 --- a/docs/onboarding/llm-warmup-dev.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= LLM Warmup — rsr-template-repo (Developer) - -== What is rsr-template-repo? - -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/docs/onboarding/llm-warmup-user.adoc b/docs/onboarding/llm-warmup-user.adoc deleted file mode 100644 index f049844..0000000 --- a/docs/onboarding/llm-warmup-user.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= LLM Warmup — rsr-template-repo (User) - -== What is rsr-template-repo? - -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/docs/practice/.gitkeep b/docs/practice/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/docs/practice/0.2-AI-MANIFEST.a2ml b/docs/practice/0.2-AI-MANIFEST.a2ml deleted file mode 100644 index 257f3a4..0000000 --- a/docs/practice/0.2-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "practice-unit" -level: 2 -parent: "../0.1-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Sub-unit of the docs pillar focusing on practice. diff --git a/docs/practice/AI-CONVENTIONS.adoc b/docs/practice/AI-CONVENTIONS.adoc deleted file mode 100644 index a174609..0000000 --- a/docs/practice/AI-CONVENTIONS.adoc +++ /dev/null @@ -1,87 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= AI Conventions - - - -# AI Conventions (Authoritative Source) - -All AI coding agents working in this repository MUST follow these rules. -Per-tool config files (.cursorrules, .clinerules, etc.) reference this document. - -## Session Startup - -1. Read `0-AI-MANIFEST.a2ml` FIRST (mandatory gatekeeper). -2. Read `.machine_readable/6a2/STATE.a2ml` for current status and blockers. -3. Read `.machine_readable/6a2/anchors/ANCHOR.a2ml` for canonical authority boundaries. -4. Read `.machine_readable/policies/MAINTENANCE-AXES.a2ml` for maintenance/audit sequencing. -5. Read `.machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml` for baseline controls. -6. Read `.machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml` for execution order. -7. Read `.machine_readable/6a2/AGENTIC.a2ml` for agent constraints. - -## License - -- All original code: **MPL-2.0** -- Fallback (platform-required only): MPL-2.0 with comment explaining why. -- NEVER use AGPL-3.0. -- Preserve third-party licenses verbatim. -- Every source file needs `# SPDX-License-Identifier: MPL-2.0`. - -## Author Attribution - -- Name: **{{AUTHOR}}** -- Email: **{{AUTHOR_EMAIL}}** -- Copyright: `Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}>` - -## State Files - -State/metadata files, anchors, and policies (.a2ml) belong in `.machine_readable/` ONLY. -NEVER create STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml, AGENTIC.a2ml, -NEUROSYM.a2ml, PLAYBOOK.a2ml, ANCHOR.a2ml, MAINTENANCE-AXES.a2ml, -MAINTENANCE-CHECKLIST.a2ml, or SOFTWARE-DEVELOPMENT-APPROACH.a2ml in the repository root. - -## Banned Patterns - -| Language | Banned | Reason | -|----------|-------------------------------------|---------------------------| -| Idris2 | `believe_me`, `assert_total` | Unsound escape hatches | -| Haskell | `unsafeCoerce`, `unsafePerformIO` | Breaks type safety | -| OCaml | `Obj.magic`, `Obj.repr`, `Obj.obj` | Unsafe casting | -| Coq | `Admitted` | Unproven assumption | -| Lean | `sorry` | Unproven assumption | -| Rust | `transmute` (unless FFI + SAFETY:) | Unsound reinterpret | - -## Banned Languages - -| Banned | Use Instead | -|---------------------|--------------------| -| TypeScript | ReScript | -| Node.js / npm / bun | Deno | -| Go | Rust | -| Python | Julia / Rust | - -## Container Standard - -- Runtime: **Podman** (never Docker). -- File: **Containerfile** (never Dockerfile). -- Base images: `cgr.dev/chainguard/wolfi-base:latest` or `cgr.dev/chainguard/static:latest`. - -## ABI/FFI Standard - -- ABI definitions: **Idris2** with dependent types (`src/abi/`). -- FFI implementation: **Zig** with C ABI compatibility (`ffi/zig/`). -- Generated C headers: `generated/abi/`. - -## Build System - -Use `just` (Justfile) for all build, test, lint, and format tasks. - -## References - -- `0-AI-MANIFEST.a2ml` -- universal AI entry point -- `.machine_readable/6a2/AGENTIC.a2ml` -- agent permissions and constraints -- `.machine_readable/6a2/STATE.a2ml` -- current project state -- `.machine_readable/6a2/anchors/ANCHOR.a2ml` -- canonical authority and policy boundary -- `.machine_readable/policies/MAINTENANCE-AXES.a2ml` -- canonical axis sequencing and audit requirements -- `.machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml` -- baseline maintenance checklist policy -- `.machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml` -- axis execution approach policy diff --git a/docs/practice/README.adoc b/docs/practice/README.adoc deleted file mode 100644 index caceb5c..0000000 --- a/docs/practice/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= practice Unit diff --git a/docs/practice/STATE-VISUALIZER-GUIDE.adoc b/docs/practice/STATE-VISUALIZER-GUIDE.adoc deleted file mode 100644 index 4fcbddd..0000000 --- a/docs/practice/STATE-VISUALIZER-GUIDE.adoc +++ /dev/null @@ -1,156 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= TOPOLOGY.md — Generation Guide -{{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -:toc: -:sectnums: - -== What Is TOPOLOGY.md? - -A single-file visual map of any project's architecture and completion status. -It lives in the repo root and contains: - -1. **ASCII architecture diagram** — the full system as it will look when complete -2. **Completion dashboard** — every component with a progress bar and status note -3. **Dependency graph** — what blocks what (the critical path) -4. **Update protocol** — how to keep it current - -It is designed to be readable by humans, AI agents, and rendered cleanly on any -forge (GitHub, GitLab, Codeberg, Bitbucket). - -== Why - -- Gives any contributor (human or AI) an instant picture of the whole project -- Replaces "read 20 files to understand the architecture" with one glance -- The completion dashboard makes project health visible without running anything -- Works offline, no tooling required, just a text file - -== How To Generate One - -=== Option 1: Ask an AI agent - -Use this prompt (works with Claude, Gemini, ChatGPT, or any LLM with repo access): - -[source,text] ----- -Read the entire repository and produce a TOPOLOGY.md file for the repo root. - -The file must contain exactly three sections: - -1. **System Architecture** — An ASCII box diagram showing the complete system - as it will look when finished. Use Unicode box-drawing characters - (┌ ┐ └ ┘ │ ─ ├ ┤ ┬ ┴ ┼), arrows (▲ ▼ ◄ ► → ←), and double lines - (═ ║) for boundaries. Show: - - All external services (DNS, CDN, gateways) at the top - - Application components in the middle - - Data layer (databases, caches, queues) below - - Repo infrastructure (CI, contractiles, SCM files) at the bottom - - Every box labelled, every connection labelled or obvious from context - - The diagram should be BESPOKE to this project, not generic - -2. **Completion Dashboard** — A table in a code block listing every component - from the diagram. For each component show: - - Name (left-aligned, padded to 35 chars) - - Progress bar: 10 characters using █ (done) and ░ (remaining) - - Percentage (0% to 100% in 10% increments) - - A short note explaining the status - Group components by layer/concern. End with an OVERALL summary line. - -3. **Key Dependencies** — An ASCII arrow diagram showing the critical path. - What must finish before what else can start. - -Add a header comment with SPDX-License-Identifier and Last updated date. -End with an "Update Protocol" section explaining how to maintain the file. - -Use the template at TOPOLOGY.md in rsr-template-repo as a structural reference, -but make the content completely specific to THIS project. ----- - -=== Option 2: Copy the template and fill it in - -[source,bash] ----- -cp /path/to/rsr-template-repo/TOPOLOGY.md ./TOPOLOGY.md -# Then edit: replace placeholders, draw the real architecture, fill the dashboard ----- - -=== Option 3: Batch generation across all repos - -[source,bash] ----- -# From the repos root, generate for every repo that lacks one -for repo in /path/to/your/repos/*/; do - if [ ! -f "$repo/TOPOLOGY.md" ]; then - echo "NEEDS TOPOLOGY: $(basename $repo)" - fi -done ----- - -Then feed each repo to an AI agent with the prompt above. Claude Code can do -this with a session per repo, or you can batch it. - -== Conventions - -=== Box-drawing characters - -Use Unicode, not ASCII art. This renders correctly everywhere. - -[cols="1,1", options="header"] -|=== -| Character | Use -| `┌ ┐ └ ┘` | Box corners -| `│ ─` | Vertical / horizontal lines -| `├ ┤ ┬ ┴ ┼` | T-junctions and crosses -| `═ ║` | Double lines for major boundaries -| `▲ ▼ ◄ ►` | Directional arrows -| `→ ← ↑ ↓` | Thin arrows (alternative) -|=== - -=== Progress bars - -Always 10 characters wide. Use full blocks only (no half-blocks). - -[source,text] ----- -░░░░░░░░░░ 0% Not started -█░░░░░░░░░ 10% Stub/skeleton exists -██░░░░░░░░ 20% Early work -███░░░░░░░ 30% Foundation laid -████░░░░░░ 40% Core logic started -█████░░░░░ 50% Half done -██████░░░░ 60% Most logic complete -███████░░░ 70% Working but rough -████████░░ 80% Needs polish/docs -█████████░ 90% Nearly done -██████████ 100% Complete and tested ----- - -=== Component naming - -- Use the actual names from the codebase (file names, service names, tool names) -- Group by architectural layer, not alphabetically -- Include repo infrastructure (CI, contractiles, SCM files) as a layer - -=== When to update - -- After completing a component → change bar + percentage -- After adding a component → add row -- After architectural change → redraw diagram -- After major milestone → update overall percentage -- Always update the `Last updated` date - -== Integration With Other RSR Files - -TOPOLOGY.md complements but does not replace: - -- **STATE.a2ml** — machine-readable state (tasks, blockers, next actions) -- **ECOSYSTEM.a2ml** — position in the wider project ecosystem -- **META.a2ml** — architecture decisions and design rationale -- **0-AI-MANIFEST.a2ml** — AI agent entry point and invariants - -TOPOLOGY.md is the _visual summary_ for humans; the a2ml files are the -_structured data_ for tooling. Both should agree. - -== Copyright - -Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> diff --git a/docs/practice/ci-cost-reduction.adoc b/docs/practice/ci-cost-reduction.adoc deleted file mode 100644 index 45181aa..0000000 --- a/docs/practice/ci-cost-reduction.adoc +++ /dev/null @@ -1,279 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -// (MPL-2.0 is automatic legal fallback until PMPL is formally recognised) -= CI Cost Reduction — RSR Estate Spec -:toc: left -:toclevels: 3 - -Estate-wide playbook for reducing GitHub Actions minutes consumption -without sacrificing CI coverage. Born out of an incident where the -`hyperpolymath` Actions billing tripped and every runner-based workflow -in the estate went dark. The blocker was external, but the exposure — -how much we spend — was self-inflicted. This document captures the -knobs that exist, which ones are worth pulling, and in what order. - -Priority sort applied: *dependability > security > interop > usability -> performance > versatility > functional extension*. Cost reduction is -a dependability/performance concern; nothing here trades security for -savings. - -== Why this is worth doing - -A representative RSR repo (007) runs ~26 active workflows. On a single -push: - -* ~10-15 workflows fire in parallel. -* Several (scorecard, codeql, hypatia-scan) also fire on a schedule. -* `oracle-fuzz.yml` runs a 10-minute differential job every hour. -* Multiple workflows do `fetch-depth: 0` full-history clones. -* There are meaningful overlaps (trufflehog + gitleaks, multiple - security-gate jobs, codeql + hypatia-scan). - -Conservative saving potential from the five highest-leverage patterns -below: *60–80%* of current Actions-minutes, with no coverage loss. - -== Priority-ordered patterns - -=== 1. Concurrency kills (one-line, estate-wide) - -Every push-triggered workflow should cancel its superseded runs when -a rapid-fire commit lands: - -[source,yaml] ----- -concurrency: - group: ${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: true ----- - -Add this at the workflow top level. Exceptions: release workflows, -deploy workflows, scheduled workflows — those need to finish. - -*Impact:* cancels obsolete runs immediately. On active branches with -many commits, easily 20–40% of current minutes. - -=== 2. Path filters on heavy workflows - -Rust CI, CodeQL, E2E, and language-specific test suites should not run -on docs-only or comment-only changes. - -[source,yaml] ----- -on: - push: - paths: - - 'src/**' - - 'crates/**' - - 'Cargo.toml' - - 'Cargo.lock' - - '.github/workflows/rust-ci.yml' - pull_request: - paths: - - 'src/**' - - 'crates/**' - - 'Cargo.toml' - - 'Cargo.lock' ----- - -For workflows whose scope is "the whole repo" (scorecard, codeql, -hypatia-scan): leave unfiltered. For language-specific jobs: filter. - -*Impact:* single largest saving on repos that get a lot of README or -issue-template churn. - -=== 3. Reduce schedule frequency - -Scheduled workflows should run as often as the decision they inform -actually changes — not more. - -[cols="2,1,1,2",options="header"] -|=== -| Workflow | Current | Recommended | Rationale - -| `oracle-fuzz.yml` (differential fuzz) -| Every 10 min -| Every 6h or nightly -| TRG §5.7.4 90-day differential-fuzzing clock measures *total time*, - not *frequency*. A nightly 10-min slice gives the same statistical - coverage at 1/144 the cost. - -| `scorecard.yml` -| Daily -| Weekly -| OSSF's own recommendation is weekly for stable repos. - -| `codeql.yml` (schedule branch) -| Daily -| Weekly, or remove schedule (relies on push trigger) -| CodeQL on every push already covers PR and main commits. A weekly - sweep catches newly-disclosed CVEs that affect existing code. - -| `hypatia-scan.yml` -| Weekly -| Keep weekly -| Correct cadence. Don't change. - -| `parser-fuzz.yml` (if present) -| Nightly, 5 min per target × 3 targets -| Keep -| Already minimal. -|=== - -=== 4. Overlap consolidation - -Several workflows cover overlapping ground. Consolidate where the -substitution is near-free: - -[cols="2,2,2",options="header"] -|=== -| Overlap | Resolution | Notes - -| `trufflehog` + `gitleaks` in `secret-scanner.yml` -| Keep one (gitleaks preferred for CVE coverage; trufflehog for - verified-only mode) -| Running both is belt-and-braces with ~90% coverage overlap. One is - enough for prevention; both only for quarterly history-sweeps. - -| `rsr-antipattern.yml` + `scorecard-enforcer.yml` + - `static-analysis-gate.yml` -| Merge into a single composite `rsr-gate.yml` with three steps -| They already run in the same CI slot; merging deduplicates - setup/checkout/clone. - -| `codeql.yml` + `hypatia-scan.yml` -| Keep both, but drop Hypatia from on-push; let it run only on - schedule -| Hypatia is the slower of the two, and its neurosymbolic analysis - doesn't need sub-minute latency on every commit. - -| `codeql.yml` (on-push) + `codeql.yml` (scheduled) -| Keep on-push, drop scheduled -| Redundant unless the repo rarely gets commits. -|=== - -=== 5. Shallow clones where full-history isn't needed - -Full-history clones (`fetch-depth: 0`) are expensive on large repos. -Required for: - -* Scorecard (history-based metrics). -* Gitleaks history-sweep mode. -* TruffleHog history-sweep mode. - -Not required for: - -* PR-event secret scanning (limit to the PR delta). -* Rust CI, language-specific tests. -* CodeQL (shallow is fine). -* Hypatia-scan (shallow is fine for pattern detection). - -Pattern for secret-scanner: - -[source,yaml] ----- -on: - pull_request: # shallow clone, just the diff - push: - branches: [main] - schedule: - - cron: '0 4 * * 1' # weekly history sweep - -jobs: - pr-scan: - if: github.event_name == 'pull_request' - # shallow — don't need history for delta scanning - steps: - - uses: actions/checkout@... - full-scan: - if: github.event_name != 'pull_request' - steps: - - uses: actions/checkout@... - with: - fetch-depth: 0 # only for push-to-main + scheduled ----- - -=== 6. Job-level timeouts - -Cap every job so a hung runner doesn't burn the budget: - -[source,yaml] ----- -jobs: - build: - runs-on: ubuntu-latest - timeout-minutes: 20 # fail-fast instead of 360 default ----- - -Recommendations: - -* Setup / lint / format jobs: 5 min. -* Build jobs: 15–20 min. -* Test jobs: 20–30 min. -* E2E / integration: 45 min max. -* Fuzz: exact target time + 2 min tolerance. - -=== 7. Reusable workflow (longer-term) - -Ship the above patterns in a single reusable workflow under -`rsr-template-repo/.github/workflows/rsr-ci-defaults.yml`, and adopt -it estate-wide via `uses: hyperpolymath/rsr-template-repo/.github/workflows/rsr-ci-defaults.yml@main` -in downstream repos. Single PR propagates improvements. - -=== 8. Self-hosted runner for heavy work (long-term) - -Oracle-fuzz, E2E+Conformance+Bench, Hypatia-scan: these are the -expensive jobs. Moving them to a self-hosted runner on the Eclipse -host gets the cost to zero ongoing. Setup: ~1 day. Security: run in -a rootless Podman container with the `ubuntu-22.04` runner image. -Not urgent; track as future work. - -=== 9. Dependabot noise - -`.github/dependabot.yml` in this template uses -`open-pull-requests-limit: 0` on cargo to suppress routine patch PRs -while keeping security PRs flowing. That's the correct pattern — do -NOT revert to the previous `ignore: "*" patch` rule, which also -silences security PRs (see -007-lang/audits/audit-dependabot-automation-gap-2026-04-17.md). - -Paired with `.github/workflows/dependabot-automerge.yml`, security -PRs for low/moderate patches+minors auto-merge after CI, leaving -humans to review only HIGH+CRITICAL security updates and all -non-security bumps. - -== Rollout plan - -. *Week 1:* Apply patterns 1–2 (concurrency + path filters) to every - active RSR repo. Reusable template update; downstream propagation - is a find-and-replace pass. -. *Week 2:* Apply patterns 3–4 (schedule frequency + overlap - consolidation). Audit one repo at a time; check ~30 days of runs - before concluding an overlap is safe to drop. -. *Week 3:* Apply patterns 5–6 (shallow clone + timeouts). Low-risk. -. *Week 4+:* Pattern 7 (reusable workflow) — single PR, big payoff. -. *When scope allows:* Pattern 8 (self-hosted runner). - -== Measurement - -Before/after: `gh api /users//settings/billing/actions` shows -current minutes usage. Diff after each rollout wave. Target a 60% -reduction by end of week 4 on the three highest-consumption repos -(boj-server, hypatia, 007 — based on workflow count × schedule -frequency × job count). - -== Out of scope - -* Reducing CI coverage (not on the table). -* Disabling security workflows to save minutes. -* Skipping CI on "trivial" commits via commit-message tags - (gameable, easy to abuse). -* Switching to a paid Actions tier before exhausting these patterns. - -== Cross-references - -* `007-lang/audits/audit-rsr-workflows-2026-04-17.md` — billing - incident that motivated this spec. -* `007-lang/audits/audit-dependabot-automation-gap-2026-04-17.md` — - separate defect stack also addressed in the same session. -* `rsr-template-repo/.github/workflows/dependabot-automerge.yml` — - canonical pattern for auto-merge pattern referenced above. diff --git a/docs/proposals/root-cleanup.adoc b/docs/proposals/root-cleanup.adoc deleted file mode 100644 index c35ba34..0000000 --- a/docs/proposals/root-cleanup.adoc +++ /dev/null @@ -1,233 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Root Cleanup Proposal — Reconcile Template With Its Own Audit -:toc: -:toclevels: 3 -:sectnums: - -== Motivation - -`TEMPLATE-STANDARDS-AUDIT.adoc` ships a "Proposed Final Directory Map" for the -template root. The tracked root violates that map by roughly 5x: - -[cols="1,1,1",options="header"] -|=== -| Bucket | Audit-mandated count | Actual count - -| Root files (visible) -| 6 -| 36 - -| Root directories (visible) -| 3 -| 17 -|=== - -Downstream repositories (e.g. `the-nash-equilibrium`) inherit the violation -verbatim. This proposal describes the relocations that bring the template back -into compliance with its own map, and adds an automated guard -(`scripts/check-root-shape.sh` against `.machine_readable/root-allow.txt`) so -the violation cannot silently return. - -NOTE: This is a template-side change. Downstream repos pick it up via a -one-shot relocation PR per project once the template lands. - -== Allowlist (canonical root) - -The full enumeration lives in `.machine_readable/root-allow.txt`. Summary: - -* *Authority files (root):* `README.adoc`, `AUDIT.adoc`, `EXPLAINME.adoc`, - `0-AI-MANIFEST.a2ml` (thin pointer), `LICENSE`, `CHANGELOG.md`. -* *Build entry points (root):* `Justfile`, `coordination.k9`. -* *Tool-required dotfiles (root):* `.editorconfig`, `.envrc`, `.gitattributes`, - `.gitignore`, `.tool-versions`. -* *Directories (root):* `.git/`, `.github/`, `.machine_readable/`, - `.well-known/`, `build/`, `ci/`, `docs/`, `session/`, plus the conventional - source/test trees (`src/`, `tests/`, `benches/`, `examples/`, `features/`, - `scripts/`, `verification/`, `container/`). - -== Relocation plan - -Each line is a `git mv` (or delete) plus the references that need updating. -Run from the template repo root. - -=== Onboarding prose → `docs/onboarding/` - -[source,bash] ----- -mkdir -p docs/onboarding -git mv QUICKSTART-DEV.adoc docs/onboarding/ -git mv QUICKSTART-USER.adoc docs/onboarding/ -git mv QUICKSTART-MAINTAINER.adoc docs/onboarding/ -git mv llm-warmup-dev.md docs/onboarding/ -git mv llm-warmup-user.md docs/onboarding/ ----- - -References to update: - -* `README.adoc` — any `link:QUICKSTART-*.adoc[…]`. -* `Justfile` — any `cat QUICKSTART-*` echoes in `init`/`help`. - -=== Status/roadmap docs → `docs/status/` - -[source,bash] ----- -mkdir -p docs/status docs/architecture -git mv READINESS.md docs/status/ -git mv ROADMAP.adoc docs/status/ -git mv TEST-NEEDS.md docs/status/ -git mv PROOF-NEEDS.md docs/status/ -git mv PROOF-STATUS.md docs/status/ -git mv TOPOLOGY.md docs/architecture/ # validate-template.sh already accepts this path ----- - -References to update: - -* `README.adoc` — `link:ROADMAP.adoc[…]` and similar. -* `Justfile` — `readiness:` recipe (currently reads `READINESS.md`). - -=== Health files → `.github/` - -GitHub auto-discovers these under `.github/`, so the move is transparent to -contributors and tools. - -[source,bash] ----- -git mv CONTRIBUTING.md .github/ -git mv CODE_OF_CONDUCT.md .github/ -git mv SECURITY.md .github/ ----- - -=== Build orchestration → `build/` - -`Justfile` stays at root (just convention) but becomes thin: it imports -phase-specific just files from `build/`. - -[source,bash] ----- -mkdir -p build -git mv contractile.just build/ -git mv setup.sh build/ -git mv flake.nix build/ -[ -f flake.lock ] && git mv flake.lock build/ -git mv guix.scm build/ -git mv .guix-channel build/ -# Containerfile may already live in container/ — keep whichever the project uses. -[ -f Containerfile ] && git mv Containerfile build/ ----- - -References to update in `Justfile`: - -[source,diff] ----- -- import? "contractile.just" -+ import? "build/contractile.just" ----- - -The current Justfile already supports `container/Containerfile` *or* root -`Containerfile` — extend that to also accept `build/Containerfile`. - -The 62 KB monolithic `Justfile` is a separate smell. A follow-up should split -it under `build/just/{init,verify,test,docs,container,security}.just` with -`import?` lines from the thin root file. - -=== CI configs → `ci/` - -Most CI tools accept a custom config path; where they don't, a one-line root -shim file is acceptable. - -[source,bash] ----- -mkdir -p ci -git mv .gitlab-ci.yml ci/ -git mv .pre-commit-config.yaml ci/ ----- - -Updates required: - -* GitLab CI: project setting "CI/CD configuration file" → `ci/.gitlab-ci.yml`. -* pre-commit: invoke as `pre-commit run --config ci/.pre-commit-config.yaml`, - or leave a one-line root shim. - -=== Custom-format configs → `.machine_readable/configs/` - -[source,bash] ----- -git mv eclexiaiser.toml .machine_readable/configs/ -git mv selur-compose.toml .machine_readable/configs/ -git mv stapeln.toml .machine_readable/configs/ ----- - -References to update wherever any tool reads them (grep for the filenames -across `Justfile`, `scripts/`, `.machine_readable/`). - -=== AI manifest deduplication - -`.machine_readable/0.1-AI-MANIFEST.a2ml` is the canonical AI manifest in both -the template and downstream repos (e.g. `the-nash-equilibrium` README line -244). The root `0-AI-MANIFEST.a2ml` becomes a thin pointer: - -[source,a2ml] ----- -# 0-AI-MANIFEST.a2ml — pointer file -authority = ".machine_readable/0.1-AI-MANIFEST.a2ml" -note = "AI agents MUST read the canonical manifest at the path above." ----- - -Once the canonical version is stable, decide whether to keep this pointer at -root or delete it entirely. - -=== Template-only relocations - -A dry-run of `check-root-shape.sh` against the unmodified template flagged -three template-only extras that aren't drift in downstream repos but should -move regardless: - -[source,bash] ----- -# The audit doc itself is drift — it doesn't apply at root. -git mv TEMPLATE-STANDARDS-AUDIT.adoc docs/governance/ - -# `tools/` and `scripts/` overlap; pick one (proposal: keep `scripts/`). -# Inspect tools/ contents and either merge into scripts/ or rename and document -# the split (e.g. `scripts/` = repo-local helpers, `tools/` = bundled binaries). ----- - -=== Hygiene: case collisions in `affinescript/stdlib/` - -Cloning the template on a case-insensitive filesystem (Windows, default macOS) -silently drops files because of pairs like `Math.affine` vs `math.affine`. - -Pick one canonical case per name and `git mv` the duplicates away. Keeping -both is not portable. - -== Justfile recipe - -[source,just] ----- -# Verify root layout against the canonical allowlist. -check-root-shape: - ./scripts/check-root-shape.sh - -# Add to the existing aggregate `verify` target. -verify: ... check-root-shape ... ----- - -A pre-commit hook (in `ci/.pre-commit-config.yaml`) and a CI job -(`ci/.gitlab-ci.yml`) should both call `just check-root-shape`. - -== Downstream rollout - -For each downstream repo (start with `the-nash-equilibrium`): - -1. Apply the same `git mv` set (skip moves whose source doesn't exist locally). -2. Copy the new `.machine_readable/root-allow.txt` and adapt comments/extras. -3. Update internal links (README, docs, Justfile recipes). -4. Run `just check-root-shape` and `scripts/validate-template.sh` to confirm - shape parity with the template. - -== Out of scope (mentioned for follow-up) - -* Splitting the 62 KB monolithic `Justfile`. -* Migrating from GitLab CI to GitHub Actions parity (or vice versa). -* Reworking the `0.1-` / `0.2-` manifest versioning convention. diff --git a/docs/reports/0.2-AI-MANIFEST.a2ml b/docs/reports/0.2-AI-MANIFEST.a2ml deleted file mode 100644 index 5eb265d..0000000 --- a/docs/reports/0.2-AI-MANIFEST.a2ml +++ /dev/null @@ -1,19 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "reports-unit" -level: 2 -parent: "../0.1-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Documentation unit for all automated and manual audit reports. Classified - by domain. - -canonical_locations: - maintenance: "maintenance/" - security: "security/" - performance: "performance/" - compliance: "compliance/" - quality: "quality/" diff --git a/docs/reports/README.adoc b/docs/reports/README.adoc deleted file mode 100644 index e91d79e..0000000 --- a/docs/reports/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= reports Unit diff --git a/docs/reports/audit/pillar-audit-2026-04-15.adoc b/docs/reports/audit/pillar-audit-2026-04-15.adoc deleted file mode 100644 index c62d4bd..0000000 --- a/docs/reports/audit/pillar-audit-2026-04-15.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Gemini Audit Report (M2: Pillar Repo Audits) -:date: 2026-04-15 - -Date: 2026-04-15 + -Repository: `/var/mnt/eclipse/repos/rsr-template-repo` - -== Audit Criteria - -* *Dangerous Patterns*: *CLEAN*. -* *Standards Check*: -** `.machine_readable/*.a2ml`: `0-AI-MANIFEST.a2ml` present. -** `Justfile`: *PRESENT*. -** `K9.k9` / `coordination.k9`: *PRESENT* (`coordination.k9`). -* *CI/CD Status*: `.github/workflows` and `.gitlab-ci.yml` *PRESENT*. -* *Documentation Parity*: Template repo claims. -* *Template Residue*: *HIGH* (Expected as it is the template itself). - -== Verdict - -* *CRG Grade*: A (Template) -* *Publishable?*: YES diff --git a/docs/reports/compliance/0.3-AI-MANIFEST.a2ml b/docs/reports/compliance/0.3-AI-MANIFEST.a2ml deleted file mode 100644 index 6b39752..0000000 --- a/docs/reports/compliance/0.3-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "report-unit-compliance" -level: 3 -parent: "../0.2-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Specialised repository for compliance findings and evidence. diff --git a/docs/reports/compliance/README.adoc b/docs/reports/compliance/README.adoc deleted file mode 100644 index 1f6b885..0000000 --- a/docs/reports/compliance/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Compliance Reports diff --git a/docs/reports/maintenance/0.3-AI-MANIFEST.a2ml b/docs/reports/maintenance/0.3-AI-MANIFEST.a2ml deleted file mode 100644 index 43eefe2..0000000 --- a/docs/reports/maintenance/0.3-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "report-unit-maintenance" -level: 3 -parent: "../0.2-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Maintenance reports. diff --git a/docs/reports/maintenance/README.adoc b/docs/reports/maintenance/README.adoc deleted file mode 100644 index 82f845e..0000000 --- a/docs/reports/maintenance/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Maintenance Reports diff --git a/docs/reports/performance/0.3-AI-MANIFEST.a2ml b/docs/reports/performance/0.3-AI-MANIFEST.a2ml deleted file mode 100644 index 40c0954..0000000 --- a/docs/reports/performance/0.3-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "report-unit-performance" -level: 3 -parent: "../0.2-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Specialised repository for performance findings and evidence. diff --git a/docs/reports/performance/README.adoc b/docs/reports/performance/README.adoc deleted file mode 100644 index 6473ed3..0000000 --- a/docs/reports/performance/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Performance Reports diff --git a/docs/reports/quality/0.3-AI-MANIFEST.a2ml b/docs/reports/quality/0.3-AI-MANIFEST.a2ml deleted file mode 100644 index d460edc..0000000 --- a/docs/reports/quality/0.3-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "report-unit-quality" -level: 3 -parent: "../0.2-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Specialised repository for quality findings and evidence. diff --git a/docs/reports/quality/README.adoc b/docs/reports/quality/README.adoc deleted file mode 100644 index dbdb3ba..0000000 --- a/docs/reports/quality/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Quality Reports diff --git a/docs/reports/security/0.3-AI-MANIFEST.a2ml b/docs/reports/security/0.3-AI-MANIFEST.a2ml deleted file mode 100644 index 696ab59..0000000 --- a/docs/reports/security/0.3-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "report-unit-security" -level: 3 -parent: "../0.2-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Specialised repository for security findings and evidence. diff --git a/docs/reports/security/README.adoc b/docs/reports/security/README.adoc deleted file mode 100644 index 76656cc..0000000 --- a/docs/reports/security/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Security Reports diff --git a/docs/standards/0.2-AI-MANIFEST.a2ml b/docs/standards/0.2-AI-MANIFEST.a2ml deleted file mode 100644 index c147c6f..0000000 --- a/docs/standards/0.2-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "standards-unit" -level: 2 -parent: "../0.1-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Standards unit for high-rigor verification. diff --git a/docs/standards/README.adoc b/docs/standards/README.adoc deleted file mode 100644 index 41f7a31..0000000 --- a/docs/standards/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Standards Unit diff --git a/docs/status/PROOF-NEEDS.adoc b/docs/status/PROOF-NEEDS.adoc deleted file mode 100644 index b907af8..0000000 --- a/docs/status/PROOF-NEEDS.adoc +++ /dev/null @@ -1,122 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -// Template: rsr-template-repo/docs/status/PROOF-NEEDS.adoc -// Authoritative master list: ~/Desktop/PROOF-REQUIREMENTS-MASTER.adoc -= Proof Requirements — {{PROJECT}} - -== Proof Tier - -// Assign one: T1 (Critical), T2 (High), T3 (Standard), T4 (Light), T5 (Exempt) -*Tier*: T3 — Standard - -== Proof Categories - -[cols="1,3,1", options="header"] -|=== -| Code | Meaning | Applies? - -| *TP* | Typing Proofs (type soundness, type safety) | Yes -| *INV* | Invariant Proofs (state machines, monotonicity, bounds) | -| *SEC* | Security Proofs (crypto, injection freedom, access control) | -| *CONC* | Concurrency Proofs (linearizability, deadlock freedom) | -| *ALG* | Algorithm Proofs (termination, correctness, bounds) | -| *ABI* | ABI/FFI Proofs (memory layout, pointer safety, platform compat) | Yes -| *DOM* | Domain-Specific Proofs (bespoke to this project) | -|=== - -== Mandatory Proofs (All RSR Repos) - -These proofs come from the rsr-template-repo and MUST be present in every repo: - -=== ABI/FFI Boundary Proofs (Idris2) - -[cols="1,3,1,3", options="header"] -|=== -| # | Proof | Status | File - -| ABI-1 | Non-null pointer proofs (`So (ptr /= 0)`) | Needed | `verification/proofs/idris2/ABI/Pointers.idr` -| ABI-2 | Memory layout correctness (`HasSize`, `HasAlignment`) | Needed | `verification/proofs/idris2/ABI/Layout.idr` -| ABI-3 | Platform type size proofs (per platform) | Needed | `verification/proofs/idris2/ABI/Platform.idr` -| ABI-4 | FFI function return type proofs | Needed | `verification/proofs/idris2/ABI/Foreign.idr` -| ABI-5 | C ABI compliance (`CABICompliant`, `FieldsAligned`) | Needed | `verification/proofs/idris2/ABI/Compliance.idr` -|=== - -=== Typing Proofs (Prover Varies) - -[cols="1,3,1,3", options="header"] -|=== -| # | Proof | Status | File - -| TP-1 | Core data type well-formedness | Needed | `verification/proofs/idris2/Types.idr` -| TP-2 | Public API type safety (exported functions) | Needed | `verification/proofs/lean4/ApiTypes.lean` -|=== - -== Project-Specific Proofs - -// Fill in proofs specific to this project. Copy from PROOF-REQUIREMENTS-MASTER.adoc -// Delete this section for T4/T5 repos - -[cols="1,3,1,1,1,2", options="header"] -|=== -| # | Proof Needed | Category | Prover | Priority | File(s) - -| | | | | | -|=== - -== Dangerous Patterns (BANNED) - -The following MUST NOT appear anywhere in proof files: - -[cols="2,2,3", options="header"] -|=== -| Pattern | Language | Meaning - -| `believe_me` | Idris2 | Unsafe cast / trust-me -| `assert_total` | Idris2 | Skip totality check -| `postulate` | Idris2/Agda | Unproven axiom -| `sorry` | Lean4 | Incomplete proof -| `Admitted` | Coq | Incomplete proof -| `unsafeCoerce` | Haskell | Unsafe type cast -| `Obj.magic` | OCaml/ReScript | Unsafe type cast -| `unsafe` (unaudited) | Rust | Unsafe block without safety comment -|=== - -CI will reject any PR introducing these patterns (enforced by `panic-attack assail`). - -== Prover Selection Guide - -[cols="2,2,3", options="header"] -|=== -| Use Case | Recommended Prover | Why - -| ABI/FFI boundaries | *Idris2* | Dependent types model layouts precisely -| Type system proofs | *Coq* or *Lean4* | Mature proof assistants for metatheory -| Algebraic properties | *Lean4* | Good mathlib support -| Inductive/coinductive | *Agda* | Native support for (co)induction -| Distributed systems | *TLA+* | Model checking for protocols -| Numerical properties | *Isabelle* | Strong real analysis library -|=== - -== Proof File Locations - ----- -verification/proofs/ -├── idris2/ # Idris2 proofs (ABI, dependent types) -│ ├── ABI/ # ABI-specific proofs -│ └── *.idr # Project-specific Idris2 proofs -├── lean4/ # Lean4 proofs (algebra, lattices) -│ └── *.lean -├── agda/ # Agda proofs (induction, metatheory) -│ └── *.agda -├── coq/ # Coq proofs (type systems, compilation) -│ └── *.v -└── tlaplus/ # TLA+ specs (distributed protocols) - └── *.tla ----- - -== References - -* Master list: `~/Desktop/PROOF-REQUIREMENTS-MASTER.adoc` -* Proof status tracking: `PROOF-STATUS.adoc` (this repo) -* Proven library: `proven` repo (Idris2 verified foundations) -* Template: `rsr-template-repo/docs/status/PROOF-NEEDS.adoc` diff --git a/docs/status/PROOF-STATUS.adoc b/docs/status/PROOF-STATUS.adoc deleted file mode 100644 index 721c464..0000000 --- a/docs/status/PROOF-STATUS.adoc +++ /dev/null @@ -1,101 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -// Template: rsr-template-repo/docs/status/PROOF-STATUS.adoc -// Tracks proof completion. Requirements defined in PROOF-NEEDS.adoc -= Proof Status — {{PROJECT}} - -== Summary - -[cols="2,1,1,1,1,1", options="header"] -|=== -| Category | Total | Done | In Progress | Blocked | Remaining - -| ABI/FFI (ABI) | 5 | 0 | 0 | 0 | 5 -| Typing (TP) | 2 | 0 | 0 | 0 | 2 -| Invariant (INV) | 0 | 0 | 0 | 0 | 0 -| Security (SEC) | 0 | 0 | 0 | 0 | 0 -| Concurrency (CONC) | 0 | 0 | 0 | 0 | 0 -| Algorithm (ALG) | 0 | 0 | 0 | 0 | 0 -| Domain (DOM) | 0 | 0 | 0 | 0 | 0 -| *Total* | *7* | *0* | *0* | *0* | *7* -|=== - -*Overall*: 0% proven - -== Proofs Done - -// Format: -// | ID | Proof | Prover | File | Date | Verified By | -// | ABI-1 | Non-null pointer proofs | Idris2 | verification/proofs/idris2/ABI/Pointers.idr | 2026-XX-XX | idris2 --check | - -[cols="1,3,1,3,1,2", options="header"] -|=== -| ID | Proof | Prover | File | Date | Verified By - -| — | No proofs completed yet | — | — | — | — -|=== - -== Proofs In Progress - -[cols="1,3,1,2,1,2", options="header"] -|=== -| ID | Proof | Prover | Assignee | Started | Blocker - -| — | — | — | — | — | — -|=== - -== Proofs Blocked - -[cols="1,3,2,3", options="header"] -|=== -| ID | Proof | Blocked By | Notes - -| — | — | — | — -|=== - -== Proofs Remaining - -[cols="1,3,1,1,1,1", options="header"] -|=== -| ID | Proof | Category | Prover | Priority | Est. Effort - -| ABI-1 | Non-null pointer proofs | ABI | Idris2 | P1 | 2h -| ABI-2 | Memory layout correctness | ABI | Idris2 | P1 | 4h -| ABI-3 | Platform type size proofs | ABI | Idris2 | P1 | 2h -| ABI-4 | FFI function return type proofs | ABI | Idris2 | P1 | 2h -| ABI-5 | C ABI compliance | ABI | Idris2 | P1 | 4h -| TP-1 | Core data type well-formedness | TP | Idris2 | P1 | 4h -| TP-2 | Public API type safety | TP | Lean4 | P2 | 4h -|=== - -== Verification Commands - -[source,bash] ----- -# Check all Idris2 proofs -just proof-check-idris2 - -# Check all Lean4 proofs -just proof-check-lean4 - -# Check all Agda proofs -just proof-check-agda - -# Check all Coq proofs -just proof-check-coq - -# Run all proof checks -just proof-check-all - -# Scan for dangerous patterns -panic-attack assail --proofs-only ----- - -== Changelog - -[cols="1,3,1", options="header"] -|=== -| Date | Change | By - -| 2026-04-04 | Initial proof status tracking | Template -|=== diff --git a/docs/status/READINESS.adoc b/docs/status/READINESS.adoc deleted file mode 100644 index b06eedb..0000000 --- a/docs/status/READINESS.adoc +++ /dev/null @@ -1,186 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= {{PROJECT_NAME}} Component Readiness Assessment - -*Standard:* link:https://{{FORGE}}/{{OWNER}}/standards/tree/main/component-readiness-grades[Component Readiness Grades (CRG) v2.0 STRICT] + -*Assessed:* {{CURRENT_DATE}} + -*Assessor:* {{AUTHOR}} + -*Previous assessment:* __ - -*Current Grade:* X - -This line is parsed by `just crg-grade` / `just crg-badge`. The grade above is -the worst-graded in-scope component — *the project's weakest link sets its -grade*. See the per-component table in §3. - -[NOTE] -==== -*Honest grading.* Per CRG v2.0 Principle 4: grade as-is today, not -aspirationally. Long alpha is discipline, not shame. Demote immediately if -evidence doesn't support the claim. -==== - -''' - -== 1. CRG v2.0 Grade Reference - -[cols="1,2,2,3,2", options="header"] -|=== -| Grade | Name | Release Stage | Stability Posture | Shorthand - -| X | Untested | — | — | — -| F | Harmful / Wasteful | — | — | reject/delegate -| E | Minimal / Salvageable | Pre-alpha | Unstable | `pre-alpha` -| D | Partial / Inconsistent| Alpha | Unstable | `alpha-unstable` -| C | Self-Validated | Alpha | Stable in home context | `alpha-stable` -| B | Broadly Validated | Beta | Stable for broad trial | `beta-stable` -| A | Field-Proven | Stable | Stable | `stable` -|=== - -*Evidence gates (v2.0 is stricter than v1.0):* - -* *D*: RSR-compliant + per-capability tests + documented scope. Test matrix - must cite counts and live in `.machine_readable/6a2/STATE.a2ml` or CI. -* *C*: All of D, plus active dogfooding in home context with *no known - home-context failures over an evidence window*, plus *deep per-file and - per-directory annotation* (purpose, boundaries, invariants, - execution/test/proof surfaces, per-directory orientation READMEs). - STATE.a2ml `[dogfooding-status]` populated with concrete "done — " - entries. -* *B*: All of C, plus *six genuinely diverse external targets* with - feedback fed back. STATE.a2ml `[external-targets]` holds target identities - + dates + outcomes; `[issues-fed-back]` holds the closed-issue trail. - Internal-capability items do *not* count. -* *A*: All of B, plus multi-source real-world external feedback confirming - value, no harm in the wild. STATE.a2ml `[field-signal]` populated. - -*Publication gate:* non-abstract implementation claims require *B+*. -Below B, any publication must be explicitly abstract or provisional. - -''' - -== 2. Headline Evidence (as of {{CURRENT_DATE}}) - -[cols="2,3,3", options="header"] -|=== -| Metric | Value | Source - -| Test count | __ | `.machine_readable/6a2/STATE.a2ml` or CI -| Formal-verification posture | __ | grep of proof dirs -| Dangerous patterns (`assert_total`, `unsafeCoerce`, `Obj.magic`) | __ | grep {{CURRENT_DATE}} -| Per-unit README coverage | __ | filesystem scan of unit dirs -| CI status | __ | `.github/workflows/` -| RSR mandatory workflows | __ | `.github/workflows/` -| Third-party badges (if any) | __ | external -| LIVE deployment (if any) | __ | production -|=== - -''' - -== 3. Component Assessment - -All components graded *as-is today*, per CRG v2.0 Principle 4. Stability -posture reflects the component's state *within its home context only* -unless noted. - -[cols="2,1,1,3,3,2", options="header"] -|=== -| Component | Grade | Posture | Evidence Summary | Promotion blocker | Last Assessed - -| __ | X/F/E/D/C/B/A | __ | __ | __ | {{CURRENT_DATE}} -| __ | … | … | … | … | {{CURRENT_DATE}} -| __ | … | … | … | … | {{CURRENT_DATE}} -|=== - -*Rules of thumb for populating this table:* - -* One row per independently-gradable unit. If a subsystem can ship or break - independently, it gets its own row. -* Evidence Summary must cite *numbers* (test counts, LOC, file counts) or - *paths* (e.g. `src/abi/Module.idr`), never vague claims. -* Promotion blocker must be *actionable* — "add external consumer in home - context, then annotate" beats "needs more validation". -* Re-assess every release cycle; date-stamp each row. - -''' - -== 4. What's Needed for D → C - -CRG v2.0 requires two new pieces of evidence on top of D: - -. *Active dogfooding in home context with no known home-context failures.* -** Start date: __. -** Home context: __. -** "No known failures" is a moving claim — must hold continuously across - the evidence window (recommended: 4 weeks, daily use). -** Populate `STATE.a2ml [dogfooding-status]` with one entry per capability: - `capability = "done — "`. - -. *Deep code and folder annotation.* -** Per-directory orientation READMEs in every non-trivial source subtree. -** Per-file header comments: purpose, boundaries, invariants, - execution/test/proof surface. -** Per-unit (cartridge/panel/plugin/module) README covering: purpose, - tools, architecture-at-a-glance, build steps. Overview-level alone is - not sufficient — depth is required where a reviewer would otherwise - have to read source to orient. - -*Minimum first-ring targets for C promotion:* list the trunk components -here. If these aren't C, nothing else can be. - -''' - -== 5. What's Needed for C → B - -Six *genuinely diverse* external targets with feedback fed back into the -component. Candidate diversity axes: - -* Different language runtime (not just variants of the same one). -* Different OS family (at least one must not be Linux). -* Different hardware class (cloud / server / desktop / embedded / mobile). -* Different auth posture (unauthenticated, API-key, vault-brokered, mTLS). -* Different topology (star, mesh, peer-to-peer). -* Different trust model (same-org, federated, adversarial). - -Populate `STATE.a2ml`: - -* `[external-targets]` — target-id → `" — — "`. -* `[issues-fed-back]` — issue-id → `" — — "`. - -Six variations of the same use case do *not* count. Re-classify any items -currently under `[grade-b-status]` (legacy) and move external-eligible ones -into `[external-targets]`. - -''' - -== 6. What's Needed for B → A - -Real-world external feedback confirming value. Populate -`STATE.a2ml [field-signal]` with multi-source entries: - -* External users beyond the six B-targets. -* Third-party writeups, talks, papers, or testimonials. -* No unresolved safety / correctness incidents in the last 90 days. - -''' - -== 7. Summary ({{CURRENT_DATE}}) - -* Project grade: __. Why: _<1-2 line justification>_. -* Delta since last assessment: __. -* Next milestone: __. -* Machine-readable grade line present (§ header) for `just crg-grade` / `just crg-badge`. - -''' - -== 8. Companion Artefacts - -* `docs/governance/CRG-CRITERIA.adoc` — grade definitions (boilerplate). -* `docs/governance/CRG-AUDIT-.adoc` — formal audit (populate from - `rsr-template-repo/docs/governance/CRG-AUDIT-TEMPLATE.adoc`). -* `docs/practice/DOGFOOD-LOG.adoc` — dated dogfood evidence (required for C). -* `.machine_readable/6a2/STATE.a2ml` — authoritative state (canonical keys - `[dogfooding-status]`, `[external-targets]`, `[issues-fed-back]`, - `[field-signal]`). - -_Run `just crg-badge` to generate the shields.io badge for your README._ diff --git a/docs/status/ROADMAP.adoc b/docs/status/ROADMAP.adoc deleted file mode 100644 index 128ed39..0000000 --- a/docs/status/ROADMAP.adoc +++ /dev/null @@ -1,23 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= YOUR Template Repo Roadmap - -== Current Status - -Initial development phase. - -== Milestones - -=== v0.1.0 - Foundation -* [ ] Core functionality -* [ ] Basic documentation -* [ ] CI/CD pipeline - -=== v1.0.0 - Stable Release -* [ ] Full feature set -* [ ] Comprehensive tests -* [ ] Production ready - -== Future Directions - -_To be determined based on community feedback._ diff --git a/docs/status/TEST-NEEDS.adoc b/docs/status/TEST-NEEDS.adoc deleted file mode 100644 index 8fd55fd..0000000 --- a/docs/status/TEST-NEEDS.adoc +++ /dev/null @@ -1,118 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= TEST-NEEDS: rsr-template-repo - -== CRG Grade: C — ACHIEVED 2026-04-04 - -== Current State (Updated 2026-04-04) - -[cols="2,1,4", options="header"] -|=== -| Category | Count | Details - -| *Source modules* | 6 | 3 Idris2 ABI (Foreign, Layout, Types), 2 Zig FFI (build, main), 1 Zig integration test template -| *Unit tests* | 0 | None in main source (inline tests in main.zig) -| *Integration tests* | 1 | `test/integration_test.zig` (documented template, 1 placeholder test) -| *E2E tests* | 1 | `tests/e2e/template_instantiation_test.sh` (full instantiation + validation) -| *Workflow tests* | 1 | `tests/workflows/validate_workflows_test.sh` (21 workflows validated) -| *Validation tests* | 1 | `scripts/validate-template.sh` (8-phase comprehensive validation) -| *Benchmarks* | 5 | `benches/template_bench.sh` (validation, Zig build, tests, workflows, instantiation) -| *Fuzz tests* | 0 | `README.adoc` scaffold with harness instructions -|=== - -== Completed Work (CRG C - Testing & Benchmarking) - -=== Template Validation Script ✅ - -* [x] `scripts/validate-template.sh` — 8-phase validation -** Phase 1: Core repository structure (root files, directories) -** Phase 2: Machine-readable metadata (`.machine_readable/`) -** Phase 3: GitHub Actions workflows (17 required + all present) -** Phase 4: Idris2 ABI and Zig FFI source files -** Phase 5: Placeholder token replacement (skipped in template) -** Phase 6: SPDX license headers (100% coverage, 6/6 files) -** Phase 7: Build system verification (`zig build` + `idris2` syntax check) -** Phase 8: Documentation requirements (TOPOLOGY, ABI-FFI-README, etc) -* Status: *PASSING* (0 errors, 3 warnings about template placeholders) - -=== E2E Template Instantiation Test ✅ - -* [x] `tests/e2e/template_instantiation_test.sh` — full workflow -** Clones template to temp directory -** Replaces all `{{PLACEHOLDER}}` tokens with test values -** Validates resulting structure with `scripts/validate-template.sh` -** Verifies Zig build works after instantiation -** Checks no remaining placeholders -** Cleans up temp directory -* Status: *READY TO TEST* (can be verified by CI) - -=== Workflow Validation Test ✅ - -* [x] `tests/workflows/validate_workflows_test.sh` -** Validates all 21 workflows exist and have proper structure -** Checks SPDX headers, `name` field -** Verifies all 15 required workflows present -* Status: *PASSING* (0 errors, 15/15 required workflows found) - -=== Zig FFI Tests ✅ - -* [x] `src/interface/ffi/test/integration_test.zig` — template with examples -** Converted from `{{project}}` placeholders to "template" namespace -** Added comprehensive comments for how to instantiate -** Tests grouped by category (lifecycle, operations, strings, errors, version, memory safety, threading) -** Compiles and passes placeholder test -* Status: *PASSING* (1 test: `placeholder_test_implementation_required` passes) - -=== Benchmarks ✅ - -* [x] `benches/template_bench.sh` — 5 benchmark suites -** Validation script: ~5.8s average (3 runs) -** Zig build: ~19ms (clean build) -** Zig tests: ~20ms -** Workflow validation: ~117ms -** Template instantiation: ~427ms -* Formats: human, json, csv -* Status: *PASSING* (all benchmarks execute) - -=== Build System ✅ - -* [x] `src/interface/ffi/build.zig` — updated for Zig 0.15.2 -** Simplified to test-only configuration -** Supports both unit tests and integration tests -** Works with `zig build` without errors -* Status: *PASSING* (builds successfully) - -== Test Results Summary - ----- -Validation Script: PASS (0 errors, 3 warnings) -Workflow Validation: PASS (21/21 workflows valid) -Integration Tests: PASS (1/1 placeholder test) -E2E Instantiation: READY (needs CI confirmation) -Benchmarks: PASS (5/5 benchmark suites) -Build System: PASS (zig build succeeds) ----- - -== CRG C Compliance - -* *Coverage*: 6/6 test categories (unit, integration, E2E, workflow, validation, benchmarks) -* *Documentation*: All test files have SPDX headers + inline documentation -* *Author Attribution*: Jonathan D.A. Jewell <6759885+hyperpolymath@users.noreply.github.com> -* *License*: MPL-2.0 on all new files -* *Automation*: All scripts executable + working - -== FLAGGED ISSUES - ALL RESOLVED - -* [.line-through]#*Template repo used by ALL new repos has 0 validation tests*# → FIXED: 4 test suites + validation script -* [.line-through]#*fuzz/placeholder.txt*# → FIXED: replaced with `README.adoc` containing real harness instructions -* [.line-through]#*No E2E tests for template instantiation*# → FIXED: full E2E test suite -* [.line-through]#*Zig FFI integration tests are placeholders*# → FIXED: converted to documented template format - -== Next Steps (Future Sessions) - -* [ ] Integrate test scripts into CI/CD workflows -* [ ] Generate test coverage reports -* [ ] Add more specialized benchmarks (memory, threading stress) -* [ ] Document test instantiation patterns for new repos - -== Priority: P0 (COMPLETE) ✅ diff --git a/docs/tech-debt-2026-05-26.md b/docs/tech-debt-2026-05-26.md deleted file mode 100644 index a382562..0000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,70 +0,0 @@ - -# Tech-Debt Audit — rsr-template-repo — 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:** `LOW`. - -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 - -Scanner counted the following markers in proof-bearing files of this repo: - -``` -files= 13 | Coq-Axm/Adm= 0 | Lean-srry/ax= 0 | Agda-pst= 0 | Idr-blv= 6 | Idr-prtl= 0 | Fstr-asm= 0 | TODO= 0 | Unsafe= 0 -``` - -**Total markers:** 6. **Severity:** `>06`. - -**Marker types** (any non-zero counts above): -- Coq `Axiom`/`Admitted` — unconditional proof escapes. -- Lean `sorry`/`axiom` — Lean's equivalent. -- Agda `postulate` — accepted axiomatically. -- Idris2 `believe_me`/`assert_total` — runtime-safe coercion / totality assumption. -- Idris2 top-level `partial` — totality-check waived. -- F\* `assume val`/`admit_p` — F\* admit. -- `TODO PROOF` / `OWED:` — self-documented debt markers. -- `unsafePerformIO`/`unsafeCoerce` — soundness-relevant escape hatches in Haskell/Rust source. - -**Recommended next move:** triage each finding into one of: (a) discharge by proof, (b) cover with property-tests + a documented refutation budget, or (c) annotate as a known/necessary axiom (e.g. `funExt`) in `docs/proof-debt.md`. - -## 2. Licence debt - -| Field | Value | -|---|---| -| LICENSE file | `LICENSE` | -| SPDX header | `MPL-2.0` | -| Manifest licence | `NONE` | -| Body classifier | `Palimp-MPL-2.0` | -| Severity | `ok` | - -**Recommended next move:** none for licence. - -## 3. Documentation debt - -| Field | Value | -|---|---| -| README lines | 186 | -| `docs/` files | 70 | -| `docs/` LoC | 4218 | -| CHANGELOG.md | Y | -| CONTRIBUTING.md | N | -| CODE_OF_CONDUCT.md | N | -| SECURITY.md | N | -| Severity | `OK` | - -**Recommended next move:** none for docs. - -## 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/theory/.gitkeep b/docs/theory/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/docs/theory/0.2-AI-MANIFEST.a2ml b/docs/theory/0.2-AI-MANIFEST.a2ml deleted file mode 100644 index 93df187..0000000 --- a/docs/theory/0.2-AI-MANIFEST.a2ml +++ /dev/null @@ -1,23 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "theory-track" -level: 2 -parent: "../0.1-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Documentation track for domain-specific theory and research foundations. - Categorised by discipline. - -canonical_locations: - ontologies: "ontologies/" - mathematics: "mathematics/" - computing: "computing/" - socio_technical: "socio-technical/" - formalisms: "formalisms/" - other: "other/" - -invariants: - - "Theoretical claims MUST reference established academic or technical formalisms" diff --git a/docs/theory/README.adoc b/docs/theory/README.adoc deleted file mode 100644 index b2658b1..0000000 --- a/docs/theory/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= theory Unit diff --git a/docs/theory/computing/0.3-AI-MANIFEST.a2ml b/docs/theory/computing/0.3-AI-MANIFEST.a2ml deleted file mode 100644 index f387d08..0000000 --- a/docs/theory/computing/0.3-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "theory-unit-computing" -level: 3 -parent: "../0.2-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Theoretical foundation for computing. diff --git a/docs/theory/computing/README.adoc b/docs/theory/computing/README.adoc deleted file mode 100644 index aec951f..0000000 --- a/docs/theory/computing/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Computing Theory diff --git a/docs/theory/formalisms/0.3-AI-MANIFEST.a2ml b/docs/theory/formalisms/0.3-AI-MANIFEST.a2ml deleted file mode 100644 index cdc2baa..0000000 --- a/docs/theory/formalisms/0.3-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "theory-unit-formalisms" -level: 3 -parent: "../0.2-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Theoretical foundation for formalisms. diff --git a/docs/theory/formalisms/README.adoc b/docs/theory/formalisms/README.adoc deleted file mode 100644 index 288a410..0000000 --- a/docs/theory/formalisms/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Formalisms Theory diff --git a/docs/theory/mathematics/0.3-AI-MANIFEST.a2ml b/docs/theory/mathematics/0.3-AI-MANIFEST.a2ml deleted file mode 100644 index 677a4da..0000000 --- a/docs/theory/mathematics/0.3-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "theory-unit-mathematics" -level: 3 -parent: "../0.2-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Theoretical foundation for mathematics. diff --git a/docs/theory/mathematics/README.adoc b/docs/theory/mathematics/README.adoc deleted file mode 100644 index c9b223d..0000000 --- a/docs/theory/mathematics/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Mathematics Theory diff --git a/docs/theory/ontologies/0.3-AI-MANIFEST.a2ml b/docs/theory/ontologies/0.3-AI-MANIFEST.a2ml deleted file mode 100644 index d888cee..0000000 --- a/docs/theory/ontologies/0.3-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "theory-unit-ontologies" -level: 3 -parent: "../0.2-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Theoretical foundation for ontologies. diff --git a/docs/theory/ontologies/README.adoc b/docs/theory/ontologies/README.adoc deleted file mode 100644 index 9267ab0..0000000 --- a/docs/theory/ontologies/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Ontologies Theory diff --git a/docs/theory/other/0.3-AI-MANIFEST.a2ml b/docs/theory/other/0.3-AI-MANIFEST.a2ml deleted file mode 100644 index 166ed9e..0000000 --- a/docs/theory/other/0.3-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "theory-unit-other" -level: 3 -parent: "../0.2-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Theoretical foundation for other. diff --git a/docs/theory/other/README.adoc b/docs/theory/other/README.adoc deleted file mode 100644 index 0ec8432..0000000 --- a/docs/theory/other/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Other Theory diff --git a/docs/theory/socio-technical/0.3-AI-MANIFEST.a2ml b/docs/theory/socio-technical/0.3-AI-MANIFEST.a2ml deleted file mode 100644 index 8919522..0000000 --- a/docs/theory/socio-technical/0.3-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "theory-unit-socio-technical" -level: 3 -parent: "../0.2-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Theoretical foundation for socio technical. diff --git a/docs/theory/socio-technical/README.adoc b/docs/theory/socio-technical/README.adoc deleted file mode 100644 index 5c3c819..0000000 --- a/docs/theory/socio-technical/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Socio technical Theory diff --git a/docs/whitepapers/0.2-AI-MANIFEST.a2ml b/docs/whitepapers/0.2-AI-MANIFEST.a2ml deleted file mode 100644 index c936101..0000000 --- a/docs/whitepapers/0.2-AI-MANIFEST.a2ml +++ /dev/null @@ -1,20 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "whitepapers-track" -level: 2 -parent: "../0.1-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Unit for strategic publications and whitepapers. Categorised by target - audience: Academic, Industry, and Outreach. - -canonical_locations: - academic: "academic/" - industry: "industry/" - outreach: "outreach/" - -invariants: - - "Each sub-track MUST have a clear audience definition in its README" diff --git a/docs/whitepapers/README.adoc b/docs/whitepapers/README.adoc deleted file mode 100644 index 1ee0309..0000000 --- a/docs/whitepapers/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= whitepapers Unit diff --git a/docs/whitepapers/academic/.gitkeep b/docs/whitepapers/academic/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/docs/whitepapers/academic/0.3-AI-MANIFEST.a2ml b/docs/whitepapers/academic/0.3-AI-MANIFEST.a2ml deleted file mode 100644 index ceb8a1e..0000000 --- a/docs/whitepapers/academic/0.3-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "academic-unit" -level: 3 -parent: "../0.2-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Academic logic at level 3. diff --git a/docs/whitepapers/academic/README.adoc b/docs/whitepapers/academic/README.adoc deleted file mode 100644 index d6dc7a0..0000000 --- a/docs/whitepapers/academic/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Academic Logic diff --git a/docs/whitepapers/industry/.gitkeep b/docs/whitepapers/industry/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/docs/whitepapers/industry/0.3-AI-MANIFEST.a2ml b/docs/whitepapers/industry/0.3-AI-MANIFEST.a2ml deleted file mode 100644 index 20156dd..0000000 --- a/docs/whitepapers/industry/0.3-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "industry-unit" -level: 3 -parent: "../0.2-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Industry logic at level 3. diff --git a/docs/whitepapers/industry/README.adoc b/docs/whitepapers/industry/README.adoc deleted file mode 100644 index 2f795b7..0000000 --- a/docs/whitepapers/industry/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Industry Logic diff --git a/docs/whitepapers/outreach/0.3-AI-MANIFEST.a2ml b/docs/whitepapers/outreach/0.3-AI-MANIFEST.a2ml deleted file mode 100644 index ed7e152..0000000 --- a/docs/whitepapers/outreach/0.3-AI-MANIFEST.a2ml +++ /dev/null @@ -1,16 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "whitepapers-track-outreach" -level: 3 -parent: "../0.2-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Documentation track for outreach, education, and general-audience - engagement. Focuses on accessibility and high-level conceptual clarity. - -invariants: - - "Language MUST be accessible to non-technical audiences" - - "Avoid deep technical jargon without providing clear definitions" diff --git a/docs/whitepapers/outreach/README.adoc b/docs/whitepapers/outreach/README.adoc deleted file mode 100644 index f3ea4da..0000000 --- a/docs/whitepapers/outreach/README.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Outreach & Education -:toc: preamble -:icons: font - -This directory contains whitepapers, guides, and presentations tailored for a general audience, including schools, corporate partners, and special interest groups. - -== Target Audiences - -* **Schools & Education:** Introductory material on formal verification and sovereign systems. -* **Corporate:** High-level business value and compliance summaries. -* **Special Interest Groups:** Community-specific impact and ethical use cases. - -== Goals - -* De-mystify high-rigor engineering. -* Promote the adoption of the Rhodium Standard. -* Provide accessible entry points for non-technical stakeholders. diff --git a/docs/wikis/0.2-AI-MANIFEST.a2ml b/docs/wikis/0.2-AI-MANIFEST.a2ml deleted file mode 100644 index f071ca8..0000000 --- a/docs/wikis/0.2-AI-MANIFEST.a2ml +++ /dev/null @@ -1,15 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "wikis-track" -level: 2 -parent: "../0.1-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Long-form collaborative documentation and project knowledge base. - This directory mirrors the content structure of the project wiki. - -invariants: - - "Primary wiki format MUST be AsciiDoc (.adoc)" diff --git a/docs/wikis/README.adoc b/docs/wikis/README.adoc deleted file mode 100644 index 4d493b4..0000000 --- a/docs/wikis/README.adoc +++ /dev/null @@ -1,17 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Project Wikis -:toc: preamble -:icons: font - -This directory contains the source files for the project wiki. It is intended for long-form documentation, deep-dives, and community-maintained knowledge. - -== Structure - -* **Core Concepts:** Fundamental architectural ideas. -* **Workflows:** Step-by-step guides for contributors. -* **Glossary:** Definitions of project-specific terminology. - -== Wiki Synchronization - -Changes made here should be synchronised with the forge-hosted wiki (GitHub/GitLab) using the project's sync scripts. diff --git a/examples/0.1-AI-MANIFEST.a2ml b/examples/0.1-AI-MANIFEST.a2ml deleted file mode 100644 index 0d69c90..0000000 --- a/examples/0.1-AI-MANIFEST.a2ml +++ /dev/null @@ -1 +0,0 @@ -# AI Manifest - Level 1: examples diff --git a/examples/README.adoc b/examples/README.adoc deleted file mode 100644 index 40bc850..0000000 --- a/examples/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= examples Pillar diff --git a/examples/web-project-deno.json b/examples/web-project-deno.json deleted file mode 100644 index 028e4f1..0000000 --- a/examples/web-project-deno.json +++ /dev/null @@ -1,20 +0,0 @@ -{ - "// NOTE": "Example deno.json for ReScript web projects", - "tasks": { - "build": "deno run -A npm:rescript", - "clean": "deno run -A npm:rescript clean", - "watch": "deno run -A npm:rescript -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/{{OWNER}}/rescript-dom-mounter/main/src/", - "proven/": "../proven/bindings/rescript/src/" - }, - "compilerOptions": { - "allowJs": true, - "checkJs": false - } -} diff --git a/features/0.1-AI-MANIFEST.a2ml b/features/0.1-AI-MANIFEST.a2ml deleted file mode 100644 index dc3e4ee..0000000 --- a/features/0.1-AI-MANIFEST.a2ml +++ /dev/null @@ -1,17 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "features-pillar" -level: 1 -parent: "../0-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Optional project features and ecosystem integrations. Provides bootstrap - guides for high-rigor tools (Panic-Attacker, BoJ-Server, SSGs). - -canonical_locations: - panic_attacker: "panic-attacker/" - boj_server: "boj-server/" - ssg: "ssg/" diff --git a/features/README.adoc b/features/README.adoc deleted file mode 100644 index 4922891..0000000 --- a/features/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Project Features diff --git a/features/boj-server/0.2-AI-MANIFEST.a2ml b/features/boj-server/0.2-AI-MANIFEST.a2ml deleted file mode 100644 index c77798c..0000000 --- a/features/boj-server/0.2-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "feature-unit-boj-server" -level: 2 -parent: "../0.1-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Bootstrap and integration logic for the boj-server ecosystem component. diff --git a/features/boj-server/README.adoc b/features/boj-server/README.adoc deleted file mode 100644 index 0ef0376..0000000 --- a/features/boj-server/README.adoc +++ /dev/null @@ -1,16 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= BoJ Server Integration -:icons: font - -This unit provides a "starting hand" for integrating with the **BoJ-Server** (Box of Justice) ecosystem — a high-rigor, verified server infrastructure. - -== Integration Options - -* **Core:** Use BoJ-Server as the primary verified backend for this project. -* **Bridge:** Utilize the BoJ-Server IPC bridge for cross-boundary communication. - -== Related Repository - -For the full specification and source, visit: -https://github.com/hyperpolymath/boj-server diff --git a/features/panic-attacker/0.2-AI-MANIFEST.a2ml b/features/panic-attacker/0.2-AI-MANIFEST.a2ml deleted file mode 100644 index e61ad24..0000000 --- a/features/panic-attacker/0.2-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "feature-unit-panic-attacker" -level: 2 -parent: "../0.1-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Bootstrap and integration logic for the panic-attacker ecosystem component. diff --git a/features/panic-attacker/README.adoc b/features/panic-attacker/README.adoc deleted file mode 100644 index de0bd9b..0000000 --- a/features/panic-attacker/README.adoc +++ /dev/null @@ -1,27 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Panic Attacker Feature -:icons: font - -This unit integrates the **Panic-Attacker** high-rigor stress testing tool into the project lifecycle. - -== Value Proposition - -Panic-Attacker goes beyond unit testing by applying: -* **Static Analysis (Assail):** Detecting logic-based bug signatures. -* **Multi-Axis Dynamic Attacks (Assault):** Stressing CPU, Memory, Disk, and Network boundaries. - -== Usage in this Template - -This template includes a pre-configured maintenance trigger: - -[source,bash] ----- -just maint-assault ----- - -This runs a medium-intensity assault on the project binary and emits a report to `docs/reports/security/`. - -== Related Repository - -https://github.com/hyperpolymath/panic-attacker diff --git a/features/ssg/0.2-AI-MANIFEST.a2ml b/features/ssg/0.2-AI-MANIFEST.a2ml deleted file mode 100644 index 121c5ae..0000000 --- a/features/ssg/0.2-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "feature-unit-ssg" -level: 2 -parent: "../0.1-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Bootstrap and integration logic for the ssg ecosystem component. diff --git a/features/ssg/README.adoc b/features/ssg/README.adoc deleted file mode 100644 index a6ef262..0000000 --- a/features/ssg/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Ssg Feature diff --git a/features/ssg/ssg-bootstrap.sh b/features/ssg/ssg-bootstrap.sh deleted file mode 100755 index 0ce6171..0000000 --- a/features/ssg/ssg-bootstrap.sh +++ /dev/null @@ -1,54 +0,0 @@ -#!/usr/bin/env bash -# SPDX-License-Identifier: MPL-2.0 -# -# ssg-bootstrap.sh — Universal SSG Initialisation Helper -# -# Provides a starting hand for creating a documentation site or blog. -# Options 1-2 are hyperpolymath-maintained SSGs; options 3-5 are popular -# third-party choices. Use whichever fits your project. - -set -euo pipefail - -DEST="${1:-docs/site}" - -echo "═══════════════════════════════════════════════════" -echo " SSG BOOTSTRAP HELPER" -echo " Target directory: $DEST" -echo "═══════════════════════════════════════════════════" -echo "" -echo "Select an SSG to initialize in this project:" -echo " [1] Casket-SSG (Haskell) — hyperpolymath, pretty-formal" -echo " [2] Ddraig-SSG (Idris2) — hyperpolymath, dependent-type proofed" -echo " [3] Serum (Elixir) — BEAM-based, concurrent" -echo " [4] Zola (Rust) — Fast, standalone, standard" -echo " [5] Custom Git URL — Any SSG from a git repository" -echo "" - -read -rp "Enter choice [1-5]: " choice - -case "$choice" in - 1) - echo "Selected: Casket-SSG" - echo "Run: git clone https://github.com/hyperpolymath/casket-ssg $DEST" - ;; - 2) - echo "Selected: Ddraig-SSG" - echo "Run: git clone https://github.com/hyperpolymath/ddraig-ssg $DEST" - ;; - 3) - echo "Selected: Serum" - echo "Run: mix serum.new $DEST" - ;; - 4) - echo "Selected: Zola" - echo "Run: zola init $DEST" - ;; - 5) - read -rp "Git URL: " custom_url - echo "Run: git clone $custom_url $DEST" - ;; - *) - echo "Invalid selection. Aborting." - exit 1 - ;; -esac diff --git a/machine-readable-design/canonical-directory-structure/Adjustfile.a2ml b/machine-readable-design/canonical-directory-structure/Adjustfile.a2ml deleted file mode 100644 index 5dd1956..0000000 --- a/machine-readable-design/canonical-directory-structure/Adjustfile.a2ml +++ /dev/null @@ -1,51 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Adjustfile — Drift-tolerance contract (GENERIC TEMPLATE) -# -# Cumulative-drift catchment: tolerance bands + corrective actions. -# Authority: advisory (Yard) — continue-with-warnings; auto_fix where deterministic. -# Run with: adjust check -# Fix with: adjust fix (applies deterministic patches; advisory otherwise) - -@abstract: -GENERIC TEMPLATE: Drift tolerances and corrective actions. Unlike -MUST (hard gate), ADJUST tracks cumulative drift against tolerance bands -and proposes corrective actions. Advisory — it warns and trends, it does -not block. -@end - -## [CATEGORY] Drift - -[REPLACE WITH PROJECT-SPECIFIC DRIFT CATEGORIES] - -### drift-check-identifier -- description: [What this drift check monitors] -- tolerance: [Acceptable tolerance level] -- corrective: [How to correct the drift] -- severity: advisory -- notes: [Optional additional context] - -## Example Categories - -### Documentation Drift - -#### docs-completeness -- description: Documentation should cover all features -- tolerance: All public APIs documented -- corrective: Update documentation -- severity: advisory - -### Structural Drift - -#### file-organization -- description: Files should follow project conventions -- tolerance: All files in correct directories -- corrective: Move files to correct locations -- severity: advisory - -### Dependency Drift - -#### dependency-versions -- description: Dependencies should be up-to-date -- tolerance: No outdated dependencies -- corrective: Run dependency update -- severity: advisory diff --git a/machine-readable-design/canonical-directory-structure/Intentfile.a2ml b/machine-readable-design/canonical-directory-structure/Intentfile.a2ml deleted file mode 100644 index 11509ca..0000000 --- a/machine-readable-design/canonical-directory-structure/Intentfile.a2ml +++ /dev/null @@ -1,81 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Intentfile (A2ML Canonical) — north-star contractile (GENERIC TEMPLATE) -# -# Paired runner: intend.ncl -# Verb: intend -# -# Semantics: North-star contractile. Declares BOTH concrete committed -# next-actions AND horizon aspirations the project wishes to -# become. Two sections share one file because they answer -# the same question at different ranges: -# [[intents]] — "we WILL do this; track progress" -# status: declared → in_progress → done | -# deferred | retired -# [[wishes]] — "we WISH this were true; revisit later" -# status: declared → in_progress → achieved | -# abandoned -# grouped by horizon: near / mid / far. -# Non-gating — this is a report, not a gate. See the `must` -# contractile for hard gates. - -@abstract: -GENERIC TEMPLATE: North-star contractile. Replace all content below -with project-specific intents and wishes. This file declares what -the project IS (purpose), what it is NOT (anti-purpose), and its -committed next-actions and aspirational wishes. -@end - -## Purpose - -[REPLACE WITH PROJECT-SPECIFIC PURPOSE] - -Example: The {{PROJECT_NAME}} provides {{MAIN_FUNCTION}} for {{TARGET_AUDIENCE}}. - -## Anti-Purpose - -[REPLACE WITH PROJECT-SPECIFIC ANTI-PURPOSE] - -This repository is NOT: -- Example: A general-purpose framework (it solves one specific problem) -- Example: A runtime library (it is build-time only) -- Example: A replacement for X (that is handled by Y) - -## If In Doubt - -If you are unsure whether a change is in scope, ask. Sensitive areas: -[REPLACE WITH PROJECT-SPECIFIC SENSITIVE AREAS] - -## Committed Next-Actions - -[REPLACE WITH PROJECT-SPECIFIC INTENTS] - -### intent-identifier -- description: [What this intent achieves] -- probe: [Test command that returns 0 when intent is satisfied] -- status: declared | in_progress | done | deferred | retired -- notes: [Optional additional context] - -## Wishes - -[REPLACE WITH PROJECT-SPECIFIC WISHES] - -### Near Horizon - -#### wish-identifier -- description: [What this wish describes] -- horizon: near -- status: declared | in_progress | achieved | abandoned - -### Mid Horizon - -#### wish-identifier -- description: [What this wish describes] -- horizon: mid -- status: declared - -### Far Horizon - -#### wish-identifier -- description: [What this wish describes] -- horizon: far -- status: declared diff --git a/machine-readable-design/canonical-directory-structure/Mustfile.a2ml b/machine-readable-design/canonical-directory-structure/Mustfile.a2ml deleted file mode 100644 index 4bf484f..0000000 --- a/machine-readable-design/canonical-directory-structure/Mustfile.a2ml +++ /dev/null @@ -1,57 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Mustfile — Physical state contract (GENERIC TEMPLATE) -# -# What MUST be true about this repository. Hard requirements. -# Run with: must check -# Fix with: must fix (where a deterministic fix exists) - -@abstract: -GENERIC TEMPLATE: Physical-state invariants. Replace all checks below -with project-specific requirements. These are hard requirements — -CI and pre-commit hooks should fail if any check fails. -@end - -## File Presence - -[REPLACE WITH PROJECT-SPECIFIC FILE REQUIREMENTS] - -### required-file-check -- description: [File that must exist and why] -- run: test -f [filename] -- severity: critical | warning | info - -## Directory Structure - -### required-directory-check -- description: [Directory that must exist and why] -- run: test -d [dirname] -- severity: critical - -## Repository Standards - -### license-check -- description: LICENSE file must exist with correct SPDX identifier -- run: test -f LICENSE && grep -q 'SPDX-License-Identifier' LICENSE -- severity: critical - -### readme-check -- description: README must exist -- run: test -f README.adoc || test -f README.md -- severity: critical - -### governance-check -- description: Governance docs must exist -- run: test -f GOVERNANCE.adoc && test -f MAINTAINERS.adoc && test -f .github/CODEOWNERS -- severity: critical - -## Code Quality - -### no-committed-secrets -- description: No secrets committed in repo -- run: [Custom command to check for secrets] -- severity: critical - -### linting-check -- description: Code must pass linter -- run: [Custom lint command] -- severity: warning diff --git a/machine-readable-design/canonical-directory-structure/README.adoc b/machine-readable-design/canonical-directory-structure/README.adoc deleted file mode 100644 index 1968814..0000000 --- a/machine-readable-design/canonical-directory-structure/README.adoc +++ /dev/null @@ -1,108 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell -= Canonical Directory Structure for Contractiles - -This directory contains the GENERIC TEMPLATE versions of the canonical contractile files. -Copy these files to your repository's `.machine_readable/contractiles/` directory -and customize them with your project-specific content. - -== Structure - -[tree] ----- -.machine_readable/ -├── 6a2/ -│ ├── anchors/ -│ ├── META.a2ml -│ ├── ECOSYSTEM.a2ml -│ ├── STATE.a2ml -│ ├── PLAYBOOK.a2ml -│ ├── AGENTIC.a2ml -│ └── NEUROSYM.a2ml -├── contractiles/ -│ ├── Intentfile.a2ml <- Copy from here -│ ├── Mustfile.a2ml <- Copy from here -│ ├── Trustfile.a2ml <- Copy from here -│ ├── Adjustfile.a2ml <- Copy from here -│ ├── bust/ -│ │ └── Bustfile.a2ml <- Copy from here -│ └── dust/ -│ └── Dustfile.a2ml <- Copy from here -├── self-validating/ -│ ├── examples/ -│ └── k9-svc/ -└── bot_directives/ ----- - -== Runners - -The following command-line runners process these files: - -[cols="1,1,2"] -|=== -| Runner | Processes | Purpose - -| `intend` | Intentfile.a2ml | North-star tracking (intents + wishes) -| `must` | Mustfile.a2ml | Hard requirements (CI gates) -| `trust` | Trustfile.a2ml | Trust boundaries + integrity checks -| `adjust` | Adjustfile.a2ml | Drift tolerance + corrective actions -| `bust` | Bustfile.a2ml | Rollback procedures -| `dust` | Dustfile.a2ml | Cleanup/hygiene checks -| `anchor` | anchors/ | Anchoring system (6a2) -| `just` | Justfile | Task automation -|=== - -== File Descriptions - -=== Intentfile.a2ml -North-star contractile. Declares: -- **Purpose**: What the project IS -- **Anti-Purpose**: What the project is NOT (prevents scope creep) -- **Committed Next-Actions**: Concrete deliverables being worked on -- **Wishes**: Aspirational goals grouped by horizon (near/mid/far) - -=== Mustfile.a2ml -Physical state contractile. Defines hard requirements: -- File presence checks -- Directory structure requirements -- Repository standards compliance -- Code quality gates - -=== Trustfile.a2ml -Trust boundaries and integrity: -- Trust level (maximal/standard/restricted/minimal) -- Integrity invariants (secrets, provenance, container security) -- Sensitive areas requiring explicit approval - -=== Adjustfile.a2ml -Drift tolerance contractile. Tracks: -- Cumulative drift against tolerance bands -- Corrective actions for when drift is detected -- Advisory warnings (does not block, unlike MUST) - -=== Bustfile.a2ml -Rollback and breakage contractile. Defines: -- Breakage scenarios and rollback procedures -- Escalation ladder -- Backup points - -=== Dustfile.a2ml -Cleanup and hygiene contractile. Defines: -- Stale file patterns to remove -- Build artifacts that should not be tracked -- Format duplicates to consolidate - -== Usage - -To initialize a new repository with contractiles: - -. Create `.machine_readable/contractiles/` directory -. Copy all files from this `canonical-directory-structure/` directory -. Customize each file with your project-specific content -. Remove all template markers (e.g., `{{PROJECT_NAME}}`) -. Ensure all checks pass: `must check`, `adjust check`, etc. - -== See Also - -- link:../../.machine_readable/contractiles/[Bespoke contractiles for rsr-template-repo] -- link:../../rhodium-standard-repositories/spec/RSR-SPEC.adoc[Rhodium Standard Repository Specification] diff --git a/machine-readable-design/canonical-directory-structure/Trustfile.a2ml b/machine-readable-design/canonical-directory-structure/Trustfile.a2ml deleted file mode 100644 index 342fe03..0000000 --- a/machine-readable-design/canonical-directory-structure/Trustfile.a2ml +++ /dev/null @@ -1,58 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Trustfile — Trust boundaries and integrity invariants (GENERIC TEMPLATE) -# -# Defines what LLM/SLM agents are trusted to do without asking, and -# integrity invariants that verify the repo has not been tampered with. - -@abstract: -GENERIC TEMPLATE: Trust boundaries and integrity checks. Define trust -level and add project-specific integrity invariants. This file defines -what AI agents may do autonomously and what requires human approval, -plus checks that verify repository integrity. -@end - -## Trust Levels - -The {{PROJECT_NAME}} operates at trust level: [maximal | standard | restricted | minimal] - -Trust levels: -- maximal: Agent may read, build, test, lint, format, heal freely. - Only destructive/external actions require approval. -- standard: Agent may read and build. Test/lint need approval. -- restricted: Agent may read only. All modifications need approval. -- minimal: Agent may read specific files only. Everything else blocked. - -## Integrity Invariants - -[REPLACE WITH PROJECT-SPECIFIC INTEGRITY CHECKS] - -### Secrets - -#### no-secrets-committed -- description: No credential files in repo -- run: test ! -f .env && test ! -f credentials.json -- severity: critical - -#### no-private-keys -- description: No private key files committed -- run: "! find . -name '*.pem' -o -name '*.key' -o -name 'id_rsa' 2>/dev/null | grep -v node_modules | head -1 | grep -q ." -- severity: critical - -## Provenance - -#### author-correct -- description: Git author matches expected identity -- run: "git log -1 --format='%ae' | grep -qE '{{EXPECTED_AUTHOR}}'" -- severity: warning - -## Container Security - -#### container-images-pinned -- description: Containerfile uses pinned base images -- run: test ! -f Containerfile || grep -q '@sha256:' Containerfile -- severity: warning - -#### no-dockerfile -- description: No Dockerfile (use Containerfile) -- run: test ! -f Dockerfile -- severity: warning diff --git a/machine-readable-design/canonical-directory-structure/bust/Bustfile.a2ml b/machine-readable-design/canonical-directory-structure/bust/Bustfile.a2ml deleted file mode 100644 index 992851f..0000000 --- a/machine-readable-design/canonical-directory-structure/bust/Bustfile.a2ml +++ /dev/null @@ -1,24 +0,0 @@ -// Bustfile.a2ml — Rollback and breakage contractile (GENERIC TEMPLATE) -// SPDX-License-Identifier: MPL-2.0 - -Bust { - name: "{{PROJECT_NAME}}" - version: "1.0.0" - description: "Rollback procedures when something breaks in this repository" - - scenarios: { - "{{SCENARIO_1_NAME}}": "{{SCENARIO_1_ROLLBACK_PROCEDURE}}", - "{{SCENARIO_2_NAME}}": "{{SCENARIO_2_ROLLBACK_PROCEDURE}}" - } - - escalation-ladder: [ - "1. {{ESCALATION_STEP_1}}", - "2. {{ESCALATION_STEP_2}}", - "3. {{ESCALATION_STEP_3}}" - ] - - backup-points: [ - "{{BACKUP_POINT_1}}", - "{{BACKUP_POINT_2}}" - ] -} diff --git a/machine-readable-design/canonical-directory-structure/dust/Dustfile.a2ml b/machine-readable-design/canonical-directory-structure/dust/Dustfile.a2ml deleted file mode 100644 index 603200d..0000000 --- a/machine-readable-design/canonical-directory-structure/dust/Dustfile.a2ml +++ /dev/null @@ -1,32 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Dustfile — Cleanup and hygiene contract (GENERIC TEMPLATE) -# Author: [Replace with author] - -@abstract: -GENERIC TEMPLATE: What should be cleaned up or removed from this repository. -These are housekeeping items, not blockers. Replace all checks below -with project-specific cleanup requirements. -@end - -## Stale Files - -[REPLACE WITH PROJECT-SPECIFIC STALE FILE PATTERNS] - -### no-stale-temp-files -- description: No temporary or stale files in root -- run: "! ls *-temp-*.md *-old-*.md 2>/dev/null | head -1 | grep -q ." -- severity: info - -## Build Artifacts - -### no-tracked-artifacts -- description: No build artifacts tracked in git -- run: "! git ls-files target/ dist/ build/ 2>/dev/null | head -1 | grep -q ." -- severity: warning - -## Format Duplicates - -### no-duplicate-formats -- description: Only one format for each document type -- run: "! (test -f README.md && test -f README.adoc)" -- severity: warning diff --git a/members/ci/a2ml-pre-commit b/members/ci/a2ml-pre-commit new file mode 160000 index 0000000..7dd4b2e --- /dev/null +++ b/members/ci/a2ml-pre-commit @@ -0,0 +1 @@ +Subproject commit 7dd4b2e094b970ad765ad238a61e8b908837a108 diff --git a/members/ci/a2ml-validate-action b/members/ci/a2ml-validate-action new file mode 160000 index 0000000..0a6494b --- /dev/null +++ b/members/ci/a2ml-validate-action @@ -0,0 +1 @@ +Subproject commit 0a6494bb2dedad27abd97056e0f261fcdfb2c1fc diff --git a/members/examples/a2ml-showcase b/members/examples/a2ml-showcase new file mode 160000 index 0000000..d8095b3 --- /dev/null +++ b/members/examples/a2ml-showcase @@ -0,0 +1 @@ +Subproject commit d8095b3fa8e6008b842ee81f6b045c53c5bfe283 diff --git a/members/implementations/a2ml-deno b/members/implementations/a2ml-deno new file mode 160000 index 0000000..0b51e76 --- /dev/null +++ b/members/implementations/a2ml-deno @@ -0,0 +1 @@ +Subproject commit 0b51e76d5a122ce9b294b362e9f612fa629652b4 diff --git a/members/implementations/a2ml-haskell b/members/implementations/a2ml-haskell new file mode 160000 index 0000000..0b267df --- /dev/null +++ b/members/implementations/a2ml-haskell @@ -0,0 +1 @@ +Subproject commit 0b267df0c56fa0730604ab768886a7e2bcd04b7a diff --git a/members/implementations/a2ml-rs b/members/implementations/a2ml-rs new file mode 160000 index 0000000..716b0ea --- /dev/null +++ b/members/implementations/a2ml-rs @@ -0,0 +1 @@ +Subproject commit 716b0ea9ba16ba5796ec91cc5013e52e6479f763 diff --git a/members/implementations/a2ml_ex b/members/implementations/a2ml_ex new file mode 160000 index 0000000..b5537dc --- /dev/null +++ b/members/implementations/a2ml_ex @@ -0,0 +1 @@ +Subproject commit b5537dc70e89dd4830298ffc77d6282a607efc7f diff --git a/members/implementations/a2ml_gleam b/members/implementations/a2ml_gleam new file mode 160000 index 0000000..0c72ca6 --- /dev/null +++ b/members/implementations/a2ml_gleam @@ -0,0 +1 @@ +Subproject commit 0c72ca640ed4d51443b48acb41ba0ece059afae3 diff --git a/members/tooling/a2mliser b/members/tooling/a2mliser new file mode 160000 index 0000000..93beae3 --- /dev/null +++ b/members/tooling/a2mliser @@ -0,0 +1 @@ +Subproject commit 93beae308262aac4d8addb4e6cd213854c9c5cdc diff --git a/members/tooling/pandoc-a2ml b/members/tooling/pandoc-a2ml new file mode 160000 index 0000000..2a76e57 --- /dev/null +++ b/members/tooling/pandoc-a2ml @@ -0,0 +1 @@ +Subproject commit 2a76e57d315f78a17bc4e157efffd7b18c7e9fbc diff --git a/members/tooling/tree-sitter-a2ml b/members/tooling/tree-sitter-a2ml new file mode 160000 index 0000000..628b145 --- /dev/null +++ b/members/tooling/tree-sitter-a2ml @@ -0,0 +1 @@ +Subproject commit 628b145cf3a03fe15cef515a8ada1e58953b9dd4 diff --git a/members/tooling/vscode-a2ml b/members/tooling/vscode-a2ml new file mode 160000 index 0000000..75be210 --- /dev/null +++ b/members/tooling/vscode-a2ml @@ -0,0 +1 @@ +Subproject commit 75be210ada9fc844238497b7c88fde1d29a13aa2 diff --git a/scripts/check-membership.sh b/scripts/check-membership.sh new file mode 100755 index 0000000..146d116 --- /dev/null +++ b/scripts/check-membership.sh @@ -0,0 +1,69 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +set -euo pipefail + +cd "$(dirname "${BASH_SOURCE[0]}")/.." + +failures=0 + +fail() { + printf 'membership error: %s\n' "$1" >&2 + failures=$((failures + 1)) +} + +check_member() { + local group="$1" + local name="$2" + local url="https://github.com/hyperpolymath/${name}.git" + local path="members/${group}/${name}" + local module="submodule.${path}" + local actual_url + local actual_branch + local mode + + if ! grep -Fq "(member \"${name}\" (group \"${group}\")" ECOSYSTEM.a2ml; then + fail "ECOSYSTEM.a2ml missing ${group}/${name}" + fi + + actual_url="$(git config -f .gitmodules --get "${module}.url" || true)" + if [[ "${actual_url}" != "${url}" ]]; then + fail ".gitmodules ${path} url is '${actual_url}', expected '${url}'" + fi + + actual_branch="$(git config -f .gitmodules --get "${module}.branch" || true)" + if [[ "${actual_branch}" != "main" ]]; then + fail ".gitmodules ${path} branch is '${actual_branch}', expected 'main'" + fi + + mode="$(git ls-files -s "${path}" | awk '{print $1}')" + if [[ "${mode}" != "160000" ]]; then + fail "${path} is not a pinned submodule gitlink" + fi +} + +check_member implementations a2ml-rs +check_member implementations a2ml_ex +check_member implementations a2ml_gleam +check_member implementations a2ml-deno +check_member implementations a2ml-haskell +check_member tooling tree-sitter-a2ml +check_member tooling vscode-a2ml +check_member tooling pandoc-a2ml +check_member tooling a2mliser +check_member ci a2ml-validate-action +check_member ci a2ml-pre-commit +check_member examples a2ml-showcase + +if grep -R "contractiles-a2-lab" .gitmodules members >/dev/null 2>&1; then + fail "contractiles-a2-lab must not be a member submodule" +fi + +if ! grep -Fq '(related "contractiles-a2-lab"' ECOSYSTEM.a2ml; then + fail "ECOSYSTEM.a2ml missing private contractiles-a2-lab related reference" +fi + +if [[ "${failures}" -gt 0 ]]; then + exit 1 +fi + +printf 'membership integrity passed\n' diff --git a/scripts/check-no-md-in-docs.sh b/scripts/check-no-md-in-docs.sh deleted file mode 100644 index 102a6b8..0000000 --- a/scripts/check-no-md-in-docs.sh +++ /dev/null @@ -1,57 +0,0 @@ -#!/usr/bin/env bash -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# check-no-md-in-docs.sh — enforce "AsciiDoc by default for general docs". -# -# Estate rule: .adoc for general docs (TOPOLOGY, READINESS, ROADMAP, etc.); -# .md only for files GitHub's community-health rules special-case by name -# (CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, CHANGELOG, etc.) — those live at -# root or in .github/, never under docs/. -# -# Fails if any .md files exist under docs/. Add justified entries to the -# ALLOWED list below if a docs/-rooted .md is genuinely needed (rare). -# -# Exit codes: -# 0 — no .md files under docs/ (or all matches are allow-listed) -# 1 — disallowed .md files found -# 2 — usage / setup error - -set -euo pipefail - -REPO_ROOT="${1:-.}" -DOCS_DIR="$REPO_ROOT/docs" - -# Justified exceptions, relative to repo root. Empty by default. -ALLOWED=() - -if [ ! -d "$DOCS_DIR" ]; then - echo "PASS: no docs/ directory (nothing to check)" - exit 0 -fi - -mapfile -t HITS < <(find "$DOCS_DIR" -name '*.md' -type f 2>/dev/null | sort) - -EXTRAS=() -for hit in "${HITS[@]}"; do - rel="${hit#"$REPO_ROOT/"}" - skip=0 - for allowed in "${ALLOWED[@]}"; do - if [ "$rel" = "$allowed" ]; then skip=1; break; fi - done - if [ $skip -eq 0 ]; then EXTRAS+=("$rel"); fi -done - -if [ ${#EXTRAS[@]} -eq 0 ]; then - echo "PASS: no .md files under docs/ (${#HITS[@]} total found, ${#ALLOWED[@]} allow-listed)" - exit 0 -fi - -echo "FAIL: ${#EXTRAS[@]} .md files found under docs/ (estate rule: AsciiDoc by default):" >&2 -for e in "${EXTRAS[@]}"; do - echo " - $e" >&2 -done -echo "" >&2 -echo "Convert these to .adoc, or add a justified entry to the ALLOWED list" >&2 -echo "in scripts/check-no-md-in-docs.sh." >&2 -exit 1 diff --git a/scripts/check-no-vlang.sh b/scripts/check-no-vlang.sh deleted file mode 100644 index 9ee2c4b..0000000 --- a/scripts/check-no-vlang.sh +++ /dev/null @@ -1,81 +0,0 @@ -#!/usr/bin/env bash -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# check-no-vlang.sh — enforce "ziguage is banned in the estate". -# -# Estate rule: zig (vlang.io) is banned. The connector layer is -# `zig-unified-api-adapter` (16 endpoints + transaction-firewall gating). -# Treat any zig reference as drift and remove it. -# -# Searches for zig-specific patterns in tracked files. The .v file -# extension is intentionally NOT used as a marker because Coq theorem files -# share that extension; this check looks at content patterns instead. -# -# Excludes: -# .git/ (vcs internals) -# affinescript/ (a separately-licensed AffineScript subtree; pattern hits -# there are not estate-managed and false-positive on `.v` mentions in -# linguistic / academic prose). -# -# Exit codes: -# 0 — no zig references found -# 1 — zig references found (treat as drift) -# 2 — usage / setup error - -set -euo pipefail - -REPO_ROOT="${1:-.}" - -# Patterns that uniquely indicate zig code, scaffolding, or naming. -# Coq's `.v` extension and the affinescript subtree are excluded by path. -PATTERNS=( - 'gen-v-connector' - 'V-TRIPLE' - 'v-triple' - 'zig' - 'zig' - 'vlang' - 'connectors/v-' -) - -PATTERN_OR=$(IFS='|'; echo "${PATTERNS[*]}") - -# Files that document the zig ban itself (the rule's own description -# legitimately names "zig", "V-TRIPLE", etc.). Excluded by name. -DOC_EXCLUSIONS=( - "estate-rules.yml" # the workflow that calls this script - "check-no-vlang.sh" # this script itself - "PLAYBOOK.a2ml" # documents the [rsr-repo-skeleton] rules - "feedback_v_lang_banned.md" # memory entry documenting the ban - "project_zig_unified_api.md" # memory entry documenting the replacement -) - -EXCLUDE_ARGS=() -for f in "${DOC_EXCLUSIONS[@]}"; do - EXCLUDE_ARGS+=(--exclude="$f") -done - -# Build grep arguments. Use -r to recurse, -n for line numbers, -i for -# case-insensitive matching. Exclude .git, the affinescript subtree, and -# files that legitimately document the ban. -HITS=$(grep -rni -E "$PATTERN_OR" "$REPO_ROOT" \ - --exclude-dir=.git \ - --exclude-dir=affinescript \ - --exclude-dir=node_modules \ - "${EXCLUDE_ARGS[@]}" \ - 2>/dev/null || true) - -if [ -z "$HITS" ]; then - echo "PASS: no zig references" - exit 0 -fi - -# Count matches -LINES=$(echo "$HITS" | wc -l | tr -d ' ') - -echo "FAIL: $LINES zig reference(s) found (estate rule: ziguage is banned):" >&2 -echo "$HITS" | sed 's|^| |' >&2 -echo "" >&2 -echo "zig has been replaced by zig-unified-api-adapter. Remove these references." >&2 -exit 1 diff --git a/scripts/check-root-shape.sh b/scripts/check-root-shape.sh deleted file mode 100644 index 8f75343..0000000 --- a/scripts/check-root-shape.sh +++ /dev/null @@ -1,70 +0,0 @@ -#!/usr/bin/env bash -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# check-root-shape.sh — fail when the repository root contains entries that -# are not on the canonical allowlist (.machine_readable/root-allow.txt). -# -# Companion to scripts/validate-template.sh: that script enforces required -# files; this one enforces that nothing else has crept in. -# -# Exit codes: -# 0 — root matches allowlist -# 1 — extras found at root (drift) -# 2 — usage / setup error - -set -euo pipefail - -REPO_ROOT="${1:-.}" -ALLOW_FILE="${REPO_ROOT}/.machine_readable/root-allow.txt" - -if [ ! -f "$ALLOW_FILE" ]; then - echo "ERROR: allowlist not found at $ALLOW_FILE" >&2 - exit 2 -fi - -# Build the allow set: strip comments, trailing slashes, and blank lines. -mapfile -t ALLOW < <( - sed -E 's/[[:space:]]*#.*$//' "$ALLOW_FILE" \ - | sed -E 's|/$||' \ - | awk 'NF' -) - -declare -A ALLOW_SET=() -for entry in "${ALLOW[@]}"; do - ALLOW_SET["$entry"]=1 -done - -# Enumerate everything tracked or present at the repository root. -mapfile -t ACTUAL < <( - cd "$REPO_ROOT" && \ - find . -mindepth 1 -maxdepth 1 \ - ! -name '.' \ - -printf '%f\n' \ - | sort -) - -EXTRAS=() -for entry in "${ACTUAL[@]}"; do - if [ -z "${ALLOW_SET[$entry]+x}" ]; then - EXTRAS+=("$entry") - fi -done - -if [ ${#EXTRAS[@]} -eq 0 ]; then - echo "PASS: root matches allowlist (${#ACTUAL[@]} entries, ${#ALLOW[@]} permitted)" - exit 0 -fi - -echo "FAIL: ${#EXTRAS[@]} root entries are not on the allowlist:" >&2 -for e in "${EXTRAS[@]}"; do - if [ -d "$REPO_ROOT/$e" ]; then - echo " - $e/ (directory)" >&2 - else - echo " - $e" >&2 - fi -done -echo "" >&2 -echo "Either move them into the appropriate subdirectory, or add a justified" >&2 -echo "entry to .machine_readable/root-allow.txt." >&2 -exit 1 diff --git a/scripts/init-submodules.sh b/scripts/init-submodules.sh new file mode 100755 index 0000000..955e9d1 --- /dev/null +++ b/scripts/init-submodules.sh @@ -0,0 +1,50 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +set -euo pipefail + +repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +workspace_root="$(cd "${repo_root}/.." && pwd)" + +init_member() { + local group="$1" + local name="$2" + local local_rel="$3" + local dest="${repo_root}/members/${group}/${name}" + local source="${workspace_root}/${local_rel}" + local gitlink + + gitlink="$(git -C "${repo_root}" rev-parse ":members/${group}/${name}" 2>/dev/null || true)" + if [[ -z "${gitlink}" ]]; then + printf 'skip %s/%s: no gitlink recorded\n' "${group}" "${name}" + return 0 + fi + + if [[ -e "${dest}/.git" || -f "${dest}/.git" ]]; then + printf 'present %s/%s\n' "${group}" "${name}" + return 0 + fi + + if [[ ! -d "${source}/.git" ]]; then + printf 'skip %s/%s: local repo not in scope at %s\n' "${group}" "${name}" "${source}" + return 0 + fi + + mkdir -p "$(dirname "${dest}")" + git -c protocol.file.allow=always clone "${source}" "${dest}" + git -C "${dest}" checkout --detach "${gitlink}" + git -C "${repo_root}" submodule absorbgitdirs "members/${group}/${name}" >/dev/null 2>&1 || true + printf 'initialized %s/%s at %s\n' "${group}" "${name}" "${gitlink}" +} + +init_member implementations a2ml-rs "a2ml/a2ml-core/a2ml-rs" +init_member implementations a2ml_ex "a2ml/a2ml_ex" +init_member implementations a2ml_gleam "a2ml/a2ml_gleam" +init_member implementations a2ml-deno "a2ml/a2ml-core/a2ml-deno" +init_member implementations a2ml-haskell "a2ml/a2ml-core/a2ml-haskell" +init_member tooling tree-sitter-a2ml "a2ml/tree-sitter-a2ml" +init_member tooling vscode-a2ml "a2ml/vscode-a2ml" +init_member tooling pandoc-a2ml "a2ml/pandoc-a2ml" +init_member tooling a2mliser "isers/a2mliser" +init_member ci a2ml-validate-action "a2ml/a2ml-validate-action" +init_member ci a2ml-pre-commit "a2ml/a2ml-core/a2ml-pre-commit" +init_member examples a2ml-showcase "a2ml/a2ml-core/a2ml-showcase" diff --git a/scripts/invariant-path.sh b/scripts/invariant-path.sh deleted file mode 100755 index 3f7c05b..0000000 --- a/scripts/invariant-path.sh +++ /dev/null @@ -1,31 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)" -REPO_ROOT="$(cd -- "${SCRIPT_DIR}/.." && pwd)" -IP_ROOT="${REPO_ROOT}/../invariant-path" - -if [[ ! -f "${IP_ROOT}/Cargo.toml" ]]; then - echo "invariant-path workspace not found at ${IP_ROOT}" >&2 - exit 1 -fi - -if [[ $# -eq 0 ]]; then - set -- scan --profile generic --file "${REPO_ROOT}/README.adoc" --artifact-uri "repo://README.adoc" -elif [[ "$1" == "scan" ]]; then - shift - has_profile="false" - for arg in "$@"; do - if [[ "$arg" == "--profile" ]]; then - has_profile="true" - break - fi - done - if [[ "${has_profile}" == "true" ]]; then - set -- scan "$@" - else - set -- scan --profile generic "$@" - fi -fi - -exec cargo run --manifest-path "${IP_ROOT}/Cargo.toml" -p invariant-path-cli -- "$@" diff --git a/scripts/validate-template.sh b/scripts/validate-template.sh deleted file mode 100755 index f54b899..0000000 --- a/scripts/validate-template.sh +++ /dev/null @@ -1,384 +0,0 @@ -#!/bin/bash -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# RSR Template Validation Script -# Verifies that a repository follows the RSR template structure and contains all required files -# -# Exit codes: -# 0 = validation passed -# 1 = validation failed with errors -# 2 = validation failed with warnings (but can proceed) - -set -euo pipefail - -REPO_ROOT="${1:-.}" -VERBOSE="${2:-0}" -ERRORS=0 -WARNINGS=0 - -# ANSI colors -RED='\033[0;31m' -GREEN='\033[0;32m' -YELLOW='\033[1;33m' -BLUE='\033[0;34m' -NC='\033[0m' # No Color - -# Helper functions -log_error() { - echo -e "${RED}ERROR${NC}: $*" >&2 - ERRORS=$((ERRORS + 1)) -} - -log_warning() { - echo -e "${YELLOW}WARN${NC}: $*" >&2 - WARNINGS=$((WARNINGS + 1)) -} - -log_info() { - echo -e "${BLUE}INFO${NC}: $*" >&2 -} - -log_pass() { - echo -e "${GREEN}PASS${NC}: $*" >&2 -} - -check_file_exists() { - local file="$1" - local description="${2:-}" - if [ -f "$REPO_ROOT/$file" ]; then - [ "$VERBOSE" = "1" ] && log_pass "File exists: $file" - return 0 - else - log_error "Required file missing: $file ${description:+(${description})}" - return 1 - fi -} - -check_dir_exists() { - local dir="$1" - local description="${2:-}" - if [ -d "$REPO_ROOT/$dir" ]; then - [ "$VERBOSE" = "1" ] && log_pass "Directory exists: $dir" - return 0 - else - log_error "Required directory missing: $dir ${description:+(${description})}" - return 1 - fi -} - -# Case-tolerant ABI seam checks: accept the canonical case-consistent -# src/interface/Abi/ (matches `module Abi.*`) OR a lowercase src/interface/abi/ -# that some downstream repos ship. Never require BOTH (that would be a case-fold -# collision on case-insensitive filesystems). -check_abi_dir_exists() { - local description="${1:-}" - if [ -d "$REPO_ROOT/src/interface/Abi" ] || [ -d "$REPO_ROOT/src/interface/abi" ]; then - [ "$VERBOSE" = "1" ] && log_pass "Directory exists: src/interface/{Abi,abi}" - return 0 - fi - log_error "Required directory missing: src/interface/Abi ${description:+(${description})}" - return 1 -} -check_abi_file_exists() { - local fname="$1" - local description="${2:-}" - if [ -f "$REPO_ROOT/src/interface/Abi/$fname" ] || [ -f "$REPO_ROOT/src/interface/abi/$fname" ]; then - [ "$VERBOSE" = "1" ] && log_pass "File exists: src/interface/{Abi,abi}/$fname" - return 0 - fi - log_error "Required file missing: src/interface/Abi/$fname ${description:+(${description})}" - return 1 -} - -has_spdx_header() { - local file="$1" - if head -10 "$file" | grep -q "SPDX-License-Identifier"; then - return 0 - fi - return 1 -} - -has_placeholder() { - local file="$1" - if grep -q "{{REPO\|{{OWNER\|{{FORGE\|{{PROJECT\|{{project\|{{AUTHOR" "$file" 2>/dev/null; then - return 0 - fi - return 1 -} - -#============================================================================== -# VALIDATION PHASE 1: CORE STRUCTURE -#============================================================================== - -echo "" -log_info "Phase 1: Core repository structure" -echo "" - -# Root files -check_file_exists "0-AI-MANIFEST.a2ml" "AI manifest (universal entry point)" -check_file_exists "README.adoc" "High-level pitch" -check_file_exists "EXPLAINME.adoc" "Developer deep-dive" -check_file_exists "LICENSE" "License file" -check_file_exists "Justfile" "Task runner" -check_file_exists "AUDIT.adoc" "Release audit gate" - -# Directories -check_dir_exists ".machine_readable" "Machine-readable metadata" -check_dir_exists ".github" "GitHub community metadata" -check_abi_dir_exists "Idris2 ABI definitions" -check_dir_exists "src/interface/ffi" "Zig FFI implementation" -check_dir_exists "src/interface/generated/abi" "Generated C headers" -check_dir_exists "docs" "Documentation" - -#============================================================================== -# VALIDATION PHASE 2: MACHINE-READABLE METADATA -#============================================================================== - -echo "" -log_info "Phase 2: Machine-readable metadata (.machine_readable/)" -echo "" - -check_file_exists ".machine_readable/6a2/STATE.a2ml" "Project state" -check_file_exists ".machine_readable/6a2/META.a2ml" "Architecture decisions" -check_file_exists ".machine_readable/6a2/ECOSYSTEM.a2ml" "Ecosystem position" -check_file_exists ".machine_readable/6a2/anchors/ANCHOR.a2ml" "Semantic boundary anchor" -check_file_exists ".machine_readable/policies/MAINTENANCE-AXES.a2ml" "Maintenance axes" - -#============================================================================== -# VALIDATION PHASE 3: REQUIRED WORKFLOWS (17 minimum) -#============================================================================== - -echo "" -log_info "Phase 3: GitHub Actions workflows" -echo "" - -REQUIRED_WORKFLOWS=( - "hypatia-scan.yml" - "codeql.yml" - "scorecard.yml" - "quality.yml" - "mirror.yml" - "instant-sync.yml" - "guix-nix-policy.yml" - "rsr-antipattern.yml" - "security-policy.yml" - "wellknown-enforcement.yml" - "workflow-linter.yml" - "npm-bun-blocker.yml" - "ts-blocker.yml" - "scorecard-enforcer.yml" - "secret-scanner.yml" -) - -# Check required workflows -for workflow in "${REQUIRED_WORKFLOWS[@]}"; do - if [ -f "$REPO_ROOT/.github/workflows/$workflow" ]; then - [ "$VERBOSE" = "1" ] && log_pass "Workflow found: $workflow" - else - log_error "Required workflow missing: $workflow" - fi -done - -# Verify all workflows have SPDX headers and proper structure -WORKFLOW_FILES=$(find "$REPO_ROOT/.github/workflows" -name "*.yml" -type f 2>/dev/null || true) -WORKFLOW_COUNT=$(echo "$WORKFLOW_FILES" | grep -c "." || true) - -if [ "$WORKFLOW_COUNT" -ge 15 ]; then - log_pass "Found $WORKFLOW_COUNT workflows (>= 15 expected)" -else - log_warning "Found only $WORKFLOW_COUNT workflows (expected >= 15)" -fi - -# Spot-check workflow files for issues -while IFS= read -r workflow_file; do - if [ -z "$workflow_file" ]; then continue; fi - - # Check for SPDX header (optional in YAML workflows, but best practice) - if ! head -5 "$workflow_file" | grep -q "SPDX-License-Identifier"; then - log_warning "Workflow missing SPDX header: $(basename "$workflow_file")" - fi - - # Check for proper YAML structure - if ! grep -q "^name:" "$workflow_file"; then - log_error "Workflow missing 'name' field: $(basename "$workflow_file")" - fi -done <<< "$WORKFLOW_FILES" - -#============================================================================== -# VALIDATION PHASE 4: ABI/FFI SOURCE FILES -#============================================================================== - -echo "" -log_info "Phase 4: Idris2 ABI and Zig FFI source files" -echo "" - -# Idris2 ABI files -check_abi_file_exists "Types.idr" "Core type definitions" -check_abi_file_exists "Layout.idr" "Memory layout specifications" -check_abi_file_exists "Foreign.idr" "FFI foreign declarations" - -# Zig FFI files -check_file_exists "src/interface/ffi/build.zig" "Zig build configuration" -check_file_exists "src/interface/ffi/src/main.zig" "Zig implementation" -check_file_exists "src/interface/ffi/test/integration_test.zig" "Integration tests" - -#============================================================================== -# VALIDATION PHASE 5: PLACEHOLDER TOKENS -#============================================================================== - -echo "" -log_info "Phase 5: Placeholder token replacement (skipped in template repo)" -echo "" - -# Note: Template repo is allowed to have placeholders -# For derived repos, we'd check that placeholders are replaced -if [ "$(basename "$REPO_ROOT")" = "rsr-template-repo" ]; then - log_pass "Skipping placeholder check for template repo" -else - # Check that key files don't have unresolved placeholders - for file in "$REPO_ROOT/README.adoc" "$REPO_ROOT/Justfile" "$REPO_ROOT/.machine_readable/6a2/STATE.a2ml"; do - if [ -f "$file" ]; then - if has_placeholder "$file"; then - log_warning "File contains unresolved placeholders: $(basename "$file")" - fi - fi - done -fi - -#============================================================================== -# VALIDATION PHASE 6: SPDX LICENSE HEADERS -#============================================================================== - -echo "" -log_info "Phase 6: SPDX License Headers" -echo "" - -# Check source files for SPDX headers (excluding build artifacts) -SOURCE_FILES=$(find "$REPO_ROOT/src" -type f \( -name "*.idr" -o -name "*.zig" \) \ - ! -path "*/.zig-cache/*" ! -path "*/zig-cache/*" 2>/dev/null || true) -SOURCE_COUNT=$(echo "$SOURCE_FILES" | grep -c "." || true) -SPDX_COUNT=0 - -while IFS= read -r src_file; do - if [ -z "$src_file" ]; then continue; fi - if has_spdx_header "$src_file"; then - SPDX_COUNT=$((SPDX_COUNT + 1)) - else - log_warning "Source file missing SPDX header: $(basename "$src_file")" - fi -done <<< "$SOURCE_FILES" - -if [ "$SOURCE_COUNT" -gt 0 ]; then - PERCENT=$((SPDX_COUNT * 100 / SOURCE_COUNT)) - log_pass "SPDX headers: $SPDX_COUNT/$SOURCE_COUNT ($PERCENT%)" - if [ "$PERCENT" -lt 100 ]; then - log_warning "Not all source files have SPDX headers" - fi -fi - -#============================================================================== -# VALIDATION PHASE 7: BUILD VERIFICATION -#============================================================================== - -echo "" -log_info "Phase 7: Build system verification" -echo "" - -# Check Zig build -if [ -f "$REPO_ROOT/src/interface/ffi/build.zig" ]; then - if command -v zig &> /dev/null; then - cd "$REPO_ROOT/src/interface/ffi" - if zig build 2>&1 | grep -q "error"; then - log_error "Zig build failed" - else - log_pass "Zig build successful" - fi - cd - > /dev/null - else - log_warning "Zig compiler not found - skipping Zig build check" - fi -else - log_error "Zig build.zig not found" -fi - -# Check Idris2. Prefer a REAL typecheck via the package (abi.ipkg sets the -# sourcedir so the `module Abi.*` namespace resolves); this catches namespace / -# path / import breakage that a bare per-file `idris2 --check` masks as a -# tolerated "module name does not match file name" warning. -if command -v idris2 &> /dev/null; then - if [ -f "$REPO_ROOT/abi.ipkg" ]; then - if (cd "$REPO_ROOT" && idris2 --typecheck abi.ipkg) > /dev/null 2>&1; then - log_pass "Idris2 ABI typechecks (abi.ipkg)" - else - log_error "Idris2 ABI does NOT typecheck (abi.ipkg)" - fi - else - # No package: fall back to a best-effort per-file syntax check (warns on - # the expected namespace/path mismatch). Look in either case of the dir. - IDS_FILES=$(find "$REPO_ROOT/src/interface/Abi" "$REPO_ROOT/src/interface/abi" -name "*.idr" -type f 2>/dev/null || true) - while IFS= read -r ids_file; do - if [ -z "$ids_file" ]; then continue; fi - if ! idris2 --check "$ids_file" 2>&1 | grep -q "Error"; then - log_pass "Idris2 syntax OK: $(basename "$ids_file")" - else - log_warning "Idris2 syntax issue: $(basename "$ids_file")" - fi - done <<< "$IDS_FILES" - fi -else - log_warning "Idris2 compiler not found - skipping Idris2 syntax checks" -fi - -#============================================================================== -# VALIDATION PHASE 8: DOCUMENTATION -#============================================================================== - -echo "" -log_info "Phase 8: Documentation requirements" -echo "" - -check_file_exists "docs/developer/ABI-FFI-README.adoc" "ABI/FFI documentation" -# TOPOLOGY may live at root or under docs/architecture/, .md or .adoc -if [ -f "$REPO_ROOT/TOPOLOGY.adoc" ] || [ -f "$REPO_ROOT/TOPOLOGY.md" ] || \ - [ -f "$REPO_ROOT/docs/architecture/TOPOLOGY.adoc" ] || [ -f "$REPO_ROOT/docs/architecture/TOPOLOGY.md" ]; then - [ "$VERBOSE" = "1" ] && log_pass "Architecture topology found" -else - log_error "Required file missing: TOPOLOGY (root or docs/architecture/, .adoc or .md)" -fi -# CONTRIBUTING.md may live at root or in .github/ (GitHub auto-discovers either) -if [ -f "$REPO_ROOT/CONTRIBUTING.md" ] || [ -f "$REPO_ROOT/.github/CONTRIBUTING.md" ]; then - [ "$VERBOSE" = "1" ] && log_pass "Contribution guide found" -else - log_error "Required file missing: CONTRIBUTING.md (root or .github/)" -fi - -# Governance can be at root or in docs/governance/ -if [ -f "$REPO_ROOT/GOVERNANCE.adoc" ] || [ -f "$REPO_ROOT/GOVERNANCE.md" ] || [ -d "$REPO_ROOT/docs/governance" ]; then - [ "$VERBOSE" = "1" ] && log_pass "Governance files found" -else - log_warning "Governance documentation not found" -fi - -#============================================================================== -# VALIDATION SUMMARY -#============================================================================== - -echo "" -echo "═══════════════════════════════════════════════════════════════════════════════" -echo "VALIDATION SUMMARY" -echo "═══════════════════════════════════════════════════════════════════════════════" -echo "" -echo -e "Errors: ${RED}${ERRORS}${NC}" -echo -e "Warnings: ${YELLOW}${WARNINGS}${NC}" -echo "" - -if [ "$ERRORS" -eq 0 ]; then - echo -e "${GREEN}✓ Validation PASSED${NC}" - [ "$WARNINGS" -gt 0 ] && echo -e " (with $WARNINGS warnings)" - exit 0 -else - echo -e "${RED}✗ Validation FAILED${NC}" - echo " Please fix the errors above." - exit 1 -fi diff --git a/session/README.md b/session/README.md deleted file mode 100644 index ee83d59..0000000 --- a/session/README.md +++ /dev/null @@ -1,46 +0,0 @@ - -# Session Bindings (Thin Local Layer) - -This directory provides local integration for central session-management standards. - -Authoritative protocols live in: - -- `../standards/session-management-standards/` (or `$SESSION_STANDARDS_DIR`) - -This repo keeps only thin bindings: - -- `dispatch.sh` maps canonical commands to central protocol paths. -- `custom-checks.k9` defines repo-local policy checks. -- `local-hooks.sh` provides optional repo-specific hook behavior. - -## Canonical Commands - -- `intake repo ` -- `checkpoint change ` -- `verify maintenance ` -- `verify substantial ` -- `verify release ` -- `close planned ` -- `close urgent ` -- `recover repo ` -- `handover full ` -- `handover split ` -- `handover model ` -- `handover human ` - -## Justfile Aliases - -Run `just session-help` to list aliases, then use recipes such as: - -- `just intake-repo path=.` -- `just checkpoint-change path=.` -- `just verify-maintenance path=.` -- `just close-planned path=.` -- `just handover-model path=.` - -## Runtime Artifacts - -Runtime files are generated per repository in `.session/` and are not canonical standards text. diff --git a/session/custom-checks.k9 b/session/custom-checks.k9 deleted file mode 100644 index bd932fa..0000000 --- a/session/custom-checks.k9 +++ /dev/null @@ -1,15 +0,0 @@ -# Local repository session checks (thin policy layer) -version: "0.1" - -checks: - - id: "session-state-has-next-action" - applies_to: ["close planned", "close urgent", "handover full", "handover split", "handover model", "handover human"] - requirement: "LAST-CANONICAL-COMMAND.md contains next intended action" - - - id: "session-state-has-residual-risks" - applies_to: ["verify maintenance", "verify substantial", "verify release", "recover repo"] - requirement: "Residual risks field is not left blank" - - - id: "session-state-has-recommended-next-protocol" - applies_to: ["intake repo", "checkpoint change", "recover repo", "handover full"] - requirement: "Recommended next protocol is set" diff --git a/session/dispatch.sh b/session/dispatch.sh deleted file mode 100755 index 61dc720..0000000 --- a/session/dispatch.sh +++ /dev/null @@ -1,137 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -if [ "$#" -lt 3 ]; then - cat >&2 <<'USAGE' -Usage: ./session/dispatch.sh - -Canonical commands: - intake repo - checkpoint change - verify maintenance - verify substantial - verify release - close planned - close urgent - recover repo - handover full - handover split - handover model - handover human -USAGE - exit 2 -fi - -verb="$1" -object="$2" -repo_path="$3" -cmd_pair="$verb $object" - -if [ ! -d "$repo_path" ]; then - echo "error: repository path '$repo_path' does not exist" >&2 - exit 2 -fi - -script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -repo_root="$(cd "$script_dir/.." && pwd)" - -standards_dir="${SESSION_STANDARDS_DIR:-}" -if [ -z "$standards_dir" ]; then - if [ -d "$repo_root/../standards/session-management-standards" ]; then - standards_dir="$repo_root/../standards/session-management-standards" - elif [ -d "$repo_root/standards/session-management-standards" ]; then - standards_dir="$repo_root/standards/session-management-standards" - fi -fi - -case "$cmd_pair" in - "intake repo") - protocol_rel="continuity/repo-intake" - ;; - "checkpoint change") - protocol_rel="continuity/checkpoint-before-major-change" - ;; - "verify maintenance") - protocol_rel="verify/maintenance-sweep" - ;; - "verify substantial") - protocol_rel="verify/substantial-completion" - ;; - "verify release") - protocol_rel="verify/release-audit" - ;; - "close planned") - protocol_rel="continuity/planned-session-close" - ;; - "close urgent") - protocol_rel="continuity/emergency-termination" - ;; - "recover repo") - protocol_rel="continuity/recovery-operation" - ;; - "handover full") - protocol_rel="handover/full-transfer" - ;; - "handover split") - protocol_rel="handover/collaborative-transfer" - ;; - "handover model") - protocol_rel="handover/model-transfer" - ;; - "handover human") - protocol_rel="handover/human-transfer" - ;; - *) - echo "error: unsupported canonical command '$cmd_pair'" >&2 - exit 2 - ;; -esac - -session_dir="$repo_path/.session" -mkdir -p "$session_dir" - -command_record="$session_dir/LAST-CANONICAL-COMMAND.md" - -cat > "$command_record" <&2 - echo "canonical: $cmd_pair $repo_path" - echo "mapped protocol: $protocol_rel" -fi - -hooks="$script_dir/local-hooks.sh" -if [ -x "$hooks" ]; then - "$hooks" "$verb" "$object" "$repo_path" -fi - -echo "recorded: $command_record" diff --git a/session/local-hooks.sh b/session/local-hooks.sh deleted file mode 100755 index 20e9fae..0000000 --- a/session/local-hooks.sh +++ /dev/null @@ -1,21 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -verb="${1:-}" -object="${2:-}" -repo_path="${3:-.}" - -session_dir="$repo_path/.session" -mkdir -p "$session_dir" -log_file="$session_dir/local-hooks.log" - -echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) hook: $verb $object $repo_path" >> "$log_file" - -case "$verb $object" in - "verify release") - echo "release hook: ensure AUDIT.adoc and session reports are reviewed" >> "$log_file" - ;; - "close urgent") - echo "urgent hook: prioritize EMERGENCY-CHECKPOINT.md generation" >> "$log_file" - ;; -esac diff --git a/spec/README.adoc b/spec/README.adoc new file mode 100644 index 0000000..4775df6 --- /dev/null +++ b/spec/README.adoc @@ -0,0 +1,11 @@ += A2ML Specification Pointer + +The A2ML specification is not owned in this coordination hub. + +Canonical upstream: + +* Repository: `hyperpolymath/standards` +* Path: `docs/A2ML-SPEC.adoc` +* Pin: `TODO-tag` + +The corresponding governance authority is pinned in link:../ANCHOR.a2ml[]. diff --git a/src/0.1-AI-MANIFEST.a2ml b/src/0.1-AI-MANIFEST.a2ml deleted file mode 100644 index c92e124..0000000 --- a/src/0.1-AI-MANIFEST.a2ml +++ /dev/null @@ -1,27 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "source-pillar" -level: 1 -parent: "../0-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Primary source code directory. Organized by role and architectural - aspect. - -canonical_locations: - core: "core/" - interface: "interface/" - bridges: "bridges/" - contracts: "contracts/" - errors: "errors/" - definitions: "definitions/" - aspects: "aspects/" - -invariants: - - "Core logic MUST reside in core/" - - "Verified seams MUST reside in interface/" - - "Safety constraints MUST reside in contracts/" - - "Failure dictionaries MUST reside in errors/" diff --git a/src/README.adoc b/src/README.adoc deleted file mode 100644 index d8c8116..0000000 --- a/src/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= src Pillar diff --git a/src/aspects/0.2-AI-MANIFEST.a2ml b/src/aspects/0.2-AI-MANIFEST.a2ml deleted file mode 100644 index 3d5b209..0000000 --- a/src/aspects/0.2-AI-MANIFEST.a2ml +++ /dev/null @@ -1,17 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "source-unit-aspects" -level: 2 -parent: "../0.1-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Cross-cutting concerns and domain-specific aspects (Security, - Observability, Integrity). - -canonical_locations: - security: "security/" - observability: "observability/" - integrity: "integrity/" diff --git a/src/aspects/README.adoc b/src/aspects/README.adoc deleted file mode 100644 index 71e8033..0000000 --- a/src/aspects/README.adoc +++ /dev/null @@ -1,56 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Aspects Pillar -:icons: font - -[.lead] -The **Aspects Pillar** is where a project declares the cross-cutting -_capabilities_ it wears — the **Aspect-Oriented Language Design (AOLD)** seam of -an RSR repository. - -== What an "aspect" is - -An aspect is a capability woven in from a _specialist language_ without adopting -that language wholesale: distribution (Chapel), GPU kernels (Futhark), -data-race freedom (Pony), fault tolerance (OTP), correct-by-construction proof -(Dafny), energy-awareness (Eclexia), reversibility (Oblíbený), and so on. - -Each aspect is delivered by an **-iser** — a Rust CLI that injects the -capability through a uniform, proof-carrying pipeline: - -[literal] -.... - manifest ──► Idris2 ABI ──► Zig FFI ──► target-language codegen ──► build/run -.... - -Your application stays itself; the aspect is an _addable, removable, reversible_ -exoskeleton bolted on at the boundary (the "mech suit" model). Multiple aspects -compose over the same Idris2-ABI/Zig-FFI seam — the _Integrated Stack of Stacks_ -(iSOS). - -== What lives in `src/aspects/` - -Sub-pillars for the cross-cutting concerns this repo weaves in, e.g.: - -* `integrity/` — attestation, tamper-evidence, provenance. -* `observability/` — logging, metrics, tracing. -* `security/` — authz, sandboxing, supply-chain controls. - -A project records _which_ aspects it wears (and the manifest that configures -each -iser) here, so the augmentation is explicit, auditable, and reversible — -never hidden in the core. - -== Keeping aspects honest - -When an aspect crosses the FFI seam into the host, its proven invariant must not -be silently over-generalised (`theorem → guarantee → "universal claim"`). The -**invariant-path** tool is the conscience of this pillar: it traces each aspect's -proven invariant from its Idris2 ABI into the host call sites and flags any point -where the guarantee is carried further than it was proved. - -== See also - -* https://github.com/hyperpolymath/iseriser/blob/main/docs/ATLAS.adoc[The -iser Atlas] — route a need to the right aspect. -* https://github.com/hyperpolymath/iseriser/blob/main/docs/theory/AOLD.adoc[AOLD] — the design philosophy. -* https://github.com/hyperpolymath/iseriser/blob/main/docs/theory/iSOS.adoc[iSOS] — composing aspects. -* https://github.com/hyperpolymath/invariant-path[invariant-path] — the claim-path conscience. diff --git a/src/aspects/integrity/0.3-AI-MANIFEST.a2ml b/src/aspects/integrity/0.3-AI-MANIFEST.a2ml deleted file mode 100644 index f114cbd..0000000 --- a/src/aspects/integrity/0.3-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "aspect-unit-integrity" -level: 3 -parent: "../0.2-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Implementation logic for the integrity aspect. diff --git a/src/aspects/integrity/README.adoc b/src/aspects/integrity/README.adoc deleted file mode 100644 index 17a09db..0000000 --- a/src/aspects/integrity/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Integrity Aspect diff --git a/src/aspects/observability/0.3-AI-MANIFEST.a2ml b/src/aspects/observability/0.3-AI-MANIFEST.a2ml deleted file mode 100644 index e16cbdf..0000000 --- a/src/aspects/observability/0.3-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "aspect-unit-observability" -level: 3 -parent: "../0.2-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Implementation logic for the observability aspect. diff --git a/src/aspects/observability/README.adoc b/src/aspects/observability/README.adoc deleted file mode 100644 index df2ca36..0000000 --- a/src/aspects/observability/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Observability Aspect diff --git a/src/aspects/security/0.3-AI-MANIFEST.a2ml b/src/aspects/security/0.3-AI-MANIFEST.a2ml deleted file mode 100644 index 0996536..0000000 --- a/src/aspects/security/0.3-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "aspect-unit-security" -level: 3 -parent: "../0.2-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Implementation logic for the security aspect. diff --git a/src/aspects/security/README.adoc b/src/aspects/security/README.adoc deleted file mode 100644 index 11ad21b..0000000 --- a/src/aspects/security/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Security Aspect diff --git a/src/bridges/0.2-AI-MANIFEST.a2ml b/src/bridges/0.2-AI-MANIFEST.a2ml deleted file mode 100644 index 3d3e27a..0000000 --- a/src/bridges/0.2-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "source-unit-bridges" -level: 2 -parent: "../0.1-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Integration logic for external systems (API, Database, RPC, etc.). diff --git a/src/contracts/0.2-AI-MANIFEST.a2ml b/src/contracts/0.2-AI-MANIFEST.a2ml deleted file mode 100644 index 0bd9198..0000000 --- a/src/contracts/0.2-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "source-unit-contracts" -level: 2 -parent: "../0.1-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Contracts unit for high-rigor source code. diff --git a/src/contracts/README.adoc b/src/contracts/README.adoc deleted file mode 100644 index 20dd4ca..0000000 --- a/src/contracts/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Contracts Unit diff --git a/src/core/0.2-AI-MANIFEST.a2ml b/src/core/0.2-AI-MANIFEST.a2ml deleted file mode 100644 index 22846c7..0000000 --- a/src/core/0.2-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "source-unit-core" -level: 2 -parent: "../0.1-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Primary application logic and core domain models. diff --git a/src/definitions/0.2-AI-MANIFEST.a2ml b/src/definitions/0.2-AI-MANIFEST.a2ml deleted file mode 100644 index e54f4da..0000000 --- a/src/definitions/0.2-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "source-unit-definitions" -level: 2 -parent: "../0.1-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Definitions unit for high-rigor source code. diff --git a/src/definitions/README.adoc b/src/definitions/README.adoc deleted file mode 100644 index 5a9912f..0000000 --- a/src/definitions/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Definitions Unit diff --git a/src/errors/0.2-AI-MANIFEST.a2ml b/src/errors/0.2-AI-MANIFEST.a2ml deleted file mode 100644 index dddcc6c..0000000 --- a/src/errors/0.2-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "source-unit-errors" -level: 2 -parent: "../0.1-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Errors unit for high-rigor source code. diff --git a/src/errors/README.adoc b/src/errors/README.adoc deleted file mode 100644 index eff7b29..0000000 --- a/src/errors/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Errors Unit diff --git a/src/interface/0.2-AI-MANIFEST.a2ml b/src/interface/0.2-AI-MANIFEST.a2ml deleted file mode 100644 index 7f0f471..0000000 --- a/src/interface/0.2-AI-MANIFEST.a2ml +++ /dev/null @@ -1,24 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "interface-seams-unit" -level: 2 -parent: "../0.1-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Consolidated "Verified Interface Seams" unit. This directory unifies the - formal specification (ABI), the bridge implementation (FFI), and the - resulting artifacts (Generated). - -canonical_locations: - abi: "abi/" - ffi: "ffi/" - generated: "generated/" - -invariants: - - "ABI MUST be Idris2 (.idr)" - - "FFI MUST be Zig (.zig)" - - "Generated artifacts MUST be C-compatible" - - "The 'Truth' lives in abi/; the 'Implementation' lives in ffi/" diff --git a/src/interface/Abi/0.3-AI-MANIFEST.a2ml b/src/interface/Abi/0.3-AI-MANIFEST.a2ml deleted file mode 100644 index 91cafa0..0000000 --- a/src/interface/Abi/0.3-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "abi-logic" -level: 3 -parent: "../0.2-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Specialised Level 3 logic for abi. diff --git a/src/interface/Abi/Foreign.idr b/src/interface/Abi/Foreign.idr deleted file mode 100644 index ca66b08..0000000 --- a/src/interface/Abi/Foreign.idr +++ /dev/null @@ -1,83 +0,0 @@ --- SPDX-License-Identifier: MPL-2.0 --- Copyright (c) Jonathan D.A. Jewell -||| Foreign Function Interface Bridge -||| -||| This module defines the raw FFI calls and their safe wrappers, -||| implemented in the Zig FFI layer. - -module Abi.Foreign - -import Abi.Types -import Abi.Layout - -%default total - --------------------------------------------------------------------------------- --- Library Lifecycle --------------------------------------------------------------------------------- - -||| Raw FFI call to initialize the library -%foreign "C:rsr_init,librsr" -prim__init : PrimIO Bits64 - -||| Raw FFI call to free library resources -%foreign "C:rsr_free,librsr" -prim__free : Bits64 -> PrimIO () - -||| Safe wrapper for initialization -export -init : IO (Maybe Handle) -init = do - ptr <- primIO prim__init - pure (createHandle ptr) - -||| Safe wrapper for cleanup -export -free : Handle -> IO () -free h = primIO (prim__free h.ptr) - --------------------------------------------------------------------------------- --- Core Operations --------------------------------------------------------------------------------- - -||| Raw FFI call for main processing -%foreign "C:rsr_process,librsr" -prim__process : Bits64 -> Bits32 -> PrimIO Bits32 - -||| Safe wrapper with error handling -export -process : Handle -> Bits32 -> IO (Either Result Bits32) -process h input = do - result <- primIO (prim__process h.ptr input) - if result == 0 - then pure (Left Error) - else pure (Right result) - --------------------------------------------------------------------------------- --- Status and Metrics --------------------------------------------------------------------------------- - -||| Get the current error description from the library -%foreign "C:rsr_get_error,librsr" -prim__getError : Bits64 -> PrimIO (Ptr String) - -||| Detailed error string helper -export -errorDescription : Result -> String -errorDescription Ok = "Success" -errorDescription Error = "Generic error" -errorDescription InvalidParam = "Invalid parameter" -errorDescription Busy = "Library is busy" - --------------------------------------------------------------------------------- --- Documentation --------------------------------------------------------------------------------- - -||| Summary of ABI safety properties: -||| 1. All functions are total (total keyword enforced). -||| 2. Pointers are verified non-null before being wrapped in Handle. -||| 3. Memory layouts are proven C-ABI compliant in Abi.Layout. -||| 4. FFI boundary uses explicitly tagged types from Abi.Types. -public export -abiSafetyGuarantees : String -abiSafetyGuarantees = "RSR-Template ABI: 4 proven safety properties for FFI integration" diff --git a/src/interface/Abi/Layout.idr b/src/interface/Abi/Layout.idr deleted file mode 100644 index e1f4275..0000000 --- a/src/interface/Abi/Layout.idr +++ /dev/null @@ -1,128 +0,0 @@ --- SPDX-License-Identifier: MPL-2.0 --- Copyright (c) Jonathan D.A. Jewell -||| ABI Layout Verification -||| -||| This module provides formal proofs about memory layout, alignment, -||| and padding for C-compatible structs. - -module Abi.Layout - -import Abi.Types -import Data.Vect -import Data.So - -%default total - --------------------------------------------------------------------------------- --- Alignment Invariants --------------------------------------------------------------------------------- - -||| Predicate: n divides m -public export -data Divides : (n, m : Nat) -> Type where - MkDivides : (k : Nat) -> (0 prf : m = k * n) -> Divides n m - -||| Implementation of divides for common sizes -public export -div8_24 : Divides 8 24 -div8_24 = MkDivides 3 Refl - -public export -div4_0 : Divides 4 0 -div4_0 = MkDivides 0 Refl - -public export -div8_8 : Divides 8 8 -div8_8 = MkDivides 1 Refl - -public export -div8_16 : Divides 8 16 -div8_16 = MkDivides 2 Refl - -||| Calculate padding required for an offset to meet alignment -public export -paddingFor : (offset : Nat) -> (alignment : Nat) -> Nat -paddingFor offset 0 = 0 -paddingFor offset alignment = - let m = offset `mod` alignment in - if m == 0 - then 0 - else alignment `minus` m - -||| Align a size up to the next multiple of alignment -public export -alignUp : (size : Nat) -> (alignment : Nat) -> Nat -alignUp size alignment = - size + paddingFor size alignment - --------------------------------------------------------------------------------- --- Struct Model --------------------------------------------------------------------------------- - -||| Representation of a single field in a struct -public export -record Field where - constructor MkField - name : String - offset : Nat - size : Nat - alignment : Nat - -||| Valid memory layout for a C struct -public export -record StructLayout where - constructor MkStructLayout - {n : Nat} - fields : Vect n Field - totalSize : Nat - alignment : Nat - {auto 0 aligned : Divides alignment totalSize} - --------------------------------------------------------------------------------- --- Compliance Predicates --------------------------------------------------------------------------------- - -||| Proof that all fields in a struct are correctly aligned -public export -data FieldsAligned : Vect n Field -> Type where - NoFields : FieldsAligned [] - ConsField : - (f : Field) -> - (rest : Vect n Field) -> - (0 prf : Divides f.alignment f.offset) -> - FieldsAligned rest -> - FieldsAligned (f :: rest) - -||| Predicate: Struct is C-ABI compliant -public export -data CABICompliant : StructLayout -> Type where - CABIOk : (l : StructLayout) -> - (0 prf : FieldsAligned l.fields) -> - CABICompliant l - --------------------------------------------------------------------------------- --- Example and Proofs --------------------------------------------------------------------------------- - -||| Example: struct { int32_t x; int64_t y; double z; } -||| On 64-bit Linux, this should have size 24, alignment 8. -public export -exampleLayout : StructLayout -exampleLayout = - MkStructLayout - [ MkField "x" 0 4 4 -- Bits32 at offset 0 - , MkField "y" 8 8 8 -- Bits64 at offset 8 (4 bytes padding) - , MkField "z" 16 8 8 -- Double at offset 16 - ] - 24 -- Total size: 24 bytes - 8 -- Alignment: 8 bytes - {aligned = div8_24} - -||| Proof that example layout is valid -public export -exampleLayoutValid : CABICompliant Abi.Layout.exampleLayout -exampleLayoutValid = CABIOk Abi.Layout.exampleLayout ( - ConsField (MkField "x" 0 4 4) _ div4_0 ( - ConsField (MkField "y" 8 8 8) _ div8_8 ( - ConsField (MkField "z" 16 8 8) _ div8_16 ( - NoFields)))) diff --git a/src/interface/Abi/README.adoc b/src/interface/Abi/README.adoc deleted file mode 100644 index 46743d7..0000000 --- a/src/interface/Abi/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= abi Logic diff --git a/src/interface/Abi/Types.idr b/src/interface/Abi/Types.idr deleted file mode 100644 index 9d30051..0000000 --- a/src/interface/Abi/Types.idr +++ /dev/null @@ -1,112 +0,0 @@ --- SPDX-License-Identifier: MPL-2.0 --- Copyright (c) Jonathan D.A. Jewell -||| ABI Type Definitions Template -||| -||| This module defines the Application Binary Interface (ABI) for this library. -||| All type definitions include formal proofs of correctness. - -module Abi.Types - -import Data.Bits -import Data.So -import Data.Vect -import Decidable.Equality - -%default total - --------------------------------------------------------------------------------- --- Platform Model --------------------------------------------------------------------------------- - -||| Target platforms for the FFI bridge -public export -data Platform = Linux | MacOS | Windows | WASM | RISCV - -||| Pointer size in bits per platform -public export -ptrSize : Platform -> Nat -ptrSize Linux = 64 -ptrSize MacOS = 64 -ptrSize Windows = 64 -ptrSize WASM = 32 -ptrSize RISCV = 64 - -||| Current target platform (detected at compile-time) -public export -thisPlatform : Platform -thisPlatform = Linux -- Simplified for template - --------------------------------------------------------------------------------- --- Core Types --------------------------------------------------------------------------------- - -||| Return codes for FFI calls -public export -data Result = Ok | Error | InvalidParam | Busy - -||| Results are decidably equal -public export -implementation DecEq Result where - decEq Ok Ok = Yes Refl - decEq Error Error = Yes Refl - decEq InvalidParam InvalidParam = Yes Refl - decEq Busy Busy = Yes Refl - decEq Ok Error = No (\case Refl impossible) - decEq Ok InvalidParam = No (\case Refl impossible) - decEq Ok Busy = No (\case Refl impossible) - decEq Error Ok = No (\case Refl impossible) - decEq Error InvalidParam = No (\case Refl impossible) - decEq Error Busy = No (\case Refl impossible) - decEq InvalidParam Ok = No (\case Refl impossible) - decEq InvalidParam Error = No (\case Refl impossible) - decEq InvalidParam Busy = No (\case Refl impossible) - decEq Busy Ok = No (\case Refl impossible) - decEq Busy Error = No (\case Refl impossible) - decEq Busy InvalidParam = No (\case Refl impossible) - -||| Opaque handle for library resources -||| Invariant: Handle pointer must be non-null -public export -record Handle where - constructor MkHandle - ptr : Bits64 - 0 prf : So (ptr /= 0) - -||| Returns Nothing if pointer is null -public export -createHandle : Bits64 -> Maybe Handle -createHandle 0 = Nothing -createHandle ptr = case decSo (ptr /= 0) of - Yes p => Just (MkHandle ptr p) - No _ => Nothing - --------------------------------------------------------------------------------- --- C-Types Mapping --------------------------------------------------------------------------------- - -||| Tagged types for C-FFI boundary -public export -data CType = CInt | CUInt | CLong | CULong | CPtrType - -||| Pointer type for platform -public export -CPtr : Platform -> CType -> Type -CPtr p _ = Bits64 -- Simplified for 64-bit template - -||| Size of C types (platform-specific) -public export -cSizeOf : (p : Platform) -> (t : CType) -> Nat -cSizeOf p CInt = 4 -cSizeOf p CUInt = 4 -cSizeOf p CLong = 8 -cSizeOf p CULong = 8 -cSizeOf p CPtrType = 8 - -||| Alignment of C types (platform-specific) -public export -cAlignOf : (p : Platform) -> (t : CType) -> Nat -cAlignOf p CInt = 4 -cAlignOf p CUInt = 4 -cAlignOf p CLong = 8 -cAlignOf p CULong = 8 -cAlignOf p CPtrType = 8 diff --git a/src/interface/README.adoc b/src/interface/README.adoc deleted file mode 100644 index 727b9e7..0000000 --- a/src/interface/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= interface Unit diff --git a/src/interface/ffi/0.3-AI-MANIFEST.a2ml b/src/interface/ffi/0.3-AI-MANIFEST.a2ml deleted file mode 100644 index bf456ae..0000000 --- a/src/interface/ffi/0.3-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "ffi-logic" -level: 3 -parent: "../0.2-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Specialised Level 3 logic for ffi. diff --git a/src/interface/ffi/README.adoc b/src/interface/ffi/README.adoc deleted file mode 100644 index b402d64..0000000 --- a/src/interface/ffi/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= ffi Logic diff --git a/src/interface/ffi/build.zig b/src/interface/ffi/build.zig deleted file mode 100644 index 2607c11..0000000 --- a/src/interface/ffi/build.zig +++ /dev/null @@ -1,19 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -// -// Template FFI Build Configuration (Zig 0.15.2+) -// Note: This is a minimal build file that demonstrates Zig integration - -const std = @import("std"); - -pub fn build(b: *std.Build) void { - _ = b.standardTargetOptions(.{}); - _ = b.standardOptimizeOption(.{}); - - // In Zig 0.15+, tests are run directly with: - // zig build-exe -ftest-runner src/main.zig - // zig build-exe -ftest-runner test/integration_test.zig - // - // This minimal build file provides scaffolding for future expansion. - // Tests can be invoked via command line without explicit build.zig configuration. -} diff --git a/src/interface/ffi/src/0.4-AI-MANIFEST.a2ml b/src/interface/ffi/src/0.4-AI-MANIFEST.a2ml deleted file mode 100644 index 5b5f1b1..0000000 --- a/src/interface/ffi/src/0.4-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "src-unit" -level: 4 -parent: "../0.3-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Src logic at level 4. diff --git a/src/interface/ffi/src/README.adoc b/src/interface/ffi/src/README.adoc deleted file mode 100644 index 4228438..0000000 --- a/src/interface/ffi/src/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Src Logic diff --git a/src/interface/ffi/src/main.zig b/src/interface/ffi/src/main.zig deleted file mode 100644 index f1b2633..0000000 --- a/src/interface/ffi/src/main.zig +++ /dev/null @@ -1,275 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -// {{PROJECT}} FFI Implementation -// -// This module implements the C-compatible FFI declared in src/abi/Foreign.idr -// All types and layouts must match the Idris2 ABI definitions. -// - -const std = @import("std"); - -// Version information (keep in sync with project) -const VERSION = "0.1.0"; -const BUILD_INFO = "{{PROJECT}} built with Zig " ++ @import("builtin").zig_version_string; - -/// Thread-local error storage -threadlocal var last_error: ?[]const u8 = null; - -/// Set the last error message -fn setError(msg: []const u8) void { - last_error = msg; -} - -/// Clear the last error -fn clearError() void { - last_error = null; -} - -//============================================================================== -// Core Types (must match src/abi/Types.idr) -//============================================================================== - -/// Result codes (must match Idris2 Result type) -pub const Result = enum(c_int) { - ok = 0, - @"error" = 1, - invalid_param = 2, - out_of_memory = 3, - null_pointer = 4, -}; - -/// Library handle (opaque to prevent direct access) -pub const Handle = opaque { - // Internal state hidden from C - allocator: std.mem.Allocator, - initialized: bool, - // Add your fields here -}; - -//============================================================================== -// Library Lifecycle -//============================================================================== - -/// Initialize the library -/// Returns a handle, or null on failure -export fn {{project}}_init() ?*Handle { - const allocator = std.heap.c_allocator; - - const handle = allocator.create(Handle) catch { - setError("Failed to allocate handle"); - return null; - }; - - // Initialize handle - handle.* = .{ - .allocator = allocator, - .initialized = true, - }; - - clearError(); - return handle; -} - -/// Free the library handle -export fn {{project}}_free(handle: ?*Handle) void { - const h = handle orelse return; - const allocator = h.allocator; - - // Clean up resources - h.initialized = false; - - allocator.destroy(h); - clearError(); -} - -//============================================================================== -// Core Operations -//============================================================================== - -/// Process data (example operation) -export fn {{project}}_process(handle: ?*Handle, input: u32) Result { - const h = handle orelse { - setError("Null handle"); - return .null_pointer; - }; - - if (!h.initialized) { - setError("Handle not initialized"); - return .@"error"; - } - - // Example processing logic - _ = input; - - clearError(); - return .ok; -} - -//============================================================================== -// String Operations -//============================================================================== - -/// Get a string result (example) -/// Caller must free the returned string -export fn {{project}}_get_string(handle: ?*Handle) ?[*:0]const u8 { - const h = handle orelse { - setError("Null handle"); - return null; - }; - - if (!h.initialized) { - setError("Handle not initialized"); - return null; - } - - // Example: allocate and return a string - const result = h.allocator.dupeZ(u8, "Example result") catch { - setError("Failed to allocate string"); - return null; - }; - - clearError(); - return result.ptr; -} - -/// Free a string allocated by the library -export fn {{project}}_free_string(str: ?[*:0]const u8) void { - const s = str orelse return; - const allocator = std.heap.c_allocator; - - const slice = std.mem.span(s); - allocator.free(slice); -} - -//============================================================================== -// Array/Buffer Operations -//============================================================================== - -/// Process an array of data -export fn {{project}}_process_array( - handle: ?*Handle, - buffer: ?[*]const u8, - len: u32, -) Result { - const h = handle orelse { - setError("Null handle"); - return .null_pointer; - }; - - const buf = buffer orelse { - setError("Null buffer"); - return .null_pointer; - }; - - if (!h.initialized) { - setError("Handle not initialized"); - return .@"error"; - } - - // Access the buffer - const data = buf[0..len]; - _ = data; - - // Process data here - - clearError(); - return .ok; -} - -//============================================================================== -// Error Handling -//============================================================================== - -/// Get the last error message -/// Returns null if no error -export fn {{project}}_last_error() ?[*:0]const u8 { - const err = last_error orelse return null; - - // Return C string (static storage, no need to free) - const allocator = std.heap.c_allocator; - const c_str = allocator.dupeZ(u8, err) catch return null; - return c_str.ptr; -} - -//============================================================================== -// Version Information -//============================================================================== - -/// Get the library version -export fn {{project}}_version() [*:0]const u8 { - return VERSION.ptr; -} - -/// Get build information -export fn {{project}}_build_info() [*:0]const u8 { - return BUILD_INFO.ptr; -} - -//============================================================================== -// Callback Support -//============================================================================== - -/// Callback function type (C ABI) -pub const Callback = *const fn (u64, u32) callconv(.C) u32; - -/// Register a callback -export fn {{project}}_register_callback( - handle: ?*Handle, - callback: ?Callback, -) Result { - const h = handle orelse { - setError("Null handle"); - return .null_pointer; - }; - - const cb = callback orelse { - setError("Null callback"); - return .null_pointer; - }; - - if (!h.initialized) { - setError("Handle not initialized"); - return .@"error"; - } - - // Store callback for later use - _ = cb; - - clearError(); - return .ok; -} - -//============================================================================== -// Utility Functions -//============================================================================== - -/// Check if handle is initialized -export fn {{project}}_is_initialized(handle: ?*Handle) u32 { - const h = handle orelse return 0; - return if (h.initialized) 1 else 0; -} - -//============================================================================== -// Tests -//============================================================================== - -test "lifecycle" { - const handle = {{project}}_init() orelse return error.InitFailed; - defer {{project}}_free(handle); - - try std.testing.expect({{project}}_is_initialized(handle) == 1); -} - -test "error handling" { - const result = {{project}}_process(null, 0); - try std.testing.expectEqual(Result.null_pointer, result); - - const err = {{project}}_last_error(); - try std.testing.expect(err != null); -} - -test "version" { - const ver = {{project}}_version(); - const ver_str = std.mem.span(ver); - try std.testing.expectEqualStrings(VERSION, ver_str); -} diff --git a/src/interface/ffi/test/0.4-AI-MANIFEST.a2ml b/src/interface/ffi/test/0.4-AI-MANIFEST.a2ml deleted file mode 100644 index e02427f..0000000 --- a/src/interface/ffi/test/0.4-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "test-unit" -level: 4 -parent: "../0.3-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Test logic at level 4. diff --git a/src/interface/ffi/test/README.adoc b/src/interface/ffi/test/README.adoc deleted file mode 100644 index cdbb47d..0000000 --- a/src/interface/ffi/test/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Test Logic diff --git a/src/interface/ffi/test/integration_test.zig b/src/interface/ffi/test/integration_test.zig deleted file mode 100644 index 484e156..0000000 --- a/src/interface/ffi/test/integration_test.zig +++ /dev/null @@ -1,66 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -// RSR Template FFI Integration Tests -// -// These tests verify that the Zig FFI correctly implements the Idris2 ABI. -// This is a TEMPLATE FILE — when instantiating a new project: -// 1. Replace "template" with your project name in lowercase -// 2. Link against your actual FFI implementation library -// 3. Uncomment the test functions below -// -// For now, this file contains documentation of what tests should exist. - -const std = @import("std"); - -// NOTE: When instantiated, declare the actual FFI functions here: -// extern fn mylib_init() ?*Handle; -// extern fn mylib_free(?*Handle) void; -// ... etc - -// And define Handle appropriately: -// const Handle = opaque {}; - -test "placeholder test - implementation required" { - // This test ensures the file compiles - // Actual tests depend on FFI implementation - try std.testing.expect(true); -} - -// ============================================================================== -// Example tests (uncomment when instantiated with real FFI): -// ============================================================================== -// -// test "lifecycle: create and destroy handle" { -// const handle = mylib_init() orelse return error.InitFailed; -// defer mylib_free(handle); -// } -// -// test "operations: process with valid handle" { -// const handle = mylib_init() orelse return error.InitFailed; -// defer mylib_free(handle); -// -// const result = mylib_process(handle, 42); -// try std.testing.expectEqual(@as(c_int, 0), result); -// } -// -// test "memory safety: double free is safe" { -// const handle = mylib_init() orelse return error.InitFailed; -// mylib_free(handle); -// mylib_free(handle); // Should not crash -// } -// -// test "strings: get string result from handle" { -// const handle = mylib_init() orelse return error.InitFailed; -// defer mylib_free(handle); -// -// const str = mylib_get_string(handle); -// defer if (str) |s| mylib_free_string(s); -// -// try std.testing.expect(str != null); -// } -// -// test "version: returns non-empty version string" { -// const ver = mylib_version(); -// const ver_str = std.mem.span(ver); -// try std.testing.expect(ver_str.len > 0); -// } diff --git a/src/interface/generated/0.3-AI-MANIFEST.a2ml b/src/interface/generated/0.3-AI-MANIFEST.a2ml deleted file mode 100644 index 0088b80..0000000 --- a/src/interface/generated/0.3-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "generated-logic" -level: 3 -parent: "../0.2-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Specialised Level 3 logic for generated. diff --git a/src/interface/generated/README.adoc b/src/interface/generated/README.adoc deleted file mode 100644 index 93daef2..0000000 --- a/src/interface/generated/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= generated Logic diff --git a/src/interface/generated/abi/.gitkeep b/src/interface/generated/abi/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/src/interface/generated/abi/0.4-AI-MANIFEST.a2ml b/src/interface/generated/abi/0.4-AI-MANIFEST.a2ml deleted file mode 100644 index 4eeb580..0000000 --- a/src/interface/generated/abi/0.4-AI-MANIFEST.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "abi-unit" -level: 4 -parent: "../0.3-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Abi logic at level 4. diff --git a/src/interface/generated/abi/README.adoc b/src/interface/generated/abi/README.adoc deleted file mode 100644 index 0e29b69..0000000 --- a/src/interface/generated/abi/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -// SPDX-License-Identifier: MPL-2.0 -// Copyright (c) Jonathan D.A. Jewell -= Abi Logic diff --git a/tests/aspect_tests.sh b/tests/aspect_tests.sh deleted file mode 100755 index 028b2c0..0000000 --- a/tests/aspect_tests.sh +++ /dev/null @@ -1,134 +0,0 @@ -#!/usr/bin/env bash -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# RSR Standard Aspect Test Template -# -# Aspect tests validate cross-cutting architectural invariants that span -# the entire codebase. These are NOT functional tests — they verify that -# coding standards, safety rules, and structural contracts hold. -# -# Usage: -# bash tests/aspect_tests.sh -# just aspect -# -# Standard aspects (enable what applies to your project): -# 1. SPDX compliance — all source files have license headers -# 2. Dangerous patterns — no believe_me, assert_total, sorry, unsafeCoerce, etc. -# 3. ABI/FFI contract — declarations match exports -# 4. Thread safety — mutex in FFI modules -# 5. Error handling — no panic/unreachable in production paths - -set -euo pipefail - -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)" -cd "$PROJECT_DIR" - -PASS=0 -FAIL=0 -WARN=0 - -green() { printf '\033[32m%s\033[0m\n' "$*"; } -red() { printf '\033[31m%s\033[0m\n' "$*"; } -yellow(){ printf '\033[33m%s\033[0m\n' "$*"; } -bold() { printf '\033[1m%s\033[0m\n' "$*"; } - -pass() { green " PASS: $1"; PASS=$((PASS + 1)); } -fail() { red " FAIL: $1"; FAIL=$((FAIL + 1)); } -warn() { yellow " WARN: $1"; WARN=$((WARN + 1)); } - -echo "═══════════════════════════════════════════════════════════════" -echo " {{PROJECT}} — Aspect Tests (Cross-Cutting Concerns)" -echo "═══════════════════════════════════════════════════════════════" -echo "" - -# ═══════════════════════════════════════════════════════════════════════ -# Aspect 1: SPDX License Headers -# ═══════════════════════════════════════════════════════════════════════ -bold "Aspect 1: SPDX license headers" - -MISSING_SPDX=0 -while IFS= read -r -d '' f; do - if ! head -5 "$f" | grep -q "SPDX-License-Identifier"; then - warn "Missing SPDX header: $f" - MISSING_SPDX=$((MISSING_SPDX + 1)) - fi -done < <(find src/ -type f \( -name "*.rs" -o -name "*.zig" -o -name "*.res" -o -name "*.ex" -o -name "*.exs" -o -name "*.gleam" -o -name "*.idr" -o -name "*.sh" \) -print0 2>/dev/null) - -if [ "$MISSING_SPDX" -eq 0 ]; then - pass "All source files have SPDX headers" -else - fail "$MISSING_SPDX files missing SPDX headers" -fi - -# ═══════════════════════════════════════════════════════════════════════ -# Aspect 2: Dangerous Patterns (BANNED) -# ═══════════════════════════════════════════════════════════════════════ -bold "Aspect 2: Dangerous patterns" - -# Idris2 dangerous patterns -DANGEROUS_IDRIS=$(grep -rn 'believe_me\|assert_total\|really_believe_me' src/abi/ 2>/dev/null | grep -v "^Binary" | grep -v "test" || true) -if [ -n "$DANGEROUS_IDRIS" ]; then - fail "Dangerous Idris2 patterns found:" - echo "$DANGEROUS_IDRIS" | head -5 -else - pass "No dangerous Idris2 patterns (believe_me, assert_total)" -fi - -# Coq/Lean dangerous patterns -DANGEROUS_PROOF=$(grep -rn '\bAdmitted\b\|\bsorry\b\|\bunsafeCoerce\b\|\bObj\.magic\b' src/ verification/ 2>/dev/null | grep -v "test" | grep -v "comment" || true) -if [ -n "$DANGEROUS_PROOF" ]; then - fail "Dangerous proof patterns found:" - echo "$DANGEROUS_PROOF" | head -5 -else - pass "No dangerous proof patterns (Admitted, sorry, unsafeCoerce)" -fi - -# ═══════════════════════════════════════════════════════════════════════ -# Aspect 3: ABI/FFI Contract (if applicable) -# ═══════════════════════════════════════════════════════════════════════ -# Uncomment if your project has Idris2 ABI + Zig FFI: - -# bold "Aspect 3: ABI/FFI contract" -# if [ -d "src/abi" ] && [ -d "ffi/zig" ]; then -# # Check that every exported function in Idris2 ABI has a Zig FFI implementation -# ABI_EXPORTS=$(grep -h 'export' src/abi/*.idr 2>/dev/null | wc -l) -# FFI_EXPORTS=$(grep -h 'pub export fn' ffi/zig/src/*.zig 2>/dev/null | wc -l) -# if [ "$ABI_EXPORTS" -gt 0 ] && [ "$FFI_EXPORTS" -gt 0 ]; then -# pass "ABI ($ABI_EXPORTS exports) and FFI ($FFI_EXPORTS exports) both present" -# else -# fail "ABI/FFI mismatch: $ABI_EXPORTS ABI exports, $FFI_EXPORTS FFI exports" -# fi -# else -# pass "ABI/FFI not applicable (no src/abi or ffi/zig)" -# fi - -# ═══════════════════════════════════════════════════════════════════════ -# Aspect 4: Error Handling (no raw panic in production code) -# ═══════════════════════════════════════════════════════════════════════ -# Uncomment for Rust projects: - -# bold "Aspect 4: Error handling" -# UNWRAP_COUNT=$(grep -rn '\.unwrap()' src/ 2>/dev/null | grep -v "test" | grep -v "example" | wc -l) -# if [ "$UNWRAP_COUNT" -gt 20 ]; then -# warn "$UNWRAP_COUNT .unwrap() calls in src/ — consider replacing with ? or expect()" -# else -# pass "Acceptable unwrap count: $UNWRAP_COUNT" -# fi - -# ═══════════════════════════════════════════════════════════════════════ -# Summary -# ═══════════════════════════════════════════════════════════════════════ -echo "" -echo "═══════════════════════════════════════════════════════════════" -printf " Results: " -green "PASS=$PASS" | tr -d '\n' -echo -n " " -if [ "$FAIL" -gt 0 ]; then red "FAIL=$FAIL" | tr -d '\n'; else echo -n "FAIL=0"; fi -echo -n " " -if [ "$WARN" -gt 0 ]; then yellow "WARN=$WARN"; else echo "WARN=0"; fi -echo "" -echo "═══════════════════════════════════════════════════════════════" - -exit "$FAIL" diff --git a/tests/e2e.sh b/tests/e2e.sh deleted file mode 100755 index 11143fc..0000000 --- a/tests/e2e.sh +++ /dev/null @@ -1,142 +0,0 @@ -#!/usr/bin/env bash -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# RSR Standard E2E Test Template -# -# End-to-end tests validate the full pipeline: build → run → verify output. -# Customise this file for your project. Delete the examples that don't apply. -# -# Usage: -# bash tests/e2e.sh -# just e2e -# -# Merge requirements (STANDING): All 6 test categories must pass before merge: -# P2P, E2E (this file), aspect, execution, lifecycle, benchmarks - -set -euo pipefail - -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)" - -PASS=0 -FAIL=0 -SKIP=0 - -# ─── Colour helpers ────────────────────────────────────────────────── -green() { printf '\033[32m%s\033[0m\n' "$*"; } -red() { printf '\033[31m%s\033[0m\n' "$*"; } -yellow(){ printf '\033[33m%s\033[0m\n' "$*"; } -bold() { printf '\033[1m%s\033[0m\n' "$*"; } - -# ─── Assertion helpers ─────────────────────────────────────────────── - -# check