From fa62dd571f4f2d39221ffbeb120f37958995127a Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 4 Nov 2026 23:54:20 +0000 Subject: [PATCH 1/4] chore(template): move the scaffolding to rsr-template-repo c481073 secret-types was created from rsr-template-repo 05bf1b9 (2026-09-24; the Initial commit's tree is that commit's tree) and never minted, so Canon lockstep still fetches the profile from hyperpolymath/rsr-template-repo/ and can never pass (as #14 recorded), and openssf-compliance fails on unfilled tokens. The template has since retired the .a2ml descriptiles for clauses of the repo deed (D312) and reads the canon pin from the deed through github.repository. This commit lays the template's tree at c481073 over the repository and restores, unchanged, every file secret-types owns: everything added since the Initial commit (src/SecretTypes, tests/reject, tests/minimal-laws, scripts/check.sh, minimal-laws.sh, proof-flags.sh, grade-receipt.sh, dev-toolchain.sh, secret-types.agda-lib, proofs.yml, PROOF-STATUS.adoc, verification/receipts/agda-grade3.a2ml, docs/*), README.adoc and docs/EXPLAINME.adoc, and the six reusable-workflow callers #15 pinned to metadatastician/standards@46ee183 (governance, hypatia-scan, mirror, rust-ci, scorecard, secret-scanner): owner decision 2026-11-04, keep #15's callers. Licence files are untouched (doctrine 6): LICENSE, LICENSES/ and docs/legal/ are byte-identical to main, and the template's LICENSE.adoc is not added. It is not minted yet: the next commit runs repo-init on this tree. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01BYbQRtNu216R13jtZLmoqs --- .clinerules | 29 +- .coderabbit.yaml | 33 + .cursorrules | 54 - .devcontainer/Containerfile | 26 +- .devcontainer/README.adoc | 47 +- .devcontainer/devcontainer.json | 61 +- .devcontainer/docker/devcontainer.json | 61 + .editorconfig | 3 - .envrc | 8 +- .gitattributes | 3 +- .gitbot-fleet/enrolment.json | 1 + .gitbot-fleet/report-backs/README.md | 35 + .github/CODEOWNERS | 13 +- .github/CODE_OF_CONDUCT.md | 338 ---- .github/CONTRIBUTING.md | 120 -- .github/{GOVERNANCE.md => GOVERNANCE.adoc} | 2 +- .github/actions/squabble/README.adoc | 123 ++ .github/actions/squabble/action.yml | 68 + .github/actions/squabble/install.sh | 146 ++ .github/actions/squabble/run.sh | 39 + .github/copilot-instructions.md | 27 +- .github/dependabot.yml | 22 +- .github/hooks/pre-push | 7 +- .github/hooks/scan-secrets.sh | 2 +- .github/hooks/validate-deed.sh | 406 +---- .github/hooks/validate-k9.sh | 407 +---- .github/label-classifier.json | 740 +------- .github/labels.json | 261 +-- .github/pull_request_template.md | 9 +- .github/rulesets/Immutable-Tags.json | 29 +- .github/rulesets/README.adoc | 103 +- .github/rulesets/base.json | 103 +- .github/rulesets/branch-floor.json | 1 + .github/rulesets/require-linear-history.json | 1 + .github/rulesets/require-signed-commits.json | 1 + .github/workflows/README.adoc | 182 ++ .github/workflows/actions.lock | 181 +- .github/workflows/build-notification.yml | 2 +- .github/workflows/codeql.yml | 2 +- .github/workflows/deed-validate.yml | 59 - .github/workflows/dependabot-automerge.yml | 173 +- .github/workflows/docker-build.yml | 8 +- .github/workflows/dogfood-gate.yml | 546 +++--- .github/workflows/dogfood-summary.yml | 6 +- .../workflows/dot-wellknown-enforcement.yml | 2 +- .github/workflows/e2e.yml.template | 43 +- .github/workflows/eclexiaiser-validate.yml | 8 +- .github/workflows/empty-linter.yml | 12 +- .github/workflows/estate-rules.yml | 188 +- .github/workflows/fork-governance.yml | 465 +++++ .github/workflows/groove-check.yml | 24 +- .github/workflows/guix-policy.yml | 2 +- .github/workflows/k9-validate.yml | 64 - .github/workflows/label-triage.yml | 4 +- .github/workflows/labels.yml | 4 +- .github/workflows/lock-sync-gate.yml | 5 +- .github/workflows/main-estate-audit.yml | 64 +- .github/workflows/ossf-best-practices.yml | 34 +- .github/workflows/pages.yml | 4 +- .github/workflows/proven-tests.yml | 108 ++ .github/workflows/push-email-notify.yml | 4 +- .github/workflows/quality.yml | 46 +- .github/workflows/release.yml | 14 +- .github/workflows/rsr-compliance-canary.yml | 12 +- .github/workflows/runtime-policy.yml | 72 - .github/workflows/security-policy.yml | 6 +- .github/workflows/sonarqube.yml | 4 +- .github/workflows/squabble.yml | 93 + .github/workflows/static-analysis-gate.yml | 637 ++++--- .github/workflows/verdict-grid-publish.yml | 169 ++ .github/workflows/workflow-linter.yml | 19 +- .gitignore | 8 +- .hypatia-ignore | 7 + .machine_readable/ENSAID_CONFIG.a2ml | 96 - .machine_readable/README.adoc | 17 +- .machine_readable/ai/AI.a2ml | 38 - .machine_readable/ai/PLACEHOLDERS.adoc | 42 +- .machine_readable/ai/README.adoc | 81 +- .machine_readable/arrival-pack/README.adoc | 19 +- .../arrival-pack/arrival-pack.ncl | 48 +- .../arrival-pack/claude-md.k9.ncl | 17 +- .machine_readable/arrival-pack/extract.sh | 162 +- .machine_readable/arrival-pack/generate.sh | 6 +- .machine_readable/arrival-pack/verify.sh | 6 +- .machine_readable/bot_directives/README.adoc | 34 +- .../bot_directives/coverage.a2ml | 61 - .machine_readable/bot_directives/debt.a2ml | 49 - .../bot_directives/methodology.a2ml | 115 -- .machine_readable/bot_directives/rra.a2ml | 55 - .machine_readable/coaptation/README.adoc | 25 +- .machine_readable/coaptation/coapt.k9.ncl | 29 +- .machine_readable/coaptation/coapt.ncl | 10 +- .machine_readable/coaptation/coapt.sh | 31 +- .../coaptation/core/Coaptation.idr | 2 + .../coaptation/extract-clauses.sh | 135 +- .machine_readable/coaptation/extract-facts.sh | 180 +- .../coaptation/receipts/latest.a2ml | 100 - .../coaptation/receipts/latest.toml | 102 ++ .machine_readable/coaptation/verify.sh | 6 +- .machine_readable/coaptation/witness-map.ncl | 56 +- .machine_readable/contractiles/INDEX.a2ml | 133 -- .machine_readable/contractiles/Justfile | 208 +-- .machine_readable/contractiles/README.adoc | 137 +- .machine_readable/contractiles/_base.ncl | 4 +- .../contractiles/adjust/Adjustfile.a2ml | 72 - .../contractiles/adjust/adjust.k9.ncl | 136 +- .../contractiles/adjust/adjust.manifest.a2ml | 47 - .../contractiles/adjust/adjust.ncl | 8 +- .../contractiles/bust/Bustfile.a2ml | 52 - .../contractiles/bust/bust.k9.ncl | 110 +- .../contractiles/bust/bust.manifest.a2ml | 48 - .machine_readable/contractiles/bust/bust.ncl | 6 +- .../contractiles/dust/Dustfile.a2ml | 75 - .../contractiles/dust/dust.k9.ncl | 126 +- .../contractiles/dust/dust.manifest.a2ml | 51 - .machine_readable/contractiles/dust/dust.ncl | 8 +- .../contractiles/intend/Intentfile.a2ml | 99 - .../contractiles/intend/intend.k9.ncl | 157 +- .../contractiles/intend/intend.manifest.a2ml | 73 - .../contractiles/intend/intend.ncl | 8 +- .../contractiles/must/Mustfile.a2ml | 103 -- .../contractiles/must/must.k9.ncl | 215 ++- .../contractiles/must/must.manifest.a2ml | 59 - .machine_readable/contractiles/must/must.ncl | 16 +- .../contractiles/trust/Trustfile.a2ml | 105 -- .../contractiles/trust/trust.k9.ncl | 187 +- .../contractiles/trust/trust.manifest.a2ml | 72 - .../contractiles/trust/trust.ncl | 6 +- .machine_readable/descriptiles/AGENTIC.a2ml | 56 - .machine_readable/descriptiles/CLADE.a2ml | 76 - .machine_readable/descriptiles/ECOSYSTEM.a2ml | 45 - .machine_readable/descriptiles/META.a2ml | 53 - .machine_readable/descriptiles/NEUROSYM.a2ml | 23 - .machine_readable/descriptiles/PLAYBOOK.a2ml | 137 -- .machine_readable/descriptiles/README.adoc | 43 +- .machine_readable/descriptiles/STATE.a2ml | 82 - .../descriptiles/anchors/ANCHOR.a2ml | 62 - .../descriptiles/anchors/README.adoc | 26 +- .../descriptiles/provisioning_praxis.deed | 32 + .../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 - .machine_readable/mint-verbatim.txt | 36 + .../policies/MAINTENANCE-AXES.a2ml | 54 - .../policies/MAINTENANCE-CHECKLIST.a2ml | 159 -- .machine_readable/policies/README.adoc | 21 + .../SOFTWARE-DEVELOPMENT-APPROACH.a2ml | 53 - .../policies/hypatia-rule-order.json | 1 + .machine_readable/required-contexts-allow.txt | 11 + .machine_readable/root-allow.txt | 32 +- .machine_readable/rsr-profile.a2ml | 149 -- .../scripts/maintenance/maint-assault.sh | 10 +- .machine_readable/self-validating/README.adoc | 16 +- ...setup-repo.k9.ncl => setup-repo.k9.ncl.in} | 12 +- .../self-validating/methodology-guard.k9.ncl | 22 +- ...te-hunt.k9.ncl => template-hunt.k9.ncl.in} | 0 ...ennel.k9.ncl => template-kennel.k9.ncl.in} | 0 ...te-yard.k9.ncl => template-yard.k9.ncl.in} | 0 .../testing/adversarial-content.k9.ncl | 43 + .tool-versions | 9 - .windsurfrules | 51 - CHANGELOG.adoc | 395 ++++ CITATION.cff | 6 +- CLAUDE.md | 123 +- CODE_OF_CONDUCT.adoc | 32 + CONTRIBUTING.adoc | 20 +- GEMINI.md | 8 - Justfile | 265 +-- .github/SUPPORT.md => SUPPORT.adoc | 0 archetypes/README.adoc | 81 +- archetypes/julia-library/ARCHETYPE.a2ml | 34 - archetypes/julia-library/actions.lock | 41 + .../julia-library/julia-library_praxis.deed | 37 + .../overlay/.github/workflows/actions.lock | 18 - .../overlay/.github/workflows/julia-ci.yml.in | 67 +- .../.github/workflows/julia-docs.yml.in | 88 +- .../descriptiles/provisioning_praxis.deed | 38 + .../julia-library/overlay/Project.toml.in | 16 +- .../overlay/scripts/julia-quality.jl | 129 ++ .../julia-library/overlay/src/PACKAGE.jl.in | 5 +- .../julia-library/overlay/test/cases/smoke.jl | 3 + .../julia-library/overlay/test/runtests.jl | 5 +- archetypes/julia-library/prune.txt | 14 + archetypes/rust-cli/overlay/Cargo.toml.in | 30 + archetypes/rust-cli/overlay/src/lib.rs.in | 22 + archetypes/rust-cli/overlay/src/main.rs.in | 6 + archetypes/rust-cli/overlay/tests/cli.rs.in | 14 + archetypes/rust-cli/prune.txt | 15 + archetypes/rust-cli/rust-cli_praxis.deed | 37 + benches/baseline.json | 1 + benches/template_bench.sh | 325 ++-- build/channels.scm | 18 + build/container/Containerfile | 152 -- build/container/README.adoc | 50 +- build/container/compose.example.yaml | 233 ++- build/container/compose.yaml | 197 +- build/container/stapeln/.gatekeeper.yaml | 257 +-- build/container/stapeln/deploy.k9.ncl | 170 -- build/container/stapeln/deploy.k9.ncl.in | 189 ++ build/guix.scm | 52 +- build/just/assess.just | 62 +- build/just/container.just | 43 +- build/just/groove.just | 47 +- build/just/proofs.just | 9 - build/just/provision-check.sh | 121 ++ build/just/provision-lib.sh | 972 ++++++++++ build/just/provision-modes.sh | 169 ++ build/just/provision.just | 108 ++ build/just/repo-init.just | 1096 +++++++---- build/just/validate.just | 130 +- build/manifest.scm | 15 + build/templates/CLADE.a2ml.in | 127 -- build/templates/ROADMAP.adoc.in | 23 + build/templates/identity.deed.in | 96 + ci/.pre-commit-config.yaml | 15 +- coordination.k9.ncl | 1 + docs/AI-INSTALL-README-SECTION.adoc | 29 +- docs/AI_INSTALLATION_GUIDE.adoc | 76 +- docs/HYPATIA-RULE-ORDER.adoc | 364 ++++ docs/MAINTAINERS.adoc | 4 +- docs/README.adoc | 1 - docs/RSR_OUTLINE.adoc | 52 +- docs/SETUP.adoc | 215 +++ docs/architecture/REPOSITORY-MAP.adoc | 65 +- docs/architecture/THREAT-MODEL.adoc | 2 +- docs/decisions/0001-adopt-rsr-standard.adoc | 4 + docs/decisions/0002-variant-contract.adoc | 2 + .../0003-forge-and-sustain-lifecycle.adoc | 2 + docs/governance/CRG-AUDIT-TEMPLATE.adoc | 34 +- docs/governance/CRG-CRITERIA.a2ml | 108 -- docs/governance/MAINTENANCE-CHECKLIST.adoc | 8 +- docs/governance/TEMPLATE-LINEAGE-AUDIT.adoc | 6 + docs/governance/TEMPLATE-STANDARDS-AUDIT.adoc | 6 +- docs/governance/TSDM.a2ml | 22 - docs/governance/TSDM.adoc | 2 +- docs/onboarding/llm-warmup-dev.adoc | 94 +- docs/onboarding/llm-warmup-maintainer.adoc | 42 + docs/onboarding/llm-warmup-user.adoc | 62 +- docs/practice/AI-CONVENTIONS.adoc | 34 +- docs/practice/STATE-VISUALIZER-GUIDE.adoc | 9 +- docs/practice/ci-cost-reduction.adoc | 2 +- docs/proposals/root-cleanup.adoc | 20 +- .../audit/pillar-audit-2026-04-15.adoc | 2 + .../RSR-TEMPLATE-DAMAGE-2026-10-30.adoc | 486 +++++ docs/status/READINESS.adoc | 38 +- docs/status/ROADMAP.adoc | 72 +- launcher.sh | 42 + mise.lock | 157 ++ mise.toml | 104 +- rsr-template-repo_chora.deed | 982 +++++++++- scripts/bench-stats.jq | 96 + scripts/check-bench-regression.sh | 157 ++ scripts/check-container-pins.sh | 227 +++ scripts/check-escape-hatches.sh | 210 +++ scripts/check-hypatia-ignore.sh | 168 ++ scripts/check-hypatia-rule-order.sh | 204 +++ scripts/check-ijson-jcs.sh | 152 ++ scripts/check-invisible-characters.sh | 2 +- scripts/check-lock-sync.sh | 205 ++- scripts/check-mint-tokens.sh | 214 +++ scripts/check-mise-language.sh | 232 +++ scripts/check-no-a2ml.sh | 30 + scripts/check-no-placeholders.sh | 48 +- scripts/check-no-vlang.sh | 2 - scripts/check-proofs.sh | 4 +- scripts/check-required-contexts.sh | 143 ++ scripts/check-spdx-headers.sh | 330 ++++ scripts/check-template-conformance.sh | 274 +++ scripts/check-variant-drift.sh | 60 +- scripts/check-workflow-edges.sh | 232 +++ scripts/compute-bench-baseline.sh | 118 ++ scripts/deed-clause.sh | 160 ++ scripts/deed-field.sh | 188 ++ scripts/emit-aggregate-inputs.sh | 91 + scripts/gen-repo-map.sh | 29 +- scripts/governance-badge.js | 1030 +++++++++++ scripts/ijson-jcs-cli.js | 408 +++++ scripts/kyaml-format.sh | 126 ++ scripts/merge-actions-lock.rs | 228 +++ scripts/pin-container-digests.sh | 150 ++ scripts/prune-archetype-modules.sh | 76 + scripts/prune-dependabot-ecosystems.rs | 2 + scripts/render-mise.sh | 176 ++ scripts/resolve-template-pin.sh | 186 ++ scripts/rsr-campaign.sh | 36 +- scripts/run-proven-suite.sh | 229 +++ scripts/strip-instruction-blocks.rs | 112 +- scripts/survey-template-damage.sh | 96 + scripts/sweep-wellknown.sh | 15 +- scripts/validate-template.sh | 115 +- scripts/verdict-grid-lane.sh | 550 ++++++ session/custom-checks.k9.ncl | 1 + src/interface/ffi/build.zig | 30 +- src/interface/ffi/src/main.zig | 36 +- tests/aspect_tests.sh | 18 +- tests/e2e.sh | 4 +- tests/e2e/julia_fmt_test.sh | 73 + tests/e2e/julia_mint_test.sh | 155 +- tests/e2e/language_profiles_mint_test.sh | 294 +++ tests/e2e/template_instantiation_test.sh | 147 +- tests/e2e/use_template_mint_test.sh | 228 +++ tests/ffi_strings_test.sh | 111 ++ tests/invisible-characters-test.sh | 6 +- tests/proven_suite_test.sh | 452 +++++ tests/run_proven_suite_test.sh | 157 ++ tests/workflows/archetype_lock_merge_test.sh | 191 ++ tests/workflows/check_ijson_jcs_test.sh | 279 +++ tests/workflows/check_lock_sync_test.sh | 330 ++++ tests/workflows/check_no_a2ml_test.sh | 43 + tests/workflows/container_kyaml_test.sh | 143 ++ tests/workflows/deed_clause_test.sh | 80 + tests/workflows/dependabot_automerge_test.sh | 109 ++ tests/workflows/devcontainer_test.sh | 100 + tests/workflows/governance_badge_test.js | 1606 +++++++++++++++++ tests/workflows/governance_badge_test.sh | 271 +++ tests/workflows/governance_policy_test.sh | 199 ++ tests/workflows/hypatia_ignore_test.sh | 230 +++ tests/workflows/hypatia_rule_order_test.sh | 239 +++ tests/workflows/julia_library_test.sh | 185 ++ tests/workflows/kyaml_format_test.sh | 126 ++ tests/workflows/kyaml_ratchet_test.sh | 256 +++ tests/workflows/mint_cleanup_test.sh | 20 +- tests/workflows/mint_gates_test.sh | 288 +++ tests/workflows/non_interactive_mint_test.sh | 37 + tests/workflows/resolve_template_pin_test.sh | 127 ++ tests/workflows/runtime_policy_fold_test.sh | 169 ++ tests/workflows/self_name_pass_test.sh | 98 + tests/workflows/squabble_gate_test.sh | 390 ++++ tests/workflows/template_conformance_test.sh | 162 ++ tests/workflows/validate_workflows_test.sh | 8 +- tests/workflows/verdict_grid_test.sh | 707 ++++++++ tests/workflows/workflow_edges_test.sh | 181 ++ tests/workflows/workflow_evidence_test.sh | 171 ++ verification/proofs/README.adoc | 94 +- verification/proofs/idris2/ABI/Compliance.idr | 2 +- verification/proofs/idris2/ABI/Foreign.idr | 2 +- verification/proofs/idris2/ABI/Layout.idr | 2 +- verification/proofs/idris2/ABI/Platform.idr | 2 +- verification/proofs/idris2/ABI/Pointers.idr | 2 +- verification/proofs/idris2/Types.idr | 2 +- www/.well-known/ai.txt | 2 +- www/.well-known/aibdp.json | 80 +- www/errors/430.html | 17 + www/schemas/aibdp-schema-v0.2.json | 378 +--- www/tests/check-bind-safety.sh | 2 +- .../controls/aibdp-bad-status.control.json | 8 +- .../controls/aibdp-enforce-430.control.json | 9 +- 349 files changed, 27589 insertions(+), 9831 deletions(-) create mode 100644 .coderabbit.yaml delete mode 100644 .cursorrules create mode 100644 .devcontainer/docker/devcontainer.json create mode 100644 .gitbot-fleet/enrolment.json create mode 100644 .gitbot-fleet/report-backs/README.md delete mode 100644 .github/CODE_OF_CONDUCT.md delete mode 100644 .github/CONTRIBUTING.md rename .github/{GOVERNANCE.md => GOVERNANCE.adoc} (97%) create mode 100644 .github/actions/squabble/README.adoc create mode 100644 .github/actions/squabble/action.yml create mode 100755 .github/actions/squabble/install.sh create mode 100755 .github/actions/squabble/run.sh create mode 100644 .github/rulesets/branch-floor.json create mode 100644 .github/rulesets/require-linear-history.json create mode 100644 .github/rulesets/require-signed-commits.json delete mode 100644 .github/workflows/deed-validate.yml create mode 100644 .github/workflows/fork-governance.yml delete mode 100644 .github/workflows/k9-validate.yml create mode 100644 .github/workflows/proven-tests.yml delete mode 100644 .github/workflows/runtime-policy.yml create mode 100644 .github/workflows/squabble.yml create mode 100644 .github/workflows/verdict-grid-publish.yml delete mode 100644 .machine_readable/ENSAID_CONFIG.a2ml delete mode 100644 .machine_readable/ai/AI.a2ml 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/bot_directives/rra.a2ml delete mode 100644 .machine_readable/coaptation/receipts/latest.a2ml create mode 100644 .machine_readable/coaptation/receipts/latest.toml delete mode 100644 .machine_readable/contractiles/INDEX.a2ml delete mode 100644 .machine_readable/contractiles/adjust/Adjustfile.a2ml delete mode 100644 .machine_readable/contractiles/adjust/adjust.manifest.a2ml delete mode 100644 .machine_readable/contractiles/bust/Bustfile.a2ml delete mode 100644 .machine_readable/contractiles/bust/bust.manifest.a2ml delete mode 100644 .machine_readable/contractiles/dust/Dustfile.a2ml delete mode 100644 .machine_readable/contractiles/dust/dust.manifest.a2ml delete mode 100644 .machine_readable/contractiles/intend/Intentfile.a2ml delete mode 100644 .machine_readable/contractiles/intend/intend.manifest.a2ml delete mode 100644 .machine_readable/contractiles/must/Mustfile.a2ml delete mode 100644 .machine_readable/contractiles/must/must.manifest.a2ml delete mode 100644 .machine_readable/contractiles/trust/Trustfile.a2ml delete mode 100644 .machine_readable/contractiles/trust/trust.manifest.a2ml delete mode 100644 .machine_readable/descriptiles/AGENTIC.a2ml delete mode 100644 .machine_readable/descriptiles/CLADE.a2ml delete mode 100644 .machine_readable/descriptiles/ECOSYSTEM.a2ml delete mode 100644 .machine_readable/descriptiles/META.a2ml delete mode 100644 .machine_readable/descriptiles/NEUROSYM.a2ml delete mode 100644 .machine_readable/descriptiles/PLAYBOOK.a2ml delete mode 100644 .machine_readable/descriptiles/STATE.a2ml delete mode 100644 .machine_readable/descriptiles/anchors/ANCHOR.a2ml create mode 100644 .machine_readable/descriptiles/provisioning_praxis.deed 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 create mode 100644 .machine_readable/mint-verbatim.txt delete mode 100644 .machine_readable/policies/MAINTENANCE-AXES.a2ml delete mode 100644 .machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml delete mode 100644 .machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml create mode 100644 .machine_readable/policies/hypatia-rule-order.json create mode 100644 .machine_readable/required-contexts-allow.txt delete mode 100644 .machine_readable/rsr-profile.a2ml rename .machine_readable/self-validating/examples/{setup-repo.k9.ncl => setup-repo.k9.ncl.in} (89%) rename .machine_readable/self-validating/{template-hunt.k9.ncl => template-hunt.k9.ncl.in} (100%) rename .machine_readable/self-validating/{template-kennel.k9.ncl => template-kennel.k9.ncl.in} (100%) rename .machine_readable/self-validating/{template-yard.k9.ncl => template-yard.k9.ncl.in} (100%) create mode 100644 .machine_readable/testing/adversarial-content.k9.ncl delete mode 100644 .tool-versions delete mode 100644 .windsurfrules create mode 100644 CODE_OF_CONDUCT.adoc delete mode 100644 GEMINI.md rename .github/SUPPORT.md => SUPPORT.adoc (100%) delete mode 100644 archetypes/julia-library/ARCHETYPE.a2ml create mode 100644 archetypes/julia-library/actions.lock create mode 100644 archetypes/julia-library/julia-library_praxis.deed delete mode 100644 archetypes/julia-library/overlay/.github/workflows/actions.lock create mode 100644 archetypes/julia-library/overlay/.machine_readable/descriptiles/provisioning_praxis.deed create mode 100644 archetypes/julia-library/overlay/scripts/julia-quality.jl create mode 100644 archetypes/julia-library/prune.txt create mode 100644 archetypes/rust-cli/overlay/Cargo.toml.in create mode 100644 archetypes/rust-cli/overlay/src/lib.rs.in create mode 100644 archetypes/rust-cli/overlay/src/main.rs.in create mode 100644 archetypes/rust-cli/overlay/tests/cli.rs.in create mode 100644 archetypes/rust-cli/prune.txt create mode 100644 archetypes/rust-cli/rust-cli_praxis.deed create mode 100644 benches/baseline.json create mode 100644 build/channels.scm delete mode 100644 build/container/Containerfile delete mode 100644 build/container/stapeln/deploy.k9.ncl create mode 100644 build/container/stapeln/deploy.k9.ncl.in create mode 100755 build/just/provision-check.sh create mode 100755 build/just/provision-lib.sh create mode 100755 build/just/provision-modes.sh create mode 100644 build/just/provision.just create mode 100644 build/manifest.scm delete mode 100644 build/templates/CLADE.a2ml.in create mode 100644 build/templates/ROADMAP.adoc.in create mode 100644 build/templates/identity.deed.in create mode 100644 docs/HYPATIA-RULE-ORDER.adoc create mode 100644 docs/SETUP.adoc delete mode 100644 docs/governance/CRG-CRITERIA.a2ml delete mode 100644 docs/governance/TSDM.a2ml create mode 100644 docs/onboarding/llm-warmup-maintainer.adoc create mode 100644 docs/reports/compliance/RSR-TEMPLATE-DAMAGE-2026-10-30.adoc create mode 100755 launcher.sh create mode 100644 mise.lock create mode 100644 scripts/bench-stats.jq create mode 100755 scripts/check-bench-regression.sh create mode 100644 scripts/check-container-pins.sh create mode 100755 scripts/check-escape-hatches.sh create mode 100755 scripts/check-hypatia-ignore.sh create mode 100755 scripts/check-hypatia-rule-order.sh create mode 100755 scripts/check-ijson-jcs.sh create mode 100644 scripts/check-mint-tokens.sh create mode 100644 scripts/check-mise-language.sh create mode 100755 scripts/check-no-a2ml.sh create mode 100755 scripts/check-required-contexts.sh create mode 100755 scripts/check-spdx-headers.sh create mode 100755 scripts/check-template-conformance.sh create mode 100755 scripts/check-workflow-edges.sh create mode 100755 scripts/compute-bench-baseline.sh create mode 100755 scripts/deed-clause.sh create mode 100755 scripts/deed-field.sh create mode 100755 scripts/emit-aggregate-inputs.sh create mode 100644 scripts/governance-badge.js create mode 100755 scripts/ijson-jcs-cli.js create mode 100755 scripts/kyaml-format.sh create mode 100644 scripts/merge-actions-lock.rs create mode 100755 scripts/pin-container-digests.sh create mode 100755 scripts/prune-archetype-modules.sh create mode 100755 scripts/render-mise.sh create mode 100755 scripts/resolve-template-pin.sh create mode 100755 scripts/run-proven-suite.sh create mode 100755 scripts/survey-template-damage.sh create mode 100755 scripts/verdict-grid-lane.sh create mode 100644 tests/e2e/julia_fmt_test.sh create mode 100644 tests/e2e/language_profiles_mint_test.sh create mode 100755 tests/e2e/use_template_mint_test.sh create mode 100644 tests/ffi_strings_test.sh create mode 100755 tests/proven_suite_test.sh create mode 100644 tests/run_proven_suite_test.sh create mode 100755 tests/workflows/archetype_lock_merge_test.sh create mode 100755 tests/workflows/check_ijson_jcs_test.sh create mode 100644 tests/workflows/check_lock_sync_test.sh create mode 100755 tests/workflows/check_no_a2ml_test.sh create mode 100644 tests/workflows/container_kyaml_test.sh create mode 100755 tests/workflows/deed_clause_test.sh create mode 100644 tests/workflows/dependabot_automerge_test.sh create mode 100644 tests/workflows/devcontainer_test.sh create mode 100644 tests/workflows/governance_badge_test.js create mode 100644 tests/workflows/governance_badge_test.sh create mode 100644 tests/workflows/governance_policy_test.sh create mode 100755 tests/workflows/hypatia_ignore_test.sh create mode 100755 tests/workflows/hypatia_rule_order_test.sh create mode 100644 tests/workflows/julia_library_test.sh create mode 100644 tests/workflows/kyaml_format_test.sh create mode 100644 tests/workflows/kyaml_ratchet_test.sh create mode 100644 tests/workflows/mint_gates_test.sh create mode 100755 tests/workflows/non_interactive_mint_test.sh create mode 100755 tests/workflows/resolve_template_pin_test.sh create mode 100644 tests/workflows/runtime_policy_fold_test.sh create mode 100755 tests/workflows/self_name_pass_test.sh create mode 100755 tests/workflows/squabble_gate_test.sh create mode 100755 tests/workflows/template_conformance_test.sh create mode 100755 tests/workflows/verdict_grid_test.sh create mode 100755 tests/workflows/workflow_edges_test.sh create mode 100755 tests/workflows/workflow_evidence_test.sh create mode 100644 www/errors/430.html diff --git a/.clinerules b/.clinerules index b3b9ab74..89d315b5 100644 --- a/.clinerules +++ b/.clinerules @@ -2,7 +2,7 @@ # Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> # Authoritative source: docs/practice/AI-CONVENTIONS.adoc -# STARTUP: Read the repo deed (*_chora.deed at the repo root) first, then .machine_readable/descriptiles/STATE.a2ml. +# STARTUP: Read the repo deed (*_chora.deed at the repo root) first, then docs/status/ROADMAP.adoc. # LICENSE # All original code: MPL-2.0. @@ -10,10 +10,11 @@ # 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. +# STATE FILES +# No .a2ml file may exist anywhere: the format is retired. State, metadata, +# (neurosym) and (playbook) are clauses of the repo deed (*_chora.deed); +# the journal is docs/status/ROADMAP.adoc. Never recreate them as files. +# The repo deed and .machine_readable/ are the single source of truth. # BANNED PATTERNS # Idris2: believe_me, assert_total, assert_smaller, unsafePerformIO @@ -23,15 +24,15 @@ # Lean: sorry # Rust: transmute (unless FFI with // SAFETY: comment) -# JS/TS RUNTIMES — ordered preference, reach for the first that can do the job -# (standards/3-practice/LANGUAGE-POLICY.adoc section 1, ruled 2026-07-29) -# 1. Bun default for all new work; runs .ts directly, no build step -# 2. Deno existing Deno projects are grandfathered; prefer over pnpm/npm -# 3. pnpm only where an upstream toolchain needs a node_modules layout -# 4. npm last resort; permitted, never preferred — a noted decision -# TypeScript IS PERMITTED under Bun. The old "use ReScript instead" rule is -# RETIRED: ReScript is no longer used in this estate, so that rule named a dead -# alternative. Do NOT migrate Bun to Deno — that inverts the current ruling. +# JS RUNTIME — Bun first (standards/3-practice/LANGUAGE-POLICY.adoc sections 1.3-1.4) +# 1. Bun tier 1: package.json + bun.lock, run with bun / bunx +# 2. Deno tier 2: permitted; runs the same package.json scripts (deno task) +# 3. pnpm tier 3 +# 4. npm last resort; permitted, never preferred; keeps no lock +# One package.json carries every runtime's lock (bun.lock, deno.lock, +# pnpm-lock.yaml); `js-runtimes regen` writes all three (owner ruling +# 2026-10-14). TypeScript and ReScript are banned; they migrate to +# AffineScript. Use plain JavaScript where JS is needed. # BANNED LANGUAGES # Go -> Rust diff --git a/.coderabbit.yaml b/.coderabbit.yaml new file mode 100644 index 00000000..6342c2ca --- /dev/null +++ b/.coderabbit.yaml @@ -0,0 +1,33 @@ +# SPDX-License-Identifier: MPL-2.0 +# CodeRabbit reviews changes; humans and authorised agents own changes. +# Canonical estate language policy: +# https://github.com/metadatastician/standards/blob/main/3-practice/LANGUAGE-POLICY.adoc +# This template must never permit unsolicited AI-generated fixes/commits. +reviews: + path_instructions: + - path: "**/*" + instructions: >- + Enforce the canonical estate language policy: Python is prohibited + for all NEW work, without exceptions. Do not suggest Python + implementations or tests, and flag newly added/modified Python + files or dependency manifests as policy violations. Use the owning + project's approved language and runtime. Pre-existing third-party + code is not permission to author new Python. Do not demand language + migrations of unrelated upstream dependencies as cosmetic PR work. + pre_merge_checks: + docstrings: + mode: warning + threshold: 80 + finishing_touches: + docstrings: + enabled: false + unit_tests: + enabled: false + simplify: + enabled: false + autofix: + enabled: false + fix_ci: + enabled: false + resolve_merge_conflict: + enabled: false diff --git a/.cursorrules b/.cursorrules deleted file mode 100644 index 2357fd38..00000000 --- a/.cursorrules +++ /dev/null @@ -1,54 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> -# Authoritative source: docs/practice/AI-CONVENTIONS.adoc - -# Read the repo deed (*_chora.deed in the repo root) FIRST: canonical file locations -# live in its (ply ...) canonical-locations clauses. - -# LICENSE -# All original code: MPL-2.0 (SPDX header required on every file). -# Copyright: {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> - -# STATE FILES -# .deed metadata files go in .machine_readable/ ONLY. -# Never create STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml, AGENTIC.a2ml, NEUROSYM.a2ml, or PLAYBOOK.a2ml. - -# 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) - -# JS RUNTIMES — ordered preference, reach for the first that can do the job -# (standards/3-practice/LANGUAGE-POLICY.adoc section 1, ruled 2026-07-29) -# 1. Bun default for all new work; runs .ts directly, no build step -# 2. Deno existing Deno projects are grandfathered; prefer over pnpm/npm -# 3. pnpm only where an upstream toolchain needs a node_modules layout -# 4. npm last resort; permitted, never preferred — a noted decision -# TypeScript IS PERMITTED under Bun. The old "use ReScript instead" rule is -# RETIRED: ReScript is no longer used in this estate, so that rule named a dead -# alternative. Do NOT migrate Bun to Deno — that inverts the current ruling. - -# BANNED LANGUAGES -# 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 headers to every source file. diff --git a/.devcontainer/Containerfile b/.devcontainer/Containerfile index 24f9f410..f69a8938 100644 --- a/.devcontainer/Containerfile +++ b/.devcontainer/Containerfile @@ -6,6 +6,10 @@ # Build: podman build -t {{PROJECT_NAME}}-dev -f .devcontainer/Containerfile . # `:latest` suits a dev container (rebuilt daily); pin by digest # (...@sha256:) if you need a reproducible dev environment. +# +# Every tool comes from Wolfi or from a sha256-checked release binary, so the +# image builds with no dev-container features (registry-hosted features can +# vanish or turn private, and then nobody can start the container). FROM cgr.dev/chainguard/wolfi-base:latest @@ -14,16 +18,30 @@ RUN apk update && apk add --no-cache \ bash \ curl \ git \ + just \ 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 +# Nickel (the .machine_readable contracts): the same verified release CI uses +# (.github/workflows/estate-rules.yml). Bump the version and both digests together. +ARG NICKEL_VERSION=1.17.0 +RUN set -eu; \ + case "$(uname -m)" in \ + x86_64) asset=nickel-x86_64-linux; sum=afcdfa6e0fff31760cf229e85997456c02c00b8b3b84ff38f897ac7b3f39ae34 ;; \ + aarch64) asset=nickel-arm64-linux; sum=9d7e027fde829b5788c92231c27fcfc926ee841d0716d655cee202c9f582e0c0 ;; \ + *) echo "no Nickel release binary for $(uname -m)" >&2; exit 1 ;; \ + esac; \ + curl --proto '=https' --proto-redir '=https' -fsSL \ + "https://github.com/nickel-lang/nickel/releases/download/${NICKEL_VERSION}/${asset}" \ + -o /usr/local/bin/nickel; \ + echo "${sum} /usr/local/bin/nickel" | sha256sum -c -; \ + chmod 0755 /usr/local/bin/nickel + +# Dev user: wolfi-base already ships `nonroot` (uid/gid 65532, home /home/nonroot); +# devcontainer.json maps your host user onto it with --userns=keep-id. # Set workspace directory WORKDIR /workspaces/{{PROJECT_NAME}} diff --git a/.devcontainer/README.adoc b/.devcontainer/README.adoc index 5eee18bc..6a0114ec 100644 --- a/.devcontainer/README.adoc +++ b/.devcontainer/README.adoc @@ -5,24 +5,57 @@ == 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. +The image (`Containerfile`) is `cgr.dev/chainguard/wolfi-base` with bash, curl, +git, just, openssh-client and a C toolchain from Wolfi packages, plus the Nickel +release binary (SHA-256 checked). It uses no dev container *features*: the +feature images are pulled from ghcr.io and can fail anonymously, which would stop +anyone from opening the container. -== VS Code (Local) +You work as `nonroot`, the user built into wolfi-base (uid/gid 65532). + +There are two configurations for the same image: + +[cols="1,2,3"] +|=== +| Config | Engine | Why + +| `devcontainer.json` +| rootless Podman (estate default) +| Maps your host user onto `nonroot` with `--userns=keep-id:uid=65532,gid=65532`, + so the bind-mounted workspace is writable. `--security-opt=label=disable` + lets the mount work on SELinux-enforcing hosts. + +| `docker/devcontainer.json` +| Docker, GitHub Codespaces, Gitpod +| Docker rejects `--userns=keep-id`, so this one has no `runArgs`. +|=== + +== VS Code (local, Podman) . 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. +. Open the repo folder, then choose **Reopen in Container** and pick + **{{PROJECT_NAME}} (Podman)**. + +== devcontainer CLI (Podman) + +[source,sh] +---- +bunx @devcontainers/cli up --workspace-folder . --docker-path podman +---- == GitHub Codespaces -. From the repository on GitHub, click **Code > Codespaces > New codespace**. -. The container builds automatically from this configuration. +. From the repository on GitHub, click **Code > Codespaces > ... > New with options**. +. Choose the **{{PROJECT_NAME}} (Docker / Codespaces)** configuration. == Gitpod . Prefix the repo URL with `https://gitpod.io/#` to launch a workspace. -. Gitpod reads `devcontainer.json` and builds the environment. +. Point Gitpod at `.devcontainer/docker/devcontainer.json`. == 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. +Replace the `{{PROJECT_NAME}}` placeholders in both `devcontainer.json` files and +the `Containerfile` with your actual project name. `just deps` runs automatically +after the container is created. Run it again to check the environment. diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index a4b33e0a..3193734e 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -1,35 +1,22 @@ // 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 +// Dev Container configuration for {{PROJECT_NAME}} — rootless Podman (default). +// Works with: VS Code Dev Containers with `dev.containers.dockerPath` = podman, +// and the devcontainer CLI (`devcontainer up --docker-path podman`). +// Docker, GitHub Codespaces and Gitpod: use .devcontainer/docker/devcontainer.json +// instead — Docker rejects the Podman-only `--userns=keep-id` below. { - "name": "{{PROJECT_NAME}}", - "build": { - "dockerfile": "Containerfile", - "context": ".." + "context": "..", + "dockerfile": "Containerfile" }, - - "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", + "HOME": "/home/nonroot", "LANG": "C.UTF-8" }, - + "containerUser": "nonroot", "customizations": { "vscode": { "extensions": [ @@ -45,25 +32,29 @@ "usernamehw.errorlens" ], "settings": { + "[makefile]": { + "editor.insertSpaces": false + }, "editor.formatOnSave": true, "editor.insertSpaces": true, "editor.tabSize": 2, - "files.trimTrailingWhitespace": true, "files.insertFinalNewline": true, "files.trimFinalNewlines": true, - "[makefile]": { - "editor.insertSpaces": false - } + "files.trimTrailingWhitespace": true } - }, - "codespaces": { - "openFiles": [ - "README.adoc" - ] } }, - - "forwardPorts": [], - - "shutdownAction": "stopContainer" + "name": "{{PROJECT_NAME}} (Podman)", + "postCreateCommand": "just deps", + "remoteUser": "nonroot", + // Rootless Podman maps your host user to root inside the container, so the + // bind-mounted workspace would be owned by root and unwritable for `nonroot`. + // keep-id maps your host user to uid/gid 65532 (`nonroot`, built into wolfi-base) instead. + // label=disable lets the workspace mount work on SELinux-enforcing hosts. + "runArgs": [ + "--userns=keep-id:uid=65532,gid=65532", + "--security-opt=label=disable" + ], + "shutdownAction": "stopContainer", + "updateRemoteUserUID": false } diff --git a/.devcontainer/docker/devcontainer.json b/.devcontainer/docker/devcontainer.json new file mode 100644 index 00000000..fadee842 --- /dev/null +++ b/.devcontainer/docker/devcontainer.json @@ -0,0 +1,61 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> +// +// Dev Container configuration for {{PROJECT_NAME}} — Docker engines. +// Works with: GitHub Codespaces, Gitpod, and VS Code Dev Containers on Docker. +// The estate default is rootless Podman: .devcontainer/devcontainer.json. +// Same image (../Containerfile); only the user-namespace settings differ. +{ + "name": "{{PROJECT_NAME}} (Docker / Codespaces)", + + "build": { + "dockerfile": "../Containerfile", + "context": "../.." + }, + + "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 index 7767fc47..808e2414 100644 --- a/.editorconfig +++ b/.editorconfig @@ -121,9 +121,6 @@ end_of_line = crlf # adopted for new work. These sections are inert where the files are absent and # keep surviving files from drifting. Removal is a per-repo judgement. -[*.a2ml] -indent_size = 2 - [*.go] indent_style = tab diff --git a/.envrc b/.envrc index 38d3f0c5..ec7a7ad0 100644 --- a/.envrc +++ b/.envrc @@ -2,14 +2,14 @@ # Activate development environment # Install direnv: https://direnv.net/ -# Load .tool-versions if asdf is available +# Load the mise toolchain (mise.toml + mise.lock) if has mise; then use mise fi -# Load Guix shell if build/guix.scm exists -if has guix && [ -f build/guix.scm ]; then - use guix +# Load the Guix development shell when Guix is present (same manifest as `just dev-shell`) +if has guix && [ -f build/manifest.scm ]; then + use guix -m build/manifest.scm fi # Project environment variables diff --git a/.gitattributes b/.gitattributes index c85fa951..60462f86 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,4 +1,5 @@ -# SPDX-License-Identifier: MPL-2.0 +# SPDX-License-Identifier: MPL-2.0 (code) +# SPDX-License-Identifier: CC-SA-BY-4.0 (prose) # Hyperpolymath estate canonical .gitattributes (standards#343 phase 1) # Canon lives in rsr-template-repo; do not add a per-repo name to this header. # diff --git a/.gitbot-fleet/enrolment.json b/.gitbot-fleet/enrolment.json new file mode 100644 index 00000000..28d108ee --- /dev/null +++ b/.gitbot-fleet/enrolment.json @@ -0,0 +1 @@ +{"reporters":{"accessibilitybot":{"enrolled":false,"reason":"template default: enrol once the repository serves HTML"},"cipherbot":{"enrolled":false,"reason":"template default: enrol once the repository implements cryptography"},"echidnabot":{"enrolled":false,"reason":"template default: enrol once the repository carries proofs and an ECHIDNA engine is configured"},"finishingbot":{"enrolled":true,"title":"finishingbot (release readiness)"},"glambot":{"enrolled":true,"title":"glambot (presentation quality)"},"panicbot":{"enrolled":false,"reason":"panic-attack is already graded by the verdict grid's own panic-attack row, from static-analysis-gate.yml evidence; enrolling panicbot would report one scanner twice and give two rows that can disagree"},"rhodibot":{"enrolled":true,"title":"rhodibot (RSR compliance)"},"seambot":{"enrolled":false,"reason":"template default: enrol once a seam register exists at spec/seams/seam-register.json"},"sustainabot":{"enrolled":false,"reason":"reserved fleet slot; no adapter exists (gitbot-fleet bots/sustainabot/README.adoc)"}},"schema":1} diff --git a/.gitbot-fleet/report-backs/README.md b/.gitbot-fleet/report-backs/README.md new file mode 100644 index 00000000..526ba64b --- /dev/null +++ b/.gitbot-fleet/report-backs/README.md @@ -0,0 +1,35 @@ +# gitbot-fleet report-backs + +One JSON envelope per enrolled fleet member, `.json`, in the shape +metadatastician/standards `docs/VERDICT-GRID-SPEC.adoc` defines ("The +report-back envelope"). The Hypatia verdict grid gives every member named in +`../enrolment.json` one row; the row stays **orange** ("enrolled, but no +report-back was received") until an envelope is present here when the grid +renders. + +**This directory is empty in git on purpose, and stays so.** Envelopes are +produced per run by the `fleet` job of `.github/workflows/fork-governance.yml` +(gitbot-fleet `scripts/fleet-report-back.sh`), uploaded as the +`fleet-report-backs` artifact, and read from that artifact at render time by the +`verdict` job of the same workflow, which passes this directory to the grid +renderer. A committed envelope would be stale evidence about an older commit, so +none is ever committed. Do not add a placeholder to turn a row green; only a +real run may. + +Two related rules: + +* an enrolled member with **no** envelope renders **orange** ("enrolled, but no + report-back was received") — never green, and never grey + (`docs/HYPATIA-RULE-ORDER.adoc`); +* a member that reports back without an enrolment entry still gets a row from + its envelope alone. Enrolment decides what a *missing* envelope means; it does + not decide what a present one is allowed to say + (metadatastician/standards `docs/VERDICT-GRID-SPEC.adoc`). + +When instantiating a repository from this template, edit `../enrolment.json`: +enrol what is true of the repository, with a reason for every member that does +not apply. The template defaults enrol rhodibot, finishingbot and glambot, +which apply to every estate repository. Adoption guide: standards +`3-practice/fork-governance/ADOPTION.adoc` §8. + +Only files matching `*.json` are read, so this README is inert. diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 9257eac0..6bdfc8a2 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -2,13 +2,14 @@ # CODEOWNERS - Define code review assignments # See: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners # -# Repository owner: hyperpolymath +# Replace {{OWNER}} with your GitHub username or team # Default owners for everything -* @hyperpolymath +* @{{OWNER}} # Security-sensitive files require explicit review -SECURITY.md @hyperpolymath -.github/workflows/ @hyperpolymath -Trustfile.a2ml @hyperpolymath -.machine_readable/ @hyperpolymath +SECURITY.md @{{OWNER}} +.github/workflows/ @{{OWNER}} +.machine_readable/contractiles/trust/ @{{OWNER}} +*_chora.deed @{{OWNER}} +.machine_readable/ @{{OWNER}} diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md deleted file mode 100644 index c7f72aee..00000000 --- a/.github/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,338 +0,0 @@ - -# Code of Conduct - - - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in rsr-template-repo 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 | - -**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 the {{CONDUCT_TEAM}} are themselves 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 - -This project uses the estate's **Tri-Perimeter Contribution Framework (TPCF)**, a -graduated trust model defined in `hyperpolymath/standards` -(`rhodium-standard-repositories/README.adoc`): - -- 🔒 **Perimeter 1 (Core)** — maintainers only; shell runtime, build systems -- 🧠 **Perimeter 2 (Expert)** — trusted contributors; protocol extensions, validators -- 🌱 **Perimeter 3 (Community)** — open to all; docs, tests, proposals - -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 the {{CONDUCT_TEAM}}, excluding anyone involved in 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://github.com/hyperpolymath/rsr-template-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 ba9e87af..00000000 --- a/.github/CONTRIBUTING.md +++ /dev/null @@ -1,120 +0,0 @@ - -``` -# Clone the repository -git clone https://github.com/hyperpolymath/rsr-template-repo.git -cd rsr-template-repo - -# Using Guix (recommended for reproducibility) -guix shell -D -f build/guix.scm - -# Or using toolbox/distrobox -toolbox create rsr-template-repo-dev -toolbox enter rsr-template-repo-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure - -The authoritative map is **generated** from the tree and checked in CI, so it -cannot drift: -[`docs/architecture/REPOSITORY-MAP.adoc`](../docs/architecture/REPOSITORY-MAP.adoc). -Regenerate it with `just repo-map`. - -A hand-written tree used to live here. It described `lib/`, `extensions/`, -`plugins/` and `spec/` directories that this repository has never contained, -which is precisely why the map is now generated rather than typed. - ---- - -## 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](../docs/status/ROADMAP.adoc) if available -2. Search existing issues and discussions -3. Consider which perimeter the feature belongs to - -**When suggesting**: - -Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: - -- Problem statement (what pain point does this solve?) -- Proposed solution -- Alternatives considered -- Which perimeter this affects - -### Your First Contribution - -Look for issues labelled: - -- [`good first issue`](https://github.com/hyperpolymath/rsr-template-repo/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/rsr-template-repo/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/rsr-template-repo/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/rsr-template-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] -``` - -### Signed commits - -Every commit that reaches the default branch must be signed; a ruleset refuses -unsigned pushes. Estate policy: -[SIGNING-POLICY](https://github.com/hyperpolymath/standards/blob/main/docs/SIGNING-POLICY.adoc). - -- **People and interactive agents** sign with an SSH key registered on GitHub - as a *signing* key (`gpg.format=ssh`, `user.signingkey=.pub`, - `commit.gpgsign=true`). The committer email must be verified on that account. -- **Apps, bots and workflows** never `git push` local commits. They write - through the API (`createCommitOnBranch` or the estate `signed-push` action) - so that GitHub signs each commit. -- Merge PRs with **squash**. The ruleset checks every commit on the PR branch, - not just the result, so one unsigned commit blocks the merge. Re-create such a - branch with signed commits (`git cherry-pick -S`) and open a new PR. - Rebase-merge replays commits unsigned and is disabled. diff --git a/.github/GOVERNANCE.md b/.github/GOVERNANCE.adoc similarity index 97% rename from .github/GOVERNANCE.md rename to .github/GOVERNANCE.adoc index 4f88882e..246a51a4 100644 --- a/.github/GOVERNANCE.md +++ b/.github/GOVERNANCE.adoc @@ -46,7 +46,7 @@ release schedules, contributor access, and community standards. - 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/descriptiles/META.a2ml` for the machine-readable ADR index. +- The ADR index is `docs/decisions/` itself; the `(meta)` clause of the repo deed (`*_chora.deed`) records the machine-readable architecture axes and practices. --- diff --git a/.github/actions/squabble/README.adoc b/.github/actions/squabble/README.adoc new file mode 100644 index 00000000..65e54255 --- /dev/null +++ b/.github/actions/squabble/README.adoc @@ -0,0 +1,123 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 +// Copyright (c) 2026 Jonathan D.A. Jewell += squabble action — install the pinned, attested squabble binary +:toc: preamble + +A composite action that installs one exact squabble release binary in a +workflow and, optionally, runs it. It refuses any file whose sha256 is not +the pinned digest, and any file whose build provenance does not trace back +to this repository's release workflow at the pinned tag and source commit. +Nothing is executed until both checks pass. + +== Usage + +Pin the action to a full commit SHA of this repository, never to a branch or +tag: + +[source,yaml] +---- +# Install only: squabble is on PATH from the next step on. +- uses: hyperpolymath/cicd-squabbler/.github/actions/squabble@<40-hex sha> + id: squabble +- run: squabble --version +---- + +Run mode passes `args` to squabble, one argument per line, taken literally +(no shell parsing, no globbing; blank lines are dropped). The step fails +when squabble exits non-zero, and `run.sh` records the exit code as the +`exit-code` output (see <<_not_yet_tested>> for what CI has not yet shown). + +[source,yaml] +---- +- uses: hyperpolymath/cicd-squabbler/.github/actions/squabble@<40-hex sha> + with: + args: | + verify-satisfied + ${{ github.repository }} + ${{ github.event.pull_request.number }} + token: ${{ steps.app-token.outputs.token }} +---- + +=== Inputs and outputs + +[cols="1,3"] +|=== +| `args` (input) | squabble's arguments, one per line. Empty (the default) means install only. +| `token` (input) | `GH_TOKEN` for squabble in run mode. Defaults to `github.token`. `verify-satisfied` reads branch rules, which need *Administration: read*; `github.token` cannot hold that, so pass a GitHub App installation token for it. +| `path` (output) | Absolute path of the installed binary. +| `exit-code` (output) | squabble's exit code in run mode; empty when `args` is empty. +|=== + +The download and the attestation check always use the workflow's own +`github.token`, never `token`: an App token minted for the caller's +repository need not reach this one. This repository is public, so +`github.token` is enough for both. + +== What is checked, in order + +`install.sh` does all of this before the binary is made executable: + +. The runner is Linux on x86_64. That is the only asset published. +. The release asset is downloaded into a fresh directory. +. Its sha256 must equal the pinned digest. +. `gh attestation verify --format json` must accept it with this repository, + the signer workflow `.github/workflows/release.yml`, the source ref + `refs/tags/`, the pinned source commit, the SLSA provenance v1 + predicate, and `--deny-self-hosted-runners`. The JSON is then read + back: it must be a non-empty array in which every result names the asset + with the pinned digest. The JSON form is used because the plain-text output + has been seen empty, with exit 0, when stdout is not a terminal. +. Only then is the file made executable, and it must report the pinned + version (`squabble 0.1.0`). + +== Pins + +[cols="1,3"] +|=== +| Release tag | `v0.1.0` (a locator, not a trust anchor) +| Asset | `squabble-x86_64-linux-musl` +| Asset sha256 | `6cbeb4577d83ccf2dea3405a3afb0d34b7fee422af73f2113d413ea7edba026c` +| Source commit | `b854d17abc0dce296719a349ebe856ff945cf03e` +| Signer workflow | `hyperpolymath/cicd-squabbler/.github/workflows/release.yml` +|=== + +== Bumping to a new release + +Read every value from the release itself, never from a tag name alone. + +. `gh release download --repo hyperpolymath/cicd-squabbler --pattern + squabble-x86_64-linux-musl --pattern SHA256SUMS`, then `sha256sum -c + SHA256SUMS --ignore-missing`. +. Find the commit the tag points to: `git rev-parse ^{commit}`. +. Run `gh attestation verify` on the asset with the flags `install.sh` uses + and that commit as `--source-digest`. It must pass. +. Set `SQUABBLE_TAG`, `SQUABBLE_SHA256` and `SQUABBLE_SOURCE_DIGEST` in + `install.sh`, and update any version reference in + `.github/workflows/squabble.yml`. +. Run `bash tests/workflows/squabble_gate_test.sh`. It must end with every + planned case run and none failed. + +== How it is tested + +`tests/workflows/squabble_gate_test.sh` exercises the action guards and the +companion required-context gate with Silence + Firing + Setup cases: the +`verify_digest` SHA256 mismatch check, the `check_attestation_json` SLSA +attestation checks (empty array, matching digest, mismatched digest), +`run.sh` exit-code propagation (`0` and blocking exit `4`) against a stand-in +binary, and `scripts/check-required-contexts.sh` against missing producers, +path-filtered workflows, unmapped ruleset contexts, and `gh pr merge --admin` +bypass invocations. + +`.github/workflows/squabble.yml` runs `install.sh` and `run.sh` on a real +runner against this repository's `.github/workflows` directory and verifies +`scripts/check-required-contexts.sh`. + +=== Not yet tested + +GitHub's own evaluation of `action.yml` (composite inputs, outputs and the +`if:` on the run step) is not exercised here. This repository has an +`actions.lock`, and the lockfile does not support local-path actions, so a +workflow here cannot call the action as `uses: ./.github/actions/squabble`. +It is first exercised by a caller that pins the action at a merged commit of +`main`, which the lockfile does support. That caller should check in +particular that `exit-code` is readable when the run step fails. diff --git a/.github/actions/squabble/action.yml b/.github/actions/squabble/action.yml new file mode 100644 index 00000000..a42a408b --- /dev/null +++ b/.github/actions/squabble/action.yml @@ -0,0 +1,68 @@ +# SPDX-License-Identifier: MPL-2.0 +# +# squabble: install the pinned, attested squabble release binary and, +# optionally, run it. Call it pinned to a commit of this repository: +# +# uses: hyperpolymath/cicd-squabbler/.github/actions/squabble@<40-hex sha> +# +# The binary itself is pinned inside install.sh by sha256 and by its +# build-provenance attestation. See README.adoc next to this file. +# +# This file is KYAML (standards YAML-POLICY, D280). Regenerate it with +# standards/scripts/kyaml-format.sh after an edit; keep each run: to one line +# that calls a script, so the KYAML stays readable. +{ + name: "squabble", + description: "Install the pinned squabble release (sha256 and build attestation checked), and optionally run it.", + author: "hyperpolymath", + inputs: { + args: { + description: "Arguments for squabble, one per line, taken literally. Empty means install only.", + required: false, + default: "", + }, + token: { + description: "GH_TOKEN for squabble itself in run mode. verify-satisfied needs Administration:read, which github.token cannot hold, so pass an App token for it. Installing always uses github.token.", + required: false, + default: "${{ github.token }}", + }, + }, + outputs: { + path: { + description: "Absolute path of the installed squabble binary.", + value: "${{ steps.install.outputs.path }}", + }, + exit-code: { + description: "squabble's exit code in run mode; empty when args is empty.", + value: "${{ steps.run.outputs.exit-code }}", + }, + }, + runs: { + using: "composite", + steps: [ + # Install with the workflow's own token, never the caller's run-mode token: + # an App installation token for the caller's repo need not reach this one. + { + name: "Install pinned squabble (sha256 + attestation)", + id: "install", + shell: "bash", + env: { + GH_TOKEN: "${{ github.token }}", + }, + run: "bash \"${GITHUB_ACTION_PATH}/install.sh\"", + }, + { + name: "Run squabble", + id: "run", + if: "inputs.args != ''", + shell: "bash", + env: { + GH_TOKEN: "${{ inputs.token }}", + SQUABBLE_ARGS: "${{ inputs.args }}", + SQUABBLE_BIN: "${{ steps.install.outputs.path }}", + }, + run: "bash \"${GITHUB_ACTION_PATH}/run.sh\"", + }, + ], + }, +} diff --git a/.github/actions/squabble/install.sh b/.github/actions/squabble/install.sh new file mode 100755 index 00000000..8c9de84e --- /dev/null +++ b/.github/actions/squabble/install.sh @@ -0,0 +1,146 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# +# install.sh — install the pinned squabble release binary, or refuse. +# +# The order is the whole point of this file: +# +# 1. download the release asset into a fresh directory; +# 2. refuse it unless its sha256 equals SQUABBLE_SHA256, before anything +# else reads or runs the file; +# 3. refuse it unless `gh attestation verify` proves it was built by this +# repository's release.yml, from the pinned tag AND the pinned source +# commit, on a GitHub-hosted runner, and the attested subject for the +# asset carries that same digest; +# 4. only then make it executable, smoke-test its version and put it on PATH. +# +# The tag is a locator, not a trust anchor: the digest is the anchor, and the +# attestation ties that digest to the source commit. The plain-text output of +# `gh attestation verify` has been seen EMPTY with exit 0 when stdout is not a +# terminal (2026-10-09), so the JSON form is read and checked here instead. +# +# Bumping squabble means changing SQUABBLE_TAG, SQUABBLE_SHA256 and +# SQUABBLE_SOURCE_DIGEST to a new release's values, each read from that +# release itself, never copied from a tag name; README.adoc next to this file +# gives the steps. +# +# Sourcing this file defines the functions without running main, so +# tests/squabble_action_test.sh can exercise each guard on its own. + +set -euo pipefail + +readonly SQUABBLE_REPO="hyperpolymath/cicd-squabbler" +readonly SQUABBLE_TAG="v0.1.0" +readonly SQUABBLE_ASSET="squabble-x86_64-linux-musl" +readonly SQUABBLE_SHA256="6cbeb4577d83ccf2dea3405a3afb0d34b7fee422af73f2113d413ea7edba026c" +readonly SQUABBLE_SOURCE_DIGEST="b854d17abc0dce296719a349ebe856ff945cf03e" +readonly SQUABBLE_SIGNER_WORKFLOW="hyperpolymath/cicd-squabbler/.github/workflows/release.yml" + +# die MESSAGE... — print MESSAGE as a GitHub Actions error annotation and exit 1. +die() { + printf '::error::%s\n' "$*" >&2 + exit 1 +} + +# require_platform — refuse any machine that cannot execute the x86_64 Linux asset. +require_platform() { + local os arch + os="$(uname -s)" + arch="$(uname -m)" + if [[ "$os" != "Linux" || "$arch" != "x86_64" ]]; then + die "squabble action supports only x86_64 Linux runners (this is ${os}/${arch})" + fi +} + +# verify_digest FILE — succeed only if FILE exists and its sha256 equals SQUABBLE_SHA256. +verify_digest() { + local file="$1" actual + if [[ ! -f "$file" ]]; then + printf '::error::%s does not exist\n' "$file" >&2 + return 1 + fi + actual="$(sha256sum -- "$file")" + actual="${actual%% *}" + if [[ "$actual" != "$SQUABBLE_SHA256" ]]; then + printf '::error::%s has sha256 %s, expected %s; refusing it\n' \ + "$file" "$actual" "$SQUABBLE_SHA256" >&2 + return 1 + fi +} + +# check_attestation_json FILE — succeed only if FILE holds a non-empty JSON array +# of verification results, each of which attests SQUABBLE_ASSET, and only with +# the digest SQUABBLE_SHA256. Other subjects in the same statement (the release +# also attests SHA256SUMS) are allowed; an empty array is a refusal, not a pass. +check_attestation_json() { + local json="$1" + jq -e --arg name "$SQUABBLE_ASSET" --arg sha "$SQUABBLE_SHA256" ' + type == "array" and length > 0 and all(.[]; + [.verificationResult.statement.subject[]? + | select(.name == $name) | .digest.sha256] as $d + | ($d | length) > 0 and all($d[]; . == $sha)) + ' "$json" >/dev/null +} + +# verify_attestation FILE — succeed only if GitHub's build-provenance attestation +# for FILE was signed by SQUABBLE_SIGNER_WORKFLOW at SQUABBLE_TAG, built from +# SQUABBLE_SOURCE_DIGEST on a GitHub-hosted runner, and names the pinned digest. +verify_attestation() { + local file="$1" json rc=0 + json="${file}.attestation.json" + gh attestation verify "$file" \ + --repo "$SQUABBLE_REPO" \ + --signer-workflow "$SQUABBLE_SIGNER_WORKFLOW" \ + --source-ref "refs/tags/${SQUABBLE_TAG}" \ + --source-digest "$SQUABBLE_SOURCE_DIGEST" \ + --predicate-type "https://slsa.dev/provenance/v1" \ + --deny-self-hosted-runners \ + --format json >"$json" || rc=$? + if (( rc != 0 )); then + printf '::error::gh attestation verify refused %s (exit %d)\n' "$file" "$rc" >&2 + return 1 + fi + if ! check_attestation_json "$json"; then + printf '::error::the attestation for %s does not name %s with sha256 %s\n' \ + "$file" "$SQUABBLE_ASSET" "$SQUABBLE_SHA256" >&2 + return 1 + fi +} + +# main — download, verify and install squabble; on success append its directory +# to GITHUB_PATH and write `path=` to GITHUB_OUTPUT when those are set. +main() { + local work asset bin version + require_platform + work="$(mktemp -d "${RUNNER_TEMP:-${TMPDIR:-/tmp}}/squabble.XXXXXX")" + mkdir -p "${work}/bin" + gh release download "$SQUABBLE_TAG" \ + --repo "$SQUABBLE_REPO" \ + --pattern "$SQUABBLE_ASSET" \ + --dir "${work}/download" + asset="${work}/download/${SQUABBLE_ASSET}" + + verify_digest "$asset" || die "squabble ${SQUABBLE_TAG}: download does not match the pinned sha256" + verify_attestation "$asset" || die "squabble ${SQUABBLE_TAG}: attestation check failed" + + bin="${work}/bin/squabble" + mv -- "$asset" "$bin" + chmod 0755 "$bin" + version="$("$bin" --version)" + if [[ "$version" != "squabble ${SQUABBLE_TAG#v}" ]]; then + die "installed binary reports '${version}', expected 'squabble ${SQUABBLE_TAG#v}'" + fi + + if [[ -n "${GITHUB_PATH:-}" ]]; then + printf '%s\n' "${work}/bin" >>"$GITHUB_PATH" + fi + if [[ -n "${GITHUB_OUTPUT:-}" ]]; then + printf 'path=%s\n' "$bin" >>"$GITHUB_OUTPUT" + fi + printf 'installed %s at %s (sha256:%s, attestation verified)\n' \ + "$version" "$bin" "$SQUABBLE_SHA256" >&2 +} + +if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then + main "$@" +fi diff --git a/.github/actions/squabble/run.sh b/.github/actions/squabble/run.sh new file mode 100755 index 00000000..339805f5 --- /dev/null +++ b/.github/actions/squabble/run.sh @@ -0,0 +1,39 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# +# run.sh — run the installed squabble with the arguments in SQUABBLE_ARGS, +# record its exit code as the step output `exit-code`, and exit with it. +# +# SQUABBLE_ARGS holds one argument per line, taken literally: no shell +# parsing, no globbing, no word splitting. Blank lines are dropped, so the +# trailing newline of a YAML block scalar adds no empty argument. +# +# The exit code is captured with `|| rc=$?`. The runner's shell is +# `bash -e`, under which `cmd; rc=$?` never reaches the assignment. + +set -euo pipefail + +# main — split SQUABBLE_ARGS on newlines, run SQUABBLE_BIN with them, write +# exit-code to GITHUB_OUTPUT when it is set, and exit with squabble's code. +main() { + local line rc=0 + local -a args=() + if [[ ! -x "${SQUABBLE_BIN:-}" ]]; then + printf '::error::SQUABBLE_BIN (%s) is not an executable file\n' "${SQUABBLE_BIN:-}" >&2 + exit 1 + fi + while IFS= read -r line; do + if [[ -n "$line" ]]; then + args+=("$line") + fi + done <<<"${SQUABBLE_ARGS:-}" + + "$SQUABBLE_BIN" "${args[@]}" || rc=$? + + if [[ -n "${GITHUB_OUTPUT:-}" ]]; then + printf 'exit-code=%d\n' "$rc" >>"$GITHUB_OUTPUT" + fi + exit "$rc" +} + +main "$@" diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 4d831b62..8c3234ca 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -11,7 +11,7 @@ Copyright (c) Jonathan D.A. Jewell - Read the repo deed (`*_chora.deed` in the repo root) for canonical file locations (its `(ply ...)` clauses carry the canonical-locations tables). -- State files (.a2ml) live in `.machine_readable/` ONLY, never the root. +- No `.a2ml` file may exist anywhere: state and metadata are clauses of the repo deed. ## License @@ -43,13 +43,17 @@ that can do the job: 1. **Bun** — default for all new work. Runs compiled ESM/JS directly, no bundler step. Uses an npm-compatible `package.json` plus `bun.lock`; both are expected, not anti-patterns. -2. **pnpm** — only where an upstream toolchain requires `node_modules`. -3. **npm** — last resort. Permitted, never preferred; a deliberate, noted choice. - -**Deno is being removed**, not grandfathered. Owner ruling 2026-08-26: *"deno is -to go and bun is the way we are going, put it first everywhere unless not -possible and explain why if not."* Existing Deno projects migrate to Bun; where -Bun genuinely cannot be used, document the reason in the repo. +2. **Deno** — permitted (tier 2). Deno 2 reads the same `package.json` and runs + its scripts with `deno task`. +3. **pnpm** — tier 3. +4. **npm** — last resort. Permitted, never preferred; it keeps no lock + (`package-lock.json` stays refused). + +**One manifest, every runtime** (owner ruling 2026-10-14, `LANGUAGE-POLICY.adoc` +§1.3–§1.4). `package.json` is the only manifest and carries every runtime's lock: +`bun.lock`, `deno.lock` and `pnpm-lock.yaml`. `js-runtimes regen` is the only +writer; run it after every `bun add`. Governance checks each runtime against its +lock. The ruling supersedes the 2026-08-26 one that removed Deno. **TypeScript is not the language for new application code — AffineScript is.** `LANGUAGE-POLICY.adoc` §1.2, ruled 2026-08-25, separates two questions the older @@ -64,7 +68,6 @@ migration destination is AffineScript. - No Go (use Rust) - No Python (use Julia or Rust) - No Nix (use Guix) -- No Deno for new work — being removed estate-wide; use Bun (owner ruling 2026-08-26) - No ReScript (`LANGUAGE-POLICY.adoc` §3) — migrate to AffineScript ## Containers @@ -81,6 +84,6 @@ migration destination is AffineScript. ## 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. +No `.a2ml` file may exist anywhere: the format is retired. State, metadata, +`(neurosym)` and `(playbook)` are clauses of the repo deed (`*_chora.deed`); +the journal is `docs/status/ROADMAP.adoc`. Never recreate them as separate files. diff --git a/.github/dependabot.yml b/.github/dependabot.yml index c58f7eb0..83278065 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -14,6 +14,20 @@ updates: patterns: - "*" open-pull-requests-limit: 2 + ignore: + # HOLD: github/codeql-action at v4.38.0 (SHA-pinned). v4.38.1 fails + # GitHub workflow-startup validation estate-wide (nexia-list#100; + # SHA-form re-bump bypassed versions-scoped ignores - see + # nexia-list#101/#104). Hold until upstream clears 4.38.1 or a + # newer release verifies green; revisit deliberately. + # + # The trailing * is load-bearing, as in standards/.github/dependabot.yml. + # Workflows reference the SUBPATH actions (github/codeql-action/init, + # /analyze) and Dependabot treats each subpath as its own dependency + # name, so a bare "github/codeql-action" matches NONE of them. That is + # how #210 bumped 4.38.0 -> 4.38.2 straight through this hold and left + # actions.lock out of sync (#217). + - dependency-name: "github/codeql-action*" # Rust/Cargo # @@ -27,14 +41,6 @@ updates: # "security only, not routine bumps". Pair with the # dependabot-automerge.yml workflow for low-touch security # maintenance. - ignore: - # HOLD: github/codeql-action at v4.38.0 (SHA-pinned). v4.38.1 fails - # GitHub workflow-startup validation estate-wide (nexia-list#100; - # SHA-form re-bump bypassed versions-scoped ignores - see - # nexia-list#101/#104). Hold until upstream clears 4.38.1 or a - # newer release verifies green; revisit deliberately. - - dependency-name: "github/codeql-action" - - package-ecosystem: "cargo" directory: "/" schedule: diff --git a/.github/hooks/pre-push b/.github/hooks/pre-push index 7e006867..7174c81a 100755 --- a/.github/hooks/pre-push +++ b/.github/hooks/pre-push @@ -6,9 +6,10 @@ # # Runs the SAME DEED + K9 validators the CI Dogfood Gate runs, but here on # your machine before the push leaves, so format drift is caught in seconds -# instead of surfacing as red CI minutes later. The vendored validators in -# this directory are byte-identical to the pinned CI action scripts and are -# refreshed by the estate `refresh-githooks` sweep. +# instead of surfacing as red CI minutes later. The two scripts here are thin +# wrappers over the canonical linter and validator in a hyperpolymath/standards +# checkout (STANDARDS_DIR, default ../standards); without one they skip with a +# notice and the CI lanes remain the gate. # # Enable once per clone: # git config core.hooksPath .github/hooks diff --git a/.github/hooks/scan-secrets.sh b/.github/hooks/scan-secrets.sh index b26dd40c..3ecb23f0 100755 --- a/.github/hooks/scan-secrets.sh +++ b/.github/hooks/scan-secrets.sh @@ -162,7 +162,7 @@ scan() { } if [ -n "${K9_PUSH_RANGES:-}" ]; then - while read -r local_ref local_sha remote_ref remote_sha; do + while read -r local_ref local_sha _remote_ref remote_sha; do [ -z "${local_sha:-}" ] && continue [ "$local_sha" = "$ZERO" ] && continue # branch deletion if [ "${remote_sha:-$ZERO}" = "$ZERO" ]; then diff --git a/.github/hooks/validate-deed.sh b/.github/hooks/validate-deed.sh index e644a73d..770ba695 100755 --- a/.github/hooks/validate-deed.sh +++ b/.github/hooks/validate-deed.sh @@ -2,392 +2,56 @@ # SPDX-License-Identifier: MPL-2.0 # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) # -# validate-deed.sh — DEED manifest validation script +# validate-deed.sh — pre-push deed check, through the canonical linter. # -# Scans for .a2ml and .deed files (dual-accept per owner ruling R-H2) and validates: -# 1. Required fields: agent-id or pedigree name, version -# 2. SPDX-License-Identifier header presence -# 3. Attestation block structure (if present) -# 4. Section heading syntax ([section] or ## section) +# One validator per family (hyperpolymath/standards, +# docs/CONTRACTILE-DESCRIPTILE-VALIDATION.adoc): the grep checks that used to +# live here were a second validator. This runs 1-formats/deed/tools/deed_lint.js +# (Bun) from a standards checkout over the tracked .deed files, as the +# deed-conformance lane does in CI (.github/workflows/dogfood-gate.yml). The +# lane is the gate; this is the early warning. A tracked .a2ml file is an +# error on sight: the format is retired estate-wide (D99, D312) and its facts +# belong in the repo deed. # # Environment variables: -# INPUT_PATH — Directory to scan (default: .) -# INPUT_STRICT — Promote warnings to errors (default: false) +# INPUT_PATH — Repository to check (default: .) +# STANDARDS_DIR — A hyperpolymath/standards checkout +# (default: ../standards beside the repository) # # Exit codes: -# 0 — All files valid (or only warnings in non-strict mode) -# 1 — Validation errors found +# 0 — Every tracked deed lints, or no linter is available (skipped with a +# notice: CI still runs the lane) +# 1 — A deed failed, or a .a2ml file is tracked set -euo pipefail -# --------------------------------------------------------------------------- -# Configuration -# --------------------------------------------------------------------------- +REPO="${INPUT_PATH:-.}" +STANDARDS_DIR="${STANDARDS_DIR:-$(cd "$REPO/.." && pwd)/standards}" +LINTER="$STANDARDS_DIR/1-formats/deed/tools/deed_lint.js" -SCAN_PATH="${INPUT_PATH:-.}" -STRICT="${INPUT_STRICT:-false}" -PATHS_IGNORE_RAW="${INPUT_PATHS_IGNORE:-}" -GITHUB_OUTPUT_FILE="${GITHUB_OUTPUT:-/dev/null}" +cd "$REPO" +errors=0 -# Parse paths-ignore: newline-separated fragments, blank lines and # comments -# stripped. Each fragment is a substring match against the file path. Pattern -# adopted from hyperpolymath/hypatia#243 — content-pattern validators must -# distinguish a target from a vendored / fixture file that legitimately -# contains the very pattern being checked. -PATHS_IGNORE=() -while IFS= read -r _frag; do - # Strip leading and trailing whitespace (canonical bash idiom). - _frag="${_frag#"${_frag%%[![:space:]]*}"}" - _frag="${_frag%"${_frag##*[![:space:]]}"}" - [[ -z "$_frag" || "$_frag" == \#* ]] && continue - PATHS_IGNORE+=("$_frag") -done <<< "$PATHS_IGNORE_RAW" - -# Returns 0 if path should be skipped (matches any ignore fragment) -path_ignored() { - local p="$1" frag - for frag in "${PATHS_IGNORE[@]}"; do - [[ "$p" == *"$frag"* ]] && return 0 - done - return 1 -} - -# Counters -FILES_SCANNED=0 -ERRORS=0 -WARNINGS=0 - -# --------------------------------------------------------------------------- -# Helper: emit GitHub annotation -# --------------------------------------------------------------------------- -# Usage: annotate -# level: error | warning | notice -annotate() { - local level="$1" file="$2" line="$3" message="$4" - echo "::${level} file=${file},line=${line}::${message}" -} - -# --------------------------------------------------------------------------- -# Helper: report issue (respects strict mode) -# --------------------------------------------------------------------------- -# Usage: report_issue -# severity: error | warning -report_issue() { - local severity="$1" file="$2" line="$3" message="$4" - - if [[ "$severity" == "warning" && "$STRICT" == "true" ]]; then - severity="error" - fi - - annotate "$severity" "$file" "$line" "$message" - - if [[ "$severity" == "error" ]]; then - ERRORS=$((ERRORS + 1)) - else - WARNINGS=$((WARNINGS + 1)) - fi -} - -# --------------------------------------------------------------------------- -# Validator: check a single .a2ml file -# --------------------------------------------------------------------------- -validate_deed() { - local file="$1" - FILES_SCANNED=$((FILES_SCANNED + 1)) - - # --- Check 1: SPDX header --- - # The SPDX-License-Identifier should appear in the first 10 lines - local has_spdx=false - local line_num=0 - while IFS= read -r line; do - line_num=$((line_num + 1)) - if [[ $line_num -gt 10 ]]; then - break - fi - if [[ "$line" == *"SPDX-License-Identifier"* ]]; then - has_spdx=true - break - fi - done < "$file" - - if [[ "$has_spdx" == "false" ]]; then - report_issue "warning" "$file" 1 \ - "Missing SPDX-License-Identifier in first 10 lines" - fi - - # --- Check 2: Required identity fields --- - # DEED files must contain either: - # - agent-id = "..." or agent_id = "..." - # - pedigree block with name field - # - name = "..." at top level (for AI manifests) - # - project = "..." (for STATE.a2ml) - local has_identity=false - local has_version=false - local first_form_seen=false - line_num=0 - - while IFS= read -r line; do - line_num=$((line_num + 1)) - - # Check for identity fields (various DEED patterns) - # TOML/kv form: `name = "..."`, `project = "..."`, `agent-id = "..."`. - # - # `archetype` is the identity key of the ARCHETYPE.a2ml shape — the - # `just repo-init` scaffolding descriptors under archetypes/. It names the - # archetype exactly as `name` names a manifest, and is the fourth - # dialect this recogniser accommodates alongside TOML, s-expression and - # brace-block. Without it, archetypes/julia-library/ARCHETYPE.a2ml - # failed with "Missing required identity field" — on main, in this repo - # and in every repo instantiated from it. - # - # Recognising the shape is the right fix rather than adding a redundant - # `name = "julia-library"` beside `archetype = "julia-library"`: that - # file's own header states an archetype "must not write fiction", and - # duplicating its identity to satisfy a grep is exactly that. - if [[ "$line" =~ ^[[:space:]]*(agent[-_]id|name|project|archetype)[[:space:]]*= ]]; then - has_identity=true - fi - # S-expression form: `(name "...")`, `(project "...")`, - # `(agent-id "...")`. Some DEED dialects (audit registries, - # classification stores) use Lisp-style s-expressions for the - # metadata block instead of TOML. Identity carries the same - # semantics; only the syntax differs. Match at any indent so it - # also picks up entries nested under `(metadata ...)`. - if [[ "$line" =~ ^[[:space:]]*\([[:space:]]*(agent[-_]id|name|project)[[:space:]]+\" ]]; then - has_identity=true - fi - # Colon / brace-block form: `name: "..."`, `id: "..."`, `project: "..."`. - # YAML-ish and brace-block DEED dialects (e.g. `Trust { name: "..." }`, - # `id: "tsdm-standard"`) carry the same identity semantics; only the - # delimiter (`:` vs `=`) differs. `id` is the brace-block spelling of an - # identity key. - if [[ "$line" =~ ^[[:space:]]*(agent[-_]id|name|project|id)[[:space:]]*: ]]; then - has_identity=true - fi - # DEED s-expression head form: `(estate-deed`, `(repo-deed`, - # `(estate-atlas-deed`, `(praxis-deed`. Per DEED-GRAMMAR-SPEC - # <>, a file whose first form is one of the four declared - # heads is a deed of that kind, and the head satisfies the structural - # half of identity. Only the FIRST form is eligible — checking every - # line would let a malformed file open with some other form and append - # a deed head lower down to buy identity. Ported from - # hyperpolymath/deed-ecosystem validate-action/validate-a2ml.sh so the - # local hook and the CI action agree on what a deed is. - if [[ "$first_form_seen" == "false" && "$line" =~ ^[[:space:]]*\( ]]; then - first_form_seen=true - if [[ "$line" =~ ^[[:space:]]*\((estate-deed|repo-deed|estate-atlas-deed|praxis-deed)([[:space:]]|$) ]]; then - has_identity=true - fi - fi - # DEED keyword identity form: `:canonical-name "..."` and the two other - # identity keywords the spec names. Leading colon: none of the forms - # above match it, because they test the bare words. - if [[ "$line" =~ ^[[:space:]]*:(canonical-name|estate-authority|agent-id)[[:space:]] ]]; then - has_identity=true - fi - # Check for version field — TOML form - if [[ "$line" =~ ^[[:space:]]*(version|schema_version)[[:space:]]*= ]]; then - has_version=true - fi - # Version field — s-expression form - if [[ "$line" =~ ^[[:space:]]*\([[:space:]]*(version|schema_version)[[:space:]]+\" ]]; then - has_version=true - fi - # Version field — colon / brace-block form - if [[ "$line" =~ ^[[:space:]]*(version|schema_version)[[:space:]]*: ]]; then - has_version=true - fi - # DEED keyword version form: `:schema-version "1.0.0"` — leading colon, - # hyphenated, REQUIRED on all four deed heads. The three patterns above - # spell it `schema_version` with no leading colon, so a conforming deed - # matched none of them. `:registry-version` is a distinct, optional - # atlas field and never satisfies the version requirement. - if [[ "$line" =~ ^[[:space:]]*:schema-version[[:space:]] ]]; then - has_version=true - fi - done < "$file" - - # AI manifest files (0-AI-MANIFEST.a2ml, 0.1-AI-MANIFEST.a2ml, etc.) - # use markdown-style headers and free text, so identity check is relaxed - local basename - basename="$(basename "$file")" - local is_manifest=false - if [[ "$basename" == *"AI-MANIFEST"* ]]; then - is_manifest=true - fi - # Canonical typed manifests under .machine_readable/descriptiles/ — identity comes - # from the enclosing directory + filename, not an in-file field. Sibling - # files in the same directory (ECOSYSTEM.a2ml, STATE.a2ml) DO carry their - # own $name/project and continue to be validated normally. - case "$basename" in - AGENTIC.a2ml|META.a2ml|NEUROSYM.a2ml|PLAYBOOK.a2ml|AI.a2ml) - # AI.a2ml = free-text "AI Assistant Instructions" manifest, the same - # doc type as 0-AI-MANIFEST.a2ml but with the bare name; identity is - # carried by the enclosing repo/plugin dir, not an in-file field. - is_manifest=true - ;; - # Dockerfile-style top-level typed manifests (Intentfile, Trustfile, …) - # use markdown-flavoured DEED; identity is carried by the parent repo. - *file.a2ml) - is_manifest=true - ;; - esac - - # Contractile-shape DEED files use `@directive:` syntax instead of - # TOML `key = value`. Trustfile.a2ml, Intentfile.a2ml, Mustfile.a2ml, - # Adjustfile.a2ml etc. are policy / trust / intent / abstract files - # whose identity is implicit in their @-prefixed directives - # (`@trust-level`, `@intent`, ...) rather than a TOML name/version - # pair. Treating them as manifest-shape produces 100% false positives — - # they're a different DEED doc type. Detected by the presence of any - # contractile directive in the file body. - local is_contractile_shape=false - if grep -qE '^@(abstract|trust-level|trust-boundary|trust-actions|trust-deny|intent|must|adjust|end)([[:space:]]*:|$)' "$file"; then - is_contractile_shape=true - fi - - # Canonical structured DEED tree. Everything under a `.machine_readable/` - # directory is a typed agent-readable doc (CLADE, ANCHOR, STATE, - # ECOSYSTEM, bot_directives/{debt,coverage,methodology}, ai/AI, - # policies/*, integrations/*, …). Per the RSR convention these carry - # identity structurally — owning repo + path + filename — not via an - # in-file `name`/`agent-id`. This generalises the `.machine_readable/descriptiles/` - # rationale above to the whole tree: rsr-template-repo itself ships these - # files without an in-file identity key, so requiring one produces - # estate-wide false positives on every repo built from the canonical - # template. Files outside `.machine_readable/` are still validated. - local is_structural_identity=false - if [[ "$file" == *"/.machine_readable/"* || "$file" == "./.machine_readable/"* || "$file" == ".machine_readable/"* ]]; then - is_structural_identity=true - fi - - if [[ "$has_identity" == "false" && "$is_manifest" == "false" && "$is_contractile_shape" == "false" && "$is_structural_identity" == "false" ]]; then - report_issue "error" "$file" 1 \ - "Missing required identity field (agent-id, name, or project)" - fi - - if [[ "$has_version" == "false" && "$is_manifest" == "false" && "$is_contractile_shape" == "false" && "$is_structural_identity" == "false" ]]; then - report_issue "warning" "$file" 1 \ - "Missing version or schema_version field" - fi - - # --- Check 3: Attestation block structure --- - # If file contains [attestation] or ## ATTESTATION, validate it has - # required sub-fields: proof or signature - local in_attestation=false - local attestation_line=0 - local attestation_has_content=false - line_num=0 - - while IFS= read -r line; do - line_num=$((line_num + 1)) - - # Detect attestation section start - if [[ "$line" =~ ^\[attestation\] ]] || [[ "$line" =~ ^##[[:space:]]+[Aa]ttestation ]] || [[ "$line" =~ ^##[[:space:]]+ATTESTATION ]]; then - in_attestation=true - attestation_line=$line_num - continue - fi - - # Detect next section (ends attestation block) - if [[ "$in_attestation" == "true" ]]; then - if [[ "$line" =~ ^\[.+\] ]] || [[ "$line" =~ ^##[[:space:]] ]]; then - in_attestation=false - continue - fi - # Check for content in attestation block - if [[ "$line" =~ (proof|signature|verified|hash)[[:space:]]*= ]]; then - attestation_has_content=true - fi - fi - done < "$file" - - if [[ $attestation_line -gt 0 && "$attestation_has_content" == "false" ]]; then - report_issue "warning" "$file" "$attestation_line" \ - "Attestation block found but missing proof/signature/hash fields" - fi - - # --- Check 4: Section heading syntax --- - # Validate that [section] headings are well-formed (no unclosed brackets) - line_num=0 - while IFS= read -r line; do - line_num=$((line_num + 1)) - # Lines starting with [ should have a matching ] - if [[ "$line" =~ ^\[ && ! "$line" =~ ^\[.+\] ]]; then - # Exclude markdown-style links and multi-line values - if [[ ! "$line" =~ ^\[.*\]\( && ! "$line" =~ ^\[TODO && ! "$line" =~ ^\[YOUR ]]; then - report_issue "warning" "$file" "$line_num" \ - "Possibly malformed section heading: unclosed bracket" - fi - fi - done < "$file" -} - -# --------------------------------------------------------------------------- -# Main: discover and validate .a2ml files -# --------------------------------------------------------------------------- - -echo "::group::DEED Manifest Validation" -echo "Scanning ${SCAN_PATH} for .a2ml files..." -echo "" - -# Find all manifest files (.a2ml legacy + .deed — dual-accept; extension migration = standards #837, the DEED conversion campaign), excluding .git -mapfile -t deed_candidates < <(find "$SCAN_PATH" \( -name '*.a2ml' -o -name '*.deed' \) -not -path '*/.git/*' -type f | sort) - -# Apply paths-ignore filter -deed_files=() -SKIPPED=0 -for _f in "${deed_candidates[@]}"; do - if path_ignored "$_f"; then - SKIPPED=$((SKIPPED + 1)) - continue - fi - deed_files+=("$_f") +mapfile -t a2ml < <(git ls-files -- '*.a2ml') +for f in "${a2ml[@]}"; do + echo "::error file=$f::.a2ml is retired; move its facts into the repo deed and delete it" + errors=$((errors + 1)) done -if [[ $SKIPPED -gt 0 ]]; then - echo "::notice::Skipped ${SKIPPED} file(s) matching paths-ignore" -fi - -if [[ ${#deed_files[@]} -eq 0 ]]; then - echo "::notice::No .a2ml files found in ${SCAN_PATH}" - echo "files_scanned=0" >> "$GITHUB_OUTPUT_FILE" 2>/dev/null || true - echo "errors=0" >> "$GITHUB_OUTPUT_FILE" 2>/dev/null || true - echo "warnings=0" >> "$GITHUB_OUTPUT_FILE" 2>/dev/null || true - echo "::endgroup::" +if [ ! -f "$LINTER" ] || ! command -v bun >/dev/null 2>&1; then + echo "::notice::DEED: no deed linter here (needs Bun and a standards checkout at $STANDARDS_DIR; set STANDARDS_DIR); the deed-conformance lane lints in CI" + [ "$errors" -eq 0 ] || exit 1 exit 0 fi -echo "Found ${#deed_files[@]} .a2ml file(s)" -echo "" - -for file in "${deed_files[@]}"; do - echo " Validating: ${file}" - validate_deed "$file" +mapfile -t deeds < <(git ls-files -- '*.deed' | sort) +for f in "${deeds[@]}"; do + echo " Linting: $f" + if ! bun "$LINTER" "$f"; then + errors=$((errors + 1)) + fi done -echo "" -echo "────────────────────────────────────────" -echo "Files scanned: ${FILES_SCANNED}" -echo "Errors: ${ERRORS}" -echo "Warnings: ${WARNINGS}" -echo "Strict mode: ${STRICT}" -echo "────────────────────────────────────────" - -# Write outputs for GitHub Actions -{ - echo "files_scanned=${FILES_SCANNED}" - echo "errors=${ERRORS}" - echo "warnings=${WARNINGS}" -} >> "$GITHUB_OUTPUT_FILE" 2>/dev/null || true - -echo "::endgroup::" - -# Exit with failure if errors were found -if [[ $ERRORS -gt 0 ]]; then - echo "::error::DEED validation failed with ${ERRORS} error(s)" - exit 1 -fi - +echo "DEED: ${#deeds[@]} file(s), ${errors} failing (linter: $LINTER)" +[ "$errors" -eq 0 ] || { echo "::error::DEED validation failed for ${errors} file(s)"; exit 1; } echo "DEED validation passed." -exit 0 diff --git a/.github/hooks/validate-k9.sh b/.github/hooks/validate-k9.sh index 02845a4c..4fff2533 100755 --- a/.github/hooks/validate-k9.sh +++ b/.github/hooks/validate-k9.sh @@ -2,388 +2,61 @@ # SPDX-License-Identifier: MPL-2.0 # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) # -# validate-k9.sh — K9 configuration file validation script +# validate-k9.sh — pre-push K9 check, through the canonical validator. # -# Scans for .k9 and .k9.ncl files and validates: -# 1. K9! magic number on line 1 -# 2. Pedigree block presence with required fields (name, version) -# 3. Security level is one of: kennel, yard, hunt (case-insensitive) -# 4. Hunt-level files must have a signature or signature_required field -# 5. SPDX-License-Identifier header presence +# One validator per family (hyperpolymath/standards, +# docs/CONTRACTILE-DESCRIPTILE-VALIDATION.adoc): the grep checks that used to +# live here were a second validator, and they accepted files that contract +# v1.0.0 (D173) rejects. This runs 1-formats/k9/tools/k9-validate.sh from a +# standards checkout over the tracked K9 files, strict, layers L0–L2 (L0–L1 +# when nickel is not installed), as the k9-conformance lane does in CI (.github/workflows/dogfood-gate.yml). The lane +# is the gate; this is the early warning. # # Environment variables: -# INPUT_PATH — Directory to scan (default: .) -# INPUT_STRICT — Promote warnings to errors (default: false) +# INPUT_PATH — Repository to check (default: .) +# STANDARDS_DIR — A hyperpolymath/standards checkout +# (default: ../standards beside the repository) # # Exit codes: -# 0 — All files valid (or only warnings in non-strict mode) -# 1 — Validation errors found +# 0 — Every tracked K9 file passes, or no validator is available (skipped +# with a notice: CI still runs the lane) +# 1 — A file failed set -euo pipefail -# --------------------------------------------------------------------------- -# Configuration -# --------------------------------------------------------------------------- +REPO="${INPUT_PATH:-.}" +STANDARDS_DIR="${STANDARDS_DIR:-$(cd "$REPO/.." && pwd)/standards}" +VALIDATOR="$STANDARDS_DIR/1-formats/k9/tools/k9-validate.sh" -SCAN_PATH="${INPUT_PATH:-.}" -STRICT="${INPUT_STRICT:-false}" -PATHS_IGNORE_RAW="${INPUT_PATHS_IGNORE:-}" -GITHUB_OUTPUT_FILE="${GITHUB_OUTPUT:-/dev/null}" - -# Parse paths-ignore: newline-separated fragments, blank lines and # comments -# stripped. Each fragment is a substring match against the file path. Pattern -# adopted from hyperpolymath/hypatia#243 — content-pattern validators must -# distinguish a target from a vendored / fixture file that legitimately -# contains the very pattern being checked. -PATHS_IGNORE=() -while IFS= read -r _frag; do - # Strip leading and trailing whitespace (canonical bash idiom). - _frag="${_frag#"${_frag%%[![:space:]]*}"}" - _frag="${_frag%"${_frag##*[![:space:]]}"}" - [[ -z "$_frag" || "$_frag" == \#* ]] && continue - PATHS_IGNORE+=("$_frag") -done <<< "$PATHS_IGNORE_RAW" - -# Returns 0 if path should be skipped (matches any ignore fragment) -path_ignored() { - local p="$1" frag - for frag in "${PATHS_IGNORE[@]}"; do - [[ "$p" == *"$frag"* ]] && return 0 - done - return 1 -} - -# Counters -FILES_SCANNED=0 -ERRORS=0 -WARNINGS=0 - -# Valid security levels (the leash metaphor) -VALID_LEVELS="kennel yard hunt" - -# --------------------------------------------------------------------------- -# Helper: emit GitHub annotation -# --------------------------------------------------------------------------- -annotate() { - local level="$1" file="$2" line="$3" message="$4" - echo "::${level} file=${file},line=${line}::${message}" -} - -# --------------------------------------------------------------------------- -# Helper: report issue (respects strict mode) -# --------------------------------------------------------------------------- -report_issue() { - local severity="$1" file="$2" line="$3" message="$4" - - if [[ "$severity" == "warning" && "$STRICT" == "true" ]]; then - severity="error" - fi - - annotate "$severity" "$file" "$line" "$message" - - if [[ "$severity" == "error" ]]; then - ERRORS=$((ERRORS + 1)) - else - WARNINGS=$((WARNINGS + 1)) - fi -} - -# --------------------------------------------------------------------------- -# Helper: normalise a security level string -# --------------------------------------------------------------------------- -# Strips quotes, leading/trailing whitespace, Nickel enum tick prefix -normalise_level() { - local raw="$1" - # Remove surrounding quotes, tick prefix ('Kennel -> Kennel), whitespace - raw="${raw#*=}" # Remove everything before = - raw="${raw//\"/}" # Remove double quotes - raw="${raw//\'/}" # Remove single quotes (Nickel tick) - raw="${raw//,/}" # Remove trailing commas - raw="${raw## }" # Trim leading space - raw="${raw%% }" # Trim trailing space - raw="${raw%%#*}" # Remove inline comments - raw="${raw## }" # Trim again - raw="${raw%% }" - echo "${raw,,}" # Lowercase -} - -# --------------------------------------------------------------------------- -# Validator: check a single K9 file -# --------------------------------------------------------------------------- -validate_k9() { - local file="$1" - FILES_SCANNED=$((FILES_SCANNED + 1)) - - # --- Check 1: K9! magic number on first non-empty line --- - local first_content_line="" - local first_content_line_num=0 - local line_num=0 - - while IFS= read -r line; do - line_num=$((line_num + 1)) - # Skip empty lines - if [[ -z "${line// /}" ]]; then - continue - fi - first_content_line="$line" - first_content_line_num=$line_num - break - done < "$file" - - if [[ "$first_content_line" != "K9!" ]]; then - report_issue "error" "$file" "$first_content_line_num" \ - "Missing K9! magic number. First non-empty line must be exactly 'K9!'" - fi - - # --- Check 2: SPDX header --- - local has_spdx=false - line_num=0 - while IFS= read -r line; do - line_num=$((line_num + 1)) - if [[ $line_num -gt 10 ]]; then - break - fi - if [[ "$line" == *"SPDX-License-Identifier"* ]]; then - has_spdx=true - break - fi - done < "$file" - - if [[ "$has_spdx" == "false" ]]; then - report_issue "warning" "$file" 1 \ - "Missing SPDX-License-Identifier in first 10 lines" - fi - - # --- Check 3: Pedigree block with required fields --- - local has_pedigree=false - local has_pedigree_name=false - local has_pedigree_version=false - local has_security_level=false - local security_level_value="" - local security_level_line=0 - local has_signature_field=false - local in_pedigree=false - local pedigree_depth=0 - - # Resolve a one-hop `let` indirection before scanning. - # - # Nickel lets you build the pedigree separately and attach it by name: - # - # let component_pedigree = { - # metadata = { name = "verisimdb-test-infra", ... }, - # } in - # { pedigree = component_pedigree, ... } - # - # The brace-depth scanner below only sees `pedigree = component_pedigree,` - # — a line with no braces — so depth never rises, the block appears empty, - # and `name` is invisible. The file is valid; the grep could not follow the - # reference. Observed on verisimdb/connectors/test-infra/deploy.k9.ncl, - # which does declare metadata.name at its line 23. - # - # If `pedigree = ` names a binding, treat `let = {` - # as the block opener too. One hop only: chased aliases would need a real - # Nickel evaluator, and `nickel typecheck` cannot be used here because the - # mandatory `K9!` magic line on line 1 is not valid Nickel. - local pedigree_alias="" - pedigree_alias=$(sed -nE 's/^[[:space:]]*pedigree[[:space:]]*=[[:space:]]*([A-Za-z_][A-Za-z0-9_]*)[[:space:]]*,?[[:space:]]*$/\1/p' "$file" | head -1) - - line_num=0 - while IFS= read -r line; do - line_num=$((line_num + 1)) - - # Detect pedigree block start. Note: do NOT `continue` here — the - # `pedigree = {` line itself contains the opening brace that - # establishes the block. Falling through to the brace counter - # below makes depth start at 1, so a subsequent `security = {…},` - # closing brace correctly takes depth to 1 (not 0), keeping us - # inside the pedigree block when later fields (name/version/leash) - # are checked. Previously the `continue` skipped this opening - # brace, depth started at 0, and the first nested block's close - # prematurely terminated the validator's view of the pedigree — - # making `pedigree.metadata.name` invisible. - if [[ "$line" =~ ^[[:space:]]*pedigree[[:space:]]*= ]]; then - has_pedigree=true - in_pedigree=true - pedigree_depth=0 - # fall through - fi - - # `let = {` where is what `pedigree =` points at. - # See the pedigree_alias note above. - if [[ -n "$pedigree_alias" ]] && \ - [[ "$line" =~ ^[[:space:]]*let[[:space:]]+${pedigree_alias}[[:space:]]*= ]]; then - has_pedigree=true - in_pedigree=true - pedigree_depth=0 - # fall through — this line carries the opening brace - fi - - if [[ "$in_pedigree" == "true" ]]; then - # Track brace depth to know when pedigree block ends - local opens closes - opens="${line//[^\{]/}" - closes="${line//[^\}]/}" - pedigree_depth=$(( pedigree_depth + ${#opens} - ${#closes} )) - - if [[ $pedigree_depth -le 0 && "$has_pedigree" == "true" ]]; then - # Check this final line too before leaving - : - fi - - # Check for name field within pedigree.metadata or pedigree directly. - # Two patterns cover both multi-line and single-line pedigrees: - # 1. ^[[:space:]]+name[[:space:]]*= — the normal multi-line case where - # `name = "..."` appears on its own indented line. - # 2. [[:space:]]name[[:space:]]*= — inline within a single-line - # pedigree assignment such as: - # pedigree = component_pedigree & { name = "foo" } - # (root cause: developer-ecosystem@baab1534 — single-line form - # was missed entirely because the pedigree block opened and - # closed in one line, never reaching the ^[[:space:]]+ check on - # a subsequent iteration.) - if [[ "$line" =~ ^[[:space:]]+name[[:space:]]*= ]] || \ - [[ "$line" =~ [[:space:]]name[[:space:]]*= ]]; then - has_pedigree_name=true - fi - - # Check for version field - if [[ "$line" =~ ^[[:space:]]+(version|schema_version)[[:space:]]*= ]] || \ - [[ "$line" =~ [[:space:]](version|schema_version)[[:space:]]*= ]]; then - has_pedigree_version=true - fi - - # Check for security level (leash field) - if [[ "$line" =~ ^[[:space:]]+(leash|security_level)[[:space:]]*= ]]; then - has_security_level=true - security_level_value="$(normalise_level "$line")" - security_level_line=$line_num - fi - - # Check for signature fields - if [[ "$line" =~ ^[[:space:]]+(signature|signature_required)[[:space:]]*= ]]; then - has_signature_field=true - fi - - # End of pedigree block - if [[ $pedigree_depth -le 0 && "$has_pedigree" == "true" && "$line" == *"}"* ]]; then - in_pedigree=false - fi - fi - - # Also check for signature fields outside pedigree (top-level) - if [[ "$line" =~ ^[[:space:]]*(signature)[[:space:]]*= ]]; then - has_signature_field=true - fi - done < "$file" - - if [[ "$has_pedigree" == "false" ]]; then - report_issue "error" "$file" 1 \ - "Missing pedigree block. K9 files must contain a 'pedigree = { ... }' section" - else - if [[ "$has_pedigree_name" == "false" ]]; then - report_issue "error" "$file" 1 \ - "Pedigree block missing 'name' field (in pedigree.metadata.name or pedigree.name)" - fi - - if [[ "$has_pedigree_version" == "false" ]]; then - report_issue "warning" "$file" 1 \ - "Pedigree block missing 'version' or 'schema_version' field" - fi - fi - - # --- Check 4: Security level validation --- - if [[ "$has_security_level" == "true" ]]; then - local level_valid=false - for valid in $VALID_LEVELS; do - if [[ "$security_level_value" == "$valid" ]]; then - level_valid=true - break - fi - done - - if [[ "$level_valid" == "false" ]]; then - report_issue "error" "$file" "$security_level_line" \ - "Invalid security level '${security_level_value}'. Must be one of: kennel, yard, hunt" - fi - else - if [[ "$has_pedigree" == "true" ]]; then - report_issue "warning" "$file" 1 \ - "No security level (leash/security_level) found in pedigree block" - fi - fi - - # --- Check 5: Hunt-level signature requirement --- - if [[ "$security_level_value" == "hunt" && "$has_signature_field" == "false" ]]; then - report_issue "error" "$file" "$security_level_line" \ - "Hunt-level K9 file must include a 'signature' or 'signature_required' field" - fi -} - -# --------------------------------------------------------------------------- -# Main: discover and validate K9 files -# --------------------------------------------------------------------------- - -echo "::group::K9 Configuration Validation" -echo "Scanning ${SCAN_PATH} for K9 files (.k9, .k9.ncl)..." -echo "" - -# Find all K9 files, excluding .git directory -mapfile -t k9_candidates < <(find "$SCAN_PATH" \( -name '*.k9' -o -name '*.k9.ncl' \) -not -path '*/.git/*' -type f | sort) - -# Apply paths-ignore filter -k9_files=() -SKIPPED=0 -for _f in "${k9_candidates[@]}"; do - if path_ignored "$_f"; then - SKIPPED=$((SKIPPED + 1)) - continue - fi - k9_files+=("$_f") -done +if [ ! -f "$VALIDATOR" ]; then + echo "::notice::K9: no standards checkout at $STANDARDS_DIR (set STANDARDS_DIR to run the validator locally); the k9-conformance lane validates in CI" + exit 0 +fi -if [[ $SKIPPED -gt 0 ]]; then - echo "::notice::Skipped ${SKIPPED} file(s) matching paths-ignore" +# L2 is the Nickel evaluation against the contract; without nickel the +# validator reports those checks as SKIPPED and refuses to call that a pass, +# so stop at L1 here and say so. The lane checks L2 in CI either way. +LAYER=L2 +if ! command -v nickel >/dev/null 2>&1; then + echo "::notice::K9: nickel is not installed, so layer L2 (Nickel semantics) is left to the CI lane; checking L0–L1" + LAYER=L1 fi -if [[ ${#k9_files[@]} -eq 0 ]]; then - echo "::notice::No K9 files found in ${SCAN_PATH}" - echo "files_scanned=0" >> "$GITHUB_OUTPUT_FILE" 2>/dev/null || true - echo "errors=0" >> "$GITHUB_OUTPUT_FILE" 2>/dev/null || true - echo "warnings=0" >> "$GITHUB_OUTPUT_FILE" 2>/dev/null || true - echo "::endgroup::" +cd "$REPO" +mapfile -t files < <(git ls-files -- '*.k9.ncl' '*.k9' '*.k9.lock' | sort) +if [ "${#files[@]}" -eq 0 ]; then + echo "::notice::K9: no tracked K9 file" exit 0 fi -echo "Found ${#k9_files[@]} K9 file(s)" -echo "" - -for file in "${k9_files[@]}"; do - echo " Validating: ${file}" - validate_k9 "$file" +errors=0 +for f in "${files[@]}"; do + echo " Validating: $f" + if ! bash "$VALIDATOR" --strict --layer "$LAYER" "$f"; then + errors=$((errors + 1)) + fi done -echo "" -echo "────────────────────────────────────────" -echo "Files scanned: ${FILES_SCANNED}" -echo "Errors: ${ERRORS}" -echo "Warnings: ${WARNINGS}" -echo "Strict mode: ${STRICT}" -echo "────────────────────────────────────────" - -# Write outputs for GitHub Actions -{ - echo "files_scanned=${FILES_SCANNED}" - echo "errors=${ERRORS}" - echo "warnings=${WARNINGS}" -} >> "$GITHUB_OUTPUT_FILE" 2>/dev/null || true - -echo "::endgroup::" - -# Exit with failure if errors were found -if [[ $ERRORS -gt 0 ]]; then - echo "::error::K9 validation failed with ${ERRORS} error(s)" - exit 1 -fi - +echo "K9: ${#files[@]} file(s), ${errors} failing (validator: $VALIDATOR)" +[ "$errors" -eq 0 ] || { echo "::error::K9 validation failed for ${errors} file(s)"; exit 1; } echo "K9 validation passed." -exit 0 diff --git a/.github/label-classifier.json b/.github/label-classifier.json index d349eaad..92e25573 100644 --- a/.github/label-classifier.json +++ b/.github/label-classifier.json @@ -1,739 +1 @@ -{ - "_generated_from": ".github/label-classifier.yml + .github/labels.yml in hyperpolymath/.git-private-farm", - "_do_not_edit": "regenerate with scripts/gen-classifier-json.py", - "version": 1, - "prefix_split_on": "/", - "title_prefix": { - "docs": { - "type": "documentation" - }, - "ci": { - "type": "chore", - "areas": [ - "cicd" - ] - }, - "governance": { - "type": "chore", - "areas": [ - "governance" - ] - }, - "roadmap": { - "type": "enhancement", - "meta": "meta:roadmap" - }, - "chore": { - "type": "chore" - }, - "build": { - "type": "chore", - "areas": [ - "cicd" - ] - }, - "security": { - "type": "chore", - "areas": [ - "security" - ] - }, - "proof": { - "type": "chore", - "areas": [ - "proofs" - ] - }, - "proofs": { - "type": "chore", - "areas": [ - "proofs" - ] - }, - "proof-debt": { - "type": "tech-debt", - "areas": [ - "proofs" - ] - }, - "epic": { - "type": "enhancement", - "meta": "meta:umbrella" - }, - "umbrella": { - "type": "enhancement", - "meta": "meta:umbrella" - }, - "tracking": { - "type": "chore", - "meta": "meta:umbrella" - }, - "campaign": { - "type": "enhancement", - "meta": "meta:campaign" - }, - "hygiene": { - "type": "tech-debt" - }, - "audit": { - "type": "research" - }, - "estate": { - "type": "chore", - "scope": "scope:estate" - }, - "automation": { - "type": "enhancement", - "areas": [ - "automation" - ] - }, - "research": { - "type": "research" - }, - "refactor": { - "type": "refactor" - }, - "test": { - "type": "testing" - }, - "tests": { - "type": "testing" - }, - "feat": { - "type": "enhancement" - }, - "fix": { - "type": "bug" - }, - "bug": { - "type": "bug" - }, - "perf": { - "type": "enhancement", - "areas": [ - "performance" - ] - }, - "codegen": { - "type": "enhancement", - "areas": [ - "architecture" - ] - }, - "packaging": { - "type": "chore", - "areas": [ - "packaging" - ] - }, - "policy": { - "type": "chore", - "areas": [ - "governance" - ] - }, - "ops": { - "type": "chore", - "areas": [ - "automation" - ] - }, - "standard": { - "type": "chore", - "areas": [ - "governance" - ] - }, - "migration": { - "type": "refactor", - "areas": [ - "migration" - ] - }, - "drift": { - "type": "tech-debt" - }, - "corrective": { - "type": "bug" - }, - "adaptive": { - "type": "enhancement" - }, - "perfective": { - "type": "enhancement" - }, - "preventive": { - "type": "tech-debt" - }, - "machine-readable": { - "type": "tech-debt" - }, - "parser": { - "type": "bug" - }, - "lang": { - "type": "bug" - }, - "clippy": { - "type": "tech-debt" - }, - "release": { - "type": "chore" - }, - "upstream": { - "type": "chore" - }, - "hardening": { - "type": "chore", - "areas": [ - "security" - ] - }, - "deps": { - "type": "chore" - }, - "rustsec": { - "type": "chore", - "areas": [ - "security" - ] - }, - "track": { - "type": "chore", - "meta": "meta:umbrella" - }, - "tracker": { - "type": "chore", - "meta": "meta:umbrella" - }, - "wiki": { - "type": "documentation" - }, - "reclassify": { - "type": "refactor" - }, - "backlog": { - "type": "chore" - }, - "core": { - "type": "enhancement", - "areas": [ - "design" - ] - }, - "evidence": { - "type": "enhancement", - "areas": [ - "design" - ] - }, - "manifest": { - "type": "enhancement", - "areas": [ - "design" - ] - }, - "backends": { - "type": "enhancement", - "areas": [ - "design" - ] - } - }, - "bracket_tag": { - "campaign": { - "meta": "meta:campaign" - }, - "umbrella": { - "meta": "meta:umbrella" - }, - "gov": { - "areas": [ - "governance" - ] - }, - "proofs/a": { - "areas": [ - "proofs" - ] - }, - "proofs/b": { - "areas": [ - "proofs" - ] - }, - "proofs/c": { - "areas": [ - "proofs" - ] - }, - "estate": { - "scope": "scope:estate" - }, - "repo": { - "scope": "scope:repo" - }, - "feature": { - "type": "enhancement" - }, - "integration": { - "areas": [ - "conformance" - ] - }, - "reference": { - "type": "documentation" - }, - "register": { - "type": "documentation" - }, - "p0": { - "priority": "priority:p0" - }, - "p1": { - "priority": "priority:p1" - }, - "p2": { - "priority": "priority:p2" - }, - "et-l2": { - "areas": [ - "conformance" - ] - }, - "et-l4": { - "areas": [ - "conformance" - ] - } - }, - "keyword_area": { - "proofs": [ - "agda", - "coq", - "rocq", - "idris", - "lean", - "isabelle", - "hol", - "mizar", - "why3", - "tla", - "alloy", - "dafny", - "acl2", - "pvs", - "metamath", - "z3", - "smt", - "prover", - "provers", - "theorem", - "theorems", - "axiom", - "axioms", - "postulate", - "postulates", - "believe_me", - "sorry", - "proof obligation", - "proof obligations", - "proof hole", - "proof holes", - "proof suite", - "proof-pipeline", - "proof debt", - "proof-debt", - "metatheory", - "mechanize", - "qed" - ], - "cicd": [ - "workflow", - "github action", - "actions.lock", - "lockfile", - "runner", - "startup_failure", - "dependabot", - "check run", - "required context", - "scorecard", - "codeql", - "ci/cd" - ], - "licensing": [ - "spdx", - "licence", - "license", - "reuse", - "copyright", - "attribution", - "agpl", - "mpl" - ], - "security": [ - "gitleaks", - "secret", - "vulnerabilit", - "advisory", - "supply chain", - "cve" - ], - "bindings": [ - "abi", - "ffi", - "wasm", - "jni", - "c api", - "interop", - "extern \"c\"", - "nif", - "snif" - ], - "packaging": [ - "guix", - "nix", - "container", - "containerfile", - "docker", - "flatpak", - "oci image" - ], - "scaffolding": [ - "rsr", - "scaffold", - "template", - "repo-init", - "instantiat", - "placeholder" - ], - "governance": [ - "ruleset", - "policy", - "compliance", - "governance", - "branch protection", - "codeowners", - "code of conduct" - ], - "migration": [ - "rescript", - "to-affinescript", - "\u2192 affinescript", - "port", - "deno", - "bun" - ], - "automation": [ - "bot", - "gitbot", - "hypatia", - "sustainabot", - "oikosbot", - "fan-out", - "fanout", - "dispatch", - "self-heal" - ], - "performance": [ - "latency", - "throughput", - "binary size", - "memory", - "hot path", - "regression" - ] - }, - "keyword_type": { - "tech-debt": [ - "debt", - "drift", - "hygiene", - "stale", - "cleanup", - "follow-up", - "clean up", - "left over", - "leftover", - "anti-pattern", - "inconsistency", - "inconsistent", - "placeholder", - "placeholders", - "tbd", - "todo", - "todos", - "unfilled" - ], - "documentation": [ - "document", - "docs", - "readme", - "adoc", - "prose", - "docs/", - "changelog", - "explainme", - "quickstart", - "wiki", - "docstring", - "doc tree" - ], - "testing": [ - "test", - "tests", - "fuzz", - "bench", - "coverage", - "crash-consistency", - "linearizability", - "equivalence", - "property-correspondence", - "property-based", - "test suite", - "proptest" - ], - "bug": [ - "broken", - "fails", - "failing", - "crash", - "oom", - "regression", - "incorrect", - "does not", - "panic", - "panics", - "unreachable", - "mangled", - "never run", - "never ran", - "never succeeded", - "never fires", - "cannot fail", - "deadlock", - "hangs" - ], - "refactor": [ - "refactor", - "restructure", - "consolidate", - "consolidation", - "reconcile", - "reconciliation", - "unify", - "dedupe", - "re-point", - "repoint", - "extract", - "retire", - "retire duplicate", - "deduplicate", - "reclassify", - "migrate" - ], - "research": [ - "investigat", - "explore", - "spike", - "work out", - "triage", - "assess", - "survey", - "gap analysis", - "self-audit", - "inventory", - "weakness list", - "theory", - "synthesis", - "prioritised weakness", - "feasibility" - ], - "decision": [ - "ruling", - "decide", - "decision", - "adjudicat", - "which of" - ], - "enhancement": [ - "add", - "implement", - "support", - "introduce", - "enable", - "expand", - "expansion", - "extend", - "wire", - "complete", - "build", - "create", - "port" - ] - }, - "meta_signal": { - "meta:umbrella": [ - "umbrella", - "epic", - "master issue", - "parent issue", - "sub-issues", - "child issues" - ], - "meta:campaign": [ - "campaign" - ], - "meta:roadmap": [ - "roadmap", - "capability-expansion", - "future work" - ], - "meta:recurring": [ - "recurring", - "recurrence", - "standing", - "every run", - "each week" - ] - }, - "status_signal": { - "status:blocked": [ - "blocked on", - "blocked:", - "(blocked", - "is blocked", - "gated on", - "waiting on upstream", - "needs upstream" - ], - "status:needs-owner": [ - "unassigned", - "needs an owner", - "no owner" - ], - "status:needs-ruling": [ - "needs a ruling", - "awaiting ruling", - "owner decision needed" - ] - }, - "scope_signal": { - "scope:estate": [ - "estate-wide", - "estate wide", - "across the estate", - "all repos", - "fleet-wide" - ] - }, - "tier_of": { - "bug": "type", - "enhancement": "type", - "documentation": "type", - "refactor": "type", - "tech-debt": "type", - "testing": "type", - "chore": "type", - "research": "type", - "decision": "type", - "question": "type", - "cicd": "area", - "security": "area", - "proofs": "area", - "governance": "area", - "design": "area", - "architecture": "area", - "performance": "area", - "bindings": "area", - "migration": "area", - "packaging": "area", - "licensing": "area", - "automation": "area", - "scaffolding": "area", - "conformance": "area", - "priority:p0": "priority", - "priority:p1": "priority", - "priority:p2": "priority", - "priority:p3": "priority", - "status:blocked": "status", - "status:ready": "status", - "status:needs-owner": "status", - "status:needs-ruling": "status", - "status:do-not-automate": "status", - "meta:umbrella": "meta", - "meta:campaign": "meta", - "meta:roadmap": "meta", - "meta:recurring": "meta", - "scope:estate": "scope", - "scope:repo": "scope" - }, - "tier_max": { - "type": 1, - "area": null, - "priority": 1, - "status": 1, - "meta": 1, - "scope": 1 - }, - "types": [ - "bug", - "enhancement", - "documentation", - "refactor", - "tech-debt", - "testing", - "chore", - "research", - "decision", - "question" - ], - "frozen": [ - "dependencies", - "duplicate", - "elixir", - "gitar-approved", - "github_actions", - "good first issue", - "help wanted", - "invalid", - "javascript", - "never-stale", - "nix", - "pinned", - "python", - "rust", - "security", - "stale", - "wontfix" - ], - "precedence": { - "meta:campaign": 0, - "meta:umbrella": 1, - "meta:recurring": 2, - "meta:roadmap": 3, - "priority:p0": 0, - "priority:p1": 1, - "priority:p2": 2, - "priority:p3": 3, - "status:blocked": 0, - "status:needs-ruling": 1, - "status:needs-owner": 2, - "status:do-not-automate": 3, - "status:ready": 4, - "scope:estate": 0, - "scope:repo": 1, - "bug": 0, - "decision": 1, - "tech-debt": 2, - "testing": 3, - "documentation": 4, - "refactor": 5, - "research": 6, - "enhancement": 7, - "chore": 8, - "question": 9 - } -} +{"_do_not_edit":"regenerate with scripts/gen-classifier-json.py","_generated_from":".github/label-classifier.yml + .github/labels.yml in hyperpolymath/.git-private-farm","bracket_tag":{"campaign":{"meta":"meta:campaign"},"estate":{"scope":"scope:estate"},"et-l2":{"areas":["conformance"]},"et-l4":{"areas":["conformance"]},"feature":{"type":"enhancement"},"gov":{"areas":["governance"]},"integration":{"areas":["conformance"]},"p0":{"priority":"priority:p0"},"p1":{"priority":"priority:p1"},"p2":{"priority":"priority:p2"},"proofs/a":{"areas":["proofs"]},"proofs/b":{"areas":["proofs"]},"proofs/c":{"areas":["proofs"]},"reference":{"type":"documentation"},"register":{"type":"documentation"},"repo":{"scope":"scope:repo"},"umbrella":{"meta":"meta:umbrella"}},"frozen":["dependencies","duplicate","elixir","gitar-approved","github_actions","good first issue","help wanted","invalid","javascript","never-stale","nix","pinned","python","rust","security","stale","wontfix"],"keyword_area":{"automation":["bot","gitbot","hypatia","sustainabot","oikosbot","fan-out","fanout","dispatch","self-heal"],"bindings":["abi","ffi","wasm","jni","c api","interop","extern \"c\"","nif","snif"],"cicd":["workflow","github action","actions.lock","lockfile","runner","startup_failure","dependabot","check run","required context","scorecard","codeql","ci/cd"],"governance":["ruleset","policy","compliance","governance","branch protection","codeowners","code of conduct"],"licensing":["spdx","licence","license","reuse","copyright","attribution","agpl","mpl"],"migration":["rescript","to-affinescript","→ affinescript","port","deno","bun"],"packaging":["guix","nix","container","containerfile","docker","flatpak","oci image"],"performance":["latency","throughput","binary size","memory","hot path","regression"],"proofs":["agda","coq","rocq","idris","lean","isabelle","hol","mizar","why3","tla","alloy","dafny","acl2","pvs","metamath","z3","smt","prover","provers","theorem","theorems","axiom","axioms","postulate","postulates","believe_me","sorry","proof obligation","proof obligations","proof hole","proof holes","proof suite","proof-pipeline","proof debt","proof-debt","metatheory","mechanize","qed"],"scaffolding":["rsr","scaffold","template","repo-init","instantiat","placeholder"],"security":["gitleaks","secret","vulnerabilit","advisory","supply chain","cve"]},"keyword_type":{"bug":["broken","fails","failing","crash","oom","regression","incorrect","does not","panic","panics","unreachable","mangled","never run","never ran","never succeeded","never fires","cannot fail","deadlock","hangs"],"decision":["ruling","decide","decision","adjudicat","which of"],"documentation":["document","docs","readme","adoc","prose","docs/","changelog","explainme","quickstart","wiki","docstring","doc tree"],"enhancement":["add","implement","support","introduce","enable","expand","expansion","extend","wire","complete","build","create","port"],"refactor":["refactor","restructure","consolidate","consolidation","reconcile","reconciliation","unify","dedupe","re-point","repoint","extract","retire","retire duplicate","deduplicate","reclassify","migrate"],"research":["investigat","explore","spike","work out","triage","assess","survey","gap analysis","self-audit","inventory","weakness list","theory","synthesis","prioritised weakness","feasibility"],"tech-debt":["debt","drift","hygiene","stale","cleanup","follow-up","clean up","left over","leftover","anti-pattern","inconsistency","inconsistent","placeholder","placeholders","tbd","todo","todos","unfilled"],"testing":["test","tests","fuzz","bench","coverage","crash-consistency","linearizability","equivalence","property-correspondence","property-based","test suite","proptest"]},"meta_signal":{"meta:campaign":["campaign"],"meta:recurring":["recurring","recurrence","standing","every run","each week"],"meta:roadmap":["roadmap","capability-expansion","future work"],"meta:umbrella":["umbrella","epic","master issue","parent issue","sub-issues","child issues"]},"precedence":{"bug":0,"chore":8,"decision":1,"documentation":4,"enhancement":7,"meta:campaign":0,"meta:recurring":2,"meta:roadmap":3,"meta:umbrella":1,"priority:p0":0,"priority:p1":1,"priority:p2":2,"priority:p3":3,"question":9,"refactor":5,"research":6,"scope:estate":0,"scope:repo":1,"status:blocked":0,"status:do-not-automate":3,"status:needs-owner":2,"status:needs-ruling":1,"status:ready":4,"tech-debt":2,"testing":3},"prefix_split_on":"/","scope_signal":{"scope:estate":["estate-wide","estate wide","across the estate","all repos","fleet-wide"]},"status_signal":{"status:blocked":["blocked on","blocked:","(blocked","is blocked","gated on","waiting on upstream","needs upstream"],"status:needs-owner":["unassigned","needs an owner","no owner"],"status:needs-ruling":["needs a ruling","awaiting ruling","owner decision needed"]},"tier_max":{"area":null,"meta":1,"priority":1,"scope":1,"status":1,"type":1},"tier_of":{"architecture":"area","automation":"area","bindings":"area","bug":"type","chore":"type","cicd":"area","conformance":"area","decision":"type","design":"area","documentation":"type","enhancement":"type","governance":"area","licensing":"area","meta:campaign":"meta","meta:recurring":"meta","meta:roadmap":"meta","meta:umbrella":"meta","migration":"area","packaging":"area","performance":"area","priority:p0":"priority","priority:p1":"priority","priority:p2":"priority","priority:p3":"priority","proofs":"area","question":"type","refactor":"type","research":"type","scaffolding":"area","scope:estate":"scope","scope:repo":"scope","security":"area","status:blocked":"status","status:do-not-automate":"status","status:needs-owner":"status","status:needs-ruling":"status","status:ready":"status","tech-debt":"type","testing":"type"},"title_prefix":{"adaptive":{"type":"enhancement"},"audit":{"type":"research"},"automation":{"areas":["automation"],"type":"enhancement"},"backends":{"areas":["design"],"type":"enhancement"},"backlog":{"type":"chore"},"bug":{"type":"bug"},"build":{"areas":["cicd"],"type":"chore"},"campaign":{"meta":"meta:campaign","type":"enhancement"},"chore":{"type":"chore"},"ci":{"areas":["cicd"],"type":"chore"},"clippy":{"type":"tech-debt"},"codegen":{"areas":["architecture"],"type":"enhancement"},"core":{"areas":["design"],"type":"enhancement"},"corrective":{"type":"bug"},"deps":{"type":"chore"},"docs":{"type":"documentation"},"drift":{"type":"tech-debt"},"epic":{"meta":"meta:umbrella","type":"enhancement"},"estate":{"scope":"scope:estate","type":"chore"},"evidence":{"areas":["design"],"type":"enhancement"},"feat":{"type":"enhancement"},"fix":{"type":"bug"},"governance":{"areas":["governance"],"type":"chore"},"hardening":{"areas":["security"],"type":"chore"},"hygiene":{"type":"tech-debt"},"lang":{"type":"bug"},"machine-readable":{"type":"tech-debt"},"manifest":{"areas":["design"],"type":"enhancement"},"migration":{"areas":["migration"],"type":"refactor"},"ops":{"areas":["automation"],"type":"chore"},"packaging":{"areas":["packaging"],"type":"chore"},"parser":{"type":"bug"},"perf":{"areas":["performance"],"type":"enhancement"},"perfective":{"type":"enhancement"},"policy":{"areas":["governance"],"type":"chore"},"preventive":{"type":"tech-debt"},"proof":{"areas":["proofs"],"type":"chore"},"proof-debt":{"areas":["proofs"],"type":"tech-debt"},"proofs":{"areas":["proofs"],"type":"chore"},"reclassify":{"type":"refactor"},"refactor":{"type":"refactor"},"release":{"type":"chore"},"research":{"type":"research"},"roadmap":{"meta":"meta:roadmap","type":"enhancement"},"rustsec":{"areas":["security"],"type":"chore"},"security":{"areas":["security"],"type":"chore"},"standard":{"areas":["governance"],"type":"chore"},"test":{"type":"testing"},"tests":{"type":"testing"},"track":{"meta":"meta:umbrella","type":"chore"},"tracker":{"meta":"meta:umbrella","type":"chore"},"tracking":{"meta":"meta:umbrella","type":"chore"},"umbrella":{"meta":"meta:umbrella","type":"enhancement"},"upstream":{"type":"chore"},"wiki":{"type":"documentation"}},"types":["bug","enhancement","documentation","refactor","tech-debt","testing","chore","research","decision","question"],"version":1} diff --git a/.github/labels.json b/.github/labels.json index 78786d4e..8e8c403e 100644 --- a/.github/labels.json +++ b/.github/labels.json @@ -1,260 +1 @@ -{ - "_generated_from": ".github/labels.yml in hyperpolymath/.git-private-farm", - "_do_not_edit": "regenerate with scripts/gen-labels-json.py", - "version": 1, - "labels": [ - { - "name": "bug", - "color": "d73a4a", - "description": "Something is broken or behaves incorrectly", - "tier": "type" - }, - { - "name": "enhancement", - "color": "a2eeef", - "description": "New capability or improvement to existing behaviour", - "tier": "type" - }, - { - "name": "documentation", - "color": "0075ca", - "description": "Docs, prose, diagrams, READMEs, ADRs", - "tier": "type" - }, - { - "name": "refactor", - "color": "c5def5", - "description": "Restructuring that preserves observable behaviour", - "tier": "type" - }, - { - "name": "tech-debt", - "color": "fbca04", - "description": "Known shortcut, drift, or hygiene owed - includes cleanup", - "tier": "type" - }, - { - "name": "testing", - "color": "bfd4f2", - "description": "Tests, benchmarks, fuzzing, property checks, coverage", - "tier": "type" - }, - { - "name": "chore", - "color": "ededed", - "description": "Routine maintenance with no behaviour change", - "tier": "type" - }, - { - "name": "research", - "color": "d4c5f9", - "description": "Open investigation; the outcome is knowledge, not code", - "tier": "type" - }, - { - "name": "decision", - "color": "8b5cf6", - "description": "A ruling is required before work can proceed", - "tier": "type" - }, - { - "name": "question", - "color": "d876e3", - "description": "Further information is requested", - "tier": "type" - }, - { - "name": "cicd", - "color": "006b75", - "description": "CI/CD: workflows, actions, lockfiles, pins, runners, release gates", - "tier": "area" - }, - { - "name": "security", - "color": "006b75", - "description": "Security posture, secrets, scanning, advisories, supply chain", - "tier": "area" - }, - { - "name": "proofs", - "color": "006b75", - "description": "Formal verification: Agda, Coq, Idris, Lean, Z3/SMT, axiom debt", - "tier": "area" - }, - { - "name": "governance", - "color": "006b75", - "description": "Policy, rulesets, standards, compliance, and their enforcement", - "tier": "area" - }, - { - "name": "design", - "color": "006b75", - "description": "Design of an interface, protocol, grammar, or type theory", - "tier": "area" - }, - { - "name": "architecture", - "color": "006b75", - "description": "Structural/system-level shape and runtime behaviour", - "tier": "area" - }, - { - "name": "performance", - "color": "006b75", - "description": "Throughput, latency, memory, binary size", - "tier": "area" - }, - { - "name": "bindings", - "color": "006b75", - "description": "ABI, FFI, WASM, and cross-language interop surfaces", - "tier": "area" - }, - { - "name": "migration", - "color": "006b75", - "description": "Porting between languages or toolchains (e.g. -> AffineScript)", - "tier": "area" - }, - { - "name": "packaging", - "color": "006b75", - "description": "Guix, Nix, containers, distribution artefacts", - "tier": "area" - }, - { - "name": "licensing", - "color": "006b75", - "description": "Licences, SPDX headers, REUSE compliance, attribution", - "tier": "area" - }, - { - "name": "automation", - "color": "006b75", - "description": "Bots, schedulers, dispatch, self-healing, fan-out", - "tier": "area" - }, - { - "name": "scaffolding", - "color": "006b75", - "description": "RSR templates, repo init, instantiation, project skeletons", - "tier": "area" - }, - { - "name": "conformance", - "color": "006b75", - "description": "Conformance to an external or internal specification", - "tier": "area" - }, - { - "name": "priority:p0", - "color": "b60205", - "description": "Critical - drop other work", - "tier": "priority" - }, - { - "name": "priority:p1", - "color": "d93f0b", - "description": "High - schedule next", - "tier": "priority" - }, - { - "name": "priority:p2", - "color": "e99695", - "description": "Normal - queue it", - "tier": "priority" - }, - { - "name": "priority:p3", - "color": "f9d0c4", - "description": "Low - nice to have", - "tier": "priority" - }, - { - "name": "status:blocked", - "color": "fbca04", - "description": "Cannot proceed until a dependency clears", - "tier": "status" - }, - { - "name": "status:ready", - "color": "fbca04", - "description": "Fully specified and ready to be picked up", - "tier": "status" - }, - { - "name": "status:needs-owner", - "color": "fbca04", - "description": "Unassigned and needs someone to take it", - "tier": "status" - }, - { - "name": "status:needs-ruling", - "color": "fbca04", - "description": "Awaiting an owner decision", - "tier": "status" - }, - { - "name": "status:do-not-automate", - "color": "fbca04", - "description": "Bots and sweeps must not touch this issue", - "tier": "status" - }, - { - "name": "meta:umbrella", - "color": "5319e7", - "description": "Parent issue aggregating child issues", - "tier": "meta" - }, - { - "name": "meta:campaign", - "color": "5319e7", - "description": "Coordinated multi-repo push with a defined end state", - "tier": "meta" - }, - { - "name": "meta:roadmap", - "color": "5319e7", - "description": "Forward planning; not yet actionable work", - "tier": "meta" - }, - { - "name": "meta:recurring", - "color": "5319e7", - "description": "Recurs on a schedule or by trigger; never finally closed", - "tier": "meta" - }, - { - "name": "scope:estate", - "color": "bfdadc", - "description": "Affects many or all repos across the estate", - "tier": "scope" - }, - { - "name": "scope:repo", - "color": "bfdadc", - "description": "Confined to this repository", - "tier": "scope" - } - ], - "frozen": [ - "dependencies", - "duplicate", - "elixir", - "gitar-approved", - "github_actions", - "good first issue", - "help wanted", - "invalid", - "javascript", - "never-stale", - "nix", - "pinned", - "python", - "rust", - "security", - "stale", - "wontfix" - ] -} +{"_do_not_edit":"regenerate with scripts/gen-labels-json.py","_generated_from":".github/labels.yml in hyperpolymath/.git-private-farm","frozen":["dependencies","duplicate","elixir","gitar-approved","github_actions","good first issue","help wanted","invalid","javascript","never-stale","nix","pinned","python","rust","security","stale","wontfix"],"labels":[{"color":"d73a4a","description":"Something is broken or behaves incorrectly","name":"bug","tier":"type"},{"color":"a2eeef","description":"New capability or improvement to existing behaviour","name":"enhancement","tier":"type"},{"color":"0075ca","description":"Docs, prose, diagrams, READMEs, ADRs","name":"documentation","tier":"type"},{"color":"c5def5","description":"Restructuring that preserves observable behaviour","name":"refactor","tier":"type"},{"color":"fbca04","description":"Known shortcut, drift, or hygiene owed - includes cleanup","name":"tech-debt","tier":"type"},{"color":"bfd4f2","description":"Tests, benchmarks, fuzzing, property checks, coverage","name":"testing","tier":"type"},{"color":"ededed","description":"Routine maintenance with no behaviour change","name":"chore","tier":"type"},{"color":"d4c5f9","description":"Open investigation; the outcome is knowledge, not code","name":"research","tier":"type"},{"color":"8b5cf6","description":"A ruling is required before work can proceed","name":"decision","tier":"type"},{"color":"d876e3","description":"Further information is requested","name":"question","tier":"type"},{"color":"006b75","description":"CI/CD: workflows, actions, lockfiles, pins, runners, release gates","name":"cicd","tier":"area"},{"color":"006b75","description":"Security posture, secrets, scanning, advisories, supply chain","name":"security","tier":"area"},{"color":"006b75","description":"Formal verification: Agda, Coq, Idris, Lean, Z3/SMT, axiom debt","name":"proofs","tier":"area"},{"color":"006b75","description":"Policy, rulesets, standards, compliance, and their enforcement","name":"governance","tier":"area"},{"color":"006b75","description":"Design of an interface, protocol, grammar, or type theory","name":"design","tier":"area"},{"color":"006b75","description":"Structural/system-level shape and runtime behaviour","name":"architecture","tier":"area"},{"color":"006b75","description":"Throughput, latency, memory, binary size","name":"performance","tier":"area"},{"color":"006b75","description":"ABI, FFI, WASM, and cross-language interop surfaces","name":"bindings","tier":"area"},{"color":"006b75","description":"Porting between languages or toolchains (e.g. -> AffineScript)","name":"migration","tier":"area"},{"color":"006b75","description":"Guix, Nix, containers, distribution artefacts","name":"packaging","tier":"area"},{"color":"006b75","description":"Licences, SPDX headers, REUSE compliance, attribution","name":"licensing","tier":"area"},{"color":"006b75","description":"Bots, schedulers, dispatch, self-healing, fan-out","name":"automation","tier":"area"},{"color":"006b75","description":"RSR templates, repo init, instantiation, project skeletons","name":"scaffolding","tier":"area"},{"color":"006b75","description":"Conformance to an external or internal specification","name":"conformance","tier":"area"},{"color":"b60205","description":"Critical - drop other work","name":"priority:p0","tier":"priority"},{"color":"d93f0b","description":"High - schedule next","name":"priority:p1","tier":"priority"},{"color":"e99695","description":"Normal - queue it","name":"priority:p2","tier":"priority"},{"color":"f9d0c4","description":"Low - nice to have","name":"priority:p3","tier":"priority"},{"color":"fbca04","description":"Cannot proceed until a dependency clears","name":"status:blocked","tier":"status"},{"color":"fbca04","description":"Fully specified and ready to be picked up","name":"status:ready","tier":"status"},{"color":"fbca04","description":"Unassigned and needs someone to take it","name":"status:needs-owner","tier":"status"},{"color":"fbca04","description":"Awaiting an owner decision","name":"status:needs-ruling","tier":"status"},{"color":"fbca04","description":"Bots and sweeps must not touch this issue","name":"status:do-not-automate","tier":"status"},{"color":"5319e7","description":"Parent issue aggregating child issues","name":"meta:umbrella","tier":"meta"},{"color":"5319e7","description":"Coordinated multi-repo push with a defined end state","name":"meta:campaign","tier":"meta"},{"color":"5319e7","description":"Forward planning; not yet actionable work","name":"meta:roadmap","tier":"meta"},{"color":"5319e7","description":"Recurs on a schedule or by trigger; never finally closed","name":"meta:recurring","tier":"meta"},{"color":"bfdadc","description":"Affects many or all repos across the estate","name":"scope:estate","tier":"scope"},{"color":"bfdadc","description":"Confined to this repository","name":"scope:repo","tier":"scope"}],"version":1} diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 2cca1e1f..751230fa 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -21,7 +21,7 @@ Copyright (c) Jonathan D.A. Jewell - [ ] 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 , no npm/bun, no Go/Python) +- [ ] No banned language patterns (no Python, Go, TypeScript or ReScript; JavaScript runs Bun > Deno > pnpm > npm) - [ ] 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 @@ -29,9 +29,10 @@ Copyright (c) Jonathan D.A. Jewell ### As Applicable -- [ ] `.machine_readable/descriptiles/STATE.a2ml` updated (if project state changed) -- [ ] `.machine_readable/descriptiles/ECOSYSTEM.a2ml` updated (if integrations changed) -- [ ] `.machine_readable/descriptiles/META.a2ml` updated (if architectural decisions changed) +- [ ] Repo deed (`*_chora.deed`) `(status)` / `(maturity)` updated (if project state changed) +- [ ] Repo deed `(ecosystem)` updated (if integrations changed) +- [ ] Repo deed `(meta)` and/or `docs/decisions/` updated (if architectural decisions changed) +- [ ] `docs/status/ROADMAP.adoc` updated (if milestones or next actions changed) - [ ] Documentation updated for user-facing changes - [ ] `TOPOLOGY.md` updated (if architecture changed) - [ ] `CHANGELOG` or release notes updated diff --git a/.github/rulesets/Immutable-Tags.json b/.github/rulesets/Immutable-Tags.json index 75fe73a0..05dbc8b6 100644 --- a/.github/rulesets/Immutable-Tags.json +++ b/.github/rulesets/Immutable-Tags.json @@ -1,28 +1 @@ -{ - "name": "Immutable-Tags", - "target": "tag", - "enforcement": "active", - "conditions": { - "ref_name": { - "include": [ - "~ALL" - ], - "exclude": [] - } - }, - "bypass_actors": [], - "rules": [ - { - "type": "deletion" - }, - { - "type": "non_fast_forward" - }, - { - "type": "update" - }, - { - "type": "required_signatures" - } - ] -} +{"bypass_actors":[],"conditions":{"ref_name":{"exclude":[],"include":["~ALL"]}},"enforcement":"active","name":"Immutable-Tags","rules":[{"type":"deletion"},{"type":"non_fast_forward"},{"type":"update"},{"type":"required_signatures"}],"target":"tag"} diff --git a/.github/rulesets/README.adoc b/.github/rulesets/README.adoc index 1b797261..a7794bc8 100644 --- a/.github/rulesets/README.adoc +++ b/.github/rulesets/README.adoc @@ -39,14 +39,113 @@ gh api --method PUT \ == Files `base.json`:: Canonical branch protection ruleset for the default branch (`~DEFAULT_BRANCH`). -Enforces required signatures, linear history, squash merge, and deletion/force-push protection -without unsatisfiable coverage or deadlocking approval requirements. +Enforces deleted-branch protection, linear history, squash merge, signatures and required +status checks, without unsatisfiable coverage or deadlocking approval requirements. +Sourced verbatim from `hyperpolymath/standards` `config/rulesets/base.json` (§7.3). + +`branch-floor.json`:: The irreducible branch floor for the default branch: deletion and +non-fast-forward protection only, with no bypass actors. This is the ruleset that keeps a +branch recoverable when the richer `Base` ruleset is unavailable or has been removed. +Sourced verbatim from `hyperpolymath/standards` `config/rulesets/branch-floor.json`. + +`require-signed-commits.json`:: Standalone, zero-bypass `required_signatures` on the default +branch (D215). Every new repo is born with it. See `hyperpolymath/standards` +`docs/SIGNING-POLICY.adoc`. Sourced verbatim from `config/rulesets/require-signed-commits.json`. + +`require-linear-history.json`:: Standalone, zero-bypass `required_linear_history` (D216). +Pair it with squash-only merge settings. A new repo starts with no merge commits, so it is +always linear-safe. Sourced verbatim from `config/rulesets/require-linear-history.json`. `Immutable-Tags.json`:: Makes release tags immutable — blocks tag deletion, non-fast-forward updates, and overwrites, and requires signed tags. +[NOTE] +==== +Files here are named to match the *live ruleset name*, which is not always the +upstream filename. Upstream ships `branch-floor.json` and `immutable-tags.json` +(lowercase, with a matching lowercase `name` inside the JSON); this repository's +`Immutable-Tags.json` declares `"name": "Immutable-Tags"`. Renaming a file here +changes nothing on GitHub, but it does change which upstream file it is diffed +against — keep that in mind when syncing. +==== + +== What is actually enforced on this repository + +Files are intent; this table is fact. Regenerate it with: + +[source,bash] +---- +gh api "/repos/{owner}/{repo}/rulesets" --jq '.[] | "\(.id)\t\(.name)\t\(.enforcement)\t\(.target)"' +---- + +|=== +| Live ruleset | Enforcement | Target | Covers + +| `Base` (`23218684`) | active | branch | deletion, required signatures, code scanning (CodeQL/Hypatia), Copilot review, non-fast-forward +| `Require-Linear-History` (`24258228`) | active | branch | required linear history +| `Secret-Scan-Floor` (`24309812`) | active | branch | required status checks (`scan / gitleaks`) +| `Immutable-Tags` (`22959911`) | active | tag | creation, deletion, non-fast-forward, update, required signatures +|=== + +=== Known drift between these files and what is live + +The files below are *not* a transcript of the live rulesets. This is the +divergence as of 2026-10-25, recorded rather than silently reconciled because +`base.json` is sourced verbatim from upstream and must not be forked here. + +*Live rulesets that no synced file describes* :: + +`code_scanning` (with CodeQL and Hypatia tools) and `copilot_code_review` are +enforced live in `Base` (`23218684`), and `Secret-Scan-Floor` (`24309812`) +enforces `required_status_checks` for `scan / gitleaks` (`integration_id: 15368`), +yet neither appears in `base.json` nor any upstream file synced into this +directory. Upstream's nearest equivalent for code scanning, +`config/rulesets/Optimus-Extras.json`, declares `code_scanning` with an *empty* +`code_scanning_tools` list, so it does not describe what is live here either. +Conversely, `branch-floor.json` is retained here as the irreducible recovery +payload even though the separate `Branch-Floor` live ruleset is not currently +mounted (`Base` covers both `deletion` and `non_fast_forward`). + +*Removed from live `Base` on 2026-10-02 (owner decision)* :: + +`Scorecard` was dropped from `code_scanning_tools`, and the `code_coverage` rule +(minimum 80%, max drop 5) was deleted. Neither could ever be satisfied by a pull +request. `scorecard.yml` runs only on `schedule` and `workflow_dispatch`, and +Scorecard scores repository posture rather than a diff, so with +`alerts_threshold: all` any standing finding would have blocked every PR. Nothing +in this template produces a coverage report: `rust-ci / llvm-cov` is skipped +because the template has no Rust. The result was that every PR sat `BLOCKED` until +an admin bypass (#219). CodeQL and Hypatia both upload results on pull requests, +so they stay. Do not add either rule back without a producer that runs on +`pull_request`. + +*`base.json` rules that are not in force* :: + +`required_linear_history` is in `base.json` but not in live `Base`; it is +enforced by the separate `Require-Linear-History` ruleset. `required_status_checks` (an empty list, so a no-op) and the +`pull_request` rule are likewise absent from live `Base`. (`non_fast_forward` is +live in `Base` as of 2026-10-02; `branch-floor.json` also specifies it as a +retained recovery payload, though `Branch-Floor` is not mounted as a separate live ruleset.) + +*`Immutable-Tags.json` lags the live ruleset* :: + +The live tag ruleset includes a `creation` rule; this file does not. Upstream +`immutable-tags.json` also populates `bypass_actors` (repository-role 5 and an +integration) with `bypass_mode: always`, and this file declares none. + +[WARNING] +==== +`bypass_actors` cannot be diffed from a low-privilege token: the REST API returns +`null` for that field unless the caller has admin on the repository. Absence of +`bypass_actors` in the output above is *not* evidence that none are configured. +==== + == Verifying Do not infer that a ruleset is active because the JSON is present. Check with the `gh api ... /rulesets` list above. A ruleset that exists as a file but was never POSTed is the protection equivalent of a check that cannot fail. + +Conversely, do not infer that the estate is protected because a ruleset exists. +A ruleset with `enforcement: disabled` is inert, and a `pull_request` rule with +`allowed_merge_methods: []` can never be satisfied at all. diff --git a/.github/rulesets/base.json b/.github/rulesets/base.json index 136c0a0d..5c3eaf04 100644 --- a/.github/rulesets/base.json +++ b/.github/rulesets/base.json @@ -1,102 +1 @@ -{ - "name": "Base", - "target": "branch", - "enforcement": "active", - "conditions": { - "ref_name": { - "include": [ - "~DEFAULT_BRANCH" - ], - "exclude": [] - } - }, - "bypass_actors": [ - { - "actor_id": 5, - "actor_type": "RepositoryRole", - "bypass_mode": "pull_request" - }, - { - "actor_id": 1236702, - "actor_type": "Integration", - "bypass_mode": "pull_request" - }, - { - "actor_id": 29110, - "actor_type": "Integration", - "bypass_mode": "pull_request" - }, - { - "actor_id": 15368, - "actor_type": "Integration", - "bypass_mode": "pull_request" - }, - { - "actor_id": 347564, - "actor_type": "Integration", - "bypass_mode": "pull_request" - }, - { - "actor_id": 46505, - "actor_type": "Integration", - "bypass_mode": "pull_request" - }, - { - "actor_id": 1143301, - "actor_type": "Integration", - "bypass_mode": "pull_request" - }, - { - "actor_id": 1144995, - "actor_type": "Integration", - "bypass_mode": "pull_request" - }, - { - "actor_id": 12526, - "actor_type": "Integration", - "bypass_mode": "pull_request" - }, - { - "actor_id": 2538504, - "actor_type": "Integration", - "bypass_mode": "pull_request" - } - ], - "rules": [ - { - "type": "deletion" - }, - { - "type": "non_fast_forward" - }, - { - "type": "required_signatures" - }, - { - "type": "required_linear_history" - }, - { - "type": "pull_request", - "parameters": { - "required_approving_review_count": 0, - "dismiss_stale_reviews_on_push": true, - "require_code_owner_review": false, - "require_last_push_approval": false, - "required_review_thread_resolution": true, - "require_extra_approval_for_unattributed_changes": false, - "required_reviewers": [], - "allowed_merge_methods": [ - "squash" - ] - } - }, - { - "type": "required_status_checks", - "parameters": { - "strict_required_status_checks_policy": true, - "do_not_enforce_on_create": false, - "required_status_checks": [] - } - } - ] -} +{"bypass_actors":[{"actor_id":5,"actor_type":"RepositoryRole","bypass_mode":"pull_request"},{"actor_id":1236702,"actor_type":"Integration","bypass_mode":"pull_request"},{"actor_id":29110,"actor_type":"Integration","bypass_mode":"pull_request"},{"actor_id":15368,"actor_type":"Integration","bypass_mode":"pull_request"},{"actor_id":347564,"actor_type":"Integration","bypass_mode":"pull_request"},{"actor_id":46505,"actor_type":"Integration","bypass_mode":"pull_request"},{"actor_id":1143301,"actor_type":"Integration","bypass_mode":"pull_request"},{"actor_id":1144995,"actor_type":"Integration","bypass_mode":"pull_request"},{"actor_id":12526,"actor_type":"Integration","bypass_mode":"pull_request"},{"actor_id":2538504,"actor_type":"Integration","bypass_mode":"pull_request"}],"conditions":{"ref_name":{"exclude":[],"include":["~DEFAULT_BRANCH"]}},"enforcement":"active","name":"Base","rules":[{"type":"deletion"},{"type":"non_fast_forward"},{"type":"required_signatures"},{"type":"required_linear_history"},{"parameters":{"allowed_merge_methods":["squash"],"dismiss_stale_reviews_on_push":true,"require_code_owner_review":false,"require_extra_approval_for_unattributed_changes":false,"require_last_push_approval":false,"required_approving_review_count":0,"required_review_thread_resolution":true,"required_reviewers":[]},"type":"pull_request"},{"parameters":{"do_not_enforce_on_create":false,"required_status_checks":[],"strict_required_status_checks_policy":true},"type":"required_status_checks"}],"target":"branch"} diff --git a/.github/rulesets/branch-floor.json b/.github/rulesets/branch-floor.json new file mode 100644 index 00000000..13b9d11f --- /dev/null +++ b/.github/rulesets/branch-floor.json @@ -0,0 +1 @@ +{"bypass_actors":[],"conditions":{"ref_name":{"exclude":[],"include":["~DEFAULT_BRANCH"]}},"enforcement":"active","name":"Branch-Floor","rules":[{"type":"deletion"},{"type":"non_fast_forward"}],"target":"branch"} diff --git a/.github/rulesets/require-linear-history.json b/.github/rulesets/require-linear-history.json new file mode 100644 index 00000000..611b621f --- /dev/null +++ b/.github/rulesets/require-linear-history.json @@ -0,0 +1 @@ +{"bypass_actors":[],"conditions":{"ref_name":{"exclude":[],"include":["~DEFAULT_BRANCH"]}},"enforcement":"active","name":"Require-Linear-History","rules":[{"type":"required_linear_history"}],"target":"branch"} diff --git a/.github/rulesets/require-signed-commits.json b/.github/rulesets/require-signed-commits.json new file mode 100644 index 00000000..6d78a18d --- /dev/null +++ b/.github/rulesets/require-signed-commits.json @@ -0,0 +1 @@ +{"bypass_actors":[],"conditions":{"ref_name":{"exclude":[],"include":["~DEFAULT_BRANCH"]}},"enforcement":"active","name":"Require-Signed-Commits","rules":[{"type":"required_signatures"}],"target":"branch"} diff --git a/.github/workflows/README.adoc b/.github/workflows/README.adoc index c7a23281..50e77417 100644 --- a/.github/workflows/README.adoc +++ b/.github/workflows/README.adoc @@ -61,3 +61,185 @@ pins), and gitleaks in CI catches a genuine SonarCloud token as `generic-api-key Each targets a different language/surface; together they cover what no single analyser does. + +== Deed and K9 conformance come from the canon, not from this tree + +`dogfood-gate.yml` validates the repo deed and the K9 contracts by calling the +two reusable lanes in hyperpolymath/standards, `deed-conformance.yml` and +`k9-conformance.yml`, at the one standards commit every `uses:` in this +directory pins. That commit supplies the linter, the validator, the K9 contract +(v1.0.0, D173) and the verdict-grid renderer, so what CI accepts is exactly +what the canon says (standards `docs/CONTRACTILE-DESCRIPTILE-VALIDATION.adoc`). + +* `k9-validate` (reusable) renders the K9 grid into its job summary and the + `k9-grid` artifact; it asks for `pull-requests: read` only. `k9-verdict` + downloads that artifact and posts `report.md` to the pull request under + ``, one comment per PR, + updated in place. `badges` publishes `badges/k9.json` to the + `governance-badges` branch on eligible pushes to `main`; the README badge reads it + through the shields endpoint; the section "The README badges are + generated output" below states the contract that branch operates under. +* `hypatia-scan.yml` -> `verdict` job posts the Hypatia grid the same way + (artifact `verdict-grid`, marker ``). + +There is deliberately no second validator here: the former `k9-validate.yml` +and `deed-validate.yml` (the `k9-ecosystem` / `deed-ecosystem` actions at +`@main`) and the grep checks in `.github/hooks/validate-{k9,deed}.sh` accepted +files the contract rejects. The hooks are now thin wrappers over the same +canonical tools, run from a standards checkout (`STANDARDS_DIR`), and skip +with a notice when none is present. k9iser is retired estate-wide: contracts +are authored to `1-formats/k9/spec/K9-CONTRACT-SPEC.adoc`, never generated. + +== The README badges are generated output (`governance-badges`) + +Every repository minted from this template publishes one Shields-endpoint JSON +file per validation lane, on a *separate orphan branch* named +`governance-badges`: + +[cols="1,1,3",options="header"] +|=== +| Lane | File | Written by + +| K9 conformance +| `badges/k9.json` +| `dogfood-gate.yml` -> `badges` job, on eligible pushes to `main` + +|=== + +`README.adoc` reads that file through the shields endpoint at a URL that must +not change: + +---- +https://raw.githubusercontent.com///governance-badges/badges/k9.json +---- + +Both halves - rendering the badge and deciding whether to publish it - live in +`scripts/governance-badge.js`. The workflow only supplies the lane's result and +the lane's artifact. `tests/workflows/governance_badge_test.sh` exercises the +helper against a mock of the GitHub API and checks this directory's wiring. + +=== It is generated output, not source + +* `governance-badges` is an *orphan* branch. Its commits are created with + `parents: []`, so there is *no common ancestor with `main`* - not "a little + history", none. It is not a variant, a release branch or a staging area. +* *It must never be merged*, and there is nothing to merge: a pull request from + it would show unrelated histories. Do not open one, do not merge one, do not + rebase it onto `main`. Merging it would import a badges-only tree over the + repository's real content. +* *Recent pushes are normal.* Eligible pushes to `main` republish the badge. A run + whose badge is unchanged makes *no commit at all*, so the branch is quiet + when the lane result is stable and moves only when the state changes. +* It is safe to delete. The next eligible push to `main` recreates it, with no parent, + from scratch. +* It carries no workflows, no code and nothing that runs. Treat it like a + generated site deployment, not like a branch of the repository. + +=== What each colour means + +[cols="1,1,1,3",options="header"] +|=== +| Lane result | Badge message | Colour | Meaning + +| `success` +| `success` +| brightgreen +| The lane ran, passed, and produced its artifact. + +| `failure` +| `failure` +| red +| The lane ran and failed. + +| `skipped` +| `skipped` +| lightgrey +| The lane did not run for this commit. + +| `cancelled` +| `cancelled` +| lightgrey +| The lane started and was cancelled (superseded run, manual cancel, workflow + concurrency). + +| missing/malformed lane artifact +| `unavailable` +| lightgrey +| The lane claims success but its evidence is missing, unreadable or + self-contradictory (for example a `success` message paired with a red + colour). Nothing trustworthy happened, so nothing green is published. + +| anything else (`timed_out`, `neutral`, `action_required`, empty, a value from + a newer GitHub) +| `unknown` +| lightgrey +| Unrecognised. Treated as "no trustworthy result" rather than guessed at. +|=== + +*Grey means "this run did not produce a trustworthy success/failure result".* +It does not mean "pending", "cached" or "about to go green", and it is never a +stale green left behind by an earlier run: a workflow that runs with a skipped, +cancelled or unavailable lane *publishes grey*. + +The badge reflects the *lane job's* result (`needs.k9-validate.result`), with +the lane's artifact as a *witness*: a `success` result is only believed when the +`k9-grid` artifact is present, well formed, byte-identical to the canonical +render, and itself records `success`. An artifact can never turn a failed lane +green; it can only stop a green one being published. + +[NOTE] +==== +*Known limit.* If the whole workflow run is cancelled, GitHub does not start +the publisher at all, so the badge keeps its previous value until the next eligible push +to `main`. No job can publish a state for a run it was not allowed to execute. +Because the run that cancels a superseded one is itself publishing, the badge +converges on the newest run's result rather than staying stuck. +==== + +=== Identical content produces no commit + +Before writing anything, the publisher fetches the file that is currently on the +branch and compares it *byte for byte* with the badge it has just rendered. + +* Identical -> it prints `unchanged`, writes no commit, and exits 0. +* Different -> it publishes with the blob sha it just read, so a concurrent + publication is detected (HTTP 409) and re-evaluated instead of silently + overwriting the other run's commit. Publications are also serialised by a + per-repository `concurrency` group. +* The JSON is never re-serialised or canonicalised to make a comparison + succeed. Key order and spacing are fixed by the renderer, and a file that + differs only in layout *is* a difference: it gets republished. + +=== Missing is not the same as broken + +The publisher distinguishes the two, because treating every API error as +"missing" is how a badge pipeline quietly creates branches it should not: + +[cols="1,2",options="header"] +|=== +| HTTP | What happens + +| `404` on the file, `404` on the ref +| The branch really is absent: create it as an orphan (`parents: []`). + +| `404` on the file, `200` on the ref +| The branch exists but the file does not: add the file, no new branch. + +| `404` on the file, anything else on the ref +| Unknown. Fail the run; do not create a branch. + +| `401` / `403` +| Authentication or permission failure. Fail; do not write. + +| `429` / `5xx`, or a network error +| Transient. Retried a bounded number of times, then fail; nothing is treated + as missing. + +| Any other status +| Fail; do not write. +|=== + +A malformed file that is already on the branch (not JSON, not an object, no +`schemaVersion`, no message) is *refused*, not overwritten: it did not come from +this tool, and silently replacing it would hide a hand edit. Repair or delete it +and re-run. diff --git a/.github/workflows/actions.lock b/.github/workflows/actions.lock index c5d89c8d..29050b78 100644 --- a/.github/workflows/actions.lock +++ b/.github/workflows/actions.lock @@ -8,18 +8,17 @@ workflows: '.github/workflows/codeql.yml': - 'actions/checkout@v7.0.1' - 'github/codeql-action@9b3254085494b55a0f7c4c2b3d2d52cc712ce370' - '.github/workflows/deed-validate.yml': - - 'actions/checkout@v7.0.1' - - 'hyperpolymath/deed-ecosystem@main' '.github/workflows/dependabot-automerge.yml': - - 'dependabot/fetch-metadata@v3.1.0' + - 'dependabot/fetch-metadata@25dd0e34f4fe68f24cc83900b1fe3fe149efef98' '.github/workflows/docker-build.yml': - 'actions/checkout@v7.0.1' '.github/workflows/dogfood-gate.yml': - - 'actions/checkout@v7.0.1' - - 'erlef/setup-beam@v1.24.1' - - 'hyperpolymath/deed-ecosystem@main' - - 'hyperpolymath/k9-ecosystem@main' + - 'actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9' + - 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' + - 'actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333' + - 'actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9' + - 'erlef/setup-beam@54075bcc5e249e4758d363f27d099f55d843f124' + - 'oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6' '.github/workflows/dogfood-summary.yml': - 'actions/checkout@v7.0.1' '.github/workflows/dot-wellknown-enforcement.yml': @@ -29,25 +28,34 @@ workflows: '.github/workflows/empty-linter.yml': - 'actions/checkout@v7.0.1' '.github/workflows/estate-rules.yml': - - 'actions/checkout@v7.0.1' + - 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' + '.github/workflows/fork-governance.yml': + - 'actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9' + - 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' + - 'actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333' + - 'actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9' + - 'oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6' + '.github/workflows/verdict-grid-publish.yml': + - 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' '.github/workflows/governance.yml': - - 'metadatastician/standards@46ee18323305d5b36e2eef936e47dd54c39ea736' + - 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' '.github/workflows/groove-check.yml': - 'actions/checkout@v7.0.1' '.github/workflows/guix-policy.yml': - 'actions/checkout@v7.0.1' '.github/workflows/hypatia-scan.yml': - - 'metadatastician/standards@46ee18323305d5b36e2eef936e47dd54c39ea736' - '.github/workflows/k9-validate.yml': - - 'actions/checkout@v7.0.1' - - 'hyperpolymath/k9-ecosystem@main' + - 'actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9' + - 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' + - 'actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9' + - 'erlef/setup-beam@54075bcc5e249e4758d363f27d099f55d843f124' + - 'github/codeql-action@9b3254085494b55a0f7c4c2b3d2d52cc712ce370' '.github/workflows/label-triage.yml': [] '.github/workflows/labels.yml': [] '.github/workflows/lock-sync-gate.yml': [] '.github/workflows/main-estate-audit.yml': - - 'hyperpolymath/cicd-suite@55556cf5ba71ba744695861503c13148d3915a5d' + - 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' '.github/workflows/mirror.yml': - - 'metadatastician/standards@46ee18323305d5b36e2eef936e47dd54c39ea736' + - 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' '.github/workflows/ossf-best-practices.yml': - 'actions/checkout@v7.0.1' '.github/workflows/pages.yml': @@ -57,13 +65,15 @@ workflows: - 'actions/deploy-pages@v5.0.1' - 'actions/upload-pages-artifact@v5.0.0' - 'haskell-actions/setup@v2.12.1' - '.github/workflows/proofs.yml': + '.github/workflows/proven-tests.yml': + - 'actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9' - 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' + - 'oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6' '.github/workflows/push-email-notify.yml': - - 'hyperpolymath/smtp-notify-action@v0.5.1' + - 'hyperpolymath/smtp-notify-action@v0.5.0' '.github/workflows/quality.yml': - - 'actions/checkout@v7.0.1' - - 'editorconfig-checker/action-editorconfig-checker@v3.0.0' + - 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' + - 'editorconfig-checker/action-editorconfig-checker@51f63319f592f97930c73d9c46184d20bd206393' '.github/workflows/release.yml': - 'actions/attest-build-provenance@v4.2.2' - 'actions/checkout@v7.0.1' @@ -71,27 +81,27 @@ workflows: - 'softprops/action-gh-release@v3.0.3' '.github/workflows/rsr-compliance-canary.yml': - 'actions/checkout@v7.0.1' - '.github/workflows/runtime-policy.yml': - - 'actions/checkout@v7.0.1' '.github/workflows/rust-ci.yml': - - 'metadatastician/standards@46ee18323305d5b36e2eef936e47dd54c39ea736' + - 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' '.github/workflows/scorecard.yml': - - 'metadatastician/standards@46ee18323305d5b36e2eef936e47dd54c39ea736' + - 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' + - 'github/codeql-action@9b3254085494b55a0f7c4c2b3d2d52cc712ce370' + - 'ossf/scorecard-action@fa7117db83c52d787ae5a89f350999701505d78e' '.github/workflows/secret-scanner.yml': - - 'metadatastician/standards@46ee18323305d5b36e2eef936e47dd54c39ea736' + - 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' '.github/workflows/security-policy.yml': - - 'actions/checkout@v7.0.1' + - 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' '.github/workflows/sonarqube.yml': - 'actions/checkout@v7.0.1' - - 'sonarsource/sonarqube-scan-action@v8.4.0' + - 'sonarsource/sonarqube-scan-action@v8.3.0' + '.github/workflows/squabble.yml': [] '.github/workflows/static-analysis-gate.yml': - - 'actions/checkout@v7.0.1' - - 'actions/download-artifact@v8.0.2' - - 'actions/upload-artifact@v7.0.2' - - 'erlef/setup-beam@v1.24.1' + - 'actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9' + - 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' + - 'actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333' + - 'actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9' '.github/workflows/workflow-linter.yml': - 'actions/checkout@v7.0.1' - - 'oven-sh/setup-bun@v2.2.0' dependencies: 'actions/attest-build-provenance@v4.2.2': ref: 'v4.2.2' @@ -140,11 +150,6 @@ dependencies: commit: 'sha1-9000827ccba6bdab643e8b6fd33ac0654aef8333' owner_id: 44036562 repo_id: 192626254 - 'actions/download-artifact@v8.0.2': - ref: 'v8.0.2' - commit: 'sha1-9000827ccba6bdab643e8b6fd33ac0654aef8333' - owner_id: 44036562 - repo_id: 192626254 'actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f': ref: 'v7.0.0' commit: 'sha1-bbbca2ddaa5d8feaa63e36b76fdaad77386f024f' @@ -167,109 +172,36 @@ dependencies: repo_id: 496012378 uses: - 'actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f' - 'denoland/setup-deno@22d081ff2d3a40755e97629de92e3bcbfa7cf2ed': - ref: 'v2.0.5' - commit: 'sha1-22d081ff2d3a40755e97629de92e3bcbfa7cf2ed' - owner_id: 42048915 - repo_id: 356423100 - 'dependabot/fetch-metadata@v3.1.0': + 'dependabot/fetch-metadata@25dd0e34f4fe68f24cc83900b1fe3fe149efef98': ref: 'v3.1.0' commit: 'sha1-25dd0e34f4fe68f24cc83900b1fe3fe149efef98' owner_id: 27347476 repo_id: 371068214 - 'dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8': - ref: 'v1' - commit: 'sha1-683b588c487a69d01f6c6ddf40f036ff682cc2c8' - owner_id: 1940490 - repo_id: 260749683 'editorconfig-checker/action-editorconfig-checker@51f63319f592f97930c73d9c46184d20bd206393': ref: 'v3.0.0' commit: 'sha1-51f63319f592f97930c73d9c46184d20bd206393' owner_id: 26415196 repo_id: 297874902 - 'editorconfig-checker/action-editorconfig-checker@v3.0.0': - ref: 'v3.0.0' - commit: 'sha1-51f63319f592f97930c73d9c46184d20bd206393' - owner_id: 26415196 - repo_id: 297874902 'erlef/setup-beam@54075bcc5e249e4758d363f27d099f55d843f124': ref: 'v1.24.1' commit: 'sha1-54075bcc5e249e4758d363f27d099f55d843f124' owner_id: 47606891 repo_id: 331103973 - 'erlef/setup-beam@v1.24.1': - ref: 'v1.24.1' - commit: 'sha1-54075bcc5e249e4758d363f27d099f55d843f124' - owner_id: 47606891 - repo_id: 331103973 'github/codeql-action@9b3254085494b55a0f7c4c2b3d2d52cc712ce370': ref: 'v4.39.1' commit: 'sha1-9b3254085494b55a0f7c4c2b3d2d52cc712ce370' owner_id: 9919 repo_id: 259445878 - 'github/codeql-action@b96794f015dfd88f77b49b1c93e0fa7110f94c63': - ref: 'v4.38.0' - commit: 'sha1-b96794f015dfd88f77b49b1c93e0fa7110f94c63' - owner_id: 9919 - repo_id: 259445878 - 'goto-bus-stop/setup-zig@abea47f85e598557f500fa1fd2ab7464fcb39406': - ref: 'v2.2.1' - commit: 'sha1-abea47f85e598557f500fa1fd2ab7464fcb39406' - owner_id: 1006268 - repo_id: 212984112 'haskell-actions/setup@v2.12.1': ref: 'v2.12.1' commit: 'sha1-0f8e8c99d88aeb3fbfd523f1ef2c6f762d10d64d' owner_id: 75048950 repo_id: 623796603 - 'hyperpolymath/cicd-suite@0da816c05ae7486671d863e07935f93981c0c2d5': - ref: '0da816c05ae7486671d863e07935f93981c0c2d5' - commit: 'sha1-0da816c05ae7486671d863e07935f93981c0c2d5' - owner_id: 6759885 - repo_id: 1326697643 - 'hyperpolymath/cicd-suite@55556cf5ba71ba744695861503c13148d3915a5d': - ref: '55556cf5ba71ba744695861503c13148d3915a5d' - commit: 'sha1-55556cf5ba71ba744695861503c13148d3915a5d' - owner_id: 6759885 - repo_id: 1326697643 - uses: - - 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' - - 'hyperpolymath/cicd-suite@0da816c05ae7486671d863e07935f93981c0c2d5' - 'hyperpolymath/deed-ecosystem@main': - ref: 'main' - commit: 'sha1-44f9c9fc42901a55e0f489a40eabf4173e550d1d' - owner_id: 6759885 - repo_id: 1275649586 - 'hyperpolymath/k9-ecosystem@main': - ref: 'main' - commit: 'sha1-2155aa26a21758f2ba119f61bc7e0e1981c106fb' - owner_id: 6759885 - repo_id: 1275650185 - 'hyperpolymath/smtp-notify-action@v0.5.1': - ref: 'v0.5.1' - commit: 'sha1-e384daf6167a7a7567642d6a62060106244d2413' + 'hyperpolymath/smtp-notify-action@v0.5.0': + ref: 'v0.5.0' + commit: 'sha1-c1c9fa07992a02c1fd3d67a0dc1b08cccb852aef' owner_id: 6759885 repo_id: 1352485172 - 'metadatastician/standards@46ee18323305d5b36e2eef936e47dd54c39ea736': - ref: '46ee18323305d5b36e2eef936e47dd54c39ea736' - commit: 'sha1-46ee18323305d5b36e2eef936e47dd54c39ea736' - owner_id: 297579217 - repo_id: 1116521501 - uses: - - 'actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9' - - 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' - - 'actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333' - - 'actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9' - - 'denoland/setup-deno@22d081ff2d3a40755e97629de92e3bcbfa7cf2ed' - - 'dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8' - - 'editorconfig-checker/action-editorconfig-checker@51f63319f592f97930c73d9c46184d20bd206393' - - 'erlef/setup-beam@54075bcc5e249e4758d363f27d099f55d843f124' - - 'github/codeql-action@b96794f015dfd88f77b49b1c93e0fa7110f94c63' - - 'goto-bus-stop/setup-zig@abea47f85e598557f500fa1fd2ab7464fcb39406' - - 'ossf/scorecard-action@fa7117db83c52d787ae5a89f350999701505d78e' - - 'oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6' - - 'swatinem/rust-cache@d1527c8f67ef9af357290475d4af4b0fab8f12e0' - - 'webfactory/ssh-agent@e83874834305fe9a4a2997156cb26c5de65a8555' 'ossf/scorecard-action@fa7117db83c52d787ae5a89f350999701505d78e': ref: 'v2.5.0' commit: 'sha1-fa7117db83c52d787ae5a89f350999701505d78e' @@ -280,28 +212,13 @@ dependencies: commit: 'sha1-0c5077e51419868618aeaa5fe8019c62421857d6' owner_id: 108928776 repo_id: 512644635 - 'oven-sh/setup-bun@v2.2.0': - ref: 'v2.2.0' - commit: 'sha1-0c5077e51419868618aeaa5fe8019c62421857d6' - owner_id: 108928776 - repo_id: 512644635 'softprops/action-gh-release@v3.0.3': ref: 'v3.0.3' commit: 'sha1-efb35369e0ad2afab669f228072c1b0d510eae64' owner_id: 2242 repo_id: 204253808 - 'sonarsource/sonarqube-scan-action@v8.4.0': - ref: 'v8.4.0' - commit: 'sha1-4d1dc0c91ee400dcf8a6dddf2f705ac36542e304' + 'sonarsource/sonarqube-scan-action@v8.3.0': + ref: 'v8.3.0' + commit: 'sha1-d209202bc7d53ff1cc128f7f907dac145c9d6ae9' owner_id: 545988 repo_id: 366408409 - 'swatinem/rust-cache@d1527c8f67ef9af357290475d4af4b0fab8f12e0': - ref: 'v2.9.3' - commit: 'sha1-d1527c8f67ef9af357290475d4af4b0fab8f12e0' - owner_id: 580492 - repo_id: 298565987 - 'webfactory/ssh-agent@e83874834305fe9a4a2997156cb26c5de65a8555': - ref: 'v0.10.0' - commit: 'sha1-e83874834305fe9a4a2997156cb26c5de65a8555' - owner_id: 135788 - repo_id: 208510314 diff --git a/.github/workflows/build-notification.yml b/.github/workflows/build-notification.yml index e43da5b7..0df5cc5d 100644 --- a/.github/workflows/build-notification.yml +++ b/.github/workflows/build-notification.yml @@ -19,7 +19,7 @@ permissions: contents: read jobs: trigger-boj: - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 timeout-minutes: 15 if: ${{ vars.BOJ_SERVER_URL != '' }} steps: diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index 345c9c75..4b76561a 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -15,7 +15,7 @@ permissions: contents: read jobs: analyze: - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 timeout-minutes: 15 permissions: contents: read diff --git a/.github/workflows/deed-validate.yml b/.github/workflows/deed-validate.yml deleted file mode 100644 index 47cf3446..00000000 --- a/.github/workflows/deed-validate.yml +++ /dev/null @@ -1,59 +0,0 @@ -# This workflow is managed by gh actions-lock. -# SPDX-License-Identifier: MPL-2.0 -name: "🟡 CHECK: DEED Manifest Validation" - -on: - pull_request: - branches: ['**'] - push: - branches: [main, master] - -concurrency: - group: ${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: true - -permissions: - contents: read - -jobs: - deed-validate: - name: Validate DEED manifests - runs-on: ubuntu-latest - timeout-minutes: 15 - - steps: - - name: Checkout repository - uses: actions/checkout@v7.0.1 - - - name: Check for A2ML files - id: detect - run: | - COUNT=$(find . \( -name '*.a2ml' -o -name '*.deed' \) -not -path './.git/*' | wc -l) - echo "count=$COUNT" >> "$GITHUB_OUTPUT" - if [ "$COUNT" -eq 0 ]; then - echo "::warning::No .a2ml/.deed manifest files found. Every RSR repo should have a repo deed (_chora.deed); legacy 0-AI-MANIFEST.a2ml accepted mid-migration — standards #837" - fi - - - name: "🟡 CHECK: Validate DEED manifests" - if: steps.detect.outputs.count > 0 - uses: hyperpolymath/deed-ecosystem/validate-action@main - with: - path: '.' - strict: 'false' - - - name: Write summary - run: | - MANIFEST_COUNT="${{ steps.detect.outputs.count }}" - if [ "$MANIFEST_COUNT" -eq 0 ]; then - cat <<'EOF' >> "$GITHUB_STEP_SUMMARY" - ## DEED Manifest Validation - - :warning: **No .a2ml/.deed manifest files found.** Every RSR-compliant repo should have a repo deed (`_chora.deed`) at its root. - - Copy it from [rsr-template-repo](https://github.com/hyperpolymath/rsr-template-repo). Manifests are validated against the DEED grammar (standards `1-formats/deed/`); the `.a2ml` → `.deed` extension migration is tracked in standards #837 — the deed validator scans both. - EOF - else - echo "## DEED Manifest Validation" >> "$GITHUB_STEP_SUMMARY" - echo "" >> "$GITHUB_STEP_SUMMARY" - echo "Scanned **${MANIFEST_COUNT}** .a2ml/.deed manifest(s). See step output for details." >> "$GITHUB_STEP_SUMMARY" - fi diff --git a/.github/workflows/dependabot-automerge.yml b/.github/workflows/dependabot-automerge.yml index 31a7b6aa..f1487d05 100644 --- a/.github/workflows/dependabot-automerge.yml +++ b/.github/workflows/dependabot-automerge.yml @@ -1,39 +1,21 @@ # This workflow is managed by gh actions-lock. # 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). +# dependabot-automerge.yml — enable GitHub's native auto-merge on Dependabot +# pull requests that satisfy the fail-closed severity + semver policy (#204): +# 1. PR author is Dependabot (verified by immutable numeric user.id 49699333 +# AND user.login == 'dependabot[bot]', never spoofable github.actor); +# 2. Security update (GHSA ID present) whose GitHub Advisory severity is +# verified via the GitHub Advisory API as `low` or `medium` (CVSS < 7.0; +# `high`, `critical`, or unreadable advisories fail closed to human review); +# 3. Semver update is `patch` or `minor` (never `major`). # -# 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. +# Never invokes `--admin`: GitHub's native `--auto` waits for all required +# status checks, reviews and code-scanning rulesets to pass (`squabble != bypass`). +# Enabling auto-merge does not require submitting an approving review. Keep +# any required review pending for a maintainer instead of depending on the +# repository setting that permits GitHub Actions to approve pull requests. +# The merge request must match the head commit that triggered this run. name: Dependabot Auto-Merge on: @@ -44,84 +26,91 @@ concurrency: cancel-in-progress: false permissions: contents: read - pull-requests: write # needed to approve - # NB: keep narrow — do NOT add secrets: read or id-token: write here. - # The write scope auto-merge needs is elevated PER JOB below, not here: a - # job-level permissions: block REPLACES this one, so the job restates both. + pull-requests: read jobs: automerge: - # Only run for PRs actually authored by Dependabot. - if: github.actor == 'dependabot[bot]' && github.event.pull_request.user.login == 'dependabot[bot]' + if: github.event.pull_request.user.login == 'dependabot[bot]' && github.event.pull_request.user.id == 49699333 permissions: - contents: write # needed to enable auto-merge (gh pr merge --auto) - pull-requests: write # needed to approve - runs-on: ubuntu-latest + contents: write + pull-requests: write + runs-on: ubuntu-24.04 timeout-minutes: 15 steps: - name: Fetch Dependabot metadata id: meta - uses: dependabot/fetch-metadata@v3.1.0 + uses: dependabot/fetch-metadata@25dd0e34f4fe68f24cc83900b1fe3fe149efef98 # v3.1.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 + github-token: ${{ github.token }} + + - name: Decide policy outcome (fail-closed on severity & semver) id: policy env: - GHSA_ID: ${{ steps.meta.outputs.ghsa-id }} + GH_TOKEN: ${{ github.token }} + META_GHSA_ID: ${{ steps.meta.outputs.ghsa-id }} + DEP_NAMES: ${{ steps.meta.outputs.dependency-names }} UPDATE_TYPE: ${{ steps.meta.outputs.update-type }} - PR_LABELS: ${{ toJson(github.event.pull_request.labels.*.name) }} + PR_BODY: ${{ github.event.pull_request.body }} run: | set -euo pipefail + action="manual_review" + severity="n/a" + reason="routine or non-qualifying update" - is_security=false - [ -n "$GHSA_ID" ] && is_security=true + # Populate GHSA_ID from fetch-metadata when available; otherwise extract + # the GHSA identifier from Dependabot's security PR body and cross-verify + # against the authoritative GitHub Advisory API + dependency name (never + # trusting PR text alone, and requiring no PAT secret). + GHSA_ID="$META_GHSA_ID" + if [ -z "$GHSA_ID" ] && [ -n "$PR_BODY" ]; then + GHSA_ID="$(printf '%s\n' "$PR_BODY" | grep -oE 'GHSA-[23456789cfghjmpqrvwx]{4}-[23456789cfghjmpqrvwx]{4}-[23456789cfghjmpqrvwx]{4}' | head -n 1 || true)" + fi - # Owner policy (deliberate: velocity over caution). Auto-merge EVERY - # Dependabot update — patch, minor AND major, security or routine. - # Safe because GitHub's auto-merge only COMPLETES once the required - # checks (secret-scanner, codeql, hypatia-scan, openssf-compliance, - # build/test) are green: a bump that breaks fails CI and the PR stays - # OPEN with an email ("oi, it broke") instead of landing on a red - # main; a bump that passes lands within minutes with no chasing. - # This is preferred over making Dependabot a ruleset BYPASS actor, - # which would let bumps skip those very checks (no gate, no signal). - echo "action=automerge" >> "$GITHUB_OUTPUT" - 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 [ -n "$GHSA_ID" ]; then + if [[ "$UPDATE_TYPE" = "version-update:semver-patch" || "$UPDATE_TYPE" = "version-update:semver-minor" ]]; then + adv_json="$(gh api "/advisories/${GHSA_ID}" 2>/dev/null || echo '{}')" + severity="$(printf '%s' "$adv_json" | jq -r '.severity // "unknown"')" + cvss="$(printf '%s' "$adv_json" | jq -r 'if (.cvss.score | type) == "number" then (.cvss.score | tostring) else "invalid" end')" + pkg_match="$(printf '%s' "$adv_json" | jq -r --arg deps "$DEP_NAMES" ' + ($deps | split(",") | map(gsub("^\\s+|\\s+$"; "") | ascii_downcase) | map(select(length > 0))) as $dlist + | [ (.vulnerabilities // [])[].package.name // "" | ascii_downcase ] as $alist + | if ($dlist | length) > 0 and any($dlist[]; . as $d | any($alist[]; . == $d)) then "true" else "false" end + ')" + if [ "$pkg_match" = "true" ] && [[ "$severity" = "low" || "$severity" = "medium" ]] && [[ "$cvss" =~ ^[0-9]+(\.[0-9]+)?$ ]] && awk -v s="$cvss" 'BEGIN { exit !(s + 0 < 7.0) }'; then + action="automerge" + reason="verified ${severity} security ${UPDATE_TYPE#version-update:} (CVSS ${cvss} < 7.0)" + else + reason="security advisory ${GHSA_ID} (severity='${severity}', CVSS=${cvss}, pkg_match=${pkg_match}) — human review required" + fi + else + reason="security update ${GHSA_ID} is '${UPDATE_TYPE}' (major or unknown) — human review required" + fi + fi + + { + echo "action=$action" + echo "severity=$severity" + echo "reason=$reason" + echo "update_type=$UPDATE_TYPE" + echo "ghsa=$GHSA_ID" + } >> "$GITHUB_OUTPUT" + + - name: Enable auto-merge (when fail-closed policy allows) + id: enable if: steps.policy.outputs.action == 'automerge' env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GH_TOKEN: ${{ github.token }} PR_URL: ${{ github.event.pull_request.html_url }} + PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }} run: | - gh pr merge --auto --squash "$PR_URL" + gh pr merge --auto --squash --match-head-commit "$PR_HEAD_SHA" "$PR_URL" + - name: Write decision to step summary + if: always() env: ACTION: ${{ steps.policy.outputs.action }} - IS_SECURITY: ${{ steps.policy.outputs.security }} + MERGE_OUTCOME: ${{ steps.enable.outcome }} + SEVERITY: ${{ steps.policy.outputs.severity }} + REASON: ${{ steps.policy.outputs.reason }} UPDATE_TYPE: ${{ steps.policy.outputs.update_type }} GHSA: ${{ steps.policy.outputs.ghsa }} run: | @@ -130,8 +119,10 @@ jobs: echo "" echo "| Field | Value |" echo "|-------|-------|" - echo "| Policy action | \`$ACTION\` |" - echo "| Security update | \`$IS_SECURITY\` |" - echo "| Update type | \`$UPDATE_TYPE\` |" + echo "| Policy action | \`${ACTION}\` |" + echo "| Auto-merge request | \`${MERGE_OUTCOME}\` |" + echo "| Reason | ${REASON} |" + echo "| Advisory severity | \`${SEVERITY}\` |" + echo "| Update type | \`${UPDATE_TYPE}\` |" echo "| GHSA ID | \`${GHSA:-n/a}\` |" } >> "$GITHUB_STEP_SUMMARY" diff --git a/.github/workflows/docker-build.yml b/.github/workflows/docker-build.yml index f795d2ee..819043da 100644 --- a/.github/workflows/docker-build.yml +++ b/.github/workflows/docker-build.yml @@ -6,7 +6,7 @@ on: paths: - 'build/container/**' - 'build/just/container.just' - - '.github/workflows/container-build.yml' + - '.github/workflows/docker-build.yml' push: tags: ['v*'] workflow_dispatch: @@ -32,6 +32,8 @@ jobs: contents: read steps: - uses: actions/checkout@v7.0.1 + with: + persist-credentials: false - name: Tooling check run: | @@ -46,9 +48,11 @@ jobs: run: just container-verify - name: Scan image (trivy, best-effort) + env: + REPO_NAME: ${{ github.event.repository.name }} run: | if command -v trivy >/dev/null 2>&1; then - trivy image --severity HIGH,CRITICAL --exit-code 0 "${{ github.event.repository.name }}:latest" || true + trivy image --severity HIGH,CRITICAL --exit-code 0 "${REPO_NAME}:latest" || true else echo "trivy not installed on this runner — skipping image scan" fi diff --git a/.github/workflows/dogfood-gate.yml b/.github/workflows/dogfood-gate.yml index 925af4c1..70275ba8 100644 --- a/.github/workflows/dogfood-gate.yml +++ b/.github/workflows/dogfood-gate.yml @@ -1,11 +1,11 @@ # This workflow is managed by gh actions-lock. # SPDX-License-Identifier: MPL-2.0 -# This workflow is managed by gh actions-lock. # 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. +# Companion to static-analysis-gate.yml (security) and fork-governance.yml (PR +# DEED/K9/Hypatia lanes + unified grid comment). name: Dogfood Gate on: @@ -22,111 +22,199 @@ permissions: jobs: # --------------------------------------------------------------------------- - # Job 1: DEED manifest validation + # Job 1: DEED conformance on push (pull_request runs in fork-governance.yml + # per metadatastician/standards 3-practice/fork-governance/ADOPTION.adoc §3). # --------------------------------------------------------------------------- deed-validate: name: Validate DEED manifests - runs-on: ubuntu-latest - timeout-minutes: 15 - + if: github.event_name != 'pull_request' + runs-on: ubuntu-24.04 + timeout-minutes: 10 + permissions: + contents: read steps: - name: Checkout repository - uses: actions/checkout@v7.0.1 - - - name: Check for manifest files (.a2ml/.deed) - id: detect - run: | - COUNT=$(find . \( -name '*.a2ml' -o -name '*.deed' \) -not -path './.git/*' | wc -l) - echo "count=$COUNT" >> "$GITHUB_OUTPUT" - if [ "$COUNT" -eq 0 ]; then - echo "::warning::No .a2ml/.deed manifest files found. Every RSR repo should have a repo deed (_chora.deed); legacy 0-AI-MANIFEST.a2ml accepted mid-migration — standards #837" - fi - - - name: Validate DEED manifests - if: steps.detect.outputs.count > 0 - uses: hyperpolymath/deed-ecosystem/validate-action@main + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: - path: '.' - strict: 'false' - - - name: Write summary + persist-credentials: false + - name: Checkout canonical DEED validator + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + repository: metadatastician/standards + ref: 8e48b1caade08a552646adeab66558ac43b4360d + path: .standards-deed + sparse-checkout: 1-formats/deed + sparse-checkout-cone-mode: true + persist-credentials: false + - name: Setup Bun runtime + uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 + with: + bun-version: '1.3.12' + - name: Run DEED validation hook run: | - MANIFEST_COUNT="${{ steps.detect.outputs.count }}" - if [ "$MANIFEST_COUNT" -eq 0 ]; then - cat <<'EOF' >> "$GITHUB_STEP_SUMMARY" - ## DEED Manifest Validation - - :warning: **No .a2ml/.deed manifest files found.** Every RSR-compliant repo should have a repo deed (`_chora.deed`) at its root. - - Copy it from [rsr-template-repo](https://github.com/hyperpolymath/rsr-template-repo). Manifests are validated against the DEED grammar (standards `1-formats/deed/`); the `.a2ml` → `.deed` extension migration is tracked in standards #837 — the deed validator scans both. - EOF - else - echo "## DEED Manifest Validation" >> "$GITHUB_STEP_SUMMARY" - echo "" >> "$GITHUB_STEP_SUMMARY" - echo "Scanned **${MANIFEST_COUNT}** .a2ml/.deed manifest(s). See step output for details." >> "$GITHUB_STEP_SUMMARY" - fi + set -euo pipefail + rm -rf "$RUNNER_TEMP/standards-deed" + mv "$PWD/.standards-deed" "$RUNNER_TEMP/standards-deed" + STANDARDS_DIR="$RUNNER_TEMP/standards-deed" bash .github/hooks/validate-deed.sh # --------------------------------------------------------------------------- - # Job 2: K9 contract validation + # Job 2: K9 conformance on push (pull_request runs in fork-governance.yml). # --------------------------------------------------------------------------- k9-validate: name: Validate K9 contracts - runs-on: ubuntu-latest + if: github.event_name != 'pull_request' + runs-on: ubuntu-24.04 timeout-minutes: 15 - + permissions: + contents: read + env: + NICKEL_VERSION: '1.18.0' + NICKEL_SHA256: '9cba4dd65ae9915ec61f73033aafcff307a377665a83fd8f530df086763318cb' steps: - name: Checkout repository - uses: actions/checkout@v7.0.1 - - - name: Check for K9 files - id: detect + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - name: Checkout canonical K9 validator + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + repository: metadatastician/standards + ref: 8e48b1caade08a552646adeab66558ac43b4360d + path: .standards-k9 + sparse-checkout: 1-formats/k9 + sparse-checkout-cone-mode: true + persist-credentials: false + - name: Install sha256-verified Nickel CLI 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-ecosystem/validate-action@main + set -euo pipefail + URL="https://github.com/tweag/nickel/releases/download/${NICKEL_VERSION}/nickel-x86_64-linux" + curl -sSfL --proto '=https' --proto-redir '=https' --tlsv1.2 --retry 3 -o "$RUNNER_TEMP/nickel" "$URL" + echo "${NICKEL_SHA256} ${RUNNER_TEMP}/nickel" | sha256sum -c - + chmod +x "$RUNNER_TEMP/nickel" + echo "$RUNNER_TEMP" >> "$GITHUB_PATH" + - name: Setup Bun runtime + uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 with: - path: '.' - strict: 'false' + bun-version: '1.3.12' - - name: Write summary + - name: Run K9 validation hook + id: validate + run: | + set -euo pipefail + rm -rf "$RUNNER_TEMP/standards-k9" + mv "$PWD/.standards-k9" "$RUNNER_TEMP/standards-k9" + STANDARDS_DIR="$RUNNER_TEMP/standards-k9" bash .github/hooks/validate-k9.sh + + # The state -> badge mapping lives in scripts/governance-badge.js and + # nowhere else. It used to be this inline jq, which wrote `skipped` and + # `cancelled` in RED. The renderer is shared with the publisher, so the + # artifact and the published badge cannot drift apart. + - name: Generate K9 badge + if: always() + env: + K9_RESULT: ${{ steps.validate.outcome }} 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 + set -euo pipefail + mkdir -p "$RUNNER_TEMP/k9-grid" + bun scripts/governance-badge.js render \ + --label K9 \ + --state "${K9_RESULT:-unknown}" \ + --out "$RUNNER_TEMP/k9-grid/badge.json" + cat "$RUNNER_TEMP/k9-grid/badge.json" + + - name: Upload K9 grid + if: always() + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + with: + name: k9-grid + path: ${{ runner.temp }}/k9-grid/badge.json + if-no-files-found: error - :warning: **No K9 contract files found.** Run `k9iser` to generate contracts. + # The live README badge: badges/k9.json (shields endpoint schema) published to + # the generated `governance-badges` ORPHAN branch on every push to main. + # + # Operational contract (the long form is in .github/workflows/README.adoc): + # * the branch is generated output - no common ancestor with main, no PR, + # never merged. That is why the branch is built with `parents: []` and + # never with main's head; + # * identical bytes produce NO commit; + # * only a `success` lane result may render brightgreen; + # * skipped, cancelled, unavailable and unrecognised states render + # lightgrey. Running with a skipped lane PUBLISHES grey; it must never + # leave a previous green badge in place, which is why this job no longer + # excludes `needs.k9-validate.result == 'skipped'`. + # + # scripts/governance-badge.js owns the whole decision, so it can be unit + # tested without a repository, a token or a network. + badges: + name: Publish the lane badges + needs: k9-validate + if: always() && github.event_name == 'push' && github.ref == 'refs/heads/main' + runs-on: ubuntu-24.04 + timeout-minutes: 5 + permissions: + contents: write + # One publisher at a time per repository. The contents API is ALSO + # sha-checked, so a race that slips past the queue is detected (409) and + # re-evaluated against what the other run wrote instead of blindly + # overwriting it. + concurrency: + group: governance-badges-${{ github.repository }} + cancel-in-progress: false + steps: + - name: Checkout repository + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false - 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 + - name: Setup Bun runtime + uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 + with: + bun-version: '1.3.12' + + # Deliberately non-fatal: a missing artifact IS a lane state ("we have no + # evidence"), and failing here would leave the previous badge - possibly + # a green one - in place. The publisher turns it into a grey + # "unavailable" badge and then fails the step, so the run is still red + # and the badge still stops claiming success. + - name: Download the lane grid + continue-on-error: true + uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2 + with: + name: k9-grid + path: ${{ runner.temp }}/k9-grid + + - name: Publish badges/k9.json to the governance-badges branch + env: + GITHUB_TOKEN: ${{ github.token }} + LANE_RESULT: ${{ needs.k9-validate.result }} + ARTIFACT: ${{ runner.temp }}/k9-grid/badge.json + BRANCH: governance-badges + DEST: badges/k9.json + SOURCE_SHA: ${{ github.sha }} + run: | + set -euo pipefail + bun scripts/governance-badge.js publish \ + --label K9 \ + --lane-result "$LANE_RESULT" \ + --artifact "$ARTIFACT" \ + --branch "$BRANCH" \ + --path "$DEST" \ + --repo "$GITHUB_REPOSITORY" \ + --source-sha "$SOURCE_SHA" # --------------------------------------------------------------------------- # Job 3: Empty-linter — invisible character detection # --------------------------------------------------------------------------- empty-lint: name: "🔴 GATE: Empty-linter (invisible characters)" - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 timeout-minutes: 15 - steps: - name: Checkout repository - uses: actions/checkout@v7.0.1 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false - name: Scan for invisible characters id: lint @@ -173,10 +261,12 @@ jobs: fi - name: Write summary + env: + READY: ${{ steps.lint.outputs.ready }} + FINDINGS: ${{ steps.lint.outputs.findings }} run: | - if [ "${{ steps.lint.outputs.ready }}" = "true" ]; then - FINDINGS="${{ steps.lint.outputs.findings }}" - if [ "$FINDINGS" -gt 0 ] 2>/dev/null; then + if [ "$READY" = "true" ]; then + if [ "${FINDINGS:-0}" -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" @@ -196,23 +286,20 @@ jobs: # --------------------------------------------------------------------------- groove-check: name: "🟡 CHECK: Groove manifest check" - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 timeout-minutes: 15 - steps: - name: Checkout repository - uses: actions/checkout@v7.0.1 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false - name: Check for Groove manifest id: groove run: | - # Check for static or dynamic Groove endpoints HAS_MANIFEST="false" HAS_GROOVE_CODE="false" - # Canonical manifest location is www/.well-known/groove/ (issue #53); - # the repository-root path is accepted, with a warning, during the - # migration window. MANIFEST="" if [ -f "www/.well-known/groove/manifest.json" ]; then MANIFEST="www/.well-known/groove/manifest.json" @@ -223,12 +310,7 @@ jobs: if [ -n "$MANIFEST" ]; then HAS_MANIFEST="true" - # Validate the manifest JSON if ! jq empty "$MANIFEST" 2>/dev/null; then - # Gate, don't annotate: an unparseable manifest is a real error, - # not a warning — same behaviour as the standalone - # groove-check.yml (this job had drifted to annotation-only, - # the class of "check that cannot fail" from nexia-list#49). echo "::error file=$MANIFEST::Invalid JSON in Groove manifest" exit 1 else @@ -237,18 +319,10 @@ jobs: 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 in production. Key on - # production HTTP-server framework markers only. A bare `TcpListener` - # is deliberately NOT a signal: it is dominated by test/utility use - # (e.g. a #[cfg(test)] loopback fake), so matching it produced a - # spurious groove nudge on client-only apps. A real hand-rolled Rust - # server still pairs the listener with `axum::serve`/`hyper::Server`, - # which are matched here. HAS_SERVER="false" if grep -rl 'Bandit\|Plug.Cowboy\|httpz\|vweb\|axum::serve\|actix_web\|hyper::Server\|rocket::build\|warp::serve' --include='*.rs' --include='*.ex' --include='*.zig' --include='*.v' . 2>/dev/null | head -1 | grep -q .; then HAS_SERVER="true" @@ -263,32 +337,38 @@ jobs: fi - name: Write summary + env: + HAS_MANIFEST: ${{ steps.groove.outputs.has_manifest }} + HAS_GROOVE_CODE: ${{ steps.groove.outputs.has_groove_code }} + HAS_SERVER: ${{ steps.groove.outputs.has_server }} 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 (www/.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" + { + echo "## Groove Protocol Check" + echo "" + echo "| Check | Status |" + echo "|-------|--------|" + echo "| Static manifest (www/.well-known/groove/manifest.json) | ${HAS_MANIFEST} |" + echo "| Groove endpoint in code | ${HAS_GROOVE_CODE} |" + echo "| Has HTTP server code | ${HAS_SERVER} |" + } >> "$GITHUB_STEP_SUMMARY" # --------------------------------------------------------------------------- # Job 5: eclexiaiser manifest validation # --------------------------------------------------------------------------- eclexiaiser-validate: name: Validate eclexiaiser manifest - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 timeout-minutes: 15 - steps: - name: Checkout repository - uses: actions/checkout@v7.0.1 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false - 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 @@ -297,9 +377,6 @@ jobs: fi echo "has_manifest=true" >> "$GITHUB_OUTPUT" - - # Validate eclexiaiser.toml structure (bash + grep; NO Python per estate policy). - # Structural presence checks only — deep schema validation is eclexiaiser's own job. err=0 grep -qE '^[[:space:]]*\[project\]' eclexiaiser.toml || { echo "::error file=eclexiaiser.toml::[project] section is required"; err=1; } grep -qE '^[[:space:]]*name[[:space:]]*=[[:space:]]*"[^"]+"' eclexiaiser.toml || { echo "::error file=eclexiaiser.toml::a non-empty name is required"; err=1; } @@ -311,8 +388,10 @@ jobs: echo "Valid: eclexiaiser.toml structure present (${fns} function block(s))" - name: Write summary + env: + HAS_MANIFEST: ${{ steps.eclex.outputs.has_manifest }} run: | - if [ "${{ steps.eclex.outputs.has_manifest }}" = "true" ]; then + if [ "$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" @@ -324,24 +403,10 @@ jobs: # --------------------------------------------------------------------------- # Job 6: Canon lockstep — does this template still implement the canon? - # - # The canon<->spine binding. hyperpolymath/standards publishes canon.lock: the - # released identity of the law, with a sha256 per law artefact. This repo - # declares the SAME hashes in .machine_readable/rsr-profile.a2ml [canon]. - # - # Before this job, the declaration was two free-text strings - # (`spec = "rsr-criteria-v2"`, `declares-against = "2.0.0-draft"`) and nothing - # failed when the canon changed. This makes it a comparison. - # - # Deliberately a bare `run:` step with NO `uses:`. Adding an action reference - # would have required an actions.lock row, and this repo's lock records - # FLOATING refs ('actions/checkout@v7.0.1') where the canon's records SHAs - - # so a pinned `uses:` here would mismatch the lock and fail at LOAD time with - # `jobs=0` and no annotation. Read-only over the public internet needs no auth. # --------------------------------------------------------------------------- canon-lockstep: name: Canon lockstep - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 timeout-minutes: 5 permissions: contents: read @@ -351,25 +416,11 @@ jobs: run: | set -euo pipefail LOCK="$RUNNER_TEMP/canon.lock" - URL="https://raw.githubusercontent.com/hyperpolymath/standards/main/canon.lock" + URL="https://raw.githubusercontent.com/metadatastician/standards/main/canon.lock" if ! curl -fsSL --retry 3 --max-time 30 "$URL" -o "$LOCK"; then echo "::error::could not fetch canon.lock from $URL" - echo "The canon does not publish a released identity, so this repo" - echo "cannot be shown to implement it. Fix at source: add canon.lock." exit 1 fi - # Read (not compute) the criteria hash canon.lock asserts. - # - # awk only JOINS the record — the artefact entries are inline tables - # that span lines — then grep -oE extracts the hash. Deliberately the - # same two-step the canon's own check-canon-lockstep.sh uses, so - # there is one technique across both repos. - # - # Two traps this avoids, both found by running it rather than reading - # it. (1) An earlier version used `gsub(/.*"|"/,"",s)` to strip the - # quotes; the `.*"` is GREEDY, so it ate the entire string and the - # hash came out EMPTY. (2) awk interval expressions are not portable - # across mawk/gawk builds; grep -oE is. rec="$(awk ' /^[[:space:]]*#/ { next } /^criteria[[:space:]]*=/ { on=1 } @@ -382,8 +433,7 @@ jobs: | grep -oE 'sha256[[:space:]]*=[[:space:]]*"[0-9a-f]{64}"' \ | grep -oE '[0-9a-f]{64}' | head -1)" if [ -z "$want" ]; then - echo "::error::canon.lock carries no criteria sha256 — malformed, or" - echo "the criteria record no longer starts a line with 'criteria ='." + echo "::error::canon.lock carries no criteria sha256" exit 1 fi echo "want=$want" >> "$GITHUB_OUTPUT" @@ -391,48 +441,33 @@ jobs: - name: Compare this repo's declared pin env: WANT: ${{ steps.canon.outputs.want }} - # This job has NO `uses:` steps, deliberately: any added action would - # have to be pinned in actions.lock, and `uses ⊆ actions.lock` is already - # failing on main, so this job must not make it worse. That means no - # actions/checkout — and therefore NO WORKING TREE. Which is what - # broke this job: it read "machine-readable/rsr-profile.a2ml" from a - # directory that was never populated, so it failed 100% of the time - # with "no rsr-profile.a2ml", and would have whatever the pin said. - # - # Fetch the profile by SHA instead, exactly as canon.lock is fetched - # above. Deliberately NOT github.sha: on pull_request that is the - # ephemeral MERGE commit, which is not on the remote and would 404. - # The event's head sha is the commit that actually exists there. HEAD_SHA: ${{ github.event.pull_request.head.sha || github.sha }} + REPO: ${{ github.repository }} + TOKEN: ${{ github.token }} run: | set -euo pipefail - PROFILE="$RUNNER_TEMP/rsr-profile.a2ml" - fetched="" - for p in ".machine_readable/rsr-profile.a2ml" "machine-readable/rsr-profile.a2ml"; do - URL="https://raw.githubusercontent.com/hyperpolymath/rsr-template-repo/${HEAD_SHA}/${p}" - if curl -fsSL --retry 3 --max-time 30 "$URL" -o "$PROFILE" 2>/dev/null; then - fetched="$p"; break - fi - done - if [ -z "$fetched" ]; then - echo "::error::no rsr-profile.a2ml at ${HEAD_SHA:0:7} — this repo cannot declare a canon pin" - echo "Looked for .machine_readable/rsr-profile.a2ml and machine-readable/rsr-profile.a2ml." + DEED_NAME="${REPO#*/}_chora.deed" + DEED="$RUNNER_TEMP/repo.deed" + API="https://api.github.com/repos/${REPO}/contents/${DEED_NAME}?ref=${HEAD_SHA}" + if ! curl -fsSL --retry 3 --max-time 30 \ + -H "Authorization: Bearer ${TOKEN}" \ + -H "Accept: application/vnd.github.raw" \ + -H "X-GitHub-Api-Version: 2022-11-28" \ + "$API" -o "$DEED"; then + echo "::error::no $DEED_NAME at ${HEAD_SHA:0:7} — this repo cannot declare a canon pin" exit 1 fi - echo "profile: $fetched @ ${HEAD_SHA:0:7}" - - # ALL THREE PINS, BOTH SIDES. - # - # This step used to compare only criteria_sha256, while this repo's own - # rsr-profile.a2ml stated that "these values ... equal canon.lock - # [canon.artifacts]" — plural. The claim was wider than the check, so - # `version` and `gates_sha256` could sit at stale values and nothing - # reported it. They did: canon 2.0.1 changed gates_sha256, and this repo - # kept asserting 2.0.0 and the superseded hash. A pin nothing verifies - # is not a binding. See hyperpolymath/standards docs/AUDIT.adoc F8. - # - # Both readers below are the technique the canon's own - # check-canon-lockstep.sh uses, so there is one idiom across both repos. + echo "deed: $DEED_NAME @ ${HEAD_SHA:0:7}" + + deed_canon() { + _clauses="$(awk 'BEGIN { bs = sprintf("%c", 92); dq = sprintf("%c", 34) } { o = ""; q = 0; for (i = 1; i <= length($0); i++) { c = substr($0, i, 1); if (q && c == bs) { o = o c substr($0, i + 1, 1); i++; continue } if (c == dq) q = !q; else if (!q && c == ";") break; o = o c } printf "%s ", o }' "$2" | grep -oE '[(]canon[[:space:]][^()]*[)]')" || true + _n="$(echo "$_clauses" | grep -c '(canon' || true)" + if [ "$_n" != "1" ]; then + echo "deed_canon: $2 carries ${_n:-0} (canon …) clauses, need exactly 1" >&2 + return 0 + fi + echo "$_clauses" | grep -oE ':'"$1"'[[:space:]]+"[^"]*"' | head -1 | sed -E 's/^[^"]*"//; s/"$//' || true + } canon_key() { awk -v key="$1" ' /^[[:space:]]*#/ { next } @@ -441,9 +476,6 @@ jobs: sub(/^[^=]*=[[:space:]]*/, ""); gsub(/^["[:space:]]+|["[:space:]]+$/, ""); print; exit }' "$2" } - # The artefact records are inline tables spanning lines, so awk JOINS the - # record and grep extracts the hash. Deliberately not anchored to the - # sha256 being on any particular line of the record. artefact_hash() { awk -v key="$1" ' $0 ~ "^" key "[[:space:]]*=" { f = 1 } @@ -455,17 +487,20 @@ jobs: want_crit="$WANT" want_gates="$(artefact_hash gates "$RUNNER_TEMP/canon.lock")" want_ver="$(canon_key version "$RUNNER_TEMP/canon.lock")" - got_crit="$(canon_key criteria_sha256 "$PROFILE")" - got_gates="$(canon_key gates_sha256 "$PROFILE")" - got_ver="$(canon_key version "$PROFILE")" - - # An unreadable pin must not pass. Hashing or parsing nothing yields an - # empty string, and `"" = ""` is a green build with nothing behind it — - # the same class of bug as this job reading a file that was never there. - for pair in "want_crit:$want_crit" "want_gates:$want_gates" "want_ver:$want_ver" \ - "got_crit:$got_crit" "got_gates:$got_gates" "got_ver:$got_ver"; do - if [ -z "${pair#*:}" ]; then - echo "::error::could not read ${pair%%:*} — refusing to compare an empty value" + got_crit="$(deed_canon criteria-sha256 "$DEED")" + got_gates="$(deed_canon gates-sha256 "$DEED")" + got_ver="$(deed_canon version "$DEED")" + + for pair in "want_crit:$want_crit" "want_gates:$want_gates" \ + "got_crit:$got_crit" "got_gates:$got_gates"; do + if ! printf '%s' "${pair#*:}" | grep -qxE '[0-9a-f]{64}'; then + echo "::error::${pair%%:*} is not a sha256 (got '${pair#*:}') — refusing to compare" + exit 1 + fi + done + for pair in "want_ver:$want_ver" "got_ver:$got_ver"; do + if ! printf '%s' "${pair#*:}" | grep -qxE '[0-9]+\.[0-9]+\.[0-9]+'; then + echo "::error::${pair%%:*} is not a semver (got '${pair#*:}') — refusing to compare" exit 1 fi done @@ -479,95 +514,69 @@ jobs: { echo "## Canon lockstep" echo "" - echo "| pin | canon.lock asserts | this repo declares | |" + echo "| pin | canon.lock asserts | \`$DEED_NAME\` declares | |" echo "|---|---|---|---|" row version "$want_ver" "$got_ver" - row criteria_sha256 "$want_crit" "$got_crit" - row gates_sha256 "$want_gates" "$got_gates" + row criteria-sha256 "$want_crit" "$got_crit" + row gates-sha256 "$want_gates" "$got_gates" } >> "$GITHUB_STEP_SUMMARY" + if [ "$ok" = "1" ]; then echo ":white_check_mark: This template implements the canon at HEAD." exit 0 fi echo "::error::canon lockstep broken — the template does not implement the canon at HEAD" - { - echo "" - echo ":x: **Lockstep broken.**" - echo "" - echo "The canon's law changed and this template has not adopted it." - echo "Order matters (\`canon.lock [canon.lockstep].order\` is" - echo "\`spine-adopts-then-canon-releases\`): re-pin \`[canon]\` in" - echo "\`.machine_readable/rsr-profile.a2ml\` to the new hashes and fix any" - echo "criteria this repo now fails, BEFORE the canon release lands." - } >> "$GITHUB_STEP_SUMMARY" exit 1 + # --------------------------------------------------------------------------- # Job 7: Dogfooding summary # --------------------------------------------------------------------------- dogfood-summary: name: "ℹ️ ADVISORY: Dogfooding compliance summary (non-gating)" - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 timeout-minutes: 15 needs: [deed-validate, k9-validate, empty-lint, groove-check, eclexiaiser-validate, canon-lockstep] if: always() - steps: - name: Checkout repository - uses: actions/checkout@v7.0.1 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false - name: Generate dogfooding scorecard run: | SCORE=0 MAX=6 - - # DEED manifest present? (.a2ml legacy extension accepted during standards #837 migration) - if find . \( -name '*.a2ml' -o -name '*.deed' \) -not -path './.git/*' | head -1 | grep -q .; then - SCORE=$((SCORE + 1)) - DEED_STATUS=":white_check_mark:" + if find . -name '*.deed' -not -path './.git/*' | head -1 | grep -q .; then + SCORE=$((SCORE + 1)); DEED_STATUS=":white_check_mark:" else DEED_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:" + 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:" + SCORE=$((SCORE + 1)); EC_STATUS=":white_check_mark:" else EC_STATUS=":x:" fi - - # Groove manifest or code? if [ -f "www/.well-known/groove/manifest.json" ] || [ -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:" + 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:" + 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:" + SCORE=$((SCORE + 1)); ECLEX_STATUS=":white_check_mark:" else ECLEX_STATUS=":ballot_box_with_check:" fi - cat <> "$GITHUB_STEP_SUMMARY" ## Dogfooding Scorecard @@ -575,58 +584,55 @@ jobs: | Tool/Format | Status | Notes | |-------------|--------|-------| - | DEED repo deed (`_chora.deed`) | ${DEED_STATUS} | Required for all RSR repos | + | DEED repo deed (\`_chora.deed\`) | ${DEED_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 rsr-score-self: name: RSR oracle — dogfood this repo - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 + timeout-minutes: 20 steps: - - uses: actions/checkout@v7.0.1 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: + path: subject fetch-depth: 0 - - uses: actions/checkout@v7.0.1 + persist-credentials: false + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: - repository: hyperpolymath/standards + repository: metadatastician/standards + ref: 8e48b1caade08a552646adeab66558ac43b4360d path: _standards - - uses: actions/checkout@v7.0.1 + persist-credentials: false + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: repository: hyperpolymath/hypatia + ref: be98f74ce93df200752f3798efa1305bfa3e0e10 path: _hypatia - - name: Setup Elixir for the oracle - uses: erlef/setup-beam@v1.24.1 + persist-credentials: false + - name: Setup Elixir 1.19.4 / OTP 28.3 for Hypatia oracle + uses: erlef/setup-beam@54075bcc5e249e4758d363f27d099f55d843f124 # v1.24.1 with: elixir-version: '1.19.4' otp-version: '28.3' + - name: Cache Hypatia Mix deps and build + uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 + with: + path: | + _hypatia/deps + _hypatia/_build + ~/.hex + ~/.mix + key: hypatia-oracle-${{ runner.os }}-otp28-elx1194-be98f74ce93df200752f3798efa1305bfa3e0e10 - name: Compile the oracle working-directory: _hypatia - run: mix deps.get && mix compile + run: mix local.hex --force && mix local.rebar --force && mix deps.get && mix compile - name: Score this repo against the canon working-directory: _hypatia run: | - # --ssot is explicit until the hypatia M-3 fix lands (the - # --standards default still points at the pre-reorg path). - mix hypatia.rsr_score .. \ - --ssot ../_standards/0-canon/rsr/rsr-criteria-v2.a2ml \ - --write - - name: Show the scorecard - if: always() - run: | - if [ -f .machine_readable/descriptiles/SCORECARD.a2ml ]; then - cat .machine_readable/descriptiles/SCORECARD.a2ml - else - echo "::warning::no scorecard written — the oracle failed; see the step log" - fi - # Deliberately NO --fail-under: the point is to publish the honest - # scorecard (provisional=true until the coverage worklist is triaged), - # not to gate the spine on itself. Tightens in the PR that lands the - # first coverage tranche. + mix hypatia.rsr_score ../subject \ + --ssot ../_standards/0-canon/rsr/rsr-criteria-v2.a2ml diff --git a/.github/workflows/dogfood-summary.yml b/.github/workflows/dogfood-summary.yml index 2df5c3dd..9ff1f478 100644 --- a/.github/workflows/dogfood-summary.yml +++ b/.github/workflows/dogfood-summary.yml @@ -18,7 +18,7 @@ permissions: jobs: dogfood-summary: name: "Dogfooding compliance summary" - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 timeout-minutes: 15 if: always() @@ -31,8 +31,8 @@ jobs: SCORE=0 MAX=6 - # DEED manifest present? (.a2ml legacy extension accepted during standards #837 migration) - if find . \( -name '*.a2ml' -o -name '*.deed' \) -not -path './.git/*' | head -1 | grep -q .; then + # DEED manifest present? + if find . -name '*.deed' -not -path './.git/*' | head -1 | grep -q .; then SCORE=$((SCORE + 1)) DEED_STATUS=":white_check_mark:" else diff --git a/.github/workflows/dot-wellknown-enforcement.yml b/.github/workflows/dot-wellknown-enforcement.yml index 7ce166ed..0fb8b4a6 100644 --- a/.github/workflows/dot-wellknown-enforcement.yml +++ b/.github/workflows/dot-wellknown-enforcement.yml @@ -27,7 +27,7 @@ permissions: contents: read jobs: validate: - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 timeout-minutes: 15 permissions: contents: read diff --git a/.github/workflows/e2e.yml.template b/.github/workflows/e2e.yml.template index 98424510..92d238d5 100644 --- a/.github/workflows/e2e.yml.template +++ b/.github/workflows/e2e.yml.template @@ -58,7 +58,7 @@ jobs: # repos either extend tests/e2e.sh or uncomment a stack block below. e2e: name: E2E — template smoke - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 timeout-minutes: 15 steps: - name: Checkout @@ -77,7 +77,7 @@ jobs: ## === RUST E2E === # e2e: # name: E2E — Full Pipeline -# runs-on: ubuntu-latest +# runs-on: ubuntu-24.04 # timeout-minutes: 15 # steps: # - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 @@ -90,7 +90,7 @@ jobs: ## === ZIG FFI E2E === # e2e: # name: E2E — FFI Pipeline -# runs-on: ubuntu-latest +# runs-on: ubuntu-24.04 # timeout-minutes: 15 # steps: # - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 @@ -103,7 +103,7 @@ jobs: ## === ELIXIR E2E === # e2e: # name: E2E — Full Pipeline -# runs-on: ubuntu-latest +# runs-on: ubuntu-24.04 # timeout-minutes: 15 # steps: # - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 @@ -114,24 +114,21 @@ jobs: # - run: mix deps.get && mix compile --warnings-as-errors # - run: mix test test/integration/e2e_test.exs --trace -## === DENO/ E2E === +## === BUN E2E === # e2e: # name: E2E — Full Pipeline -# runs-on: ubuntu-latest +# runs-on: ubuntu-24.04 # 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/ +# - uses: oven-sh/setup-bun@v2.2.0 # resolved by actions.lock +# - run: bun install --frozen-lockfile +# - run: bun test tests/e2e/ ## === PLAYWRIGHT (Browser E2E) === # e2e-playwright: # name: Playwright — ${{ matrix.project }} -# runs-on: ubuntu-latest +# runs-on: ubuntu-24.04 # timeout-minutes: 20 # strategy: # fail-fast: false @@ -139,12 +136,10 @@ jobs: # 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: oven-sh/setup-bun@v2.2.0 # resolved by actions.lock +# - run: bun install --frozen-lockfile +# - run: bunx playwright install --with-deps +# - run: bunx playwright test --project=${{ matrix.project }} # - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 # if: failure() # with: @@ -155,7 +150,7 @@ jobs: ## === HASKELL E2E === # e2e: # name: E2E — Full Pipeline -# runs-on: ubuntu-latest +# runs-on: ubuntu-24.04 # timeout-minutes: 15 # steps: # - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 @@ -172,7 +167,7 @@ jobs: # aspect-tests: # name: Aspect — Architectural Invariants -# runs-on: ubuntu-latest +# runs-on: ubuntu-24.04 # timeout-minutes: 10 # steps: # - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 @@ -184,7 +179,7 @@ jobs: ## === RUST BENCH === # benchmarks: # name: Bench — Performance Regression -# runs-on: ubuntu-latest +# runs-on: ubuntu-24.04 # timeout-minutes: 15 # steps: # - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 @@ -201,7 +196,7 @@ jobs: ## === ZIG BENCH === # benchmarks: # name: Bench — Performance Regression -# runs-on: ubuntu-latest +# runs-on: ubuntu-24.04 # timeout-minutes: 15 # steps: # - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 @@ -215,7 +210,7 @@ jobs: # readiness: # name: Readiness — Grade D/C/B -# runs-on: ubuntu-latest +# runs-on: ubuntu-24.04 # timeout-minutes: 10 # steps: # - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 diff --git a/.github/workflows/eclexiaiser-validate.yml b/.github/workflows/eclexiaiser-validate.yml index aae74816..e0e5e250 100644 --- a/.github/workflows/eclexiaiser-validate.yml +++ b/.github/workflows/eclexiaiser-validate.yml @@ -18,12 +18,14 @@ permissions: jobs: eclexiaiser-validate: name: "🟡 CHECK: Validate eclexiaiser manifest" - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 timeout-minutes: 15 steps: - name: Checkout repository uses: actions/checkout@v7.0.1 + with: + persist-credentials: false - name: Check and validate eclexiaiser manifest id: eclex @@ -52,8 +54,10 @@ jobs: echo "Valid: eclexiaiser.toml structure present (${fns} function block(s))" - name: "Write summary" + env: + HAS_MANIFEST: ${{ steps.eclex.outputs.has_manifest }} run: | - if [ "${{ steps.eclex.outputs.has_manifest }}" = "true" ]; then + if [ "$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" diff --git a/.github/workflows/empty-linter.yml b/.github/workflows/empty-linter.yml index 7bdf2371..dcb890dc 100644 --- a/.github/workflows/empty-linter.yml +++ b/.github/workflows/empty-linter.yml @@ -18,12 +18,14 @@ permissions: jobs: empty-lint: name: "🔴 GATE: Empty-linter (invisible characters)" - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 timeout-minutes: 15 steps: - name: Checkout repository uses: actions/checkout@v7.0.1 + with: + persist-credentials: false - name: Scan for invisible characters id: lint @@ -70,10 +72,12 @@ jobs: fi - name: "Write summary" + env: + READY: ${{ steps.lint.outputs.ready }} + FINDINGS: ${{ steps.lint.outputs.findings }} run: | - if [ "${{ steps.lint.outputs.ready }}" = "true" ]; then - FINDINGS="${{ steps.lint.outputs.findings }}" - if [ "$FINDINGS" -gt 0 ] 2>/dev/null; then + if [ "$READY" = "true" ]; then + if [ "${FINDINGS:-0}" -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" diff --git a/.github/workflows/estate-rules.yml b/.github/workflows/estate-rules.yml index 9dd2741e..a25eaf41 100644 --- a/.github/workflows/estate-rules.yml +++ b/.github/workflows/estate-rules.yml @@ -23,11 +23,13 @@ permissions: contents: read jobs: estate-rules: - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 timeout-minutes: 15 steps: - name: Checkout - uses: actions/checkout@v7.0.1 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false # Prove the instrument works before trusting its reading. This gate was # one-directional for months, which is indistinguishable from a working # gate until you try to make it fail. @@ -66,6 +68,13 @@ jobs: # Was written but wired to nothing, so it had never run in CI. - name: V-language gate self-test run: bash tests/workflows/check_no_vlang_test.sh + # .a2ml is retired estate-wide: facts are deed clauses, contracts are .k9. + - name: No .a2ml files + run: bash scripts/check-no-a2ml.sh . + - name: No-a2ml gate self-test (planted positives must fail) + run: bash tests/workflows/check_no_a2ml_test.sh + - name: Deed clause writer controls + run: bash tests/workflows/deed_clause_test.sh - name: Install verified Nickel 1.17.0 run: | mkdir -p "$RUNNER_TEMP/nickel-bin" @@ -83,3 +92,178 @@ jobs: run: bash tests/workflows/session_contracts_test.sh - name: Verify mint cleanup controls run: bash tests/workflows/mint_cleanup_test.sh + - name: Self-name pass keeps issue references, provenance and detectors + run: bash tests/workflows/self_name_pass_test.sh + # The automated mint path (RSR_NON_INTERACTIVE) never completed, and no + # workflow exercised repo-init at all: tests/e2e runs nowhere in CI. + - name: Install verified just 1.43.0 + run: | + mkdir -p "$RUNNER_TEMP/just-bin" + curl --proto '=https' --proto-redir '=https' --fail --silent --show-error --location \ + https://github.com/casey/just/releases/download/1.43.0/just-1.43.0-x86_64-unknown-linux-musl.tar.gz \ + --output "$RUNNER_TEMP/just.tgz" + echo "a1bc93654f31669fd964ea3011a5e5e9676b9b6f8adcd762606e5140632ea72d $RUNNER_TEMP/just.tgz" | sha256sum --check --strict + tar -xzf "$RUNNER_TEMP/just.tgz" -C "$RUNNER_TEMP/just-bin" just + echo "$RUNNER_TEMP/just-bin" >> "$GITHUB_PATH" + - name: Non-interactive mint resolves every prompt from the environment + run: bash tests/workflows/non_interactive_mint_test.sh + # repo-init recorded the CHILD's own HEAD as the template commit whenever + # a repo was created with "Use this template" (metadatastician/lintel). + - name: Template pin resolves by tree equality (controls) + run: bash tests/workflows/resolve_template_pin_test.sh + # The first CI job to run a FULL mint: a Use-this-template child, checked + # for provenance, untouched fixtures and ignored files, the map and the + # closing advice. A fresh mint of main aborted on 2026-10-20 and nothing + # here noticed. uuidgen is util-linux; installed only if the image lacks it. + - name: Use-this-template mint end to end + run: | + command -v uuidgen >/dev/null || { sudo apt-get update -q && sudo apt-get install -y -q uuid-runtime; } + bash tests/e2e/use_template_mint_test.sh + # An archetype overlay once shipped its own actions.lock, which replaced + # the spine's at mint and left every Julia mint with Lock Sync red. + - name: Archetype lock fragments merge into a valid lock + run: bash tests/workflows/archetype_lock_merge_test.sh + # The CHECK half of the template contract. repo-init has always written an + # answer-file (now the child deed's (provenance) clause); nothing ever read it. + # This is the missing reader, and it covers the #200/#201/#203 class: + # self-parenting identity, unresolved pins, and leaked template branches. + # + # The template itself self-skips (archetypes/ present), so the real check + # runs in minted children. What THIS proves is that the instrument can + # fail — the only property that matters for a gate, and the one that was + # missing in #49, #64 and the conformance gate that "reported them + # conforming" upstream. + - name: Template conformance gate self-test (must fail on drift) + run: bash tests/workflows/template_conformance_test.sh + # runtime-policy.yml folded into governance (#244). Both validators must + # require governance.yml, and a retired gate's name must not stand in. + - name: Validators require governance in place of the runtime gate + run: bash tests/workflows/runtime_policy_fold_test.sh + # Bun is the estate's first-choice runtime; the governance test below + # parses the workflow and its lock with Bun.YAML. Pinned and verified, + # as the other tools here are. + - name: Install verified Bun 1.4.2 + run: | + curl --proto '=https' --proto-redir '=https' --fail --silent --show-error --location \ + https://github.com/oven-sh/bun/releases/download/bun-v1.4.2/bun-linux-x64.zip \ + --output "$RUNNER_TEMP/bun.zip" + echo "36368faef7527875d5ffa52e53cd48021741f2a83eb6208a8dd64068d422a913 $RUNNER_TEMP/bun.zip" | sha256sum --check --strict + unzip -q "$RUNNER_TEMP/bun.zip" -d "$RUNNER_TEMP" + echo "$RUNNER_TEMP/bun-linux-x64" >> "$GITHUB_PATH" + # The runtime gate stays retired, governance runs for pull requests to + # any branch, and it calls the standards reusable at the commit its lock + # records. + - name: Governance replaces the runtime gate for every pull request + run: bash tests/workflows/governance_policy_test.sh + # The README badge is generated output on an orphan branch. This proves + # the state -> colour table (grey, never a stale green), the byte-equal + # no-op, the orphan commit, the API-error classification and the workflow + # wiring - against a mock API, so no experiment is pushed to any branch. + # Behaviour tests run under the same Bun the step above installed, with a + # Node fallback; the wiring checks also run against a mutated workflow so + # they are proven able to fail. + - name: Governance badge contract (state mapping, no-op, orphan, errors) + run: bash tests/workflows/governance_badge_test.sh + # KYAML ratchet (standards YAML-POLICY §3.4, §5 step 5, standards#1024): + # every file listed here has been converted and must stay KYAML. A file + # joins the list in the PR that converts it and never leaves it. The + # formatter is standards' own kyaml-format.sh at a pinned commit, the one + # rewriter the step-2 comment-preservation proof covers, so this repo + # carries no copy that can drift. yq is pinned too: kyaml-format.sh exits + # 2 (red) on a yq that cannot write KYAML, never green. Workflows wait for + # step 6 (standards#1025); files a third-party bot or tool rewrites or + # finds by schema (Dependabot, FUNDING, issue forms, settings, CodeRabbit, + # Copilot, GitLab CI, pre-commit) are not listed, as in standards. + - name: Install verified yq 4.53.3 and kyaml-format.sh (standards 8e48b1c) + run: | + mkdir -p "$RUNNER_TEMP/yq-bin" + curl --proto '=https' --proto-redir '=https' --fail --silent --show-error --location \ + https://github.com/mikefarah/yq/releases/download/v4.53.3/yq_linux_amd64 \ + --output "$RUNNER_TEMP/yq-bin/yq" + echo "fa52a4e758c63d38299163fbdd1edfb4c4963247918bf9c1c5d31d84789eded4 $RUNNER_TEMP/yq-bin/yq" | sha256sum --check --strict + chmod +x "$RUNNER_TEMP/yq-bin/yq" + echo "$RUNNER_TEMP/yq-bin" >> "$GITHUB_PATH" + curl --proto '=https' --proto-redir '=https' --fail --silent --show-error --location \ + https://raw.githubusercontent.com/metadatastician/standards/8e48b1caade08a552646adeab66558ac43b4360d/scripts/kyaml-format.sh \ + --output "$RUNNER_TEMP/kyaml-format.sh" + echo "5fddd58fc8cbd2b68766ef5b4b5ba39f299da3f27252ae6cdcff0a641bbaef18 $RUNNER_TEMP/kyaml-format.sh" | sha256sum --check --strict + # Container narrowing at mint (build/just/container.just) can delete any + # of these files. The template (archetypes/ present) must keep all of + # them; a minted repository checks the ones it kept and names the rest. + - name: Converted YAML stays KYAML + run: | + set -euo pipefail + converted=( + build/container/compose.yaml + build/container/compose.example.yaml + build/container/stapeln/.gatekeeper.yaml + ) + present=() + for file in "${converted[@]}"; do + if [ -f "$file" ]; then + present+=("$file") + elif [ -d archetypes ]; then + echo "::error::$file is missing from the template" + exit 1 + else + echo "::notice::$file was removed at mint by container narrowing; not checked" + fi + done + if [ "${#present[@]}" -eq 0 ]; then + echo "No converted YAML is left in this repository; nothing to check." + exit 0 + fi + bash "$RUNNER_TEMP/kyaml-format.sh" --check "${present[@]}" + - name: Estate composite actions stay KYAML + run: | + set -euo pipefail + if [ -f .github/actions/squabble/action.yml ]; then + bash "$RUNNER_TEMP/kyaml-format.sh" --check .github/actions/squabble/action.yml + if [ -f scripts/kyaml-format.sh ]; then + bash scripts/kyaml-format.sh --check .github/actions/squabble/action.yml + fi + fi + - name: Converted container configs keep their data (template only) + run: bash tests/workflows/container_kyaml_test.sh + - name: KYAML ratchet self-test (installs verify, gate propagates, narrowing) + run: bash tests/workflows/kyaml_ratchet_test.sh + - name: I-JSON (RFC 7493) + JCS (RFC 8785) canonical gate & self-test + run: | + set -euo pipefail + bash tests/workflows/check_ijson_jcs_test.sh + bash scripts/check-ijson-jcs.sh --enforce . + # ── The scanner/reporting pipeline's own rules ──────────────────────── + # docs/HYPATIA-RULE-ORDER.adoc states the exemption layers, the clashes + # between them and what resolves each. These four steps are the parts of + # that document a machine can check; the rest is stated there as review. + - name: Hypatia exemption meta-rules (.hypatia-ignore) + run: | + set -euo pipefail + bash tests/workflows/hypatia_ignore_test.sh + bash scripts/check-hypatia-ignore.sh . + # The layer order, the ownership table and the clash resolutions are a + # contract (.machine_readable/policies/hypatia-rule-order.json), not a + # description: this step refuses a duplicate or gapped rank, an owner that + # does not exist, an unclassified exemption, and any pin that disagrees + # with the workflow that uses it. The suite proves each refusal fires. + - name: Hypatia rule order & clash resolution + run: | + set -euo pipefail + bash tests/workflows/hypatia_rule_order_test.sh + bash scripts/check-hypatia-rule-order.sh . + - name: Workflow edges (producer -> verdict grid) resolve + run: | + set -euo pipefail + bash tests/workflows/workflow_edges_test.sh + bash scripts/check-workflow-edges.sh . + # The grid itself is rendered by the pinned standards renderer, which the + # tests stub: this proves the lane's evidence collection, digest refusal, + # orange-not-green fallback and one-comment-per-PR behaviour, and that the + # workflow wiring is what the checks expect (mutated copies included). + - name: Verdict grid lane (collect, verify, render, comment) + run: bash tests/workflows/verdict_grid_test.sh + - name: Required status contexts & squabble anti-bypass gate + run: | + set -euo pipefail + bash tests/workflows/squabble_gate_test.sh + bash scripts/check-required-contexts.sh . diff --git a/.github/workflows/fork-governance.yml b/.github/workflows/fork-governance.yml new file mode 100644 index 00000000..f00165dc --- /dev/null +++ b/.github/workflows/fork-governance.yml @@ -0,0 +1,465 @@ +# This workflow is managed by gh actions-lock. +# SPDX-License-Identifier: MPL-2.0 +# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# fork-governance.yml — PR-time entry point for DEED syntax, K9-DEED L0–L2 +# conformance, the gitbot-fleet report-backs, and THE Hypatia verdict grid. +# Everything is pinned to metadatastician/standards@8e48b1caade08a552646adeab66558ac43b4360d. +# +# ── HOW THIS FILE RELATES TO THE SCANNERS (read before editing) ────────────── +# +# The estate used to run scanners in three places with no statement of which +# one owned what, so the same Hypatia binary was built twice per pull request, +# two different jobs gated on "critical", and the verdict grid this file claimed +# to feed was produced nowhere. The layering is now explicitly: +# +# 1. PRODUCERS — each scanner runs in exactly one workflow: +# .github/workflows/hypatia-scan.yml -> artifact `hypatia-scan-findings` +# (Hypatia JSON, relativised; +# SARIF `category: hypatia`) +# .github/workflows/static-analysis-gate.yml -> artifact `static-analysis-findings` +# (panic-attack and pons status +# envelopes, patch bridge, unified) +# A producer states its own gate. Hypatia gates on critical; panic-attack +# gates on critical; pons is advisory. No other workflow repeats those +# decisions: this file never fails on a finding, so a pull request cannot be +# blocked twice for one finding, and no gate is suppressed here either — +# the producer's own check still goes red. +# +# 2. REPORTER — this workflow. It does not scan anything. It collects the +# producers' artifacts for one commit, renders the findings-family verdict +# grid (metadatastician/standards docs/VERDICT-GRID-SPEC.adoc) over Hypatia, +# panic-attack, pons and every enrolled gitbot-fleet member, uploads it as +# `verdict-grid`, and writes a job summary with read-only permissions. +# +# 3. SEQUENCING — this workflow runs on `pull_request` and `workflow_dispatch`. +# A pull-request run may render an orange row for a scanner that has not +# reported yet (orange, never green). verdict-grid-publish.yml runs on +# `workflow_run` when a producer finishes, re-renders with a trusted +# default-branch lane script, and maintains one comment per pull request. +# +# Two deliberate non-decisions: +# +# * A failing `fleet` job does NOT fail the verdict. Its rows go orange (no +# report-back evidence) and the `Fleet report-backs` check goes red, which is +# where a fleet failure is visible. Failing the verdict as well would report +# one failure twice and would block a pull request on infrastructure rather +# than on evidence about the pull request. The previous wiring reported the +# fleet result in a table and then ignored it; this comment is the statement +# that replaces that silence. +# * The grid is not a gate. Its state is published (job summary, artifact, +# comment) and the gating decisions stay with the producers. The spec's +# §Non-goals makes the same point: a grid is worst-of reporting, not a score. +name: Fork governance + +on: + pull_request: + workflow_dispatch: + +concurrency: + # Group by workflow and github.ref, keeping each pull request's runs separate. + group: ${{ github.workflow }}-${{ github.ref }} + # The newer run re-collects the producers' artifacts for this ref. + cancel-in-progress: true + +permissions: + contents: read + +env: + # The merge revision scanned by the fleet and producers, or the dispatch commit. + TARGET_SHA: ${{ github.sha }} + # Actions run discovery filters by the PR head rather than the merge revision. + PR_HEAD_SHA: ${{ github.event.pull_request.head.sha || github.sha }} + # A manual dispatch has no pull request; its grid stays in the summary/artifact. + TARGET_PR: ${{ github.event.pull_request.number || '' }} + +jobs: + deed: + name: DEED syntax + runs-on: ubuntu-24.04 + timeout-minutes: 10 + permissions: + contents: read + steps: + - name: Checkout repository + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - name: Checkout canonical DEED validator + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + repository: metadatastician/standards + ref: 8e48b1caade08a552646adeab66558ac43b4360d + path: .standards-deed + sparse-checkout: 1-formats/deed + sparse-checkout-cone-mode: true + persist-credentials: false + + - name: Setup Bun runtime + uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 + with: + bun-version: '1.3.12' + + - name: Validate DEED manifests and block retired .a2ml files + run: | + set -euo pipefail + STANDARDS_ABS="$PWD/.standards-deed" + rm -rf "$RUNNER_TEMP/standards-deed" + mv "$STANDARDS_ABS" "$RUNNER_TEMP/standards-deed" + STANDARDS_DIR="$RUNNER_TEMP/standards-deed" bash .github/hooks/validate-deed.sh + + k9: + name: K9-DEED conformance + runs-on: ubuntu-24.04 + timeout-minutes: 15 + permissions: + contents: read + env: + NICKEL_VERSION: '1.18.0' + NICKEL_SHA256: '9cba4dd65ae9915ec61f73033aafcff307a377665a83fd8f530df086763318cb' + steps: + - name: Checkout repository + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - name: Checkout canonical K9 validator and contract + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + repository: metadatastician/standards + ref: 8e48b1caade08a552646adeab66558ac43b4360d + path: .standards-k9 + sparse-checkout: 1-formats/k9 + sparse-checkout-cone-mode: true + persist-credentials: false + + - name: Install sha256-verified Nickel CLI + run: | + set -euo pipefail + URL="https://github.com/tweag/nickel/releases/download/${NICKEL_VERSION}/nickel-x86_64-linux" + curl -sSfL --proto '=https' --proto-redir '=https' --tlsv1.2 --retry 3 -o "$RUNNER_TEMP/nickel" "$URL" + echo "${NICKEL_SHA256} ${RUNNER_TEMP}/nickel" | sha256sum -c - + chmod +x "$RUNNER_TEMP/nickel" + echo "$RUNNER_TEMP" >> "$GITHUB_PATH" + + - name: Validate K9 contracts (L0–L2) + run: | + set -euo pipefail + rm -rf "$RUNNER_TEMP/standards-k9" + mv "$PWD/.standards-k9" "$RUNNER_TEMP/standards-k9" + STANDARDS_DIR="$RUNNER_TEMP/standards-k9" bash .github/hooks/validate-k9.sh + + # Fleet report-backs: the evidence behind each gitbot-fleet row of the verdict + # grid (.gitbot-fleet/enrolment.json says which members apply). Inline rather + # than `uses:`, because a repository instantiated from this template may live + # under an owner whose Actions policy refuses a reusable workflow from + # hyperomath at plan time (zero jobs, no error line). Checking out another + # repository is plain git. The build and run logic lives in the two + # gitbot-fleet scripts; standards 3-practice/fork-governance/ADOPTION.adoc §8 + # is the guide. + # + # The artifact name is what the verdict grid reads, and what + # hypatia-scan-reusable.yml downloads by default (`report-backs-artifact`), so + # a repository that later adopts the standards reusable needs no change here. + fleet: + name: Fleet report-backs + runs-on: ubuntu-24.04 + timeout-minutes: 45 + permissions: + contents: read + env: + # hyperpolymath/gitbot-fleet commit whose driver and adapters run. + FLEET_REF: e85b71bf139a61f956c7e0717a2912cd6e347cc5 + # panic-attack commit for panicbot. Deliberately the SAME commit + # static-analysis-gate.yml builds: panicbot is not enrolled today (the + # grid's own panic-attack row already grades that scanner, so a second + # row would report one tool twice), and if it ever is, both rows must + # describe the same binary or the grid would compare two tools and call + # it one. The standards Hypatia reusable pins b689a74 for its own row; + # scripts/check-workflow-edges.sh reports that divergence rather than + # letting it hide. + PANIC_ATTACK_SHA: b5530834a839734d1d181bfe6edb0d43d4233cf4 + steps: + - name: Checkout repository + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + ref: ${{ github.sha }} + + - name: Checkout gitbot-fleet at the pinned commit + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + repository: hyperpolymath/gitbot-fleet + ref: ${{ env.FLEET_REF }} + path: .fleet-src + persist-credentials: false + + # The fleet checkout must not sit inside the tree being reported on: walk- + # based adapters would scan the fleet's own source and attribute its findings + # to this repository. actions/checkout only writes under the workspace, so + # the checkout is moved out to RUNNER_TEMP first; the lockfile hash for the + # cache key is taken before the move. + - name: Move the fleet checkout out of the scanned tree + id: fleet + run: | + set -euo pipefail + lockhash=$(cat .fleet-src/bots/*/Cargo.lock .fleet-src/shared-context/Cargo.lock 2>/dev/null | sha256sum | cut -c1-16) + mv .fleet-src "$RUNNER_TEMP/fleet-src" + echo "dir=$RUNNER_TEMP/fleet-src" >> "$GITHUB_OUTPUT" + echo "lockhash=$lockhash" >> "$GITHUB_OUTPUT" + + - name: Plan which adapters to build + id: plan + run: | + set -euo pipefail + plan=$(bash "$RUNNER_TEMP/fleet-src/scripts/fleet-report-back.sh" --plan --enrolment .gitbot-fleet/enrolment.json) + echo "plan:"; printf '%s\n' "$plan" | sed 's/^/ /' + crates=$(printf '%s\n' "$plan" | awk -F'\t' '$2 != "" {print $2}' | sort -u | tr '\n' ' ') + echo "crates=${crates% }" >> "$GITHUB_OUTPUT" + if printf '%s\n' "$plan" | awk -F'\t' '$1 == "panicbot" {f=1} END {exit !f}'; then echo panicbot=true; else echo panicbot=false; fi >> "$GITHUB_OUTPUT" + { echo "workspaces< target"; done; echo "$RUNNER_TEMP/fleet-src/shared-context -> target"; echo WS; } >> "$GITHUB_OUTPUT" + if [ -n "${crates% }" ]; then echo build=true; else echo build=false; fi >> "$GITHUB_OUTPUT" + + # Rust comes with the GitHub-hosted runner image; the cache is actions/cache + # keyed on the fleet commit's lockfiles. Only GitHub-owned, SHA-pinned + # actions appear in this job, as in gitbot-fleet's reusable. + - name: Cache adapter builds + if: steps.plan.outputs.build == 'true' + uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 + with: + path: | + ~/.cargo/registry/index + ~/.cargo/registry/cache + ~/.cargo/git/db + ${{ runner.temp }}/fleet-src/bots/*/target + key: fleet-report-back-v3-${{ runner.os }}-${{ runner.arch }}-${{ steps.fleet.outputs.lockhash }}-${{ steps.plan.outputs.crates }} + restore-keys: | + fleet-report-back-v3-${{ runner.os }}-${{ runner.arch }}-${{ steps.fleet.outputs.lockhash }}- + fleet-report-back-v3-${{ runner.os }}-${{ runner.arch }}- + + - name: Report the Rust toolchain in use + if: steps.plan.outputs.build == 'true' || steps.plan.outputs.panicbot == 'true' + run: | + set -euo pipefail + command -v cargo >/dev/null || { echo "::error::cargo is not on this runner; the adapters cannot be built"; exit 1; } + cargo --version; rustc --version + + - name: Restore panic-attack build cache + if: steps.plan.outputs.panicbot == 'true' + uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 + with: + path: ~/.panic-attack + key: panic-attack-v1-${{ runner.os }}-${{ runner.arch }}-${{ env.PANIC_ATTACK_SHA }} + + - name: Build the enrolled adapters + if: steps.plan.outputs.build == 'true' || steps.plan.outputs.panicbot == 'true' + env: + CRATES: ${{ steps.plan.outputs.crates }} + PANICBOT: ${{ steps.plan.outputs.panicbot }} + run: | + set -euo pipefail + args=(--fleet "$RUNNER_TEMP/fleet-src" --bin-dir "$RUNNER_TEMP/fleet-bin" --crates "$CRATES") + [ "$PANICBOT" = true ] && args+=(--panic-attack "$PANIC_ATTACK_SHA") + bash "$RUNNER_TEMP/fleet-src/scripts/fleet-report-back-build.sh" "${args[@]}" + + - name: Run the enrolled adapters and write the envelopes + run: | + set -euo pipefail + mkdir -p "$RUNNER_TEMP/fleet-bin" "$RUNNER_TEMP/report-backs" + bash "$RUNNER_TEMP/fleet-src/scripts/fleet-report-back.sh" --repo . --out "$RUNNER_TEMP/report-backs" \ + --bin-dir "$RUNNER_TEMP/fleet-bin" --enrolment .gitbot-fleet/enrolment.json \ + --fleet-ref "$FLEET_REF" --summary "$GITHUB_STEP_SUMMARY" + ls "$RUNNER_TEMP/report-backs"/*.json >/dev/null 2>&1 \ + || echo "No member is enrolled in .gitbot-fleet/enrolment.json." > "$RUNNER_TEMP/report-backs/NONE-ENROLLED.txt" + + - name: Upload the report-backs + if: ${{ always() }} + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + with: + name: fleet-report-backs + path: ${{ runner.temp }}/report-backs + if-no-files-found: error + retention-days: 90 + + # Render and upload the PR-time grid with read-only permissions: actions for + # artifacts, contents for checkout, pull-requests for the previous comment. + # verdict-grid-publish.yml owns comment publication. + verdict: + name: Fork governance verdict + needs: [deed, k9, fleet] + if: always() + runs-on: ubuntu-24.04 + timeout-minutes: 15 + permissions: + actions: read + contents: read + pull-requests: read + env: + DEED_RESULT: ${{ needs.deed.result }} + K9_RESULT: ${{ needs.k9.result }} + FLEET_RESULT: ${{ needs.fleet.result }} + steps: + # This job is read-only (actions/contents/pull-requests: read). It runs + # the merge-revision lane script, which is untrusted, so it must never receive a + # write-scoped token. Publishing lives in verdict-grid-publish.yml, which + # checks out the default branch. + - name: Checkout the scanned revision's lane script (read-only token) + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: ${{ env.TARGET_SHA }} + persist-credentials: false + sparse-checkout: | + scripts/verdict-grid-lane.sh + .gitbot-fleet + sparse-checkout-cone-mode: false + + # The renderer is not copied into this repository: it is fetched from + # standards at the pinned commit and verified against a sha256 recorded in + # scripts/verdict-grid-lane.sh. A copy would be a second implementation of + # the estate's grid that could drift from the tested one. + - name: Checkout the verdict grid renderer at the pinned standards commit + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + repository: metadatastician/standards + ref: 8e48b1caade08a552646adeab66558ac43b4360d + path: .standards-grid + persist-credentials: false + sparse-checkout: | + scripts/verdict-grid.sh + scripts/lib/verdict-grid.jq + sparse-checkout-cone-mode: false + + # Discover producer runs by PR_HEAD_SHA; their default checkouts scan the + # merge revision reported as TARGET_SHA. A scanner with no run, or a run with + # no artifact, is recorded with its reason and renders orange — this step + # never turns "not yet" into "clean". + - name: Collect the producers' evidence + id: collect + env: + GH_TOKEN: ${{ github.token }} + run: | + set -euo pipefail + bash scripts/verdict-grid-lane.sh collect \ + --repo "$GITHUB_REPOSITORY" \ + --sha "$PR_HEAD_SHA" \ + --out "$RUNNER_TEMP/evidence" \ + --source hypatia-scan.yml:hypatia-scan-findings \ + --source static-analysis-gate.yml:static-analysis-findings + + # The fleet's report-backs come from THIS run (the fleet job above), so a + # same-run download is enough. Missing evidence is not fatal here: an + # enrolled member without an envelope renders orange, which is the honest + # reading and the reason the grid can be trusted when it is green. + - name: Download the fleet report-backs + continue-on-error: true + uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2 + with: + name: fleet-report-backs + path: ${{ runner.temp }}/evidence/fleet-report-backs + + # The delta column compares against the grid this lane posted last time. + # Best effort: a missing previous comment only means "no comparable + # baseline", which the renderer says explicitly. + - name: Read the previous verdict grid + id: previous + if: ${{ always() && env.TARGET_PR != '' }} + continue-on-error: true + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + set -uo pipefail + # An unreadable previous comment is not a failure of this run: the grid + # then says "— no comparable baseline", which is true. Written as an + # explicit branch rather than `cmd || :`, because a swallowed non-zero + # exit is exactly what RE005 exists to flag. + if ! bash scripts/verdict-grid-lane.sh previous \ + --repo "$GITHUB_REPOSITORY" --pr "$TARGET_PR" \ + --out "$RUNNER_TEMP/previous.md"; then + echo "no previous verdict grid could be read; the delta column will say so" + : > "$RUNNER_TEMP/previous.md" + fi + + - name: Check the evidence shapes before rendering + if: ${{ always() }} + run: | + set -euo pipefail + bash scripts/verdict-grid-lane.sh validate \ + --hypatia "$RUNNER_TEMP/evidence/hypatia-scan-findings/hypatia-findings.relativized.json" \ + --panic "$RUNNER_TEMP/evidence/static-analysis-findings/panic-attack-findings.json" \ + --pons "$RUNNER_TEMP/evidence/static-analysis-findings/pons-findings.json" \ + --enrolment .gitbot-fleet/enrolment.json + + - name: Render the verdict grid + id: grid + if: ${{ always() }} + env: + PREVIOUS: ${{ runner.temp }}/previous.md + run: | + set -euo pipefail + ev="$RUNNER_TEMP/evidence" + args=( + render --out "$RUNNER_TEMP/verdict-grid" + --renderer-dir .standards-grid + --repo "$GITHUB_REPOSITORY" + --sha "$TARGET_SHA" --run "$GITHUB_RUN_ID" --pr "${TARGET_PR:-local}" + --url "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID" + --enrolment .gitbot-fleet/enrolment.json + --hypatia "$ev/hypatia-scan-findings/hypatia-findings.relativized.json" + --panic "$ev/static-analysis-findings/panic-attack-findings.json" + --pons "$ev/static-analysis-findings/pons-findings.json" + --hypatia-ref be98f74ce93df200752f3798efa1305bfa3e0e10 + --panic-ref b5530834a839734d1d181bfe6edb0d43d4233cf4 + --pons-ref 51b8920f541782ceb9465ea3f0d33c96104fc1fb + ) + [ -d "$ev/fleet-report-backs" ] && args+=(--report-backs "$ev/fleet-report-backs") + [ -s "$PREVIOUS" ] && args+=(--previous "$PREVIOUS") + bash scripts/verdict-grid-lane.sh "${args[@]}" + + - name: Upload the verdict grid + if: ${{ always() }} + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + with: + name: verdict-grid + path: ${{ runner.temp }}/verdict-grid + if-no-files-found: error + retention-days: 90 + + # Publishing is deliberately handled by a separate default-branch + # workflow_run consumer. This PR-time workflow is read-only, so its + # untrusted head scripts never receive a write-scoped token. + + - name: Summarise the lanes and gate on conformance only + if: ${{ always() }} + env: + GRID_STATE: ${{ steps.grid.outputs.state }} + BADGE: ${{ steps.grid.outputs.badge }} + run: | + set -euo pipefail + { + echo "## Fork governance" + echo "" + echo "PR head (producer run lookup): \`$PR_HEAD_SHA\`" + echo "Scanned revision (merge revision for PRs): \`$TARGET_SHA\`" + echo "" + echo "| Lane | Result | Gates a merge? |" + echo "|------|--------|----------------|" + echo "| DEED syntax | \`${DEED_RESULT}\` | yes |" + echo "| K9-DEED conformance (L0–L2) | \`${K9_RESULT}\` | yes |" + echo "| Fleet report-backs (evidence, not a lane) | \`${FLEET_RESULT}\` | no — a failed fleet is orange rows, not a blocked PR |" + echo "| Verdict grid | \`${GRID_STATE:-missing}\` | no — see the producers for each scanner's gate |" + echo "" + echo "The grid itself is in the \`verdict-grid\` artifact and, on a pull request, in the" + echo "comment maintained by verdict-grid-publish.yml. A grid state of red or purple is reporting: Hypatia" + echo "and panic-attack gate on critical in their own workflows." + } >> "$GITHUB_STEP_SUMMARY" + failed="" + [ "$DEED_RESULT" = "success" ] || failed="${failed} deed=${DEED_RESULT}" + [ "$K9_RESULT" = "success" ] || failed="${failed} k9=${K9_RESULT}" + if [ -n "$failed" ]; then + echo "::error::Fork governance failed (${failed# })" + exit 1 + fi + if [ -z "${GRID_STATE:-}" ]; then + echo "::warning::No verdict grid state was rendered; see the Render step above." + fi diff --git a/.github/workflows/groove-check.yml b/.github/workflows/groove-check.yml index f0e8785b..605d3651 100644 --- a/.github/workflows/groove-check.yml +++ b/.github/workflows/groove-check.yml @@ -18,12 +18,14 @@ permissions: jobs: groove-check: name: "🟡 CHECK: Groove manifest check" - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 timeout-minutes: 15 steps: - name: Checkout repository uses: actions/checkout@v7.0.1 + with: + persist-credentials: false - name: Check for Groove manifest id: groove @@ -81,11 +83,17 @@ jobs: fi - name: "Write summary" + env: + HAS_MANIFEST: ${{ steps.groove.outputs.has_manifest }} + HAS_GROOVE_CODE: ${{ steps.groove.outputs.has_groove_code }} + HAS_SERVER: ${{ steps.groove.outputs.has_server }} 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 (www/.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" + { + echo "## Groove Protocol Check" + echo "" + echo "| Check | Status |" + echo "|-------|--------|" + echo "| Static manifest (www/.well-known/groove/manifest.json) | ${HAS_MANIFEST} |" + echo "| Groove endpoint in code | ${HAS_GROOVE_CODE} |" + echo "| Has HTTP server code | ${HAS_SERVER} |" + } >> "$GITHUB_STEP_SUMMARY" diff --git a/.github/workflows/guix-policy.yml b/.github/workflows/guix-policy.yml index 6363018b..d6ac2758 100644 --- a/.github/workflows/guix-policy.yml +++ b/.github/workflows/guix-policy.yml @@ -16,7 +16,7 @@ permissions: contents: read jobs: check: - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 timeout-minutes: 15 permissions: contents: read diff --git a/.github/workflows/k9-validate.yml b/.github/workflows/k9-validate.yml deleted file mode 100644 index 548c3bbf..00000000 --- a/.github/workflows/k9-validate.yml +++ /dev/null @@ -1,64 +0,0 @@ -# This workflow is managed by gh actions-lock. -# SPDX-License-Identifier: MPL-2.0 -name: "🟡 CHECK: K9 Contract Validation" - -on: - pull_request: - branches: ['**'] - push: - branches: [main, master] - -concurrency: - group: ${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: true - -permissions: - contents: read - -jobs: - k9-validate: - name: "🟡 CHECK: Validate K9 contracts" - runs-on: ubuntu-latest - timeout-minutes: 15 - - steps: - - name: Checkout repository - uses: actions/checkout@v7.0.1 - - - 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: "🟡 CHECK: Validate K9 contracts" - if: steps.detect.outputs.k9_count > 0 - uses: hyperpolymath/k9-ecosystem/validate-action@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 diff --git a/.github/workflows/label-triage.yml b/.github/workflows/label-triage.yml index b7522268..3b8aa96f 100644 --- a/.github/workflows/label-triage.yml +++ b/.github/workflows/label-triage.yml @@ -46,12 +46,12 @@ permissions: jobs: triage: - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 timeout-minutes: 10 # Hypatia workflow_audit/missing_timeout_minutes (alert #68) steps: - name: Classify and label env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GH_TOKEN: ${{ github.token }} NUM: ${{ github.event.issue.number || inputs.issue }} run: | set -uo pipefail diff --git a/.github/workflows/labels.yml b/.github/workflows/labels.yml index 31618e4b..c496ffd1 100644 --- a/.github/workflows/labels.yml +++ b/.github/workflows/labels.yml @@ -32,12 +32,12 @@ permissions: jobs: sync: - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 timeout-minutes: 10 # Hypatia workflow_audit/missing_timeout_minutes (alert #69) steps: - name: Apply canonical labels env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GH_TOKEN: ${{ github.token }} # ⚠ LOAD-BEARING. This workflow deliberately does not check the repo # out (no `uses:`, so no actions.lock entry can drift), which means # `gh label create` / `gh label edit` have no git remote to infer a diff --git a/.github/workflows/lock-sync-gate.yml b/.github/workflows/lock-sync-gate.yml index db046cb7..baabfd9d 100644 --- a/.github/workflows/lock-sync-gate.yml +++ b/.github/workflows/lock-sync-gate.yml @@ -35,7 +35,7 @@ concurrency: jobs: lock-sync: name: actions.lock is in sync with the workflow YAML - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 timeout-minutes: 5 steps: - name: Check out without actions/checkout @@ -62,3 +62,6 @@ jobs: test -x scripts/check-lock-sync.sh \ || { echo "::error::scripts/check-lock-sync.sh missing or not executable"; exit 1; } ./scripts/check-lock-sync.sh + + - name: Test lockfile rejection cases + run: bash tests/workflows/check_lock_sync_test.sh diff --git a/.github/workflows/main-estate-audit.yml b/.github/workflows/main-estate-audit.yml index c856ee3f..758b056d 100644 --- a/.github/workflows/main-estate-audit.yml +++ b/.github/workflows/main-estate-audit.yml @@ -1,20 +1,68 @@ # This workflow is managed by gh actions-lock. # SPDX-License-Identifier: MPL-2.0 -# This workflow is managed by gh actions-lock. name: Central Estate CI/CD Audit -# The called reusable declares `permissions: contents: read`; a caller must grant -# at least what the reusable declares, and this grants exactly that — no more. permissions: contents: read +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + on: push: - branches: [ "main" ] + branches: ["main"] pull_request: - branches: [ "main" ] - workflow_call: + branches: ["main"] + workflow_dispatch: +# Executes the enforcing gates from hyperpolymath/cicd-suite pinned at a full +# 40-hex commit SHA without a cross-repository workflow_call (avoiding the +# GitHub runner 0-job rejection on onboarded cross-repo workflow_call callers). jobs: - call-estate-audit: - uses: hyperpolymath/cicd-suite/.github/workflows/main-estate-audit.yml@55556cf5ba71ba744695861503c13148d3915a5d # cicd-suite MAIN (branch-reachable): remote-form callee — 27 full-SHA refs, de-onboarded; witnessed cross-repo in rsr runs 35282081912 + 35283168495 (jobs spawn; gates audit THIS repo). Prior f9e173a pin (via #137) = deleted PR head: pull-ref-only reachability -> 0-job creation rejection; its onboarded @main/tag form was separately proven startup_failure cross-repo (35280642055). Repin on callee updates; never to PR-head commits. + estate-audit: + name: Central Estate CI/CD Audit + runs-on: ubuntu-24.04 + timeout-minutes: 15 + permissions: + contents: read + steps: + - name: Checkout repository + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - name: Checkout pinned cicd-suite gates + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + repository: hyperpolymath/cicd-suite + ref: bf7dd95cf49733019343ff485c2f45c6b261839c + path: .cicd-suite-tmp + persist-credentials: false + + - name: Run enforcing cicd-suite governance, hygiene, and language gates + env: + REPO_OWNER: ${{ github.repository_owner }} + REPO_NAME: ${{ github.repository }} + run: | + set -euo pipefail + rm -rf "$RUNNER_TEMP/cicd-suite" + mv .cicd-suite-tmp "$RUNNER_TEMP/cicd-suite" + SUITE="$RUNNER_TEMP/cicd-suite/actions" + + for gate in affirmation-check referencing-check code-hygiene-check secrets-check boj-cartridge-check; do + echo "=== cicd-suite: $gate ===" + bash "$SUITE/$gate/check.sh" . + done + + echo "=== cicd-suite: spdx-license-check ===" + test -f LICENSE.txt || test -f LICENSE || test -f LICENSE.md || test -f LICENSE.adoc + + echo "=== cicd-suite: idris2-abi & zig-unified-api-adapter ===" + if find . -name '*.zig' -not -path './.git/*' | grep -q .; then + if git grep -E 'std\.fs|std\.io' -- '*.zig'; then + echo "::error::Zig FFI modules contain prohibited side-effects (std.fs/std.io)" + exit 1 + fi + fi + echo "Central Estate CI/CD Audit passed." diff --git a/.github/workflows/ossf-best-practices.yml b/.github/workflows/ossf-best-practices.yml index b3aa90ee..bd0cb626 100644 --- a/.github/workflows/ossf-best-practices.yml +++ b/.github/workflows/ossf-best-practices.yml @@ -16,7 +16,7 @@ permissions: contents: read jobs: openssf-compliance: - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 timeout-minutes: 15 permissions: contents: read @@ -44,11 +44,21 @@ jobs: 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 + # A root licence file in any of the usual spellings, or a REUSE + # LICENSES/ directory holding at least one licence text: a non-empty + # . file, per the REUSE spec (dotfiles and READMEs do not count). + for f in LICENSE LICENSE.txt LICENSE.md LICENSE.adoc; do + if [ -f "$f" ]; then + echo "LICENSE: OK ($f)" + exit 0 + fi + done + if [ -n "$(find LICENSES -maxdepth 1 -type f -size +0c -name '*.*' ! -name '.*' ! -iname 'README*' 2>/dev/null | head -n 1)" ]; then + echo "LICENSE: OK (REUSE LICENSES/)" + exit 0 fi - echo "LICENSE: OK" + echo "::error::LICENSE file is required for OpenSSF Best Practices" + exit 1 - name: Check CONTRIBUTING exists run: | if [ ! -f "CONTRIBUTING.md" ] && [ ! -f "CONTRIBUTING.adoc" ] \ @@ -64,18 +74,24 @@ jobs: exit 1 fi echo "README: OK" - - name: Check .machine_readable directory and STATE.a2ml + - name: Check .machine_readable directory and the repo deed run: | if [ ! -d ".machine_readable" ]; then echo "::error::.machine_readable/ directory is required" exit 1 fi - if [ ! -f ".machine_readable/descriptiles/STATE.a2ml" ]; then - echo "::error::.machine_readable/descriptiles/STATE.a2ml is required" + # Project state is the (status …) clause of the repo deed + # (rsr-template-repo#209), which replaced descriptiles/STATE.a2ml. + if ! DEED=$(bash scripts/deed-field.sh --find .); then + echo "::error::exactly one _chora.deed is required at the root" + exit 1 + fi + if ! bash scripts/deed-field.sh --has "$DEED" status; then + echo "::error::$DEED has no (status …) clause" exit 1 fi - echo ".machine_readable/descriptiles/STATE.a2ml: OK" + echo "$DEED (status): OK" - name: Check CHANGELOG exists run: | if [ ! -f "CHANGELOG.md" ] && [ ! -f "CHANGELOG.adoc" ] && [ ! -f "CHANGES.md" ]; then diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index a176cb20..7fcc1965 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -22,7 +22,7 @@ concurrency: jobs: build: timeout-minutes: 20 - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 steps: - name: Checkout uses: actions/checkout@v7.0.1 @@ -83,7 +83,7 @@ jobs: environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 needs: build steps: - name: Deploy to GitHub Pages diff --git a/.github/workflows/proven-tests.yml b/.github/workflows/proven-tests.yml new file mode 100644 index 00000000..8135e18b --- /dev/null +++ b/.github/workflows/proven-tests.yml @@ -0,0 +1,108 @@ +# This workflow is managed by gh actions-lock. +# SPDX-License-Identifier: MPL-2.0 +# +# proven-tests.yml — Full 3-outcome testing, proof honesty, data-format, and +# Six-Sigma leave-one-out benchmark regression suite grounded in +# hyperpolymath/proven-tests-and-benches and hyperpolymath/ijson-jcs. +name: Proven Tests and Benches + +on: + pull_request: + push: + branches: [main, master] + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: proven-tests-${{ github.ref }} + cancel-in-progress: true + +jobs: + proven-suite: + name: Proven 3-outcome test & bench suite + runs-on: ubuntu-24.04 + timeout-minutes: 20 + env: + NICKEL_VERSION: '1.18.0' + NICKEL_SHA256: '9cba4dd65ae9915ec61f73033aafcff307a377665a83fd8f530df086763318cb' + steps: + - name: Checkout repository + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - name: Checkout canon validators into RUNNER_TEMP (metadatastician/standards) + run: | + set -euo pipefail + git init -q "$RUNNER_TEMP/standards" + git -C "$RUNNER_TEMP/standards" remote add origin https://github.com/metadatastician/standards.git + git -C "$RUNNER_TEMP/standards" config core.sparseCheckout true + printf '1-formats/deed/\n1-formats/k9/\n' > "$RUNNER_TEMP/standards/.git/info/sparse-checkout" + git -C "$RUNNER_TEMP/standards" fetch -q --depth 1 origin 8e48b1caade08a552646adeab66558ac43b4360d + git -C "$RUNNER_TEMP/standards" checkout -q FETCH_HEAD + + - name: Set up Bun + uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 + - name: Install verified Nickel 1.18.0 (K9 L2 semantics) + run: | + set -euo pipefail + mkdir -p "$RUNNER_TEMP/nickel-bin" + curl --proto '=https' --proto-redir '=https' --tlsv1.2 --fail --silent --show-error --location \ + "https://github.com/tweag/nickel/releases/download/${NICKEL_VERSION}/nickel-x86_64-linux" \ + --output "$RUNNER_TEMP/nickel-bin/nickel" + echo "${NICKEL_SHA256} $RUNNER_TEMP/nickel-bin/nickel" | sha256sum --check --strict + chmod +x "$RUNNER_TEMP/nickel-bin/nickel" + echo "$RUNNER_TEMP/nickel-bin" >> "$GITHUB_PATH" + - name: Install verified Zig 0.16.0 (matching mise.lock) + run: | + set -euo pipefail + curl --proto '=https' --proto-redir '=https' --fail --silent --show-error --location \ + https://ziglang.org/download/0.16.0/zig-x86_64-linux-0.16.0.tar.xz \ + --output "$RUNNER_TEMP/zig.tar.xz" + echo "70e49664a74374b48b51e6f3fdfbf437f6395d42509050588bd49abe52ba3d00 $RUNNER_TEMP/zig.tar.xz" | sha256sum --check --strict + mkdir -p "$RUNNER_TEMP/zig" + tar -xJf "$RUNNER_TEMP/zig.tar.xz" -C "$RUNNER_TEMP/zig" --strip-components=1 + echo "$RUNNER_TEMP/zig" >> "$GITHUB_PATH" + + - name: Install verified Just 1.56.0 (matching mise.lock) + run: | + set -euo pipefail + curl --proto '=https' --proto-redir '=https' --fail --silent --show-error --location \ + https://github.com/casey/just/releases/download/1.56.0/just-1.56.0-x86_64-unknown-linux-musl.tar.gz \ + --output "$RUNNER_TEMP/just.tar.gz" + echo "fa2a8ec1015d9df5330941ade12437488fc40d33f9c9f8cd4eb70a26de11b639 $RUNNER_TEMP/just.tar.gz" | sha256sum --check --strict + mkdir -p "$RUNNER_TEMP/just-bin" + tar -xzf "$RUNNER_TEMP/just.tar.gz" -C "$RUNNER_TEMP/just-bin" just + chmod +x "$RUNNER_TEMP/just-bin/just" + echo "$RUNNER_TEMP/just-bin" >> "$GITHUB_PATH" + + - name: Cache pinned ijson-jcs and panic-attack binaries + id: cache-ijson + uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 + with: + path: | + ~/.cargo/bin/ijson-jcs + ~/.cargo/bin/panic-attack + key: proven-tools-${{ runner.os }}-ijson-2c880594c8b1-pa-b5530834a839 + + - name: Build pinned hyperpolymath/ijson-jcs & panic-attack when uncached + if: steps.cache-ijson.outputs.cache-hit != 'true' + run: | + set -euo pipefail + cargo install --locked \ + --git https://github.com/hyperpolymath/ijson-jcs.git \ + --rev 2c880594c8b1f823a7ab2a8a830c894975a1792e \ + --bin ijson-jcs + cargo install --locked \ + --git https://github.com/hyperpolymath/panic-attack.git \ + --rev b5530834a839734d1d181bfe6edb0d43d4233cf4 + + - name: Run 3-outcome proven test, proof honesty, FFI, E2E & bench suite + env: + IJSON_JCS: ijson-jcs + run: | + set -euo pipefail + export PATH="$HOME/.cargo/bin:$PATH" + STANDARDS_DIR="$RUNNER_TEMP/standards" bash scripts/run-proven-suite.sh --require-zig --bench diff --git a/.github/workflows/push-email-notify.yml b/.github/workflows/push-email-notify.yml index 3b108c5c..e7fc1641 100644 --- a/.github/workflows/push-email-notify.yml +++ b/.github/workflows/push-email-notify.yml @@ -35,11 +35,11 @@ jobs: notify: name: Email on push if: ${{ vars.PUSH_EMAIL_ENABLED == 'true' && github.event.deleted != true }} - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 timeout-minutes: 5 steps: - name: Send push notification email - uses: hyperpolymath/smtp-notify-action@v0.5.1 # NOSONAR — pin authority is actions.lock (sha1-22e7bdb322c430c1d0dac6b3bb307f4bb139d0be) + uses: hyperpolymath/smtp-notify-action@v0.5.0 # NOSONAR — pin authority is actions.lock (sha1-22e7bdb322c430c1d0dac6b3bb307f4bb139d0be) with: server_address: ${{ secrets.SMTP_HOST }} server_port: ${{ secrets.SMTP_PORT }} diff --git a/.github/workflows/quality.yml b/.github/workflows/quality.yml index c9c638c7..0eb32704 100644 --- a/.github/workflows/quality.yml +++ b/.github/workflows/quality.yml @@ -17,12 +17,14 @@ permissions: contents: read jobs: lint: - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 timeout-minutes: 15 permissions: contents: read steps: - - uses: actions/checkout@v7.0.1 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false - name: Check file permissions run: | find . -type f -perm /111 -name "*.sh" | head -10 || true @@ -56,15 +58,49 @@ jobs: run: | find . -type f -size +1M -not -path "./.git/*" | head -10 || echo "No large files" - name: EditorConfig check - uses: editorconfig-checker/action-editorconfig-checker@v3.0.0 + uses: editorconfig-checker/action-editorconfig-checker@51f63319f592f97930c73d9c46184d20bd206393 # v3.0.0 continue-on-error: true + # The gates this template ships, and the proof that each one can fail. + # + # Nothing else in this workflow runs them: `just quality` is deliberately not + # wired here, because it needs the repository's own toolchain (zig for this + # tree) and a CI job that installs a toolchain to run a check is a job that + # gets skipped when the toolchain moves. These four gates need bash and git. + # + # tests/workflows/mint_gates_test.sh is the part that matters: it asserts that + # every gate above FAILS on a fixture built to fail it. A gate whose only + # exercised path is the passing one is the fake-gate class this estate hunts, + # and it cannot be caught by reading the gate. + mint-gates: + runs-on: ubuntu-24.04 + timeout-minutes: 15 + permissions: + contents: read + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - name: Gates + run: | + fail=0 + for g in check-mint-tokens check-spdx-headers check-mise-language check-container-pins; do + echo "── ${g} ──" + bash "scripts/${g}.sh" || fail=1 + done + exit "$fail" + - name: Every gate must fail on a fixture + run: bash tests/workflows/mint_gates_test.sh + - name: Language profiles (Julia and Rust scaffolds) + run: bash tests/e2e/language_profiles_mint_test.sh docs: - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 timeout-minutes: 15 permissions: contents: read steps: - - uses: actions/checkout@v7.0.1 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false - name: Check documentation run: | MISSING="" diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 72454cf5..75229769 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -18,7 +18,7 @@ permissions: jobs: build: name: Build Artifacts - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 timeout-minutes: 15 permissions: contents: read @@ -44,10 +44,6 @@ jobs: 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" @@ -66,7 +62,7 @@ jobs: 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" + echo "Expected one of: mix.exs, Cargo.toml, build.zig, gossamer.conf.json, gleam.toml, rebar.config, Justfile" exit 1 fi # TODO: Upload build artifacts if needed (pin actions/upload-artifact @@ -77,7 +73,7 @@ jobs: # path: target/release/ changelog: name: Generate Changelog - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 timeout-minutes: 15 permissions: contents: read @@ -118,7 +114,7 @@ jobs: release: name: Create GitHub Release needs: [build, changelog] - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 timeout-minutes: 15 permissions: contents: write @@ -143,7 +139,7 @@ jobs: # files: | # artifacts/* env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GITHUB_TOKEN: ${{ github.token }} # GitHub native artifact attestation (build provenance). Generates a # signed, verifiable claim binding each released artifact to this build # (commit, workflow, runner) via OIDC + Sigstore — verify with diff --git a/.github/workflows/rsr-compliance-canary.yml b/.github/workflows/rsr-compliance-canary.yml index 13e0a55a..e03cd32e 100644 --- a/.github/workflows/rsr-compliance-canary.yml +++ b/.github/workflows/rsr-compliance-canary.yml @@ -30,7 +30,7 @@ permissions: contents: read jobs: canary: - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 timeout-minutes: 15 steps: - name: Checkout @@ -54,11 +54,9 @@ jobs: for f in *-STATUS-*.md *-COMPLETION-*.md *-COMPLETE.md *-VERIFIED-*.md; do [ -f "$f" ] && warn "stale snapshot present: $f (would be deleted)" done - # would-RENAME: legacy manifest name (a repo deed at root is the - # deed-era equivalent — standards#837) - if [ -f "AI.a2ml" ] && [ ! -f "0-AI-MANIFEST.a2ml" ] && ! ls *_chora.deed >/dev/null 2>&1; then - warn "AI.a2ml present without 0-AI-MANIFEST.a2ml or a repo deed (would be renamed)" - fi + # retired format: every .a2ml file is drift (facts belong in the deed) + a2ml_left=$(find . -path ./.git -prune -o -type f -name '*.a2ml' -print | head -5) + [ -z "$a2ml_left" ] || warn "retired .a2ml files present (move their facts into the repo deed): $(echo $a2ml_left)" # would-DELETE: duplicate community files [ -f "CONTRIBUTING.md" ] && [ -f "CONTRIBUTING.adoc" ] && warn "duplicate CONTRIBUTING.md + CONTRIBUTING.adoc (one would be removed)" if [ -f "README.md" ] && [ -f "README.adoc" ] && [ "$(wc -l < README.md)" -lt 5 ]; then @@ -75,7 +73,7 @@ jobs: [ -f "CONTRIBUTING.md" ] || [ -f ".github/CONTRIBUTING.md" ] || warn "no CONTRIBUTING.md (would be created)" # --- unfixable compliance gaps (also drift) --- - [ -f "0-AI-MANIFEST.a2ml" ] || [ -f "AI.a2ml" ] || ls *_chora.deed >/dev/null 2>&1 || warn "missing AI manifest (0-AI-MANIFEST.a2ml or repo deed *_chora.deed)" + ls *_chora.deed >/dev/null 2>&1 || warn "missing repo deed (*_chora.deed at the root)" [ -f "LICENSE" ] || [ -f "LICENSE.md" ] || [ -f "LICENSE.txt" ] || warn "missing LICENSE file" [ -f "README.adoc" ] || [ -f "README.md" ] || warn "missing README" diff --git a/.github/workflows/runtime-policy.yml b/.github/workflows/runtime-policy.yml deleted file mode 100644 index 51ec04fa..00000000 --- a/.github/workflows/runtime-policy.yml +++ /dev/null @@ -1,72 +0,0 @@ -# This workflow is managed by gh actions-lock. -# SPDX-License-Identifier: MPL-2.0 -# Runtime and package-manager policy check. -# -# Authority: hyperpolymath/standards LANGUAGE-POLICY.adoc §1. -# Ordering: Bun (1st) > Deno (2nd) > pnpm (3rd) > npm (last resort). -# -# REPLACES npm-bun-blocker.yml, which failed any build carrying `bun.lockb` with -# the message "npm/bun artifacts detected. Use Deno instead." That gate blocked -# what is now the FIRST-choice runtime and mandated the second. It was present in -# 55 repositories. -# -# What this fails on, deliberately: -# MIXED TOOLCHAINS -- two different package managers' lockfiles in one repo. -# That is real, actionable drift: two dependency graphs that can disagree. -# What it does NOT fail on: -# Using bun, pnpm or npm. Deno is RETIRED (2026-08-26). npm is LAST but PERMITTED; the check reports -# the tier in use so drift is visible without blocking legitimate work. -name: Runtime Policy -on: - push: - branches: [main, master] - pull_request: - -concurrency: - group: ${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: true - -permissions: - contents: read - -jobs: - runtime-policy: - name: Runtime Policy - runs-on: ubuntu-latest - timeout-minutes: 10 - permissions: - contents: read - steps: - - uses: actions/checkout@v7.0.1 - - - name: Report runtime tier and reject mixed toolchains - run: | - set -euo pipefail - - bun=0; deno=0; pnpm=0; npm=0 - [ -f bun.lockb ] || [ -f bun.lock ] && bun=1 || true - [ -f deno.lock ] || [ -f deno.json ] || [ -f deno.jsonc ] && deno=1 || true - [ -f pnpm-lock.yaml ] && pnpm=1 || true - [ -f package-lock.json ] && npm=1 || true - - total=$((bun + deno + pnpm + npm)) - - if [ "$total" -eq 0 ]; then - echo "::notice::No JS/TS package manager in use — nothing to check." - exit 0 - fi - - # Report the tier actually in use (LANGUAGE-POLICY.adoc §1). - [ "$bun" -eq 1 ] && echo "Bun — tier 1 (preferred)" - [ "$deno" -eq 1 ] && echo "::warning::Deno lockfile/config present. Deno is BEING REMOVED, not grandfathered (owner ruling 2026-08-26, canon standards#655). Migrate to Bun — package.json + bun.lock. This is a warning rather than an error only while the estate migration is in flight; it escalates to an error when that completes." - [ "$pnpm" -eq 1 ] && echo "pnpm — tier 3" - [ "$npm" -eq 1 ] && echo "::warning::npm lockfile present. npm is tier 4, the last resort — permitted, never preferred. See LANGUAGE-POLICY.adoc §1." - - if [ "$total" -gt 1 ]; then - echo "::error::Mixed toolchains: $total package managers have lockfiles in this repository." - echo "Two dependency graphs that can disagree is real drift. Pick one — preferring the" - echo "highest tier present — and delete the others' lockfiles." - exit 1 - fi - - echo "✅ Single package manager in use." diff --git a/.github/workflows/security-policy.yml b/.github/workflows/security-policy.yml index 3c64369d..6d9e43f5 100644 --- a/.github/workflows/security-policy.yml +++ b/.github/workflows/security-policy.yml @@ -16,12 +16,14 @@ permissions: contents: read jobs: check: - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 timeout-minutes: 15 permissions: contents: read steps: - - uses: actions/checkout@v7.0.1 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false - name: Security checks run: | FAILED=false diff --git a/.github/workflows/sonarqube.yml b/.github/workflows/sonarqube.yml index fe33947d..b2d14b06 100644 --- a/.github/workflows/sonarqube.yml +++ b/.github/workflows/sonarqube.yml @@ -36,7 +36,7 @@ permissions: jobs: sonarqube: name: SonarQube - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 timeout-minutes: 15 # Secrets cannot be referenced from a job-level `if:`, so the presence test # is carried through an env var set at job scope and read in a first step. @@ -64,6 +64,6 @@ jobs: - name: SonarQube Scan if: steps.cfg.outputs.configured == 'true' - uses: SonarSource/sonarqube-scan-action@v8.4.0 + uses: SonarSource/sonarqube-scan-action@v8.3.0 env: SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }} diff --git a/.github/workflows/squabble.yml b/.github/workflows/squabble.yml new file mode 100644 index 00000000..ef85af21 --- /dev/null +++ b/.github/workflows/squabble.yml @@ -0,0 +1,93 @@ +# This workflow is managed by gh actions-lock. +# SPDX-License-Identifier: MPL-2.0 +# +# squabble.yml — CICD-Squabbler gate & cross-repo CI dependency chain verifier +# (hyperpolymath/cicd-squabbler; Doctrine rule 5: "Squabble, don't bypass"). +# +# Carries zero external `uses:` references (lockfile entry `[]`, matching +# cicd-squabbler's own squabble-action.yml pattern) so it can never be felled +# by a third-party action tag move or lockfile mismatch: +# 1. Checks out the exact commit under test via git HTTP header auth; +# 2. Installs Bun 1.4.2 (sha256-verified) and runs offline Silence + Firing +# self-tests (`squabble_gate_test.sh`) plus `check-required-contexts.sh`; +# 3. Installs the pinned `squabble` v0.1.0 release binary through +# `.github/actions/squabble/install.sh` (sha256 + GitHub SLSA provenance +# attestation verified before chmod +x); +# 4. Runs `squabble chains .= --follow 1` through +# `.github/actions/squabble/run.sh`, failing loudly (exit 4) on any +# cross-repo CI dependency cycle or dead upstream action/workflow. +name: CICD Squabbler + +on: + pull_request: + push: + branches: [main, master] + workflow_dispatch: + +permissions: + contents: read + attestations: read + +concurrency: + group: squabble-${{ github.ref }} + cancel-in-progress: true + +jobs: + squabble: + name: Squabble CI chains & required-context gate + runs-on: ubuntu-24.04 + timeout-minutes: 10 + steps: + - name: Check out commit without external uses + env: + REPO: ${{ github.repository }} + SHA: ${{ github.event.pull_request.head.sha || github.sha }} + TOKEN: ${{ github.token }} + run: | + set -euo pipefail + AUTH="AUTHORIZATION: basic $(printf 'x-access-token:%s' "${TOKEN}" | base64 -w0)" + git init -q . + git remote add origin "https://github.com/${REPO}.git" + git -c http.extraheader="${AUTH}" fetch -q --depth 1 origin "${SHA}" + git checkout -q FETCH_HEAD + + - name: Install verified Bun 1.4.2 + run: | + set -euo pipefail + curl --proto '=https' --proto-redir '=https' --fail --silent --show-error --location \ + https://github.com/oven-sh/bun/releases/download/bun-v1.4.2/bun-linux-x64.zip \ + --output "$RUNNER_TEMP/bun.zip" + echo "36368faef7527875d5ffa52e53cd48021741f2a83eb6208a8dd64068d422a913 $RUNNER_TEMP/bun.zip" | sha256sum --check --strict + unzip -q "$RUNNER_TEMP/bun.zip" -d "$RUNNER_TEMP" + echo "$RUNNER_TEMP/bun-linux-x64" >> "$GITHUB_PATH" + + - name: Squabble guards & required-context self-tests + env: + GH_TOKEN: ${{ github.token }} + run: | + set -euo pipefail + bash tests/workflows/squabble_gate_test.sh + bash scripts/check-required-contexts.sh . + # squabble follows CROSS-repository CI edges. The verdict grid added + # edges of the same kind INSIDE this repository (workflow_run on a + # workflow's `name:`, artifacts read by name, per-tool pins shared + # between a producer and the reporter), and a rename of any of them + # fails silently: no red check, just an orange grid row forever. + # This is the local half of the same audit. + bash scripts/check-workflow-edges.sh . + + - name: Install pinned & SLSA-attested squabble v0.1.0 + id: install + env: + GH_TOKEN: ${{ github.token }} + run: bash .github/actions/squabble/install.sh + + - name: Audit cross-repo CI dependency chains (cycles & dead upstreams) + env: + GH_TOKEN: ${{ github.token }} + REPO: ${{ github.repository }} + SQUABBLE_BIN: ${{ steps.install.outputs.path }} + run: | + set -euo pipefail + SQUABBLE_ARGS="$(printf 'chains\n.=%s\n--follow\n1\n' "${REPO}")" \ + bash .github/actions/squabble/run.sh diff --git a/.github/workflows/static-analysis-gate.yml b/.github/workflows/static-analysis-gate.yml index ffc406fb..10799b1d 100644 --- a/.github/workflows/static-analysis-gate.yml +++ b/.github/workflows/static-analysis-gate.yml @@ -1,7 +1,33 @@ # This workflow is managed by gh actions-lock. # 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. +# Static Analysis Gate — deep recon & fleet-learning deposit. +# Builds and caches pinned panic-attack and pons-asinorum, executes real scans +# without silent fallback, and deposits one evidence artifact for the verdict +# grid. +# +# ── SCOPE (see the header of fork-governance.yml for the whole picture) ────── +# +# This workflow produces evidence; it does not render the verdict grid and it +# does not run Hypatia. Until 2026-10 it ran Hypatia a second time (same pin, +# different cache key, a second "fail on critical" gate, a differently-shaped +# JSON) while .github/workflows/hypatia-scan.yml ran it too. Hypatia now runs +# once, there. What is left here is what only this workflow does: panic-attack +# assail, pons asinorum deep recon, and patch-bridge CVE triage. +# +# The evidence artifact (`static-analysis-findings`, read by fork-governance.yml) +# carries each scanner's STATUS ENVELOPE, not a bare array: +# +# { "status": "ran" | "not_run" | "error", "tool": "...", "ref": "", +# "reason": null | "", "exit_code": 0 | , "report": {...} | null } +# +# A bare array cannot distinguish "ran clean" from "never ran", and the verdict +# grid renders a scanner that did not run as orange, never as a clean scan. This +# shape is the one metadatastician/standards docs/VERDICT-GRID-SPEC.adoc defines +# and hypatia-scan-reusable.yml already writes, so adopting that reusable would +# not change what the grid reads. +# +# GATES: panic-attack blocks on critical (its own decision, taken here once); +# pons and patch-bridge are advisory. The verdict grid never gates. name: Static Analysis Gate on: pull_request: @@ -13,288 +39,219 @@ concurrency: cancel-in-progress: true permissions: contents: read +env: + # One pin per tool, estate-wide, for this repository. fork-governance.yml's + # verdict job names the same commits when it identifies this evidence, and + # scripts/check-workflow-edges.sh fails the CICD Squabbler gate when a tool is + # pinned at two different commits in two workflows. + PANIC_ATTACK_SHA: b5530834a839734d1d181bfe6edb0d43d4233cf4 + PONS_SHA: 51b8920f541782ceb9465ea3f0d33c96104fc1fb jobs: # --------------------------------------------------------------------------- - # Job 1: panic-attack assail + # Job 1: panic-attack assail + pons-asinorum deep recon # --------------------------------------------------------------------------- panic-attack-assail: - name: panic-attack assail - runs-on: ubuntu-latest - timeout-minutes: 15 + name: panic-attack & pons-asinorum deep recon + runs-on: ubuntu-24.04 + timeout-minutes: 25 steps: - name: Checkout repository - uses: actions/checkout@v7.0.1 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: fetch-depth: 0 - - name: Install panic-attack (if available) - id: install + persist-credentials: false + + - name: Cache pinned panic-attack & pons-asinorum binaries + id: cache-recon + uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 + with: + path: | + ~/.cargo/bin/panic-attack + ~/.cargo/bin/pons + key: deep-recon-v3-${{ runner.os }}-pa-${{ env.PANIC_ATTACK_SHA }}-pons-${{ env.PONS_SHA }} + + - name: Build pinned panic-attack & pons-asinorum when uncached + if: steps.cache-recon.outputs.cache-hit != 'true' 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 + set -euo pipefail + cargo install --locked --force \ + --git https://github.com/hyperpolymath/panic-attack.git \ + --rev "$PANIC_ATTACK_SHA" + cargo install --locked \ + --git https://github.com/hyperpolymath/pons-asinorum.git \ + --rev "$PONS_SHA" \ + --bin pons + + # Each scanner writes its envelope whichever way it ends, so the grid + # sees status "error" with the exit code and reason instead of an absent + # file that it could only call "not run". - 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 - PA_EXIT=$? - set -e + set -uo pipefail + export PATH="$HOME/.cargo/bin:$PATH" + PA_RAW="$RUNNER_TEMP/pa-report.json" + PA_LOG="$RUNNER_TEMP/pa-assail.log" + out=panic-attack-findings.json + PA_EXIT=0 + panic-attack assail . --output "$PA_RAW" > "$PA_LOG" 2>&1 || PA_EXIT=$? - # Same defect class as the Hypatia job below: `2>&1` folded the - # scanner's stderr into the JSON payload, so every jq parse failed, - # every count silently became 0 via `|| echo 0`, and "Fail on critical - # findings" could never fire on any input. Keep stderr on the log. - if [ ! -s panic-attack-findings.json ]; then - echo "[]" > panic-attack-findings.json - fi + envelope() { # envelope STATUS REASON + jq -n --arg s "$1" --arg r "$2" --arg ref "$PANIC_ATTACK_SHA" --argjson rc "$PA_EXIT" \ + --slurpfile doc "${3:-/dev/null}" \ + '{status: $s, tool: "panic-attack", ref: $ref, reason: ($r | if . == "" then null else . end), + exit_code: $rc, report: (if ($doc | length) > 0 then $doc[0] else null end)}' > "$out" + } - # Deliberately a WARNING, not a failure. panic-attack is a downloaded - # release binary whose exit-code and output contract are not verified - # here, and it has no confirmed --exit-zero equivalent, so we surface a - # malformed payload in the log rather than block on an unverified tool. - # Promote to `exit 1` (as the Hypatia job does) once that contract is - # confirmed -- see the follow-up issue linked from this PR. - if ! jq -e 'type == "array"' panic-attack-findings.json >/dev/null 2>&1; then - echo "::warning::panic-attack output is not a JSON array (exit ${PA_EXIT}); counts below are unreliable" + if [ "$PA_EXIT" -ne 0 ] || [ ! -s "$PA_RAW" ]; then + cat "$PA_LOG" >&2 + envelope error "panic-attack assail failed or produced an empty report (exit ${PA_EXIT})" + echo "::error::panic-attack assail failed or produced empty report (exit ${PA_EXIT})" + elif ! jq -e 'type == "object" and (.weak_points | type == "array")' "$PA_RAW" >/dev/null 2>&1; then + cat "$PA_LOG" >&2 + envelope error "panic-attack assail produced no valid AssailReport JSON object" + echo "::error::panic-attack assail did not produce a valid AssailReport JSON object" + else + envelope ran "" "$PA_RAW" + # suppressed:true is panic-attack's own "likely false positive" mark; + # the grid does not count it either (VERDICT-GRID-SPEC §grading). + jq '[.weak_points[] | select(.suppressed != true) | .severity = ((.severity // "") | ascii_downcase)]' \ + "$PA_RAW" > "$RUNNER_TEMP/pa-findings.json" + TOTAL=$(jq 'length' "$RUNNER_TEMP/pa-findings.json") + CRITICAL=$(jq '[.[] | select(.severity == "critical")] | length' "$RUNNER_TEMP/pa-findings.json") + HIGH=$(jq '[.[] | select(.severity == "high")] | length' "$RUNNER_TEMP/pa-findings.json") + MEDIUM=$(jq '[.[] | select(.severity == "medium" or .severity == "warn")] | length' "$RUNNER_TEMP/pa-findings.json") + LOW=$(jq '[.[] | select(.severity == "low")] | length' "$RUNNER_TEMP/pa-findings.json") + { + echo "total=$TOTAL" + echo "critical=$CRITICAL" + echo "high=$HIGH" + echo "medium=$MEDIUM" + echo "low=$LOW" + } >> "$GITHUB_OUTPUT" + { + echo "## panic-attack assail" + echo "" + echo "| Severity | Count |" + echo "|----------|-------|" + echo "| Critical | ${CRITICAL} |" + echo "| High | ${HIGH} |" + echo "| Medium | ${MEDIUM} |" + echo "| Low | ${LOW} |" + } >> "$GITHUB_STEP_SUMMARY" + fi + jq -e '.status | type == "string"' "$out" >/dev/null + if [ "$(jq -r .status "$out")" != "ran" ]; then + echo "::error::Blocking scanner did not produce trustworthy results" + exit 1 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" or .severity == "warn")] | 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 - # Findings carry no `.message` (keys: action,file,line,reason,rule_module, - # severity,type), so every annotation read "null". `.file` is an absolute - # runner path, which GitHub cannot anchor to the diff, so it is made - # workspace-relative here. - jq -r --arg ws "$GITHUB_WORKSPACE" '.[] | select(.file != null) | - (.file | ltrimstr($ws + "/")) as $f | - (.reason // .message // .type // "finding") as $m | - if .severity == "critical" then - "::error file=\($f),line=\(.line // 1)::[panic-attack] \($m)" - elif .severity == "high" then - "::error file=\($f),line=\(.line // 1)::[panic-attack] \($m)" - else - "::warning file=\($f),line=\(.line // 1)::[panic-attack] \($m)" - 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@v7.0.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 - # - # NOTE — this is NOT a duplicate of the standalone `hypatia-scan.yml`. - # * THIS job runs Hypatia inside the gate and hands its findings to the - # `deposit-findings` job below, which feeds the gitbot-fleet LEARNING - # pipeline (artifact -> fleet). It is a REQUIRED status check. - # * `hypatia-scan.yml` runs Hypatia standalone as the repo's security scan, - # independent of the fleet-learning deposit. - # Same tool, two different consumers — keep both. See .github/workflows/README.adoc. - # --------------------------------------------------------------------------- - hypatia-scan: - name: Hypatia neurosymbolic scan - runs-on: ubuntu-latest - timeout-minutes: 15 - steps: - - name: Checkout repository - uses: actions/checkout@v7.0.1 - with: - fetch-depth: 0 - - name: Setup Elixir for Hypatia scanner - id: beam - continue-on-error: true - uses: erlef/setup-beam@v1.24.1 - with: - elixir-version: '1.19.4' - otp-version: '28.3' - - name: Clone and build Hypatia - id: build + - name: Run pons-asinorum deep recon audit + id: pons 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 . --exit-zero > hypatia-findings.json - HYP_EXIT=$? - set -e - - # --exit-zero is Hypatia's own documented CI recipe (lib/hypatia/cli.ex), - # for exactly this case: "use in CI when a downstream step gates on - # severity counts". Findings go to stdout, the one-line summary to - # stderr, and the process exits 0 unless the SCANNER itself failed. - # - # Do NOT redirect stderr into the payload with `2>&1`: that folds the - # summary line into the JSON, so every parse fails, the old `[]` - # fallback substituted a clean result, CRITICAL was always 0, and the - # gate below could never fire on any input. Keep stderr on the log. - if [ "$HYP_EXIT" -ne 0 ]; then - echo "::error::Hypatia scanner execution failed with exit ${HYP_EXIT}" - exit "$HYP_EXIT" - fi - # `jq empty` is NOT sufficient -- it succeeds on any valid JSON, - # including a bare string, object or null. Assert the array. - if [ ! -s hypatia-findings.json ] || ! jq -e 'type == "array"' hypatia-findings.json >/dev/null; then - echo "::error::Hypatia did not produce a valid JSON findings array" + set -uo pipefail + export PATH="$HOME/.cargo/bin:$PATH" + out=pons-findings.json + if ! command -v pons >/dev/null 2>&1; then + jq -n --arg ref "$PONS_SHA" \ + '{status: "not_run", tool: "pons-asinorum", ref: $ref, + reason: "pons binary not found on PATH after the pinned build", exit_code: null, report: null}' > "$out" + echo "::error::pons binary not found on PATH" exit 1 fi + pons --version + PONS_JSON="$RUNNER_TEMP/pons-report.json" + PONS_LOG="$RUNNER_TEMP/pons.log" + PONS_RC=0 + pons scan --format json . > "$PONS_JSON" 2> "$PONS_LOG" || PONS_RC=$? - 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" or .severity == "warn")] | length' hypatia-findings.json 2>/dev/null || echo 0) - LOW=$(jq '[.[] | select(.severity == "low")] | length' hypatia-findings.json 2>/dev/null || echo 0) + envelope() { # envelope STATUS REASON + jq -n --arg s "$1" --arg r "$2" --arg ref "$PONS_SHA" --argjson rc "${PONS_RC:-0}" \ + --slurpfile doc "${3:-/dev/null}" \ + '{status: $s, tool: "pons-asinorum", ref: $ref, reason: ($r | if . == "" then null else . end), + exit_code: $rc, report: (if ($doc | length) > 0 then $doc[0] else null end)}' > "$out" + } - 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: | - # Findings carry no `.message` (keys: action,file,line,reason,rule_module, - # severity,type), so every annotation read "null". `.file` is an absolute - # runner path, which GitHub cannot anchor to the diff, so it is made - # workspace-relative here. - jq -r --arg ws "$GITHUB_WORKSPACE" '.[] | select(.file != null) | - (.file | ltrimstr($ws + "/")) as $f | - (.reason // .message // .type // "finding") as $m | - if .severity == "critical" then - "::error file=\($f),line=\(.line // 1)::[hypatia] \($m)" - elif .severity == "high" then - "::error file=\($f),line=\(.line // 1)::[hypatia] \($m)" - else - "::warning file=\($f),line=\(.line // 1)::[hypatia] \($m)" - end - ' hypatia-findings.json || true - - name: Write step summary - if: steps.build.outputs.ready == 'true' - run: | - cat <> "$GITHUB_STEP_SUMMARY" - ## Hypatia Scan Results + if [ "$PONS_RC" -ne 0 ] || ! jq -e 'type == "object" and (.findings | type == "array")' "$PONS_JSON" >/dev/null 2>&1; then + cat "$PONS_LOG" >&2 + envelope error "pons scan failed (exit ${PONS_RC}) or produced no readable findings array" + echo "::error::pons scan failed (exit ${PONS_RC})" + exit 1 + fi + envelope ran "" "$PONS_JSON" + # ERROR counts only where pons itself does not call the finding + # speculative: a heuristic is never read as a proof. + ERR_COUNT="$(jq '[.findings[] | select((.evidence // "" | ascii_upcase) != "SPECULATIVE" and (.severity // "" | ascii_upcase) == "ERROR")] | length' "$PONS_JSON")" + WARN_COUNT="$(jq '[.findings[] | select((.severity // "" | ascii_upcase) == "WARN")] | length' "$PONS_JSON")" + INFO_COUNT="$(jq '[.findings[] | select((.severity // "" | ascii_upcase) == "INFO")] | length' "$PONS_JSON")" + { + echo "## pons-asinorum Deep Recon" + echo "" + echo "| Severity | Count |" + echo "|----------|-------|" + echo "| ERROR (non-speculative) | ${ERR_COUNT} |" + echo "| WARN | ${WARN_COUNT} |" + echo "| INFO | ${INFO_COUNT} |" + } >> "$GITHUB_STEP_SUMMARY" - | 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@v7.0.2 + - name: Upload the scanner envelopes + if: always() + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 with: - name: hypatia-findings - path: hypatia-findings.json + name: static-analysis-findings + path: | + panic-attack-findings.json + pons-findings.json + if-no-files-found: error retention-days: 90 - - name: Fail on critical security findings - if: steps.build.outputs.ready == 'true' && steps.scan.outputs.critical > 0 + + - name: Fail on critical findings + if: steps.assail.outputs.critical != '0' && steps.assail.outputs.critical != '' + env: + CRIT_COUNT: ${{ steps.assail.outputs.critical }} run: | - echo "::error::Hypatia found ${{ steps.scan.outputs.critical }} critical security issue(s) — blocking merge" + echo "::error::panic-attack found ${CRIT_COUNT} critical issue(s) — blocking merge" exit 1 + # --------------------------------------------------------------------------- - # Job 3: patch-bridge triage (CVE contextual assessment) + # Job 2: patch-bridge triage (CVE contextual assessment) # --------------------------------------------------------------------------- patch-bridge-triage: name: Patch Bridge CVE triage - runs-on: ubuntu-latest - timeout-minutes: 15 + runs-on: ubuntu-24.04 + timeout-minutes: 20 steps: - name: Checkout repository - uses: actions/checkout@v7.0.1 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: fetch-depth: 0 - - name: Install panic-attack (if available) - id: install + persist-credentials: false + + # One cache namespace only. Restoring the legacy binary without Cargo's + # install metadata made the subsequent pinned install abort rather than + # replace it, leaving patch-bridge permanently red on cache misses. + - name: Restore pinned patch-bridge scanner + uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 + id: cache-pa + with: + path: ~/.cargo/bin/panic-attack + key: patch-bridge-${{ runner.os }}-${{ env.PANIC_ATTACK_SHA }} + + - name: Build pinned panic-attack when uncached + if: steps.cache-pa.outputs.cache-hit != 'true' 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 + set -euo pipefail + cargo install --locked \ + --git https://github.com/hyperpolymath/panic-attack.git \ + --rev "$PANIC_ATTACK_SHA" + - name: Run Patch Bridge triage id: triage - if: steps.install.outputs.installed == 'true' run: | + export PATH="$HOME/.cargo/bin:$PATH" set +e - panic-attack bridge triage --format json . > bridge-report.json 2>&1 - PB_EXIT=$? + panic-attack bridge triage --format json . > bridge-report.json 2>"$RUNNER_TEMP/pb.err" set -e if [ ! -s bridge-report.json ] || ! jq empty bridge-report.json 2>/dev/null; then @@ -306,149 +263,165 @@ jobs: 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" + { + echo "unmitigable=$UNMITIGABLE" + echo "mitigated=$MITIGATED" + echo "concatenative=$CONCATENATIVE" + echo "informational=$INFORMATIONAL" + } >> "$GITHUB_OUTPUT" + - name: Write step summary - if: steps.install.outputs.installed == 'true' + env: + UNMIT: ${{ steps.triage.outputs.unmitigable }} + MIT: ${{ steps.triage.outputs.mitigated }} + CONCAT: ${{ steps.triage.outputs.concatenative }} + INFO: ${{ steps.triage.outputs.informational }} 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 }} | + { + echo "## Patch Bridge CVE Triage" + echo "" + echo "| Classification | Count |" + echo "|----------------|-------|" + echo "| Unmitigable | ${UNMIT} |" + echo "| Mitigated | ${MIT} |" + echo "| Concatenative | ${CONCAT} |" + echo "| Informational | ${INFO} |" + } >> "$GITHUB_STEP_SUMMARY" - 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@v7.0.2 + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.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 + + - name: Warn on unmitigable CVEs in critical paths + if: steps.triage.outputs.unmitigable != '0' && steps.triage.outputs.unmitigable != '' + env: + UNMIT: ${{ steps.triage.outputs.unmitigable }} 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. + echo "::warning::Patch Bridge found ${UNMIT} unmitigable CVE(s) — review required" + # --------------------------------------------------------------------------- - # Job 4: deposit-findings (combines + archives for gitbot-fleet) + # Job 3: deposit-findings (one unified report, beside the envelopes) # --------------------------------------------------------------------------- + # The unified report is for humans and for the fleet's own consumers. The + # verdict grid reads the ENVELOPES from `static-analysis-findings`, not this + # file: merging two scanners into one array discards each one's "did it run" + # fact, which is the single most important thing the grid reports. deposit-findings: name: Deposit findings for gitbot-fleet - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 timeout-minutes: 15 - needs: [panic-attack-assail, hypatia-scan, patch-bridge-triage] + needs: [panic-attack-assail, patch-bridge-triage] if: always() steps: - - name: Download panic-attack findings - uses: actions/download-artifact@v8.0.2 - with: - name: panic-attack-findings - path: findings/ - - name: Download hypatia findings - uses: actions/download-artifact@v8.0.2 + - name: Download panic-attack & pons envelopes + uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2 + continue-on-error: true with: - name: hypatia-findings + name: static-analysis-findings path: findings/ - name: Download bridge report - uses: actions/download-artifact@v8.0.2 + uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2 + continue-on-error: true with: name: bridge-report path: findings/ - name: Combine findings into unified report id: combine + env: + REPO_SLUG: ${{ github.repository }} + COMMIT_SHA: ${{ github.sha }} + GIT_REF: ${{ github.ref }} + RUN_ID: ${{ github.run_id }} run: | + mkdir -p findings PA_FILE="findings/panic-attack-findings.json" - HYP_FILE="findings/hypatia-findings.json" + PONS_FILE="findings/pons-findings.json" - # Ensure both files exist and are valid JSON arrays - for f in "$PA_FILE" "$HYP_FILE"; do + # A missing envelope is recorded, not invented: "did not run" and + # "ran clean" must never collapse into the same empty array. + for f in "$PA_FILE" "$PONS_FILE"; do if [ ! -s "$f" ] || ! jq empty "$f" 2>/dev/null; then - echo "[]" > "$f" + echo '{"status": "not_run", "tool": "unknown", "ref": null, "reason": "no envelope artifact reached this job", "exit_code": null, "report": null}' > "$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 + jq '[.report.weak_points[]? | select(.suppressed != true) | . + {"scanner": "panic-attack"}]' \ + "$PA_FILE" > "$RUNNER_TEMP/pa-tagged.json" + jq '[.report.findings[]? | . + {"scanner": "pons-asinorum"}]' \ + "$PONS_FILE" > "$RUNNER_TEMP/pons-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 repo "$REPO_SLUG" \ + --arg sha "$COMMIT_SHA" \ + --arg ref "$GIT_REF" \ + --arg run_id "$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 pa "$RUNNER_TEMP/pa-tagged.json" \ + --slurpfile pons "$RUNNER_TEMP/pons-tagged.json" \ --slurpfile bridge "$BRIDGE_FILE" \ + --slurpfile pa_env "$PA_FILE" \ + --slurpfile pn_env "$PONS_FILE" \ '{ - schema_version: "1.1.0", + schema_version: "1.2.0", repository: $repo, commit_sha: $sha, ref: $ref, run_id: $run_id, timestamp: $ts, - findings: ($pa[0] + $hyp[0]), + scanners: { + panic_attack: {status: $pa_env[0].status, ref: $pa_env[0].ref, reason: $pa_env[0].reason}, + pons_asinorum: {status: $pn_env[0].status, ref: $pn_env[0].ref, reason: $pn_env[0].reason} + }, + findings: ($pa[0] + $pons[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" or .severity == "warn")] | length' findings/unified-findings.json) - LOW=$(jq '[.findings[] | select(.severity == "low")] | length' findings/unified-findings.json) + CRITICAL=$(jq '[.findings[] | select((.severity // "" | ascii_downcase) == "critical")] | length' findings/unified-findings.json) + HIGH=$(jq '[.findings[] | select((.severity // "" | ascii_downcase) == "high" or (.severity // "" | ascii_upcase) == "ERROR")] | length' findings/unified-findings.json) + + { + echo "total=$TOTAL" + echo "critical=$CRITICAL" + echo "high=$HIGH" + } >> "$GITHUB_OUTPUT" - 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@v7.0.2 + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 with: name: unified-findings path: findings/unified-findings.json retention-days: 90 + - name: Write deposit summary + env: + REPO_SLUG: ${{ github.repository }} + COMMIT_SHA: ${{ github.sha }} + CRIT: ${{ steps.combine.outputs.critical }} + HIGH_C: ${{ steps.combine.outputs.high }} + TOT: ${{ steps.combine.outputs.total }} 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 + { + echo "## Unified Findings Deposit" + echo "" + echo "**Repository:** ${REPO_SLUG}" + echo "**Commit:** \`${COMMIT_SHA}\`" + echo "**Deposited at:** $(date -u +"%Y-%m-%d %H:%M:%S UTC")" + echo "" + echo "| Severity | Count |" + echo "|----------|-------|" + echo "| Critical | ${CRIT} |" + echo "| High (incl. pons ERROR) | ${HIGH_C} |" + echo "| **Total** | ${TOT} |" + echo "" + echo "Hypatia's findings are produced once, by \`.github/workflows/hypatia-scan.yml\`," + echo "and graded directly by the verdict grid — they are not repeated here." + } >> "$GITHUB_STEP_SUMMARY" diff --git a/.github/workflows/verdict-grid-publish.yml b/.github/workflows/verdict-grid-publish.yml new file mode 100644 index 00000000..7a67d172 --- /dev/null +++ b/.github/workflows/verdict-grid-publish.yml @@ -0,0 +1,169 @@ +# SPDX-License-Identifier: MPL-2.0 +# Trusted publisher for the read-only PR verdict-grid pipeline. +# This workflow_run file executes only when present on the default branch. +# Never check out PR-controlled code or run a downloaded artifact as a script. +name: Publish verdict grid + +on: + workflow_run: # zizmor: ignore[dangerous-triggers] + workflows: + - Fork governance + - Hypatia Security Scan + - Static Analysis Gate + types: [completed] + +permissions: {} +concurrency: + group: verdict-publish-${{ github.event.workflow_run.head_repository.full_name }}-${{ github.event.workflow_run.head_sha }} + cancel-in-progress: true + +jobs: + publish: + if: github.event.workflow_run.event == 'pull_request' + runs-on: ubuntu-24.04 + timeout-minutes: 15 + permissions: + contents: read + actions: read + pull-requests: write + env: + GH_TOKEN: ${{ github.token }} + steps: + - name: Authenticate source run and identify current pull request + id: source + run: | + set -euo pipefail + run_id=$(jq -r '.workflow_run.id' "$GITHUB_EVENT_PATH") + gh api "repos/$GITHUB_REPOSITORY/actions/runs/$run_id" > "$RUNNER_TEMP/source-run.json" + jq -e --slurpfile event "$GITHUB_EVENT_PATH" ' + .id == $event[0].workflow_run.id + and .event == "pull_request" and .status == "completed" + and .repository.full_name == $event[0].repository.full_name + and .head_sha == $event[0].workflow_run.head_sha + ' "$RUNNER_TEMP/source-run.json" >/dev/null + sha=$(jq -r '.head_sha' "$RUNNER_TEMP/source-run.json") + gh api --paginate --slurp "repos/$GITHUB_REPOSITORY/commits/$sha/pulls" > "$RUNNER_TEMP/source-prs.json" + pr=$(jq -r --arg sha "$sha" --arg repo "$GITHUB_REPOSITORY" ' + [.[][] | select(.state == "open" and .head.sha == $sha + and .base.repo.full_name == $repo)] + | if length == 1 then .[0].number else empty end + ' "$RUNNER_TEMP/source-prs.json") + if [ -z "$pr" ]; then + echo "::notice::No unique current PR at the completed run SHA; refusing to publish a stale verdict." + exit 0 + fi + echo "pr=$pr" >> "$GITHUB_OUTPUT" + echo "sha=$sha" >> "$GITHUB_OUTPUT" + + - name: Checkout trusted default-branch reporter + if: steps.source.outputs.pr != '' + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: ${{ github.event.repository.default_branch }} + persist-credentials: false + sparse-checkout: | + scripts/verdict-grid-lane.sh + .gitbot-fleet + sparse-checkout-cone-mode: false + + - name: Checkout pinned renderer + if: steps.source.outputs.pr != '' + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + repository: metadatastician/standards + ref: 8e48b1caade08a552646adeab66558ac43b4360d + path: .standards-grid + persist-credentials: false + sparse-checkout: | + scripts/verdict-grid.sh + scripts/lib/verdict-grid.jq + sparse-checkout-cone-mode: false + + - name: Collect, validate and render diagnostics as data only + if: steps.source.outputs.pr != '' + env: + TARGET_SHA: ${{ steps.source.outputs.sha }} + TARGET_PR: ${{ steps.source.outputs.pr }} + run: | + set -euo pipefail + mkdir -p "$RUNNER_TEMP/evidence" + bash scripts/verdict-grid-lane.sh collect \ + --repo "$GITHUB_REPOSITORY" --sha "$TARGET_SHA" \ + --out "$RUNNER_TEMP/evidence" \ + --source hypatia-scan.yml:hypatia-scan-findings \ + --source static-analysis-gate.yml:static-analysis-findings + # Fleet evidence lives in the read-only Fork governance PR run, + # not in this privileged publisher's own workflow_run. + fleet_run=$(gh run list --repo "$GITHUB_REPOSITORY" \ + --workflow fork-governance.yml --commit "$TARGET_SHA" --event pull_request --limit 20 \ + --json databaseId,status,event | jq -r \ + '[.[] | select(.event == "pull_request" and .status == "completed")] | sort_by(.databaseId) | last | .databaseId // empty') + if [ -n "$fleet_run" ]; then + mkdir -p "$RUNNER_TEMP/evidence/fleet-report-backs" + gh run download "$fleet_run" --repo "$GITHUB_REPOSITORY" \ + --name fleet-report-backs \ + --dir "$RUNNER_TEMP/evidence/fleet-report-backs" || \ + echo "::warning::Fleet evidence unavailable; fleet rows will remain orange" + fi + ev="$RUNNER_TEMP/evidence" + evidence_ok=1 + if ! bash scripts/verdict-grid-lane.sh validate \ + --hypatia "$ev/hypatia-scan-findings/hypatia-findings.relativized.json" \ + --panic "$ev/static-analysis-findings/panic-attack-findings.json" \ + --pons "$ev/static-analysis-findings/pons-findings.json" \ + --enrolment .gitbot-fleet/enrolment.json; then + echo "::warning::Producer evidence is malformed; publishing an indeterminate (orange) report, never a stale green result." + evidence_ok=0 + fi + if ! gh api --paginate "repos/$GITHUB_REPOSITORY/pulls/$TARGET_PR/files?per_page=100" \ + --jq '.[].filename' > "$RUNNER_TEMP/changed-files.txt"; then + echo "::warning::Changed-file scope could not be established; refusing a misleading scoped verdict." + evidence_ok=0 + fi + if ! bash scripts/verdict-grid-lane.sh previous \ + --repo "$GITHUB_REPOSITORY" --pr "$TARGET_PR" \ + --out "$RUNNER_TEMP/previous.md"; then + echo "::warning::No trustworthy previous grid is available for a delta." + : > "$RUNNER_TEMP/previous.md" + fi + args=(render --out "$RUNNER_TEMP/verdict-grid" \ + --renderer-dir .standards-grid \ + --repo "$GITHUB_REPOSITORY" \ + --sha "$TARGET_SHA" --run "$GITHUB_RUN_ID" --pr "$TARGET_PR" \ + --url "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID" \ + --enrolment .gitbot-fleet/enrolment.json \ + --hypatia "$ev/hypatia-scan-findings/hypatia-findings.relativized.json" \ + --panic "$ev/static-analysis-findings/panic-attack-findings.json" \ + --pons "$ev/static-analysis-findings/pons-findings.json" \ + --hypatia-ref be98f74ce93df200752f3798efa1305bfa3e0e10 \ + --panic-ref b5530834a839734d1d181bfe6edb0d43d4233cf4 \ + --pons-ref 51b8920f541782ceb9465ea3f0d33c96104fc1fb) + [ ! -d "$ev/fleet-report-backs" ] || args+=(--report-backs "$ev/fleet-report-backs") + [ ! -s "$RUNNER_TEMP/previous.md" ] || args+=(--previous "$RUNNER_TEMP/previous.md") + args+=(--changed "$RUNNER_TEMP/changed-files.txt") + if [ "$evidence_ok" -eq 1 ]; then + if ! bash scripts/verdict-grid-lane.sh "${args[@]}"; then + echo "::warning::Verdict rendering failed; replacing the report with an explicit indeterminate state." + evidence_ok=0 + fi + fi + if [ "$evidence_ok" -ne 1 ]; then + mkdir -p "$RUNNER_TEMP/verdict-grid" + cat > "$RUNNER_TEMP/verdict-grid/report.md" <<'REPORT' + + ### Verdict grid: indeterminate + + Producer evidence was malformed, unreadable or could not be rendered. + No green result or comparative delta can be asserted for this revision. + See the trusted publisher workflow run for details. + REPORT + printf '%s\n' '{"schemaVersion":1,"label":"Hypatia grid","message":"indeterminate","color":"orange"}' > "$RUNNER_TEMP/verdict-grid/badge.json" + printf '%s\n' '{"state":"orange","reason":"unverified producer evidence"}' > "$RUNNER_TEMP/verdict-grid/report.json" + fi + # Recheck freshness immediately before the write; do not publish + # a completed scan from a now-superseded head. + gh api "repos/$GITHUB_REPOSITORY/pulls/$TARGET_PR" | + jq -e --arg sha "$TARGET_SHA" '.state == "open" and .head.sha == $sha' >/dev/null + bash scripts/verdict-grid-lane.sh comment \ + --repo "$GITHUB_REPOSITORY" --pr "$TARGET_PR" \ + --report "$RUNNER_TEMP/verdict-grid" diff --git a/.github/workflows/workflow-linter.yml b/.github/workflows/workflow-linter.yml index 35dfd9d5..ea89dfa7 100644 --- a/.github/workflows/workflow-linter.yml +++ b/.github/workflows/workflow-linter.yml @@ -21,7 +21,7 @@ permissions: jobs: lint-workflows: - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 timeout-minutes: 15 permissions: contents: read @@ -67,12 +67,17 @@ jobs: echo "All workflows have permissions declared" # Bun is the estate's first-choice runtime (LANGUAGE-POLICY.adoc §1: - # Bun > Deno > pnpm > npm) and executes .ts directly (§1.2). Tag form - # matches every other ref in this repo and is resolved by actions.lock. - - name: Set up Bun - uses: oven-sh/setup-bun@v2.2.0 - with: - bun-version: latest + # Bun > Deno > pnpm > npm). It is the estate pin 1.4.2, downloaded and + # sha256-checked as Estate Rules installs its tools, so this gate runs + # no third-party action and no unpinned runtime. + - name: Install verified Bun 1.4.2 + run: | + curl --proto '=https' --proto-redir '=https' --fail --silent --show-error --location \ + https://github.com/oven-sh/bun/releases/download/bun-v1.4.2/bun-linux-x64.zip \ + --output "$RUNNER_TEMP/bun.zip" + echo "36368faef7527875d5ffa52e53cd48021741f2a83eb6208a8dd64068d422a913 $RUNNER_TEMP/bun.zip" | sha256sum --check --strict + unzip -q "$RUNNER_TEMP/bun.zip" -d "$RUNNER_TEMP" + echo "$RUNNER_TEMP/bun-linux-x64" >> "$GITHUB_PATH" - name: Check SHA-Pinned Actions run: | diff --git a/.gitignore b/.gitignore index a3020519..638db641 100644 --- a/.gitignore +++ b/.gitignore @@ -120,7 +120,7 @@ dist/ .machine_readable/arrival-pack/claude-md-data.json # Coaptation atomiser artifacts (regenerated from contractiles + descriptiles); -# the receipt itself (receipts/latest.a2ml) IS committed as the drift baseline. +# the receipt itself (receipts/latest.toml) IS committed as the drift baseline. .machine_readable/coaptation/clauses.json .machine_readable/coaptation/facts.json @@ -128,7 +128,7 @@ dist/ .machine_readable/coaptation/core/build/ # Coaptation re-anchor basis (occasional, generated on --reanchor when red; not a baseline) -.machine_readable/coaptation/receipts/reanchor-basis.a2ml +.machine_readable/coaptation/receipts/reanchor-basis.toml # Generated by `just cookbook` (has timestamp; non-deterministic) docs/just-cookbook.adoc @@ -142,7 +142,5 @@ verification/proofs/coq/*.vos verification/proofs/coq/*.glob verification/proofs/coq/.*.aux # Agda compiled proof artifacts -# Agda interface files are build output (regenerated on every check; the gate -# runs with --ignore-interfaces), never source. -*.agdai +verification/proofs/agda/*.agdai diff --git a/.hypatia-ignore b/.hypatia-ignore index 1722a94d..41563b7a 100644 --- a/.hypatia-ignore +++ b/.hypatia-ignore @@ -53,3 +53,10 @@ research_extensions/RE005:.github/workflows/static-analysis-gate.yml # Dependabot workflow uses the unprivileged pull_request event and also verifies # github.event.pull_request.user.login, so that threat model does not apply. research_extensions/RE008:.github/workflows/dependabot-automerge.yml + +# wrong_sha_pin compares 40-hex action pins against Hypatia's static May-2026 +# @sha_pins table (e.g. actions/checkout@v4 vs the current actions/checkout@v7.0.1 +# and ossf/scorecard-action@v2.5.0). Authoritative pin verification is enforced by +# .github/workflows/actions.lock + scripts/check-lock-sync.sh + GitHub's native +# lockfile verifier on every workflow run. +workflow_audit/wrong_sha_pin:.github/workflows/ diff --git a/.machine_readable/ENSAID_CONFIG.a2ml b/.machine_readable/ENSAID_CONFIG.a2ml deleted file mode 100644 index 1384822c..00000000 --- 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 index fd6b7197..d7489cde 100644 --- a/.machine_readable/README.adoc +++ b/.machine_readable/README.adoc @@ -16,16 +16,18 @@ document is the only place the syntax, semantics and typechecking rules are defined. Every other mention of the format across the estate — including every README in this tree — is a *pointer* to it, never a restatement. -The format formerly called A2ML is now *DEED* (`.deed`). Files here still -carry `.a2ml` pending a single atomic estate-wide rename; do not -hand-convert them. +The format formerly called A2ML is now *DEED* (`.deed`), and no `.a2ml` +file may exist in this repository. The descriptive records are clauses of +the repo deed (`*_chora.deed`) at the repo root, read with +`scripts/deed-field.sh` and written with `scripts/deed-clause.sh`. ==== == Contents `descriptiles/`:: What this repository *is* and what state it is *in* — -`META`, `STATE`, `ECOSYSTEM`, `PLAYBOOK`, `AGENTIC`, `NEUROSYM`, plus the -anchors and the facet record. See `descriptiles/README.adoc`. +the repo deed's `(meta)`, `(status)`, `(ecosystem)`, `(playbook)`, +`(agentic)` and `(neurosym)` clauses, plus the `(anchor)` clause and the +facet record. See `descriptiles/README.adoc`. `contractiles/`:: What this repository *ought* to do — the Must, Trust, Adjust, Intend, Bust and Dust verb sets, each with its declaration, its @@ -34,7 +36,8 @@ Nickel runner and its k9 service-automation component. See `arrival-pack/`:: The entry pack for agents visiting this repository. -`policies/`:: Maintenance axes and related policy records. +`policies/`:: Maintenance axes and related policy records, now the repo +deed's `(policies …)` clauses. -`rsr-profile.a2ml`:: This repository's declared RSR v2.0 capabilities, +`(rsr-profile)` (repo deed clause):: This repository's declared RSR v2.0 capabilities, which gate which conformance criteria apply to it. diff --git a/.machine_readable/ai/AI.a2ml b/.machine_readable/ai/AI.a2ml deleted file mode 100644 index d25039f1..00000000 --- a/.machine_readable/ai/AI.a2ml +++ /dev/null @@ -1,38 +0,0 @@ -# SPDX-License-Identifier: MPL-2.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/descriptiles/STATE.a2ml` for blockers and next actions. -2. Respect any constraints listed inside `.machine_readable/descriptiles/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 the repo deed (_chora.deed) 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 index b10b863f..a2ba9875 100644 --- a/.machine_readable/ai/PLACEHOLDERS.adoc +++ b/.machine_readable/ai/PLACEHOLDERS.adoc @@ -23,7 +23,7 @@ validates the result, and runs k9-svc checks if available. 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_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}}' .) @@ -45,13 +45,29 @@ sed -i "s/{{CURRENT_DATE}}/$(date +%Y-%m-%d)/g" $(grep -rl '{{CURRENT_DATE}}' .) | `{{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 | +| `{{AUTHOR_ORCID}}` | Author ORCID iD, bare form; blank drops the line (default: `git config user.orcid`) | `0000-0002-1825-0097` | CITATION.cff | ### Project Identity +Three DIFFERENT things are named "the project" and they are three different +tokens. Conflating them is how a repository ends up with a display name where an +identifier belongs: + +* `{{PROJECT_NAME}}` — what a human reads: spaces, capitals, punctuation. +* `{{PROJECT}}` / `{{project}}` — what a compiler reads: an identifier, so no + spaces and no hyphens. `{{PROJECT}}` is the uppercase form (Idris2 modules, C + macros); `{{project}}` is the lowercase form (C symbols, file names, crate + and module names). +* `{{REPO}}` — what a forge reads: the repository slug. + +They may look alike today (`My Project` / `MY_PROJECT` / `my_project` / +`my-project`) and they are still four tokens, because each is filled from a +different answer in `just repo-init`. A file that needs all four needs all four. + | 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, devcontainer.json | -| `{{PROJECT_DESCRIPTION}}` | One-line description | `A tool for X` | README.adoc, build/container/Containerfile | +| `{{PROJECT_NAME}}` | Human-readable project name | `My Project` | SECURITY.md, CODE_OF_CONDUCT.md, TOPOLOGY.md, docs/status/ROADMAP.adoc (via build/templates/ROADMAP.adoc.in), Justfile, GOVERNANCE.md, MAINTAINERS.md, devcontainer.json | +| `{{PROJECT_DESCRIPTION}}` | One-line description | `A tool for X` | README.adoc, CITATION.cff, the repo deed | | `{{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 | @@ -63,7 +79,7 @@ sed -i "s/{{CURRENT_DATE}}/$(date +%Y-%m-%d)/g" $(grep -rl '{{CURRENT_DATE}}' .) | 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 | +| `{{CURRENT_DATE}}` | Current date (ISO) | `2026-02-14` | `*_chora.deed` (via build/templates/identity.deed.in), MAINTAINERS.md | | `{{DATE}}` | Last updated date | `2026-02-14` | TOPOLOGY.md, THREAT-MODEL.md | ### Contact & Security @@ -89,7 +105,7 @@ sed -i "s/{{CURRENT_DATE}}/$(date +%Y-%m-%d)/g" $(grep -rl '{{CURRENT_DATE}}' .) | 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 | +| `{{PROJECT_PURPOSE}}` | One-line project description | `FFI bridges between languages` | `*_chora.deed` `(anchor (identity))` :one-sentence (set from `{{PROJECT_DESCRIPTION}}` by `just repo-init`) | | `{{OPENSSF_BP_ID}}` | OpenSSF Best Practices numeric project ID (from registering at bestpractices.dev). Optional — leave blank until registered; `just repo-init` then surfaces it in the post-init "remaining placeholders" notice as a reminder. | `1234` | README.adoc (OpenSSF Best Practices badge) | ### Project Content & Onboarding (manual-fill, post-init) @@ -110,12 +126,12 @@ surfaces any left unfilled. | `{{BUILD_OUTPUT_PATH}}` | Build artefact output path | `build/` | docs/onboarding/QUICKSTART-MAINTAINER.adoc | | `{{DEPS}}` | Project dependencies summary | `Idris2 0.7, Zig 0.13` | docs/onboarding/QUICKSTART-MAINTAINER.adoc | | `{{MUST_INVARIANTS}}` | Required project invariants | `no believe_me; totality on` | docs/onboarding/QUICKSTART-DEV.adoc | -| `{{MAIN_FUNCTION}}` | Primary function / purpose | `FFI bridge generation` | machine-readable-design/canonical-directory-structure/Intentfile.a2ml | -| `{{TARGET_AUDIENCE}}` | Intended audience | `library authors` | machine-readable-design/canonical-directory-structure/Intentfile.a2ml | -| `{{EXPECTED_AUTHOR}}` | Expected author identity (trust anchor) | `hyperpolymath` | machine-readable-design/canonical-directory-structure/Trustfile.a2ml | -| `{{PROJECT_UNIQUE_STRENGTH}}` | What this project does better than alternatives | `proof-carrying FFI` | .machine_readable/bot_directives/methodology.a2ml | -| `{{PROJECT_KIND}}` | Project kind / category | `library` | .machine_readable/descriptiles/anchors/ANCHOR.a2ml | -| `{{PROJECT_DOMAIN}}` | Project domain | `formal-methods` | .machine_readable/descriptiles/anchors/ANCHOR.a2ml | +| `{{MAIN_FUNCTION}}` | Primary function / purpose | `FFI bridge generation` | no file in this template (the retired Intentfile is now `.machine_readable/contractiles/intend/intend.k9.ncl`, which does not carry the token) | +| `{{TARGET_AUDIENCE}}` | Intended audience | `library authors` | no file in this template (the retired Intentfile is now `.machine_readable/contractiles/intend/intend.k9.ncl`, which does not carry the token) | +| `{{EXPECTED_AUTHOR}}` | Expected author identity (trust anchor) | `hyperpolymath` | no file in this template (the retired Trustfile is now `.machine_readable/contractiles/trust/trust.k9.ncl`, which does not carry the token) | +| `{{PROJECT_UNIQUE_STRENGTH}}` | What this project does better than alternatives | `proof-carrying FFI` | `*_chora.deed` `(bot-directives (methodology (methodology (unique-strength))))` :description | +| `{{PROJECT_KIND}}` | Project kind / category | `library` | `*_chora.deed` `(anchor (identity))` :kind | +| `{{PROJECT_DOMAIN}}` | Project domain | `formal-methods` | `*_chora.deed` `(anchor (identity))` :domain | | `{{OPENSSF_PROJECT_ID}}` | OpenSSF Best Practices project ID (same value as `{{OPENSSF_BP_ID}}`) | `1234` | docs/governance/TEMPLATE-STANDARDS-AUDIT.adoc | ### Repo deed (folded family-7 allocation manifest) @@ -125,7 +141,7 @@ surfaces any left unfilled. | `[YOUR-REPO-NAME]` | Repository name | `my-project` | `*_chora.deed` (repo deed) | | `[YOUR-NAME/ORG]` | Maintainer name | `hyperpolymath` | `*_chora.deed` (repo deed) | -(`[DATE]` was listed here for 0-AI-MANIFEST.a2ml but no file ever carried the +(`[DATE]` was listed here for the root AI manifest but no file ever carried the literal token — row removed with the fold; standards#837 pilot.) ### AI Installation Guide @@ -162,7 +178,7 @@ Some files contain deletion instructions: After replacing all placeholders, verify none remain: ```bash -grep -rn '{{' . --include='*.md' --include='*.adoc' --include='*.a2ml' \ +grep -rn '{{' . --include='*.md' --include='*.adoc' --include='*.deed' \ --include='*.scm' --include='*.idr' --include='*.zig' --include='*.res' \ --include='Justfile' --include='*.nix' --include='*.toml' --include='*.yml' \ --include='*.yaml' --include='*.hs' --include='*.ncl' --include='*.txt' \ diff --git a/.machine_readable/ai/README.adoc b/.machine_readable/ai/README.adoc index a5dec599..628a0c5a 100644 --- a/.machine_readable/ai/README.adoc +++ b/.machine_readable/ai/README.adoc @@ -2,23 +2,74 @@ // Copyright (c) Jonathan D.A. Jewell = AI Guidance Directory -Put AI-facing instructions in this folder. +Put AI-facing instructions in this folder (for example `CLAUDE.md`, +`COPILOT.md`, `GEMINI.md`, `AI.djot`). Avoid scattering agent instruction +files around the repo root. Machine-readable facts do not live here: they are +clauses of the repo deed (`*_chora.deed`) at the repo root, read with +`scripts/deed-field.sh`. There are no `.a2ml` files in this estate. -Examples: +== Recommended machine read order -* `CLAUDE.md` -* `COPILOT.md` -* `GEMINI.md` -* `AI.a2ml` -* `AI.djot` +* the repo deed's `(anchor)` clause — semantic authority and golden path +* the repo deed's `(policies)` clause — `(maintenance-axes)`, + `(maintenance-checklist)`, `(software-development-approach)`, + `(crg-criteria)`, `(tsdm)` +* the repo deed's `(status)`, `(maturity)` and `(meta)` clauses +* `docs/status/ROADMAP.adoc` -Avoid scattering agent instruction files around the repo root. +== AI assistant instructions -Recommended machine read order: +=== Repository focus -* `.machine_readable/descriptiles/anchors/ANCHOR.a2ml` -* `.machine_readable/policies/MAINTENANCE-AXES.a2ml` -* `.machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml` -* `.machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml` -* `.machine_readable/descriptiles/STATE.a2ml` -* `.machine_readable/descriptiles/META.a2ml` +* This repository is a Rhodium Standard Repository; obey the Rhodium policies + and keep the repo deed and `.machine_readable/` authoritative. +* Machine-readable content is the repo deed (`*_chora.deed`, at the root) plus + `.machine_readable/` (contractiles, bot-directive and integration clauses are + in the deed). +* Keep generated files out of source control, and regenerate them with the + documented commands before committing. + +=== Workflow + +. Read `docs/status/ROADMAP.adoc` for blockers and next actions, and the repo + deed's `(status)` clause for the phase. +. Respect the constraints in the repo deed's `(agentic)` clause when tooling + changes are requested. +. After finishing edits, update `docs/status/ROADMAP.adoc` with your outcomes + and commit with a concise, imperative message. + +=== Delivery promises + +* Say in summaries whether the repo deed, `docs/status/ROADMAP.adoc` or + `.machine_readable/contractiles/` 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; their configuration is the repo +deed's `(integrations)` clause. + +[cols="1,3"] +|=== +| 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 + +. The repo deed (`_chora.deed`) exists at the repo root and lints. +. The contractiles exist: `.machine_readable/contractiles//.k9.ncl` + for must, trust and dust at least. +. The `assail` recipe is in the Justfile and wired into the pre-commit hook. +. The deed's `(integrations (proven))` clause is filled in. +. The deed's `(integrations (verisimdb))` feed is configured. +. The deed's `(integrations (feedback-o-tron))` clause is filled in for + upstream reporting. +. The deed's `(integrations (vexometer))` hooks are set (CLI/UI repos). diff --git a/.machine_readable/arrival-pack/README.adoc b/.machine_readable/arrival-pack/README.adoc index a48f9fd9..8c857014 100644 --- a/.machine_readable/arrival-pack/README.adoc +++ b/.machine_readable/arrival-pack/README.adoc @@ -10,9 +10,9 @@ the repo's own machine-readable truth. [source] ---- -a2ml (descriptiles) extract.sh arrival-pack.ncl CLAUDE.md -CLADE/ECOSYSTEM/ ──▶ (a2ml → JSON, ──▶ (Nickel projection ──▶ region between -AGENTIC/STATE/ANCHOR the thin reader) = the engine) BEGIN/END markers +_chora.deed extract.sh arrival-pack.ncl CLAUDE.md ++ anchors/ANCHOR ──▶ (deed → JSON, ──▶ (Nickel projection ──▶ region between + the thin reader) = the engine) BEGIN/END markers ---- Two halves of the generated region: @@ -20,17 +20,20 @@ Two halves of the generated region: * *Estate-common* — identical in every repo; the Manifesto doctrine + format-family orientation + canon pointers + language policy. Pinned to a Manifesto SHA once the wording is ratified (today: `DRAFT-unratified`). -* *Repo-specific* — projected from this repo's a2ml: identity, IS / IS-NOT, +* *Repo-specific* — projected from this repo's deed: identity, IS / IS-NOT, position, constraints, golden path, state. -The a2ml files remain the single source of truth. CLAUDE.md is a *view*. Content +The repo deed (`_chora.deed`) is the single source of truth; it took +over the former CLADE / ECOSYSTEM / AGENTIC / STATE records (rsr-template-repo#209), and +`extract.sh` reads it through `scripts/deed-field.sh`. The golden path +comes from its `(anchor (golden-path))` clause. CLAUDE.md is a *view*. Content outside the `ARRIVAL-PACK:BEGIN/END` markers is hand-authorable and preserved. == Files [cols="1,3"] |=== -| `extract.sh` | a2ml reader → deterministic `claude-md-data.json` (build artifact, git-ignored) +| `extract.sh` | deed reader → deterministic `claude-md-data.json` (build artifact, git-ignored) | `arrival-pack.ncl` | Nickel projection engine → the region string (`nickel export --format raw`) | `generate.sh` | orchestrator: extract → render → splice (Hunt-tier, writes CLAUDE.md) | `verify.sh` | drift check: regenerate + byte-compare committed region (Yard-tier) @@ -41,7 +44,7 @@ outside the `ARRIVAL-PACK:BEGIN/END` markers is hand-authorable and preserved. [source,console] ---- -just claude-md # (re)generate CLAUDE.md from a2ml +just claude-md # (re)generate CLAUDE.md from the repo deed just validate-claude-md # fail if the committed region drifted / was hand-edited ---- @@ -51,5 +54,5 @@ just validate-claude-md # fail if the committed region drifted / was hand-edit his voice, then pin to a `hyperpolymath/manifesto` commit SHA. * `ECOSYSTEM.what-this-is-not` is empty here, so IS-NOT renders as "not yet declared". Populating it is the boundary-erosion fix (the `lith` lesson). -* `ANCHOR.a2ml` currently encodes semantic-authority + golden-path; the +* The `(anchor)` clause currently encodes semantic-authority + golden-path; the recognised-drift / re-anchor-ledger aspect is a pending standards change. diff --git a/.machine_readable/arrival-pack/arrival-pack.ncl b/.machine_readable/arrival-pack/arrival-pack.ncl index 03249905..309ae434 100644 --- a/.machine_readable/arrival-pack/arrival-pack.ncl +++ b/.machine_readable/arrival-pack/arrival-pack.ncl @@ -3,16 +3,16 @@ # # arrival-pack.ncl — the projection ENGINE for the CLAUDE.md arrival pack. # -# Pure Nickel. Imports the deterministic JSON produced by extract.sh (the a2ml +# Pure Nickel. Imports the deterministic JSON produced by extract.sh (the deed # reader) and renders the generated CLAUDE.md region as a single string. # Emit with: nickel export --format raw --file arrival-pack.ncl # # Two halves (see ARRIVAL-PACK-DESIGN): # A. estate-common — identical everywhere; DRAFT doctrine, pinned to a # Manifesto SHA once ratified (today: DRAFT-unratified). -# B. repo-specific — projected from this repo's a2ml (data.*). +# B. repo-specific — projected from this repo's deed (data.*). # -# The a2ml files remain the single source of truth; this is a VIEW. Hand-editing +# The deed remains the single source of truth; this is a VIEW. Hand-editing # the emitted region is a flagged error (see claude-md.k9.ncl drift check). let data = import "claude-md-data.json" in @@ -20,11 +20,11 @@ let data = import "claude-md-data.json" in # owner's voice. Until then the estate-common block is explicitly DRAFT. let manifesto_pin = "DRAFT-unratified" in -let provenance = "CLADE@%{data.h_clade} ECOSYSTEM@%{data.h_eco} AGENTIC@%{data.h_agentic} STATE@%{data.h_state} ANCHOR@%{data.h_anchor}" +let provenance = "DEED@%{data.h_deed} ANCHOR@%{data.h_anchor}" in m%" - + # You are in the hyperpolymath estate — orient before acting @@ -48,31 +48,41 @@ If you are unsure what something is, **read the canon; do not guess** (guessing 15. **Elegance by default** — treat the most elegant and correct long-term option as the default arm; when you put a choice to the owner, LABEL which option that is, and if you recommend another, name both arms and say why you depart. Binds unasked design calls too: report the departure, never absorb it. ## The machine-readable substrate (read in this order on arrival) -**CLADE** → **ANCHOR** → **AGENTIC** → **ECOSYSTEM** → **STATE** +**CHORA** → **ANCHOR** → **AGENTIC** → **ECOSYSTEM** → **STATE** -> **NEUROSYM** -> **PLAYBOOK** + +ANCHOR, AGENTIC, ECOSYSTEM, STATE, NEUROSYM and PLAYBOOK are clauses of the CHORA deed — `(anchor)`, `(agentic)`, `(ecosystem)`, `(status)` and `(maturity)`, `(neurosym)`, `(playbook)` — not files; STATE's journal is `docs/status/ROADMAP.adoc`. There are no `.a2ml` files in this estate. The descriptive family (working name *descriptiles*) describes what-is; the **contractiles** are the normative set-point. | File | Answers | |---|---| -| `CLADE.a2ml` | *Identity / lineage* — what this repo IS (registers into `gv-clade-index`). | -| `ANCHOR.a2ml` | *Semantic authority + golden path* — what downstream may extend-not-redefine; if a recognised-drift / re-anchor marker is present, it **supersedes** accumulated context — read it first. | -| `META.a2ml` | *Concept / constitutional authority* — ADRs, what's permitted. | -| `AGENTIC.a2ml` | *May I act now?* — permissions, risk gating, fail-safe-deny. | -| `ECOSYSTEM.a2ml` | *Where it sits* — estate + external relations, and `what-this-is-not`. | -| `NEUROSYM.a2ml` | *Meaning* of operations — proof obligations. | -| `PLAYBOOK.a2ml` | *How* permitted actions run. | -| `STATE.a2ml` | *Where things are now* — progress, blockers, next-actions. | +| `%{data.deed}` | **CHORA**, the repo deed. Its `(identity)` `(clade)` `(lineage)` clauses say what this repo IS (registers into `gv-clade-index`); `(meta)` the architecture axes; `(agentic)` *may I act now?*; `(ecosystem)` where it sits and what it is not; `(status)` and `(maturity)` where it is now. Read fields with `scripts/deed-field.sh`. | +| `(anchor)` | *Semantic authority + golden path* — what downstream may extend-not-redefine; if a recognised-drift / re-anchor marker is present, it **supersedes** accumulated context — read it first. | +| `(neurosym)` | *Meaning* of operations — proof obligations. | +| `(playbook)` | *How* permitted actions run. | +| `docs/status/ROADMAP.adoc` | *What is next* — milestones, blockers, next actions. | | contractiles | Normative doctrine: **Intend** (north-star) · **Must** (invariants) · **Trust** (security) · **Adjust** (accessibility / inclusive design) — the integral core that holds strong; plus **Dust** (exnovation drift) · **Bust** (failure / breakage, not drift). | | k9 | *Validation*. Kennel (data) / Yard (pure eval) / Hunt (guarded exec). | ## Canon pointers +Estate data-format route: **kyq** handles exactly **TOML, Dhall, KYAML, +I-JSON/JCS**. Preserve TOML/Dhall; migrate YAML/YML to KYAML and JSON variants +through kyq using **hyperpolymath/ijson-jcs**, the actual estate implementation +repository. **kyX** owns wider projection. DEED/K9/coordination keep their own +grammars. Canon: `metadatastician/standards/3-practice/DATA-FORMAT-ROUTING.adoc`. +Planned support is not operational evidence: retain explicit transitional +checks until a pinned kyq executable passes positive and negative tests. + - `hyperpolymath/standards` — the canon source. · `hyperpolymath/gv-clade-index` — the estate map (identity registry). · `hyperpolymath/manifesto` — this doctrine. - **Before you invent, rename, or consolidate anything: STOP and check the map + IS-NOT.** ## Estate language policy (overridable per-repo via AGENTIC) -Deny: **Nix, Python, Go, TypeScript, AGPL**. (Guix, not Nix.) -JavaScript tooling order: **Bun** (default) > Deno (grandfathered) > pnpm > npm (last resort, permitted). -Use plain JavaScript when this tooling is needed. The "use ReScript" rule is retired — ReScript is no longer used in this estate. Do not migrate Bun to Deno. +Deny: **Nix, Python, Go, TypeScript, ReScript, AGPL**. (Guix, not Nix.) +JavaScript runtime: **Bun** > Deno > pnpm > npm (last resort, permitted), from one `package.json` that carries every runtime's lock (`bun.lock`, `deno.lock`, `pnpm-lock.yaml`), all written by `js-runtimes regen` (owner ruling 2026-10-14, standards LANGUAGE-POLICY §1.3–§1.4). Deno is permitted again; `package-lock.json` stays refused. +Use plain JavaScript when this tooling is needed. TypeScript and ReScript migrate to AffineScript. + +## Asking the owner +Put every question that needs the owner's decision through the selector (the AskUserQuestion tool), not as prose at the end of a report. Batch up to four per call, offer concrete options with the recommended one first, and say what each option would cause. --- @@ -82,9 +92,9 @@ Use plain JavaScript when this tooling is needed. The "use ReScript" rule is ret - **IS** — %{data.purpose} - **IS-NOT** — %{data.isnot} - **Where it sits** — pipeline position **%{data.pipeline_pos}**; chain `%{data.chain}`; coordination = `%{data.coordination}`. -- **Constraints here** (AGENTIC) — fail-closed; evidence-per-step; no-silent-skip; rerun-after-fix; release-claim-requires-hard-pass. Never: banned langs (above), secrets, state files in repo root, AGPL. Details: `.machine_readable/bot_directives/{methodology,coverage,debt}.a2ml`. +- **Constraints here** (AGENTIC) — fail-closed; evidence-per-step; no-silent-skip; rerun-after-fix; release-claim-requires-hard-pass. Never: banned langs (above), secrets, state files in repo root, AGPL. Details: the deed's `(bot-directives (methodology) (coverage) (debt))` clauses. - **Golden path** (ANCHOR) — `%{data.golden_smoke}` → %{data.golden_crit}. -- **State** — phase %{data.phase}; maturity %{data.maturity}; %{data.completion}% complete; status %{data.status}. +- **State** — phase %{data.phase}; maturity %{data.maturity}. Milestones and next actions: `docs/status/ROADMAP.adoc`. "% diff --git a/.machine_readable/arrival-pack/claude-md.k9.ncl b/.machine_readable/arrival-pack/claude-md.k9.ncl index d3fbb1cf..6685d812 100644 --- a/.machine_readable/arrival-pack/claude-md.k9.ncl +++ b/.machine_readable/arrival-pack/claude-md.k9.ncl @@ -5,13 +5,14 @@ K9! # claude-md.k9.ncl — k9 contract for the CLAUDE.md arrival-pack drift check. # # Yard-tier (pure evaluation / comparison; no exec, no network, no FS write): -# the check regenerates the arrival-pack region from this repo's a2ml and asserts +# the check regenerates the arrival-pack region from this repo's deed and asserts # the committed CLAUDE.md region byte-matches it. The runnable side is verify.sh; # writing (Hunt-tier) is generate.sh. This record documents and validates the # contract shape. { pedigree = { schema_version = "1.0.0", + component_type = "drift-check:claude-md-arrival-pack", contractile_verb = "trust", # provenance: the view must equal its source semantics = "projection-fidelity", security = { @@ -19,12 +20,12 @@ K9! trust_level = "read-only comparison", allow_network = false, allow_filesystem_write = false, - allow_subprocess = true, # runs extract.sh + nickel to reproduce the view + allow_subprocess = false, # verify.sh runs extract.sh + nickel; this record does not }, metadata = { name = "claude-md-arrival-pack", version = "1.0.0", - description = "CLAUDE.md arrival pack is a faithful projection of this repo's a2ml.", + description = "CLAUDE.md arrival pack is a faithful projection of this repo's deed.", paired_runner = "verify.sh", writer = "generate.sh", author = "Jonathan D.A. Jewell ", @@ -33,12 +34,10 @@ K9! # Inputs the projection reads (single source of truth). inputs = { + # The repo deed (_chora.deed) is the only input; the golden path is + # its (anchor (golden-path)) clause (rsr-template-repo#209). descriptiles = [ - ".machine_readable/descriptiles/CLADE.a2ml", - ".machine_readable/descriptiles/ECOSYSTEM.a2ml", - ".machine_readable/descriptiles/AGENTIC.a2ml", - ".machine_readable/descriptiles/STATE.a2ml", - ".machine_readable/descriptiles/anchors/ANCHOR.a2ml", + "_chora.deed", ], estate_common = "hyperpolymath/manifesto@", # DRAFT-unratified today target = "CLAUDE.md", @@ -47,7 +46,7 @@ K9! # Checks (all must hold). checks = [ - { id = "inputs-exist", desc = "every descriptiles input file exists and parses" }, + { id = "inputs-exist", desc = "exactly one repo deed exists, parses and carries (anchor (golden-path))" }, { id = "region-present", desc = "CLAUDE.md contains exactly one BEGIN/END region" }, { id = "no-drift", desc = "committed region byte-equals freshly generated region" }, ], diff --git a/.machine_readable/arrival-pack/extract.sh b/.machine_readable/arrival-pack/extract.sh index c0adf707..4eeb4ebe 100755 --- a/.machine_readable/arrival-pack/extract.sh +++ b/.machine_readable/arrival-pack/extract.sh @@ -2,88 +2,120 @@ # SPDX-License-Identifier: MPL-2.0 # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) # -# extract.sh — the thin a2ml *reader* for the arrival-pack compiler. +# extract.sh — the thin *reader* for the arrival-pack compiler. # -# Projects the scalar/array fields the CLAUDE.md arrival pack needs out of this -# repo's descriptive a2ml (the "descriptiles" family: CLADE/ECOSYSTEM/AGENTIC/STATE + -# anchors/ANCHOR) into a single deterministic JSON document on stdout. +# Projects the fields the CLAUDE.md arrival pack needs out of this repo's deed +# (_chora.deed: identity, clade, lineage, status, maturity, ecosystem, +# agentic, and the golden path in its (anchor) clause) into a single +# deterministic JSON document on stdout. Every deed read goes through +# scripts/deed-field.sh; there are no .a2ml inputs (rsr-template-repo#209). # -# This is a READER only — it authors nothing. The a2ml files remain the single +# This is a READER only — it authors nothing. The deed remains the single # source of truth; arrival-pack.ncl renders this JSON into the CLAUDE.md region. # Determinism (no timestamps) is required so the k9 drift check can byte-compare. set -euo pipefail +# A failed $(…) inside a function or assignment must stop the run, not read as "". +shopt -s inherit_errexit -DIR6A2="${1:-.machine_readable/descriptiles}" -CLADE="$DIR6A2/CLADE.a2ml" -ECO="$DIR6A2/ECOSYSTEM.a2ml" -AGENTIC="$DIR6A2/AGENTIC.a2ml" -STATE="$DIR6A2/STATE.a2ml" -ANCHOR="$DIR6A2/anchors/ANCHOR.a2ml" +ROOT="${1:-.}" +READ="$ROOT/scripts/deed-field.sh" -for f in "$CLADE" "$ECO" "$AGENTIC" "$STATE" "$ANCHOR"; do - [ -f "$f" ] || { echo "extract.sh: missing required a2ml: $f" >&2; exit 2; } -done +DEED="$(bash "$READ" --find "$ROOT")" \ + || { echo "extract.sh: need exactly one *_chora.deed in $ROOT" >&2; exit 2; } +bash "$READ" --has "$DEED" anchor/golden-path \ + || { echo "extract.sh: $(basename "$DEED") has no (anchor (golden-path)) clause" >&2; exit 2; } -# scalar KEY FILE -> first `KEY = "value"` or unquoted `KEY = value` (anchored) -scalar() { - local v - v="$(grep -oP "^$1 = \"\K[^\"]+" "$2" | head -1 || true)" - if [ -z "$v" ]; then - v="$(grep -oP "^$1 = \K[^\"#]+" "$2" | head -1 | sed 's/[[:space:]]*$//' || true)" - fi - printf '%s' "$v" +# field PATH KEY -> the deed value, or "" when the clause or key is absent +# (rc 1); an unreadable deed or a usage error (rc 2) fails the run instead +field() { + local rc=0 + bash "$READ" "$DEED" "$1" "$2" || rc=$? + [ "$rc" -le 1 ] || return "$rc" } -# arr KEY FILE SEP -> join all quoted strings in the `KEY = [ ... ]` block -# (inline `k = ["a","b"]` or multiline). SEP is a literal multi-char string. -arr() { - local key="$1" file="$2" sep="${3:-, }" out="" i - local -a items - mapfile -t items < <( - awk -v k="$key" ' - index($0, k" = [")==1 {grab=1} - grab {print} - grab && /\]/ {exit} - ' "$file" | grep -oP '"[^"]*"' | sed 's/^"//; s/"$//' || true - ) - for i in "${!items[@]}"; do - if [ "$i" -eq 0 ]; then out="${items[$i]}"; else out="$out$sep${items[$i]}"; fi - done +# items PATH KEY SEP -> the deed list :KEY ( … ) joined by the literal SEP, +# "" when absent; fails like field() when the deed cannot be read +items() { + local out="" item first=1 list rc=0 + list="$(bash "$READ" --list "$DEED" "$1" "$2")" || rc=$? + [ "$rc" -le 1 ] || return "$rc" + while IFS= read -r item; do + [ -n "$item" ] || continue + if [ "$first" -eq 1 ]; then out="$item"; first=0; else out="$out$3$item"; fi + done <<< "$list" printf '%s' "$out" } -# short content hash (drift provenance) -sh() { sha256sum "$1" | cut -c1-12; } +# hash12 -> short content hash of stdin (drift provenance) +hash12() { sha256sum | cut -c1-12; } + +# The identity is the deed's own TYPED literal (#u5"", later #u8""), +# never a computed hex uuid. The uuid is derived from that name and never +# stored (deed.abnf); printing its hex form put a version-5 literal in +# CLAUDE.md, which ADR-008's strict gate (owner ruling D320, standards +# governance job uuid-v7-conformance) rejects in every minted repo. The +# typed literal says what the identifier is, as ADR-008 asks of legacy ids, +# and follows the deed when it moves to version 8. +uuid_name="$(field '' repo-uuid)" +uuid="" +[ -z "$uuid_name" ] || uuid="$(sed -n -E 's/^[[:space:]]*:repo-uuid[[:space:]]+(#u[0-9]+"[^"]*").*/\1/p' "$DEED" | head -1)" +[ -z "$uuid_name" ] || [ -n "$uuid" ] \ + || { echo "extract.sh: $(basename "$DEED") :repo-uuid is not a typed #u\"...\" literal" >&2; exit 2; } + +# read_clauses -> the clauses this pack reads, one token per line. Hashing only +# these keeps an unrelated deed edit (say a canon-pin bump) from reading as drift. +read_clauses() { + local c + bash "$READ" "$DEED" '' canonical-name + printf '%s\n' "$uuid_name" + for c in identity clade lineage forges status maturity ecosystem agentic; do + bash "$READ" --clause "$DEED" "$c" || [ "$?" -eq 1 ] || return 2 + done +} -# --- IS-NOT: present only if ECOSYSTEM declares `what-this-is-not` ------------ -isnot="$(arr 'what-this-is-not' "$ECO" ' · ')" -[ -n "$isnot" ] || isnot="(not yet declared — add ECOSYSTEM.what-this-is-not)" +isnot="$(items ecosystem not ' · ')" +[ -n "$isnot" ] || isnot="(not yet declared — add (ecosystem :not (…)) to the deed)" -golden_smoke="$(arr 'smoke-test-command' "$ANCHOR" ' && ')" -golden_crit="$(arr 'success-criteria' "$ANCHOR" '; ')" +# Each value is its own assignment so that a failed deed read stops the run; +# as a bare `--arg x "$(…)"` its exit status would be discarded. +canonical_name="$(field '' canonical-name)" +[ -n "$canonical_name" ] \ + || { echo "extract.sh: $(basename "$DEED") has no :canonical-name" >&2; exit 2; } +prefixed_name="$(field identity prefixed-name)" +clade_primary="$(field clade primary)" +clade_secondary="$(items clade secondary ', ')" +born="$(field lineage born)" +forge_gh="$(field forges github)" +purpose="$(field ecosystem purpose)" +pipeline_pos="$(field ecosystem pipeline-position)" +chain="$(field ecosystem chain)" +coordination="$(field ecosystem coordination)" +phase="$(field status phase)" +maturity="$(field maturity level)" +golden_smoke="$(items anchor/golden-path smoke-test-command ' && ')" +golden_crit="$(items anchor/golden-path success-criteria '; ')" +anchor_clause="$(bash "$READ" --clause "$DEED" anchor)" +h_deed="$(read_clauses | hash12)" +h_anchor="$(printf '%s\n' "$anchor_clause" | hash12)" -jq -n \ - --arg canonical_name "$(scalar 'canonical-name' "$CLADE")" \ - --arg prefixed_name "$(scalar 'prefixed-name' "$CLADE")" \ - --arg uuid "$(scalar 'uuid' "$CLADE")" \ - --arg clade_primary "$(scalar 'primary' "$CLADE")" \ - --arg clade_secondary "$(arr 'secondary' "$CLADE" ', ')" \ - --arg born "$(scalar 'born' "$CLADE")" \ - --arg forge_gh "$(scalar 'github' "$CLADE")" \ - --arg purpose "$(scalar 'purpose' "$ECO")" \ +jq -cnS \ + --arg canonical_name "$canonical_name" \ + --arg prefixed_name "$prefixed_name" \ + --arg uuid "$uuid" \ + --arg clade_primary "$clade_primary" \ + --arg clade_secondary "$clade_secondary" \ + --arg born "$born" \ + --arg forge_gh "$forge_gh" \ + --arg purpose "$purpose" \ --arg isnot "$isnot" \ - --arg pipeline_pos "$(scalar 'position' "$ECO")" \ - --arg chain "$(scalar 'chain' "$ECO")" \ - --arg coordination "$(scalar 'coordination' "$ECO")" \ - --arg phase "$(scalar 'phase' "$STATE")" \ - --arg maturity "$(scalar 'maturity' "$STATE")" \ - --arg completion "$(scalar 'completion-percentage' "$STATE")" \ - --arg status "$(scalar 'status' "$STATE")" \ + --arg pipeline_pos "$pipeline_pos" \ + --arg chain "$chain" \ + --arg coordination "$coordination" \ + --arg phase "$phase" \ + --arg maturity "$maturity" \ + --arg deed "$(basename "$DEED")" \ --arg golden_smoke "$golden_smoke" \ --arg golden_crit "$golden_crit" \ - --arg h_clade "$(sh "$CLADE")" \ - --arg h_eco "$(sh "$ECO")" \ - --arg h_agentic "$(sh "$AGENTIC")" \ - --arg h_state "$(sh "$STATE")" \ - --arg h_anchor "$(sh "$ANCHOR")" \ + --arg h_deed "$h_deed" \ + --arg h_anchor "$h_anchor" \ '$ARGS.named' diff --git a/.machine_readable/arrival-pack/generate.sh b/.machine_readable/arrival-pack/generate.sh index ac2a8597..da27bedc 100755 --- a/.machine_readable/arrival-pack/generate.sh +++ b/.machine_readable/arrival-pack/generate.sh @@ -3,7 +3,7 @@ # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) # # generate.sh — compile the repo's CLAUDE.md arrival pack. -# extract.sh (a2ml -> JSON) -> arrival-pack.ncl (Nickel projection) -> splice. +# extract.sh (deed -> JSON) -> arrival-pack.ncl (Nickel projection) -> splice. # # The generated region lives between the ARRIVAL-PACK:BEGIN/END markers. Anything # OUTSIDE the markers in CLAUDE.md is hand-authorable and is preserved verbatim. @@ -13,7 +13,7 @@ ROOT="$(git rev-parse --show-toplevel)" AP="$ROOT/.machine_readable/arrival-pack" TARGET="$ROOT/CLAUDE.md" -bash "$AP/extract.sh" "$ROOT/.machine_readable/descriptiles" > "$AP/claude-md-data.json" +bash "$AP/extract.sh" "$ROOT" > "$AP/claude-md-data.json" nickel export --format raw "$AP/arrival-pack.ncl" > "$AP/.region.tmp" if [ -f "$TARGET" ] && grep -q 'ARRIVAL-PACK:BEGIN' "$TARGET"; then @@ -35,7 +35,7 @@ else echo "-->" echo "" echo "" + echo " repo's deed by \`just claude-md\` — do not hand-edit it. -->" echo cat "$AP/.region.tmp" } > "$TARGET" diff --git a/.machine_readable/arrival-pack/verify.sh b/.machine_readable/arrival-pack/verify.sh index 1d90acf3..c26fb58b 100755 --- a/.machine_readable/arrival-pack/verify.sh +++ b/.machine_readable/arrival-pack/verify.sh @@ -3,7 +3,7 @@ # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) # # verify.sh — drift check for the CLAUDE.md arrival pack (the runnable side of -# claude-md.k9.ncl). Regenerates the region from a2ml and byte-compares it to the +# claude-md.k9.ncl). Regenerates the region from the deed and byte-compares it to the # committed region. Non-zero exit on drift or hand-edit. Wire into CI/pre-commit. set -euo pipefail @@ -13,12 +13,12 @@ TARGET="$ROOT/CLAUDE.md" [ -f "$TARGET" ] || { echo "DRIFT: CLAUDE.md missing — run \`just claude-md\`"; exit 1; } -bash "$AP/extract.sh" "$ROOT/.machine_readable/descriptiles" > "$AP/claude-md-data.json" +bash "$AP/extract.sh" "$ROOT" > "$AP/claude-md-data.json" fresh="$(nickel export --format raw "$AP/arrival-pack.ncl")" committed="$(awk '/` comment per pull request. It is triggered by + `pull_request` *and* by `workflow_run` on the two producer workflows, so it + re-renders when a scanner finishes instead of showing "not yet" forever. +* **Hypatia ran twice per pull request.** `hypatia-scan.yml` and a + `hypatia-scan` job of `static-analysis-gate.yml` each built the same scanner + at the same pin, with separate caches and two independent "fail on critical" + gates over two differently-shaped JSON files. Hypatia now runs once, in + `hypatia-scan.yml`, which also uploads `hypatia-findings.relativized.json` + (repo-relative paths, so the grid's delta column can match + `git diff --name-only`) as `hypatia-scan-findings`. `static-analysis-gate.yml` + keeps what is specific to it and uploads `static-analysis-findings`. +* **A failed fleet job was reported and then ignored.** The verdict job printed + the fleet result in a table and never failed on it, so a fleet failure was + invisible where a reader looked; its `jq '… | .findings | length'` loop could + also abort the whole summary on one malformed envelope and skip the final + check. The verdict now fails on DEED/K9 only (each producer owns its own + gate), states that the fleet's failure is orange rows plus its own red check, + and never parses fields it does not own. +* **`.hypatia-ignore` carried a dangling cross-reference**: `panicbot` was left + unenrolled because "the Hypatia lane's direct panic-attack row" would cover + it, and no such row existed. The grid now renders that row from + `static-analysis-gate.yml` evidence, and the enrolment reason states the rule + it is an instance of (one scanner, one row). + +* **Seven defects the review of this work found, each now covered by a control.** + None of these were reached by the tests as written, which is the point: +** `check-container-pins.sh` took the "nothing to pin" success path even after + failing on a `Dockerfile`, so the one repository shape the Dockerfile rule + exists to catch reported PASS; and it registered a stage name only after the + line that `continue`s, so the ordinary `FROM image@sha256:… AS build` + + `FROM build` pair was judged an unpinned remote image. Stage names are now + registered when parsed, before any branch can skip the rest of the line; +** `pin-container-digests.sh` rewrote every `FROM` line, turning `FROM scratch` + and `FROM build` into `scratch@sha256:…` and `build@sha256:…` — corrupting the + multi-stage files it should leave alone, while the companion gate accepted the + result. It now splits FROM into flags/reference/tail and rewrites only the + reference of a remote image; +** `check-spdx-headers.sh` judged emptiness per EXTENSION, so a valid Elixir tree + with `.ex` and no `.exs` (or OCaml `.ml` without `.mli`) failed for a language + it is written in. Emptiness is now judged per language, across all of its + extensions; +** `render-mise.sh --langs` only changed the label: the tool list still came from + the tree's own detection, so a fixture asking for Julia was handed the docs + toolchain. `mise-tools` now accepts the language list, and `--check` compares + the declared toolchain rather than the rendered prose — which made it + impossible to pass on any repository that wrote its own header, the template + included; +** `check-mise-language.sh` parsed only bare `[tools]` keys, and backend-qualified + tools MUST be quoted (`"npm:prettier"`), so the banned-tool check could never + see them; its `--detect` mirror also looked only at the root, calling a tree + with `src/interface/abi.ipkg` and `src/interface/ffi/build.zig` a docs + repository. Both now follow the engine, depths included, and the mirror lists + mise tools rather than each language's binaries; +** `check-mint-tokens.sh` treated "no build/just/repo-init.just" as proof of a + minted tree — but that recipe is carried verbatim into every child, so no child + was ever recognised and an unfilled `{{PROJECT_NAME}}` passed (and + `survey-template-damage.sh` reported such repositories token-clean). The marker + is `archetypes/`, which the mint deletes; +** `archetypes/*/prune.txt` dropped only `build/container/`, so a minted Julia + package and a minted Rust CLI both carried the Idris2/Zig seam: three languages + detected, `idris2` and `zig` installed, `idris2 --build` in `just build`. Both + presets declare neither the abi nor the ffi capability, so both now prune + `src/interface/`; `validate-rsr` requires the seam only of a tree that carries + it. The archetype tests assert the toolchain is single-language. + ==== Added +* `scripts/governance-badge.js` — the single implementation of the badge + scheme: the state -> (message, colour) table, canonical rendering, the + publication decision (create orphan branch / add file / update / no-op), + API-error classification, and guards that refuse `main`, `master`, a + repository default branch, or a path outside `badges/`. Runtime-agnostic + (Bun or Node, `node:` builtins only), so it is unit testable. +* `tests/workflows/governance_badge_test.sh` and + `tests/workflows/governance_badge_test.js` — hermetic tests wired into + Estate Rules: the state table, byte-equal no-op, changed-bytes publication, + orphan-branch creation with `parents: []`, grey states for missing/malformed + lane evidence, malformed existing content, 404-vs-outage classification, + conflict reconciliation and the source-branch guards, plus wiring checks run + against a mutated workflow so they are proven able to fail. They supersede + `tests/workflows/dogfood_badge_test.sh`, which asserted the old mapping and + was never wired into CI. A present but *unreadable* artifact (EACCES, or a + TOCTOU deletion between the stat and the read) is now evidence that cannot be + checked rather than an uncaught exception: it renders grey, names the errno, + and exits 3. The assertion is skipped, with the reason printed, when the + suite runs as root, where `chmod 000` cannot deny a read. +* `README.adoc` and `.github/workflows/README.adoc` now state the operational + contract of the generated `governance-badges` branch: it is an orphan with no + common ancestor with `main`, it is never merged and has no pull request, + recent pushes are normal refreshes, identical content makes no commit, and a + grey badge means the lane produced no trustworthy result. + * `www/` site-operations bundle (issue #53): canonical `.well-known/` metadata, publishable content, policy sources, error bodies, security-header templates, Caddy/nginx/Apache integration examples, an @@ -33,9 +235,139 @@ https://semver.org/spec/v2.0.0.html[Semantic Versioning]. template; they exist for running `repo-init` over a tree that predates #53. #106 described both as already present — neither was, which is a fair part of why the estate still carries root `.well-known/` directories. +* `scripts/merge-actions-lock.rs` — merges an archetype's lock fragment + (`archetypes//actions.lock`) into the spine's + `.github/workflows/actions.lock` at mint. A record that differs between + the two stops the mint. `tests/workflows/archetype_lock_merge_test.sh` + (wired into estate-rules) checks the merged lock with + `check-lock-sync.sh`, and checks that the old clobber, a missing record + and a conflicting record all fail. + +* `scripts/verdict-grid-lane.sh` — collect / validate / render / previous / + comment for the verdict grid lane. It refuses to execute a renderer whose + sha256 does not match the recorded digest, renders an explicit **orange + "indeterminate"** grid (never green) when the renderer or the evidence is + unavailable, refuses a bare panic/pons findings array (a bare array cannot + distinguish "ran clean" from "never ran"), and updates the comment it posted + last time instead of adding one per run. +* `scripts/check-workflow-edges.sh` — the intra-repository half of the CICD + Squabbler gate, run in both `squabble.yml` and `estate-rules.yml`. It fails + when a `workflow_run.workflows` entry names no workflow's `name:`, when two + workflows share a `name:`, when the verdict job reads an artifact its named + producer never uploads, when a producer stops running on `pull_request`, when + the verdict job's `--hypatia-ref`/`--panic-ref`/`--pons-ref` disagree with the + producer's pin, or when one tool is pinned at two different commits. +* `scripts/check-hypatia-ignore.sh` — the meta-rules for `.hypatia-ignore`: + every fragment must end on a path boundary (a substring fragment silences + more than it names), no entry may be subsumed by a broader one for the same + module, the path it names must exist, and it must belong to a commented + reason block. +* `docs/HYPATIA-RULE-ORDER.adoc` — the ordered statement of Hypatia's exemption + layers (total ban, universal excludes, built-in defaults, `.hypatia-ignore`, + inline directives, baseline, grid normalisation), the eight clashes found + between them, the rule that resolves each, the e/r (evidence/reason) + contract per reporter, the GitBot design rules, what is deliberately *not* + enforced, and the refusals that make the order a checked contract. +* `tests/workflows/verdict_grid_test.sh` (70 checks), `workflow_edges_test.sh` + (21) and `hypatia_ignore_test.sh` (22) — behaviour, wiring and firing controls + for the three scripts above, with stub `gh`/renderer and mutated workflow + copies, so every check is proven able to fail. +* `.machine_readable/policies/hypatia-rule-order.json` — the rule order as a + contract rather than prose: the seven layers with their rank, scope, owner and + what each may override; the eight concerns with exactly one owning workflow or + file each; the eight clashes with the rule that resolves each; the modules + `.hypatia-ignore` currently exempts and the layer each exemption lives in; and + the scanner, grid, renderer and jq-library pins the order was written against. +* `scripts/check-hypatia-rule-order.sh` — refuses a duplicate or gapped rank, a + layer that states no scope or no override, an owner outside the four declared + parties, a concern owned by a path that does not exist, a clash with no + resolution, a module exempted but unclassified (or classified but no longer + exempted), an exemption filed under a layer this repository may not change, + and any pin or digest that disagrees with `hypatia-scan.yml` or the lane + script. Exit 0 clean, 1 violation, 2 setup error. +* `tests/workflows/hypatia_rule_order_test.sh` (44 checks) — one mutation per + refusal above, run against a copy of the real policy. Two of its own first-draft + defects are documented in `docs/HYPATIA-RULE-ORDER.adoc`: `@tsv` collapses an + empty field (a missing `overrides` was reported as a missing `scope`), and + `grep` under `set -e` exits before a missing pin can be diagnosed. +* `.machine_readable/policies/README.adoc` — the registry now says what each + policy states, what checks it, and that adding a policy means adding the + checker and its lane. +* `scripts/run-proven-suite.sh` gains the lane *Hypatia rule order & clash + resolution*, so the policy cannot drift from the four files it describes + without a red run; `tests/run_proven_suite_test.sh` asserts the lane is + dispatched (16). ==== Changed +* KYAML, step 5 of standards YAML-POLICY §5 (standards#1024): the three + estate-owned YAML files that no third-party bot rewrites are now KYAML + content: `build/container/compose.yaml`, `compose.example.yaml` and + `stapeln/.gatekeeper.yaml`. Each keeps its name, because Compose, the + Containerfile label and svalinn find it by name (§3.4). They were rewritten + by standards' `kyaml-format.sh` alone, which refuses any change to the + parsed data. Every comment line survives, and `.gatekeeper.yaml` is now + byte-identical to standards' `_shared/container/.gatekeeper.yaml`. + Estate Rules gains the ratchet "Converted YAML stays KYAML", which runs + that script at standards `75bd599` with yq 4.53.3, both sha256-verified. + Container narrowing at mint can delete any of the three files, so the + template must keep all of them, while a minted repository checks the ones + it kept and names the ones narrowing removed. + `tests/workflows/kyaml_ratchet_test.sh` covers the template and each + narrowing, and `tests/workflows/container_kyaml_test.sh` checks that the + conversion kept every value in the template's configs. Estate Rules runs + both. + Workflows wait for step 6 (standards#1025). Files that Dependabot, + FUNDING, issue forms, Probot settings, CodeRabbit, Copilot, GitLab CI or + pre-commit read or rewrite are not converted, as in standards. +* The workflow linter installs Bun 1.4.2, the estate pin, from its release + archive and checks its sha256, as Estate Rules installs its tools. It ran + `oven-sh/setup-bun@v2.2.0` with `bun-version: latest`, so the runtime was + unpinned, and SonarCloud rated a third-party action pinned by tag "C" + ("Use full commit SHA hash"), even though `actions.lock` pins its commit. + The linter's lock edge to setup-bun goes. The `setup-bun@v2.2.0` record + stays, because the commented Bun steps in `e2e.yml.template` resolve + through it. +* `.github/workflows/runtime-policy.yml` is removed, folded into governance + as the standards cicd-regularisation spec §14 rules. Governance's + "Language / package anti-pattern policy" fails any tracked + `package-lock.json`, a stricter test than this file's mixed-toolchain error, + and its "JS runtimes" jobs check `bun.lock`, `deno.lock` and + `pnpm-lock.yaml` against `package.json`. Its `actions.lock` record goes with + it, and `validate-template.sh` and `validate_workflows_test.sh` require + `governance.yml` in its place. Repositories minted from the template stop + receiving their own copy of the check. Governance now runs on pull requests + to any branch, as the removed workflow did, so a stacked pull request keeps + the check. `tests/workflows/runtime_policy_fold_test.sh`, which Estate Rules + runs, checks that both validators reject a tree without `governance.yml` and + accept none of the retired gates' names in its place. + `tests/workflows/governance_policy_test.sh`, also in Estate Rules under a + sha256-verified Bun 1.4.2, checks that the workflow and its lock record stay + gone, that governance's pull request trigger has no filter, and that its + standards call matches the lock. +* JavaScript runtimes follow the 2026-10-14 ruling (standards + LANGUAGE-POLICY §1.3–§1.4): Bun > Deno > pnpm > npm, from one + `package.json` whose `bun.lock`, `deno.lock` and `pnpm-lock.yaml` are all + written by `js-runtimes regen`. +** `.github/workflows/runtime-policy.yml` used to fail any repository + carrying more than one lock, so it failed every repository that follows the + ruling ("Mixed toolchains: 3 package managers"). Those three locks now count + as one dependency graph. `package-lock.json` next to them still fails. A + `deno.json` is a notice, not a warning. +** The provisioning engine (`build/just/provision-lib.sh`, + `provision-modes.sh`, `provision-check.sh`) is re-synced to standards + `ed04132e` (engine 0.6.0, standards#1255). A `package.json` provisions bun, + deno and pnpm, and deno and pnpm are no longer banned tools. +** The same policy appears in the arrival pack (`arrival-pack.ncl`, and + CLAUDE.md regenerated from it), `mise.toml`, `docs/SETUP.adoc` PV-W23, + PV-W30 and PV-W34, the dev warm-up, `.cursorrules`, `.clinerules`, + `.windsurfrules`, `.github/copilot-instructions.md` and the PR template. +** The six standards reusables move from `ae36881` to `934b879`. At + `ae36881` governance's Actions lockfile verify installs gh-actions-lock + v0.1.6, which cannot read this lock's format v0.0.3 (exit 2, red on main). + `actions.lock` is re-keyed and closed at the new pin (setup-bun and + setup-deno records added), as resource-algebra#8 did. + * Canonical `.well-known/` location moved from the repository root to `www/.well-known/`. Well-known enforcement, Groove checks, the root-shape allowlist, the SSG bootstrap and the documentation now prefer the `www/` @@ -56,6 +388,69 @@ https://semver.org/spec/v2.0.0.html[Semantic Versioning]. ==== Fixed +* Governance, Hypatia Security Scan, Mirror to Git Forges, Rust CI and + Secret Scanner start again. GitHub's runner now rejects a lock record whose + `ref:` is the record's own SHA ("invalid lockfile pin"), and nine of this + lock's action records had one. The standards reusables move from `6a92510` + to `75bd599`, whose own lock carries tag refs + (hyperpolymath/standards#1271, hyperpolymath/standards#1285), and + `relock-standards-pin.sh` at `75bd599` gave the nine records the same tags. + No commit changes: each tag was checked to point at its recorded commit. +* The mint's self-name pass keeps issue references. It rewrote + `rsr-template-repo#N`, a reference to this template's own issue, into + `#N`, which names an issue of the child that does not exist or is + unrelated. resource-algebra carried such references after its mint. + `tests/workflows/self_name_pass_test.sh` (wired into Estate Rules) runs + the recipe's own rewrite program on fixtures. +* CLAUDE.md prints the deed's typed identity (`#u5""`) instead of + the derived uuid5 in hex, and the deed's identity comment no longer + spells it out. ADR-008's strict v8 gate (governance "UUID v7 + conformance") rejected both, in the template and in every minted repo. +* The standards reusables are pinned to `6a92510`, whose governance job + installs gh-actions-lock v0.2.0. At `ae36881` it installed v0.1.6, which + refuses lock format v0.0.3 ("newer than this binary supports"), so + Actions lockfile verify failed. `actions.lock` was relocked with + standards' `propagate-workflow-pins.sh` (hyperpolymath/standards#1254). + `6a92510` also scans the julia-library overlay's `Project.toml.in` as a + `Project.toml` (hyperpolymath/standards#1258), so its `[extras]` registry + UUIDs no longer fail the strict v8 gate. +* The non-interactive mint completes. `RSR_NON_INTERACTIVE=1` used to + stub `read` for the whole recipe, so an unanswered prompt killed the + mint under `set -u` and the substitution loops never ended. Prompts now + read answers from the environment; `tests/workflows/non_interactive_mint_test.sh` + drives that path in Estate Rules, and the docs that warned agents off it + now describe it. +* A mint leaves just's own interpolation of `project` alone, regenerates + CLAUDE.md and the repository map from the child's deed and tree, keeps + the deed's `reject-if-contains` detector, and no longer breaks the + OpenSSF audit table when no OpenSSF id is given. +* The standards reusables are pinned to standards main (`ae36881`), where + the Actions lockfile verify job pins its tool and treats `sha-as-ref` + as advisory. +* The julia-library lock fragment is at the spine's lockfile format + v0.0.3, so Julia mints merge it again. + +* Julia mints start with Lock Sync green. The julia-library overlay + shipped its own `actions.lock`, which replaced the spine's at mint, so + every spine workflow lost its records. The records now ship beside the + overlay and are merged in. The overlay workflows gain SPDX headers and + top-level permissions, and julia-docs builds with plain steps instead of + the allowlist-refused julia-buildpkg/julia-docdeploy. julia-actions/cache + moves to v3.5.0. The root allowlist admits `?Project.toml` and `?test/`. + The docs checkout sets `persist-credentials: false`, so package code run + while the docs environment is set up finds no stored token. deploydocs + still receives GITHUB_TOKEN. +* `just repo-init julia-library` accepts a `.jl` slug. The PROJECT + tokens map its dot to an underscore, and the default service name is the + slug in lower case. + +* Dev container starts for everyone: dropped the ghcr.io dev container + features (anonymous pulls returned 403), installing just from Wolfi and a + SHA-256-checked Nickel 1.17.0 binary instead. The default + `.devcontainer/devcontainer.json` now targets rootless Podman + (`--userns=keep-id:uid=65532,gid=65532`, `label=disable`) so the workspace + is writable as wolfi-base's built-in `nonroot`; Docker, Codespaces and + Gitpod use `.devcontainer/docker/devcontainer.json`. * `dot-wellknown-enforcement.yml` now drives the migrator that #106 described but never wired up: previously the workflow only printed advice to run it, so nothing verified that a repository would survive the migration. It now diff --git a/CITATION.cff b/CITATION.cff index e69aece9..ba88b6a6 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -1,9 +1,9 @@ cff-version: 1.2.0 message: "If you use this software, please cite it as below." authors: - - family-names: "Jewell" - given-names: "Jonathan D.A." - orcid: "https://orcid.org/0000-0002-3078-6652" + - family-names: "{{AUTHOR_LAST}}" + given-names: "{{AUTHOR_FIRST}}" + orcid: "https://orcid.org/{{AUTHOR_ORCID}}" title: "{{PROJECT_NAME}}" version: 0.1.0 date-released: "{{CURRENT_DATE}}" diff --git a/CLAUDE.md b/CLAUDE.md index 2ac929dc..9e0e93b9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,9 +4,9 @@ SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell --> + repo's deed by `just claude-md` — do not hand-edit it. --> - + # You are in the hyperpolymath estate — orient before acting @@ -32,40 +32,129 @@ If you are unsure what something is, **read the canon; do not guess** (guessing ## The machine-readable substrate (read in this order on arrival) **CHORA** → **ANCHOR** → **AGENTIC** → **ECOSYSTEM** → **STATE** -> **NEUROSYM** -> **PLAYBOOK** +ANCHOR, AGENTIC, ECOSYSTEM, STATE, NEUROSYM and PLAYBOOK are clauses of the CHORA deed — `(anchor)`, `(agentic)`, `(ecosystem)`, `(status)` and `(maturity)`, `(neurosym)`, `(playbook)` — not files; STATE's journal is `docs/status/ROADMAP.adoc`. There are no `.a2ml` files in this estate. + The descriptive family (working name *descriptiles*) describes what-is; the **contractiles** are the normative set-point. | File | Answers | |---|---| -| `CLADE.a2ml` | *Identity / lineage* — what this repo IS (registers into `gv-clade-index`). | -| `ANCHOR.a2ml` | *Semantic authority + golden path* — what downstream may extend-not-redefine; if a recognised-drift / re-anchor marker is present, it **supersedes** accumulated context — read it first. | -| `META.a2ml` | *Concept / constitutional authority* — ADRs, what's permitted. | -| `AGENTIC.a2ml` | *May I act now?* — permissions, risk gating, fail-safe-deny. | -| `ECOSYSTEM.a2ml` | *Where it sits* — estate + external relations, and `what-this-is-not`. | -| `NEUROSYM.a2ml` | *Meaning* of operations — proof obligations. | -| `PLAYBOOK.a2ml` | *How* permitted actions run. | -| `STATE.a2ml` | *Where things are now* — progress, blockers, next-actions. | +| `rsr-template-repo_chora.deed` | **CHORA**, the repo deed. Its `(identity)` `(clade)` `(lineage)` clauses say what this repo IS (registers into `gv-clade-index`); `(meta)` the architecture axes; `(agentic)` *may I act now?*; `(ecosystem)` where it sits and what it is not; `(status)` and `(maturity)` where it is now. Read fields with `scripts/deed-field.sh`. | +| `(anchor)` | *Semantic authority + golden path* — what downstream may extend-not-redefine; if a recognised-drift / re-anchor marker is present, it **supersedes** accumulated context — read it first. | +| `(neurosym)` | *Meaning* of operations — proof obligations. | +| `(playbook)` | *How* permitted actions run. | +| `docs/status/ROADMAP.adoc` | *What is next* — milestones, blockers, next actions. | | contractiles | Normative doctrine: **Intend** (north-star) · **Must** (invariants) · **Trust** (security) · **Adjust** (accessibility / inclusive design) — the integral core that holds strong; plus **Dust** (exnovation drift) · **Bust** (failure / breakage, not drift). | | k9 | *Validation*. Kennel (data) / Yard (pure eval) / Hunt (guarded exec). | ## Canon pointers +Estate data-format route: **kyq** handles exactly **TOML, Dhall, KYAML, +I-JSON/JCS**. Preserve TOML/Dhall; migrate YAML/YML to KYAML and JSON variants +through kyq using **hyperpolymath/ijson-jcs**, the actual estate implementation +repository. **kyX** owns wider projection. DEED/K9/coordination keep their own +grammars. Canon: `metadatastician/standards/3-practice/DATA-FORMAT-ROUTING.adoc`. +Planned support is not operational evidence: retain explicit transitional +checks until a pinned kyq executable passes positive and negative tests. + - `hyperpolymath/standards` — the canon source. · `hyperpolymath/gv-clade-index` — the estate map (identity registry). · `hyperpolymath/manifesto` — this doctrine. - **Before you invent, rename, or consolidate anything: STOP and check the map + IS-NOT.** ## Estate language policy (overridable per-repo via AGENTIC) -Deny: **Nix, Python, Go, TypeScript, AGPL**. (Guix, not Nix.) -JavaScript tooling order: **Bun** (default) > Deno (being removed — owner ruling 2026-08-26, standards#655) > pnpm > npm (last resort, permitted). -Use plain JavaScript when this tooling is needed. The "use ReScript" rule is retired — ReScript is no longer used in this estate. Do not migrate Bun to Deno. +Deny: **Nix, Python, Go, TypeScript, ReScript, AGPL**. (Guix, not Nix.) +JavaScript runtime: **Bun** > Deno > pnpm > npm (last resort, permitted), from one `package.json` that carries every runtime's lock (`bun.lock`, `deno.lock`, `pnpm-lock.yaml`), all written by `js-runtimes regen` (owner ruling 2026-10-14, standards LANGUAGE-POLICY §1.3–§1.4). Deno is permitted again; `package-lock.json` stays refused. +Use plain JavaScript when this tooling is needed. TypeScript and ReScript migrate to AffineScript. + +## Asking the owner +Put every question that needs the owner's decision through the selector (the AskUserQuestion tool), not as prose at the end of a report. Batch up to four per call, offer concrete options with the recommended one first, and say what each option would cause. --- # This repo: `rsr-template-repo` · clade `rm-rsr-template-repo` -- **Identity** — uuid `a5ea1382-a34c-5334-8a46-a2ebe904c810`; clade `rm` (secondary ``); born 2026-03-16; forge `hyperpolymath/rsr-template-repo`. +- **Identity** — uuid `#u5"github.com/hyperpolymath/rsr-template-repo"`; clade `rm` (secondary ``); born 2026-03-16; forge `hyperpolymath/rsr-template-repo`. - **IS** — Canonical RSR-compliant repository template: scaffolding (CI/CD, AI manifests, ABI/FFI standards, container ecosystem, governance) that new hyperpolymath projects are instantiated from. - **IS-NOT** — a project in its own right · Scaffoldia (the full-featured repo designer) · standards (the canon source this template operationalises) - **Where it sits** — pipeline position **foundation**; chain `standards → rsr-template-repo → (every estate repo)`; coordination = `standards`. -- **Constraints here** (AGENTIC) — fail-closed; evidence-per-step; no-silent-skip; rerun-after-fix; release-claim-requires-hard-pass. Never: banned langs (above), secrets, state files in repo root, AGPL. Details: `.machine_readable/bot_directives/{methodology,coverage,debt}.a2ml`. +- **Constraints here** (AGENTIC) — fail-closed; evidence-per-step; no-silent-skip; rerun-after-fix; release-claim-requires-hard-pass. Never: banned langs (above), secrets, state files in repo root, AGPL. Details: the deed's `(bot-directives (methodology) (coverage) (debt))` clauses. - **Golden path** (ANCHOR) — `just test && just quality` → Core tests pass; Quality gates pass; No unresolved critical security findings. -- **State** — phase maintenance; maturity production; 95% complete; status active. +- **State** — phase active; maturity production. Milestones and next actions: `docs/status/ROADMAP.adoc`. + + + + +## Estate-Wide Format Migration Directives + +**IMPORTANT FOR ALL AGENTS (Claude, Codex, Gemini, Mistral, etc.):** + +This estate enforces strict format standards. Failure to follow these causes +estate drift and broken tooling. These rules are NOT optional. + +**Estate route (owner clarification, 2026-10-25):** `metadatastician/kyq` +handles repository gates, queries and migration for exactly **TOML, Dhall, +KYAML and I-JSON/JCS**. Preserve TOML and Dhall. YAML/YML content migrates to +KYAML; JSON variants, including NDJSON/JSONL and JSON-LD, use the profile in +**`hyperpolymath/ijson-jcs`** through kyq. That name means the owner's actual +repository, which must track standards through tested update proposals. +Preserve framing, consumer filenames and JSON-LD semantics. Wider projection +belongs to **kyX**, not extra kyq formats. DEED, K9 and coordination retain +their own grammars/contracts. Canon: +`metadatastician/standards/3-practice/DATA-FORMAT-ROUTING.adoc`. + +kyq's build and validation are still incomplete at `4370c76`; never claim a +placeholder is a working gate. The yq/ijson-jcs commands below are explicit +transitional enforcement until a pinned kyq executable passes the applicable +positive and negative tests. They are not the destination architecture. + +**KYAML (KEP-5295, owner rulings D280/D307):** YAML content is KYAML. +- Estate-owned config uses the `.kyaml` extension. +- `.yml`/`.yaml` only where a tool demands the name: GitHub workflows, + dependabot. Workflows migrate to KYAML content only once the lock-coverage + shim is a required context (D280); leave them alone until then. +- Transitional tooling: use `yq` (Go version) and the estate scripts `kyaml-format.sh`, + `kyaml-migrate.sh`. No Python YAML parsers (D293). +- KYAML format: `{}` for maps, `[]` for lists, double-quoted strings, + unquoted keys where unambiguous, trailing commas OK, 2-space indent. + KYAML is a subset of YAML; every YAML parser accepts it. + +**JSON (owner ruling D306):** every `.json`/`.jsonl` is I-JSON (RFC 7493), +serialised by JCS (RFC 8785), one record per line for JSON Lines. Extensions +do not change. Tool: `hyperpolymath/ijson-jcs` (`scripts/check-ijson-jcs.sh --enforce`, +wired in `estate-rules.yml`). Rule and gate: +`standards/3-practice/JSON-POLICY.adoc`. Tool-demanded JSONC +(`devcontainer.json`, `.vscode/*.json`) is carved out. + +**UUIDv8 (owner ruling D305, standards ADR-008):** mint every new identifier +as UUIDv8 in the ADR-008 layout. Do not rewrite existing v4/v7 identifiers by +hand; that migration is done per repo (ADR-008 phase P3). In deed files use +`#u5` literals until the deed ABNF admits v8; a `#u7` literal is illegal. + +**.a2ml → deed:** A2ML is retired; never create or restore a `.a2ml` file. +- Grammars: `standards/1-formats/deed/spec/abnf/deed.abnf` (authoritative + over the deed README, D308) and `standards/1-formats/k9/` for k9. +- Descriptiles (anchor, meta, state, ecosystem, agentic, neurosym, playbook) + are clauses of `rsr-template-repo_chora.deed` (D312). +- Contractiles (intend, must, trust, adjust, bust, dust) are k9 contracts in + `.machine_readable/contractiles//`. The deed attests to them + (`:contractiles_required`, and a `(contractiles …)` clause per D312). +- Do not hand-convert A2ML in bulk: conversion is kyX's first front end (D313). + +**ENFORCEMENT:** these rulings are recorded on `standards#787`. Some are +ruled but not yet gated: check the gate on `standards` main before +relying on it. + + +## Proofs — which prover for which obligation + +Normative source: `3-practice/PROOF-POLICY.adoc` in `hyperpolymath/standards`. +Read it there; `verification/proofs/README.adoc` maps it onto this repo. + +| Code or obligation | Verifier | +|---|---| +| Rust code | **Creusot**, on the code (Kani for `unsafe`/FFI seams and Aeneas for Rust that implements an Agda theorem run alongside, never instead) | +| Ada code | **SPARK** | +| APIs, ABIs, engineering properties | **Idris2** | +| Theory | **Agda**, rechecked in **Rocq** and **Lean** (no Mathlib) | - +Third-party code (crates such as Bevy, libraries, forks) is **not** converted +or re-proved. State what a proof relies on as an `ASSUMED` boundary +specification, and when choosing between dependencies that fit equally well, +prefer one that carries its own verification. A preference, not a gate. diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 00000000..954b4f91 --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,32 @@ +# Hyperpolymathy Estates Code of Conduct + +Like the technical community as a whole, the Hyperpolymathy Estates team and community is made up of a mixture of professionals and volunteers from all over the world, working on every aspect of the mission - including mentorship, teaching, and connecting people. + +Diversity is one of our huge strengths, but it can also lead to communication issues and unhappiness. To that end, we have a few ground rules that we ask people to adhere to. This code applies equally to founders, mentors and those seeking help and guidance. + +This isn’t an exhaustive list of things that you can’t do. Rather, take it in the spirit in which it’s intended - a guide to make it easier to enrich all of us and the technical communities in which we participate. + +This code of conduct applies to all spaces managed by the Hyperpolymathy Estates project or The Metadatastician. This includes IRC, the mailing lists, the issue tracker, DSF events, and any other forums created by the project team which the community uses for communication. In addition, violations of this code outside these spaces may affect a person's ability to participate within them. + +If you believe someone is violating the code of conduct, we ask that you report it by emailing [j.d.a.jewell@open.ac.uk](mailto:j.d.a.jewell@open.ac.uk). For more details please see our [Reporting guidelines](https://github.com/metadatastician/standards/conduct_guidelines) + +- **Be friendly and patient.** +- **Be welcoming.** We strive to be a community that welcomes and supports people of all backgrounds and identities. This includes, but is not limited to members of any race, ethnicity, culture, national origin, colour, immigration status, social and economic class, educational level, sex, sexual orientation, gender identity and expression, age, size, family status, political belief, religion, and mental and physical ability. +- **Be considerate.** Your work will be used by other people, and you in turn will depend on the work of others. Any decision you take will affect users and colleagues, and you should take those consequences into account when making decisions. Remember that we're a world-wide community, so you might not be communicating in someone else's primary language. +- **Be respectful.** Not all of us will agree all the time, but disagreement is no excuse for poor behavior and poor manners. We might all experience some frustration now and then, but we cannot allow that frustration to turn into a personal attack. It’s important to remember that a community where people feel uncomfortable or threatened is not a productive one. Members of the Hyperpolymathy Estates community should be respectful when dealing with other members as well as with people outside the Hyperpolymathy Estates community. +- **Be careful in the words that you choose.** We are a community of professionals, and we conduct ourselves professionally. Be kind to others. Do not insult or put down other participants. Harassment and other exclusionary behavior aren't acceptable. This includes, but is not limited to: + - Violent threats or language directed against another person. + - Discriminatory jokes and language. + - Posting sexually explicit or violent material. + - Posting (or threatening to post) other people's personally identifying information ("doxing"). + - Personal insults, especially those using racist or sexist terms. + - Unwelcome sexual attention. + - Advocating for, or encouraging, any of the above behavior. + - Repeated harassment of others. In general, if someone asks you to stop, then stop. +- **When we disagree, try to understand why.** Disagreements, both social and technical, happen all the time and Hyperpolymathy Estates is no exception. It is important that we resolve disagreements and differing views constructively. Remember that we’re different. The strength of Hyperpolymathy Estates comes from its varied community, people from a wide range of backgrounds. Different people have different perspectives on issues. Being unable to understand why someone holds a viewpoint doesn’t mean that they’re wrong. Don’t forget that it is human to err and blaming each other doesn’t get us anywhere. Instead, focus on helping to resolve issues and learning from mistakes. + +Original text courtesy of the [Speak Up! project](http://web.archive.org/web/20141109123859/http://speakup.io/coc.html). + +## Questions? + +If you have questions, please see [Faq](https://github.com/metadatastician/standards/conduct_guidelines/faq). If that doesn't answer your questions, feel free to [contact us](mailto:j.d.a.jewell@open.ac.uk). diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index 597c746b..b2713861 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.adoc @@ -112,16 +112,7 @@ We follow https://www.conventionalcommits.org/[Conventional Commits]: [optional footer] ---- -== Cross-references - -This root document exists because the estate docs gate -(`hyperpolymath/standards` `scripts/check-docs-presence.sh`) requires -`CONTRIBUTING.md`, `CONTRIBUTING.adoc`, or `3-practice/CONTRIBUTING.adoc` -at the repository root. The legacy copy at -link:.github/CONTRIBUTING.md[.github/CONTRIBUTING.md] predates that gate; -this document supersedes it. - -== Signed commits +=== Signed commits Every commit that reaches the default branch must be signed; a ruleset refuses unsigned pushes. Estate policy: @@ -137,3 +128,12 @@ https://github.com/hyperpolymath/standards/blob/main/docs/SIGNING-POLICY.adoc[SI not just the result, so one unsigned commit blocks the merge. Re-create such a branch with signed commits (`git cherry-pick -S`) and open a new PR. Rebase-merge replays commits unsigned and is disabled. + +== Cross-references + +This root document exists because the estate docs gate +(`hyperpolymath/standards` `scripts/check-docs-presence.sh`) requires +`CONTRIBUTING.md`, `CONTRIBUTING.adoc`, or `3-practice/CONTRIBUTING.adoc` +at the repository root. The legacy copy at +link:.github/CONTRIBUTING.md[.github/CONTRIBUTING.md] predates that gate; +this document supersedes it. diff --git a/GEMINI.md b/GEMINI.md deleted file mode 100644 index 417391d2..00000000 --- a/GEMINI.md +++ /dev/null @@ -1,8 +0,0 @@ -# Pointer - -This repository has no `AGENTS.md` yet. Until it does, the instructions -for every coding agent live in **[CLAUDE.md](./CLAUDE.md)**. Read that -file, and skip anything in it that is specific to Claude Code tooling. -Do not duplicate rules here. - -When `AGENTS.md` lands in this repository, retarget this pointer at it. diff --git a/Justfile b/Justfile index 5bcfa98e..a4ddf193 100644 --- a/Justfile +++ b/Justfile @@ -18,6 +18,9 @@ set positional-arguments := true # Re-generate with: contractile gen-just import? "build/contractile.just" +# Provisioning canon: setup, doctor, heal, dev-shell, eval, ai-setup, … (see PROVISIONING below) +mod provision 'build/just/provision.just' + # Project metadata — customize these project := "rsr-template-repo" OWNER := "hyperpolymath" @@ -52,7 +55,7 @@ info: @echo "Version: {{version}}" @echo "RSR Tier: {{tier}}" @echo "Recipes: $(just --summary | wc -w)" - @[ -f ".machine_readable/descriptiles/STATE.a2ml" ] && grep -oP 'phase\s*=\s*"\K[^"]+' .machine_readable/descriptiles/STATE.a2ml | head -1 | xargs -I{} echo "Phase: {}" || true + @d=$(bash scripts/deed-field.sh --find . 2>/dev/null) && bash scripts/deed-field.sh "$d" status phase | xargs -I{} echo "Phase: {}" || true # Run Invariant Path overlay tools for this repository invariant-path *ARGS: @@ -85,26 +88,19 @@ 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/ - @echo "Build complete" +# Build the project with every detected language's toolchain (here: pack/idris2 for +# the ABI, then `zig build` in src/interface/ffi). Replace the delegation with a +# body of your own when the project needs a different build. +build: provision::build # 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" + @echo "FAIL: 'just build-release' is not wired yet — nothing was built. Edit the 'build-release' recipe." >&2; exit 1 # Build and watch for changes (requires entr or similar) build-watch: @@ -113,7 +109,7 @@ build-watch: # Examples: # find src -name '*.rs' | entr -c just build # mix compile --force --warnings-as-errors - # deno task dev + # bun run dev # Clean build artifacts [reversible: rebuild with `just build`] clean: @@ -134,77 +130,76 @@ clean-all: clean # TEST & QUALITY # ═══════════════════════════════════════════════════════════════════════════════ -# Run all tests -test *args: - #!/usr/bin/env bash - # The proof gate: core proofs, countermodels and expected rejections - # (scripts/check.sh), then the laws census (scripts/minimal-laws.sh). - set -euo pipefail - bash scripts/check.sh - bash scripts/minimal-laws.sh +# Run every detected language's tests: `zig build test` covers src/interface/ffi +# (unit tests in src/main.zig, test/integration_test.zig). It compiles only after +# `just repo-init` has filled the template tokens, so an un-initialised template +# fails here loudly instead of reporting a pass over nothing. +test: provision::test # Run tests with verbose output -test-verbose: - @echo "Running tests (verbose)..." - # TODO: Replace with verbose test command +test-verbose: provision::test # Smoke test test-smoke: - @echo "Smoke test..." # TODO: Add basic sanity checks + @echo "FAIL: 'just test-smoke' is not wired yet — no smoke check ran. Edit the 'test-smoke' recipe." >&2; exit 1 # 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!" + bash tests/e2e.sh # 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!" + bash tests/aspect_tests.sh + +# Run benchmarks (performance regression detection). Reports N/A until a language +# declares some (e.g. a "bench" step in build.zig, [[bench]] in Cargo.toml). +bench: provision::bench + +# Run the proven-tests-and-benches 3-outcome suite (0 pass / 1 fail / 2 setup) +proven-tests *flags: + bash scripts/run-proven-suite.sh {{flags}} + +# Run the Idris2 proof escape-hatch & totality gate (proven-tests-and-benches) +escape-hatches: + bash scripts/check-escape-hatches.sh + +# Run template benchmarks and check Six-Sigma leave-one-out regression vs baseline +bench-check: + #!/usr/bin/env bash + set -euo pipefail + tmp="$(mktemp)" + trap 'rm -f "$tmp"' EXIT + bash benches/template_bench.sh --json . > "$tmp" + bash scripts/check-bench-regression.sh "$tmp" benches/baseline.json + +# Check RFC 7493 (I-JSON) + RFC 8785 (JCS) canonical form across tracked JSON +ijson-check: + bash scripts/check-ijson-jcs.sh --enforce . # 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!" + @echo "FAIL: 'just readiness' is not wired yet — no readiness test ran. Edit the 'readiness' recipe." >&2; exit 1 # 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" + @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 \ + @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" ;; \ @@ -213,16 +208,53 @@ crg-badge: 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)" + 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!" +# Run all quality checks — and fail when one of them ran nothing. +# +# This used to be `quality: fmt-check lint test` plus `@echo "All quality checks +# passed!"`. The echo is the defect: the provisioning engine reports a verb with +# no command for any detected language as +# +# info fmt-check: N/A for julia (archetype: library) — nothing to run… +# +# and exits 0. That is honest output, but this recipe turned it into "All +# quality checks passed!" — so a Julia repo printed green having run only +# `Pkg.test()`, and a downstream repo shipped `fmt`, `fmt-check` and `lint` +# recipes that were `@echo` stubs for the same reason. +# +# N/A is not a pass. A gating verb that cannot run for this repo's languages is +# either wired up (the julia-library archetype wires fmt/fmt-check/lint with +# scripts/julia-quality.jl) or removed from this recipe deliberately — never +# echoed over. +quality: + #!/usr/bin/env bash + set -uo pipefail + rc=0 + for verb in fmt-check lint test; do + echo "" + echo "── ${verb} ──" + out="$(just "${verb}" 2>&1)"; st=$? + printf '%s\n' "$out" + if [ "$st" -ne 0 ]; then + echo "FAIL: '${verb}' exited ${st}" >&2 + rc=1 + continue + fi + if printf '%s\n' "$out" | grep -q 'N/A for'; then + echo "FAIL: '${verb}' ran nothing — N/A for every detected language." >&2 + echo " N/A is not a pass: wire the verb for this language, or drop" >&2 + echo " it from the 'quality' recipe on purpose." >&2 + rc=1 + fi + done + [ "$rc" -eq 0 ] && echo "" && echo "All quality checks ran and passed." + exit "$rc" # Fix all auto-fixable issues [reversible: git checkout] fix: fmt @@ -233,46 +265,24 @@ fix: fmt # ═══════════════════════════════════════════════════════════════════════════════ # 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 +fmt: provision::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 +fmt-check: provision::fmt-check + +# Run linter (`zig fmt --check` on src/interface/ffi; like `test`, it parses the +# FFI sources only after `just repo-init` has filled the template tokens) +lint: provision::lint # ═══════════════════════════════════════════════════════════════════════════════ # RUN & EXECUTE # ═══════════════════════════════════════════════════════════════════════════════ -# Run the application -run *args: build - # TODO: Replace with your run command - echo "Run not configured yet" +# Run the application (N/A for a library; wire a "run" step or executable to enable) +run: provision::run # Run with verbose output -run-verbose *args: build - # TODO: Replace with verbose run command - echo "Run not configured yet" +run-verbose: run # Install to user path install: build-release @@ -300,14 +310,15 @@ deps-audit: # Examples: # cargo audit # mix audit - @command -v trivy >/dev/null && trivy fs --severity HIGH,CRITICAL --quiet . || true + @command -v trivy >/dev/null || { echo "FAIL: trivy is not installed, so nothing was audited (mise install, or edit this recipe)." >&2; exit 1; } + trivy fs --severity HIGH,CRITICAL --exit-code 1 --quiet . @echo "Audit complete" # ═══════════════════════════════════════════════════════════════════════════════ -# ARRIVAL PACK — agent-facing CLAUDE.md, compiled from a2ml +# ARRIVAL PACK — agent-facing CLAUDE.md, compiled from the repo deed # ═══════════════════════════════════════════════════════════════════════════════ -# Compile CLAUDE.md (the agent arrival pack) from this repo's a2ml +# Compile CLAUDE.md (the agent arrival pack) from this repo's deed claude-md: @bash .machine_readable/arrival-pack/generate.sh @@ -331,7 +342,7 @@ validate-repo-map: rm -f "$before" echo "repository map: up to date" -# Fail if CLAUDE.md's generated region drifted from a2ml or was hand-edited +# Fail if CLAUDE.md's generated region drifted from the deed or was hand-edited validate-claude-md: @bash .machine_readable/arrival-pack/verify.sh @@ -454,16 +465,17 @@ import? "build/just/validate.just" # STATE MANAGEMENT # ═══════════════════════════════════════════════════════════════════════════════ -# Update STATE.a2ml timestamp -state-touch: - @if [ -f ".machine_readable/descriptiles/STATE.a2ml" ]; then \ - sed -i 's/last-updated = "[^"]*"/last-updated = "'"$(date +%Y-%m-%d)"'"/' .machine_readable/descriptiles/STATE.a2ml && \ - echo "STATE.a2ml timestamp updated"; \ - fi +# Repo state lives in the repo deed's (status …) and (maturity …) clauses +# (rsr-template-repo#209); the journal is docs/status/ROADMAP.adoc. There is +# no last-updated stamp to touch: git log is the record of when it changed. -# Show current phase from STATE.a2ml +# Show the lifecycle phase and maturity from the repo deed state-phase: - @sed -n 's/^[[:space:]]*phase[[:space:]]*=[[:space:]]*"\([^"]*\)".*/\1/p' .machine_readable/descriptiles/STATE.a2ml 2>/dev/null | head -1 || echo "unknown" + #!/usr/bin/env bash + DEED=$(bash scripts/deed-field.sh --find . || true) + if [ -z "$DEED" ]; then echo "unknown (no *_chora.deed)"; exit 0; fi + echo "phase: $(bash scripts/deed-field.sh "$DEED" status phase || echo unknown)" + echo "maturity: $(bash scripts/deed-field.sh "$DEED" maturity level || echo unknown)" # ═══════════════════════════════════════════════════════════════════════════════ # GUIX @@ -485,7 +497,7 @@ guix-build: automate task="all": #!/usr/bin/env bash case "{{task}}" in - all) just fmt && just lint && just test && just docs && just state-touch ;; + all) just fmt && just lint && just test && just docs ;; cleanup) just clean && find . -name "*.orig" -delete && find . -name "*~" -delete ;; update) just deps && just validate ;; *) echo "Unknown: {{task}}. Use: all, cleanup, update" && exit 1 ;; @@ -581,15 +593,42 @@ 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." +# ═══════════════════════════════════════════════════════════════════════════════ +# PROVISIONING (standards 3-practice/provisioning/PROVISIONING-STANDARD.adoc) +# ═══════════════════════════════════════════════════════════════════════════════ +# The canon verbs live in the provision:: module; these delegations make +# `just ` and `just provision::` the same thing. Repository-specific +# checks go in a `doctor-local` / `setup-local` / `heal-local` recipe. + +# Install everything this repository needs, then run doctor +setup: provision::setup + +# Check the environment: PASS/WARN/FAIL with fix hints (exit 1 on any FAIL) +doctor: provision::doctor + +# Apply the safe fixes doctor knows, then re-run doctor +heal: provision::heal + +# Enter the Guix development shell (mise environment when Guix is absent) +dev-shell: provision::dev-shell + +# Bump mise to latest, re-lock mise.lock, re-pin the Guix channel +toolchain-refresh: provision::toolchain-refresh + +# Print the one sentence to give any AI assistant to set this repository up +ai-setup: provision::ai-setup + +# Print a warm-up to paste into any AI: user, dev or maintainer +ai-warmup who="user": (provision::ai-warmup who) + +# test + bench with timings, saved under .eval/ +eval: provision::eval + +# Where the toolchain and configuration are declared +config-show: provision::config-show + +# How to fetch this repository with OPSM +opsm: provision::opsm # Guided tour of key features tour: diff --git a/.github/SUPPORT.md b/SUPPORT.adoc similarity index 100% rename from .github/SUPPORT.md rename to SUPPORT.adoc diff --git a/archetypes/README.adoc b/archetypes/README.adoc index 8ed12ca7..60cbc4b0 100644 --- a/archetypes/README.adoc +++ b/archetypes/README.adoc @@ -6,22 +6,24 @@ An *archetype* specialises the spine for one kind of repository (a Julia library, a WordPress plugin, …) **as data, not as a fork**. Each archetype is a directory here: - archetypes//ARCHETYPE.a2ml required — the contract (see below) + archetypes//_praxis.deed required — the contract (see below) archetypes//overlay/ optional — files copied over the spine + archetypes//actions.lock required when the overlay ships workflows Decision record: `docs/decisions/0003-forge-and-sustain-lifecycle.adoc`. Normative lifecycle: standards `spec/SCAFFOLD-LIFECYCLE.adoc`. -== The contract (`ARCHETYPE.a2ml`) +== The contract (`_praxis.deed`) -Single-line values, grep-parseable (same discipline as the canon's -`template-capability-gates.toml`): +A `praxis-deed` (standards `1-formats/deed/spec/abnf/deed.abnf`), read by +`just repo-init` through `scripts/deed-field.sh`. Values are single-line +strings: -- `[metadata]` — `archetype`, `schema_version`. -- `[capability] preset = ""` — MUST name a preset in standards +- `(metadata :archetype … :schema_version …)`. +- `(capability :preset "")` — MUST name a preset in standards `.machine_readable/template-capability-gates.toml [presets]`. The archetype directory name and the preset name are the same string by convention. -- `[tokens]` — `TOKEN = "value"` lines. Only tokens the archetype can +- `(tokens :TOKEN "value" …)` — one pair per token. Only tokens the archetype can honestly determine (`PROJECT_KIND`, `PROJECT_DOMAIN`, `LANG_STACK`, `BUILD_CMD`, `TEST_CMD`, `DEPS`, `BUILD_OUTPUT_PATH`, `MAIN_FUNCTION`). Values MUST NOT contain `|` (the init sed delimiter — init skips such @@ -32,18 +34,75 @@ Single-line values, grep-parseable (same discipline as the canon's `just repo-init ` applies the overlay directory (if present), adds the token substitutions, and writes the preset into the minted repo's -`.machine_readable/rsr-profile.a2ml`. This whole `archetypes/` directory is +deed's `(rsr-profile)` clause. This whole `archetypes/` directory is template-only and is removed from the minted tree, exactly like `build/templates/`. +== Workflows and their lock records + +An overlay that ships workflows ships their lock records **beside** the +overlay, as `archetypes//actions.lock`, and never inside it. An +`overlay/.github/workflows/actions.lock` would replace the spine's lock when +the overlay is copied, and every spine workflow would then be refused at +startup for want of a record. That is how the first Julia mints +(ZeroInflatedCounts.jl, ResidualEvidenceTypes.jl) began with Lock Sync red. + +`just repo-init` merges the fragment into `.github/workflows/actions.lock` +with `scripts/merge-actions-lock.rs`: entries are unioned, and a key present +in both files with a different record stops the mint. Write the fragment with +the authoritative tool, never by hand: + +. Copy the overlay workflows into an empty git repository, under + `.github/workflows/` and under their minted names (drop the `.in`). +. Run `gh actions-lock --no-narrow` there, then `gh actions-lock --no-fix` + to check it. +. Copy the resulting `.github/workflows/actions.lock` to + `archetypes//actions.lock`. + +Regenerate it in the same PR as any `uses:` change in the overlay. +`tests/workflows/archetype_lock_merge_test.sh` mints each archetype's +workflow set and runs `scripts/check-lock-sync.sh` on the merged lock. + +== Removing modules the preset does not declare (`prune.txt`) + +The spine is polyglot on purpose: it carries modules that some archetypes need +and others must not have. An overlay adds files; it cannot subtract them — and +a Julia package that ships `build/container/` inherits a `Containerfile` built +for a service, which then fails `trust-container-images-pinned` in a repository +that will never build an image. + +So an archetype may ship a `prune.txt` beside its contract: one path per line, +relative to the minted root, `#` for comments, trailing `/` for a directory. +`just repo-init` reads it *after* it has recorded what the overlay wrote and +*before* it renames any `.in` file. It removes each listed path that exists +and warns on stderr when an entry is stale. The removed paths are recorded in +`MINT_REMOVES` and written to the minted variant provenance. + +Removal is a declaration: a line in `prune.txt` says "this preset does not +carry this capability", and the preset in +`.machine_readable/template-capability-gates.toml [presets]` should agree. It +is not a place to hide files that fail a gate. + == Current archetypes - `julia-library` — reference instance, harvested from - rsr-julia-library-template-repo's `VARIANT.a2ml` (ADR-0002) and the + rsr-julia-library-template-repo's variant record (ADR-0002) and the dormant scaffoldia registry's `julia/package.ncl`. The variant repo remains the full hand-maintained reference until the scaffoldia inversion; this archetype covers the `just repo-init` path. + Ships `overlay/scripts/julia-quality.jl` (the `fmt`, `fmt-check` and `lint` + verbs, run in a private Julia tools environment so Aqua and JuliaFormatter + never enter the package's own dependency set) and its + `provisioning_praxis.deed` override; prunes `build/container/`. +- `rust-cli` — the preset `rust-cli` from the canon. Ships `Cargo.toml.in`, + `src/{lib,main}.rs.in` and `tests/cli.rs.in`, so a minted CLI has a real + library-plus-binary split and one integration test rather than a + `println!` stub that no test can fail. Prunes `build/container/` for the same + reason as `julia-library`: a CLI that publishes no image should not ship a + `Containerfile`. Declared, content to follow (presets already reserved in the canon): -`wordpress-plugin`, `zotero-plugin`, `userscript`. Do not stub them empty — -an archetype exists when its contract and overlay are real. +`wordpress-plugin`, `zotero-plugin`, `userscript`, `rust-ffi-lib`, +`rust-service`, `formal-proof-lib`, `docs-site`, `affinescript-app`, `canon`. +Do not stub them empty — an archetype exists when its contract and overlay are +real. diff --git a/archetypes/julia-library/ARCHETYPE.a2ml b/archetypes/julia-library/ARCHETYPE.a2ml deleted file mode 100644 index 4a5359d1..00000000 --- a/archetypes/julia-library/ARCHETYPE.a2ml +++ /dev/null @@ -1,34 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# -# ARCHETYPE.a2ml — julia-library archetype for `just repo-init` (ADR-0003). -# -# Harvested 2026-07-21 from rsr-julia-library-template-repo (VARIANT.a2ml, -# ADR-0002 reference instance) and the dormant scaffoldia registry entry -# registry/julia/package.ncl. The variant repo remains the full -# hand-maintained reference (Project.toml [compat] closure, Aqua+JET, -# Documenter, flagship rubric); this archetype covers the `just repo-init` path. -# -# Contract rules: archetypes/README.adoc. Single-line values; no `|` in -# token values (init's sed delimiter). Tokens omitted here stay UNASSIGNED -# on purpose: PACKAGE_NAME and MUST_INVARIANTS are per-repo judgement, and -# an archetype must not write fiction. - -[metadata] -archetype = "julia-library" -name = "julia-library" -schema_version = "0.1.0" -harvested-from = "rsr-julia-library-template-repo VARIANT.a2ml + scaffoldia registry julia/package.ncl" - -[capability] -# Preset defined in standards .machine_readable/template-capability-gates.toml -preset = "julia-library" - -[tokens] -PROJECT_KIND = "library" -PROJECT_DOMAIN = "julia" -LANG_STACK = "Julia (1.9+)" -BUILD_CMD = "julia --project=. -e 'using Pkg; Pkg.instantiate()'" -TEST_CMD = "julia --project=. -e 'using Pkg; Pkg.test()'" -DEPS = "Julia General registry via Project.toml [deps] with [compat] closure" -BUILD_OUTPUT_PATH = "src/" diff --git a/archetypes/julia-library/actions.lock b/archetypes/julia-library/actions.lock new file mode 100644 index 00000000..d7fca002 --- /dev/null +++ b/archetypes/julia-library/actions.lock @@ -0,0 +1,41 @@ +# This file is machine-generated by `gh actions-lock`. +# Do not edit by hand; run `gh actions-lock` to update. +# Docs: https://gh.io/actions-lockfile +version: 'v0.0.3' +workflows: + '.github/workflows/julia-ci.yml': + - 'actions/checkout@v7.0.1' + - 'julia-actions/cache@v3.5.0' + - 'julia-actions/setup-julia@v3.0.2' + '.github/workflows/julia-docs.yml': + - 'actions/checkout@v7.0.1' + - 'actions/download-artifact@v8.0.2' + - 'actions/upload-artifact@v7.0.2' + - 'julia-actions/cache@v3.5.0' + - 'julia-actions/setup-julia@v3.0.2' +dependencies: + 'actions/checkout@v7.0.1': + ref: 'v7.0.1' + commit: 'sha1-3d3c42e5aac5ba805825da76410c181273ba90b1' + owner_id: 44036562 + repo_id: 197814629 + 'actions/download-artifact@v8.0.2': + ref: 'v8.0.2' + commit: 'sha1-9000827ccba6bdab643e8b6fd33ac0654aef8333' + owner_id: 44036562 + repo_id: 192626254 + 'actions/upload-artifact@v7.0.2': + ref: 'v7.0.2' + commit: 'sha1-cf430e030ddbb5b0abf93d22962f4752f3646cd9' + owner_id: 44036562 + repo_id: 192625955 + 'julia-actions/cache@v3.5.0': + ref: 'v3.5.0' + commit: 'sha1-9353db09a0f2bbbdec6f41791918c75d37391b36' + owner_id: 53965732 + repo_id: 441908600 + 'julia-actions/setup-julia@v3.0.2': + ref: 'v3.0.2' + commit: 'sha1-fa02766e078afaaf09b14210362cee14137e6a32' + owner_id: 53965732 + repo_id: 202020219 diff --git a/archetypes/julia-library/julia-library_praxis.deed b/archetypes/julia-library/julia-library_praxis.deed new file mode 100644 index 00000000..497ea931 --- /dev/null +++ b/archetypes/julia-library/julia-library_praxis.deed @@ -0,0 +1,37 @@ +;; SPDX-License-Identifier: MPL-2.0 +;; SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) +;; +;; julia-library_praxis.deed — the julia-library archetype for `just repo-init` +;; (ADR-0003). repo-init reads it with scripts/deed-field.sh: +;; (capability :preset) the capability preset; and +;; (tokens :) each value fills {{}} at mint. +;; +;; Harvested 2026-07-21 from rsr-julia-library-template-repo (its variant +;; record, the ADR-0002 reference instance) and the dormant scaffoldia registry +;; entry registry/julia/package.ncl. The variant repo remains the full +;; hand-maintained reference (Project.toml [compat] closure, Aqua+JET, +;; Documenter, flagship rubric); this archetype covers the `just repo-init` path. +;; +;; Contract rules: archetypes/README.adoc. Single-line values; no `|` in token +;; values (init's sed delimiter). Tokens omitted here stay UNASSIGNED on +;; purpose: PACKAGE_NAME and MUST_INVARIANTS are per-repo judgement, and an +;; archetype must not write fiction. +(praxis-deed + :schema-version "1.0.0" + :canonical-name "rsr-template-repo-archetype-julia-library" + (metadata + :archetype "julia-library" + :name "julia-library" + :schema_version "0.1.0" + :harvested-from "rsr-julia-library-template-repo variant record + scaffoldia registry julia/package.ncl") + (capability + ; Preset defined in standards .machine_readable/template-capability-gates.toml + :preset "julia-library") + (tokens + :PROJECT_KIND "library" + :PROJECT_DOMAIN "julia" + :LANG_STACK "Julia (1.9+)" + :BUILD_CMD "julia --project=. -e 'using Pkg; Pkg.instantiate()'" + :TEST_CMD "julia --project=. -e 'using Pkg; Pkg.test()'" + :DEPS "Julia General registry via Project.toml [deps] with [compat] closure" + :BUILD_OUTPUT_PATH "src/")) diff --git a/archetypes/julia-library/overlay/.github/workflows/actions.lock b/archetypes/julia-library/overlay/.github/workflows/actions.lock deleted file mode 100644 index abfe3a3a..00000000 --- a/archetypes/julia-library/overlay/.github/workflows/actions.lock +++ /dev/null @@ -1,18 +0,0 @@ -# This file is machine-generated by `gh actions-lock`. -# Do not edit by hand; run `gh actions-lock` to update. -# Docs: https://gh.io/actions-lockfile -# -# Minted with the julia-library archetype. Resolutions verified 2026-09-19 -# (see the workflow headers). Regenerate in the same PR as any uses: change. -version: 'v0.0.2' -workflows: - '.github/workflows/julia-ci.yml': - - 'actions/checkout@v7.0.1' - - 'julia-actions/cache@v2' - - 'julia-actions/setup-julia@v3.0.2' - '.github/workflows/julia-docs.yml': - - 'actions/checkout@v7.0.1' - - 'julia-actions/cache@v2' - - 'julia-actions/julia-buildpkg@v1' - - 'julia-actions/julia-docdeploy@v1' - - 'julia-actions/setup-julia@v3.0.2' diff --git a/archetypes/julia-library/overlay/.github/workflows/julia-ci.yml.in b/archetypes/julia-library/overlay/.github/workflows/julia-ci.yml.in index 9160ce7e..956a90f1 100644 --- a/archetypes/julia-library/overlay/.github/workflows/julia-ci.yml.in +++ b/archetypes/julia-library/overlay/.github/workflows/julia-ci.yml.in @@ -1,11 +1,14 @@ +# This workflow is managed by gh actions-lock. +# SPDX-License-Identifier: MPL-2.0 # {{PROJECT_NAME}} — Julia CI (julia-library archetype) # # Pin posture (estate ruling R2, 2026-09-02; D38/D39 resolution 2026-09-19): # symbolic refs here, pinned by .github/workflows/actions.lock (same dir). -# Refs resolved 2026-09-19 against the estate estate-pins: -# actions/checkout@v7.0.1 = 3d3c42e5aac5ba805825da76410c181273ba90b1 +# The lock records come from archetypes/julia-library/actions.lock, merged +# into the spine's lock at mint. Refs resolved 2026-10-09: +# actions/checkout@v7.0.1 = 3d3c42e5aac5ba805825da76410c181273ba90b1 # julia-actions/setup-julia@v3.0.2 = fa02766e078afaaf09b14210362cee14137e6a32 -# julia-actions/cache@v2 = a7bed9df697e5d7309d68afe7542a87621a8b6c8 +# julia-actions/cache@v3.5.0 = 9353db09a0f2bbbdec6f41791918c75d37391b36 # Regenerate the lock in the SAME PR as any uses: change (estate MUST). name: Julia CI @@ -15,15 +18,22 @@ on: branches: [main, master] pull_request: -# No `continue-on-error` on a MUST check (R1–R9): a red job is the gate -# working. Coverage (R4) is reported by the estate's standard coverage -# upload where present; it is not a blocker at template level. +permissions: + contents: read + +concurrency: + group: julia-ci-${{ github.ref }} + cancel-in-progress: true + jobs: fmt: name: Format (JuliaFormatter) - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 + timeout-minutes: 10 steps: - uses: actions/checkout@v7.0.1 + with: + persist-credentials: false - uses: julia-actions/setup-julia@v3.0.2 with: version: "1" @@ -33,13 +43,13 @@ jobs: using Pkg Pkg.add("JuliaFormatter") using JuliaFormatter - for f in filter(isfile, Iterators.flatten(( + for f in filter(isfile, collect(Iterators.flatten(( [joinpath("src", x) for x in readdir("src")], [joinpath("test", x) for x in readdir("test") if x != "cases"], [joinpath("test", "cases", x) for x in readdir(joinpath("test", "cases"))], - ))) + )))) text = read(f, String) - formatted = JuliaFormatter.format_string(text) + formatted = JuliaFormatter.format_text(text) if text != formatted @error "not formatted" file=f exit(1) @@ -48,37 +58,48 @@ jobs: jet: name: Static analysis (JET) - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 + timeout-minutes: 10 steps: - uses: actions/checkout@v7.0.1 + with: + persist-credentials: false - uses: julia-actions/setup-julia@v3.0.2 with: version: "1" - - uses: julia-actions/cache@v2 - - name: JET.test_package + - uses: julia-actions/cache@v3.5.0 + - name: JET analysis (supported API) run: | - julia --project=. -e ' + julia -e ' using Pkg - Pkg.add("JET") - using JET - JET.test_package(path=".", julia_version="1")' + Pkg.activate(mktempdir()) + Pkg.develop(path=".") + Pkg.add(Pkg.PackageSpec(name="JET", version="0.12")) + using {{PROJECT_NAME}}, JET + + if !hasmethod(JET.test_package, (Module,)) + error("JET ", pkgversion(JET), " has no test_package(::Module) — " * + "the julia-library overlay pins an API that no longer exists.") + end + + JET.test_package({{PROJECT_NAME}})' test: name: Test (Test + Aqua) - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 + timeout-minutes: 15 strategy: fail-fast: false matrix: - # The [compat] floor IS tested — an untested floor is an unproven - # floor (measured estate gap: Axiology-class repos declare julia 1.9 - # but test 1.10/1.11 only). julia: ["1.9", "1"] - os: [ubuntu-latest] + os: [ubuntu-24.04] steps: - uses: actions/checkout@v7.0.1 + with: + persist-credentials: false - uses: julia-actions/setup-julia@v3.0.2 with: version: ${{ matrix.julia }} - - uses: julia-actions/cache@v2 + - uses: julia-actions/cache@v3.5.0 - name: Pkg.test() run: julia --project=. -e 'using Pkg; Pkg.test()' diff --git a/archetypes/julia-library/overlay/.github/workflows/julia-docs.yml.in b/archetypes/julia-library/overlay/.github/workflows/julia-docs.yml.in index d6e8c613..fe55bb8f 100644 --- a/archetypes/julia-library/overlay/.github/workflows/julia-docs.yml.in +++ b/archetypes/julia-library/overlay/.github/workflows/julia-docs.yml.in @@ -1,41 +1,91 @@ +# This workflow is managed by gh actions-lock. +# SPDX-License-Identifier: MPL-2.0 # {{PROJECT_NAME}} — docs build & deploy (julia-library archetype) # -# Fails LOUD while docs/ is absent: a declared `docs-site` capability with -# no build is a defect (criterion 5.2.6, na-honesty). Once -# docs/Project.toml + docs/make.jl + docs/src/ exist, this builds and -# deploys via julia-actions/julia-docdeploy (canonical action, verified -# 2026-09-19: main = 9bff73f68f6a2aa952c8856564f3bd4aea155c15). -# -# Pin posture (estate ruling R2 / D38-D39): symbolic refs, pinned by -# .github/workflows/actions.lock. Regenerate the lock in the same PR as -# any uses: change. +# Split into an unprivileged `build` job (`contents: read`, no write token +# exposed to untrusted package/doc evaluation — issue #232) and a minimal +# `deploy` job (`contents: write`) that publishes only the pre-built artifact +# to `gh-pages` on default-branch pushes. name: Docs on: push: branches: [main, master] + pull_request: workflow_dispatch: +permissions: + contents: read + +concurrency: + group: julia-docs-${{ github.ref }} + cancel-in-progress: true + jobs: - docs: - name: Build and deploy - runs-on: ubuntu-latest + build: + name: Build docs (read-only) + runs-on: ubuntu-24.04 + timeout-minutes: 15 + permissions: + contents: read steps: - uses: actions/checkout@v7.0.1 + with: + persist-credentials: false - name: Layout gate — fail loud while docs/ is absent run: | if [ ! -f docs/Project.toml ] || [ ! -f docs/make.jl ] || [ ! -d docs/src ]; then - echo "::error::docs-site declared but no Documenter build: docs/Project.toml, docs/make.jl and docs/src/ are required. Either add the build or drop the docs-site capability from rsr-profile.a2ml." + echo "::error::docs-site declared but no Documenter build: docs/Project.toml, docs/make.jl and docs/src/ are required. Either add the build or drop the docs-site capability from the repo deed's (rsr-profile) clause." exit 1 fi - uses: julia-actions/setup-julia@v3.0.2 with: version: "1" - - uses: julia-actions/cache@v2 - # PIN-ME: resolve and lock this in the first estate pass (4.1.3 - # stays loud until pinned). Ref resolved 2026-09-19. - - uses: julia-actions/julia-buildpkg@v1 - - uses: julia-actions/julia-docdeploy@v1 + - uses: julia-actions/cache@v3.5.0 + - name: Instantiate the docs environment + run: julia --project=docs -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()' + - name: Build static site without write credentials env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + # Suppress Documenter deploydocs push inside the build job; deploy + # happens in the isolated job below without executing Julia code. + GITHUB_EVENT_NAME: pull_request + run: | + julia --project=docs docs/make.jl + test -d docs/build + - name: Upload built site artifact + uses: actions/upload-artifact@v7.0.2 + with: + name: julia-docs-site + path: docs/build + retention-days: 5 + + deploy: + name: Deploy docs to gh-pages + needs: build + if: (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master') + runs-on: ubuntu-24.04 + timeout-minutes: 10 + permissions: + contents: write + steps: + - name: Download built site artifact + uses: actions/download-artifact@v8.0.2 + with: + name: julia-docs-site + path: site + - name: Publish static site to gh-pages branch + env: + REPO: ${{ github.repository }} + SHA: ${{ github.sha }} + TOKEN: ${{ github.token }} + run: | + set -euo pipefail + AUTH="AUTHORIZATION: basic $(printf 'x-access-token:%s' "${TOKEN}" | base64 -w0)" + touch site/.nojekyll + git -C site init -q -b gh-pages + git -C site config user.name "github-actions[bot]" + git -C site config user.email "41898282+github-actions[bot]@users.noreply.github.com" + git -C site add -A + git -C site commit -q -m "docs: deploy ${SHA:0:12}" + git -C site -c http.extraheader="${AUTH}" push -q --force "https://github.com/${REPO}.git" gh-pages:gh-pages diff --git a/archetypes/julia-library/overlay/.machine_readable/descriptiles/provisioning_praxis.deed b/archetypes/julia-library/overlay/.machine_readable/descriptiles/provisioning_praxis.deed new file mode 100644 index 00000000..b719b8b3 --- /dev/null +++ b/archetypes/julia-library/overlay/.machine_readable/descriptiles/provisioning_praxis.deed @@ -0,0 +1,38 @@ +;; SPDX-License-Identifier: MPL-2.0 +;; SPDX-FileCopyrightText: {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> +;; +;; provisioning_praxis.deed: the repo-specific facts behind `just setup/doctor/run/…`. +;; build/just/provision-lib.sh reads each `:key "value"` field below. Rules: +;; * one key per line, value in double quotes, and no double quote inside a value; +;; * an empty value "" means "use the per-language default"; +;; * a verb key (build test bench lint fmt fmt-check run deps) replaces the default. +;; +;; Written by the julia-library archetype at mint. The three overrides below are +;; the point: the engine has no Julia formatter or linter, so fmt, fmt-check and +;; lint were N/A, exited 0, and `just quality` printed a pass having run nothing +;; but `Pkg.test()` (measured in every Julia repo minted from this template +;; before 2026-10-30). scripts/julia-quality.jl supplies them. +;; +;; Canon: hyperpolymath/standards 3-practice/provisioning/PROVISIONING-STANDARD.adoc +(praxis-deed + :schema-version "1.0.0" + :canonical-name "{{PROJECT_NAME}}-provisioning" + :repo "{{OWNER}}/{{REPO}}" + :archetype "library" ; app | library | tool | theory | docs + :languages "julia" ; detected; informational + ;; Contract-verb overrides ("" = per-language default, which `just langs` shows) + :build "" + :test "" + :bench "" + :lint "julia --project=. scripts/julia-quality.jl lint" + :fmt "julia --project=. scripts/julia-quality.jl fmt" + :fmt-check "julia --project=. scripts/julia-quality.jl fmt-check" + :run "" + :deps "" + ;; Facts shown by `just config-show` and checked by `just doctor` + :config "" + :ports "" + :system-deps "julia" + ;; What `just ai-setup` and `just opsm` print ("" = the generic line) + :ai-say-it "" + :opsm-note "") diff --git a/archetypes/julia-library/overlay/Project.toml.in b/archetypes/julia-library/overlay/Project.toml.in index ce0bc79a..0fa4b006 100644 --- a/archetypes/julia-library/overlay/Project.toml.in +++ b/archetypes/julia-library/overlay/Project.toml.in @@ -1,11 +1,17 @@ +# SPDX-License-Identifier: MPL-2.0 +# SPDX-FileCopyrightText: {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> +# # minted by: just repo-init julia-library ({{CURRENT_YEAR}}) # owner: {{OWNER}} # -# uuid = "{{PACKAGE_UUID}}" is DERIVED at mint (UUIDv5 over the repo -# identity — see repo-init's julia-library rule); it is stable across -# re-mints of the same repo and is never hand-edited. If the mint could not -# derive it (no uuidgen AND no python3 on the operator machine) it is -# UNASSIGNED and Pkg refuses to load the package until the owner assigns one. +# uuid = "{{PACKAGE_UUID}}" is MINTED at mint as UUIDv8 profile C over the +# registered domain julia-package-identity, preimage +# github.com// (see repo-init's julia-library rule; the strict +# UUIDv8 gate rejects the v5 mint per ADR-008 D320). Profile C is +# deterministic, so the uuid is stable across re-mints of the same repo and +# never hand-edited. If the mint could not derive it (no python3 and no bun +# with standards' uuid-v8.js on the operator machine) it is UNASSIGNED and +# Pkg refuses to load the package until the owner assigns one. name = "{{PROJECT_NAME}}" uuid = "{{PACKAGE_UUID}}" diff --git a/archetypes/julia-library/overlay/scripts/julia-quality.jl b/archetypes/julia-library/overlay/scripts/julia-quality.jl new file mode 100644 index 00000000..d9275608 --- /dev/null +++ b/archetypes/julia-library/overlay/scripts/julia-quality.jl @@ -0,0 +1,129 @@ +#!/usr/bin/env julia +# SPDX-License-Identifier: MPL-2.0 +# SPDX-FileCopyrightText: {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> +# +# julia-quality.jl — the `fmt`, `fmt-check` and `lint` verbs for a Julia package. +# +# ── Why this file exists ──────────────────────────────────────────────────── +# +# `just quality` is fmt-check + lint + test. For a Julia package the engine had +# no command for fmt-check or lint, so both reported N/A, exited 0, and +# `just quality` printed a pass having run only `Pkg.test()`. A gate that cannot +# fail is not a gate. +# +# ── Why the tools live in their own environment ───────────────────────────── +# +# JuliaFormatter and Aqua are DEVELOPMENT tools. Putting them in the package's +# [deps] would ship them to every user of the library — and Aqua's own +# deps_compat/stale-deps checks fail a package that does that. `[extras]` is not +# enough either: extras resolve only inside `Pkg.test`'s temporary environment, +# so `julia --project=. -e 'using JuliaFormatter'` cannot see them. +# +# So they get a private environment (default ~/.cache/rsr/julia-quality, +# override with RSR_JULIA_QUALITY_ENV), the package is `develop`ed into it for +# lint, and the package's own Project.toml stays honest. The first run resolves +# the tools from the registry; the depot caches them afterwards. +# +# ── Usage ─────────────────────────────────────────────────────────────────── +# julia --project=. scripts/julia-quality.jl fmt # rewrite +# julia --project=. scripts/julia-quality.jl fmt-check # fail if it would +# julia --project=. scripts/julia-quality.jl lint # Aqua shape gate +# +# Exit: 0 pass, 1 finding, 2 usage, 3 the tool environment could not be built. + +using Pkg + +const ROOT = normpath(joinpath(@__DIR__, "..")) +const TOOLS = get(ENV, "RSR_JULIA_QUALITY_ENV", + joinpath(homedir(), ".cache", "rsr", "julia-quality")) +const CMD = isempty(ARGS) ? "" : ARGS[1] + +if !(CMD in ("fmt", "fmt-check", "lint")) + println(stderr, "usage: julia --project=. scripts/julia-quality.jl fmt|fmt-check|lint") + exit(2) +end + +mkpath(TOOLS) +Pkg.activate(TOOLS; io = devnull) + +"""Install `pkg` into the tools environment unless it is already loadable.""" +function ensure(pkg::AbstractString) + Base.find_package(pkg) === nothing || return + try + Pkg.add(pkg; io = devnull) + catch err + println(stderr, "FAIL: could not install ", pkg, " into ", TOOLS, ": ", err) + println(stderr, " a quality gate that cannot run its tool is not a pass.") + exit(3) + end + if Base.find_package(pkg) === nothing + println(stderr, "FAIL: ", pkg, " is still not loadable after Pkg.add") + exit(3) + end + return +end + +if CMD == "fmt" || CMD == "fmt-check" + ensure("JuliaFormatter") + @eval using JuliaFormatter + + # Judge by content, not by JuliaFormatter's return value. Its `format` + # documents the return as "was the tree already formatted" in some releases + # and "did it write" in others, so `changed` inverted this check on at least + # one: a clean scaffold failed and an unformatted one passed. Formatting a + # COPY and diffing the bytes cannot be ambiguous. + jl_files(root) = [joinpath(d, f) for (d, _, fs) in walkdir(root) + for f in fs if endswith(f, ".jl")] + + if CMD == "fmt" + n = length(jl_files(ROOT)) + format(ROOT; overwrite = true, verbose = false) + println("PASS: formatted ", n, " Julia file(s) in place") + else + tmp = mktempdir() + copy_root = joinpath(tmp, "tree") + cp(ROOT, copy_root; force = true) + before = Dict(f => read(f) for f in jl_files(copy_root)) + format(copy_root; overwrite = true, verbose = false) + dirty = sort!([relpath(f, copy_root) for (f, bytes) in before if read(f) != bytes]) + rm(tmp; recursive = true, force = true) + if !isempty(dirty) + println(stderr, "FAIL: JuliaFormatter would rewrite ", length(dirty), + " file(s) — run: just fmt") + foreach(f -> println(stderr, " ", f), dirty) + exit(1) + end + println("PASS: Julia formatting is clean") + end +else + ensure("Aqua") + # Aqua checks a LOADED package: develop this one into the tools environment + # so its own dependencies resolve, then bring it into scope by the name its + # Project.toml declares (a package's module name is not its directory name). + try + Pkg.develop(Pkg.PackageSpec(path = ROOT); io = devnull) + catch err + println(stderr, "FAIL: could not develop ", ROOT, " into the tools environment: ", err) + exit(3) + end + @eval using Aqua + + text = read(joinpath(ROOT, "Project.toml"), String) + m = match(r"(?m)^name\s*=\s*\"([^\"]+)\"", text) + if m === nothing + println(stderr, "FAIL: no name = \"…\" line in Project.toml") + exit(1) + end + modname = Symbol(m.captures[1]) + try + # `using Pkg` parses to Expr(:using, Expr(:., :Pkg)); a colon node is the + # `using A: b` form. Building the colon expression loads nothing, so the + # check failed for every package it was meant to validate. + Base.eval(Main, Meta.parse("using " * String(modname))) + catch err + println(stderr, "FAIL: the package does not load: ", err) + exit(1) + end + Aqua.test_all(getfield(Main, modname)) + println("PASS: Aqua package-shape checks are clean") +end diff --git a/archetypes/julia-library/overlay/src/PACKAGE.jl.in b/archetypes/julia-library/overlay/src/PACKAGE.jl.in index 3084a24d..3ac2c8a6 100644 --- a/archetypes/julia-library/overlay/src/PACKAGE.jl.in +++ b/archetypes/julia-library/overlay/src/PACKAGE.jl.in @@ -1,9 +1,12 @@ +# SPDX-License-Identifier: MPL-2.0 +# SPDX-FileCopyrightText: {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> +# module {{PROJECT_NAME}} # {{PROJECT_NAME}} — {{PROJECT_DESCRIPTION}} # # Forged from the hyperpolymath julia-library archetype ({{CURRENT_YEAR}}). -# Provenance: MINT-PROVENANCE.a2ml at the repo root. +# Provenance: the repo deed's (provenance) clause, written at mint. # # The public API is whatever is `export`ed below; Aqua's exports/ambiguity # checks gate it from the first mint, so keep exports deliberate. diff --git a/archetypes/julia-library/overlay/test/cases/smoke.jl b/archetypes/julia-library/overlay/test/cases/smoke.jl index e3cddcb9..6d3c2ed9 100644 --- a/archetypes/julia-library/overlay/test/cases/smoke.jl +++ b/archetypes/julia-library/overlay/test/cases/smoke.jl @@ -1,3 +1,6 @@ +# SPDX-License-Identifier: MPL-2.0 +# SPDX-FileCopyrightText: {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> +# # smoke.jl — the archetype's load-check case. # # This case proves the package LOADS (module resolution, no parse/load diff --git a/archetypes/julia-library/overlay/test/runtests.jl b/archetypes/julia-library/overlay/test/runtests.jl index a8495e12..021c5df9 100644 --- a/archetypes/julia-library/overlay/test/runtests.jl +++ b/archetypes/julia-library/overlay/test/runtests.jl @@ -1,3 +1,6 @@ +# SPDX-License-Identifier: MPL-2.0 +# SPDX-FileCopyrightText: {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> +# # {{PROJECT_NAME}} — test entry point (julia-library archetype) # # Two suites, in this order: @@ -7,7 +10,7 @@ # 2. Behaviour — every test/cases/*.jl is included. The shipped case # (smoke.jl) is a LOAD check only; replace/extend it as real # behaviour tests land. Until then, `Pkg.test()` passing is necessary -# but NOT sufficient — record that in STATE.a2ml (smoke-only suite). +# but NOT sufficient — record that in docs/status/ROADMAP.adoc (smoke-only suite). using Test using {{PROJECT_NAME}} diff --git a/archetypes/julia-library/prune.txt b/archetypes/julia-library/prune.txt new file mode 100644 index 00000000..e2c7385f --- /dev/null +++ b/archetypes/julia-library/prune.txt @@ -0,0 +1,14 @@ +# SPDX-License-Identifier: MPL-2.0 +# +# Spine modules this archetype does NOT carry, one repository-relative path per +# line. `container-images-pinned` means an unpinned Containerfile cannot ship; +# a Julia package has nothing to deploy, so the deployed-container module is +# dropped rather than shipped floating. The dev container stays (it is a +# development environment, not an artifact, and the pin gate scopes it out). +build/container/ +# Same rule for the polyglot seam: a Julia package declares neither the abi nor +# the ffi capability, so src/interface/ (abi.ipkg, ffi/build.zig) is carrier data +# from the template's spine, not part of this package. Shipping it made the mint +# detect Idris2 and Zig, install both, and run `idris2 --build` from `just build` +# in a package written in one language. +src/interface/ diff --git a/archetypes/rust-cli/overlay/Cargo.toml.in b/archetypes/rust-cli/overlay/Cargo.toml.in new file mode 100644 index 00000000..2df2623f --- /dev/null +++ b/archetypes/rust-cli/overlay/Cargo.toml.in @@ -0,0 +1,30 @@ +# SPDX-License-Identifier: MPL-2.0 +# SPDX-FileCopyrightText: {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> +# +# minted by: just repo-init rust-cli ({{CURRENT_YEAR}}) +# +# The package name is the repository slug; the CRATE name (what `use` sees) is +# its underscored form, which is the token used in src/*.rs and tests/*.rs. +# `cargo build --all-targets` and `cargo test --all-targets` are what +# `just build` and `just test` run (provision-lib.sh lang_cmd rust:*). + +[package] +name = "{{REPO}}" +version = "0.1.0" +edition = "2021" +rust-version = "1.80" +license = "MPL-2.0" +description = "{{PROJECT_DESCRIPTION}}" +authors = ["{{AUTHOR}} <{{AUTHOR_EMAIL}}>"] +repository = "https://{{FORGE}}/{{OWNER}}/{{REPO}}" +readme = "README.adoc" + +[dependencies] + +# Keep the release profile explicit: a CLI is shipped as a binary, and the +# defaults differ between toolchains more than they look. +[profile.release] +codegen-units = 1 +lto = true +panic = "abort" +strip = true diff --git a/archetypes/rust-cli/overlay/src/lib.rs.in b/archetypes/rust-cli/overlay/src/lib.rs.in new file mode 100644 index 00000000..a9bf7c75 --- /dev/null +++ b/archetypes/rust-cli/overlay/src/lib.rs.in @@ -0,0 +1,22 @@ +// SPDX-License-Identifier: MPL-2.0 +// SPDX-FileCopyrightText: {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> +//! +//! {{PROJECT_DESCRIPTION}} +//! +//! The library half of the crate, so the behaviour is testable without spawning +//! the binary. Keep `main.rs` a thin shell around this. + +/// One line describing what this program is, used by `--version` and the tests. +pub fn about() -> String { + format!("{{REPO}} {}", env!("CARGO_PKG_VERSION")) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn about_names_the_package() { + assert!(about().starts_with("{{REPO}} ")); + } +} diff --git a/archetypes/rust-cli/overlay/src/main.rs.in b/archetypes/rust-cli/overlay/src/main.rs.in new file mode 100644 index 00000000..ebad037e --- /dev/null +++ b/archetypes/rust-cli/overlay/src/main.rs.in @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MPL-2.0 +// SPDX-FileCopyrightText: {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> + +fn main() { + println!("{}", {{project}}::about()); +} diff --git a/archetypes/rust-cli/overlay/tests/cli.rs.in b/archetypes/rust-cli/overlay/tests/cli.rs.in new file mode 100644 index 00000000..098944d0 --- /dev/null +++ b/archetypes/rust-cli/overlay/tests/cli.rs.in @@ -0,0 +1,14 @@ +// SPDX-License-Identifier: MPL-2.0 +// SPDX-FileCopyrightText: {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> +//! +//! An integration test, so `cargo test --all-targets` runs something real from +//! the day the repo is minted. `cargo test` with no tests at all exits 0, and a +//! green suite that contains no test is the same fake gate as one that is +//! skipped. + +use {{project}}::about; + +#[test] +fn about_is_not_empty() { + assert!(!about().is_empty()); +} diff --git a/archetypes/rust-cli/prune.txt b/archetypes/rust-cli/prune.txt new file mode 100644 index 00000000..34b1f778 --- /dev/null +++ b/archetypes/rust-cli/prune.txt @@ -0,0 +1,15 @@ +# SPDX-License-Identifier: MPL-2.0 +# +# Spine modules this archetype does NOT carry, one repository-relative path per +# line. `container-images-pinned` means an unpinned Containerfile cannot ship; +# a CLI library has nothing to deploy, so the deployed-container module is +# dropped rather than shipped floating. The dev container stays (it is a +# development environment, not an artifact, and the pin gate scopes it out). +build/container/ +# The contract above says it plainly: "nothing here declares the ffi or abi +# capability, so the archetype must not ship the ...". The seam is the template's +# polyglot spine — src/interface/abi.ipkg (Idris2) and src/interface/ffi/build.zig +# (Zig) — and carrying it made a Rust CLI detect THREE languages: render-mise.sh +# installed idris2 and zig, and the inherited build/test recipes ran them. A +# Rust CLI that needs an Idris2 toolchain is not a Rust CLI. +src/interface/ diff --git a/archetypes/rust-cli/rust-cli_praxis.deed b/archetypes/rust-cli/rust-cli_praxis.deed new file mode 100644 index 00000000..e8614b12 --- /dev/null +++ b/archetypes/rust-cli/rust-cli_praxis.deed @@ -0,0 +1,37 @@ +;; SPDX-License-Identifier: MPL-2.0 +;; SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) +;; +;; rust-cli_praxis.deed — the rust-cli archetype for `just repo-init` +;; (ADR-0003). repo-init reads it with scripts/deed-field.sh: +;; (capability :preset) the capability preset; and +;; (tokens :) each value fills {{}} at mint. +;; +;; The preset name matches a [presets] entry in standards +;; .machine_readable/template-capability-gates.toml: +;; rust-cli = ["rust", "cli", "library"] +;; It is deliberately the CLI/library preset and not rust-ffi-lib: nothing here +;; declares the ffi or abi capability, so the archetype must not ship the +;; Zig/Idris2 seam as if it did. +;; +;; Contract rules: archetypes/README.adoc. Single-line values; no `|` in token +;; values (init's sed delimiter). Tokens omitted here stay UNASSIGNED on +;; purpose: PACKAGE_NAME and MUST_INVARIANTS are per-repo judgement, and an +;; archetype must not write fiction. +(praxis-deed + :schema-version "1.0.0" + :canonical-name "rsr-template-repo-archetype-rust-cli" + (metadata + :archetype "rust-cli" + :name "rust-cli" + :schema_version "0.1.0") + (capability + ; Preset defined in standards .machine_readable/template-capability-gates.toml + :preset "rust-cli") + (tokens + :PROJECT_KIND "cli" + :PROJECT_DOMAIN "rust" + :LANG_STACK "Rust (edition 2021)" + :BUILD_CMD "cargo build --release" + :TEST_CMD "cargo test --all-targets" + :DEPS "crates.io via Cargo.toml with a [compat] floor per dependency" + :BUILD_OUTPUT_PATH "target/release/")) diff --git a/benches/baseline.json b/benches/baseline.json new file mode 100644 index 00000000..5c83c105 --- /dev/null +++ b/benches/baseline.json @@ -0,0 +1 @@ +{"bench_schema_version":1,"kind":"proven-bench-baseline","method":"arithmetic mean over the source runs (taxonomy: mean of the last 10 CI runs on main)","note":"Manual tolerance override (taxonomy Part IV permits one with a stated reason): the checker fails at 2.0x the baseline ratio or 2.5x the baseline absolute median, not the taxonomy 1.5x, because 1.5x would have failed green runs on shared GitHub runners (max observed ratio 1.53x, absolute 1.65x). Measured numbers are in benchmarks/README.adoc and scripts/check-bench-regression.sh.","schema_version":1,"sources":[{"commit":"a839e784139f68e94f353ac4228842b6df12d921","run_id":"2001"},{"commit":"a839e784139f68e94f353ac4228842b6df12d921","run_id":"2002"},{"commit":"a839e784139f68e94f353ac4228842b6df12d921","run_id":"2003"},{"commit":"a839e784139f68e94f353ac4228842b6df12d921","run_id":"2004"},{"commit":"a839e784139f68e94f353ac4228842b6df12d921","run_id":"2005"},{"commit":"a839e784139f68e94f353ac4228842b6df12d921","run_id":"2006"},{"commit":"a839e784139f68e94f353ac4228842b6df12d921","run_id":"2007"},{"commit":"a839e784139f68e94f353ac4228842b6df12d921","run_id":"2008"},{"commit":"a839e784139f68e94f353ac4228842b6df12d921","run_id":"2009"},{"commit":"a839e784139f68e94f353ac4228842b6df12d921","run_id":"2010"},{"commit":"a839e784139f68e94f353ac4228842b6df12d921","run_id":"2011"},{"commit":"a839e784139f68e94f353ac4228842b6df12d921","run_id":"2012"}],"statistic":"leave-one-out ratio: a workload median divided by the geometric mean of the other workloads medians in the same run","window":12,"workloads":{"escape_hatches":{"iterations":5,"mean_loo_ratio":3.4880762027727097,"mean_median_ns":90033327},"ijson_jcs":{"iterations":5,"mean_loo_ratio":6.645385967360134,"mean_median_ns":146102048},"required_contexts":{"iterations":5,"mean_loo_ratio":0.17998022556133478,"mean_median_ns":9758309.833333334},"root_shape":{"iterations":5,"mean_loo_ratio":0.24044680612794925,"mean_median_ns":12129016.083333334}}} diff --git a/benches/template_bench.sh b/benches/template_bench.sh index 5fb58a88..609b3e79 100755 --- a/benches/template_bench.sh +++ b/benches/template_bench.sh @@ -1,227 +1,140 @@ -#!/bin/bash +#!/usr/bin/env 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 - +# Template Benchmarks (proven-tests-and-benches JSON v1 compatible) +# +# Usage: +# benches/template_bench.sh [--json | --csv] [REPO_ROOT] +# benches/template_bench.sh [REPO_ROOT] [human | json | csv] +# +# Exit contract (proven-tests-and-benches 3-outcome convention): +# 0 = all workloads succeeded (checksum == true for every workload) +# 1 = one or more benchmarked workloads failed (a broken workload is never timed as clean) +# 2 = setup error (missing repo root or required benchmark script) 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 +OUTPUT_FORMAT="human" +REPO_ROOT="." -#============================================================================== -# 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" +while [ "$#" -gt 0 ]; do + case "$1" in + --json) OUTPUT_FORMAT="json"; shift ;; + --csv) OUTPUT_FORMAT="csv"; shift ;; + human|json|csv) OUTPUT_FORMAT="$1"; shift ;; + *) REPO_ROOT="$1"; shift ;; + esac 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 +[ -d "$REPO_ROOT" ] || { echo "template_bench: repo root '$REPO_ROOT' does not exist" >&2; exit 2; } +REPO_ROOT="$(cd "$REPO_ROOT" && pwd)" - 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 +for req in \ + "$REPO_ROOT/scripts/check-root-shape.sh" \ + "$REPO_ROOT/scripts/check-ijson-jcs.sh" \ + "$REPO_ROOT/scripts/check-required-contexts.sh" \ + "$REPO_ROOT/scripts/check-escape-hatches.sh" +do + [ -f "$req" ] || { echo "template_bench: required workload script missing: $req" >&2; exit 2; } +done -#============================================================================== -# BENCHMARK 5: Template Instantiation -#============================================================================== +# Print a message only in human output mode. +log_human() { + if [ "$OUTPUT_FORMAT" = "human" ]; then + printf '%s\n' "$*" + fi +} -log_info "Running template instantiation benchmark" +# median_of ... -> integer median on stdout +# Requires at least one integer sample; for even counts, truncate the average +# of the two middle samples toward zero. +median_of() { + local sorted count mid + mapfile -t sorted < <(printf '%s\n' "$@" | sort -n) + count="${#sorted[@]}" + mid=$(( count / 2 )) + if [ $(( count % 2 )) -eq 1 ]; then + printf '%s' "${sorted[$mid]}" + else + printf '%s' $(( (sorted[mid - 1] + sorted[mid]) / 2 )) + fi +} -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) +declare -A MEDIAN_NS +declare -A ITERS +declare -A CHECKSUM +WORKLOADS=(escape_hatches ijson_jcs required_contexts root_shape) +ANY_FAILED=0 + +# run_workload NAME ITERATIONS COMMAND... — run one warm-up and ITERATIONS timed +# samples, recording median nanoseconds, iterations, and checksum by NAME. +# Any failed invocation sets ANY_FAILED and a false checksum; sampling continues. +run_workload() { + local name="$1" iterations="$2" + shift 2 + local samples=() ok="true" i start end elapsed + + # Warm-up run + if ! "$@" >/dev/null 2>&1; then + ok="false" + ANY_FAILED=1 + fi + + for i in $(seq 1 "$iterations"); do + start="$(date +%s%N)" + if ! "$@" >/dev/null 2>&1; then + ok="false" + ANY_FAILED=1 + fi + end="$(date +%s%N)" + elapsed=$(( end - start )) + [ "$elapsed" -gt 0 ] || elapsed=1 + samples+=("$elapsed") + log_human " [$name] sample $i/$iterations: $(( elapsed / 1000000 )) ms" + done + + MEDIAN_NS["$name"]="$(median_of "${samples[@]}")" + ITERS["$name"]="$iterations" + CHECKSUM["$name"]="$ok" +} - INSTANTIATION_TIME=$(( (END - START) / 1000000 )) - results[instantiation]=$INSTANTIATION_TIME - log_pass "Template instantiation: ${INSTANTIATION_TIME}ms" -fi +log_human "Template Benchmarks (proven-bench v1)" +log_human "=====================================" -#============================================================================== -# SUMMARY -#============================================================================== +run_workload escape_hatches 5 bash "$REPO_ROOT/scripts/check-escape-hatches.sh" \ + "$REPO_ROOT/src" "$REPO_ROOT/verification" "$REPO_ROOT/.machine_readable/coaptation" +# Clear any caller-supplied IJSON_JCS binary override so the benchmark always +# measures the same deterministic JS RFC 7493/8785 workload calibrated in +# benches/baseline.json (production gates still honour IJSON_JCS on PATH). +run_workload ijson_jcs 5 env -u IJSON_JCS IJSON_JCS_FORCE_JS=1 bash "$REPO_ROOT/scripts/check-ijson-jcs.sh" --enforce "$REPO_ROOT" +run_workload required_contexts 5 bash "$REPO_ROOT/scripts/check-required-contexts.sh" "$REPO_ROOT" +run_workload root_shape 5 bash "$REPO_ROOT/scripts/check-root-shape.sh" "$REPO_ROOT" -echo "" -echo "═══════════════════════════════════════════════════════════════════════════════" -echo "BENCHMARK RESULTS" -echo "═══════════════════════════════════════════════════════════════════════════════" -echo "" +COMMIT_SHA="$(git -C "$REPO_ROOT" rev-parse HEAD 2>/dev/null || printf 'unknown')" 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 "}" + # Emit strict RFC 7493 / RFC 8785 (JCS) JSON v1 document for proven-bench tools. + printf '{"commit":"%s","results":[' "$COMMIT_SHA" + first=1 + for w in "${WORKLOADS[@]}"; do + [ "$first" -eq 1 ] || printf ',' + first=0 + printf '{"checksum":%s,"iterations":%d,"median_ns":%d,"name":"%s"}' \ + "${CHECKSUM[$w]}" "${ITERS[$w]}" "${MEDIAN_NS[$w]}" "$w" + done + printf '],"schema_version":1,"suite":"proven-bench"}\n' 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 + printf 'workload,iterations,median_ns,checksum\n' + for w in "${WORKLOADS[@]}"; do + printf '%s,%d,%d,%s\n' "$w" "${ITERS[$w]}" "${MEDIAN_NS[$w]}" "${CHECKSUM[$w]}" + 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 + log_human "" + for w in "${WORKLOADS[@]}"; do + printf ' %-20s %8d ms (median of %d, checksum=%s)\n' \ + "$w" "$(( MEDIAN_NS[$w] / 1000000 ))" "${ITERS[$w]}" "${CHECKSUM[$w]}" + done fi -echo "" -echo "Benchmark complete." -echo "" +[ "$ANY_FAILED" -eq 0 ] || exit 1 +exit 0 diff --git a/build/channels.scm b/build/channels.scm new file mode 100644 index 00000000..54ac61a2 --- /dev/null +++ b/build/channels.scm @@ -0,0 +1,18 @@ +;; SPDX-License-Identifier: MPL-2.0 +;; channels.scm — the Guix revision this repository's guix.scm and manifest.scm +;; were verified against. Reproduce that exact Guix with: +;; +;; guix time-machine -C channels.scm -- shell -m manifest.scm +;; +;; Refresh it (after re-verifying) with: just toolchain-refresh +;; Canon pin, verified 2026-09-30 (docker.io/metacall/guix, guix describe). +(list (channel + (name 'guix) + (url "https://codeberg.org/guix/guix.git") + (branch "master") + (commit "ae77aeb9543de2661d739104bc4d3803d8c6f38b") + (introduction + (make-channel-introduction + "9edb3f66fd807b096b48283debdcddccfea34bad" + (openpgp-fingerprint + "BBB0 2DDF 2CEA F6A8 0D1D E643 A2A0 6DF2 A33A 54FA"))))) diff --git a/build/container/Containerfile b/build/container/Containerfile deleted file mode 100644 index 6dbff802..00000000 --- a/build/container/Containerfile +++ /dev/null @@ -1,152 +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. -# -# This is the Tier-A artifact: a plain OCI image, buildable by ANY -# OCI-compliant engine — podman (recommended), nerdctl, or docker. -# It carries no hard dependency on the stapeln tier; the cerro-torre / -# svalinn files under build/container/stapeln/ are referenced only as labels. -# -# Build (engine-agnostic — substitute podman | nerdctl | docker): -# podman build -t {{SERVICE_NAME}}:latest -f build/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 -# -# Via the Justfile (auto-detects engine, prefers cerro-torre when present): -# just container-build - -# ============================================================================ -# 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}} -# -# Base image: `:latest` is right for a template scaffold (Chainguard rebuilds -# Wolfi daily). For PRODUCTION builds, pin by digest for reproducibility/supply- -# chain integrity, e.g.: -# FROM cgr.dev/chainguard/wolfi-base:latest@sha256: AS builder -# (cerro-torre's .ctp signing in build/container/stapeln/ records the resolved digest.) -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="build/container/stapeln/manifest.toml" \ - dev.cerrotorre.gatekeeper="build/container/stapeln/.gatekeeper.yaml" \ - dev.stapeln.compose="build/container/stapeln/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 build/container/entrypoint.sh /app/entrypoint.sh -RUN chmod +x /app/entrypoint.sh - -# OPTIONAL (Tier C — stapeln). A pure OCI image does NOT need these baked in: -# svalinn reads .gatekeeper.yaml from a mounted volume (see stapeln/compose.toml), -# and cerro-torre reads manifest.toml at pack time. Uncomment only if you want -# the policy/manifest embedded in the image itself. -# COPY build/container/stapeln/.gatekeeper.yaml /etc/svalinn/gatekeeper.yaml -# COPY build/container/stapeln/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/build/container/README.adoc b/build/container/README.adoc index 3808b62f..a6df883e 100644 --- a/build/container/README.adoc +++ b/build/container/README.adoc @@ -7,6 +7,26 @@ == Overview +[TIP] +==== +*This module ships no `Containerfile`.* It used to ship one, and that file had +two `FROM …:latest` lines and a body of TODO comments: it could not build, and +it failed `container-images-pinned` in every repository minted from this +template — including the ones that publish no image at all. + +A repository that publishes an image adds the file here, pinned: + +[source,bash] +---- +scripts/pin-container-digests.sh --root . --base --runtime \ + build/container/Containerfile +---- + +`scripts/check-container-pins.sh` fails the build until every `FROM` in it +carries an `@sha256:` digest, and `just container-build` says the same thing +rather than building an image from two moving tags. +==== + Containerisation in this template is organised in *three tiers*, from the most portable to the most sovereign. You can use only the tier you need and ignore — or delete — the rest. @@ -16,7 +36,7 @@ or delete — the rest. | Tier | What | Why | *A — OCI standard* -| `Containerfile`, `.containerignore` +| `Containerfile` (you add it — see above), `.containerignore` | A plain, multi-stage OCI image on https://www.chainguard.dev/[Chainguard] Wolfi. Builds with any OCI engine. No dependency on tiers B or C. @@ -102,9 +122,11 @@ The container engine is *auto-detected* (`podman`, then `nerdctl`, then | *cerro-torre* build → pack → sign (Ed25519) → verify → push pipeline. Engine-agnostic; degrades gracefully when cerro-torre tools are absent. -| `deploy.k9.ncl` -| *k9-svc* deployment component at Hunt trust level: full pedigree (L1–L5), - dev/staging/prod configs, rolling deployment strategy. +| `deploy.k9.ncl.in` +| *k9-svc* deployment component at the Hunt leash (K9 contract v1.0.0): + pedigree with capability grant, side effects and signature block; + dev/staging/prod configs, rolling deployment strategy. Rendered to + `deploy.k9.ncl` by `just container-init`. |=== == The stapeln ecosystem @@ -174,14 +196,26 @@ just container-push # push the signed bundle cd build/container/stapeln && selur-compose up --detach ---- -k9-svc managed deployment: +k9-svc managed deployment. The deployment component ships as the template +`build/container/stapeln/deploy.k9.ncl.in`, in the K9 contract v1.0.0 shape. +`just repo-init` fills its `PROJECT_NAME` and `VERSION` placeholders and +`just container-init` fills `SERVICE_NAME`, `PORT` and `REGISTRY`. Once no +placeholder token is left, `just container-init` renders it to +`build/container/stapeln/deploy.k9.ncl`; until then it keeps the `.in` file +and names the tokens still missing. The rendered file is a K9 component, so +the K9 lane validates it like any other: [source,bash] ---- -nickel typecheck build/container/stapeln/deploy.k9.ncl +k9-validate.sh --strict --layer L2 build/container/stapeln/deploy.k9.ncl k9-svc deploy build/container/stapeln/deploy.k9.ncl --env production ---- +It is a `'Hunt` component, so it carries a signature block. That block is a +claim until you sign the rendered file: the validator reports it +`'Present_Unverified` (K9-C001), and Hunt stays unauthorised until a verifier +accepts the signature. + == Continuous integration A `container build` workflow ships in `.github/workflows/container-build.yml`. @@ -202,14 +236,14 @@ To enable it, set a repository (or organisation) variable: | `CONTAINER_RUNNER` | Optional JSON array of runner labels. Defaults to `["self-hosted","owned","container"]` — owned compute, so **no metered - GitHub Actions minutes**. Set e.g. `["ubuntu-latest"]` to use GitHub-hosted + GitHub Actions minutes**. Set e.g. `["ubuntu-24.04"]` to use GitHub-hosted runners instead. |=== [source,bash] ---- gh variable set CONTAINER_CI --body true -# optional: gh variable set CONTAINER_RUNNER --body '["ubuntu-latest"]' +# optional: gh variable set CONTAINER_RUNNER --body '["ubuntu-24.04"]' ---- The owned runner is expected to have `just` and a container engine installed; diff --git a/build/container/compose.example.yaml b/build/container/compose.example.yaml index cbd43aad..6e84892c 100644 --- a/build/container/compose.example.yaml +++ b/build/container/compose.example.yaml @@ -12,97 +12,142 @@ # # For the sovereign selur path see build/container/stapeln/compose.example.toml. -services: - # Rust API — primary HTTP/gRPC backend. - rust-api: - build: - context: .. - dockerfile: build/container/Containerfile - image: ghcr.io/hyperpolymath/myproject-api:latest - ports: - - "8080:8080" - environment: - RUST_LOG: "info" - APP_HOST: "[::]" - APP_PORT: "8080" - APP_LOG_FORMAT: "json" - APP_DATA_DIR: "/data" - volumes: - - api-data:/data - restart: unless-stopped - healthcheck: - test: ["CMD", "curl", "-sf", "http://localhost:8080/health"] - interval: 30s - timeout: 5s - retries: 3 - - # Elixir worker — background processing, talks to the API over the network. - elixir-worker: - image: ghcr.io/hyperpolymath/myproject-worker:latest - ports: - - "4000:4000" - environment: - API_URL: "http://rust-api:8080/api/v1" - MIX_ENV: "prod" - APP_LOG_FORMAT: "json" - POOL_SIZE: "10" - depends_on: - rust-api: - condition: service_healthy - restart: unless-stopped - healthcheck: - test: ["CMD", "curl", "-sf", "http://localhost:4000/health"] - interval: 30s - timeout: 5s - retries: 3 - - # rokur — secrets gate. Refuses to come up unless required secrets are present. - rokur: - image: ghcr.io/hyperpolymath/rokur:latest - ports: - - "8081:8081" - environment: - ROKUR_BACKEND: "http://rust-api:8080" - ROKUR_LISTEN: "[::]:8081" - ROKUR_REQUIRED_SECRETS: "DATABASE_URL,JWT_SIGNING_KEY" - ROKUR_AUDIT_LOG: "/var/log/rokur/audit.jsonl" - ROKUR_LOG_FORMAT: "json" - volumes: - - rokur-audit:/var/log/rokur - depends_on: - rust-api: - condition: service_healthy - restart: unless-stopped - healthcheck: - test: ["CMD", "curl", "-sf", "http://localhost:8081/health"] - interval: 30s - timeout: 5s - retries: 3 - - # svalinn — edge gateway. TLS, auth, rate limiting, audit. The only - # externally exposed service. - svalinn: - image: ghcr.io/hyperpolymath/svalinn:latest - ports: - - "443:443" - - "80:80" - environment: - SVALINN_BACKEND: "http://rokur:8081" - SVALINN_WORKER_BACKEND: "http://elixir-worker:4000" - SVALINN_POLICY_FILE: "/etc/svalinn/gatekeeper.yaml" - SVALINN_TLS_AUTO: "true" - volumes: - - ./stapeln/.gatekeeper.yaml:/etc/svalinn/gatekeeper.yaml:ro - depends_on: - - rokur - - elixir-worker - restart: unless-stopped - healthcheck: - test: ["CMD", "curl", "-sf", "http://localhost:80/health"] - interval: 30s - timeout: 5s - retries: 3 - -volumes: - api-data: - rokur-audit: +{ + services: { + # Rust API — primary HTTP/gRPC backend. + rust-api: { + build: { + context: "..", + dockerfile: "build/container/Containerfile", + }, + image: "ghcr.io/hyperpolymath/myproject-api:latest", + ports: [ + "8080:8080", + ], + environment: { + RUST_LOG: "info", + APP_HOST: "[::]", + APP_PORT: "8080", + APP_LOG_FORMAT: "json", + APP_DATA_DIR: "/data", + }, + volumes: [ + "api-data:/data", + ], + restart: "unless-stopped", + healthcheck: { + test: [ + "CMD", + "curl", + "-sf", + "http://localhost:8080/health", + ], + interval: "30s", + timeout: "5s", + retries: 3, + }, + }, + # Elixir worker — background processing, talks to the API over the network. + elixir-worker: { + image: "ghcr.io/hyperpolymath/myproject-worker:latest", + ports: [ + "4000:4000", + ], + environment: { + API_URL: "http://rust-api:8080/api/v1", + MIX_ENV: "prod", + APP_LOG_FORMAT: "json", + POOL_SIZE: "10", + }, + depends_on: { + rust-api: { + condition: "service_healthy", + }, + }, + restart: "unless-stopped", + healthcheck: { + test: [ + "CMD", + "curl", + "-sf", + "http://localhost:4000/health", + ], + interval: "30s", + timeout: "5s", + retries: 3, + }, + }, + # rokur — secrets gate. Refuses to come up unless required secrets are present. + rokur: { + image: "ghcr.io/hyperpolymath/rokur:latest", + ports: [ + "8081:8081", + ], + environment: { + ROKUR_BACKEND: "http://rust-api:8080", + ROKUR_LISTEN: "[::]:8081", + ROKUR_REQUIRED_SECRETS: "DATABASE_URL,JWT_SIGNING_KEY", + ROKUR_AUDIT_LOG: "/var/log/rokur/audit.jsonl", + ROKUR_LOG_FORMAT: "json", + }, + volumes: [ + "rokur-audit:/var/log/rokur", + ], + depends_on: { + rust-api: { + condition: "service_healthy", + }, + }, + restart: "unless-stopped", + healthcheck: { + test: [ + "CMD", + "curl", + "-sf", + "http://localhost:8081/health", + ], + interval: "30s", + timeout: "5s", + retries: 3, + }, + }, + # svalinn — edge gateway. TLS, auth, rate limiting, audit. The only + # externally exposed service. + svalinn: { + image: "ghcr.io/hyperpolymath/svalinn:latest", + ports: [ + "443:443", + "80:80", + ], + environment: { + SVALINN_BACKEND: "http://rokur:8081", + SVALINN_WORKER_BACKEND: "http://elixir-worker:4000", + SVALINN_POLICY_FILE: "/etc/svalinn/gatekeeper.yaml", + SVALINN_TLS_AUTO: "true", + }, + volumes: [ + "./stapeln/.gatekeeper.yaml:/etc/svalinn/gatekeeper.yaml:ro", + ], + depends_on: [ + "rokur", + "elixir-worker", + ], + restart: "unless-stopped", + healthcheck: { + test: [ + "CMD", + "curl", + "-sf", + "http://localhost:80/health", + ], + interval: "30s", + timeout: "5s", + retries: 3, + }, + }, + }, + volumes: { + api-data: null, + rokur-audit: null, + }, +} diff --git a/build/container/compose.yaml b/build/container/compose.yaml index 4b5087f2..cd30b335 100644 --- a/build/container/compose.yaml +++ b/build/container/compose.yaml @@ -16,84 +16,119 @@ # # See https://compose-spec.io for the full specification. -services: - # ────────────────────────────────────────────────────────────────────── - # Primary application service - # ────────────────────────────────────────────────────────────────────── - "{{SERVICE_NAME}}": - build: - context: .. - dockerfile: build/container/Containerfile - image: "{{REGISTRY}}/{{SERVICE_NAME}}:latest" - ports: - - "{{PORT}}:{{PORT}}" - environment: - APP_HOST: "[::]" - APP_PORT: "{{PORT}}" - APP_LOG_FORMAT: "json" - APP_DATA_DIR: "/data" - volumes: - - "{{SERVICE_NAME}}-data:/data" - restart: unless-stopped - healthcheck: - test: ["CMD", "curl", "-sf", "http://localhost:{{PORT}}/health"] - interval: 30s - timeout: 5s - retries: 3 - start_period: 10s - - # ────────────────────────────────────────────────────────────────────── - # rokur — secrets-management gate (stapeln). Fronts the app and refuses - # to start the stack unless required secrets are present. on Wolfi. - # Remove this service if you do not use secret gating. - # ────────────────────────────────────────────────────────────────────── - rokur: - image: ghcr.io/hyperpolymath/rokur:latest - environment: - ROKUR_BACKEND: "http://{{SERVICE_NAME}}:{{PORT}}" - ROKUR_LISTEN: "[::]:8081" - ROKUR_REQUIRED_SECRETS: "" # comma-separated env names that MUST be set - ROKUR_AUDIT_LOG: "/var/log/rokur/audit.jsonl" - ROKUR_LOG_FORMAT: "json" - ports: - - "8081:8081" - volumes: - - rokur-audit:/var/log/rokur - depends_on: - "{{SERVICE_NAME}}": - condition: service_healthy - restart: unless-stopped - healthcheck: - test: ["CMD", "curl", "-sf", "http://localhost:8081/health"] - interval: 30s - timeout: 5s - retries: 3 - - # ────────────────────────────────────────────────────────────────────── - # svalinn — edge gateway (stapeln). TLS termination, auth, rate limiting. - # Reads the gatekeeper policy from build/container/stapeln/.gatekeeper.yaml. - # Remove this service for a bare app with no gateway. - # ────────────────────────────────────────────────────────────────────── - svalinn: - image: ghcr.io/hyperpolymath/svalinn:latest - ports: - - "443:443" - - "80:80" - environment: - SVALINN_BACKEND: "http://rokur:8081" - SVALINN_POLICY_FILE: "/etc/svalinn/gatekeeper.yaml" - SVALINN_TLS_AUTO: "true" - volumes: - - ./stapeln/.gatekeeper.yaml:/etc/svalinn/gatekeeper.yaml:ro - depends_on: - - rokur - restart: unless-stopped - healthcheck: - test: ["CMD", "curl", "-sf", "http://localhost:80/health"] - interval: 30s - timeout: 5s - retries: 3 - -volumes: - "{{SERVICE_NAME}}-data": - rokur-audit: +{ + services: { + # ────────────────────────────────────────────────────────────────────── + # Primary application service + # ────────────────────────────────────────────────────────────────────── + "{{SERVICE_NAME}}": { + build: { + context: "..", + dockerfile: "build/container/Containerfile", + }, + image: "{{REGISTRY}}/{{SERVICE_NAME}}:latest", + ports: [ + "{{PORT}}:{{PORT}}", + ], + environment: { + APP_HOST: "[::]", + APP_PORT: "{{PORT}}", + APP_LOG_FORMAT: "json", + APP_DATA_DIR: "/data", + }, + volumes: [ + "{{SERVICE_NAME}}-data:/data", + ], + restart: "unless-stopped", + healthcheck: { + test: [ + "CMD", + "curl", + "-sf", + "http://localhost:{{PORT}}/health", + ], + interval: "30s", + timeout: "5s", + retries: 3, + start_period: "10s", + }, + }, + # ────────────────────────────────────────────────────────────────────── + # rokur — secrets-management gate (stapeln). Fronts the app and refuses + # to start the stack unless required secrets are present. on Wolfi. + # Remove this service if you do not use secret gating. + # ────────────────────────────────────────────────────────────────────── + rokur: { + image: "ghcr.io/hyperpolymath/rokur:latest", + environment: { + ROKUR_BACKEND: "http://{{SERVICE_NAME}}:{{PORT}}", + ROKUR_LISTEN: "[::]:8081", + ROKUR_REQUIRED_SECRETS: "", # comma-separated env names that MUST be set + ROKUR_AUDIT_LOG: "/var/log/rokur/audit.jsonl", + ROKUR_LOG_FORMAT: "json", + }, + ports: [ + "8081:8081", + ], + volumes: [ + "rokur-audit:/var/log/rokur", + ], + depends_on: { + "{{SERVICE_NAME}}": { + condition: "service_healthy", + }, + }, + restart: "unless-stopped", + healthcheck: { + test: [ + "CMD", + "curl", + "-sf", + "http://localhost:8081/health", + ], + interval: "30s", + timeout: "5s", + retries: 3, + }, + }, + # ────────────────────────────────────────────────────────────────────── + # svalinn — edge gateway (stapeln). TLS termination, auth, rate limiting. + # Reads the gatekeeper policy from build/container/stapeln/.gatekeeper.yaml. + # Remove this service for a bare app with no gateway. + # ────────────────────────────────────────────────────────────────────── + svalinn: { + image: "ghcr.io/hyperpolymath/svalinn:latest", + ports: [ + "443:443", + "80:80", + ], + environment: { + SVALINN_BACKEND: "http://rokur:8081", + SVALINN_POLICY_FILE: "/etc/svalinn/gatekeeper.yaml", + SVALINN_TLS_AUTO: "true", + }, + volumes: [ + "./stapeln/.gatekeeper.yaml:/etc/svalinn/gatekeeper.yaml:ro", + ], + depends_on: [ + "rokur", + ], + restart: "unless-stopped", + healthcheck: { + test: [ + "CMD", + "curl", + "-sf", + "http://localhost:80/health", + ], + interval: "30s", + timeout: "5s", + retries: 3, + }, + }, + }, + volumes: { + "{{SERVICE_NAME}}-data": null, + rokur-audit: null, + }, +} diff --git a/build/container/stapeln/.gatekeeper.yaml b/build/container/stapeln/.gatekeeper.yaml index 4aac671d..46afaa1a 100644 --- a/build/container/stapeln/.gatekeeper.yaml +++ b/build/container/stapeln/.gatekeeper.yaml @@ -9,114 +9,149 @@ # # 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/*" +{ + 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/build/container/stapeln/deploy.k9.ncl b/build/container/stapeln/deploy.k9.ncl deleted file mode 100644 index 72827380..00000000 --- a/build/container/stapeln/deploy.k9.ncl +++ /dev/null @@ -1,170 +0,0 @@ -K9! -# 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 build/container/deploy.k9.ncl -# k9-svc validate build/container/deploy.k9.ncl -# k9-svc deploy build/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, - # Named field the k9 validators grep for (leash/security_level); - # value mirrors trust_level — this component is documented Hunt-level. - security_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 build/container/stapeln && selur-compose verify || podman compose --file ../compose.yaml 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 build/container/stapeln -./ct-build.sh -selur-compose up --detach || podman compose --file ../compose.yaml up --detach -echo "K9: Deployment to $ENV complete." -"%, - - # Rollback script - rollback = m%" -#!/bin/sh -set -eu -echo "K9: Rolling back {{SERVICE_NAME}} deployment..." -cd build/container/stapeln -selur-compose down || podman compose --file ../compose.yaml down -echo "K9: Rollback complete." -"%, -} in - -# Export the component -{ - pedigree = component_pedigree & { name = "{{SERVICE_NAME}}-deploy" }, - 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 build/container/deploy.k9.ncl && k9-svc deploy build/container/deploy.k9.ncl -"%, -} diff --git a/build/container/stapeln/deploy.k9.ncl.in b/build/container/stapeln/deploy.k9.ncl.in new file mode 100644 index 00000000..4a25720f --- /dev/null +++ b/build/container/stapeln/deploy.k9.ncl.in @@ -0,0 +1,189 @@ +K9! +# SPDX-License-Identifier: MPL-2.0 +# deploy.k9.ncl — {{PROJECT_NAME}} deployment component (Hunt level) +# +# k9-svc deployment component, K9 contract v1.0.0 (D173). Shipped as +# deploy.k9.ncl.in because a template is not a component: `just repo-init` +# fills PROJECT_NAME and VERSION, `just container-init` fills SERVICE_NAME, +# PORT and REGISTRY, and once no brace token is left `just container-init` +# renders it to build/container/stapeln/deploy.k9.ncl. +# +# WARNING: this component executes shell commands. It is 'Hunt, so a host +# runs it only with all five Hunt preconditions met, a verified signature +# among them. The signature block below is a claim until the owner signs the +# rendered file; until then the validator reports it 'Present_Unverified +# (K9-C001) and Hunt stays unauthorised. +# +# Usage (on the rendered file): +# k9-validate.sh --strict --layer L2 build/container/stapeln/deploy.k9.ncl +# k9-svc validate build/container/stapeln/deploy.k9.ncl +# k9-svc deploy build/container/stapeln/deploy.k9.ncl --env production + +{ + pedigree = { + schema_version = "1.0.0", + component_type = "deployment", + + metadata = { + name = "{{SERVICE_NAME}}-deploy", + version = "{{VERSION}}", + description = "{{PROJECT_NAME}} deployment component (Hunt level)", + }, + + # Target environment (extension field; contract §5.5). + target = { + os = 'Linux, + is_edge = false, + requires_podman = true, + min_memory_mb = 256, + }, + + security = { + leash = 'Hunt, + trust_level = "controlled-execution", + allow_network = true, + allow_filesystem_write = true, + allow_subprocess = true, + signature_required = true, + # Default-deny: every flag above is paid for here (contract §8.4), plus + # the deploy and rollback actions the scripts below perform. + capabilities = [ + "net.fetch", + "fs.write", + "process.spawn", + "container.run", + "deploy.apply", + "rollback.apply", + ], + }, + + warnings = [ + "This is a Hunt-level component: it executes shell commands and changes the system.", + "Review the deployment scripts before running it.", + "A signature block being present is not a signature being verified.", + "Authorise Hunt explicitly: k9-svc authorize build/container/stapeln/deploy.k9.ncl", + ], + + side_effects = [ + "spawns build/container/stapeln/ct-build.sh, which builds the image and packs and signs a .ctp bundle beside it", + "pulls and pushes {{REGISTRY}}/{{SERVICE_NAME}} images", + "starts, updates and stops the {{SERVICE_NAME}} stack with selur-compose, else podman compose over build/container/compose.yaml", + "publishes the service on port {{PORT}}", + ], + + # Ed25519, presence only (K9-S009). The signing step adds payload_hash + # and signature to the rendered file; verification is K9-C001 (L3). + signature = { + algorithm = "Ed25519", + key_id = "primary", + }, + }, + + # Deployment configuration + 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, + }, + }, + + # Deployment scripts (executed at Hunt level) + scripts = { + # Pre-deployment validation + pre_deploy = m%" +#!/bin/sh +set -eu +echo "K9: Pre-deployment validation for {{SERVICE_NAME}}..." +cd build/container/stapeln +if command -v selur-compose >/dev/null 2>&1; then + selur-compose verify +else + podman compose --file ../compose.yaml config +fi +echo "K9: Validation passed." +"%, + + # Deployment script + deploy = m%" +#!/bin/sh +set -eu +ENV="${1:-dev}" +echo "K9: Deploying {{SERVICE_NAME}} to $ENV environment..." +cd build/container/stapeln +./ct-build.sh +if command -v selur-compose >/dev/null 2>&1; then + selur-compose up --detach +else + podman compose --file ../compose.yaml up --detach +fi +echo "K9: Deployment to $ENV complete." +"%, + + # Rollback script + rollback = m%" +#!/bin/sh +set -eu +echo "K9: Rolling back {{SERVICE_NAME}} deployment..." +cd build/container/stapeln +if command -v selur-compose >/dev/null 2>&1; then + selur-compose down +else + podman compose --file ../compose.yaml down +fi +echo "K9: Rollback complete." +"%, + }, + + # Just recipes: an execution surface, which is why the leash is 'Hunt + # (K9-S011). + recipes = { + install = { + description = "Build the container image", + commands = ["just container-build"], + }, + validate = { + description = "Verify the compose configuration", + commands = ["just container-verify"], + }, + deploy = { + description = "Start the container stack", + commands = ["just container-up"], + }, + migrate = { + description = "Rebuild the image and restart the stack", + commands = ["just container-build", "just container-up"], + }, + }, +} diff --git a/build/guix.scm b/build/guix.scm index 5a769d67..adbe8c31 100755 --- a/build/guix.scm +++ b/build/guix.scm @@ -1,20 +1,46 @@ ;; SPDX-License-Identifier: MPL-2.0 -;; Guix development environment template. -;; Usage: guix shell -D -f build/guix.scm +;; SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) +;; +;; guix.scm — rsr-template-repo as a Guix package. +;; +;; guix build -f build/guix.scm # installs the source tree to share/rsr-template-repo +;; guix shell -D -f build/guix.scm # the full development toolchain +;; +;; This is a SOURCE package, and says so: a hermetic compiled build needs this +;; repository's idris2 and zig dependencies packaged in Guix, which they are not +;; (Guix builds offline). The toolchain below is real — `guix shell -D -f build/guix.scm` +;; then `just setup` gives a working environment. See docs/SETUP.adoc §Guix. +(use-modules (guix packages) (guix gexp) + (guix build-system copy) + (gnu packages) + ((guix licenses) #:prefix license:)) -(use-modules (guix packages) - (guix build-system gnu) - (guix licenses) - (gnu packages base) - (gnu packages bash)) +;; The repository root: this file sits at the root or in build/ (PROVISIONING-STANDARD §1). +(define %source-dir + (let ((d (dirname (current-filename)))) + (if (string=? (basename d) "build") (dirname d) d))) +;; A spec may name an output ("rust:cargo"); plain specification->package cannot. +(define (spec->input spec) + (call-with-values (lambda () (specification->package+output spec)) + (lambda (pkg out) (if (string=? out "out") pkg (list pkg out))))) + +(define %ignored + '(".git" "target" ".eval" "node_modules" "_build" "deps" "zig-out" ".zig-cache" "dist-newstyle")) (package (name "rsr-template-repo") (version "0.1.0") - (source #f) - (build-system gnu-build-system) - (inputs (list coreutils bash)) - (synopsis "rsr-template-repo") - (description "rsr-template-repo — part of the hyperpolymath ecosystem.") + (source (local-file %source-dir "rsr-template-repo-checkout" + #:recursive? #t + #:select? (lambda (file stat) + (not (member (basename file) %ignored))))) + (build-system copy-build-system) + (arguments (list #:install-plan #~'(("." "share/rsr-template-repo/")))) + (native-inputs (map spec->input (list "git" "bash" "coreutils" "nss-certs" "just" "mise" + "shellcheck" "chez-scheme" "gmp" "gcc-toolchain" "zig"))) (home-page "https://github.com/hyperpolymath/rsr-template-repo") - (license (@ (guix licenses) mpl2.0))) + (synopsis "Rhodium Standard Repository template") + (description "The estate's repository template: the RSR layout, an Idris2 ABI +seam with a Zig FFI, CI gates, and the provisioning set (launcher, Justfile, +mise, Guix, setup and AI-assisted installation guides).") + (license license:mpl2.0)) diff --git a/build/just/assess.just b/build/just/assess.just index 3c990317..a6a663bd 100644 --- a/build/just/assess.just +++ b/build/just/assess.just @@ -43,7 +43,23 @@ self-assess: echo "── ESSENTIAL (removing breaks Rhodium Standard) ──────────" echo "" - for f in LICENSE .editorconfig .gitignore; do + # The licence may be LICENSE in any usual spelling (this template ships + # LICENSE.adoc) or a REUSE LICENSES/ directory holding a non-empty + # . licence text (dotfiles and READMEs do not count). + lic="" + for cand in LICENSE LICENSE.txt LICENSE.md LICENSE.adoc; do + [ -f "$cand" ] && { lic="$cand"; break; } + done + if [ -z "$lic" ] && [ -n "$(find LICENSES -maxdepth 1 -type f -size +0c -name '*.*' ! -name '.*' ! -iname 'README*' 2>/dev/null | head -n 1)" ]; then + lic="LICENSES/" + fi + if [ -n "$lic" ]; then + echo " ✓ $lic — KEEP (RSR required)" + else + echo " ✗ LICENSE — MISSING (RSR violation!)" + fi + + for f in .editorconfig .gitignore; do if [ -f "$f" ]; then echo " ✓ $f — KEEP (RSR required)" else @@ -101,15 +117,17 @@ self-assess: 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/') + # The Groove manifest is the repo deed's (integrations (groove …)) clause. + GROOVE_DEED=$(bash scripts/deed-field.sh --find . 2>/dev/null || true) + if $HAS_API && [ -n "$GROOVE_DEED" ] && bash scripts/deed-field.sh --has "$GROOVE_DEED" integrations/groove; then + PORT=$(bash scripts/deed-field.sh "$GROOVE_DEED" integrations/groove port 2>/dev/null || true) if [ "$PORT" = "0" ]; then - echo " ⚠ groove.a2ml — Port not assigned. Run 'just groove-setup'." + echo " ⚠ (integrations (groove)) — Port not assigned. Run 'just groove-setup'." else - echo " ✓ groove.a2ml — KEEP (Groove discovery on port $PORT)" + echo " ✓ (integrations (groove)) — 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 " ✗ (integrations (groove)) — MISSING. Your project has an API but no Groove clause in its deed." echo " → Run 'just groove-setup' to enable snap-on/snap-off discovery." fi @@ -244,13 +262,37 @@ verify: ERRORS=$((ERRORS + 1)) } + # The licence: a root licence file in any of the usual spellings (this + # template ships LICENSE.adoc), or a REUSE LICENSES/ directory holding at + # least one licence text: a non-empty . file, per the REUSE + # spec (dotfiles and READMEs do not count). + check_licence() { + local cand + for cand in LICENSE LICENSE.txt LICENSE.md LICENSE.adoc; do + if [ -f "$cand" ]; then + echo " OK: $cand" + return 0 + fi + done + if [ -n "$(find LICENSES -maxdepth 1 -type f -size +0c -name '*.*' ! -name '.*' ! -iname 'README*' 2>/dev/null | head -n 1)" ]; then + echo " OK: LICENSES/ (REUSE)" + return 0 + fi + echo " FAIL: LICENSE (or LICENSE.adoc, or REUSE LICENSES/) missing" + ERRORS=$((ERRORS + 1)) + } + check_community_file "SECURITY" - check_file "LICENSE" + check_licence check_community_file "CONTRIBUTING" check_either "README.adoc" "README.md" - check_file ".machine_readable/descriptiles/STATE.a2ml" - check_file ".machine_readable/descriptiles/META.a2ml" - check_file ".machine_readable/descriptiles/ECOSYSTEM.a2ml" + # Identity, state and ecosystem live in the repo deed (rsr-template-repo#209). + if DEED=$(bash scripts/deed-field.sh --find . 2>/dev/null) && bash scripts/deed-field.sh --has "$DEED" status; then + echo " OK: $DEED (status, meta, ecosystem)" + else + echo " FAIL: repo deed (*_chora.deed) with a (status …) clause missing" + ERRORS=$((ERRORS + 1)) + fi check_either "CHANGELOG.md" "CHANGELOG.adoc" # Check at least 1 workflow exists diff --git a/build/just/container.just b/build/just/container.just index a906c60d..900bcc1c 100644 --- a/build/just/container.just +++ b/build/just/container.just @@ -89,17 +89,49 @@ container-init: -e "s|${LB}REGISTRY${RB}|${REGISTRY}|g" ) + # Return success when $1 is classified as text, using a byte-content probe + # (which accepts empty files) when the file command is unavailable. + is_text_file() { + if command -v file >/dev/null 2>&1; then + file --brief "$1" | grep -qi 'text\|ascii\|utf' + else + [ ! -s "$1" ] || LC_ALL=C grep -Iq . "$1" + fi + } + # Recurses into build/container/stapeln/ as well. - find build/container/ -type f | while read -r file; do - if file --brief "$file" | grep -qi 'text\|ascii\|utf'; then + find build/container/ -type f | while IFS= read -r file; do + if is_text_file "$file"; then sed -i "${SED_ARGS[@]}" "$file" fi done + # The k9-svc deploy component ships as a template (deploy.k9.ncl.in): a + # file with brace tokens is not a K9 component. Render it once nothing is + # left to fill (repo-init fills PROJECT_NAME and VERSION), so the K9 lane + # validates the real thing. The bracket spellings keep just from reading + # the token pattern as an interpolation. + DEPLOY_IN="build/container/stapeln/deploy.k9.ncl.in" + DEPLOY_OUT="${DEPLOY_IN%.in}" + if [ -f "$DEPLOY_IN" ]; then + LEFT=$(grep -oE '[{][{][A-Za-z_]+[}][}]' "$DEPLOY_IN" | sort -u | tr '\n' ' ' || true) + if [ -n "$LEFT" ]; then + echo "Kept $DEPLOY_IN: unfilled tokens ${LEFT}remain." + echo " Run 'just repo-init', then 'just container-init' again to render it." + elif [ -e "$DEPLOY_OUT" ]; then + echo "Kept $DEPLOY_IN: $DEPLOY_OUT already exists, so it was not overwritten." + else + mv "$DEPLOY_IN" "$DEPLOY_OUT" + echo "Rendered $DEPLOY_OUT (K9 component, contract v1.0.0)." + fi + fi + echo "Container templates initialised." echo "" echo "Next steps:" - echo " 1. Edit build/container/Containerfile — add your build commands (Tier A)" + echo " 1. Add build/container/Containerfile — Tier A; pin every FROM:" + echo " scripts/pin-container-digests.sh --root . build/container/Containerfile" + echo " (the template ships none: it shipped an unpinned, non-building one until 2026-10-30)" echo " 2. Edit build/container/entrypoint.sh — set your application binary" echo " 3. Review build/container/compose.yaml — portable stack (Tier B)" echo " 4. Review build/container/stapeln/ — sovereign stack (Tier C)" @@ -117,7 +149,10 @@ container-build *args: elif [ -f "Containerfile" ]; then "$ENGINE" build -t {{project}}:latest -f Containerfile . else - echo "No Containerfile found in build/container/ or project root" + echo "No Containerfile found in build/container/ or project root." + echo "This template ships none — the one it used to ship was unpinned and" + echo "built nothing. Add one, pin it, and the estate gate will accept it:" + echo " scripts/pin-container-digests.sh --root . build/container/Containerfile" exit 1 fi diff --git a/build/just/groove.just b/build/just/groove.just index d4cb734b..2b2d7ae5 100644 --- a/build/just/groove.just +++ b/build/just/groove.just @@ -4,18 +4,20 @@ # 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. +# Recipes here configure and validate the Groove protocol manifest — the +# (integrations (groove …)) clause of the repo deed: port assignment, API +# surface flags (REST/gRPC/GraphQL/WebSocket/SSE), and template-placeholder +# hygiene. Every write goes through scripts/deed-clause.sh, one clause at a +# time. The manifest 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 repo-init' first." + DEED="$(bash scripts/deed-field.sh --find .)" || { echo "Error: no single *_chora.deed here. Run 'just repo-init' first."; exit 1; } + MANIFEST="$DEED (integrations (groove))" + if ! bash scripts/deed-field.sh --has "$DEED" integrations/groove; then + echo "Error: $DEED has no (integrations (groove)) clause." exit 1 fi @@ -28,7 +30,7 @@ groove-setup: echo "" read -rp "Primary port for this service: " PORT - [ -z "$PORT" ] && echo "Error: port required" && exit 1 + [[ "$PORT" =~ ^[1-9][0-9]{0,4}$ ]] && [ "$PORT" -le 65535 ] || { echo "Error: port must be an integer 1-65535"; exit 1; } echo "" echo "Which API surfaces does this project expose?" @@ -38,14 +40,20 @@ groove-setup: 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" + bash scripts/deed-clause.sh set "$DEED" integrations/groove port "$PORT" - # 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" + # surface NAME ANSWER DEFAULT — write :enabled for one API surface from a + # y/n answer, DEFAULT (y or n) applying to an empty answer. + surface() { + local a="${2:-$3}" v='#f' + [[ "${a,,}" == y* ]] && v='#t' + bash scripts/deed-clause.sh set "$DEED" "integrations/groove/api-surfaces/$1" enabled "$v" + } + surface rest "$REST" y + surface grpc "$GRPC" n + surface graphql "$GRAPHQL" n + surface websocket "$WS" n + surface sse "$SSE" n echo "" echo "Groove manifest updated: $MANIFEST" @@ -59,7 +67,7 @@ verify-template: FOUND=0 # Check for double-brace placeholder patterns - HITS=$(grep -rn '{{'{{'}}[A-Z_]*{{'}}'}}' --include="*.adoc" --include="*.md" --include="*.a2ml" \ + HITS=$(grep -rn '{{'{{'}}[A-Z_]*{{'}}'}}' --include="*.adoc" --include="*.md" --include="*.deed" \ --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 @@ -76,13 +84,14 @@ verify-template: fi # Check for port 0 in Groove manifest - if grep -q '(port 0)' .machine_readable/integrations/groove.a2ml 2>/dev/null; then + DEED="$(bash scripts/deed-field.sh --find . 2>/dev/null || true)" + if [ -n "$DEED" ] && [ "$(bash scripts/deed-field.sh "$DEED" integrations/groove port 2>/dev/null)" = 0 ]; 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/descriptiles/STATE.a2ml .machine_readable/descriptiles/META.a2ml .machine_readable/descriptiles/ECOSYSTEM.a2ml; do + # Check the repo deed for unfilled template placeholders + for f in *_chora.deed; do if [ -f "$f" ] && grep -q '{{'{{'}}' "$f" 2>/dev/null; then echo "⚠ $f still has template placeholders" FOUND=1 diff --git a/build/just/proofs.just b/build/just/proofs.just index 605f71d5..dfd63346 100644 --- a/build/just/proofs.just +++ b/build/just/proofs.just @@ -40,15 +40,6 @@ proof-check-coq: proof-scan-dangerous: @bash scripts/scan-dangerous.sh -# Regenerate the Grade-3 verification receipt (mathesis §6; PROOF-STATUS -# "Grade, and the independent-witness legs"). CI runs the --check form, so a -# committed receipt that no longer matches the tree fails the gate. -proof-receipt: - @bash scripts/grade-receipt.sh --check - -proof-receipt-write: - @bash scripts/grade-receipt.sh --write - # Show proof status summary proof-status: #!/usr/bin/env bash diff --git a/build/just/provision-check.sh b/build/just/provision-check.sh new file mode 100755 index 00000000..36a855ac --- /dev/null +++ b/build/just/provision-check.sh @@ -0,0 +1,121 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# provision-check.sh — offline conformance check for the provisioning set +# (PROVISIONING-STANDARD.adoc §8, items 1–5). No network, no installs. +# +# provision-check.sh [--dev] [REPO_DIR] +# +# Exit 0 = conforms, 1 = does not. Every failure is printed; none is skipped. +# --dev downgrades repository-specific slot residue (__SPEC_X__) to a warning, +# for a checkout mid-specialisation. Mechanical residue (__X__) always fails. +set -uo pipefail + +HERE=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd) +LIB="$HERE/provision-lib.sh" +DEV=0 +[ "${1:-}" = "--dev" ] && { DEV=1; shift; } +REPO="${1:-.}" +cd "$REPO" || { echo "provision-check: no such directory: $REPO" >&2; exit 1; } + +MIN_JUST="1.42.0" +VERBS="setup doctor heal dev-shell toolchain-refresh ai-setup ai-warmup eval config-show opsm build test bench lint fmt fmt-check run deps" # hypatia:ignore eval_in_shell -- "eval" is a verb name, not the shell builtin +# Files the provisioning set owns; residue anywhere else is not ours to judge. +# The engine scripts under build/just/ are excluded: they name slot syntax in their +# own comments and code, and realign owns them. README.adoc is scanned only inside +# its [[ai-install]] section. +# Their locations come from provision-lib.sh (guix-dir, set-files): the engine and +# this check must never disagree about where the Guix files or warm-ups live. +[ -f "$LIB" ] || { echo "provision-check: engine missing: $LIB" >&2; exit 1; } +# Run the provisioning engine with the checked repository as its root. +lib() { PROVISION_ROOT="$PWD" bash "$LIB" "$@"; } +GDIR=$(lib guix-dir) +SET_FILES=$(lib set-files) +# Print the path to Guix filename $1 using the resolved Guix directory. +gp() { [ "$GDIR" = . ] && echo "$1" || echo "$GDIR/$1"; } + +fails=0 warns=0 +# Print a successful conformance check. +ok() { printf ' ok %s\n' "$*"; } +# Print a failed conformance check and increment the failure count. +bad() { printf ' FAIL %s\n' "$*"; fails=$((fails + 1)); } +# Print a conformance warning and increment the warning count. +warn() { printf ' warn %s\n' "$*"; warns=$((warns + 1)); } + +# Return success when version $1 is at least $2, using version sort order. +version_ge() { [ "$(printf '%s\n%s\n' "$2" "$1" | sort -V | head -1)" = "$2" ]; } + +echo "[1] launcher" +if [ ! -f launcher.sh ]; then bad "launcher.sh missing" +elif [ ! -x launcher.sh ]; then bad "launcher.sh is not executable (chmod +x; committed mode must be 100755)" +else + for m in --help --version; do + if ./launcher.sh "$m" >/dev/null 2>&1; then ok "launcher.sh $m exits 0" + else bad "launcher.sh $m exits non-zero"; fi + done +fi + +echo "[2] just" +f0=$fails +if ! command -v just >/dev/null 2>&1; then bad "just is not installed; cannot check the recipe contract" +else + jv=$(just --version 2>/dev/null | awk '{print $2}') + if version_ge "$jv" "$MIN_JUST"; then ok "just $jv >= $MIN_JUST" + else bad "just $jv < $MIN_JUST (module-recipe dependencies do not resolve)"; fi + if ! summary=$(just --summary 2>&1); then + bad "the Justfile does not parse: $(printf '%s' "$summary" | head -1)" + else + have=" $summary " + for v in $VERBS; do + case "$have" in *" $v "*) ;; *) bad "root recipe missing: $v" ;; esac + case "$have" in *" provision::$v "*) ;; *) bad "module recipe missing: provision::$v (engine drift)" ;; esac + done + [ "$fails" -eq "$f0" ] && ok "all ${VERBS// /, } present at root and in provision::" + fi +fi + +echo "[3] mise" +if [ ! -f mise.toml ]; then bad "mise.toml missing" +else + if hit=$(lib mise-banned); then ok "mise.toml names no banned tool"; else bad "mise.toml names banned tools: $hit"; fi + [ -f .mise.toml ] && bad "both mise.toml and .mise.toml exist" + if lg=$(lib mise-lock-gaps); then ok "mise.lock pins every mise.toml tool"; else bad "$lg (latest is not concrete; run: mise lock)"; fi +fi + +echo "[4] guix" +for g in "$(gp guix.scm)" "$(gp manifest.scm)" "$(gp channels.scm)"; do + if r=$(lib guix-stub "$g"); then ok "$g is not a stub"; else bad "$g: $r"; fi +done + +echo "[5] template residue" +f0=$fails +# Read text from stdin and report unfilled slots under label $1; +# repository-specific slots are warnings in --dev mode and failures otherwise. +# Mechanical slots always fail. Callers use the tallies, not the return status. +residue() { # $1 label; stdin = the text to judge + local text mech spec + text=$(cat) + # Mechanical slots (__X__ not starting SPEC_) are the generator's job: always fatal. + mech=$(printf '%s\n' "$text" | grep -noE '__[A-Z][A-Z_]*__' | grep -v ':__SPEC_' | head -3 | tr '\n' ' ') + spec=$(printf '%s\n' "$text" | grep -noE '__SPEC_[A-Z_]*__' | head -3 | tr '\n' ' ') + [ -n "$mech" ] && bad "$1: unfilled mechanical slots: $mech" + if [ -n "$spec" ]; then + if [ "$DEV" = 1 ]; then warn "$1: unfilled repository slots: $spec" + else bad "$1: unfilled repository slots: $spec"; fi + fi +} +for f in $SET_FILES; do + # shellcheck disable=SC2094 # $f is only the label; nothing writes it + [ -f "$f" ] && residue "$f" < "$f" +done +for r in README.adoc README.md; do + [ -f "$r" ] || continue + # From the [[ai-install]] anchor to the next level-2 heading after its own. + residue "$r [[ai-install]]" < <(awk '/^\[\[ai-install\]\]/{on=1; n=0} on && /^== /{n++; if (n>1) exit} on' "$r") +done +[ "$fails" -eq "$f0" ] && ok "no residue that fails this mode" + +echo +echo "provision-check: $fails FAIL, $warns WARN" +[ "$fails" -eq 0 ] diff --git a/build/just/provision-lib.sh b/build/just/provision-lib.sh new file mode 100755 index 00000000..41a74c8f --- /dev/null +++ b/build/just/provision-lib.sh @@ -0,0 +1,972 @@ +#!/usr/bin/env bash +# SC2015: `A && pass || fail` is safe here — pass/warn/fail/info always return 0. +# shellcheck disable=SC2015 +# SPDX-License-Identifier: MPL-2.0 +# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# provision-lib.sh — the shared provisioning engine behind build/just/provision.just +# +# Canon: hyperpolymath/standards 3-practice/provisioning/PROVISIONING-STANDARD.adoc +# Vendored into every repo at build/just/provision-lib.sh by `provision-set mint`. +# DO NOT hand-edit a vendored copy: repo-specific facts live in +# .machine_readable/descriptiles/provisioning_praxis.deed, and `provision-set realign` +# overwrites this file from canon. +# +# Usage: provision-lib.sh [args] +# verbs: langs doctor setup heal dev-shell toolchain-refresh crates-scm ai-setup +# ai-warmup eval config-show opsm lang-run (hypatia:ignore eval_in_shell -- verb list) +# search version +# facts: guix-specs mise-tools langs guix-dir set-files guix-gaps tool-table +# system-deps +# predicates (print why and exit 1, or exit 0 silently): +# guix-stub FILE, mise-lock-gaps, mise-banned +# +# Exit: 0 ok | 1 a FAIL was found / a step failed | 2 usage error +set -uo pipefail + +PROVISION_LIB_VERSION="0.6.0" +ROOT="${PROVISION_ROOT:-$(pwd)}" +cd "$ROOT" || exit 2 +DEED=".machine_readable/descriptiles/provisioning_praxis.deed" +MIN_JUST="1.42.0" # root→module recipe deps (`doctor: provision::doctor`); 1.41 rejects them +# How to get mise: package managers first; the installer only as download, read, run. +MISE_INSTALL_HINT="brew install mise | Fedora: dnf copr enable jdxcode/mise, dnf install mise | winget install jdx.mise | others: https://mise.jdx.dev/installing-mise.html — or: curl -fsSLo mise-install.sh https://mise.run, read it, sh mise-install.sh" +T="timeout 15" # some --version probes hang (observed 2026-09-30); never probe unbounded + +if [ -t 1 ]; then R=$'\033[31m'; G=$'\033[32m'; Y=$'\033[33m'; B=$'\033[34m'; Z=$'\033[0m'; else R=; G=; Y=; B=; Z=; fi +PASS=0; WARN=0; FAIL=0 +# Increment the PASS tally and print the diagnostic message. +pass() { PASS=$((PASS+1)); printf ' %sPASS%s %s\n' "$G" "$Z" "$*"; } +# Increment the WARN tally and print the diagnostic message. +warn() { WARN=$((WARN+1)); printf ' %sWARN%s %s\n' "$Y" "$Z" "$*"; } +# Increment the FAIL tally and print the diagnostic message. +fail() { FAIL=$((FAIL+1)); printf ' %sFAIL%s %s\n' "$R" "$Z" "$*"; } +# Print an informational message without changing diagnostic tallies. +info() { printf ' %sinfo%s %s\n' "$B" "$Z" "$*"; } +# Print a section heading for provisioning output. +hdr() { printf '\n%s== %s ==%s\n' "$B" "$*" "$Z"; } +# Return success when command $1 is available in the current shell. +have() { command -v "$1" >/dev/null 2>&1; } + +# Where this repository keeps each part of the set. A file sits at the root only +# when something needs it there (launcher.sh, Justfile, mise.toml, mise.lock); +# the Guix trio and the warm-ups follow the layout the repository already has +# (rsr-template-repo keeps build/guix.scm and docs/onboarding/llm-warmup-*.adoc). +# This is the ONE answer: provision-check.sh asks it through `guix-dir` and +# `set-files` rather than keeping its own copy. +guix_dir() { if [ -f build/guix.scm ]; then echo build; else echo .; fi; } +# Print the first directory containing warm-up guides, falling back to the root. +warmup_dir() { + local d + for d in . docs/onboarding docs; do + compgen -G "$d/llm-warmup-*.adoc" >/dev/null && { echo "$d"; return; } + done + echo . +} +# Print the path to Guix filename $1 in the repository layout. +gpath() { local d; d=$(guix_dir); [ "$d" = . ] && echo "$1" || echo "$d/$1"; } +# Print the warm-up guide path for audience $1 in the repository layout. +wpath() { local d; d=$(warmup_dir); [ "$d" = . ] && echo "llm-warmup-$1.adoc" || echo "$d/llm-warmup-$1.adoc"; } +# List the provisioning-owned paths checked for unfilled template slots. +set_files() { + printf '%s\n' launcher.sh Justfile justfile mise.toml \ + "$(gpath guix.scm)" "$(gpath manifest.scm)" "$(gpath channels.scm)" \ + "$DEED" docs/SETUP.adoc docs/AI_INSTALLATION_GUIDE.adoc \ + "$(wpath user)" "$(wpath dev)" "$(wpath maintainer)" +} + +# --------------------------------------------------------------------------- +# Descriptor: flat `:key "value"` reads from provisioning_praxis.deed (s-expression). +# Use default $2 when the value is absent or empty; print without a trailing newline. +deed() { # $1 key, $2 default + local v="" + [ -f "$DEED" ] && v=$(grep -oE "\(:?$1[[:space:]]+\"[^\"]*\"" "$DEED" 2>/dev/null | head -1 | sed -E 's/^[^"]*"//; s/"$//') + [ -z "$v" ] && v=$(grep -oE ":$1[[:space:]]+\"[^\"]*\"" "$DEED" 2>/dev/null | head -1 | sed -E 's/^[^"]*"//; s/"$//') + printf '%s' "${v:-$2}" +} +# Derive the repository slug from origin, falling back to hyperpolymath/. +repo_slug() { + local u; u=$(git config --get remote.origin.url 2>/dev/null || true) + u=${u%.git}; u=${u#*github.com[:/]} + [ -n "$u" ] && printf '%s' "$u" || printf 'hyperpolymath/%s' "$(basename "$ROOT")" +} +REPO_SLUG="$(deed repo "$(repo_slug)")" +REPO_NAME="${REPO_SLUG#*/}" +ARCHETYPE="$(deed archetype "")" + +# --------------------------------------------------------------------------- +# Language detection. Markers at the root or one level down (workspaces). The +# estate ABI/FFI pattern nests deeper: Idris2 to two levels down (src/abi/*.ipkg), +# Zig to three (ffi/zig/build.zig, and rsr-template-repo's src/interface/ffi/build.zig: +# 74 repos have their only build.zig at that depth, measured 2026-09-30). +# Order matters only for display. `docs` is reported when nothing else is. +# Print the first path matching glob $1 within find depth $2 (default 2), +# excluding .git, node_modules and root target contents; no match prints nothing. +first() { find . -maxdepth "${2:-2}" -not -path './.git/*' -not -path '*/node_modules/*' -not -path './target/*' -name "$1" -print -quit 2>/dev/null; } +# Print detected languages, one per line; use docs when no language marker exists. +detect_langs() { + local out=() + [ -n "$(first Cargo.toml)" ] && out+=(rust) + [ -n "$(first '*.ipkg' 3)" ] && out+=(idris2) + [ -n "$(first Project.toml 1)" ] && out+=(julia) + [ -n "$(first build.zig 4)" ] && out+=(zig) + [ -n "$(first mix.exs)" ] && out+=(elixir) + [ -n "$(first gleam.toml)" ] && out+=(gleam) + [ -n "$(first dune-project)" ] && out+=(ocaml) + { [ -n "$(first '*.cabal')" ] || [ -n "$(first stack.yaml 1)" ]; } && out+=(haskell) + [ -n "$(first package.json)" ] && out+=(bun) + [ ${#out[@]} -eq 0 ] && out+=(docs) + printf '%s\n' "${out[@]}" +} +mapfile -t LANGS < <(detect_langs) +[ -z "$ARCHETYPE" ] && { [ "${LANGS[*]}" = docs ] && ARCHETYPE=docs || ARCHETYPE=library; } + +# Binaries each language needs, and how each is obtained. +# mise registry gaps (verified 2026-09-30 against mise 2026.7.5): ocaml, haskell, +# idris2 and guile are NOT mise tools. They come from opam / ghcup / pack / the +# system package manager (or Guix), and the doctor probes the binary itself. +lang_tools() { + case "$1" in + rust) echo "cargo rustc" ;; + idris2) echo "idris2" ;; + julia) echo "julia" ;; + zig) echo "zig" ;; + elixir) echo "elixir mix erl" ;; + gleam) echo "gleam erl" ;; + ocaml) echo "opam dune ocaml" ;; + haskell) echo "ghc cabal" ;; + # One package.json, every runtime (LANGUAGE-POLICY §1.4): bun runs it, and + # `js-runtimes regen` needs deno and pnpm to write their locks too. + bun) echo "bun deno pnpm" ;; + docs) echo "" ;; + esac +} +# Guix package specs per language (verified 2026-09-30 against guix ae77aeb in +# docker.io/metacall/guix). Guix has NO idris2, gleam, bun or lychee, and its +# julia is 1.8.5: those come from mise, which Guix itself ships ("mise"). deno +# and pnpm come from mise as well (their Guix packages were not measured). +GUIX_BASE="git bash coreutils nss-certs just mise shellcheck" +# Print the Guix package specifications for language $1, if available. +lang_guix() { + case "$1" in + rust) echo "rust rust:cargo gcc-toolchain pkg-config" ;; + idris2) echo "chez-scheme gmp gcc-toolchain" ;; + zig) echo "zig" ;; + elixir) echo "elixir erlang" ;; + gleam) echo "erlang" ;; + ocaml) echo "ocaml dune opam ocaml-findlib" ;; + haskell) echo "ghc cabal-install" ;; + docs) echo "ruby-asciidoctor" ;; + julia|bun) echo "" ;; + esac +} +# Tools a Guix shell cannot supply, so mise (inside that shell) does. +lang_guix_gap() { + case "$1" in + idris2) echo "idris2 (via pack)" ;; julia) echo julia ;; gleam) echo gleam ;; bun) echo "bun deno pnpm" ;; docs) echo lychee ;; + esac +} +# Print deduplicated base and detected-language Guix package specifications. +guix_specs() { + local l s=" $GUIX_BASE " + for l in "${LANGS[@]}"; do for p in $(lang_guix "$l"); do case "$s" in *" $p "*) ;; *) s="$s$p ";; esac; done; done + echo "$s" | xargs +} + +# mise tools per language (registry-checked 2026-09-30, mise 2026.7.5). idris2 comes +# from pack and haskell from ghcup or Guix: neither is a mise tool. The recipes +# themselves need just and shellcheck, so those two are always declared. +MISE_BASE="just shellcheck" +# Tools a repo's own recipes call (e.g. `deps-audit` runs trivy): pinned only where used. +RECIPE_TOOLS="trivy" +# Print the mise tool names for language $1, if supported. +lang_mise() { case "$1" in + rust) echo "rust" ;; zig) echo "zig" ;; julia) echo "julia" ;; + elixir) echo "erlang elixir" ;; gleam) echo "erlang gleam" ;; ocaml) echo "opam" ;; + bun) echo "bun deno pnpm" ;; docs) echo "lychee" ;; esac; } +# Print known recipe tools referenced outside comments in the repository Justfiles. +recipe_tools() { + local t f body="" + for f in Justfile justfile build/just/*.just; do + [ -f "$f" ] && body+=$(grep -v '^[[:space:]]*#' "$f")$'\n' + done + for t in $RECIPE_TOOLS; do + [[ "$body" =~ (^|[^[:alnum:]_-])$t([^[:alnum:]_-]|$) ]] && echo "$t" + done +} + +# Print deduplicated mise tools needed by the base, detected languages and recipes. +# Usage: mise_tools [lang ...] +# The language list defaults to what the tree detects; callers that already know +# (scripts/render-mise.sh --langs) pass it, so an override actually changes the, +# toolchain rather than only the label above it. +mise_tools() { + local l t seen=" " out=() use=() + if [ "$#" -gt 0 ]; then use=("$@"); else use=("${LANGS[@]}"); fi + for t in $MISE_BASE $(for l in "${use[@]}"; do lang_mise "$l"; done) $(recipe_tools); do + case "$seen" in *" $t "*) ;; *) out+=("$t"); seen="$seen$t " ;; esac + done + printf "%s\n" "${out[*]}" +} + +# Print installation guidance for the toolchain of language $1. +lang_remedy() { + case "$1" in + rust) echo "mise use rust@latest (or rustup: https://rustup.rs)" ;; + idris2) echo "install pack: https://github.com/stefan-hoeck/idris2-pack#installation, then: pack install-app idris2" ;; + julia) echo "mise use julia@latest (or: https://julialang.org/install/ — juliaup)" ;; + zig) echo "mise use zig@latest" ;; + elixir) echo "mise use erlang@latest elixir@latest (erlang builds from source: allow ~10 min)" ;; + gleam) echo "mise use gleam@latest erlang@latest" ;; + ocaml) echo "mise use opam@latest && opam init -y && opam switch create . --deps-only -y" ;; + haskell) echo "ghcup: https://www.haskell.org/ghcup/ (or: just dev-shell, which uses Guix)" ;; + bun) echo "mise use bun@latest deno@latest pnpm@latest" ;; + esac +} + +# The per-language default for each contract verb. A repo overrides any of +# these simply by defining the root recipe itself; `provision-set` only adds +# `: provision::` where the root Justfile has no such recipe. +lang_cmd() { # $1 lang, $2 verb -> prints a shell command, or nothing (= N/A) + local l=$1 v=$2 ipkg + case "$l:$v" in + rust:deps) echo "cargo fetch" ;; + rust:build) echo "cargo build --all-targets" ;; + rust:test) echo "cargo test --all-targets" ;; + rust:bench) grep -rqs '\[\[bench\]\]\|criterion\|divan' --include=Cargo.toml . && echo "cargo bench" ;; + rust:lint) echo "cargo clippy --all-targets -- -D warnings" ;; + rust:fmt) echo "cargo fmt --all" ;; + rust:fmt-check) echo "cargo fmt --all -- --check" ;; + rust:run) echo "cargo run --release" ;; + + idris2:*) + ipkg=$(first '*.ipkg' 1); [ -z "$ipkg" ] && ipkg=$(first '*.ipkg'); [ -z "$ipkg" ] && ipkg=$(first '*.ipkg' 3); ipkg=${ipkg#./} + case "$v" in + deps) have pack && echo "pack install-deps $ipkg" ;; + build) have pack && echo "pack build $ipkg" || echo "idris2 --build $ipkg" ;; + test) local t; t=$(find . -maxdepth 3 -name 'test*.ipkg' -print -quit 2>/dev/null) + if [ -n "$t" ]; then have pack && echo "pack test ${t#./}" || echo "idris2 --build ${t#./}" + else have pack && echo "pack typecheck $ipkg" || echo "idris2 --typecheck $ipkg"; fi ;; + run) grep -qs '^[[:space:]]*executable' "$ipkg" && { have pack && echo "pack run $ipkg" || echo "idris2 --build $ipkg && ./build/exec/*"; } ;; + esac ;; + + julia:deps) echo "julia --project=. -e 'using Pkg; Pkg.instantiate()'" ;; + julia:build) echo "julia --project=. -e 'using Pkg; Pkg.precompile()'" ;; + julia:test) echo "julia --project=. -e 'using Pkg; Pkg.test()'" ;; + julia:bench) [ -f benchmark/benchmarks.jl ] && echo "julia --project=benchmark -e 'using Pkg; Pkg.develop(path=\".\"); Pkg.instantiate(); include(\"benchmark/benchmarks.jl\")'" ;; + + zig:*) + # build.zig may sit in ffi/zig/; run there, not at the root. + local zb zd; zb=$(first build.zig 1); [ -z "$zb" ] && zb=$(first build.zig); [ -z "$zb" ] && zb=$(first build.zig 3); [ -z "$zb" ] && zb=$(first build.zig 4) + zd=$(dirname "${zb#./}"); local cdz=""; [ "$zd" != . ] && cdz="cd '$zd' && " + case "$v" in + build) echo "${cdz}zig build" ;; + test) grep -qs '"test"' "$zb" && echo "${cdz}zig build test" ;; + bench) grep -qs '"bench"' "$zb" && echo "${cdz}zig build bench -Doptimize=ReleaseFast" ;; + fmt) echo "zig fmt $zd" ;; + fmt-check) echo "zig fmt --check $zd" ;; + lint) echo "zig fmt --check $zd" ;; + run) grep -qs '"run"' "$zb" && echo "${cdz}zig build run" ;; + esac ;; + + elixir:deps) echo "mix local.hex --force --if-missing && mix local.rebar --force --if-missing && mix deps.get" ;; + elixir:build) echo "mix compile --warnings-as-errors" ;; + elixir:test) echo "mix test" ;; + elixir:bench) ls bench/*.exs >/dev/null 2>&1 && echo "for f in bench/*.exs; do mix run \"\$f\"; done" ;; + elixir:lint) grep -qs ':credo' mix.exs && echo "mix credo --strict" || echo "mix compile --warnings-as-errors" ;; + elixir:fmt) echo "mix format" ;; + elixir:fmt-check) echo "mix format --check-formatted" ;; + elixir:run) echo "mix run --no-halt" ;; + + gleam:deps) echo "gleam deps download" ;; + gleam:build) echo "gleam build" ;; + gleam:test) echo "gleam test" ;; + gleam:fmt) echo "gleam format" ;; + gleam:fmt-check) echo "gleam format --check" ;; + gleam:lint) echo "gleam format --check" ;; + gleam:run) echo "gleam run" ;; + + ocaml:deps) echo "opam install . --deps-only --with-test -y" ;; + ocaml:build) echo "opam exec -- dune build" ;; + ocaml:test) echo "opam exec -- dune test" ;; + ocaml:fmt) echo "opam exec -- dune fmt" ;; + ocaml:fmt-check) echo "opam exec -- dune build @fmt" ;; + + haskell:deps) echo "cabal update && cabal build all --only-dependencies" ;; + haskell:build) echo "cabal build all" ;; + haskell:test) echo "cabal test all" ;; + haskell:bench) grep -qs '^benchmark' ./*.cabal && echo "cabal bench all" ;; + haskell:run) echo "cabal run" ;; + + bun:deps) [ -f bun.lock ] || [ -f bun.lockb ] && echo "bun install --frozen-lockfile" || echo "bun install" ;; + bun:build) grep -qs '"build"[[:space:]]*:' package.json && echo "bun run build" ;; + # `bun test` exits 0 when it finds no test files, so it runs only when some exist. + bun:test) if grep -qs '"test"[[:space:]]*:' package.json; then echo "bun run test" + elif git ls-files 2>/dev/null | grep -qE '(\.|_)(test|spec)\.(js|mjs|cjs|jsx)$'; then echo "bun test"; fi ;; + bun:bench) grep -qs '"bench"[[:space:]]*:' package.json && echo "bun run bench" ;; + bun:lint) grep -qs '"lint"[[:space:]]*:' package.json && echo "bun run lint" ;; + bun:fmt) grep -qs '"fmt"[[:space:]]*:' package.json && echo "bun run fmt" ;; + bun:fmt-check) grep -qs '"fmt-check"[[:space:]]*:' package.json && echo "bun run fmt-check" ;; + bun:run) grep -qs '"start"[[:space:]]*:' package.json && echo "bun run start" ;; + + docs:test) have asciidoctor && echo "for f in \$(git ls-files '*.adoc'); do asciidoctor -o /dev/null --failure-level=WARN \"\$f\" || exit 1; done" ;; + docs:lint) have lychee && echo "lychee --offline --no-progress \$(git ls-files '*.adoc' '*.md')" ;; + esac +} + +# Run a contract verb across every detected language. N/A is reported, not +# faked green: a verb with no command for any language exits 0 but SAYS so. +# A deed override runs alone and its status is returned. Otherwise all available +# language commands run; return the last failing status, or 0 if none failed. +lang_run() { # $1 verb + local verb=$1 ran=0 rc=0 l cmd override + override=$(deed "$verb" "") + if [ -n "$override" ]; then + info "$verb (from provisioning_praxis.deed): $override" + bash -c "$override"; return $? + fi + for l in "${LANGS[@]}"; do + cmd=$(lang_cmd "$l" "$verb") + [ -z "$cmd" ] && continue + ran=1 + info "$verb [$l]: $cmd" + bash -c "$cmd" || { rc=$?; printf ' %sFAIL%s %s [%s] exited %s\n' "$R" "$Z" "$verb" "$l" "$rc" >&2; } + done + [ $ran -eq 0 ] && info "$verb: N/A for ${LANGS[*]} (archetype: $ARCHETYPE) — nothing to run, and nothing was faked" + return $rc +} + +# --------------------------------------------------------------------------- +# A repo keeps its own checks as root recipes named doctor-local / setup-local / +# heal-local (provision-set renames a pre-existing custom doctor/setup/heal to +# these); the canon verbs run them, so `just doctor`, `./launcher.sh --doctor` and +# CI all see the same result. +has_recipe() { have just && just --summary 2>/dev/null | tr " " "\n" | grep -qx "$1"; } + +# Return success when version $1 is at least $2, using version sort order. +version_ge() { [ "$(printf '%s\n%s\n' "$2" "$1" | sort -V | head -1)" = "$2" ]; } + +# Tools that must never appear in a repo's toolchain (estate language policy). +# deno and pnpm are permitted runtimes since the 2026-10-14 ruling (Bun > Deno > +# pnpm > npm); node stays banned, so npm, the last resort, is never provisioned. +BANNED_TOOLS='python|node|nodejs|npm|yarn|typescript|rescript|make|black|ruff|pip|poetry|nix|go|golang|java|kotlin' +BANNED_BACKENDS='npm|pipx|pip|go' + +# --------------------------------------------------------------------------- +# Shared predicates. doctor and provision-check.sh both call THESE (the check via +# `provision-lib.sh guix-stub|mise-lock-gaps|mise-banned`): a gate with its own +# copy of a test passes what doctor warns about. + +# The tools every repository mise config declares, quotes stripped ("cargo:foo" +# stays cargo:foo): the [tools] keys of mise.toml and .mise.toml and the first +# word of each .tool-versions line. mise merges all three, so a predicate that +# read mise.toml alone would pass a banned tool pinned in the others. +mise_toml_tools() { + local f + for f in .tool-versions mise.toml .mise.toml; do + [ -f "$f" ] || continue + if [ "$f" = .tool-versions ]; then + awk '!/^[ \t]*(#|$)/{print $1}' "$f" + else + awk '/^\[tools\]/{t=1;next} /^\[/{t=0} t && /=/{sub(/[ \t]*=.*/,""); gsub(/["\x27 ]/,""); print}' "$f" + fi + done | awk '!seen[$0]++' +} +# True when a bare registry name resolves only to banned backends ("prettier" +# is only npm:prettier). Needs no network: `mise registry` reads the registry +# baked into mise. False when mise is absent or does not know the name, so an +# unknown tool is left to mise-lock to report, never called banned on a guess. +only_banned_backends() { + local b n=0 + command -v mise >/dev/null 2>&1 || return 1 + for b in $(mise registry "$1" 2>/dev/null); do + n=$((n + 1)) + [[ "$b" =~ ^($BANNED_BACKENDS): ]] || return 1 + done + [ "$n" -gt 0 ] +} +# Banned tools named in the mise configs. A backend prefix does not hide one +# ("aqua:denoland/deno" is deno), an npm:/pipx:/pip:/go: backend installs +# through a banned runtime whatever the package is ("npm:prettier"), and so does +# a bare name with no other backend ("prettier"). +# Print space-separated matches without a trailing newline; callers determine +# failure from non-empty output. +mise_banned() { + local t base hits="" + for t in $(mise_toml_tools); do + base=${t##*:}; base=${base%%@*}; base=${base##*/} + if [[ "$base" =~ ^($BANNED_TOOLS)$ ]] || [[ "$t" =~ ^($BANNED_BACKENDS): ]]; then + hits="$hits$t " + elif [[ "$t" != *:* ]] && only_banned_backends "$t"; then + hits="$hits$t " + fi + done + printf '%s' "${hits% }" +} +# Print the first category of lockfile gaps, or nothing if none is found. +# Skip checking when mise.toml is absent; otherwise check tools from all three +# config files for a non-empty version and platform tables for sha256 entries. +# Callers inspect stdout; version concreteness and checksum contents are not validated. +mise_lock_gaps() { + [ -f mise.toml ] || return 0 + [ -f mise.lock ] || { echo "mise.lock missing"; return; } + [ -s mise.lock ] || { echo "mise.lock is empty"; return; } + local t miss="" + # A tool is pinned when its [[tools.X]] block carries a concrete version line. + for t in $(mise_toml_tools); do + awk -v a="[[tools.$t]]" -v b="[[tools.\"$t\"]]" ' + $0 == a || $0 == b { inb = 1; next } + /^\[/ { inb = 0 } + inb && /^version = "[^"]+"/ { ok = 1 } + END { exit !ok }' mise.lock || miss="$miss$t " + done + [ -n "$miss" ] && { echo "mise.lock does not pin: ${miss% }"; return; } + # Checksums are per artefact: every [tools.X."platforms.P"] table needs its own + # sha256, so one checksummed tool cannot vouch for another. A tool with no + # platform tables has no artefact to checksum (core:rust installs through + # rustup, cargo: builds from source), which is what `mise lock` writes for it. + miss=$(awk ' + # Print the open platform table as tool/platform when it carried no sha256. + function close_table() { if (p != "" && !c) printf "%s ", p; p = "" } + /^\[tools\..*platforms\./ { close_table(); p = $0; c = 0 + gsub(/^\[tools\.|\]$|"/, "", p); sub(/\.platforms\./, "/", p); next } + /^\[/ { close_table() } + /^checksum = "sha256:[0-9a-f]+"/ { c = 1 } + END { close_table() }' mise.lock) + [ -z "$miss" ] || echo "mise.lock has no sha256 for: ${miss% }" +} +# Print why Guix file $1 appears to be a stub, or nothing if the textual checks +# pass. Check required package fields as well as known stub shapes; this does +# not evaluate Scheme or verify that the package builds. Callers inspect stdout. +# For example, `(package (name "x") (source (local-file ".")))` is a stub. +guix_stub_reason() { + local f=$1 k miss="" + [ -f "$f" ] || { echo "missing"; return; } + grep -qE '\{\{|__[A-Z][A-Z_]*__' "$f" && { echo "unfilled template slots"; return; } + grep -qE '\(inputs \(list\)\)|\(source #f\)' "$f" && { echo "empty inputs or no source"; return; } + case "${f##*/}" in + manifest.scm) grep -q 'specifications->manifest' "$f" || echo "lists no specifications"; return ;; + channels.scm) grep -qE '\(commit "[0-9a-f]{40}"\)' "$f" || echo "pins no commit"; return ;; + esac + for k in name version source build-system home-page synopsis description license; do + grep -qE "\\(${k}[[:space:]]" "$f" || miss="$miss$k " + done + [ -n "$miss" ] && { echo "no package field: ${miss% }"; return; } + if grep -q 'crates\.scm' "$f"; then + grep -qs 'define %crate-inputs' build/guix/crates.scm || echo "build/guix/crates.scm is missing or defines no %crate-inputs" + fi +} + +# --------------------------------------------------------------------------- +# Facts the generator writes into docs/SETUP.adoc and the AI guide. They live here, +# beside lang_tools and lang_remedy, so no second per-language table exists. +lang_title() { case "$1" in + rust) echo Rust ;; idris2) echo Idris2 ;; julia) echo Julia ;; zig) echo Zig ;; elixir) echo Elixir ;; + gleam) echo Gleam ;; ocaml) echo OCaml ;; haskell) echo Haskell ;; bun) echo Bun ;; docs) echo Docs ;; esac; } +# What a language's route needs from the OS: "fedora|debian|macos command|why", or nothing. +lang_sysdeps() { case "$1" in + rust) echo "gcc pkgconf-pkg-config|build-essential pkg-config|xcode-select --install|Rust links through the system C toolchain, and pkg-config finds C libraries" ;; + idris2) echo "chez-scheme gmp-devel|chezscheme libgmp-dev|brew install chezscheme gmp|pack builds Idris2 on top of Chez Scheme and GMP" ;; + elixir|gleam) echo "gcc gcc-c++ make autoconf ncurses-devel openssl-devel|build-essential autoconf m4 libncurses-dev libssl-dev|brew install autoconf openssl@3|mise builds Erlang/OTP from source (allow ~10 min); the make here is the system tool that build uses, not a Makefile in this repository" ;; + ocaml) echo "gcc make patch unzip bubblewrap|build-essential patch unzip bubblewrap|xcode-select --install|opam compiles OCaml and sandboxes its builds with bubblewrap" ;; + haskell) echo "gcc gcc-c++ gmp-devel make ncurses-devel xz perl|build-essential curl libffi-dev libgmp-dev libncurses-dev|xcode-select --install|ghcup installs GHC, which links through the C toolchain and GMP" ;; +esac; } +# Print a comma-separated list of tools Guix cannot supply, or none. +guix_gaps() { + local l g gaps="" + for l in "${LANGS[@]}"; do g=$(lang_guix_gap "$l"); [ -n "$g" ] && gaps="$gaps${gaps:+, }$g"; done + printf '%s\n' "${gaps:-none}" +} +# Print AsciiDoc table rows describing required tools and installation commands. +tool_table() { + local l t base + for l in "${LANGS[@]}"; do + if [ "$l" = docs ]; then echo "|docs |\`lychee\` |mise use lychee@latest"; continue; fi + t=$(lang_tools "$l"); echo "|$l |\`${t// /\`, \`}\` |$(lang_remedy "$l")" + done + base="$MISE_BASE $(recipe_tools | xargs)"; base=$(echo "$base" | xargs) + echo "|(recipes) |\`${base// /\`, \`}\` |mise install, or your OS package manager (e.g. \`dnf install just ShellCheck\`)" +} +# shellcheck disable=SC2016 # the backticks are AsciiDoc literals, not command substitution +# Print OS dependency guidance for detected languages; $1 selects adoc or ai output. +system_deps() { # $1 adoc|ai + local l d seen="" fed deb mac why any=0 + [ "$1" = adoc ] && printf '=== System packages\n' + for l in "${LANGS[@]}"; do + d=$(lang_sysdeps "$l"); [ -z "$d" ] && continue + case "$seen" in *"|$d|"*) continue ;; esac; seen="$seen|$d|"; any=1 + IFS='|' read -r fed deb mac why <<<"$d" + if [ "$1" = adoc ]; then + printf '\n%s: %s.\n\n* Fedora: `sudo dnf install %s`\n* Debian/Ubuntu: `sudo apt install %s`\n* macOS: `%s`\n' \ + "$(lang_title "$l")" "$why" "$fed" "$deb" "$mac" + else + printf '* %s needs OS packages (%s): Fedora `sudo dnf install %s` · Debian/Ubuntu `sudo apt install %s` · macOS `%s`.\n' \ + "$(lang_title "$l")" "$why" "$fed" "$deb" "$mac" + fi + done + if [ "$1" = adoc ]; then + if [ $any -eq 1 ]; then printf '\nThe Guix development shell (`%s`) provides these itself, so inside `just dev-shell` none of them is needed.\n' "$(gpath manifest.scm)" + else printf '\nNone beyond git and a shell: every tool this repository needs comes from mise, or from the Guix shell.\n'; fi + elif [ $any -eq 0 ]; then printf '* No other OS packages: every tool comes from mise.\n'; fi +} + +# Diagnose the provisioning set and toolchain, then the repository's own +# doctor-local checks. The PASS/WARN/FAIL tally is the last line of stdout; +# returns non-zero when anything FAILed. +# Warnings alone do not fail. An early doctor-local.sh exit or failed +# doctor-local recipe becomes a FAIL rather than propagating its exit status. +cmd_doctor() { + printf '%s doctor — %s (%s; languages: %s)\n' "$REPO_NAME" "$REPO_SLUG" "$ARCHETYPE" "${LANGS[*]}" + + hdr "Core toolchain" + have git && pass "git $($T git --version 2>/dev/null | awk '{print $3}')" || fail "PV-E01 git not found — install git from your OS package manager" + if have just; then + local jv; jv=$($T just --version 2>/dev/null | awk '{print $2}') + version_ge "$jv" "$MIN_JUST" && pass "just $jv (>= $MIN_JUST)" || fail "PV-E02 just $jv is older than $MIN_JUST — run: mise use just@latest" + else fail "PV-E02 just not found — run: mise use -g just@latest (or see docs/SETUP.adoc)"; fi + if have mise; then + pass "mise $($T mise --version 2>/dev/null | awk '{print $1}')" + if [ -f mise.toml ] || [ -f .mise.toml ]; then + # Only THIS repo's declarations: `mise ls` also lists the user's global config. + local here=${ROOT/#$HOME/\~} missing + missing=$($T mise ls --current --missing 2>/dev/null | grep -F -e "$here/mise.toml" -e "$here/.mise.toml" -e "$ROOT/mise.toml" | awk '{print $1"@"$2}' | tr '\n' ' ') + [ -z "${missing// /}" ] && pass "every mise tool is installed" || fail "PV-E03 mise tools not installed: $missing— run: just setup" + fi + else warn "PV-W01 mise not found — tools must then come from Guix or your OS; install: $MISE_INSTALL_HINT"; fi + if have guix; then pass "guix $($T guix --version 2>/dev/null | head -1 | awk '{print $NF}') (optional reproducible path)" + else info "guix not installed — optional; mise is the default path (docs/SETUP.adoc §Guix)"; fi + + hdr "Language toolchains" + local l t + for l in "${LANGS[@]}"; do + [ "$l" = docs ] && { info "no build language detected — docs/theory archetype"; continue; } + for t in $(lang_tools "$l"); do + if have "$t"; then pass "$l: $t ($(command -v "$t"))" + else fail "PV-E10 $l: '$t' not found — run: just setup (manual: $(lang_remedy "$l"))"; fi + done + done + local extra; extra=$(deed system-deps "") + for t in $extra; do have "$t" && pass "system dep: $t" || fail "PV-E11 system dependency '$t' not found (declared in $DEED) — see docs/SETUP.adoc §Prerequisites"; done + + hdr "Repository provisioning files" + [ -f mise.toml ] && pass "mise.toml" || fail "PV-E20 mise.toml missing — the toolchain is undeclared" + local lg; lg=$(mise_lock_gaps) + [ -z "$lg" ] && pass "mise.lock pins every mise.toml tool (latest → concrete, checksummed)" || warn "PV-W20 $lg — run: just toolchain-refresh" + [ -f .mise.toml ] && [ -f mise.toml ] && warn "PV-W21 both mise.toml and .mise.toml — mise merges them; keep only mise.toml" + [ -f .tool-versions ] && warn "PV-W22 .tool-versions present — a second toolchain source; fold it into mise.toml" + if [ -f mise.toml ] || [ -f .mise.toml ] || [ -f .tool-versions ]; then + local bad; bad=$(mise_banned) + [ -z "$bad" ] && pass "the mise configs pin no banned tool" || warn "PV-W23 a mise config pins banned tool(s): $bad (language policy: Bun > Deno > pnpm; no python/node/npm/make)" + fi + # hypatia guix_not_stub reads guix.scm AND build/guix.scm; an unfilled __PLACEHOLDER__ is a stub too. + local g r gstub="" + for g in guix.scm build/guix.scm "$(gpath manifest.scm)" "$(gpath channels.scm)"; do + [ -f "$g" ] || continue + r=$(guix_stub_reason "$g"); [ -n "$r" ] && gstub="$gstub$g ($r) " + done + local gs gm; gs=$(gpath guix.scm); gm=$(gpath manifest.scm) + [ -f guix.scm ] && [ -f build/guix.scm ] && warn "PV-W35 both guix.scm and build/guix.scm exist — two Guix sources; keep one (build/ is used)" + if [ -f "$gs" ]; then + if [ -n "$gstub" ]; then warn "PV-W24 template stub in: $gstub— the Guix path does not build this repo (just heal cannot fix this; provision-set realign does)" + else pass "$gs (non-stub)"; fi + else warn "PV-W25 guix.scm missing — no reproducible Guix path"; fi + [ -f "$gm" ] && pass "$gm (guix shell -m $gm)" || warn "PV-W26 $gm missing — 'just dev-shell' falls back to mise" + [ -x launcher.sh ] && pass "launcher.sh (executable)" || { [ -f launcher.sh ] && fail "PV-E27 launcher.sh not executable — run: just heal" || warn "PV-W27 launcher.sh missing"; } + local d + for d in docs/SETUP.adoc docs/AI_INSTALLATION_GUIDE.adoc "$(wpath user)" "$(wpath dev)" "$(wpath maintainer)"; do + if [ ! -f "$d" ]; then warn "PV-W28 $d missing" + elif grep -qE "__[A-Z][A-Z_]*__" "$d"; then warn "PV-W29 $d still has unfilled template slots (__SPEC_…__) — replace each with the facts for this repo" + else pass "$d"; fi + done + + hdr "Estate policy drift" + local f any=0 + # deno.lock is a generated lock every package carries (`js-runtimes regen`); + # authoring in Deno is permitted (tier 2), so its manifests are a notice only. + for f in deno.json deno.jsonc import_map.json; do + [ -f "$f" ] && info "PV-W30 $f — authored for Deno (permitted, tier 2); package.json stays the one manifest every runtime reads" + done + for f in flake.nix flake.lock shell.nix default.nix; do [ -f "$f" ] && { warn "PV-W31 $f — Nix is not an estate toolchain; Guix is"; any=1; }; done + for f in Makefile GNUmakefile makefile; do [ -f "$f" ] && { warn "PV-W32 $f — Justfile is the only task runner"; any=1; }; done + for f in requirements.txt pyproject.toml setup.py Pipfile; do [ -f "$f" ] && { warn "PV-W33 $f — Python is not an estate language"; any=1; }; done + for f in package-lock.json yarn.lock tsconfig.json; do [ -f "$f" ] && { warn "PV-W34 $f — npm/yarn/TypeScript leftover; package.json + bun.lock, deno.lock and pnpm-lock.yaml (js-runtimes regen)"; any=1; }; done + [ $any -eq 0 ] && pass "no nix / make / python / npm leftovers" + + local hook=build/just/doctor-local.sh + if [ -f "$hook" ]; then + hdr "Repo-specific checks ($hook)" + # Sourced so the hook can call pass/warn/fail, but in a subshell so an `exit` + # or `set -e` in it cannot end the doctor before the summary. The EXIT trap + # hands the hook's tally back; an early exit is itself a FAIL. + local tally qtally hp w f rc + tally=$(mktemp) + printf -v qtally '%q' "$tally" + # shellcheck disable=SC2030,SC2031 # the subshell's counts return via $tally + ( PASS=0 WARN=0 FAIL=0 hook_done=0 + # The path is baked in now: when `set -e` trips, bash unwinds this + # function's locals before the EXIT trap runs, so $tally is gone by then. + # shellcheck disable=SC2064 + trap "printf '%d %d %d %d\n' \"\$PASS\" \"\$WARN\" \"\$FAIL\" \"\$hook_done\" > $qtally" EXIT + # shellcheck source=/dev/null + . "$hook" + hook_done=1 ) + rc=$? + read -r hp w f hook_done < "$tally" || { hp=0 w=0 f=0 hook_done=0; } + rm -f "$tally" + # shellcheck disable=SC2031 + PASS=$((PASS+hp)) WARN=$((WARN+w)) FAIL=$((FAIL+f)) + [ "$hook_done" = 1 ] || fail "PV-E51 $hook exited (status $rc) before it finished; its later checks did not run" + fi + if has_recipe doctor-local; then + hdr "Repo-specific checks (just doctor-local)" + just doctor-local && pass "doctor-local" || fail "PV-E50 the repo-specific doctor-local recipe failed (output above)" + fi + + printf '\n%s: %s%d PASS%s, %s%d WARN%s, %s%d FAIL%s\n' "$REPO_NAME" "$G" "$PASS" "$Z" "$Y" "$WARN" "$Z" "$R" "$FAIL" "$Z" + if [ "$FAIL" -gt 0 ]; then + # stderr, so the tally above stays the last line of stdout on every outcome. + echo "Next: 'just heal' fixes what is safe to fix automatically; each FAIL code is explained in docs/SETUP.adoc §Troubleshooting." >&2 + return 1 + fi + return 0 +} + +# Install available toolchains and dependencies, run local setup hooks, then doctor; +# return non-zero when a tracked installation step or verification fails. +# May trust mise configuration, extend PATH, initialise opam and make the +# launcher executable. Installation and hook failures do not skip verification. +cmd_setup() { + printf '%s setup — installing everything this repository needs\n' "$REPO_NAME" + local rc=0 + if have mise; then + hdr "mise toolchain" + $T mise trust -q . 2>/dev/null || true + mise install || rc=1 + else + warn "mise not found. Install it ($MISE_INSTALL_HINT), or enter the Guix shell with 'just dev-shell', then re-run: just setup" + fi + local l + for l in "${LANGS[@]}"; do + case "$l" in + idris2) have pack || warn "pack not found — Idris2 comes from pack, not mise: $(lang_remedy idris2)" ;; + haskell) have ghcup || have ghc || warn "ghc not found — $(lang_remedy haskell)" ;; + ocaml) have opam && { opam switch show >/dev/null 2>&1 || opam init -y --bare; } ;; + esac + done + hdr "Project dependencies" + # Put this repo's mise tools on PATH for the dependency step. + if have mise; then PATH="$(mise bin-paths 2>/dev/null | paste -sd: -):$PATH"; export PATH; fi + lang_run deps || rc=1 + local hook=build/just/setup-local.sh + [ -f "$hook" ] && { hdr "Repo-specific setup ($hook)"; bash "$hook" || rc=1; } + has_recipe setup-local && { hdr "Repo-specific setup (just setup-local)"; just setup-local || rc=1; } + [ -f launcher.sh ] && chmod +x launcher.sh + hdr "Verification" + cmd_doctor || rc=1 + [ $rc -eq 0 ] && printf '\n%sReady.%s Try: just --list\n' "$G" "$Z" || printf '\n%sSetup incomplete%s — read the FAIL lines above; docs/SETUP.adoc has the manual route.\n' "$R" "$Z" + return $rc +} + +# Apply automatic environment repairs and local heal hooks, then return doctor status. +# Earlier repair and hook failures are not propagated independently of doctor. +cmd_heal() { + printf '%s heal — applying safe, reversible fixes, then re-checking\n' "$REPO_NAME" + hdr "Fixes" + [ -f launcher.sh ] && [ ! -x launcher.sh ] && chmod +x launcher.sh && info "made launcher.sh executable" + for f in build/just/*.sh scripts/*.sh; do [ -f "$f" ] && [ ! -x "$f" ] && chmod +x "$f" && info "made $f executable"; done + if have mise; then + $T mise trust -q . 2>/dev/null && info "mise config trusted" + mise install && info "mise tools installed" + [ -f mise.lock ] || { $T mise lock 2>/dev/null && info "mise.lock generated"; } + fi + if printf '%s\n' "${LANGS[@]}" | grep -qx elixir && have mix; then mix deps.get >/dev/null 2>&1 && info "mix deps fetched"; fi + if printf '%s\n' "${LANGS[@]}" | grep -qx bun && have bun; then bun install >/dev/null 2>&1 && info "bun deps installed"; fi + if printf '%s\n' "${LANGS[@]}" | grep -qx julia && have julia; then julia --project=. -e 'using Pkg; Pkg.instantiate()' >/dev/null 2>&1 && info "julia deps instantiated"; fi + local hook=build/just/heal-local.sh + [ -f "$hook" ] && { info "running $hook"; bash "$hook" || true; } + has_recipe heal-local && { info "running just heal-local"; just heal-local || true; } + echo "Not touched (never automatic): source files, git history, Deno/Nix/Make leftovers — those are migrations, tracked as issues." + hdr "Re-check" + cmd_doctor +} + +# Replace this process with Guix when its manifest exists and has no {{ residue; +# otherwise use mise and SHELL (default bash). Return 1 if neither route is +# available; a failed exec terminates the script without trying the other route. +cmd_dev_shell() { + local gm; gm=$(gpath manifest.scm) + if have guix && [ -f "$gm" ] && ! grep -q '{{' "$gm"; then + info "entering: guix shell -m $gm (exit to leave)" + exec guix shell -m "$gm" + elif have mise; then + info "guix/manifest.scm unavailable — entering the mise environment instead (exit to leave)" + exec mise exec -- "${SHELL:-bash}" + else + fail "PV-E40 neither guix nor mise is installed — see docs/SETUP.adoc"; return 1 + fi +} + +# Print the 40-hex commit of the `guix` channel in a channels list read from +# stdin (`guix describe --format=channels`), or nothing when there is none. +guix_channel_commit() { + awk '/\(name .guix\)/ { g = 1 } + g && match($0, /\(commit "[0-9a-f]{40}"\)/) { print substr($0, RSTART + 9, 40); exit }' +} + +# Re-pin only the `guix` channel's commit in channels file $1 to $2, keeping +# every other line (comments, other channels, introduction) as it is. Returns +# non-zero, leaving the file untouched, when it has no guix channel commit. +repin_guix_channel() { + local ch=$1 pin=$2 tmp + tmp=$(mktemp) || return 1 + if awk -v pin="$pin" ' + /\(name .guix\)/ { g = 1 } + g && !done && sub(/\(commit "[0-9a-f]{40}"\)/, "(commit \"" pin "\")") { done = 1 } + { print } + END { exit !done }' "$ch" > "$tmp"; then + cat "$tmp" > "$ch"; rm -f "$tmp" + else + rm -f "$tmp"; return 1 + fi +} + +# Weekly toolchain refresh: bump mise pins and the lock, re-pin the Guix channel, +# regenerate build/guix/crates.scm when guix.scm loads it, then show the diff +# for a signed commit. +# Return 1 for missing mise or failed mise update, locking or crate regeneration. +# Channel pin failures are warnings; unavailable Guix operations are skipped. +# Earlier updates are not rolled back. +cmd_toolchain_refresh() { + hdr "mise: bump 'latest' resolutions and re-lock" + have mise || { fail "mise not found"; return 1; } + mise up --bump || return 1 + $T mise lock 2>/dev/null || mise lock || return 1 + local ch; ch=$(gpath channels.scm) + if [ -f "$ch" ]; then + hdr "guix: channel pin" + if have guix; then + local pin + pin=$(guix describe --format=channels 2>/dev/null | guix_channel_commit) + if [ -z "$pin" ]; then + warn "could not read the current guix channel commit — $ch left unchanged" + elif repin_guix_channel "$ch" "$pin"; then + info "$ch: guix channel re-pinned to $pin" + else + warn "$ch has no (name 'guix) channel with a commit — left unchanged" + fi + else info "guix not installed — $ch left as-is (CI re-pins it)"; fi + fi + local cr="" + if [ -f Cargo.lock ] && grep -qs 'crates\.scm' "$(gpath guix.scm)"; then + hdr "guix: crate inputs from Cargo.lock" + cr=build/guix/crates.scm + if have "${GUIX%% *}"; then cmd_crates_scm || return 1 + else info "guix not installed — $cr left as-is (CI regenerates it)"; fi + fi + git --no-pager diff --stat -- mise.toml mise.lock "$ch" $cr 2>/dev/null + echo "Commit the diff above (signed) as: chore(toolchain): weekly refresh" +} + +# The guix command (default: guix), e.g. a wrapper that runs it in a container +# with this directory mounted. +GUIX="${GUIX:-guix}" + +# Write build/guix/crates.scm: every registry crate in Cargo.lock as a Guix +# origin, and %crate-inputs listing them for guix.scm. Written whole or not at +# all. Accept importer output when its rust- definition count matches the number +# of registry packages in Cargo.lock; the importer's exit status is not checked. +# GUIX may contain a command and arguments; import is limited to 1,800 seconds. +# Missing Cargo.lock is a successful no-op. Return 1 for temporary-file creation +# failure or a count mismatch; later write errors are not reliably propagated. +cmd_crates_scm() { + local dst=build/guix/crates.scm want got tmp spdx + [ -f Cargo.lock ] || { info "no Cargo.lock — no crate inputs"; return 0; } + want=$(grep -c '^source = "registry+' Cargo.lock) + tmp=$(mktemp) || return 1 + if [ "$want" -gt 0 ]; then + # GUIX is split on purpose: it may be a command with arguments. + # shellcheck disable=SC2086 + timeout 1800 $GUIX import crate --lockfile=Cargo.lock "$REPO_NAME" >"$tmp" 2>"$tmp.err" + got=$(grep -c '^(define rust-' "$tmp") + if [ "$got" != "$want" ]; then + fail "PV-E41 guix import crate defined $got of the $want registry crates in Cargo.lock; $dst left as-is: $(grep -m1 -i 'error' "$tmp.err" || grep -v '^+' "$tmp.err" | tail -1)" + rm -f "$tmp" "$tmp.err"; return 1 + fi + fi + # The licence line is guix.scm's own, so the file matches its repository. + spdx=$(grep -m1 'SPDX-License-Identifier' "$(gpath guix.scm)" 2>/dev/null) + mkdir -p build/guix + { + [ -n "$spdx" ] && printf '%s\n' "$spdx" + # shellcheck disable=SC2016 # the backticks are literal text + printf ';; Generated from Cargo.lock by `just toolchain-refresh` (guix import crate\n' + printf ';; --lockfile); never hand-edit it. guix.scm loads it for %%crate-inputs.\n\n' + grep -v '^guix (GNU Guix)' "$tmp" + printf '\n(define %%crate-inputs\n (list' + grep -o '^(define rust-[^ ]*' "$tmp" | awk '{printf "\n %s", $2}' + printf '))\n' + } >"$dst.new" && mv "$dst.new" "$dst" + rm -f "$tmp" "$tmp.err" + info "$dst: $want crate source(s)" +} + +# The sentence people are told to say lives in one place a reader sees: the first +# listing block of the README's [[ai-install]] section. The deed's ai-say-it and +# the generic line are fallbacks for a README without that section. +just_say_it() { + local line="" r + for r in README.adoc README.md; do + [ -f "$r" ] || continue + line=$(awk '/^\[\[ai-install\]\]/{on=1} on && /^----$/{if (inb) exit; inb=1; next} inb && NF{print; exit}' "$r") + [ -n "$line" ] && break + done + [ -z "$line" ] && line=$(deed ai-say-it "") + [ -z "$line" ] && line="Set up $REPO_NAME from https://github.com/$REPO_SLUG — follow docs/AI_INSTALLATION_GUIDE.adoc in that repo." + printf '%s' "$line" +} +# Copy stdin to an available clipboard with a three-second timeout; +# silently consume input and return 1 when no clipboard command is available. +# Otherwise return the timeout command's status; suppress clipboard output and errors. +clip() { # best-effort; silent when no clipboard exists (CI, SSH) + # wl-copy and xclip fork a daemon that inherits stdout; left attached, it + # holds any pipeline open forever (observed 2026-09-30). Detach and bound it. + local c=() + if have clip.exe; then c=(clip.exe) # WSL: the Windows clipboard + elif have pbcopy; then c=(pbcopy) + elif [ -n "${WAYLAND_DISPLAY:-}" ] && have wl-copy; then c=(wl-copy) + elif [ -n "${DISPLAY:-}" ] && have xclip; then c=(xclip -selection clipboard) + else cat >/dev/null; return 1; fi + timeout 3 "${c[@]}" >/dev/null 2>&1 +} +# Print AI-assisted setup instructions and attempt to copy the setup sentence. +# Clipboard failure is ignored. +cmd_ai_setup() { + cat <" >&2; return 2 ;; esac + for f in "$(wpath "$who")" "llm-warmup-$who.adoc" "docs/onboarding/llm-warmup-$who.adoc" "docs/llm-warmup-$who.adoc"; do + if [ -f "$f" ]; then + cat "$f"; clip < "$f" && echo "--- (copied $f to your clipboard — paste it as your first message to any AI)" >&2 || true + return 0 + fi + done + fail "llm-warmup-$who.adoc not found"; return 1 +} + +# Run test and bench recipes, saving output and timings under .eval/; (hypatia:ignore eval_in_shell -- directory name) +# report N/A for skipped work and return 1 if either recipe fails. +cmd_eval() { + local logf rc=0 s e v r o st + logf=".eval/$(date -u +%Y%m%dT%H%M%SZ).txt" # hypatia:ignore eval_in_shell -- .eval/ is a directory name + mkdir -p .eval # hypatia:ignore eval_in_shell -- .eval/ is a directory name + { echo "# $REPO_NAME evaluation — $(date -u +%FT%TZ) — $(git rev-parse --short HEAD 2>/dev/null || echo no-git)" + echo "# languages: ${LANGS[*]} archetype: $ARCHETYPE"; } > "$logf" + for v in test bench; do + # The root recipe if the repo defines one (its own override), else the module default. + if just --summary 2>/dev/null | tr " " "\n" | grep -qx "$v"; then r=$v; else r="provision::$v"; fi + s=$(date +%s); o=$(mktemp) + if just "$r" >"$o" 2>&1; then st=PASS; else st=FAIL; rc=1; fi + e=$(( $(date +%s) - s )); cat "$o" >>"$logf" + # A skip is not a pass: lang_run exits 0 on N/A (users see success), eval says N/A. (hypatia:ignore eval_in_shell -- verb name) + [ "$st" = PASS ] && grep -q "nothing was faked" "$o" && st=N/A + rm -f "$o"; echo "$v: $st (${e}s)" | tee -a "$logf" + done + echo "full log: $logf" + return $rc +} + +# Print resolved repository metadata and provisioning configuration paths. +cmd_config_show() { + echo "repo: $REPO_SLUG" + echo "archetype: $ARCHETYPE" + echo "languages: ${LANGS[*]}" + echo "descriptor: $DEED $([ -f "$DEED" ] && echo '(present)' || echo '(absent — defaults in use)')" + echo "config: $(deed config "none declared")" + echo "run: $(deed run "$(for l in "${LANGS[@]}"; do lang_cmd "$l" run; done | head -1)")" + echo "ports: $(deed ports "none")" + echo "mise: $([ -f mise.toml ] && echo mise.toml) $([ -f mise.lock ] && echo mise.lock)" + echo "guix: $(for f in guix.scm manifest.scm channels.scm; do f=$(gpath "$f"); [ -f "$f" ] && printf "%s " "$f"; done)" + echo "lib: provision-lib $PROVISION_LIB_VERSION" +} + +# Print repository-specific OPSM installation instructions. +cmd_opsm() { + cat <} + if have agrep; then git ls-files -z | xargs -0 agrep -n -1 -- "$p" 2>/dev/null + else git grep -n -i -- "$p"; fi +} + +case "${1:-}" in + guix-specs) guix_specs ;; + mise-tools) shift; mise_tools "$@" ;; + langs) printf '%s\n' "${LANGS[@]}" ;; + doctor) cmd_doctor ;; + setup) cmd_setup ;; + heal) cmd_heal ;; + dev-shell) cmd_dev_shell ;; + toolchain-refresh) cmd_toolchain_refresh ;; + crates-scm) cmd_crates_scm ;; + ai-setup) cmd_ai_setup ;; + ai-warmup) shift; cmd_ai_warmup "${1:-user}" ;; + eval) cmd_eval ;; # hypatia:ignore eval_in_shell -- the "eval" verb, not the builtin + config-show) cmd_config_show ;; + opsm) cmd_opsm ;; + search) shift; cmd_search "${1:-}" ;; + lang-run) shift; lang_run "${1:?verb}" ;; + version) echo "provision-lib $PROVISION_LIB_VERSION" ;; + guix-dir) guix_dir ;; + set-files) set_files ;; + guix-gaps) guix_gaps ;; + tool-table) tool_table ;; + system-deps) shift; system_deps "${1:-adoc}" ;; + # Predicates: print why, exit 1; print nothing, exit 0. + guix-stub) shift; r=$(guix_stub_reason "${1:?usage: guix-stub FILE}"); [ -z "$r" ] || { echo "$r"; exit 1; } ;; + mise-lock-gaps) r=$(mise_lock_gaps); [ -z "$r" ] || { echo "$r"; exit 1; } ;; + mise-banned) r=$(mise_banned); [ -z "$r" ] || { echo "$r"; exit 1; } ;; + *) sed -n '2,20p' "$0"; exit 2 ;; +esac diff --git a/build/just/provision-modes.sh b/build/just/provision-modes.sh new file mode 100755 index 00000000..eb9efa2f --- /dev/null +++ b/build/just/provision-modes.sh @@ -0,0 +1,169 @@ +# SPDX-License-Identifier: MPL-2.0 +# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) +# shellcheck shell=bash +# +# provision-modes.sh — the launcher-standard 0.6.0 provisioning mode family, +# as a SOURCEABLE block shared by every launcher in the estate. +# +# New launchers (library/tool/theory/docs): templates/launcher.sh.tmpl sources +# this and calls hp_launcher_main. +# Existing app launchers: add ONE line before their mode switch — +# +# . "$REPO_DIR/build/just/provision-modes.sh" && hp_provision_or_return "$@" +# +# A provisioning mode runs and the launcher exits with its status (a failed +# --setup exits non-zero); any other mode returns, so the app's own switch +# handles it. hp_provision_dispatch itself returns 99 for "not mine". +# +# Canon: hyperpolymath/standards launcher/launcher-standard_praxis.deed +# (archetypes, provisioning-modes) and +# 3-practice/provisioning/PROVISIONING-STANDARD.adoc + +HP_PROVISION_MODES_VERSION="0.6.0" + +# Print the flat deed value for key $1, falling back to default $2. +hp__deed() { # $1 key, $2 default — flat (key "value") read from provisioning_praxis.deed + local f="$REPO_DIR/.machine_readable/descriptiles/provisioning_praxis.deed" v="" + [ -f "$f" ] && v=$(grep -oE "[(:]$1[[:space:]]+\"[^\"]*\"" "$f" | head -1 | sed -E 's/^[^"]*"//; s/"$//') + printf '%s' "${v:-$2}" +} + +# Print the declared repository archetype, defaulting to library. +hp_archetype() { hp__deed archetype "library"; } +# Without a deed, the origin remote names the repo (a worktree or renamed clone +# has another directory name); the directory is the last resort. +hp_app_name() { + local u; u=$(git -C "$REPO_DIR" config --get remote.origin.url 2>/dev/null || true) + u=${u%.git}; u=${u##*/} + hp__deed name "${u:-$(basename "$REPO_DIR")}" +} + +# Print linux, macos, windows or unknown based on the host kernel name. +hp_platform() { + case "$(uname -s)" in + Linux*) echo linux ;; + Darwin*) echo macos ;; + CYGWIN*|MINGW*|MSYS*|Windows_NT) echo windows ;; + *) echo unknown ;; + esac +} + +# Make sure `just` is runnable: PATH, then mise, then say exactly what to do. +# May install just globally via mise, extend PATH or define a just wrapper. +# Return 0 when available, otherwise 1 after printing installation guidance. +hp_ensure_just() { + command -v just >/dev/null 2>&1 && return 0 + if command -v mise >/dev/null 2>&1; then + echo "just is not installed — installing it with mise (mise use -g just@latest)..." >&2 + mise use -g just@latest >&2 && PATH="$(mise bin-paths 2>/dev/null | paste -sd: -):$PATH" && command -v just >/dev/null 2>&1 && return 0 + mise exec just@latest -- true >/dev/null 2>&1 && { just() { mise exec just@latest -- just "$@"; }; return 0; } + fi + cat >&2 <<'EOF' +Neither `just` nor `mise` is installed. Install mise (it then installs everything else): + + brew install mise # macOS + sudo dnf copr enable jdxcode/mise && sudo dnf install mise # Fedora + winget install jdx.mise # Windows + # anything else (Debian/Ubuntu apt, …): https://mise.jdx.dev/installing-mise.html + # or download the installer, read it, then run it — never pipe it into a shell: + curl -fsSLo mise-install.sh https://mise.run && less mise-install.sh && sh mise-install.sh + +then re-run this command. Manual route without mise: docs/SETUP.adoc +EOF + return 1 +} + +# Ensure just is available, then run it with the supplied arguments in REPO_DIR. +hp_just() { hp_ensure_just || return 1; (cd "$REPO_DIR" && just "$@"); } +# The provisioning modes call the engine directly, not a `just` recipe: a repo may +# define its own root `doctor`/`setup`/`heal`, and the launcher must still run the +# canon (which then runs that repo's *-local recipes). Only needs bash. +hp_lib() { (cd "$REPO_DIR" && bash build/just/provision-lib.sh "$@"); } + +# The one-line hook for existing launchers: exit with a provisioning mode's +# status, or return (0) so the caller's own mode switch runs. +hp_provision_or_return() { + hp_provision_dispatch "$@" + local rc=$? + [ "$rc" -eq 99 ] && return 0 + exit "$rc" +} + +# Run the provisioning mode named by $1 and return its status; +# return 99 when the mode is not handled here. +hp_provision_dispatch() { + case "${1:-}" in + --setup) hp_lib setup ;; + --doctor) hp_lib doctor ;; + --heal) hp_lib heal ;; + --ai-setup) hp_lib ai-setup ;; + *) return 99 ;; + esac +} + +# Print the launcher name, version, commit, platform and architecture. +hp_version_line() { + local sha ver + sha=$(git -C "$REPO_DIR" rev-parse --short HEAD 2>/dev/null || echo unknown) + ver=$(hp__deed version "") + [ -z "$ver" ] && ver=$(git -C "$REPO_DIR" describe --tags --abbrev=0 2>/dev/null || echo 0.0.0) + printf '%s-launcher %s (%s) [%s-%s]\n' "$(hp_app_name)" "${ver#v}" "$sha" "$(hp_platform)" "$(uname -m)" +} + +# Print launcher usage and the modes applicable to the repository archetype. +hp_help() { + local name arch; name=$(hp_app_name); arch=$(hp_archetype) + cat < + +Provisioning (every repository): + --setup Install everything this repository needs, then run --doctor + --doctor Check the environment; PASS/WARN/FAIL with fix hints (exit 1 on FAIL) + --heal Apply safe fixes automatically, then re-run --doctor + --ai-setup Print the one line to give any AI assistant to set this up for you + +Meta: + --help This text + --version Machine-readable version line + +EOF + if [ "$arch" = app ]; then + echo "Runtime: --start --stop --status --auto (default) --integ --disinteg" + else + echo "Runtime modes (--start --stop --status --auto --integ --disinteg) do not apply" + echo "to a $arch repository; they are accepted and explain themselves." + fi + cat <&2 + return 1 + fi + echo "$(hp_app_name) is a $arch: there is nothing to ${mode#--}. Try --setup, --doctor or --help." + return 0 ;; + *) + echo "Unknown mode: $mode" >&2; hp_help >&2; return 2 ;; + esac +} diff --git a/build/just/provision.just b/build/just/provision.just new file mode 100644 index 00000000..9f1ac7c4 --- /dev/null +++ b/build/just/provision.just @@ -0,0 +1,108 @@ +# SPDX-License-Identifier: MPL-2.0 +# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# provision.just — the estate provisioning contract, as a just MODULE. +# +# Canon: hyperpolymath/standards 3-practice/provisioning/PROVISIONING-STANDARD.adoc +# Loaded from the root Justfile with: +# +# mod provision 'build/just/provision.just' +# +# A module (not `import`) so these recipes live under `provision::` and never +# collide with a repo's own `doctor`, `heal` or `test`. The root Justfile then +# exposes each contract name ONCE — either its own recipe, or a one-line +# delegation such as `doctor: provision::doctor` that `provision-set mint` +# adds only when the root has no recipe of that name. +# +# requires: just >= 1.42.0 (root recipes depend on module recipes; measured 2026-09-30: 1.41 rejects `x: m::x`, 1.42 accepts) + +root := justfile_directory() +lib := "PROVISION_ROOT=" + quote(root) + " bash " + quote(source_directory() / "provision-lib.sh") + +# List the provisioning recipes +default: + @just --list provision + +# Install every tool and dependency this repo needs, then run doctor +setup: + @{{lib}} setup + +# Diagnose the environment: PASS/WARN/FAIL with codes; exits 1 on any FAIL +doctor: + @{{lib}} doctor + +# Apply safe, reversible fixes, then re-run doctor +heal: + @{{lib}} heal + +# Enter a shell with every tool on PATH (guix shell -m manifest.scm, else mise) +dev-shell: + @{{lib}} dev-shell + +# Weekly: bump mise 'latest' resolutions, re-lock, re-pin guix channels +toolchain-refresh: + @{{lib}} toolchain-refresh + +# Print (and copy) the one line to give any AI to install this repo +ai-setup: + @{{lib}} ai-setup + +# Print (and copy) the warm-up for an AI session: user, dev or maintainer +ai-warmup who="user": + @{{lib}} ai-warmup {{quote(who)}} + +# Run test + bench, time both, and write .eval/.txt +eval: + @{{lib}} eval + +# Show where this repo's configuration and toolchain are declared +config-show: + @{{lib}} config-show + +# How to install this repo with OPSM (odds-and-sods package manager) +opsm: + @{{lib}} opsm + +# Print the languages detected from marker files +langs: + @{{lib}} langs + +# Approximate search across tracked files (agrep, else git grep) +search pattern: + @{{lib}} search {{quote(pattern)}} + +# Per-language defaults for the contract verbs, reached as `just provision::` +# or through a root recipe that delegates (`build: provision::build`). A root +# recipe with its own body is the repo-specific override. + +# Build with every detected language's toolchain +build: + @{{lib}} lang-run build + +# Run every detected language's tests +test: + @{{lib}} lang-run test + +# Run every detected language's benchmarks +bench: + @{{lib}} lang-run bench + +# Lint every detected language +lint: + @{{lib}} lang-run lint + +# Format every detected language's sources +fmt: + @{{lib}} lang-run fmt + +# Check formatting without rewriting anything (the CI form of fmt) +fmt-check: + @{{lib}} lang-run fmt-check + +# Run the project (N/A for libraries) +run: + @{{lib}} lang-run run + +# Fetch every detected language's dependencies +deps: + @{{lib}} lang-run deps diff --git a/build/just/repo-init.just b/build/just/repo-init.just index ab121908..59c5db2e 100644 --- a/build/just/repo-init.just +++ b/build/just/repo-init.just @@ -14,12 +14,124 @@ repo-init archetype="": #!/usr/bin/env bash set -euo pipefail - # Non-interactive support: if RSR_NON_INTERACTIVE is set, dummy-out 'read'. - # This prevents blocking on input and seamlessly uses environment variables. - if [ -n "${RSR_NON_INTERACTIVE:-}" ]; then - read() { return 0; } + # ask PROMPT VAR — every prompt below goes through this, never through a + # bare `read`. Interactive: read VAR from the terminal. Non-interactive + # (RSR_NON_INTERACTIVE set, the scaffoldia / CI path): touch no stdin and + # keep VAR's value from the environment, or empty when it has none. + # + # This replaced `read() { return 0; }`, which shadowed the builtin for the + # WHOLE recipe. Measured 2026-10-14 minting resource-algebra: + # * a prompt the environment did not answer left its variable unset, so + # `set -u` killed the mint at OPENSSF_BP_ID, after docs/ had already + # been overwritten by the seed; + # * every `while read -r` loop below inherited the no-op, which succeeds + # without reading, so the substitution pass spun forever on an unbound + # `file`. + # The non-interactive mint could therefore never complete, and the e2e test + # drove only the interactive path, so nothing noticed. + ask() { + if [ -n "${RSR_NON_INTERACTIVE:-}" ]; then + printf -v "$2" '%s' "${!2:-}" + else + read -rp "$1" "$2" + fi + } + + # The mint edits only what belongs to the repository, so it needs git to + # say what that is (see mint_files below). Checked first: nothing is + # asked, fetched or written for a tree that cannot be minted. + if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then + echo "Error: repo-init must run inside a git work tree (run 'git init' first)." + exit 1 fi + # --- The template's own identity --------------------------------------- + # repo-init is carried into every minted repo UNCHANGED (it is listed in + # .machine_readable/mint-verbatim.txt: it is the generator, not generated + # content), so it cannot assume it is running in rsr-template-repo. By the + # second generation the deed on disk is _chora.deed, the literal to + # rewrite is , and the provenance parent is /. + # Hardcoding the original template made a mint from a minted repo rename + # nothing, rewrite nothing, and abort at the identity step. Measured on + # metadatastician/lintel 2026-10-19; first fixed there in lintel#9 (not + # merged), ported here, where the generator lives. + # + # Derived, never asked: these are facts about the checkout, not choices. + # The root Justfile comes first because its OWNER/REPO lines are also the + # literals written through the tree, so they are exactly what the rewrite + # has to match, and they are still the TEMPLATE's in a repository created + # with "Use this template" (whose git remote is already the child's). The + # remote is second, for a Justfile that no longer declares them. The + # original template is last, so a bare export still mints something valid. + TEMPLATE_OWNER="" + TEMPLATE_REPO="" + if [ -f Justfile ]; then + TEMPLATE_REPO="$(sed -n -E 's/^REPO[[:space:]]*:=[[:space:]]*"([^"]+)".*/\1/p' Justfile | head -1)" + TEMPLATE_OWNER="$(sed -n -E 's/^OWNER[[:space:]]*:=[[:space:]]*"([^"]+)".*/\1/p' Justfile | head -1)" + fi + if [ -z "$TEMPLATE_REPO" ] || [ -z "$TEMPLATE_OWNER" ]; then + _origin="$(git config --get remote.origin.url 2>/dev/null || true)" + if [ -n "$_origin" ]; then + _origin="${_origin%.git}" + _origin="${_origin%/}" + [ -n "$TEMPLATE_REPO" ] || TEMPLATE_REPO="${_origin##*[/:]}" + _origin="${_origin%/*}" + [ -n "$TEMPLATE_OWNER" ] || TEMPLATE_OWNER="${_origin##*[/:]}" + fi + fi + TEMPLATE_REPO="${TEMPLATE_REPO:-rsr-template-repo}" + TEMPLATE_OWNER="${TEMPLATE_OWNER:-hyperpolymath}" + TEMPLATE_SLUG="${TEMPLATE_OWNER}/${TEMPLATE_REPO}" + + # --- What the mint may edit --------------------------------------------- + # mint_files prints, one per line, every regular file that belongs to the + # repository: tracked, or untracked and not ignored (what `git add -A` + # would commit), minus the files .machine_readable/mint-verbatim.txt says + # the mint carries unchanged. Every rewrite pass and every completeness + # check below reads this list, and nothing else. + # + # The passes used to `find .` the whole directory. That walked git-ignored + # caches: minting lintel, the instruction-block pass edited the pinned + # sibling checkouts under _build/dependencies/, which broke those pins. It + # also rewrote template machinery whose fixtures must keep the template's + # literal name, so tests/workflows/self_name_pass_test.sh failed in the + # child, and stripped the very fixture blocks the leftover check below + # exempts. "Untracked and not ignored" is included so that a copy which + # was never committed (tests/e2e/template_instantiation_test.sh) still + # mints; in a repository created from the template every file is tracked. + # + # Paths are printed relative and without "./"; symlinks are skipped, as + # `find -type f` skipped them. + VERBATIM_LIST=".machine_readable/mint-verbatim.txt" + [ -f "$VERBATIM_LIST" ] || { echo "Error: $VERBATIM_LIST is missing; the mint cannot tell machinery from content."; exit 1; } + mapfile -t MINT_VERBATIM < <(sed -e 's/#.*//' -e 's/[[:space:]]*$//' "$VERBATIM_LIST" | grep -v '^$') + for _v in "${MINT_VERBATIM[@]}"; do + [ -f "$_v" ] || { echo "Error: $VERBATIM_LIST names $_v, which does not exist (stale entry)."; exit 1; } + done + + # ── Can the template be minted at all? ────────────────────────────────── + # A brace token the recipe below has no answer for is a file that cannot be + # minted: it either survives into the child as a literal (measured: five + # files in every Julia repo minted before 2026-10-30) or trips the + # placeholder gate at the END of a mint that has already written the tree. + # Both are cheaper to refuse here, before a single byte is written. + if [ -f scripts/check-mint-tokens.sh ]; then + if ! bash scripts/check-mint-tokens.sh; then + echo "ERROR: mint aborted before writing anything — the template ships a" + echo " token this recipe cannot fill. See the findings above." + exit 1 + fi + fi + mint_files() { + git ls-files -z --cached --others --exclude-standard \ + | while IFS= read -r -d '' _f; do + [ -f "$_f" ] && [ ! -L "$_f" ] || continue + printf '%s\n' "$_f" + done \ + | grep -vxF -f <(printf '%s\n' "${MINT_VERBATIM[@]}") \ + | sort -u || true + } + echo "═══════════════════════════════════════════════════" echo " RSR Project Bootstrap" echo "═══════════════════════════════════════════════════" @@ -30,13 +142,13 @@ repo-init archetype="": ARCH_FILE="" ARCH_PRESET="" if [ -n "$ARCHETYPE" ]; then - ARCH_FILE="archetypes/${ARCHETYPE}/ARCHETYPE.a2ml" + ARCH_FILE="archetypes/${ARCHETYPE}/${ARCHETYPE}_praxis.deed" if [ ! -f "$ARCH_FILE" ]; then echo "Error: unknown archetype '${ARCHETYPE}'. Available:" ls -1 archetypes 2>/dev/null | grep -v 'README' || echo " (none)" exit 1 fi - ARCH_PRESET=$(sed -n 's/^preset = "\(.*\)"$/\1/p' "$ARCH_FILE" | head -1) + ARCH_PRESET=$(bash scripts/deed-field.sh "$ARCH_FILE" capability preset || true) echo "Archetype: ${ARCHETYPE}${ARCH_PRESET:+ (capability preset: $ARCH_PRESET)}" echo "" fi @@ -44,6 +156,7 @@ repo-init archetype="": # --- Load defaults from config (if exists) --- # Create yours: ~/.config/rsr/defaults # Format: OWNER=myorg AUTHOR="My Name" AUTHOR_EMAIL=me@example.org ... + # AUTHOR_ORCID=0000-0002-1825-0097 (optional) DEFAULTS="${XDG_CONFIG_HOME:-$HOME/.config}/rsr/defaults" if [ -f "$DEFAULTS" ]; then echo "Loading defaults from $DEFAULTS" @@ -53,73 +166,114 @@ repo-init archetype="": fi # --- Required values (pre-filled from defaults if available) --- - read -rp "Project name (human-readable, e.g. My Project): " PROJECT_NAME + ask "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 + ask "Repository slug (e.g. my-project): " REPO [ -z "$REPO" ] && echo "Error: repo slug required" && exit 1 - if [[ ! "$REPO" =~ ^[a-z0-9]+(-[a-z0-9]+)*$ ]]; then + # A Julia package repo is named after its package: `.jl`, where + # is the package's own identifier (UpperCamelCase by Julia + # convention). The julia-library archetype accepts that form as well as + # the estate slug; every other mint takes the estate slug only. + if [[ "$ARCHETYPE" = "julia-library" && "$REPO" =~ ^[A-Z][A-Za-z0-9]*\.jl$ ]]; then + : + elif [[ ! "$REPO" =~ ^[a-z0-9]+(-[a-z0-9]+)*$ ]]; then echo "Error: repo slug must be lowercase alphanumeric words separated by single hyphens" + [ "$ARCHETYPE" = "julia-library" ] && echo " (or, for a Julia package, .jl with in UpperCamelCase)" exit 1 fi - read -rp "Owner [${OWNER:-}]: " _OWNER + ask "Owner [${OWNER:-}]: " _OWNER OWNER="${_OWNER:-${OWNER:-}}" [ -z "$OWNER" ] && echo "Error: owner required" && exit 1 - read -rp "Author full name [${AUTHOR:-}]: " _AUTHOR + ask "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 + ask "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 + ask "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 + ask "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 + # ORCID iD for CITATION.cff. Defaults from AUTHOR_ORCID in the defaults + # file, then `git config user.orcid`, so an author sets it once: + # git config --global user.orcid 0000-0002-1825-0097 + # Blank drops the orcid line below. An all-zeros placeholder is worse than + # no line: citation tools resolve it and attribute the work to nobody. + AUTHOR_ORCID="${AUTHOR_ORCID:-$(git config --get user.orcid 2>/dev/null || true)}" + ask "Author ORCID iD [${AUTHOR_ORCID:-none}]: " _AUTHOR_ORCID + AUTHOR_ORCID="${_AUTHOR_ORCID:-${AUTHOR_ORCID:-}}" + AUTHOR_ORCID="${AUTHOR_ORCID#http*://orcid.org/}" + if [ -n "$AUTHOR_ORCID" ]; then + if [[ ! "$AUTHOR_ORCID" =~ ^[0-9]{4}-[0-9]{4}-[0-9]{4}-[0-9]{3}[0-9X]$ ]]; then + echo "Error: ORCID iD must look like 0000-0002-1825-0097 (got '${AUTHOR_ORCID}')" + exit 1 + fi + # ISO 7064 MOD 11-2 check digit, as ORCID specifies: a transposed + # digit is a valid-looking iD that belongs to someone else. + _orcid_digits="${AUTHOR_ORCID//-/}" + _orcid_total=0 + for ((i = 0; i < 15; i++)); do + _orcid_total=$(( (_orcid_total + ${_orcid_digits:i:1}) * 2 )) + done + _orcid_check=$(( (12 - _orcid_total % 11) % 11 )) + [ "$_orcid_check" = 10 ] && _orcid_check=X + if [ "$_orcid_check" != "${_orcid_digits:15:1}" ]; then + echo "Error: ORCID iD ${AUTHOR_ORCID} fails its check digit (expected ${_orcid_check})" + exit 1 + fi + fi + + ask "Project description []: " PROJECT_DESCRIPTION - read -rp "Forge domain [${FORGE:-github.com}]: " _FORGE + ask "Forge domain [${FORGE:-github.com}]: " _FORGE FORGE="${_FORGE:-${FORGE:-github.com}}" - read -rp "Security contact email [${SECURITY_EMAIL:-$AUTHOR_EMAIL}]: " _SECURITY_EMAIL + ask "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 + ask "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 + ask "Project type (library|binary|monorepo|service|website) [library]: " PROJECT_TYPE PROJECT_TYPE="${PROJECT_TYPE:-library}" - read -rp "Website URL [https://${FORGE}/${OWNER}/${REPO}]: " WEBSITE + ask "Website URL [https://${FORGE}/${OWNER}/${REPO}]: " WEBSITE WEBSITE="${WEBSITE:-https://${FORGE}/${OWNER}/${REPO}}" - read -rp "OpenSSF Best Practices project ID (blank if not yet registered) []: " OPENSSF_BP_ID + ask "OpenSSF Best Practices project ID (blank if not yet registered) []: " OPENSSF_BP_ID # --- Container values (optional — only relevant if build/container/ exists) --- + # The default service name is the slug in lower case: an OCI image name + # may not contain capitals, and a Julia slug (`.jl`) has them. if [ -d "build/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}}" + ask "Service name [${SERVICE_NAME:-${REPO,,}}]: " _SERVICE_NAME + SERVICE_NAME="${_SERVICE_NAME:-${SERVICE_NAME:-${REPO,,}}}" + ask "Primary port [${PORT:-8080}]: " _PORT + PORT="${_PORT:-${PORT:-8080}}" + ask "Container registry [${REGISTRY:-ghcr.io/${OWNER}}]: " _REGISTRY + REGISTRY="${_REGISTRY:-${REGISTRY:-ghcr.io/${OWNER}}}" else - SERVICE_NAME="${REPO}" - PORT="8080" - REGISTRY="ghcr.io/${OWNER}" + SERVICE_NAME="${SERVICE_NAME:-${REPO,,}}" + PORT="${PORT:-8080}" + REGISTRY="${REGISTRY:-ghcr.io/${OWNER}}" fi # --- Derived values --- - PROJECT_UPPER=$(echo "$REPO" | tr '[:lower:]-' '[:upper:]_') - PROJECT_LOWER=$(echo "$REPO" | tr '[:upper:]-' '[:lower:]_') + # The PROJECT and project tokens land in identifiers (Zig, Idris, C macros), + # so every character an identifier cannot hold maps to an underscore: the + # hyphens of a slug and the dot of a Julia slug alike. + 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" @@ -154,21 +308,97 @@ repo-init archetype="": echo " Owner: $OWNER" echo " Author: $AUTHOR <$AUTHOR_EMAIL>" [ -n "$AUTHOR_ORG" ] && echo " Organization: $AUTHOR_ORG" + [ -n "$AUTHOR_ORCID" ] && echo " ORCID: $AUTHOR_ORCID" echo " Forge: $FORGE" echo " Year: $CURRENT_YEAR" echo "────────────────────────────────────────────────" echo "" - read -rp "Proceed? [Y/n] " CONFIRM + ask "Proceed? [Y/n] " CONFIRM [[ "${CONFIRM:-Y}" =~ ^[Nn] ]] && echo "Aborted." && exit 0 + # Template-only paths this recipe deletes, as they stand before it runs. + # Recorded in the (variant) clause's (paths :removed …) below, so the + # record says what the mint took away instead of leaving the drift gate to + # report each file as an undeclared removal (18 lines on a fresh mint). + MINT_REMOVES=() + for _d in archetypes build/docs-seed build/templates; do + [ -d "$_d" ] && MINT_REMOVES+=("$_d/") + done + + # --- Which template commit is in hand (provenance) --------------------- + # Resolved BEFORE anything is written, so an unresolvable parent stops the + # mint with the tree untouched instead of half-minted. The child's own HEAD + # is never recorded as the template's: in a repository created with "Use + # this template" it is a commit of the child (lintel recorded its own + # claude/mint-lintel tip, 2026-10-14). scripts/resolve-template-pin.sh owns + # the rule and says why; tests/workflows/resolve_template_pin_test.sh + # holds its controls. + # RSR_TEMPLATE_URL read the template's history from here instead + # RSR_TEMPLATE_COMMIT assert the template commit (verified to exist) + # RSR_ALLOW_UNPINNED=1 record UNASSIGNED instead of aborting (offline) + PIN_ARGS=(--slug "$TEMPLATE_SLUG") + [ -z "${RSR_TEMPLATE_URL:-}" ] || PIN_ARGS+=(--url "$RSR_TEMPLATE_URL") + [ -z "${RSR_TEMPLATE_COMMIT:-}" ] || PIN_ARGS+=(--commit "$RSR_TEMPLATE_COMMIT") + if PIN_OUT="$(bash scripts/resolve-template-pin.sh "${PIN_ARGS[@]}")"; then + PARENT_BRANCH="$(sed -n 's/^branch=//p' <<<"$PIN_OUT")" + PARENT_PIN="$(sed -n 's/^commit=//p' <<<"$PIN_OUT")" + PARENT_TREE="$(sed -n 's/^tree=//p' <<<"$PIN_OUT")" + echo "Template: ${TEMPLATE_SLUG}@${PARENT_PIN:0:12} ($(sed -n 's/^source=//p' <<<"$PIN_OUT"))" + elif [ "${RSR_ALLOW_UNPINNED:-0}" = "1" ]; then + PARENT_BRANCH=UNASSIGNED PARENT_PIN=UNASSIGNED PARENT_TREE=UNASSIGNED + echo "WARNING: template commit UNASSIGNED (RSR_ALLOW_UNPINNED=1)." + echo " scripts/check-template-conformance.sh fails until it is filled." + else + echo "ERROR: mint aborted before writing anything — the template commit this" + echo " tree came from cannot be named (reason above). Re-run with" + echo " RSR_ALLOW_UNPINNED=1 only if an unpinned mint is genuinely wanted." + exit 1 + fi + echo "" echo "Replacing placeholders..." # Apply archetype overlay files (if any) BEFORE substitution, so overlay # files are rendered along with the rest of the tree. + # + # The overlay's file list is recorded first: the .in rename below must touch + # ONLY the files this archetype added. The spine ships .in templates of its + # own (build/templates/, the k9 examples) whose .in suffix is meaningful and + # must survive, and a blanket `find . -name '*.in' -exec mv` would rename + # them into broken files. + OVERLAY_FILES=() if [ -n "$ARCHETYPE" ] && [ -d "archetypes/${ARCHETYPE}/overlay" ]; then + mapfile -t OVERLAY_FILES < <( + cd "archetypes/${ARCHETYPE}/overlay" && find . -type f ! -name '*.orig' \ + | sed 's|^\./||' | sort + ) cp -a "archetypes/${ARCHETYPE}/overlay/." . - echo " applied overlay: archetypes/${ARCHETYPE}/overlay/" + echo " applied overlay: archetypes/${ARCHETYPE}/overlay/ (${#OVERLAY_FILES[@]} file(s))" + fi + + # An archetype's workflows bring their lock records as a fragment beside + # the overlay, never as an overlay file: an overlay actions.lock REPLACES + # the spine's lock, and every spine workflow then dies at startup with no + # record. Merge the fragment in; a conflicting record stops the mint. + if [ -n "$ARCHETYPE" ] && [ -f "archetypes/${ARCHETYPE}/actions.lock" ]; then + bash scripts/rust-tool.sh merge-actions-lock \ + .github/workflows/actions.lock "archetypes/${ARCHETYPE}/actions.lock" + fi + + # ── Archetype prune (ADR-0003) ─────────────────────────────────────────── + # The spine is polyglot on purpose: it carries the container module and the + # dev container so that SOME child can use them. A child carrying a module + # whose capability its preset does not declare is drift, and one of those + # modules is not harmless: `build/container/` is a DEPLOYED artifact, so a + # Julia package shipped it and failed `container-images-pinned` from birth + # over a container it does not need. The archetype says what it drops in + # archetypes//prune.txt; the removals are recorded in the child's + # (variant (paths :removed …)) so the drift gate does not report them. + if [ -n "$ARCHETYPE" ] && [ -f "archetypes/${ARCHETYPE}/prune.txt" ]; then + while IFS= read -r _pruned; do + [ -n "$_pruned" ] && MINT_REMOVES+=("$_pruned") + done < <(bash scripts/prune-archetype-modules.sh "archetypes/${ARCHETYPE}" .) + echo " pruned: archetypes/${ARCHETYPE}/prune.txt applied" fi # Seed docs/ from the documentation seed, BEFORE substitution so the seed's @@ -234,6 +464,7 @@ repo-init archetype="": -e "s|${LB}DESCRIPTION${RB}|${PROJECT_DESCRIPTION}|g" ) [ -n "$AUTHOR_EMAIL_ALT" ] && SED_ARGS+=(-e "s|${LB}AUTHOR_EMAIL_ALT${RB}|${AUTHOR_EMAIL_ALT}|g") + [ -n "$AUTHOR_ORCID" ] && SED_ARGS+=(-e "s|${LB}AUTHOR_ORCID${RB}|${AUTHOR_ORCID}|g") [ -n "$OPENSSF_BP_ID" ] && SED_ARGS+=(-e "s|${LB}OPENSSF_BP_ID${RB}|${OPENSSF_BP_ID}|g") [ -n "$OPENSSF_BP_ID" ] && SED_ARGS+=(-e "s|${LB}OPENSSF_PROJECT_ID${RB}|${OPENSSF_BP_ID}|g") @@ -242,21 +473,23 @@ repo-init archetype="": # below — sed applies expressions in order, so a token the archetype # answers never reaches the fallback, and one it omits still fails loudly. if [ -n "$ARCH_FILE" ]; then - while IFS= read -r arch_line; do - arch_tok="${arch_line%%=*}"; arch_tok="${arch_tok// /}" - arch_val=$(printf '%s' "$arch_line" | sed -n 's/^[^=]*= *"\(.*\)" *$/\1/p') + # The archetype's (tokens) clause: every :KEY "value" pair, read through + # deed-field.sh so string escapes are decoded by the one reader. + while IFS= read -r arch_tok; do + arch_val=$(bash scripts/deed-field.sh "$ARCH_FILE" tokens "$arch_tok" || true) { [ -n "$arch_tok" ] && [ -n "$arch_val" ]; } || continue case "$arch_val" in *'|'*) echo "WARN: archetype token $arch_tok contains '|' (the sed delimiter) — skipped, stays UNASSIGNED" continue ;; esac SED_ARGS+=(-e "s|${LB}${arch_tok}${RB}|${arch_val}|g") - done < <(awk '$0=="[tokens]"{f=1;next} /^\[/{f=0} f && !/^[[:space:]]*#/ && NF' "$ARCH_FILE") + done < <(bash scripts/deed-field.sh --clause "$ARCH_FILE" tokens \ + | awk 'prev ~ /^A:/ && /^S/ { print substr(prev, 3) } { prev = $0 }') fi # Tokens only the author can answer. init cannot know a project's unique # strength or its language stack, and guessing would write fiction into - # ANCHOR.a2ml — the file the estate treats as semantic authority. They + # the deed's (anchor) clause — the estate's semantic authority. They # become UNASSIGNED, the same marker `just repo-init` already writes for an # unchosen clade: honest, greppable, and obviously unfinished, whereas a # leftover brace token just looks like the template broke. @@ -269,18 +502,32 @@ repo-init archetype="": SED_ARGS+=(-e "s|${LB}${tok}${RB}|UNASSIGNED|g") done - # julia-library archetype: derive the package uuid at mint (owner ruling - # 2026-09-19: generate at mint). Same DERIVABLE class as the REPO uuid - # above - computed, never guessed. Namespace = the repo's own derived - # uuid, name = julia:: stable across re-mints of the same repo, - # never collides with the repo uuid. No uuidgen AND no python3 on the - # operator machine -> UNASSIGNED (the honest fallback at :437); Pkg - # then refuses the package loudly until the owner assigns one. + # julia-library archetype: mint the package uuid as UUIDv8 profile C + # (ADR-008 amendment: the strict UUIDv8 gate rejects the UUIDv5 mint, + # and D320 requires unregistered packages at v8). Profile C is + # DETERMINISTIC: bytes 0..15 of SHA-256("julia-package-identity" ":" + # "github.com//"), version nibble 8, variant 10 -- stable + # across re-mints of the same repo, derivable by any operator machine + # with python3 (or bun over standards' scripts/uuid-v8.js), never + # colliding with the repo uuid. The domain is REGISTERED in standards' + # ADR-008-profile-c-domains.json. No python3 and no bun -> UNASSIGNED + # (the honest fallback at :437); Pkg then refuses the package loudly + # until the owner assigns one. if [ "$ARCHETYPE" = "julia-library" ]; then - if command -v uuidgen >/dev/null 2>&1; then - PACKAGE_UUID=$(uuidgen --sha1 --namespace "${REPO_UUID}" --name "julia:${REPO}") + # GitHub owner logins are case-insensitive; canonicalize to lowercase + # before the preimage so owner casing cannot fork the UUID. + OWNER_LC=$(printf '%s' "${OWNER}" | tr '[:upper:]' '[:lower:]') + if command -v bun >/dev/null 2>&1 && [ -f "${STANDARDS_UUID_V8_JS:-}" ]; then + PACKAGE_UUID=$(bun "${STANDARDS_UUID_V8_JS}" c julia-package-identity "github.com/${OWNER_LC}/${REPO}") elif command -v python3 >/dev/null 2>&1; then - PACKAGE_UUID=$(python3 -c "import uuid; print(uuid.uuid5(uuid.UUID('${REPO_UUID}'), 'julia:${REPO}'))") + PACKAGE_UUID=$(python3 -c ' + import hashlib, sys + pre = ("julia-package-identity:github.com/%s/%s" % (sys.argv[1], sys.argv[2])).encode() + b = bytearray(hashlib.sha256(pre).digest()[:16]) + b[6] = (b[6] & 0x0F) | 0x80 # version 8 + b[8] = (b[8] & 0x3F) | 0x80 # variant 10 + h = b.hex() + print(f"{h[0:8]}-{h[8:12]}-{h[12:16]}-{h[16:20]}-{h[20:32]}")' "${OWNER_LC}" "${REPO}") else PACKAGE_UUID=UNASSIGNED fi @@ -294,9 +541,21 @@ repo-init archetype="": # in the new repo's README, and it trips the placeholder gate on every # subsequent push, which trains people to ignore a red CI. No id yet means # no badge yet; add it when you register at bestpractices.dev. + # + # Line deletion is only safe where the line is the whole construct. It + # used to run on docs/governance/TEMPLATE-STANDARDS-AUDIT.adoc too, where + # the token's line is one CELL of a six-column table row: deleting it + # left an incomplete row, asciidoctor reported "dropping cells from + # incomplete row", and Estate Rules' render gate failed in every child + # minted without an OpenSSF id (measured 2026-10-14 on resource-algebra). + # That document names the README's tokens rather than using them, so it + # now spells them as plain names and needs no pass here. if [ -z "$OPENSSF_BP_ID" ]; then sed -i "/bestpractices\.dev\/projects\/${LB}OPENSSF_BP_ID${RB}/d" README.adoc 2>/dev/null || true - sed -i "/${LB}OPENSSF_PROJECT_ID${RB}/d" docs/governance/TEMPLATE-STANDARDS-AUDIT.adoc 2>/dev/null || true + fi + # Same rule for the ORCID iD: CFF makes `orcid` optional, a wrong one is not. + if [ -z "$AUTHOR_ORCID" ]; then + sed -i "/orcid\.org\/${LB}AUTHOR_ORCID${RB}/d" CITATION.cff 2>/dev/null || true fi # A .mailmap exists to map an alternate address onto the canonical one. # With no alternate address there is nothing to map, and the sole entry @@ -310,21 +569,45 @@ repo-init archetype="": fi # 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 + # + # Skip just files too. In a Justfile or *.just module, double braces are + # just's OWN interpolation syntax, never a template token: every one in + # the template is a just variable or parameter. The lowercase project + # token is spelled exactly like just's interpolation of the `project` + # variable, so this pass used to freeze it into the identifier form. + # Measured 2026-10-14 minting resource-algebra: 7 Justfile lines, the + # contractile Justfile copy and container.just's image tag all became the + # literal `resource_algebra` instead of following `project := + # "resource-algebra"` (docs/man/resource_algebra.1, an image tagged with + # the underscored name). The self-name pass below still rewrites the + # template literal in these files; that is the edit they actually need. + # Return success when $1 is classified as text, using a byte-content probe + # (which accepts empty files) when the file command is unavailable. + is_text_file() { + if command -v file >/dev/null 2>&1; then + file --brief "$1" | grep -qi 'text\|ascii\|utf' + else + [ ! -s "$1" ] || LC_ALL=C grep -Iq . "$1" + fi + } + + mint_files | while IFS= read -r file; do + case "${file##*/}" in + MPL-2.0.txt|Justfile|*.just|*.png|*.jpg|*.gif|*.woff|*.woff2) continue ;; + esac + if is_text_file "$file"; then sed -i "${SED_ARGS[@]}" "$file" fi done - # Also replace [YOUR-REPO-NAME] and [YOUR-NAME/ORG] in the repo deed - # (the family-7 allocation manifest folded into it — standards#837 pilot). - sed -i "s|\[YOUR-REPO-NAME\]|${PROJECT_NAME}|g" rsr-template-repo_chora.deed 2>/dev/null || true - sed -i "s|\[YOUR-NAME/ORG\]|${OWNER}|g" rsr-template-repo_chora.deed 2>/dev/null || true + # [YOUR-REPO-NAME] and [YOUR-NAME/ORG] (the family-7 allocation manifest + # folded into the deed — standards#837 pilot) are replaced in the deed, + # found by its shape rather than by the original template's file name: in + # a repository minted from a minted one it is _chora.deed, and the + # two seds that named rsr-template-repo_chora.deed silently no-opped there. + DEED_IN="$(bash scripts/deed-field.sh --find .)" \ + || { echo "Error: the tree must carry exactly one *_chora.deed at its root."; exit 1; } + sed -i -e "s|\[YOUR-REPO-NAME\]|${PROJECT_NAME}|g" -e "s|\[YOUR-NAME/ORG\]|${OWNER}|g" "$DEED_IN" # --- Instruction-block pass -------------------------------------------- # Delete the "TEMPLATE INSTRUCTIONS (delete this block before publishing)" @@ -342,7 +625,7 @@ repo-init archetype="": if [ "$REPO" != "${REPO%-template-repo}" ]; then echo " instruction blocks: skipped (this IS a template repo)" else - bash scripts/rust-tool.sh strip-instruction-blocks . + mint_files | bash scripts/rust-tool.sh strip-instruction-blocks - fi # --- Dependabot ecosystem pass ----------------------------------------- @@ -366,10 +649,10 @@ repo-init archetype="": # Justfile: project := "rsr-template-repo" # Justfile: REPO := "rsr-template-repo" # sonar-project.properties sonar.projectKey=hyperpolymath_rsr-template-repo - # STATE.a2ml / ECOSYSTEM.a2ml project = "rsr-template-repo" + # the deed's (status) / (ecosystem) project = "rsr-template-repo" # i.e. it declared that it WAS the template, and would have reported its # code analysis into the TEMPLATE's SonarCloud project. This is the same - # failure the CLADE.a2ml block below fixes for the uuid/canonical-name; + # failure the repo-identity splice below fixes for the uuid/canonical-name; # nothing generalised it to the rest of the tree. Confirmed in the wild: # hyperpolymath/cargo-zigbuild still carries both Justfile lines. # @@ -378,287 +661,357 @@ repo-init archetype="": # (ADRs, its changelog, its own audit, and this recipe itself — which # holds PARENT_SLUG) are skipped wholesale, and within every other file # any line that names the parent AS a parent is left byte-for-byte alone. - if [ "$REPO" != "rsr-template-repo" ]; then - SELF_PROV='instantiated-from|parent|upstream|chain =|lineage|minted from|created from|Template: ' - find . -type f \ - -not -path './.git/*' \ - -not -path './build/just/repo-init.just' \ - -not -path './docs/decisions/*' \ - -not -path './.machine_readable/descriptiles/CLADE.a2ml' \ - -not -path './.machine_readable/descriptiles/VARIANT.a2ml' \ - -not -name 'CHANGELOG.md' \ - -not -name 'TEMPLATE-STANDARDS-AUDIT.adoc' \ - -not -name 'TEMPLATE-LINEAGE-AUDIT.adoc' \ - -not -name '*.png' -not -name '*.jpg' -not -name '*.gif' \ - -not -name '*.woff' -not -name '*.woff2' \ - | while read -r file; do - grep -q 'rsr-template-repo' "$file" 2>/dev/null || continue - file --brief "$file" | grep -qi 'text\|ascii\|utf' || continue + # + # A line that names the template as something to DETECT is protected too: + # the deed's state-validation `:reject-if-contains ("rsr-template-repo")` + # flags state files still carrying template text. Rewritten to the child's + # own slug it rejected every legitimate state file of the child (measured + # 2026-10-14 on resource-algebra) - the same "detector eaten by the + # filling" defect the :reject-if-matches comment in the deed records for + # tokens. + # + # An issue or PR reference `rsr-template-repo#N` names the TEMPLATE's own + # issue, and stays so. Rewritten it pointed at an issue of the child that + # does not exist, or worse, an unrelated one: resource-algebra carried 20 + # such references (`resource-algebra#209` for the deed-clause migration) + # after its mint on 2026-10-14. tests/workflows/self_name_pass_test.sh + # runs these two lines on fixtures. + if [ "$REPO" != "$TEMPLATE_REPO" ]; then + SELF_PROV='instantiated-from|parent|upstream|chain =|lineage|minted from|created from|Template: |reject-if-contains' + # The template's name and slug are LITERAL text, not patterns: a Julia + # mint's parent may be .jl, and `.` in a sed pattern matches any + # character. Escaped inline so self_name_pass_test.sh can evaluate this + # one assignment exactly as the recipe defines it. + SELF_NAME_SED="/${SELF_PROV}/!{s|${TEMPLATE_REPO//./\\.}#([0-9])|__TEMPLATE_ISSUE__\\1|g;s|${TEMPLATE_SLUG//./\\.}|${OWNER}/${REPO}|g;s|${TEMPLATE_REPO//./\\.}|${REPO}|g;s|__TEMPLATE_ISSUE__|${TEMPLATE_REPO}#|g;}" + # Paths that are ABOUT the template keep its name wholesale: its ADRs, + # changelog and audits. Template machinery (this recipe, the tests whose + # fixtures must stay the template's literal name) is not in mint_files + # at all; it is listed in .machine_readable/mint-verbatim.txt. + mint_files | while IFS= read -r file; do + case "$file" in + docs/decisions/*|CHANGELOG.md|*/CHANGELOG.md) continue ;; + TEMPLATE-STANDARDS-AUDIT.adoc|*/TEMPLATE-STANDARDS-AUDIT.adoc) continue ;; + TEMPLATE-LINEAGE-AUDIT.adoc|*/TEMPLATE-LINEAGE-AUDIT.adoc) continue ;; + *.png|*.jpg|*.gif|*.woff|*.woff2) continue ;; + esac + grep -qF -- "$TEMPLATE_REPO" "$file" 2>/dev/null || continue + is_text_file "$file" || continue # sed -i preserves the mode bit; rewriting via a temp file would not. - sed -i -E "/${SELF_PROV}/!{s|hyperpolymath/rsr-template-repo|${OWNER}/${REPO}|g;s|rsr-template-repo|${REPO}|g;}" "$file" + sed -i -E "$SELF_NAME_SED" "$file" done - echo " self-name: rewrote template literal -> ${REPO} (provenance lines preserved)" + echo " self-name: rewrote ${TEMPLATE_REPO} -> ${REPO} (provenance lines preserved)" # The repo deed's FILENAME carries the repo slug (deed dispatch: # _chora.deed — deed.abnf v1.0.0). The self-name pass rewrote # the slug inside the file; the file itself is renamed here. Plain mv: # mint runs before the new repo's first commit. Renames (not tokens) - # are how filenames change — a {{REPO}} token in a FILENAME is the + # are how filenames change — a REPO token in a FILENAME is the # brace-collapse hazard class repo-init has already been burnt by. - if [ -f rsr-template-repo_chora.deed ]; then - mv rsr-template-repo_chora.deed "${REPO}_chora.deed" - echo " repo deed: renamed rsr-template-repo_chora.deed -> ${REPO}_chora.deed" + # The deed was found by shape above (DEED_IN), never by the original + # template's name, so a mint from a minted repo renames it too. + if [ "${DEED_IN#./}" != "${REPO}_chora.deed" ]; then + mv -- "$DEED_IN" "${REPO}_chora.deed" + echo " repo deed: renamed ${DEED_IN#./} -> ${REPO}_chora.deed" fi + fi - # ── self-OWNER pass ────────────────────────────────────────────────── - # - # Same class as the self-name leak above, and missed by it: the - # template's own OWNER is a plain literal, so nothing rewrote it. A repo - # minted under a different owner shipped: - # - # Justfile OWNER := "hyperpolymath" - # sonar-project.properties sonar.projectKey=hyperpolymath_ - # - # i.e. it declared the wrong owner and reported its code analysis into - # the wrong SonarCloud project. Measured on a metadatastician mint. - # - # This pass is deliberately NARROW — three exact, identity-bearing - # lines. A blanket `hyperpolymath` -> ${OWNER} rewrite would be WRONG: - # `hyperpolymath/standards`, `hyperpolymath/proven` and the other estate - # dependencies are real repos every child genuinely points at, and - # rewriting those would break the child's canon, CI and badges. - if [ "$OWNER" != "hyperpolymath" ]; then - sed -i -E 's|^(OWNER[[:space:]]*:=[[:space:]]*)"hyperpolymath"|\1"'"${OWNER}"'"|' Justfile - sed -i -E 's|^sonar\.organization=hyperpolymath$|sonar.organization='"${OWNER}"'|' sonar-project.properties - sed -i -E 's|^sonar\.projectKey=hyperpolymath_|sonar.projectKey='"${OWNER}"'_|' sonar-project.properties - echo " self-owner: rewrote owner literal -> ${OWNER} (estate dependency paths preserved)" - echo " NOTE: confirm the SonarCloud ORG is really '${OWNER}' before provisioning —" - echo " the GitHub owner and the SonarCloud org are not always the same." - fi + # ── self-OWNER pass ────────────────────────────────────────────────────── + # + # Same class as the self-name leak above, and missed by it: the template's + # own OWNER is a plain literal, so nothing rewrote it. A repo minted under a + # different owner shipped: + # + # Justfile OWNER := "hyperpolymath" + # sonar-project.properties sonar.projectKey=hyperpolymath_ + # + # i.e. it declared the wrong owner and reported its code analysis into the + # wrong SonarCloud project. Measured on a metadatastician mint. The owner + # compared against is the TEMPLATE's (derived above), so a repo minted from + # a metadatastician child is handled the same way. + # + # This pass is deliberately NARROW — three exact, identity-bearing lines. A + # blanket owner rewrite would be WRONG: `hyperpolymath/standards`, + # `hyperpolymath/proven` and the other estate dependencies are real repos + # every child genuinely points at, and rewriting those would break the + # child's canon, CI and badges. + if [ "$OWNER" != "$TEMPLATE_OWNER" ]; then + sed -i -E 's|^(OWNER[[:space:]]*:=[[:space:]]*)"'"${TEMPLATE_OWNER}"'"|\1"'"${OWNER}"'"|' Justfile + sed -i -E 's|^sonar\.organization='"${TEMPLATE_OWNER}"'$|sonar.organization='"${OWNER}"'|' sonar-project.properties + sed -i -E 's|^sonar\.projectKey='"${TEMPLATE_OWNER}"'_|sonar.projectKey='"${OWNER}"'_|' sonar-project.properties + echo " self-owner: rewrote ${TEMPLATE_OWNER} -> ${OWNER} (estate dependency paths preserved)" + echo " NOTE: confirm the SonarCloud ORG is really '${OWNER}' before provisioning —" + echo " the GitHub owner and the SonarCloud org are not always the same." fi echo "" - echo "── Identity (CLADE.a2ml) ────────────────────────" - - # Install THIS repo's CLADE.a2ml, replacing rsr-template-repo's own. - # - # The CLADE.a2ml shipped in the template is the TEMPLATE's real identity — a - # real uuid for a real repo. Nothing in SED_ARGS ever touched it, so every - # repo created from this template inherited uuid a5ea1382-… and - # canonical-name "rsr-template-repo" verbatim, and told every arriving agent - # it WAS the template. Nothing caught it: each value was individually valid. - # chronicles-of-slavia and scaffoldia were corrected for exactly this on - # 2026-07-16; paint-type, cargo-zigbuild, email-octad-experiment, llm-grace - # and rsr-template-how-to still carry it. - # - # build/templates/CLADE.a2ml.in has already had its brace tokens filled by - # the substitution loop above (including the UUID one, derived earlier). - # NB: literal double-brace tokens cannot be written in this recipe body — - # just interpolates them, which is why LB/RB are built with printf above. + echo "── Identity (repo deed) ─────────────────────────" + + # Write THIS repo's identity into its deed, replacing rsr-template-repo's own. + # + # The template ships its REAL identity — clade rm, the canonical-name + # rsr-template-repo, a production maturity, its own ecosystem relations — + # between the `>>> repo-identity` / `<<< repo-identity` markers of the deed. + # Before #209 the same facts sat in descriptiles/CLADE.a2ml, which nothing + # in SED_ARGS touched, so every repo created from this template inherited + # uuid a5ea1382-… and canonical-name "rsr-template-repo" verbatim and told + # every arriving agent it WAS the template. chronicles-of-slavia and + # scaffoldia were corrected for exactly this on 2026-07-16. + # + # build/templates/identity.deed.in has already had its brace tokens filled + # by the substitution loop above. It uses only tokens whose values cannot + # break a deed string (slug, owner, forge, date); free text such as the + # description stays UNASSIGNED for the author. # The split is the whole point: - # DERIVABLE -> computed, never guessed (uuid, owner, canonical-name) + # DERIVABLE -> computed, never guessed (uuid name, owner, canonical-name) # JUDGEMENT -> left UNASSIGNED, fails loudly until a human chooses (clade) - CLADE_IN="build/templates/CLADE.a2ml.in" - CLADE_OUT=".machine_readable/descriptiles/CLADE.a2ml" - if [ -f "$CLADE_IN" ]; then - mkdir -p "$(dirname "$CLADE_OUT")" - cp "$CLADE_IN" "$CLADE_OUT" + ID_IN="build/templates/identity.deed.in" + # Whatever one deed is present (renamed for the child above, or already + # named for it): never a hardcoded template file name. + DEED="$(bash scripts/deed-field.sh --find .)" \ + || { echo "Error: the tree must carry exactly one *_chora.deed at its root."; exit 1; } + if [ -f "$ID_IN" ] && [ -f "$DEED" ]; then + if [ "$(grep -c '^ ; >>> repo-identity' "$DEED")" != 1 ] \ + || [ "$(grep -c '^ ; <<< repo-identity' "$DEED")" != 1 ]; then + echo "Error: $DEED must hold exactly one repo-identity marker pair." + exit 1 + fi + awk -v frag="$ID_IN" ' + /^ ; >>> repo-identity/ { while ((getline l < frag) > 0) print l; skip = 1; next } + /^ ; <<< repo-identity/ { skip = 0; next } + !skip + ' "$DEED" > "$DEED.splice" + cat "$DEED.splice" > "$DEED" # keeps the file's mode + rm -f "$DEED.splice" + # The uuid5 name. The self-name pass already rewrote owner and slug in + # it; the forge domain is set here, because nothing else knows it. + sed -i -E 's|^( :repo-uuid #u5")[^"]*"|\1'"${FORGE}/${OWNER}/${REPO}"'"|' "$DEED" + # The template's journal is not the child's: install the stub. + mkdir -p docs/status + cp build/templates/ROADMAP.adoc.in docs/status/ROADMAP.adoc rm -rf build/templates # template-only; not part of your repo if [ "$REPO_UUID" = "UNASSIGNED" ]; then echo " uuid: UNASSIGNED — uuidgen not found." - echo " Install util-linux (uuid-runtime), then run:" + echo " Install util-linux (uuid-runtime), then check it with:" echo " uuidgen --sha1 --namespace @url --name \"${FORGE}/${OWNER}/${REPO}\"" - echo " and put the result in $CLADE_OUT." else echo " uuid: $REPO_UUID" - echo " (uuid5 of ${FORGE}/${OWNER}/${REPO} — derived, recomputable, not invented)" + echo " (uuid5 of ${FORGE}/${OWNER}/${REPO} — derived from the deed's" + echo " :repo-uuid name, recomputable, not stored, not invented)" fi echo " clade: UNASSIGNED — a human must choose one of the 12." - echo " CLADE-003/006 FAIL until you do. That is deliberate:" + echo " just validate-rsr FAILS until you do. That is deliberate:" echo " an unchosen clade must not look like a chosen one." - echo " The taxonomy is listed in $CLADE_OUT." + echo " The taxonomy is listed in the (clade …) comment of $DEED." fi - echo "" echo "── Profile & provenance (ADR-0003) ──────────────" - # The template's own rsr-profile.a2ml is deliberately MAXIMAL (it is the - # dogfood target). A minted repo must NOT inherit it: declaring + # The template deed's own (rsr-profile) clause is deliberately MAXIMAL (it + # is the dogfood target). A minted repo must NOT inherit it: declaring # capabilities the tree lacks makes the oracle score modules that are - # absent (na-honesty, RSR-SPEC-v2 §scoring). Rewrite it minimally. - PROFILE_OUT=".machine_readable/rsr-profile.a2ml" + # absent (na-honesty, RSR-SPEC-v2 §scoring). Replace it minimally, below. # ── Canon pin (bind the canon) ────────────────────────────────────────── - # Read the canon identity from the template's [canon] block BEFORE that - # block is overwritten below. A minted repo must record WHICH canon release - # it was cut from; without it "which repos are on canon 1.x?" is a campaign - # across the whole estate instead of a grep. + # Read the canon identity from the template deed's `(canon …)` clause. A + # minted repo must record WHICH canon release it was cut from; without it + # "which repos are on canon 1.x?" is a campaign across the whole estate + # instead of a grep. + # + # The pin lives only in the deed (#215 moved it there from the retired + # profile file, whose copy could not follow canon 2.1.2). + # The deed was renamed to ${REPO}_chora.deed by the self-name pass above, + # and its (canon …) clause is carried into the child unchanged, so the + # child's deed and its PROVENANCE agree at mint. # # Count rather than guessed: a value here that silently became empty is the # same class of defect as an UNASSIGNED placeholder, and would let a repo # claim conformance to nothing. - # Section reader: `canon_key ` prints the value of from - # the [canon] section, or nothing. - # - # Deliberately escape-free: the first attempt spelled the section-header - # test as /^\[/ , which reached awk as a DOUBLE backslash followed by an - # unterminated bracket expression. awk does not error on that - it parses a - # character class that swallows the rest of the program and then matches - # nothing, so the pin came out silently EMPTY rather than failing loudly. - # `substr($0,1,1)=="["` cannot be mis-escaped. This is the same class of - # defect as an UNASSIGNED placeholder: a value that looks computed but is - # empty would let a minted repo claim conformance to nothing. - canon_key() { - awk -v want="[canon]" -v key="$1" ' - substr($0,1,1)=="[" { f = ($0==want) ? 1 : 0; next } - f && $0 ~ "^[[:space:]]*" key "[[:space:]]*=" { - sub(/^[^=]*=[[:space:]]*/, "") - gsub(/^["[:space:]]+|["[:space:]]+$/, "") - print; exit - } - ' "$2" + # + # Deliberately backslash-free. The previous TOML reader first spelled its + # section test as /^\[/ , which reached awk as a DOUBLE backslash followed + # by an unterminated bracket expression; awk parsed a character class that + # swallowed the rest of the program, matched nothing, and the pin came out + # silently EMPTY. Bracket classes such as [(] cannot be mis-escaped. + # + # deed_canon : print the value of : from the + # deed's one (canon …) clause, or nothing when the clause or key is + # absent or the clause is not unique. A ";" outside a string starts a + # comment that runs to line-end (deed.abnf), whole-line or inline. The SAME function is in + # .github/workflows/dogfood-gate.yml and standards + # scripts/check-canon-lockstep.sh; keep the three identical. + deed_canon() { + _clauses="$(awk 'BEGIN { bs = sprintf("%c", 92); dq = sprintf("%c", 34) } { o = ""; q = 0; for (i = 1; i <= length($0); i++) { c = substr($0, i, 1); if (q && c == bs) { o = o c substr($0, i + 1, 1); i++; continue } if (c == dq) q = !q; else if (!q && c == ";") break; o = o c } printf "%s ", o }' "$2" | grep -oE '[(]canon[[:space:]][^()]*[)]')" || true + _n="$(echo "$_clauses" | grep -c '(canon' || true)" + if [ "$_n" != "1" ]; then + echo "deed_canon: $2 carries ${_n:-0} (canon …) clauses, need exactly 1" >&2 + return 0 + fi + echo "$_clauses" | grep -oE ':'"$1"'[[:space:]]+"[^"]*"' | head -1 | sed -E 's/^[^"]*"//; s/"$//' || true } + DEED_OUT="${REPO}_chora.deed" CANON_VERSION="" CANON_CRITERIA_SHA="" CANON_GATES_SHA="" - if [ -f "$PROFILE_OUT" ]; then - CANON_VERSION="$(canon_key version "$PROFILE_OUT")" - CANON_CRITERIA_SHA="$(canon_key criteria_sha256 "$PROFILE_OUT")" - CANON_GATES_SHA="$(canon_key gates_sha256 "$PROFILE_OUT")" + if [ -f "$DEED_OUT" ]; then + CANON_VERSION="$(deed_canon version "$DEED_OUT")" + CANON_CRITERIA_SHA="$(deed_canon criteria-sha256 "$DEED_OUT")" + CANON_GATES_SHA="$(deed_canon gates-sha256 "$DEED_OUT")" fi CANON_VERSION="${CANON_VERSION:-UNASSIGNED}" CANON_CRITERIA_SHA="${CANON_CRITERIA_SHA:-UNASSIGNED}" CANON_GATES_SHA="${CANON_GATES_SHA:-UNASSIGNED}" + if [ ! -f "$DEED_OUT" ]; then + echo "Error: $DEED_OUT not found after the self-name pass — cannot write the" >&2 + echo " child's (rsr-profile) / (variant) / (provenance) clauses." >&2 + exit 1 + fi + + # put_clause NAME — write the clause read from stdin as the deed's + # top-level (NAME …) clause: replace it when present, append it otherwise, + # so a re-run of repo-init never leaves two. + put_clause() { + if bash scripts/deed-field.sh --has "$DEED_OUT" "$1"; then + bash scripts/deed-clause.sh replace "$DEED_OUT" "$1" - + else + bash scripts/deed-clause.sh append "$DEED_OUT" "" - + fi + } + + DECLARES_AGAINST=$(bash scripts/deed-field.sh "$DEED_OUT" rsr-profile declares-against 2>/dev/null || true) { - echo "# SPDX-License-Identifier: MPL-2.0" - echo "#" - echo "# rsr-profile.a2ml — this repo's declared RSR v2.0 capabilities." - echo "# Generated by just repo-init on ${CURRENT_DATE}. The template's maximal" - echo "# profile was removed at mint: declare only what this tree carries." - echo "" - echo "[rsr-profile]" - echo "version = \"1.0.0\"" - echo "spec = \"rsr-criteria-v2\"" - echo "declares-against = \"2.0.0-draft\"" + echo " ; rsr-profile — this repo's declared RSR v2.0 capabilities." + echo " ; Written by just repo-init on ${CURRENT_DATE}. The template's maximal" + echo " ; profile was replaced at mint: declare only what this tree carries." + echo " (rsr-profile" + echo " :version \"1.0.0\"" + echo " :spec \"rsr-criteria-v2\"" + echo " :declares-against \"${DECLARES_AGAINST:-2.0.0-draft}\"" if [ -n "$ARCH_PRESET" ]; then - echo "preset = \"${ARCH_PRESET}\"" + echo " :preset \"${ARCH_PRESET}\")" else - echo "# UNASSIGNED: declare capabilities (or a preset) — see standards" - echo "# .machine_readable/template-capability-gates.toml" - echo "capabilities = []" + echo " ; UNASSIGNED: declare capabilities (or a preset) — see standards" + echo " ; .machine_readable/template-capability-gates.toml" + echo " :capabilities ())" fi - } > "$PROFILE_OUT" - echo " profile: $PROFILE_OUT${ARCH_PRESET:+ (preset $ARCH_PRESET)}" + } | bash scripts/deed-clause.sh replace "$DEED_OUT" rsr-profile - + echo " profile: $DEED_OUT (rsr-profile)${ARCH_PRESET:+ (preset $ARCH_PRESET)}" # Provenance — the estate's answer-file (ADR-0002 contract shape, used - # per ADR-0003 with direction=generated-from-core). parent-pin resolves - # from the live template tip: correct for a fresh mint, UNASSIGNED when - # offline — honest, never guessed. - PARENT_SLUG="hyperpolymath/rsr-template-repo" - PARENT_PIN=$(git ls-remote "https://github.com/${PARENT_SLUG}.git" HEAD 2>/dev/null | cut -f1 || true) + # per ADR-0003 with direction=generated-from-core). + # + # PARENT_BRANCH / PARENT_PIN / PARENT_TREE were resolved before the first + # write (see "Which template commit is in hand" above). Reading the live + # remote tip recorded where the remote is NOW, not the tree in hand (#203); + # reading local HEAD recorded the CHILD's own commit whenever the repo was + # created with "Use this template" (lintel, 2026-10-14). Tree equality + # against the template's history is the rule that is right in both cases. + PARENT_SLUG="$TEMPLATE_SLUG" + + # Shape, not presence: a value that is not a 40-hex object name is not a pin. + [[ "$PARENT_PIN" =~ ^[0-9a-f]{40}$ ]] || PARENT_PIN="" + [[ "$PARENT_TREE" =~ ^[0-9a-f]{40}$ ]] || PARENT_TREE="" + [ "$PARENT_BRANCH" != "HEAD" ] || PARENT_BRANCH="" + PARENT_BRANCH="${PARENT_BRANCH:-UNASSIGNED}" PARENT_PIN="${PARENT_PIN:-UNASSIGNED}" - VARIANT_OUT=".machine_readable/descriptiles/VARIANT.a2ml" - mkdir -p "$(dirname "$VARIANT_OUT")" + PARENT_TREE="${PARENT_TREE:-UNASSIGNED}" + + # Recorded in the (provenance) clause. Non-interactive mints are the automated + # path (scaffoldia / CI); interactive ones are a human at a prompt. The + # distinction matters because #201 found a hand-minted instance whose + # generated identity was stale, and nothing recorded which path ran. + if [ -n "${RSR_NON_INTERACTIVE:-}" ]; then + MINT_MODE="non-interactive" + else + MINT_MODE="interactive" + fi + { - echo "# SPDX-License-Identifier: MPL-2.0" - echo "#" - echo "# VARIANT.a2ml — provenance contract (ADR-0002 shape; ADR-0003 use)." - echo "# Records what this repo was minted from so the drift gate" - echo "# (scripts/check-variant-drift.sh ) and future" - echo "# re-templating tooling have a defined input." - echo "#" - echo "# NOTE: placeholder rendering means many files differ from the" - echo "# parent by design; folding rendered answers into [normalise] is" - echo "# future work (ADR-0003), so the gate is informational for minted" - echo "# repos until then." - echo "" - echo "[metadata]" - echo "project = \"${REPO}\"" - echo "schema_version = \"0.1.0\"" - echo "last-updated = \"${CURRENT_DATE}\"" - echo "" - echo "[variant]" - echo "parent = \"${PARENT_SLUG}\"" - echo "parent-pin = \"${PARENT_PIN}\" # template tip at mint" - echo "role = \"minted-repo\"" - echo "stack = \"${ARCHETYPE:-unspecified}\"" - echo "direction = \"generated-from-core\"" - echo "" - echo "[normalise]" - echo "rules = \"action-pins self-name\"" - echo "" - echo "[paths.added]" - echo "paths = []" - echo "" - echo "[paths.removed]" - echo "paths = []" - echo "" - echo "[paths.diverged]" - echo "# Files a minted repo owns from birth." - echo "paths = [" - echo " \".machine_readable/descriptiles/CLADE.a2ml\"," - echo " \".machine_readable/descriptiles/VARIANT.a2ml\"," - echo " \".machine_readable/rsr-profile.a2ml\"," - echo "]" - } > "$VARIANT_OUT" + echo " ; variant — provenance contract (ADR-0002 shape; ADR-0003 use)." + echo " ; Records what this repo was minted from, for re-templating tooling and" + echo " ; the drift gate (scripts/check-variant-drift.sh). The mint renders" + echo " ; tokens and rewrites files, so most spine files differ from the parent" + echo " ; by design, and (normalise) does not yet fold the mint's answers" + echo " ; (ADR-0003): the gate is not armed for a minted repo. Measured on a" + echo " ; fresh mint (2026-10-20): 101 rendered files differ. The template pin" + echo " ; is checked by scripts/check-template-conformance.sh instead." + echo " (variant" + echo " :project \"${REPO}\"" + echo " :schema-version \"0.1.0\"" + echo " :last-updated \"${CURRENT_DATE}\"" + echo " :parent \"${PARENT_SLUG}\"" + echo " ; template tip at mint" + echo " :parent-pin \"${PARENT_PIN}\"" + echo " :role \"minted-repo\"" + echo " :stack \"${ARCHETYPE:-unspecified}\"" + echo " :direction \"generated-from-core\"" + echo " (normalise :rules \"action-pins self-name\")" + echo " ; Files a minted repo owns from birth are (paths :diverged …)." + echo " (paths" + echo " :added ()" + _removed=("${MINT_REMOVES[@]}") + [ "${DEED_IN#./}" = "${REPO}_chora.deed" ] || _removed+=("${DEED_IN#./}") + printf ' :removed ('; _sep="" + for _p in "${_removed[@]}"; do printf '%s"%s"' "$_sep" "$_p"; _sep=" "; done + printf ')\n' + echo " :diverged (\"${REPO}_chora.deed\" \"docs/status/ROADMAP.adoc\")))" + } | put_clause variant if [ "$PARENT_PIN" = "UNASSIGNED" ]; then - echo " provenance: $VARIANT_OUT — parent-pin UNASSIGNED (offline?)" + echo " provenance: $DEED_OUT (variant) — parent-pin UNASSIGNED (offline?)" echo " Set it to the template commit you minted from:" echo " git ls-remote https://github.com/${PARENT_SLUG}.git HEAD" else - echo " provenance: $VARIANT_OUT (parent-pin ${PARENT_PIN:0:12})" + echo " provenance: $DEED_OUT (variant) (parent-pin ${PARENT_PIN:0:12})" fi - # ── PROVENANCE.a2ml — the answer-file for the canon binding ───────────── + # ── (provenance) — the answer-file for the canon binding ───────────────── # ADR-0003 named this the single highest-leverage gap: "a minted repo does # not know which template commit it came from, so template improvements # cannot be propagated and drift cannot be detected." Copier/Cruft solved # it with an answer-file + update + check; this estate hand-simulated it as # recurring standardisation-PR campaigns. This is the answer-file. # - # VARIANT.a2ml above records the TEMPLATE dimension (diffing against the + # (variant) above records the TEMPLATE dimension (diffing against the # parent). This records the CANON dimension (which law the repo was cut # under). They are different questions and both are needed. - PROVENANCE_OUT=".machine_readable/PROVENANCE.a2ml" + # Flat keys only: a nested form headed "canon" would be counted by + # deed_canon above and empty the pin. { - echo "# SPDX-License-Identifier: MPL-2.0" - echo "#" - echo "# PROVENANCE.a2ml — what this repo was minted FROM." - echo "# Written once, at mint, by build/just/repo-init.just. Not a hand-edited" - echo "# file: tools that want \"what is this repo\" read STATE.a2ml; tools that" - echo "# want \"where did this repo come from\" read this." - echo "" - echo "[provenance]" - echo "minted_at = \"${CURRENT_DATE}\"" - echo "" - echo "template_repo = \"${PARENT_SLUG}\"" - echo "template_commit = \"${PARENT_PIN}\"" - echo "" - echo "canon_version = \"${CANON_VERSION}\"" - echo "criteria_sha256 = \"${CANON_CRITERIA_SHA}\"" - echo "gates_sha256 = \"${CANON_GATES_SHA}\"" - echo "" - echo "archetype = \"${ARCHETYPE:-}\"" - echo "minted_by = \"hand\"" - echo "" - echo "[substitutions]" - echo "# ADR-0003 records the old state honestly: \"renders 34 substitutions and" - echo "# derives identity, but leaves 12 tokens UNASSIGNED\". Listing them here" - echo "# converts that from a known defect into a QUERYABLE one: a non-empty" - echo "# list means the mint did not fully render, and the validation step" - echo "# below already fails on a leftover token." - echo "rendered = 34" - echo "unassigned = []" - } > "$PROVENANCE_OUT" + echo " ; provenance — what this repo was minted FROM. Written once, at mint," + echo " ; by build/just/repo-init.just. Tools that want \"what is this repo\" read" + echo " ; the rest of the deed; tools that want \"where did it come from\" read this." + echo " (provenance" + echo " :minted-at \"${CURRENT_DATE}\"" + echo " :template-repo \"${PARENT_SLUG}\"" + echo " :template-branch \"${PARENT_BRANCH}\"" + echo " :template-commit \"${PARENT_PIN}\"" + echo " :template-tree \"${PARENT_TREE}\"" + echo " ; Contract: branches this repo is EXPECTED to carry beyond the default." + echo " ; Empty means default-only. A mint must never inherit template work" + echo " ; branches (coderabbit/, chore/, bot-task or stale branches) — that is" + echo " ; how knot-knot received a byte-identical copy of a template work branch" + echo " ; with no common ancestor (#203). Enforced by" + echo " ; scripts/check-template-conformance.sh." + echo " :extra-branches ()" + echo " :canon-version \"${CANON_VERSION}\"" + echo " :criteria-sha256 \"${CANON_CRITERIA_SHA}\"" + echo " :gates-sha256 \"${CANON_GATES_SHA}\"" + echo " :archetype \"${ARCHETYPE:-}\"" + echo " ; Which minting path actually ran (#201/#203 needed this signal)." + echo " :minted-by \"repo-init\"" + echo " :mint-mode \"${MINT_MODE}\"" + echo " ; A non-empty :unassigned list means the mint did not fully render;" + echo " ; the validation step below already fails on a leftover token." + echo " (substitutions :rendered 34 :unassigned ()))" + } | put_clause provenance if [ "$CANON_VERSION" = "UNASSIGNED" ]; then - echo " provenance: $PROVENANCE_OUT — canon pin UNASSIGNED" - echo " The template carried no [canon] block, so this repo" + echo " provenance: $DEED_OUT (provenance) — canon pin UNASSIGNED" + echo " The template deed carried no (canon …) clause, so this repo" echo " cannot state which canon it conforms to. Fix by minting" echo " from a template commit that has one." else - echo " provenance: $PROVENANCE_OUT (canon v${CANON_VERSION} ${CANON_CRITERIA_SHA:0:12})" + echo " provenance: $DEED_OUT (provenance) (canon v${CANON_VERSION} ${CANON_CRITERIA_SHA:0:12})" fi # archetypes/ is template-only overlay data, not part of your repo @@ -666,17 +1019,25 @@ repo-init archetype="": rm -rf archetypes rm -rf build/docs-seed # template-only; its content now lives in docs/ - # Overlay .in rule (julia-library archetype; the convention any future - # overlay can adopt): the overlay ships content templates as *.in so a - # substitution token never survives in a file with a final name. Rename - # the known set now that substitution has rendered them, before the - # placeholder gate below. - if [ "$ARCHETYPE" = "julia-library" ]; then - # the name is read from Project.toml.in until the loop below renames - # it - order matters. + # Overlay .in rule (every archetype): an overlay ships content templates as + # *.in so a substitution token never survives in a file whose final name is + # already the real one — a half-rendered `Project.toml` is a file `Pkg` + # reads, while a half-rendered `Project.toml.in` is obviously unfinished. + # Only files THIS overlay added are renamed: the spine's own .in templates + # (build/templates/, the k9 examples) keep their suffix. + # + # src/PACKAGE.jl.in is the one exception, handled after the loop: the Julia + # convention names the module file after the package, and the package name + # is only known once Project.toml.in has been rendered and renamed. + for _of in "${OVERLAY_FILES[@]}"; do + case "$_of" in + src/PACKAGE.jl.in) continue ;; + *.in) [ -f "$_of" ] && { mv "$_of" "${_of%.in}"; echo " overlay: ${_of%.in}"; } ;; + esac + done + if [ "$ARCHETYPE" = "julia-library" ] && [ -f src/PACKAGE.jl.in ]; then TOML_FILE=Project.toml - [ -f "$TOML_FILE" ] || TOML_FILE=Project.toml.in - if [ -f src/PACKAGE.jl.in ] && [ -f "$TOML_FILE" ]; then + if [ -f "$TOML_FILE" ]; then PKG_NAME=$(sed -n 's/^name = "\([^"]*\)".*/\1/p' "$TOML_FILE" | head -1) if [ -n "$PKG_NAME" ] && [ "$PKG_NAME" != "UNASSIGNED" ]; then mv "src/PACKAGE.jl.in" "src/${PKG_NAME}.jl" @@ -687,11 +1048,78 @@ repo-init archetype="": echo " mv src/PACKAGE.jl.in src/.jl" fi fi - for f in Project.toml.in \ - .github/workflows/julia-ci.yml.in \ - .github/workflows/julia-docs.yml.in; do - [ -f "$f" ] && { mv "$f" "${f%.in}"; echo " overlay: ${f%.in}"; } - done + fi + + # ── www/ site-operations bundle (issue #53, stage 5) ────────────────── + # + # A repository minted from this template already carries www/.well-known/ + # as the canonical location and has no root .well-known/, so in the + # ordinary case the migration below does nothing at all. It exists for the + # case that is not ordinary: repo-init run over a tree that predates #53 + # and still has a root .well-known/. The migrator moves it — quarantining + # anything divergent rather than overwriting it — and the bundle's own + # suite (under Validation) then proves the result. It runs HERE, before the + # map and the arrival pack are regenerated, because it moves files: the map + # must be the last thing written, or it describes a tree that no longer + # exists (lintel shipped a stale map and Estate Rules failed until lintel#8). + # + # #106 described this wiring as already present. It was not: nothing + # invoked the migrator or the suite at mint, which is why the estate + # still carries root .well-known/ directories years into the convention. + if [ -d .well-known ] && [ -f scripts/migrate-wellknown-to-www.sh ]; then + echo "" + echo "Migrating legacy root .well-known/ into www/.well-known/..." + bash scripts/migrate-wellknown-to-www.sh + fi + + # ── Toolchain (mise.toml) ─────────────────────────────────────────────── + # The provisioning standard says mise.toml is MINTED per repository (canon's + # mise.toml.tmpl carries __MISE_TOOLS_TOML__ for exactly that). Until now the + # mint copied the spine's file verbatim, so every child declared the + # TEMPLATE's toolchain: the spine once declared nine runtimes (python, node, + # rust, go, zig, java, bun, denojs, npm, pip, cargo, black, ruff, pytest …) + # and a minted Julia package therefore installed Python — banned estate-wide + # — declared no Julia, and ran `cargo build` from `just build`. + # + # Rendered here, after the overlay's manifests have their final names (so + # detection can see Project.toml / Cargo.toml) and after the archetype prune + # (so a dropped module does not keep its toolchain). + if [ -f scripts/render-mise.sh ]; then + echo "" + echo "── Toolchain ────────────────────────────────────" + bash scripts/render-mise.sh --root . || { + echo "ERROR: mise.toml could not be rendered from this tree's languages." + exit 1 + } + fi + + # ── Regenerate what is DERIVED from the deed and the tree ─────────────── + # CLAUDE.md's arrival pack and the repository map are generated files, and + # until now the mint left both describing the TEMPLATE. The self-name pass + # swaps the slug inside them, which is worse than leaving them alone: the + # pack then states the template's uuid and clade, maturity `production`, + # and pipeline position `foundation` with chain "standards -> + # -> (every estate repo)", under the child's name. Measured 2026-10-14 on + # resource-algebra. The map also kept the archetypes/ root entry, + # which this recipe deletes, so Estate Rules' map-freshness step failed in + # every minted child. Both are regenerated here, after every deed clause + # above is written and every template-only path is gone. Fail-closed: a + # generator that cannot run (no nickel on PATH) stops the mint rather than + # shipping a pack that names the wrong repository. + # + # This is the LAST step that writes the tree; everything after it only + # checks (tests/e2e/use_template_mint_test.sh commits the result and runs + # the freshness check on it). The map is read from the work tree + # (--worktree), not the index: the mint runs before the first commit, so + # the index still lists archetypes/ and the template's deed name, which is + # how lintel shipped a map that failed Estate Rules from birth. + if [ -f .machine_readable/arrival-pack/generate.sh ]; then + bash .machine_readable/arrival-pack/generate.sh + echo " arrival pack: CLAUDE.md regenerated from ${DEED_OUT}" + fi + if [ -f scripts/gen-repo-map.sh ]; then + bash scripts/gen-repo-map.sh --worktree . >/dev/null + echo " repo map: docs/architecture/REPOSITORY-MAP.adoc regenerated" fi echo "" @@ -727,17 +1155,24 @@ repo-init archetype="": # gate sensibly exempting metasyntax must let the block through. The two # checks here are therefore complementary, not redundant — the block can # only be caught by name, which the check below does. - # The four allowlisted paths are copied verbatim from - # scripts/check-no-placeholders.sh so the two gates cannot drift apart. - # Each legitimately names tokens: the token vocabulary itself, prose - # explaining that tokens exist, the checker's own pattern, and the e2e - # test's answer list. + # The allowlisted paths are copied from scripts/check-no-placeholders.sh so + # the two gates cannot drift apart. Each legitimately names tokens: the + # token vocabulary itself, prose explaining that tokens exist, and the + # checker's own pattern. Template machinery that names tokens in its + # fixtures (the e2e answer list, the Julia UUID test) is in + # .machine_readable/mint-verbatim.txt, so mint_files never lists it, and + # the checker reads the same manifest. PATTERN="${LB}[A-Z_]*${RB}" META='PLACEHOLDER|ANYTHING|TOKEN|UPPER_SNAKE' - 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/' | while IFS= read -r f; do - case "${f#./}" in - .machine_readable/ai/PLACEHOLDERS.adoc|EXPLAINME.adoc|scripts/check-no-placeholders.sh|tests/e2e/template_instantiation_test.sh) continue ;; + REMAINING=$(mint_files | while IFS= read -r f; do + case "$f" in + *.md|*.adoc|*.yml|*.yaml|*.deed|*.toml|*.scm|*.ncl|*.nix|*.json|*.sh) ;; + *) continue ;; esac + case "$f" in + .machine_readable/ai/PLACEHOLDERS.adoc|EXPLAINME.adoc|scripts/check-no-placeholders.sh) continue ;; + esac + grep -q "$PATTERN" "$f" 2>/dev/null || continue # Bracketed [{]{2} rather than a doubled brace written literally, for # two independent reasons. First, `grep -E` is ugrep on some estate # machines and rejects a bare doubled brace as an "empty @@ -771,15 +1206,17 @@ repo-init archetype="": # token, and once its literal metasyntax is the only doubled-brace text left # the check above cannot distinguish the two. Fail on it by name. # - # The strip pass, this recipe and the e2e test are excluded because they - # necessarily NAME the marker in order to describe or assert on it — the fix - # for the defect would otherwise be flagged by the check for the defect, and - # so would the test that guards the fix, and the cleanup test whose - # fixture prose must keep the phrase to prove prose is not collateral. - # All four are tooling, not + # Read over mint_files, so the files that necessarily NAME the marker in + # order to describe or assert on it (the strip tool, this recipe, the e2e + # test, the cleanup test whose fixture must keep the phrase) are exempt by + # the same manifest that kept the strip pass out of them: they are listed + # in .machine_readable/mint-verbatim.txt. Before, this list exempted them + # here while the strip pass rewrote them anyway. All are tooling, not # community-health documents, so a mention in them cannot mislead a reader # about what this project's Code of Conduct says. - LEFTOVER_BLOCKS=$(grep -rl 'TEMPLATE INSTRUCTIONS' . --exclude-dir=.git 2>/dev/null | grep -vE '^\./(scripts/strip-instruction-blocks\.rs|build/just/repo-init\.just|tests/e2e/template_instantiation_test\.sh|tests/workflows/mint_cleanup_test\.sh)$' || true) + LEFTOVER_BLOCKS=$(mint_files | while IFS= read -r f; do + grep -q 'TEMPLATE INSTRUCTIONS' "$f" 2>/dev/null && echo "$f" + done || true) if [ -n "$LEFTOVER_BLOCKS" ]; then echo "" echo "Un-deleted TEMPLATE INSTRUCTIONS block in:" @@ -788,23 +1225,37 @@ repo-init archetype="": exit 1 fi - # ── www/ site-operations bundle (issue #53, stage 5) ────────────────── - # - # A repository minted from this template already carries www/.well-known/ - # as the canonical location and has no root .well-known/, so in the - # ordinary case both steps below do nothing at all. They exist for the - # case that is not ordinary: repo-init run over a tree that predates #53 - # and still has a root .well-known/. The migrator moves it — quarantining - # anything divergent rather than overwriting it — and the bundle's own - # suite then proves the result. - # - # #106 described this wiring as already present. It was not: nothing - # invoked the migrator or the suite at mint, which is why the estate - # still carries root .well-known/ directories years into the convention. - if [ -d .well-known ] && [ -f scripts/migrate-wellknown-to-www.sh ]; then + # ── The gates the template enforces on children, run on the child ──────── + # Each of these was once a check the template shipped that could not fail: + # * the SPDX check globbed one language's extensions, so in a Julia repo it + # examined nothing and reported PASS; + # * the container check asked "is cgr.dev named anywhere" and passed on a + # floating :latest, so a template shipping two of them passed itself; + # * the toolchain check did not exist, and the spine's mise.toml declared + # nine runtimes for repositories that use none of them. + # Running them HERE means a mint that would fail them fails at mint, in the + # template's own CI, instead of in N children after the fact. + echo "" + echo "── Language, licence and container gates ────────" + GATE_FAIL=0 + for _gate in check-spdx-headers check-mise-language check-container-pins; do + [ -f "scripts/${_gate}.sh" ] || continue echo "" - echo "Migrating legacy root .well-known/ into www/.well-known/..." - bash scripts/migrate-wellknown-to-www.sh + echo " ${_gate}.sh" + if bash "scripts/${_gate}.sh" --root .; then + echo " ${_gate}: OK" + else + echo " ${_gate}: FAILED" + GATE_FAIL=1 + fi + done + if [ "$GATE_FAIL" -ne 0 ]; then + echo "" + echo "ERROR: the minted tree fails a gate this template enforces on children." + echo " The tree above is complete but not conforming; fix it before" + echo " committing. (A mint that ships a failing tree teaches the child" + echo " that the gate is noise.)" + exit 1 fi # Fail-closed, like `just verify` below: the suite tolerates unminted @@ -853,5 +1304,8 @@ repo-init archetype="": echo " must be set to ci/.gitlab-ci.yml, or GitLab CI silently never" echo " runs - no pipeline and no error. See ci/README.adoc." fi - echo " 8. HARNESS — arm the drift gate against your recorded parent-pin:" - echo " scripts/check-variant-drift.sh " + echo " 8. HARNESS — check the recorded template pin (provenance):" + echo " scripts/check-template-conformance.sh [--template ]" + echo " scripts/check-variant-drift.sh is not for a minted repo yet: the mint" + echo " renders most spine files, so they differ from the parent by design" + echo " until (normalise) folds the mint's answers (ADR-0003)." diff --git a/build/just/validate.just b/build/just/validate.just index 5718a771..2606f25f 100644 --- a/build/just/validate.just +++ b/build/just/validate.just @@ -18,36 +18,81 @@ validate-rsr: [ -f "$f" ] || MISSING="$MISSING $f" done # The repo deed's filename carries the repo slug (_chora.deed), so - # this is a glob; the folded replacement of the old 0-AI-MANIFEST.a2ml. + # this is a glob. ls *_chora.deed >/dev/null 2>&1 || MISSING="$MISSING repo-deed (*_chora.deed)" - for f in .machine_readable/descriptiles/STATE.a2ml .machine_readable/descriptiles/META.a2ml .machine_readable/descriptiles/ECOSYSTEM.a2ml .machine_readable/descriptiles/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 + # .a2ml is retired: a repo carrying one is non-conformant, whatever else holds. + bash scripts/check-no-a2ml.sh . >/dev/null || MISSING="$MISSING no-a2ml(run scripts/check-no-a2ml.sh)" for f in docs/legal/EXHIBIT-A-ETHICAL-USE.txt docs/legal/EXHIBIT-B-QUANTUM-SAFE.txt LICENSES/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" + # The polyglot seam (Idris2 ABI over a Zig FFI) is INHERITED from the + # template's spine, not required of every repository: an archetype whose + # preset declares neither the abi nor the ffi capability prunes src/interface/ + # at mint (ADR-0003, archetypes//prune.txt). A minted Rust CLI is not + # incomplete for lacking a seam it did not ask for. So: a tree that carries + # the seam must carry all of it; a tree that carries none of it is complete + # without it. Deleting one part of a present seam still fails. + if [ -d src/interface ]; then + 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 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/descriptiles/META.a2ml" ]; then - grep -q 'axis-1 = "must > intend > like"' .machine_readable/descriptiles/META.a2ml || MISSING="$MISSING META.a2ml:axis-1" - grep -q 'axis-2 = "corrective > adaptive > perfective"' .machine_readable/descriptiles/META.a2ml || MISSING="$MISSING META.a2ml:axis-2" - grep -q 'axis-3 = "systems > compliance > effects"' .machine_readable/descriptiles/META.a2ml || MISSING="$MISSING META.a2ml:axis-3" - grep -q 'scoping-first = true' .machine_readable/descriptiles/META.a2ml || MISSING="$MISSING META.a2ml:scoping-first" - grep -q 'idris-unsound-scan = "believe_me/assert_total"' .machine_readable/descriptiles/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/descriptiles/META.a2ml || MISSING="$MISSING META.a2ml:audit-focus" - grep -q 'compliance-focus = "seams/compromises/exception register, bounded exceptions, anti-drift checks"' .machine_readable/descriptiles/META.a2ml || MISSING="$MISSING META.a2ml:compliance-focus" - grep -q 'effects-evidence = "benchmark execution/results and maintainer status dialogue/review"' .machine_readable/descriptiles/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" + # Identity, lifecycle, maintenance axes, the anchor and the maintenance + # policies are all clauses of the repo deed (rsr-template-repo#209). + DEED=$(bash scripts/deed-field.sh --find . || true) + if [ -n "$DEED" ] && bash scripts/deed-field.sh --has "$DEED" status; then + # Prints the field, or nothing when it is absent. + field() { bash scripts/deed-field.sh "$DEED" "$1" "$2" || true; } + # Adds a MISSING entry unless deed field CLAUSE KEY equals the expected value. + want() { + [ "$(field "$1" "$2")" = "$3" ] || MISSING="$MISSING $DEED:$1:$2" + } + [ -n "$(field "" repo-uuid)" ] || MISSING="$MISSING $DEED:repo-uuid" + # CLADE-003/006 on the deed: a closed code set, and the code must agree + # with its name. UNASSIGNED fails on purpose: an unchosen clade must + # never be mistakable for a chosen one. + case "$(field clade primary)|$(field clade primary-name)" in + "fv|Formal Verification & Proofs"|"nl|Nextgen Languages"|"rm|Repo Management & Tooling"|\ + "gv|Governance & Standards"|"db|Databases"|"ap|Applications"|"ix|Infrastructure & Cloud"|\ + "dx|Developer Ecosystem"|"pt|Protocols & Interop"|"ax|AI & Neurosymbolic"|\ + "gm|Games & Interactive"|"sc|Security") ;; + *) MISSING="$MISSING $DEED:clade(primary/primary-name unset or mismatched)" ;; + esac + # CLADE-004/005: the lifecycle phase is a closed set. + case "$(field status phase)" in + reserved|incubating|active|dormant|merged|superseded|archived|extinct) ;; + *) MISSING="$MISSING $DEED:status:phase" ;; + esac + case "$(field maturity level)" in + experimental|alpha|beta|production|lts) ;; + *) MISSING="$MISSING $DEED:maturity:level" ;; + esac + # The ecosystem clause names the repo the deed's header names. + [ "$(field ecosystem project)" = "$(field "" canonical-name)" ] \ + || MISSING="$MISSING $DEED:ecosystem:project" + want meta axis-1 "must > intend > like" + want meta axis-2 "corrective > adaptive > perfective" + want meta axis-3 "systems > compliance > effects" + want meta scoping-first true + want meta/scoping idris-unsound-scan "believe_me/assert_total" + want meta/axis-3 audit-focus "systems in place, documentation explains actual state, safety/security accounted for, observed effects reviewed" + want meta/axis-3 compliance-focus "seams/compromises/exception register, bounded exceptions, anti-drift checks" + want meta/axis-3 effects-evidence "benchmark execution/results and maintainer status dialogue/review" + for c in anchor policies/maintenance-axes policies/maintenance-checklist policies/software-development-approach; do + bash scripts/deed-field.sh --has "$DEED" "$c" || MISSING="$MISSING $DEED:($c)" + done + want policies/maintenance-axes/axis-3-audit compliance-tooling "panic-attack" + want policies/maintenance-axes/axis-3-audit effects-tooling "ecological checking with sustainabot guidance" + want policies/maintenance-checklist/metadata source-human "docs/governance/MAINTENANCE-CHECKLIST.adoc" + want policies/software-development-approach/metadata source-human "docs/governance/SOFTWARE-DEVELOPMENT-APPROACH.adoc" + else + MISSING="$MISSING repo-deed:(status …)-clause" fi if [ -n "$MISSING" ]; then echo "MISSING:$MISSING" @@ -55,17 +100,26 @@ validate-rsr: fi echo "RSR compliance: PASS" -# Validate STATE.a2ml syntax +# Validate the repo's lifecycle state: the deed's (status …) and +# (maturity …) clauses. validate-state: - @cd "{{justfile_directory()}}" && if [ -f ".machine_readable/descriptiles/STATE.a2ml" ]; then \ - grep -q '^\[metadata\]' .machine_readable/descriptiles/STATE.a2ml && \ - grep -q 'project\s*=' .machine_readable/descriptiles/STATE.a2ml && \ - echo "STATE.a2ml: valid" || echo "STATE.a2ml: INVALID (missing required sections)"; \ - else \ - echo "No .machine_readable/descriptiles/STATE.a2ml found"; \ + #!/usr/bin/env bash + cd "{{justfile_directory()}}" + DEED=$(bash scripts/deed-field.sh --find . || true) + if [ -n "$DEED" ] && bash scripts/deed-field.sh --has "$DEED" status; then + phase=$(bash scripts/deed-field.sh "$DEED" status phase || true) + level=$(bash scripts/deed-field.sh "$DEED" maturity level || true) + if [ -n "$phase" ] && [ -n "$level" ]; then + echo "$DEED: valid (phase $phase, maturity $level)" + else + echo "$DEED: INVALID (needs (status :phase …) and (maturity :level …))" + exit 1 + fi + else + echo "No repo state found: the repo deed has no (status …) clause" + exit 1 fi -# Validate AI installation guide completeness (finishbot pre-release check) validate-ai-install: #!/usr/bin/env bash cd "{{justfile_directory()}}" @@ -123,6 +177,22 @@ validate-ai-install: fi fi + # The rest of the provisioning set's AI and manual-setup documents. Their + # locations come from the provisioning engine, so this check and `just doctor` + # agree on where the warm-ups live (root, docs/onboarding/ or docs/). + if [ -f build/just/provision-lib.sh ]; then + for d in $(bash build/just/provision-lib.sh set-files | grep -E '(^|/)(SETUP|llm-warmup-[a-z]+)\.adoc$'); do + if [ ! -f "$d" ]; then + echo "MISSING: $d" + ERRORS=$((ERRORS + 1)) + fi + done + if ! grep -q '^\[\[ai-install\]\]' "$README" 2>/dev/null; then + echo "MISSING: [[ai-install]] anchor in $README (see build/just/provision.just ai-setup)" + ERRORS=$((ERRORS + 1)) + fi + fi + if [ "$ERRORS" -gt 0 ]; then echo "" echo "AI install guide: FAIL ($ERRORS issues)" diff --git a/build/manifest.scm b/build/manifest.scm new file mode 100644 index 00000000..a05df9c9 --- /dev/null +++ b/build/manifest.scm @@ -0,0 +1,15 @@ +;; SPDX-License-Identifier: MPL-2.0 +;; SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) +;; +;; manifest.scm — the Guix development shell for rsr-template-repo. +;; +;; guix shell -m manifest.scm # or: just dev-shell +;; guix time-machine -C channels.scm -- shell -m manifest.scm # the pinned Guix +;; +;; Minted by provision-set from the languages detected here (idris2, zig). +;; Tools Guix does not package: idris2 (via pack). They come from mise, which this +;; shell provides: guix shell -m manifest.scm -- mise install +;; Canon: hyperpolymath/standards 3-practice/provisioning/PROVISIONING-STANDARD.adoc +(specifications->manifest + (list "git" "bash" "coreutils" "nss-certs" "just" "mise" + "shellcheck" "chez-scheme" "gmp" "gcc-toolchain" "zig")) diff --git a/build/templates/CLADE.a2ml.in b/build/templates/CLADE.a2ml.in deleted file mode 100644 index 416512de..00000000 --- a/build/templates/CLADE.a2ml.in +++ /dev/null @@ -1,127 +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 -# -# Installed by `just repo-init` from build/templates/CLADE.a2ml.in. -# The identity below is DERIVED. The clade is NOT — a human must choose it. - -[identity] -# THE UUID IS DERIVED, NOT ALLOCATED, NOT INVENTED. The registry spec -# (gv-clade-index: docs/SPEC-clade-verisim-portal.adoc §Identity Model): -# -# uuid = UUIDv5(namespace = URL, name = "github.com//") -# -# "The same repo always produces the same UUID without a lookup table." It is a -# fact anyone can recompute and check — never copy one from another repo, and -# never make one up. Recompute this one any time with: -# -# uuidgen --sha1 --namespace @url --name "github.com/{{OWNER}}/{{REPO}}" -# -# Verify the method first by reproducing a known worked example: -# janus example -> e216170e-ff47-5a5c-bbdd-15e61c8190c8 -# -# The owner segment is part of the derived name, so it is part of the IDENTITY: -# the same repo hosted under a different owner has a different uuid. Record the -# owner that is TRUE TODAY, and re-derive if it ever moves. -uuid = "{{UUID}}" -primary-forge = "github" -primary-owner = "{{OWNER}}" -canonical-name = "{{REPO}}" -prefixed-name = "UNASSIGNED-{{REPO}}" # becomes -{{REPO}} once the clade is chosen - -[clade] -# --------------------------------------------------------------------------- -# CHOOSE ONE. A CLOSED TAXONOMY OF 12 CATEGORIES — NOT AN ABBREVIATION SCHEME. -# -# The two letters abbreviate the NAME OF THE CLADE. They NEVER abbreviate the -# name of your repo. Pick the category your repo belongs to, then write down -# that category's code. Do NOT look at your repo's name and hunt for two letters -# that fit it. -# -# fv Formal Verification & Proofs provable correctness, dependent types, theorem proving -# nl Nextgen Languages compilers, runtimes, language tooling -# rm Repo Management & Tooling scaffolding, graph analysis, bots, templates -# gv Governance & Standards licensing, compliance, policy enforcement -# db Databases database engines, query languages, storage -# ap Applications end-user apps, web, desktop, services -# ix Infrastructure & Cloud containers, deployment, sysadmin -# dx Developer Ecosystem dev tools, package managers, editors, bindings -# pt Protocols & Interop internet standards, protocol implementations -# ax AI & Neurosymbolic ML, neural proof synthesis, AI governance -# gm Games & Interactive game engines, interactive experiences -# sc Security scanning, vulnerability management, access control -# -# This is spelled out because the opposite was done, more than once: -# -# paint-type chose `pt`, reading it as "PainT-type". -# `pt` is Protocols & Interop. An image editor is `ap`. -# gossamer chose `gv`, reading it as "Graphical/Visual". -# `gv` is GoVernance & Standards. There is no graphical clade. -# -# Both codes were VALID, so every check passed, and both repos sat filed under a -# category they have nothing to do with. -# -# HOW TO CHOOSE (spec): "The primary clade reflects the project's core value -# proposition, not its implementation details." Ask what the repo is FOR, not -# what it is built with. A game written in Idris2 is `gm`, not `fv`. A webview -# shell with formal ABI proofs is what developers build on, not a proof project. -# -# Fill in BOTH `primary` and `primary-name`, and make them agree — CLADE-006 -# rejects a mismatched pair. The redundancy is deliberate: a code alone cannot -# express a wrong belief about what it means, so it cannot be checked for one. -# The pair can. -# -# Until you fill these in, CLADE-003 and CLADE-006 FAIL. That is deliberate: an -# unchosen clade must never be mistakable for a chosen one. Leaving a valid- -# looking default here is exactly how every repo built from this template ended -# up silently claiming "rm". -# --------------------------------------------------------------------------- -primary = "UNASSIGNED" -primary-name = "UNASSIGNED" -secondary = [] # [] unless there is a genuine SECOND core value proposition -assigned = "{{CURRENT_DATE}}" -rationale = "" # why THIS category — in value-proposition terms - -[forges] -github = "{{OWNER}}/{{REPO}}" -gitlab = "" # populated if/when mirrored -bitbucket = "" # populated if/when mirrored - -[lineage] -# type: standalone | monorepo | monorepo-child | inflated | deflated | hub | satellite -# hub — this repo COORDINATES an ecosystem family (its members carry -# type="satellite"). WHICH repos it coordinates is not recorded -# here: that lives in ECOSYSTEM.a2ml [pipeline] coordination. -# satellite — this repo is COORDINATED BY a hub. Its `parent` STAYS "": -# parent is a monorepo parent — never a description, and never -# the name of the coordinating hub. -# "hub"/"satellite" were added after the first hub ecosystem had to mint eight -# repos with the nearest-wrong value "standalone" (standards#726): lineage is -# the pointer, ECOSYSTEM.a2ml is the detail. Do not encode membership twice. -type = "standalone" -parent = "" # a monorepo PARENT — never a description of this repo -born = "{{CURRENT_DATE}}" -previous-names = [] -instantiated-from = "rsr-template-repo" - -[status] -# One of: reserved incubating active dormant | merged superseded archived extinct -phase = "incubating" # a repo created today has not proven anything yet -since = "{{CURRENT_DATE}}" -present = true -aliases = [] -merged-into = "" -superseded-by = "" -successors = [] -ended = "" - -[[status.history]] -phase = "incubating" -since = "{{CURRENT_DATE}}" -note = "created from rsr-template-repo; clade not yet chosen; not yet registered" - -# --------------------------------------------------------------------------- -# REGISTRATION IS NOT DERIVATION. Deriving the uuid above does not register this -# repo. Registration means an entry in gv-clade-index verisim/seed/repos.a2ml, -# it is outward-facing, and it is the OWNER's act — an agent must not do it. -# --------------------------------------------------------------------------- diff --git a/build/templates/ROADMAP.adoc.in b/build/templates/ROADMAP.adoc.in new file mode 100644 index 00000000..3a465b16 --- /dev/null +++ b/build/templates/ROADMAP.adoc.in @@ -0,0 +1,23 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 +// Copyright (c) Jonathan D.A. Jewell += {{PROJECT_NAME}} 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/build/templates/identity.deed.in b/build/templates/identity.deed.in new file mode 100644 index 00000000..60caf7b0 --- /dev/null +++ b/build/templates/identity.deed.in @@ -0,0 +1,96 @@ + ; >>> repo-identity + ; Written by `just repo-init` from build/templates/identity.deed.in, in + ; place of the block the template repo ships (template issue #209). It replaces + ; descriptiles/CLADE.a2ml and ECOSYSTEM.a2ml; the mapping is standards + ; 1-formats/deed/mappings/clade-to-repo-deed.adoc and + ; meta-ecosystem-to-repo-deed.adoc. + ; + ; THE UUID IS DERIVED, NOT ALLOCATED, NOT INVENTED. It is not stored: it is + ; uuid5(namespace = URL, name = the header :repo-uuid string) + ; and anyone can recompute it (gv-clade-index: + ; docs/SPEC-clade-verisim-portal.adoc §Identity Model): + ; uuidgen --sha1 --namespace @url --name "{{FORGE}}/{{OWNER}}/{{REPO}}" + ; The owner is part of the name, so part of the identity: record the owner + ; that is true today, and re-derive if the repo ever moves. + ; + ; CHOOSE A CLADE. A CLOSED TAXONOMY OF 12 CATEGORIES, NOT AN ABBREVIATION + ; SCHEME: the two letters abbreviate the clade's name, never your repo's. + ; fv Formal Verification & Proofs provable correctness, dependent types, theorem proving + ; nl Nextgen Languages compilers, runtimes, language tooling + ; rm Repo Management & Tooling scaffolding, graph analysis, bots, templates + ; gv Governance & Standards licensing, compliance, policy enforcement + ; db Databases database engines, query languages, storage + ; ap Applications end-user apps, web, desktop, services + ; ix Infrastructure & Cloud containers, deployment, sysadmin + ; dx Developer Ecosystem dev tools, package managers, editors, bindings + ; pt Protocols & Interop internet standards, protocol implementations + ; ax AI & Neurosymbolic ML, neural proof synthesis, AI governance + ; gm Games & Interactive game engines, interactive experiences + ; sc Security scanning, vulnerability management, access control + ; paint-type once chose `pt` reading it as "PainT-type" (an image editor is + ; `ap`); gossamer chose `gv` reading it as "Graphical/Visual" (`gv` is + ; GoVernance). Both codes were valid, so every check passed. + ; HOW TO CHOOSE: the primary clade reflects the project's core value + ; proposition, not its implementation. A game written in Idris2 is `gm`. + ; Set BOTH :primary and :primary-name, and make them agree; then set + ; :prefixed-name to "-{{REPO}}". `just validate-rsr` fails while + ; :primary is UNASSIGNED. That is deliberate: an unchosen clade must never + ; look like a chosen one. + ; + ; REGISTRATION IS NOT DERIVATION. Registering means an entry in + ; gv-clade-index verisim/seed/repos.a2ml. It is outward-facing and it is the + ; OWNER's act; an agent must not do it. + (identity + :primary-forge github + :owner "{{OWNER}}" + :prefixed-name "UNASSIGNED-{{REPO}}") + (clade + :primary UNASSIGNED + :primary-name "UNASSIGNED" + :secondary () + :assigned "{{CURRENT_DATE}}" + :rationale "") + (forges + :github "{{OWNER}}/{{REPO}}") + ; :type is one of standalone monorepo monorepo-child inflated deflated hub + ; satellite. A hub COORDINATES an ecosystem family; a satellite is + ; coordinated by one and keeps :parent "" (parent names a monorepo parent, + ; never the coordinating hub). + (lineage + :type standalone + :parent "" + :born "{{CURRENT_DATE}}" + :previous-names () + :instantiated-from "rsr-template-repo") + ; :phase is one of reserved incubating active dormant merged superseded + ; archived extinct. A repo created today has not proven anything yet. + (status + :phase incubating + :since "{{CURRENT_DATE}}" + :present #t + :aliases () + :merged-into "" + :superseded-by "" + :successors () + :ended "" + (history + (entry :phase incubating :since "{{CURRENT_DATE}}" :note "created from rsr-template-repo; clade not yet chosen; not yet registered"))) + ; :level is one of experimental alpha beta production lts (standards + ; 1-formats/deed/vocabulary/maturity.adoc). + (maturity + :level experimental + :since "{{CURRENT_DATE}}") + ; Fill in what this repo IS and IS NOT, and the repos it relates to. + ; :relationship is one of standard-source build-tooling validation-tooling + ; signing-tooling verification-tooling minted-from registry. + (ecosystem + :project "{{REPO}}" + :ecosystem "{{OWNER}}" + :position-type "UNASSIGNED" + :purpose "UNASSIGNED" + :not () + :pipeline-position "UNASSIGNED" + :chain "UNASSIGNED" + :coordination standards + (related :name "rsr-template-repo" :relationship minted-from :notes "the template this repo was minted from by just repo-init")) + ; <<< repo-identity diff --git a/ci/.pre-commit-config.yaml b/ci/.pre-commit-config.yaml index 80691647..a5c2794f 100644 --- a/ci/.pre-commit-config.yaml +++ b/ci/.pre-commit-config.yaml @@ -23,17 +23,16 @@ repos: # upstream in the A2ML retirement (standards #836 owner ruling; R-H3), # leaving this pin as broken plumbing — pre-commit could not clone it. # Replaced with a local hook calling .github/hooks/validate-deed.sh, - # verified exit-0 against all 123 manifests in this repo. Dual-accept: - # scans both .a2ml (legacy extension; migration = standards #837, the - # DEED conversion campaign) and .deed. When the grammar-faithful .deed + # It validates every .deed file and rejects any .a2ml file (the format is + # retired; its facts live in the repo deed). When the grammar-faithful .deed # validator is wired per owner ruling R-H2, this hook is its natural home. - repo: local hooks: - id: validate-deed - name: Validate DEED manifests (dual-accept .a2ml/.deed) + name: Validate DEED manifests (and refuse retired .a2ml) entry: .github/hooks/validate-deed.sh language: system - files: '\.(a2ml|deed)$' + files: '\.(a2ml|A2ML|deed)$' pass_filenames: false # --- K9 contract validation --- @@ -62,12 +61,12 @@ repos: hooks: - id: gitleaks - # --- Arrival pack drift: CLAUDE.md must stay in sync with a2ml --- + # --- Arrival pack drift: CLAUDE.md must stay in sync with the repo deed --- - repo: local hooks: - id: validate-claude-md - name: CLAUDE.md arrival pack in sync with a2ml + name: CLAUDE.md arrival pack in sync with the repo deed entry: bash .machine_readable/arrival-pack/verify.sh language: system pass_filenames: false - files: '^(\.machine_readable/descriptiles/.*|CLAUDE\.md)$' + files: '^([^/]+_chora\.deed|\.machine_readable/arrival-pack/.*|CLAUDE\.md)$' diff --git a/coordination.k9.ncl b/coordination.k9.ncl index 6f4f9877..69721f86 100644 --- a/coordination.k9.ncl +++ b/coordination.k9.ncl @@ -5,6 +5,7 @@ K9! { pedigree = { schema_version = "1.0.0", + component_type = "session:coordination-binding", metadata = { name = "session-coordination", version = "0.1.0", diff --git a/docs/AI-INSTALL-README-SECTION.adoc b/docs/AI-INSTALL-README-SECTION.adoc index 19ed4632..8041c073 100644 --- a/docs/AI-INSTALL-README-SECTION.adoc +++ b/docs/AI-INSTALL-README-SECTION.adoc @@ -2,19 +2,20 @@ // Copyright (c) 2026 Jonathan D.A. Jewell = AI-Install README Section (canonical snippet) -The block below is the canonical `== AI-Assisted Installation` section. Paste it -into a repository's `README.adoc` verbatim; `just validate-ai-install` greps the -README for the heading text, so keep the heading exactly as written. +The canonical README section is now part of the estate provisioning set: +`hyperpolymath/standards` → +`3-practice/provisioning/templates/README-ai-install.adoc.tmpl`. +It starts with the `\[[ai-install]]` anchor and the heading +`== AI-Assisted Installation (Recommended)`, then a *Just say it* block whose first +listing line is the one sentence to give any AI. `just ai-setup` and +`./launcher.sh --ai-setup` print that same line, read from the README, so edit it +there and nowhere else. ----- -== AI-Assisted Installation +`just validate-ai-install` checks for the heading text, the `\[[ai-install]]` +anchor, `docs/AI_INSTALLATION_GUIDE.adoc`, `docs/SETUP.adoc` and the three +`llm-warmup-{user,dev,maintainer}.adoc` warm-ups. -If you are an AI agent installing this project, read -link:docs/AI_INSTALLATION_GUIDE.adoc[the AI installation guide] first — it gives -the orientation order, the full prompt sequence, and the privacy notice. - -The one trap worth stating up front: **do not set `RSR_NON_INTERACTIVE=1`**. It -stubs the shell builtin `read`, which also disables the loops that perform token -substitution — the run never terminates and substitutes nothing. Pipe answers to -stdin instead. ----- +This repository's own section (see `README.adoc`) is specialised for a template: +its sentence asks the assistant to create a new repository, and it keeps the +note on minting without a terminal (`RSR_NON_INTERACTIVE=1` with the answers in +the environment). diff --git a/docs/AI_INSTALLATION_GUIDE.adoc b/docs/AI_INSTALLATION_GUIDE.adoc index ceb61fea..c5fa17c1 100644 --- a/docs/AI_INSTALLATION_GUIDE.adoc +++ b/docs/AI_INSTALLATION_GUIDE.adoc @@ -18,7 +18,7 @@ Read, in this order, before running anything: . `*_chora.deed` (the repo deed) — the universal AI entry point at the repository root. . `CLAUDE.md` — the generated arrival pack (estate doctrine + repo identity). -. `.machine_readable/descriptiles/STATE.a2ml` — current phase and completion. +. `docs/status/ROADMAP.adoc` — milestones, blockers and next actions (phase and maturity are in the deed's `(status)` and `(maturity)` clauses; `just state-phase` prints them). Do not infer the repository's purpose from its name. If a fact is not written down, record it as `UNASSIGNED` rather than inventing it. @@ -50,49 +50,59 @@ just repo-init # or: just repo-init identity, writes the provenance files, and removes the template-only directories. -[WARNING] +[NOTE] ==== -**Do not set `RSR_NON_INTERACTIVE=1`.** It stubs the shell builtin `read` -globally, which also disables the two `while read -r file` loops that drive -substitution. The result is an infinite loop that performs zero substitution — -it does not fail, it never terminates. +**Without a terminal, set `RSR_NON_INTERACTIVE=1` and answer through the +environment.** Each prompt reads the variable named in the table below; the +recipe keeps that variable's value from the environment, or leaves it empty, and +never touches stdin. `PROJECT_NAME`, `REPO`, `OWNER`, `AUTHOR` and `AUTHOR_EMAIL` +are required; an unset optional answer takes its default. -Drive it non-interactively by **piping answers to stdin** instead. Real `read` -stays intact, so the data loops work. +[source,bash] +---- +RSR_NON_INTERACTIVE=1 PROJECT_NAME="My Project" REPO=my-project \ + OWNER=my-org AUTHOR="My Name" AUTHOR_EMAIL=me@example.org \ + just repo-init +---- + +Until 2026-10-14 this mode stubbed the `read` builtin for the whole recipe, so +the substitution loops never terminated, and this guide told agents to pipe +answers to stdin instead. Piping still works, in the order below. ==== The prompts, in order, are: -[cols="1,3",options="header"] +[cols="1,3,2",options="header"] |=== -| # | Prompt - -| 1 | Project name -| 2 | Repository slug — validated against `^[a-z0-9]+(-[a-z0-9]+)*$`; no capitals, spaces or underscores (it must be a valid Guix package name) -| 3 | Owner -| 4 | Author full name -| 5 | Author email -| 6 | Author organisation -| 7 | Previous/alternate email -| 8 | Project description -| 9 | Forge domain -| 10 | Security email -| 11 | Conduct email -| 12 | Project type -| 13 | Website URL (blank = default) -| 14 | OpenSSF Best Practices ID (blank = none) -| 15 | Service name (blank = default) -| 16 | Primary port (blank = 8080) -| 17 | Container registry (blank = default) -| 18 | Proceed? — answer `y` +| # | Prompt | Environment variable + +| 1 | Project name | `PROJECT_NAME` +| 2 | Repository slug — validated against `^[a-z0-9]+(-[a-z0-9]+)*$`; no capitals, spaces or underscores (it must be a valid Guix package name) | `REPO` +| 3 | Owner | `OWNER` +| 4 | Author full name | `AUTHOR` +| 5 | Author email | `AUTHOR_EMAIL` +| 6 | Author organisation | `AUTHOR_ORG` +| 7 | Previous/alternate email | `AUTHOR_EMAIL_ALT` +| 8 | Author ORCID iD (blank = none; checked against its check digit) | `AUTHOR_ORCID` +| 9 | Project description | `PROJECT_DESCRIPTION` +| 10 | Forge domain | `FORGE` +| 11 | Security email | `SECURITY_EMAIL` +| 12 | Conduct email | `CONDUCT_EMAIL` +| 13 | Project type | `PROJECT_TYPE` +| 14 | Website URL (blank = default) | `WEBSITE` +| 15 | OpenSSF Best Practices ID (blank = none) | `OPENSSF_BP_ID` +| 16 | Service name (blank = default) | `SERVICE_NAME` +| 17 | Primary port (blank = 8080) | `PORT` +| 18 | Container registry (blank = default) | `REGISTRY` +| 19 | Proceed? — answer `y` | `CONFIRM` |=== [IMPORTANT] ==== -Prompts 15–17 are gated on the presence of the container directory, **not** on -the project type. The template always ships one, so they always fire. Supplying -only 15 answers makes `read` hit EOF, which returns 1 and kills the recipe under -`set -e`. +When piping, prompts 16–18 are gated on the presence of the container +directory, **not** on the project type. The template always ships one, so they +always fire. Supplying fewer answers than prompts makes `read` hit EOF, which +returns 1 and kills the recipe under `set -e`. ==== === 4. Verify the result diff --git a/docs/HYPATIA-RULE-ORDER.adoc b/docs/HYPATIA-RULE-ORDER.adoc new file mode 100644 index 00000000..2d3ecdbe --- /dev/null +++ b/docs/HYPATIA-RULE-ORDER.adoc @@ -0,0 +1,364 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) += Hypatia rule order, exemption layers and clash resolution +:toc: left +:toclevels: 3 +:sectnums: + +This is the repository's statement of *which* rule layer wins when two of them +speak about the same file, *which* clashes exist today, and *what resolves each +one*. It is local policy about tools that live elsewhere: Hypatia at +`hyperpolymath/hypatia@be98f74ce93df200752f3798efa1305bfa3e0e10` +(`lib/hypatia/scanner_suppression.ex`, `lib/rules/`), and the verdict grid at +`metadatastician/standards@8e48b1caade08a552646adeab66558ac43b4360d` +(`docs/VERDICT-GRID-SPEC.adoc`). + +Nothing here changes what a scanner finds. It states the order the layers are +applied in, so that "the finding is exempt" and "the finding was never looked +for" cannot be confused for each other. + +== Why this document exists + +Three facts, each verified against the pinned sources, made the ordering +ambiguous: + +. **Hypatia's exemption layers are a flat OR.** `ScannerSuppression.suppressed?/4` + returns true when *any* of the universal excludes, the built-in + `@default_exemptions`, or the repository's `.hypatia-ignore` matches. There is + no "narrow wins" rule and no negative entry, so a broader layer silently + decides for a narrower one. +. **The verdict grid grades a *set* of reporters, not a pipeline.** Its + precedence (purple > red > orange > yellow > blue > green) settles what a + *row* becomes, but not which scanner is allowed to contribute a row. +. **Every workflow claimed a relationship it did not have.** `fork-governance.yml` + said the report-backs fed "the Hypatia lane", `.gitbot-fleet/report-backs/README.md` + named a lane that did not exist, and `.github/workflows/README.adoc` said + Hypatia ran "in two places (on purpose)". All three were wrong, and nothing + could fail when they went wrong. + +== The layers, in the order they are applied + +[cols="1,3,3",options="header"] +|=== +|Order |Layer |Owner and enforcement + +|1 +|**Rule-level total ban** — `cicd_rules/banned_language_file` (Python, Go, Makefile, Gemfile) is refused by a dedicated clause that no exemption can reach. +|Hypatia (`scanner_suppression.ex`). Not this repository's to change. A repository cannot exempt it, and must not try. + +|2 +|**Universal excludes** — `.git/`, `node_modules/`, `_build/`, `deps/`, `target/`, `dist/`, `.hypatia-baseline.json`. +|Hypatia. Applied to every rule. + +|3 +|**Built-in default exemptions** — `@training_corpus_paths` (`lib/rules/`, `test/`, `tests/`, `scripts/fix-scripts/`, `.audittraining/`, `integration/fixtures/`) keyed per module, plus `benches/` for `code_safety` only. +|Hypatia. A repository cannot narrow these (see clash C7). + +|4 +|**Repository exemptions** — `.hypatia-ignore`, `/:`. +|This repository. Checked by `scripts/check-hypatia-ignore.sh`. + +|5 +|**Inline directives** — `# hypatia: allow / -- `, scoped to the line or file that carries it. +|This repository. Narrower than every layer above; cannot widen anything. + +|6 +|**Baseline** — `.hypatia-baseline.json`, applied at gate time only. +|The gate, never the grid. A baselined finding is still counted by the verdict grid (spec §Non-goals), so standing debt cannot masquerade as a clean scan. + +|7 +|**Grid normalisation** — severity words, `suppressed: true`, and the row's colour. +|The verdict grid. Presentation and grading only; it never suppresses a finding, and nothing it does can change what a scanner reported. +|=== + +The first three layers belong to Hypatia; only layers 4 and 5 are this +repository's to get wrong, which is why the checks in this repository target +those two and *state* the rest rather than restating them as if they were ours. + +=== What "first match wins" does not mean + +Layers 2–5 are **not** a cascade and not a precedence chain: Hypatia ORs them. +"Order" here is the order in which a reader (and the checker) must interpret a +suppression, and the order in which a *new* reviewer should look for the reason +a finding is missing. Where two layers genuinely conflict, the conflict is one +of the clashes below, and each has an explicit rule. + +== Clashes, with the rule that resolves each + +=== C1 — one scanner, two workflows + +*What was happening.* Hypatia ran in `hypatia-scan.yml` **and** in a +`hypatia-scan` job of `static-analysis-gate.yml`: two builds, two caches, two +"fail on critical" gates, two different output shapes, and no artifact either +of them could hand to the grid. + +*Rule.* A scanner runs in exactly one workflow, and that workflow owns its gate. +A second workflow may *read* its artifact; it may not re-run the tool. + +*Enforced by.* The absence of a Hypatia job in `static-analysis-gate.yml`, and +`scripts/check-workflow-edges.sh`, which fails the CICD Squabbler gate when a +producer's `name:`, artifact or pin stops matching what the reporter expects. + +=== C2 — one tool, two pins + +*What was happening.* `static-analysis-gate.yml` built panic-attack at +`b5530834…`; the standards Hypatia reusable pins `b689a74d…` (it carries an +upstream severity fix, standards#1306). Both were defensible; together they +meant the grid could grade two different binaries and call the result comparable. + +*Rule.* One pin per tool per repository. The verdict job names the same commit +the producing workflow builds (`--hypatia-ref`, `--panic-ref`, `--pons-ref`), and +a pin that appears at two different commits in two workflows is a failure, not a +choice. The standards reusable's different panic-attack pin is *recorded here*, +not silently copied: a repository that adopts the reusable adopts its pins, and +must then change `scripts/check-workflow-edges.sh`'s expectation deliberately. + +*Enforced by.* `scripts/check-workflow-edges.sh` (identical-ref check plus the +duplicate-pin scan). + +=== C3 — panicbot versus the direct panic-attack row + +*What was happening.* `.gitbot-fleet/enrolment.json` kept `panicbot` unenrolled +with the reason "leave it to the Hypatia lane's direct panic-attack row" — and +no such row existed, in any workflow. + +*Rule.* A scanner gets one row. panic-attack is graded by the grid's own +`panic-attack assail` row from `static-analysis-gate.yml` evidence, so +enrolling `panicbot` would report one scanner twice and produce two rows that can +disagree. `panicbot` stays unenrolled, and its enrolment reason now says *that*. +The grid now does render the direct row, so the cross-reference is no longer a +promise about the future. + +*Enforced by.* The enrolment manifest's own wording (checked for shape by +`scripts/verdict-grid-lane.sh validate --enrolment`) and the grid spec's +one-row-per-reporter rule. + +=== C4 — substring fragments suppress more than they name + +*What was happening.* `.hypatia-ignore` fragments are **substring** matches. An +entry for `x.yml` also silences `x.yml.bak`; `build/docs-seed/` also silences +`build/docs-seed-old/`. The file's stated intent ("whole-file/directory +exemptions") was narrower than its effect. + +*Rule.* Every fragment must end on a path boundary: either `/` (a directory) or a +last segment containing a dot (a file name). A raw substring is refused. + +*Enforced by.* `scripts/check-hypatia-ignore.sh`. + +=== C5 — a broad entry makes narrower ones dead + +*What was happening.* `workflow_audit/wrong_sha_pin:.github/workflows/` exempts +the rule for every workflow, so any narrower `wrong_sha_pin` entry — added in +good faith by a later author — would be dead code that reads as a considered +decision. + +*Rule.* An entry whose (module, type, path) is already covered by a broader entry +for the same module (same type or `*`, and a path fragment the narrower one +contains) is refused. If the broad exemption is right, the narrow entry goes; if +the narrow exemption is right, the broad one goes. + +*Enforced by.* `scripts/check-hypatia-ignore.sh`. + +=== C6 — an exemption outlives the file it names + +*What was happening.* Nothing tied an entry to the path it named. After a rename +the entry kept suppressing a path that no longer existed — or, if the rename +produced the same prefix, a different file. + +*Rule.* The path a fragment names must exist in the tree. A stale entry is +refused, and its removal is a visible diff rather than silent rot. + +*Enforced by.* `scripts/check-hypatia-ignore.sh`. + +=== C7 — a repository cannot narrow a built-in default + +*What is happening.* Layers 3 and 4 are OR'd: the built-in +`@training_corpus_paths` exempts `tests/` from `security_errors`, and no +`.hypatia-ignore` entry can *un*-exempt it. This repository cannot express "scan +`tests/` for secrets" locally. + +*Rule.* Do not duplicate, and do not pretend. The repository must not add an +entry that restates a default (it would read as local policy when it is not), and +must not claim a narrowing it cannot make. Where a narrower exemption is +genuinely needed, use an inline directive (layer 5), which is line-scoped. +Where an *un-suppression* is needed, that is a change in Hypatia — an upstream +issue, not a local workaround. + +*Enforced by.* Review; recorded here because the checker cannot see the +other repository's defaults. + +=== C8 — the reporter must not re-gate + +*What was happening.* `fork-governance.yml` read the fleet job's result, printed +it in a table, and then failed on DEED/K9 only — so a fleet failure was +invisible in the one place a reader looked. Its `jq '… | .findings | length'` +loop could also abort the whole summary on a malformed envelope, skipping the +final check. + +*Rule.* The reporter never gates on findings: each producer owns its own gate, +and one finding must not be able to block a pull request twice. A failed +producer is visible as its own red check and as orange rows in the grid — those +two facts are the reporting, and the reporter does not repeat them as a third. +The lane writes its summary without parsing envelope fields it does not own. + +*Enforced by.* `fork-governance.yml`'s verdict job (which fails only on +DEED/K9), and the grid's own grading (`orange` for missing evidence). + +== Evidence and reason (e/r) across the pipeline + +A row is only gradeable when the evidence says *two* things: how bad the worst +finding is (the grade) and how that was established (the reason). The rule +adopted here, per scanner: + +[cols="1,2,2",options="header"] +|=== +|Reporter |Grade comes from |Reason/evidence carried + +|Hypatia +|`severity` on the relativised findings array +|`reason` (or `message`/`type`) per finding, `rule_module` and `type` for identity + +|panic-attack +|`report.weak_points[].severity`, `suppressed: true` excluded +|`description` per weak point; the envelope's `status`/`reason` say whether the scan ran at all + +|pons asinorum +|`report.findings[].severity` (`ERROR`/`WARN`/`INFO`) +|`evidence` class and `tier` per finding, carried into the message so a heuristic is never read as a proof + +|gitbot-fleet member +|`findings[].severity` in the report-back envelope +|`rule_id` and `message` per finding; `status`/`reason` at the envelope +|=== + +Three consequences, all enforced at the boundary rather than trusted: + +* **A status envelope is mandatory.** A bare findings array cannot distinguish + "ran and found nothing" from "never ran", so `panic-attack-findings.json` and + `pons-findings.json` are envelopes (`status`, `tool`, `ref`, `reason`, + `exit_code`, `report`). `scripts/verdict-grid-lane.sh validate` refuses a bare + array by name. +* **An unknown severity word is reported, not silently graded.** The grid makes + the row orange; the lane's `validate` step names the offending words first, so + the reason reaches the log even when the grid cannot render. +* **A finding without a reason is still a finding.** The severity decides the + colour; the missing reason is a warning attached to the evidence file, never a + reason to drop the finding. + +== GitBot design and operation + +The templates' rules for the fleet, each matching the grid spec: + +. **One row per reporter.** A member that is a wrapper around a scanner already + reporting (C3) stays unenrolled. +. **Enrolment is a claim about *this* repository**, with a reason for every + member that does not apply. `enrolled: false` without a reason is not + expressible in the manifest, and `scripts/verdict-grid-lane.sh validate` + warns when one appears. +. **No report-back is orange, never green.** An enrolled member whose envelope + is absent renders "enrolled, but no report-back was received". A committed + placeholder envelope would be stale evidence about an older commit, so + `.gitbot-fleet/report-backs/` stays empty in git and is filled only at render + time from the `fleet-report-backs` artifact. +. **A failed fleet job is not a failed verdict** (C8): its rows go orange and its + own check goes red. +. **Severity words normalise; unknown words make the row orange.** The member's + own vocabulary (`error`, `warning`, `info`, `suggestion`) is accepted. + +== What this document does *not* enforce + +Honesty about the limits, because each of these has been assumed "checked" +somewhere before: + +* the built-in default exemptions (layer 3) — they live in Hypatia, and C7 is + stated, not enforced; +* that a stated reason is *true*, only that one is present; +* that a fleet adapter writes the envelope shape the spec defines — the fleet is + a separate repository at a pinned commit; +* that the renderer's recorded sha256 stays current. A stale digest turns every + render orange with the mismatch named, which is loud on purpose: it is the + one failure mode where a wrong *renderer* would otherwise look like a clean + repository. + +== The order is a contract, not only a description + +The table above is prose, and prose does not fail a build. The order, the +ownership of each concern, the clash resolutions and the pins are therefore +restated in `.machine_readable/policies/hypatia-rule-order.json` and checked by +`scripts/check-hypatia-rule-order.sh` (lane: *Hypatia rule order & clash +resolution*, in `scripts/run-proven-suite.sh`). + +The checker refuses: + +[cols="1,3"] +|=== +|Refused |Because + +|two layers with one `rank` +|a duplicate rank leaves which of the two wins to the reader + +|a `rank` sequence with a hole, or written out of order +|the document *is* the sequence; a gap invites a layer to be inserted where it +cannot be seen + +|a layer with no `overrides` +|a layer that states nothing is an OR, not a cascade, and that has to be a +decision rather than an omission + +|a layer id used twice, a `concern` declared twice, a `clash` declared twice +|a duplicated row reads as two rules and is one + +|a `concern` with no owner, or owned by a path that does not exist +|this is exactly how Hypatia came to be run by two workflows (C1) + +|an `owner` outside `hypatia \| this-repository \| the-gate \| the-grid` +|the four parties are the whole vocabulary; a fifth name means the model has +changed and this document has not + +|a `clash` with no `resolution` +|C3 and C5 were both "somebody will notice"; nobody did + +|a module exempted in `.hypatia-ignore` that `observed_modules` does not +classify, or a classification for a module the ignore file no longer mentions +|the policy and the file it describes drift in both directions, and both are +silent + +|a module classified under a layer whose `repository_can_change` is `false` +|an exemption cannot live in a layer this repository may not edit (C7) + +|a `scanner.commit`, `grid.commit`, `renderer_sha256` or `library_sha256` that +disagrees with `hypatia-scan.yml` or `scripts/verdict-grid-lane.sh` +|a policy pin that agrees only with itself proves nothing + +|a workflow with no pin at all +|absent evidence is a failure, not a pass +|=== + +The suite that proves the checker fires is +`tests/workflows/hypatia_rule_order_test.sh`: 44 checks, one mutation per +refusal above, run against a copy of the real policy. Two harness defects it +found in its own first draft are worth recording, because both are the kind of +thing that makes a green test meaningless: + +* **`@tsv` cannot carry an empty field.** Tab is IFS whitespace, so an empty +`overrides` collapsed and the value that followed it shifted into its place — +the checker reported "no scope" for a missing `overrides` and would have passed +a layer that stated neither. The checker now reads one base64-encoded JSON +object per line and decodes each field by name. +* **`grep` in a `set -e` script exits before it can complain.** A workflow with +no `HYPATIA_SHA` made the extraction fail rather than the *check*, so a missing +pin exited 1 with no diagnostic — indistinguishable from the violations it was +supposed to report. The extractions are now `sed -nE ...p`, which succeeds on no +match and lets the failure be stated. + +=== Adding or changing a rule + +. Decide which layer it belongs to, by asking *who* may waive it: the scanner +(layers 1–3), this repository (4–6), or the grid (7). If two answers are +defensible, the rule is a clash and needs a `C` entry before it needs code. +. Add the layer entry to the policy with its `rank`, `overrides` and `owner`; +re-rank the ones below it so the sequence stays complete. +. If it replaces a mechanism, name the old one `duplicate_of` and make it +advisory — two advisory voices are noise, two blocking voices are C1. +. Run `bash scripts/check-hypatia-rule-order.sh .` and then the suite. A policy +change that no test exercises is a comment. diff --git a/docs/MAINTAINERS.adoc b/docs/MAINTAINERS.adoc index 3f1fad42..458fc55d 100644 --- a/docs/MAINTAINERS.adoc +++ b/docs/MAINTAINERS.adoc @@ -12,9 +12,9 @@ earlier duplicates at `.github/MAINTAINERS` and `docs/attribution/MAINTAINERS.ad |=== | Name | Role | Contact -| Jonathan D.A. Jewell +| {{AUTHOR}} | Lead Maintainer -| https://github.com/hyperpolymath[@hyperpolymath] +| https://github.com/{{OWNER}}[@{{OWNER}}] |=== == Responsibilities diff --git a/docs/README.adoc b/docs/README.adoc index 2e8c7126..dc7274f0 100644 --- a/docs/README.adoc +++ b/docs/README.adoc @@ -43,7 +43,6 @@ and CI fails if it goes stale, so prefer it over any hand-written listing. * link:governance/SOFTWARE-DEVELOPMENT-APPROACH.adoc[governance/SOFTWARE-DEVELOPMENT-APPROACH.adoc] * link:MAINTAINERS.adoc[MAINTAINERS.adoc] — the single maintainer roster. * link:GOVERNANCE.adoc[GOVERNANCE.adoc] — the governance model. -* link:epistemic-types-transition-review.adoc[epistemic-types transition review] — verified cross-references for the 2026-10-04 transition, the ownership split, and the prepared (unposted) issue updates. [NOTE] ==== diff --git a/docs/RSR_OUTLINE.adoc b/docs/RSR_OUTLINE.adoc index 9bbe401e..0341e181 100644 --- a/docs/RSR_OUTLINE.adoc +++ b/docs/RSR_OUTLINE.adoc @@ -32,7 +32,7 @@ This repository provides the standardized structure, configuration, and tooling * Bootstrap new projects with RSR compliance * Reference the standard directory structure -* Copy configuration templates (Justfile, STATE.a2ml, etc.) +* Copy configuration templates (Justfile, repo deed, `docs/status/ROADMAP.adoc`, etc.) == Quick Start @@ -78,7 +78,7 @@ just validate-rsr |Site-operations bundle; RFC-compliant metadata at `www/.well-known/` (security.txt, ai.txt, humans.txt) |`.machine_readable/` -|All machine-readable content: state files (6 a2ml), `bot_directives/`, `contractiles/` +|All machine-readable content: `ai/`, `bot_directives/`, `contractiles/` (state and descriptive facts are clauses of the root repo deed, `*_chora.deed`) |`docs/` |Documentation directory @@ -113,8 +113,8 @@ just validate-rsr |`*_chora.deed` (repo deed) |Universal AI agent entry point -|`AI.a2ml` -|Claude-specific instructions +|`.machine_readable/ai/README.adoc` +|AI agent instructions (including the Claude-specific ones) |`src/interface/Abi/` |Idris2 ABI definitions (Types, Layout, Foreign) @@ -134,7 +134,7 @@ The template Justfile provides: * **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` +* **Project state**: `just state-phase` (prints the deed's phase and maturity) * **Container support**: `just container-build`, `just container-push` * **CI matrix**: `just ci-matrix [stage] [depth]` @@ -183,7 +183,8 @@ hand-written tree that used to sit here it cannot go stale. * `Justfile` * `README.adoc` * `LICENSE` (MPL-2.0) -* `.machine_readable/descriptiles/STATE.a2ml` +* `*_chora.deed` (repo deed) +* `docs/status/ROADMAP.adoc` * `www/.well-known/security.txt` * `www/.well-known/ai.txt` * `www/.well-known/humans.txt` @@ -198,37 +199,23 @@ hand-written tree that used to sit here it cannot go stale. * npm, Bun, pnpm, yarn (use ) * Go (use Rust) -== STATE.a2ml +== Project State -The STATE.a2ml file tracks project state: +Project state is split between the repo deed and a journal: -[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 ----- +* **Repo deed** (`*_chora.deed`): the `(status …)` clause carries the + lifecycle phase (`:phase`, `:since`, and its `(history …)`); the + `(maturity …)` clause carries `:level`. Read them with + `scripts/deed-field.sh status phase` and + `scripts/deed-field.sh maturity level`, or `just state-phase`. +* **Journal** (`docs/status/ROADMAP.adoc`): milestones, blockers, next + actions and maintenance runs. + +There is no completion percentage: it is derivable from the milestones. == Badge Schema -Generate badges from STATE.a2ml: +Generate badges from the repo deed's `(maturity)` and `(status)` clauses: [source,bash] ---- @@ -241,7 +228,6 @@ See `docs/BADGE_SCHEMA.adoc` for the full badge taxonomy. This template is part of: -* **STATE.a2ml Ecosystem**: Conversation checkpoints * **RSR Framework**: Repository standards * **Consent-Aware-HTTP**: .well-known compliance * **Hypatia**: Neurosymbolic security scanning diff --git a/docs/SETUP.adoc b/docs/SETUP.adoc new file mode 100644 index 00000000..f2524419 --- /dev/null +++ b/docs/SETUP.adoc @@ -0,0 +1,215 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) += Setting up rsr-template-repo by hand +:toc: +:toclevels: 2 + +This is the complete manual route: every step, in order, with nothing assumed. +You do not need it if you use `./launcher.sh --setup` (or ask an AI, see +link:AI_INSTALLATION_GUIDE.adoc[AI_INSTALLATION_GUIDE.adoc]), but those do +exactly what is written here, so this page is also what to read when they stop. + +[horizontal] +Repository:: https://github.com/hyperpolymath/rsr-template-repo +Kind:: library (idris2, zig) +Toolchain declared in:: `mise.toml` (versions `latest`, made concrete in `mise.lock`), and +`build/manifest.scm` / `build/guix.scm` / `build/channels.scm` for Guix +Every command below is also a `just` recipe:: run `just` to list them + +[[prerequisites]] +== 1. Prerequisites + +You need three things from your operating system. Everything else is installed +for you in step 3. + +[cols="1,2,3"] +|=== +|Tool |Why |Install + +|git +|to fetch the repository +|Fedora `sudo dnf install git` · Debian/Ubuntu `sudo apt install git` · macOS `xcode-select --install` · Windows `winget install Git.Git` + +|a C toolchain +|some language toolchains link native code +|Fedora `sudo dnf install gcc` · Debian/Ubuntu `sudo apt install build-essential` · macOS (included with the Xcode tools above) · Windows: use WSL2 + +|mise +|installs every other tool at the version this repo declares +|macOS `brew install mise` · Fedora `sudo dnf copr enable jdxcode/mise && sudo dnf install mise` · Windows `winget install jdx.mise` · Debian/Ubuntu and the rest: https://mise.jdx.dev/installing-mise.html — or download the installer, read it, then run it: `curl -fsSLo mise-install.sh https://mise.run && less mise-install.sh && sh mise-install.sh`. Then follow the one line it prints to activate it in your shell +|=== + +NOTE: On Windows, use WSL2 (`wsl --install`) and follow the Linux steps inside +it. The launcher detects the platform and says so in `./launcher.sh --version`. + +=== System packages for Idris2 + +Idris2 is built by pack on top of Chez Scheme and GMP, which come from your OS: + +* Fedora: `sudo dnf install chez-scheme gmp-devel` +* Debian/Ubuntu: `sudo apt install chezscheme libgmp-dev` +* macOS: `brew install chezscheme gmp` + +The Guix development shell (`build/manifest.scm`) already includes both. + +== 2. Get the code + +[source,bash] +---- +git clone https://github.com/hyperpolymath/rsr-template-repo.git +cd rsr-template-repo +---- + +Or with OPSM, the odds-and-sods package manager (see <>): +`opsm install https://github.com/hyperpolymath/rsr-template-repo.git --registry git` + +TIP: To start a *new* project from this template, use GitHub's *Use this template* +button (or clone as above), then run `just repo-init` before step 3; it fills every +placeholder token. The steps below work the same afterwards. + +== 3. Install the toolchain + +[source,bash] +---- +mise trust # allow this repository's mise.toml +mise install # installs everything mise.toml lists, at mise.lock's versions +---- + +That installs: + +[cols="1,2,3"] +|=== +|Language |Tools |If mise cannot supply it + +|idris2 |`idris2` |not a mise tool: install pack (https://github.com/stefan-hoeck/idris2-pack#installation), then `pack install-app idris2` +|zig |`zig` |https://ziglang.org/download/ or Guix `zig` +|(recipes) |`just`, `shellcheck` |your OS package manager, e.g. `dnf install just ShellCheck` +|=== + +`just` itself is installed by `mise install`. Without mise, install just from your +OS instead (`dnf install just`, `brew install just`, `cargo install just`); this +repository needs just 1.42 or newer. + +== 4. Set it up + +[source,bash] +---- +just setup +---- + +`just setup` repeats step 3 (harmless), fetches this repository's own +dependencies (idris2, zig), and finishes by running `just doctor`. + +== 5. Check it + +[source,bash] +---- +just doctor # PASS / WARN / FAIL for every requirement, with the fix for each +---- + +`just doctor` exits 0 when nothing FAILs. A WARN is advice, not a failure. +Every code it prints is explained in <>. + +== 6. Use it + +[source,bash] +---- +just build # build +just test # run the tests +just bench # run the benchmarks (says N/A when there are none) +just eval # tests + benchmarks with timings, saved under .eval/ +just run # run it (says N/A for a library) +just config-show # where the toolchain and config are declared +---- + +Anything that does not apply to a library says so and exits 0; nothing is faked. + +== 7. Keep it current + +[source,bash] +---- +just toolchain-refresh # mise up --bump, re-lock mise.lock, re-pin build/channels.scm +just heal # re-apply safe fixes if something drifted +---- + +[[guix]] +== The Guix route (alternative to steps 3–4) + +With GNU Guix installed you can skip mise for everything Guix packages: + +[source,bash] +---- +guix shell -m build/manifest.scm # the development shell +guix time-machine -C build/channels.scm -- shell -m build/manifest.scm # the exact, pinned Guix +guix build -f build/guix.scm # the package +---- + +Tools Guix does not package: idris2 (via pack). The Guix shell includes mise, so +inside it run `mise install` for those. `just dev-shell` picks Guix when it is present and mise +when it is not. + +[[opsm]] +== OPSM (odds-and-sods package manager) + +[source,bash] +---- +opsm install https://github.com/hyperpolymath/rsr-template-repo.git --registry git +---- + +rsr-template-repo has no registry package, so OPSM fetches it through its git +adapter; then provision it with `./launcher.sh --setup`. To get OPSM itself +(Erlang/OTP 26+ and Elixir 1.16+ required): + +[source,bash] +---- +git clone https://github.com/hyperpolymath/odds-and-sods-package-manager.git +cd odds-and-sods-package-manager/opsm_ex +mix deps.get && mix escript.build +install -m 0755 opsm ~/.local/bin/opsm +opsm --version +---- + +`just opsm` prints the same instructions. + +[[troubleshooting]] +== Troubleshooting + +Run `just doctor`, find the code it printed, apply the fix. `just heal` applies +every fix marked *auto* for you. + +[cols="1,3,3,1"] +|=== +|Code |Meaning |Fix |Auto + +|PV-E01 |git is not installed |Install git (step 1) |no +|PV-E02 |just is missing or older than 1.42 |`mise use -g just@latest` |no +|PV-E03 |a tool in mise.toml is not installed |`just setup` (or `mise install`) |yes +|PV-E10 |a language toolchain binary is missing |`just setup`; the doctor line names the manual route |yes, via mise +|PV-E11 |a system dependency from the provisioning deed is missing |install it from your OS (see <>) |no +|PV-E20 |mise.toml is missing |restore it: `git checkout -- mise.toml` |no +|PV-E27 |launcher.sh is not executable |`chmod +x launcher.sh` |yes +|PV-E40 |neither Guix nor mise is installed, so there is no dev shell |install mise (step 1) |no +|PV-E41 |`just toolchain-refresh` could not regenerate `build/guix/crates.scm`: the Guix crate importer defined fewer crates than `Cargo.lock` lists (often a network failure or a crate not yet on crates.io) |re-run `just toolchain-refresh`; the error is printed after the code. The old file is kept, so the build is unaffected |no +|PV-E50 |this repository's own `doctor-local` checks failed |read the output above the summary line; the recipe is in the Justfile |no +|PV-E51 |`build/just/doctor-local.sh` exited before its end (an `exit` or a failing command under `set -e`) |the doctor names the exit status; fix the script so it reports with pass/warn/fail instead of exiting |no +|PV-W01 |mise is not installed |install mise (step 1) |no +|PV-W20 |mise.lock is missing, so `latest` is not concrete |`just toolchain-refresh` |yes +|PV-W21 |both mise.toml and .mise.toml exist |merge into mise.toml, delete .mise.toml |no +|PV-W22 |a .tool-versions file competes with mise.toml |fold it into mise.toml |no +|PV-W23 |a mise config (mise.toml, .mise.toml, .tool-versions) pins a tool the estate does not use, or an npm:/pipx:/pip:/go: backend |remove that line |no +|PV-W24 |a Guix file is an unfilled template |regenerate it (maintainers: `provision-set realign`) |no +|PV-W25 |guix.scm is missing |as PV-W24 |no +|PV-W26 |manifest.scm is missing |as PV-W24; mise still works |no +|PV-W27 |launcher.sh is missing |as PV-W24 |no +|PV-W28 |a setup document is missing |as PV-W24 |no +|PV-W29 |a setup document still holds unfilled template slots |replace each `__SPEC_…__` slot with the facts for this repository |no +|PV-W30 |a Deno manifest (`deno.json`, `deno.jsonc`, `import_map.json`) exists |a notice, not a fault: Deno is permitted (tier 2) and reads `package.json`, which stays the one manifest |no +|PV-W31 |Nix files remain |use Guix |no +|PV-W32 |a Makefile remains |use the Justfile |no +|PV-W33 |Python files remain |not an estate language |no +|PV-W34 |npm/yarn/TypeScript files remain (`package-lock.json`, `yarn.lock`, `tsconfig.json`) |keep `package.json`, and let `js-runtimes regen` write `bun.lock`, `deno.lock` and `pnpm-lock.yaml` |no +|PV-W35 |both guix.scm and build/guix.scm exist |keep one; the engine uses build/ |no +|=== + +Still stuck? `just doctor > doctor.txt 2>&1` and open an issue at +https://github.com/hyperpolymath/rsr-template-repo/issues with that file attached. diff --git a/docs/architecture/REPOSITORY-MAP.adoc b/docs/architecture/REPOSITORY-MAP.adoc index d7848e20..b5622efa 100644 --- a/docs/architecture/REPOSITORY-MAP.adoc +++ b/docs/architecture/REPOSITORY-MAP.adoc @@ -23,11 +23,11 @@ predecessors did. | `.clinerules` | yes -| AI editor rules. Cline/Cursor/Windsurf read these from the project +| AI editor rules. Cline reads them from the project ROOT, so the copies formerly under .machine_readable/ai/ were inert (.cursorrules and .windsurfrules were retired 2026-10-26) -| `.cursorrules` -| yes -| ROOT, so the copies formerly under .machine_readable/ai/ were inert. +| `.coderabbit.yaml` +| optional +| CodeRabbit reads its config from the root only; pins Docstring Coverage to mode: warning (estate decision, not a vendor default). Optional: only the template and the repos whose rulesets require the CodeRabbit context carry it | `.devcontainer/` | optional @@ -45,6 +45,10 @@ predecessors did. | yes | - +| `.gitbot-fleet/` +| yes +| fleet enrolment manifest + report-backs/ (empty in git; filled per run by the fork-governance fleet job). Read by the Hypatia verdict grid at this path and no other + | `.github/` | yes | community health + workflows (GitHub reads this path and no other) + versioned git hooks (.github/hooks/, wired via core.hooksPath) @@ -73,14 +77,6 @@ predecessors did. | yes | git reads .mailmap from the worktree root only -| `.tool-versions` -| yes -| - - -| `.windsurfrules` -| yes -| - - | `CHANGELOG.adoc` | yes | AsciiDoc is the estate-standard documentation format @@ -91,36 +87,40 @@ predecessors did. | `CLAUDE.md` | yes -| generated arrival pack; the generator, pre-commit and Claude Code all read it from the ROOT (do not hand-edit; edit the a2ml source) +| generated arrival pack; the generator, pre-commit and Claude Code all read it from the ROOT (do not hand-edit; edit the repo deed) -| `CONTRIBUTING.adoc` +| `CODE_OF_CONDUCT.adoc` | optional -| estate docs gate (standards scripts/check-docs-presence.sh) requires CONTRIBUTING at the ROOT; this is the copy it verifies +| community health file; GitHub accepts it at root, docs/ or .github/ -| `GEMINI.md` +| `CONTRIBUTING.adoc` | optional -| pointer to CLAUDE.md for repos without AGENTS.md yet +| estate docs gate (standards scripts/check-docs-presence.sh) requires CONTRIBUTING at the ROOT; this is the copy it verifies | `Justfile` | yes | thin; delegates phases to build/just/*.just | `LICENSE` +| optional +| forge-facing copy of LICENSES/MPL-2.0.txt. Optional, not required: + +| `LICENSE.adoc` | yes -| - +| the licence (MPL-2.0); renamed from LICENSE to the estate AsciiDoc format 2026-10-26 | `LICENSES/` | yes | REUSE licence texts, dual-licence model (code MPL-2.0 / docs CC-BY-SA-4.0) -| `PROOF-STATUS.adoc` -| yes -| project theorem evidence and fragment limits, linked from README.adoc - | `README.adoc` | yes | - +| `SUPPORT.adoc` +| optional +| community health file; GitHub accepts it at root, docs/ or .github/ + | `archetypes/` | optional | template-only variation seam (ADR-0003); `just repo-init` removes it from minted repos @@ -153,9 +153,17 @@ predecessors did. | optional | optional feature packs +| `launcher.sh` +| yes +| --setup/--doctor/--heal/--ai-setup (launcher-standard 0.6.0); the one file a newcomer runs first + +| `mise.lock` +| yes +| makes latest concrete: version + per-platform checksum; mise reads it beside mise.toml + | `mise.toml` | yes -| pinned toolchains +| the toolchain: every tool at latest (PROVISIONING-STANDARD §4) | `rsr-template-repo_chora.deed` | yes @@ -165,10 +173,6 @@ predecessors did. | yes | repo helper scripts -| `secret-types.agda-lib` -| yes -| Agda discovers library descriptors at the project root - | `session/` | yes | dispatch.sh, custom-checks.k9.ncl, local-hooks.sh @@ -178,8 +182,8 @@ predecessors did. | only where the repo is analysed by SonarCloud | `src/` -| yes -| - +| optional +| source tree; optional for non-code/specification/governance repositories (issue #233, e.g. standards) | `tests/` | yes @@ -205,6 +209,8 @@ your own repo - but do not read their emptiness as neglect here. [cols="1"] |=== +| `.machine_readable/bot_directives/` +| `.machine_readable/descriptiles/anchors/` | `.machine_readable/scripts/verification/` | `docs/governance/audit/` | `docs/governance/audit/compliance/` @@ -218,7 +224,6 @@ your own repo - but do not read their emptiness as neglect here. | `docs/governance/planning/could/` | `docs/governance/planning/must/` | `docs/governance/planning/should/` -| `docs/reports/compliance/` | `docs/reports/maintenance/` | `docs/reports/performance/` | `docs/reports/quality/` diff --git a/docs/architecture/THREAT-MODEL.adoc b/docs/architecture/THREAT-MODEL.adoc index 76ca59a1..43d945d1 100644 --- a/docs/architecture/THREAT-MODEL.adoc +++ b/docs/architecture/THREAT-MODEL.adoc @@ -120,7 +120,7 @@ NOTE: See link:../STATE-VISUALIZER.adoc[STATE-VISUALIZER.adoc] for the full arch | 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 +| Secret rotation without record | CI/CD secrets | Low | Low | Low | Secret rotation logged in `docs/status/ROADMAP.adoc` (Maintenance runs) |=== diff --git a/docs/decisions/0001-adopt-rsr-standard.adoc b/docs/decisions/0001-adopt-rsr-standard.adoc index 45ec4413..cfcc68e9 100644 --- a/docs/decisions/0001-adopt-rsr-standard.adoc +++ b/docs/decisions/0001-adopt-rsr-standard.adoc @@ -4,6 +4,8 @@ // SPDX-License-Identifier: CC-BY-SA-4.0 // Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> +NOTE: Superseded in part (2026-10-06, rsr-template-repo#209): the `.a2ml` files named below no longer exist; their facts are clauses of the repo deed (`*_chora.deed`). + == 1. Adopt Rhodium Standard Repository (RSR) Template Date: 2026-02-14 @@ -50,6 +52,8 @@ The RSR template provides: CODE_OF_CONDUCT.md, LICENSE (MPL-2.0) - **Architecture Decision Records** in `docs/decisions/` +NOTE: 2026-10-02 — rsr-template-repo#209 retired STATE/META/ECOSYSTEM/AGENTIC/CLADE.a2ml; their content is now in the repo deed (`*_chora.deed`) and `docs/status/ROADMAP.adoc`. + New repositories are created by cloning the template: [source,bash] diff --git a/docs/decisions/0002-variant-contract.adoc b/docs/decisions/0002-variant-contract.adoc index dfed0ec5..80e16742 100644 --- a/docs/decisions/0002-variant-contract.adoc +++ b/docs/decisions/0002-variant-contract.adoc @@ -2,6 +2,8 @@ // Copyright (c) Jonathan D.A. Jewell = Architecture Decision Record: 0002-variant-contract +NOTE: Superseded in part (2026-10-06, rsr-template-repo#209): the `.a2ml` files named below no longer exist; their facts are clauses of the repo deed (`*_chora.deed`). The variant contract is the `(variant)` clause that `just repo-init` writes into a minted child's deed. + == 2. Variant templates declare a machine-readable contract with their parent Date: 2026-07-07 diff --git a/docs/decisions/0003-forge-and-sustain-lifecycle.adoc b/docs/decisions/0003-forge-and-sustain-lifecycle.adoc index 9726e04b..540fffce 100644 --- a/docs/decisions/0003-forge-and-sustain-lifecycle.adoc +++ b/docs/decisions/0003-forge-and-sustain-lifecycle.adoc @@ -2,6 +2,8 @@ // Copyright (c) Jonathan D.A. Jewell = Architecture Decision Record: 0003-forge-and-sustain-lifecycle +NOTE: Superseded in part (2026-10-06, rsr-template-repo#209): the `.a2ml` files named below no longer exist; their facts are clauses of the repo deed (`*_chora.deed`). `just repo-init` writes the `(rsr-profile)`, `(variant)` and `(provenance)` clauses into a minted child's deed, and an archetype is `archetypes//_praxis.deed`. + == 3. One lifecycle, one contract: Forge (mint → provision → configure → harness) and Sustain (corrective / adaptive / perfective / preventive) Date: 2026-07-21 diff --git a/docs/governance/CRG-AUDIT-TEMPLATE.adoc b/docs/governance/CRG-AUDIT-TEMPLATE.adoc index e56cbff5..192c5f93 100644 --- a/docs/governance/CRG-AUDIT-TEMPLATE.adoc +++ b/docs/governance/CRG-AUDIT-TEMPLATE.adoc @@ -24,7 +24,7 @@ Evaluates the `{{REPO}}` repository against - 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/descriptiles/STATE.a2ml` → `grade = ""` + * `docs/status/ROADMAP.adoc` → `Declared CRG grade: ` line * `docs/READINESS.md` (if present) → per-component grades * Third-party badges (Glama, OpenSSF, etc.) if any — note date and scope - Audit date: {{CURRENT_DATE}} @@ -64,8 +64,8 @@ Do *not* mark PRESENT without citing the path. | PRESENT / PARTIAL (count) / ABSENT | `.github/workflows/` -| `.machine_readable/descriptiles/` canonical A2ML -| PRESENT (STATE, META, ECOSYSTEM, AGENTIC, NEUROSYM, PLAYBOOK) / ABSENT +| `.machine_readable/descriptiles/` +| PRESENT (NEUROSYM, PLAYBOOK) / ABSENT | Layout matches CLAUDE.md invariant | `*_chora.deed` (repo deed) @@ -140,10 +140,10 @@ RSR compliance verdict: *met* / *partial* / *not met* — Grade D floor satisfie === Test matrix -Cite *from authoritative source* (STATE.a2ml or CI log). Do not re-count by -filesystem grep — grade the evidence that already exists. +Cite *from authoritative source* (`docs/status/ROADMAP.adoc` or CI log). Do not +re-count by filesystem grep — grade the evidence that already exists. -- `total-tests = N` (from `.machine_readable/descriptiles/STATE.a2ml` or CI). +- Test count N (from `docs/status/ROADMAP.adoc` 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. @@ -166,7 +166,7 @@ v2.0 C requires **per-file and per-directory orientation**. Evidence checklist: === Dogfooding / home-stable evidence -Cite STATE.a2ml `[dogfooding-status]`. For each line item: +Cite the `== Dogfooding status` section of `docs/status/ROADMAP.adoc`. For each line item: - WHAT was dogfooded (capability), - HOW (concrete use-path), - WHEN (date completed), @@ -180,15 +180,15 @@ Cite STATE.a2ml `[dogfooding-status]`. For each line item: === 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]`. +not catalogue listings. Populate the `docs/status/ROADMAP.adoc` sections named +below; internal-capability items belong in another roadmap section, *not* +under `== External targets`. -- STATE.a2ml `[external-targets]` — at least 6 diverse entries for B. +- ROADMAP.adoc `== 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 +- ROADMAP.adoc `== Issues fed back` — closed-issue trail with external-reporter label for B. -- STATE.a2ml `[field-signal]` — multi-source external confirmation for A. +- ROADMAP.adoc `== 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*. @@ -196,7 +196,8 @@ a roadmap section, *not* under `[external-targets]`. 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 +and either move it to `== External targets` in `docs/status/ROADMAP.adoc` +or drop it. See the boj-server audit for a worked example (six items all re-classified as internal). == Grade x Evidence Matrix @@ -222,7 +223,7 @@ audit for a worked example (six items all re-classified as internal). | D | ✓/✗ -| All RSR structural requirements met; N tests; scope documented in STATE.a2ml, ROADMAP.adoc +| All RSR structural requirements met; N tests; scope documented in the repo deed, ROADMAP.adoc | ... | C @@ -280,7 +281,8 @@ them. Examples: == Related Files - `docs/READINESS.md` — per-component table. Note v1.0-vs-v2.0 schema alignment. -- `.machine_readable/descriptiles/STATE.a2ml` — authoritative self-declared state. +- `*_chora.deed` (repo deed) — authoritative phase and maturity (`(status)`, `(maturity)`). +- `docs/status/ROADMAP.adoc` — milestones, evidence and the declared CRG grade. - `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. diff --git a/docs/governance/CRG-CRITERIA.a2ml b/docs/governance/CRG-CRITERIA.a2ml deleted file mode 100644 index 61625859..00000000 --- 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/MAINTENANCE-CHECKLIST.adoc b/docs/governance/MAINTENANCE-CHECKLIST.adoc index 48149d86..7550b1e6 100644 --- a/docs/governance/MAINTENANCE-CHECKLIST.adoc +++ b/docs/governance/MAINTENANCE-CHECKLIST.adoc @@ -8,7 +8,7 @@ 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) +- `*_chora.deed` `(policies (software-development-approach))` (machine-readable) ## Canonical Repo Baseline (Final) @@ -91,8 +91,8 @@ Run this pass at the end of a corrective/adaptive/perfective cycle: - `MAINTAINER` in root - `.github/CODEOWNERS` - [ ] Keep machine-readable canonical structure under `.machine_readable/`: - - state/meta/ecosystem files (`*.a2ml` or repo standard) - - `anchors/ANCHOR.a2ml` + - state/meta/ecosystem/anchor facts as clauses of the root repo deed + (`*_chora.deed`: `(status)`, `(meta)`, `(ecosystem)`, `(anchor)`); no `.a2ml` files - `contractiles/` (`must`, `trust`, `intend`, and related) - `ai/` for AI guidance files - `bot_directives/` for bot control files @@ -412,7 +412,7 @@ Add these checks for language/compiler repositories with formal ABI/FFI constrai - [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] Machine-readable docs synchronized (repo deed `(status)`, `(meta)`, `(ecosystem)` clauses, 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. diff --git a/docs/governance/TEMPLATE-LINEAGE-AUDIT.adoc b/docs/governance/TEMPLATE-LINEAGE-AUDIT.adoc index ea015132..9c64d8ae 100644 --- a/docs/governance/TEMPLATE-LINEAGE-AUDIT.adoc +++ b/docs/governance/TEMPLATE-LINEAGE-AUDIT.adoc @@ -5,6 +5,8 @@ :toclevels: 3 :sectnums: +NOTE: Superseded in part (2026-10-06, rsr-template-repo#209): the `.a2ml` files named below no longer exist; their facts are clauses of the repo deed (`*_chora.deed`). + *Measured 2026-09-15 against the live estate.* This document records what the template's self-identity repair passes do, what they provably did *not* do to repositories minted before they existed, and — just as importantly — which of @@ -47,6 +49,8 @@ that it WAS the template, and would have reported its code analysis into the TEMPLATE's SonarCloud project. ____ +NOTE: 2026-10-02 — rsr-template-repo#209 retired STATE/META/ECOSYSTEM/AGENTIC/CLADE.a2ml; their content is now in the repo deed (`*_chora.deed`) and `docs/status/ROADMAP.adoc`. + The ordinary mint path rewrites `{{OWNER}}`, `{{REPO}}` and friends. Those tokens *are* consumed widely — 56 files in this repository, including the README badge block, `CITATION.cff`, `.github/CODEOWNERS`, @@ -188,6 +192,8 @@ Both `Justfile:24` and `.machine_readable/contractiles/Justfile:24` declare `canonical-name = "rsr-julia-library-template-repo"`. `OWNER :=` is correct in both files. +NOTE: 2026-10-02 — in this template, rsr-template-repo#209 retired CLADE.a2ml; the canonical name now lives in the repo deed header (`:canonical-name`). + *Severity is lower than it appears.* Across every `Justfile` and `*.just` in that repository there are *zero* `{{OWNER}}` or `{{REPO}}` interpolations, so neither variable is consumed by any recipe. This is a wrong self-description diff --git a/docs/governance/TEMPLATE-STANDARDS-AUDIT.adoc b/docs/governance/TEMPLATE-STANDARDS-AUDIT.adoc index ea823028..079d2aac 100644 --- a/docs/governance/TEMPLATE-STANDARDS-AUDIT.adoc +++ b/docs/governance/TEMPLATE-STANDARDS-AUDIT.adoc @@ -7,6 +7,8 @@ v1.0, 2026-04-07 :toclevels: 3 :sectnums: +NOTE: Superseded in part (2026-10-06, rsr-template-repo#209): the `.a2ml` files named below no longer exist; their facts are clauses of the repo deed (`*_chora.deed`). + == Scope And Inventory Audit scope: @@ -28,7 +30,7 @@ Inventory snapshot at audit time: | Placeholder badge tokens in README | `README.adoc` -| `{{OPENSSF_PROJECT_ID}}`, `{{OWNER}}`, `{{REPO}}` +| `OPENSSF_PROJECT_ID`, `OWNER`, `REPO` (README badge token names) | placeholder | Template placeholders are intentional pre-bootstrap content. | Keep; document clearly as template tokens. @@ -155,7 +157,7 @@ Current status: rsr-template-repo/ README.adoc AUDIT.adoc - 0-AI-MANIFEST.a2ml + rsr-template-repo_chora.deed EXPLAINME.adoc Justfile coordination.k9 diff --git a/docs/governance/TSDM.a2ml b/docs/governance/TSDM.a2ml deleted file mode 100644 index f27036cc..00000000 --- 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 index 42899ec6..bbb4ba16 100644 --- a/docs/governance/TSDM.adoc +++ b/docs/governance/TSDM.adoc @@ -25,4 +25,4 @@ TSDM is a three-dimensional governance framework designed for high-assurance, lo == 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. +TSDM is the operational core of the Rhodium Standard. Every task in the `Justfile` and every state change in the repo deed (`*_chora.deed` `(status)` / `(maturity)`) or `docs/status/ROADMAP.adoc` should be justifiable within this framework. diff --git a/docs/onboarding/llm-warmup-dev.adoc b/docs/onboarding/llm-warmup-dev.adoc index f12ada86..8b65d04a 100644 --- a/docs/onboarding/llm-warmup-dev.adoc +++ b/docs/onboarding/llm-warmup-dev.adoc @@ -1,21 +1,87 @@ // SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) Jonathan D.A. Jewell -= LLM Warmup — rsr-template-repo (Developer) +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) += LLM warm-up — rsr-template-repo (developer) -== What is rsr-template-repo? +Paste this into an AI assistant before changing code in rsr-template-repo. -See `README.adoc` for overview. +== Orientation -== Key Commands +rsr-template-repo (https://github.com/hyperpolymath/rsr-template-repo): a library in idris2, zig. -* `just setup` — set up development environment -* `just build` — build the project -* `just test` — run tests -* `just doctor` — diagnose issues -* `just heal` — attempt auto-repair +The template's own code is the ABI/FFI seam that every minted repo inherits: -== Quick Context +* `src/interface/Abi/` + `src/interface/abi.ipkg`: Idris2 types and layout proofs + (the ABI owns the contract). +* `src/interface/ffi/`: the Zig implementation (`build.zig`, `src/main.zig`, + `test/integration_test.zig`), exporting C symbols named `_*`. +* `src/interface/generated/`: C headers generated from the ABI. -* License: MPL-2.0 -* Part of hyperpolymath ecosystem -* See `EXPLAINME.adoc` for architecture +Everything else is scaffolding: `.machine_readable/` (descriptiles, contractiles, +policies), `build/just/*.just` (the task phases the root `Justfile` imports), and +`.github/workflows/` (the CI a minted repo starts with). + +== Toolchain + +* Declared in `mise.toml` (specs `latest`), made concrete in `mise.lock`. Never + hand-edit versions; `just toolchain-refresh` bumps and re-locks. +* Guix alternative: `build/manifest.scm` (dev shell), `build/guix.scm` (package), + `build/channels.scm` (pinned Guix). `just dev-shell` picks whichever is present. +* `just` ≥ 1.42. The shared recipes live in `build/just/provision.just` + (`mod provision`); root recipes in `Justfile` override them. + +== The loop + +[source,bash] +---- +just setup # once +just build +just test +just bench # N/A when there are no benchmarks +just eval # test + bench with timings, logged under .eval/ +just lint && just fmt +just doctor # before you open a PR +---- + +Template-specific commands: + +[source,bash] +---- +just repo-init # instantiate: fills every placeholder token, then validates +just validate # RSR shape + metadata + AI-install completeness +just quality # fmt-check, lint, test +just test-all # test, e2e, aspect, bench, readiness +just repo-map # regenerate docs/architecture/REPOSITORY-MAP.adoc (CI checks it) +---- + +The golden path is `just test && just quality`. In the template itself `test` and +`lint` fail on the placeholder tokens in `src/interface/ffi/src/main.zig`; that is +deliberate. Test a change to the FFI in a scratch copy after `repo-init`. + +== Where things are + +* Top level: `archetypes/ benches/ build/ ci/ docs/ examples/ features/ LICENSES/ + scripts/ session/ src/ tests/ verification/ www/`. The root file list is fenced by + `.machine_readable/root-allow.txt`; a new root file needs a line there. +* `build/just/`: provisioning (`provision.just`, `provision-lib.sh`), `repo-init.just`, + `validate.just`, and the other imported phases. +* `build/guix.scm`, `build/manifest.scm`, `build/channels.scm`: the Guix route. +* `tests/`: e2e, aspect, shape and workflow checks. `benches/`: benchmark harness. +* `docs/`: SETUP, AI installation guide, onboarding warm-ups, architecture map. + +== Rules that bite + +* Languages: JavaScript runs Bun > Deno > pnpm > npm from one `package.json`; + after `bun add`, run `js-runtimes regen`. Python, TypeScript, ReScript, Nix, + Go and Makefiles are banned. New code follows the repository's existing languages. +* Every new file carries an SPDX header: `MPL-2.0` for code and config, + `CC-BY-SA-4.0` for prose docs. Never change an existing file's licence. +* Commits are signed; history is linear (squash merges). + +* `.machine_readable/contractiles/Justfile` must stay byte-identical to the root + `Justfile`; copy it after every edit. +* Never put literal placeholder tokens in prose that `repo-init` will process: it + substitutes them. Write "placeholder token" instead. +* `build/` is not an artefact directory here: `just clean` deliberately leaves it, + because `build/just/repo-init.just` lives there. +* Descriptile and policy facts are clauses of the repo deed (`*_chora.deed`), + read with `scripts/deed-field.sh`; A2ML is retired and no `.a2ml` file may exist. diff --git a/docs/onboarding/llm-warmup-maintainer.adoc b/docs/onboarding/llm-warmup-maintainer.adoc new file mode 100644 index 00000000..0ebbfac4 --- /dev/null +++ b/docs/onboarding/llm-warmup-maintainer.adoc @@ -0,0 +1,42 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) += LLM warm-up — rsr-template-repo (maintainer) + +Paste this into an AI assistant before release, CI or governance work on +rsr-template-repo. Read `llm-warmup-dev.adoc` first; this adds what a maintainer owns. + +== The provisioning set + +This repository is provisioned from the estate canon +(https://github.com/hyperpolymath/standards, `3-practice/provisioning/`). +Repo-specific facts live in `.machine_readable/descriptiles/provisioning_praxis.deed`. +`provision-set realign` overwrites only the engine: `launcher.sh`, +`build/just/provision*.{just,sh}` and `channels.scm`; change behaviour through the +deed, never by hand-editing those. Everything else (`guix.scm` once real, +`manifest.scm`, `mise.toml`, the Justfile, `docs/` and these warm-ups) is minted +once and then belongs to this repository: keep it true as the code changes. + +== Keeping it current + +* `just toolchain-refresh` — `mise up --bump`, `mise lock`, re-pin `channels.scm`. + Commit the lock changes on their own. +* `just doctor` must be clean before a release; WARN codes are tracked, not ignored. +* The `provisioning-check` workflow reports drift from the canon. + +== Release + +A release is a signed tag `v` on `main`; pushing it runs `.github/workflows/release.yml`, which builds the release notes, publishes the GitHub release (`softprops/action-gh-release`) and attests build provenance. Bump `version` in the Justfile and `CITATION.cff` first, in the same PR. This repository is a GitHub *template*: a release changes what every new repository is born with, so re-run `./launcher.sh --doctor` and `bash build/just/provision-check.sh .` on a fresh clone before tagging. + +== CI and branch rules + +`main` is protected by a ruleset with these rule types: `required_signatures`, `required_linear_history`, `non_fast_forward`, `deletion`, `code_scanning`, `code_coverage` and `copilot_code_review` (read 2026-09-30; re-read with `gh api repos/hyperpolymath/rsr-template-repo/rules/branches/main`). Only squash merges are allowed and auto-merge is on. Every commit must be SSH-signed or the PR cannot land. The workflows under `.github/workflows/` are themselves the estate's reference copies: a change here propagates to every repository minted from the template, so change the canonical reusable in `hyperpolymath/standards` first and pin to it here. + +Rulesets can block a merge for reasons other than checks (review threads, +signatures, code owners): enumerate the ruleset's rule types before calling a PR +mergeable. + +== Decisions + +Owner rulings for the estate are recorded in `hyperpolymath/standards` +(issue #787 is the decision surface). Do not re-open a ruled question; cite it. +Rulings that bind this repository in particular: bun is the only JavaScript runtime (deno, TypeScript, ReScript, Python are banned), A2ML is retired (no `.a2ml` file may exist; descriptive and policy facts are clauses of the repo deed, `*_chora.deed`), and Justfile changes are mirrored in `.machine_readable/contractiles/Justfile`, which is kept byte-identical. diff --git a/docs/onboarding/llm-warmup-user.adoc b/docs/onboarding/llm-warmup-user.adoc index 2127530b..5d56ae79 100644 --- a/docs/onboarding/llm-warmup-user.adoc +++ b/docs/onboarding/llm-warmup-user.adoc @@ -1,21 +1,55 @@ // SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) Jonathan D.A. Jewell -= LLM Warmup — rsr-template-repo (User) +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) += LLM warm-up — rsr-template-repo (user) -== What is rsr-template-repo? +Paste this whole file into any AI assistant before asking it about +rsr-template-repo. It tells the assistant what the project is, how a person gets it +running, and where to look when something goes wrong. -See `README.adoc` for overview. +== What it is -== Key Commands +rsr-template-repo (https://github.com/hyperpolymath/rsr-template-repo) is a library written in idris2, zig. -* `just setup` — set up development environment -* `just build` — build the project -* `just test` — run tests -* `just doctor` — diagnose issues -* `just heal` — attempt auto-repair +It is not a project in its own right: it is the template every new hyperpolymath +repository is created from. It ships CI/CD, machine-readable metadata +(`.machine_readable/descriptiles/`), an AI gatekeeper deed +(`rsr-template-repo_chora.deed`), a typed ABI/FFI seam (Idris2 over Zig), Guix and +mise toolchains, and governance files, all passing the RSR validators before you +add a line of your own. -== Quick Context +== Getting it running -* License: MPL-2.0 -* Part of hyperpolymath ecosystem -* See `EXPLAINME.adoc` for architecture +The supported routes, in order of ease: + +. *Ask an AI*: follow `docs/AI_INSTALLATION_GUIDE.adoc` in the repository. +. *The launcher*: `git clone https://github.com/hyperpolymath/rsr-template-repo.git && cd rsr-template-repo && ./launcher.sh --setup` +. *By hand*: `docs/SETUP.adoc`, every step explained. + +Prerequisites are git, a C toolchain and mise; everything else is installed by +`mise install`, at the versions pinned in `mise.lock`. + +== Using it + +A person uses it to start a new repository: + +. On GitHub, *Use this template* (or clone it). +. In the new checkout, run `just repo-init`. It asks for the project name, owner, + author and licence contact (listed in `.machine_readable/ai/PLACEHOLDERS.adoc`), + replaces every placeholder token, then validates the result. `just repo-init + julia-library` applies the one archetype overlay shipped in `archetypes/`. +. Run `just validate` (structure + metadata) and `just doctor` (toolchain). + +An AI running `repo-init` sets `RSR_NON_INTERACTIVE=1` and passes the answers as +environment variables (see `docs/AI_INSTALLATION_GUIDE.adoc`), or pipes them to stdin. + +== When something is wrong + +Run `just doctor`. Every FAIL line carries a code (PV-E…) that is explained, with +its fix, in `docs/SETUP.adoc` §Troubleshooting. `just heal` applies the automatic +fixes. Do not guess an installer that the repository does not document. + +== What it touches + +Nothing leaves the machine. `mise install` and `just setup` install tools per-user +under the mise data directory; `just repo-init` rewrites files only inside the +checkout. No remote repository is created and nothing is pushed until you do it. diff --git a/docs/practice/AI-CONVENTIONS.adoc b/docs/practice/AI-CONVENTIONS.adoc index d960221b..a2e60d7f 100644 --- a/docs/practice/AI-CONVENTIONS.adoc +++ b/docs/practice/AI-CONVENTIONS.adoc @@ -12,12 +12,12 @@ Per-tool config files (.cursorrules, .clinerules, etc.) reference this document. === Session Startup 1. Read the repo deed (`*_chora.deed` at root) FIRST (mandatory gatekeeper). -2. Read `.machine_readable/descriptiles/STATE.a2ml` for current status and blockers. -3. Read `.machine_readable/descriptiles/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/descriptiles/AGENTIC.a2ml` for agent constraints. +2. Read `docs/status/ROADMAP.adoc` for blockers and next actions (phase and maturity are in the deed's `(status)` and `(maturity)` clauses). +3. Read the deed's `(anchor)` clause for canonical authority boundaries. +4. Read the deed's `(policies (maintenance-axes))` clause for maintenance/audit sequencing. +5. Read the deed's `(policies (maintenance-checklist))` clause for baseline controls. +6. Read the deed's `(policies (software-development-approach))` clause for execution order. +7. Read the deed's `(agentic)` clause for agent constraints. === License @@ -44,10 +44,11 @@ Per estate policy (hyperpolymath/standards `LICENCE-POLICY.adoc` Rule 1 + Addend === 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. +No `.a2ml` file may exist anywhere in this repository: the format is retired. +State, metadata, anchor and policy facts are clauses of the repo deed +(`*_chora.deed`) — `(status)`, `(maturity)`, `(meta)`, `(anchor)`, +`(neurosym)`, `(playbook)`, `(policies …)` — and the journal is +`docs/status/ROADMAP.adoc`. Never recreate them as separate files. === Banned Patterns @@ -94,9 +95,10 @@ Use `just` (Justfile) for all build, test, lint, and format tasks. === References - `*_chora.deed` (repo deed) -- universal AI entry point -- `.machine_readable/descriptiles/AGENTIC.a2ml` -- agent permissions and constraints -- `.machine_readable/descriptiles/STATE.a2ml` -- current project state -- `.machine_readable/descriptiles/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 +- `*_chora.deed` `(agentic)` -- agent permissions and constraints +- `*_chora.deed` `(status)` / `(maturity)` -- current phase and maturity +- `docs/status/ROADMAP.adoc` -- milestones, blockers, next actions +- `*_chora.deed` `(anchor)` -- canonical authority and policy boundary +- `*_chora.deed` `(policies (maintenance-axes))` -- canonical axis sequencing and audit requirements +- `*_chora.deed` `(policies (maintenance-checklist))` -- baseline maintenance checklist policy +- `*_chora.deed` `(policies (software-development-approach))` -- axis execution approach policy diff --git a/docs/practice/STATE-VISUALIZER-GUIDE.adoc b/docs/practice/STATE-VISUALIZER-GUIDE.adoc index 48dda5f5..dc9a561d 100644 --- a/docs/practice/STATE-VISUALIZER-GUIDE.adoc +++ b/docs/practice/STATE-VISUALIZER-GUIDE.adoc @@ -143,12 +143,13 @@ Always 10 characters wide. Use full blocks only (no half-blocks). 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 +- **docs/status/ROADMAP.adoc** — milestones, blockers, next actions +- **Repo deed `(status)` / `(maturity)`** — project phase and maturity +- **Repo deed `(ecosystem)`** — position in the wider project ecosystem +- **Repo deed `(meta)` and `docs/decisions/`** — architecture axes and decisions - ***_chora.deed (repo deed)** — AI agent entry point: allocation policy and directory invariants -TOPOLOGY.md is the _visual summary_ for humans; the a2ml files are the +TOPOLOGY.md is the _visual summary_ for humans; the deed and roadmap are the _structured data_ for tooling. Both should agree. == Copyright diff --git a/docs/practice/ci-cost-reduction.adoc b/docs/practice/ci-cost-reduction.adoc index 3f5e50c5..705c637a 100644 --- a/docs/practice/ci-cost-reduction.adoc +++ b/docs/practice/ci-cost-reduction.adoc @@ -199,7 +199,7 @@ Cap every job so a hung runner doesn't burn the budget: ---- jobs: build: - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 timeout-minutes: 20 # fail-fast instead of 360 default ---- diff --git a/docs/proposals/root-cleanup.adoc b/docs/proposals/root-cleanup.adoc index 84548e34..891cb17d 100644 --- a/docs/proposals/root-cleanup.adoc +++ b/docs/proposals/root-cleanup.adoc @@ -37,7 +37,8 @@ one-shot relocation PR per project once the template lands. 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`. + `_chora.deed` (the repo deed, which is the AI manifest), `LICENSE`, + `CHANGELOG.md`. * *Build entry points (root):* `Justfile`, `coordination.k9`. * *Tool-required dotfiles (root):* `.editorconfig`, `.envrc`, `.gitattributes`, `.gitignore`, `.tool-versions`. @@ -161,19 +162,10 @@ 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. +Resolved: the repo deed (`_chora.deed` at the root) is the single AI +manifest. The family-7 allocation manifest folded into it (standards#837 +pilot), and no separate manifest or pointer file remains: no `.a2ml` file +may exist in the template or its downstream repos (rsr-template-repo#209). === Template-only relocations diff --git a/docs/reports/audit/pillar-audit-2026-04-15.adoc b/docs/reports/audit/pillar-audit-2026-04-15.adoc index a99e61f8..d94b391e 100644 --- a/docs/reports/audit/pillar-audit-2026-04-15.adoc +++ b/docs/reports/audit/pillar-audit-2026-04-15.adoc @@ -3,6 +3,8 @@ = Gemini Audit Report (M2: Pillar Repo Audits) :date: 2026-04-15 +NOTE: Superseded in part (2026-10-06, rsr-template-repo#209): the `.a2ml` files named below no longer exist; their facts are clauses of the repo deed (`*_chora.deed`). + Date: 2026-04-15 + Repository: `/var/mnt/eclipse/repos/rsr-template-repo` diff --git a/docs/reports/compliance/RSR-TEMPLATE-DAMAGE-2026-10-30.adoc b/docs/reports/compliance/RSR-TEMPLATE-DAMAGE-2026-10-30.adoc new file mode 100644 index 00000000..5d07f2c8 --- /dev/null +++ b/docs/reports/compliance/RSR-TEMPLATE-DAMAGE-2026-10-30.adoc @@ -0,0 +1,486 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 +// Copyright (c) Jonathan D.A. Jewell += Template damage: what rsr-template-repo shipped, why it survived, and what now stops it +:toc: +:toclevels: 3 +:date: 2026-10-30 + +*Status*: remediation landed in this repository. Estate remediation is inventoried, +not performed — see <>. + +== Summary + +`JuliaPackageSpitter.jl` was reported as a broken Julia package: a `mise.toml` +declaring Python, Node, Go, Rust, Java, Bun and Cargo for a Julia library and no +Julia; a `Containerfile` built from two floating `:latest` stages and otherwise +consisting of TODO comments; `{{PROJECT_NAME}}` and a `tier` token sitting in +committed files; an SPDX gate that passed without reading a single file; a +`Justfile` whose `fmt`, `fmt-check` and `lint` recipes are `@echo` statements, so +`just quality` printed "All quality checks passed!" having run only `Pkg.test()`. + +None of that was authored in that repository. It was authored here, and copied +into every repository minted while it was true. Fixing it in the downstream +repository fixes one repository; fixing it here is what stops the next mint. + +== The template, and how it was found + +[cols="1,3"] +|=== +| Search | Result + +| `gh search repos rsr-template --owner hyperpolymath --json fullName,description` +| `hyperpolymath/rsr-template-repo` — the only match. There is no separate + Julia template repository: `rsr-julia-library-template-repo` and its variants + return 404 (probed), so `JuliaPackageSpitter.jl` came from this template plus + the `julia-library` archetype. + +| `gh api -X GET search/code -f q='org:hyperpolymath "Juliapackage Reuse Audit"'` +| 13 files. (`gh search code` has no `--owner` flag; the `gh api search/code` + form is the one that works.) +|=== + +Provenance of the specific files, from this repository's own history: + +* `mise.toml` — introduced at `05fc319a`, corrected here at `cf15de59`. The + correction reached this repository only. Repositories minted between those + dates have the nine-runtime file, and nothing ever went back for them. +* `build/container/Containerfile` — introduced at `dbc4d67f`, corrected here at + `adb66f51`, with the same one-way reach. +* Everything else (unfilled tokens, the `@echo` quality verbs, the vacuous SPDX + glob) was never corrected at all — it was still true in this tree when this + investigation started. + +== The defects, and why each survived + +=== 1. The SPDX gate could not fail on a non-Rust repository + +`Mustfile.a2ml`'s `spdx-headers` check globbed `*.rs`, `*.res` and `*.gleam` and +capped the scan with `head -20`. In a Julia repository it matched zero files, +counted zero missing headers, and printed PASS. In a Rust repository with more +than 20 source files it graded the first 20. + +*A gate that examined nothing reported coverage.* It survived because it was +green everywhere it was read. + +=== 2. `container-images-pinned` asked the wrong question + +The probe was `grep -q 'cgr.dev\|@sha256:' Containerfile`. Any `cgr.dev` image +satisfied it, including `FROM cgr.dev/chainguard/wolfi-base:latest`, which is +what the template shipped. The check asked "is an approved registry named" while +reporting "images are pinned". + +=== 3. The mint never rendered the toolchain + +`mise.toml` was copied from the spine as-is. The spine's copy was one file for +every language, so every minted repository got the union of them all. This +repository eventually repaired its own copy by hand; the archetype never carried +a Julia `mise.toml` at all, so mints kept producing the union. + +=== 4. Nothing checked that `mise.toml` matched the languages present + +The estate had no gate for "the toolchain this repository declares is the +toolchain its languages need". Consequently the union file was not a red build +anywhere, in any repository, for two months. + +=== 5. Tokens survived because the checker skipped the files they survived in + +The placeholder gate excludes `Justfile` and `*.just` (they contain just's own +`{{...}}` interpolation), and the mint's token list is a fixed set. Between the +two, `Justfile project := "{{PROJECT_NAME}}"`, `tier := "…"` (the `tier` brace token), +`.envrc`, `.reuse/dep5`, `Containerfile`, `devcontainer.json` and +`.devcontainer/Containerfile` kept their braces all the way into commits. + +Downstream, `JuliaPackageSpitter.jl` still carries *75* unfilled +token references; the 111-repository survey below found them in 105 of 111. + +=== 6. `just quality` echoed over verbs that ran nothing + +The provisioning engine prints `info fmt-check: N/A for julia (archetype: +library) — nothing to run…` and exits 0. That is honest. The `quality` recipe +then printed `All quality checks passed!`. A repo with no formatter, no linter +and no formatter-check reported "all quality checks passed". + +=== 7. The archetype could not remove what the preset does not declare + +The spine is polyglot on purpose, and an overlay can add files but not subtract +them. A Julia library that ships no image therefore inherited +`build/container/Containerfile` and failed `container-images-pinned` — or, before +this PR, passed it vacuously. + +== What changed here + +[cols="2,3"] +|=== +| File | Change + +| `scripts/check-spdx-headers.sh` | New. Derives the extension set from the + languages the repository declares (via `provision-lib.sh langs`), scans every + matched file with no cap, and fails when a declared language has no files or + when it matched nothing at all. Names banned-language source it finds. + +| `scripts/check-mise-language.sh` | New. Reads the languages and expected tools + from the provisioning engine, then requires that every declared tool is needed + and every needed tool is declared. Banned tools are findings wherever they + appear. `--detect` audits repositories minted before the engine shipped with + them. + +| `scripts/check-container-pins.sh` | New. Every `FROM` must carry a 64-hex + `@sha256:` digest or be `scratch`/a stage name. A pin behind `ARG` is a + finding, because the digest is then decided at build time. + +| `scripts/check-mint-tokens.sh` | New. Reads the answerable tokens *out of the + mint recipe* (not a copy) and fails on any brace token that is not in it. + Lowercase tokens included. In a minted tree with no recipe, every brace token + is a leak. + +| `scripts/render-mise.sh` | New, and now a mint step. Renders `mise.toml` from + the detected languages plus the recipe tools. Idempotent; `--check` reports + drift. + +| `scripts/pin-container-digests.sh` | New. Rewrites `FROM` lines to digest + pins. Refuses to run with a placeholder or malformed digest. + +| `build/container/Containerfile` | **Deleted.** It had two `FROM …:latest` + lines and a body of TODO comments — it could not build, and it failed + `container-images-pinned` in every repository that carried it, including the + ones that publish no image. Pinning it was not possible from here (no registry + access) and would have left a file that still builds nothing. "Pinned or not + at all" resolves to *not at all*: a repository that publishes an image adds + the file and pins it. `build/container/README.adoc` and `just container-build` + say so, and `just container-build` now explains this instead of exiting with + "No Containerfile found". + +| `scripts/prune-archetype-modules.sh` | New, and now a mint step. Deletes the + paths an archetype's `prune.txt` lists, refusing to continue on a path that + does not exist. + +| `scripts/survey-template-damage.sh` | New. Runs these gates against real + repositories (shallow clone each) to inventory the damage. + +| `build/just/repo-init.just` | Token gate before the first write; overlay files + recorded so only *their* `.in` names are resolved; prune step; + `render-mise.sh`; hard gate loop before handoff. + +| `archetypes/julia-library/` | `overlay/scripts/julia-quality.jl` (fmt, + fmt-check, lint in a private tools env — Aqua and JuliaFormatter must not enter + the package's own `[deps]`, where Aqua's own `deps_compat` check would fail + them), the `provisioning_praxis.deed` overrides that point the verbs at it, and + `prune.txt` removing `build/container/`. + +| `archetypes/rust-cli/` | New archetype: `rust-cli_praxis.deed`, + `Cargo.toml.in`, `src/{lib,main}.rs.in`, `tests/cli.rs.in`, `prune.txt`. + +| `Justfile` | `quality` runs the verbs, fails on a non-zero exit, and fails when + a verb reports `N/A for` every detected language. N/A is not a pass. + +| `.machine_readable/contractiles/must/must.k9.ncl` | `spdx-headers` now runs the + script instead of globbing three extensions; new `toolchain-matches-language` + invariant. + +| `.machine_readable/contractiles/trust/trust.k9.ncl` | `container-images-pinned` + now runs the script; severity raised to `critical`. + +| `scripts/validate-template.sh` | Phase 6 delegates to `check-spdx-headers.sh`; + the dead fixed-glob implementation is removed. + +| `scripts/check-no-placeholders.sh` | Fixed a silent failure: a repository with + no `origin` remote (a fresh `git init`, exactly what a mint produces before the + first push) made `git config` exit 1, which under `set -e` + `pipefail` killed + the gate with exit 1 and no output. + +| `.github/workflows/quality.yml` | New `mint-gates` job: the four gates plus + both test suites. No new action — `actions/checkout` at its existing pin. + +| `LICENSE` | Added — the MPL-2.0 text, identical to `LICENSES/MPL-2.0.txt`. + There was no file named `LICENSE`, so `validate-template.sh` failed Phase 1, + the Mustfile's `license-present` failed, and every minted repository's + `link:LICENSE[LICENSE]` was a dead link. (REUSE keeps `LICENSES/` authoritative; + the root copy exists because forges and readers look for it.) + +| `scripts/validate-template.sh` | Two more repairs: `SCRIPT_DIR` was referenced + but never set, so `set -u` aborted the run at Phase 6 and the last two phases + never ran; and the required-file check demanded `CONTRIBUTING.md` in a + repository whose `CONTRIBUTING.adoc` has been there all along. + +| `.machine_readable/ai/PLACEHOLDERS.adoc` | The Project Identity section now + separates the human name, the compiler identifier (upper and lower) and the + forge slug, and says they are four tokens filled from four answers. +|=== + +== Proof that the gates can fail + +`tests/workflows/mint_gates_test.sh` — 30 controls, each pair a positive and a +negative fixture: + +---- +$ bash tests/workflows/mint_gates_test.sh +── SPDX (language-derived) ──────────────────────────────── + PASS SPDX passes on the template tree + PASS SPDX fails on a Julia file with no header + PASS SPDX fails when a declared language has no files + PASS SPDX fails when it matches zero files + PASS SPDX fails on banned-language source (.py) + PASS SPDX passes on a well-formed Julia fixture +── Container image pins ─────────────────────────────────── + PASS pin gate fails on a floating :latest + PASS pin gate fails on a tag without a digest + PASS pin gate passes on a digest-pinned image + PASS pin gate fails when the pin lives in a build argument + PASS pin gate fails on a truncated digest + PASS pin gate allows a stage name and scratch + PASS pin gate fails on a Dockerfile + PASS pin gate passes when no Containerfile ships + PASS pinner refuses without a digest + PASS pinner rewrites both FROM lines + PASS pin gate passes after the pinner ran + PASS pinner removed the floating tag +── mise.toml matches the declared languages ─────────────── + PASS mise gate passes when the toolchain matches + PASS mise gate fails on a banned tool + PASS mise gate fails when the language tool is missing + PASS mise gate fails on a tool no language needs + PASS mise gate fails on an empty [tools] table + PASS mise gate fails when mise.toml is missing + PASS mise gate passes on the template tree +── Mint tokens ──────────────────────────────────────────── + PASS token gate passes on the template + PASS token gate ignores just's own interpolation + PASS token gate fails on a token with no answer +── Archetype prune ──────────────────────────────────────── + PASS prune script runs + PASS prune removed the listed path +mint gates: 30/30 controls hold +---- + +Two of these controls exist because the gates themselves were written badly the +first time and the tests caught it: + +* `check-spdx-headers.sh` read `git ls-files` paths relative to `--root` as if + they were relative to the caller's directory. On a fixture that shared a path + with the template it graded *the template's file*. Found when the Julia + scaffold reported four files missing that plainly carried headers. +* `check-mint-tokens.sh` piped answers into `grep -q`. `grep -q` exits on its + first match, the writer takes SIGPIPE, `pipefail` reports 141, and a *match* + became a non-match — a different one or two tokens reported unanswerable on + every run of an unchanged tree. Here-strings now. + +== A Julia package and a Rust CLI, minted and gated + +`tests/e2e/language_profiles_mint_test.sh` builds both from this tree and the +archetypes, using the recipe's own overlay/prune/rename ordering and its own +answer list, then runs the gates: + +---- +$ bash tests/e2e/language_profiles_mint_test.sh +── Julia scaffold ───────────────────────────────────────── + PASS Julia: Project.toml has its final name + PASS Julia: package name rendered from the archetype token + PASS Julia: module file named after the package + PASS Julia: build/container/ pruned (no unpinnable Containerfile ships) + PASS Julia: mise declares julia + PASS Julia: mise declares no banned or foreign tool + PASS Julia: quality verbs wired (scripts/julia-quality.jl) + PASS Julia: fmt/fmt-check/lint overrides shipped in the provisioning deed +── Rust scaffold ────────────────────────────────────────── + PASS Rust: Cargo.toml has its final name + PASS Rust: sources rendered from the overlay's .in files + PASS Rust: crate name is the repo slug + PASS Rust: mise declares rust + PASS Rust: mise declares no banned tool + PASS Rust: build/container/ pruned +── Gates on both scaffolds ──────────────────────────────── + PASS DemoPackage.jl: SPDX gate passes + PASS DemoPackage.jl: mise/language gate passes + PASS DemoPackage.jl: container pin gate passes + PASS DemoPackage.jl: no unanswered token survives the mint + PASS DemoPackage.jl: placeholder gate passes + PASS demo-rust: SPDX gate passes + PASS demo-rust: mise/language gate passes + PASS demo-rust: container pin gate passes + PASS demo-rust: no unanswered token survives the mint + PASS demo-rust: placeholder gate passes +── Replay the downstream damage ─────────────────────────── + PASS damage replay: the nine-runtime mise.toml is caught + PASS damage replay: a floating Containerfile is caught + PASS damage replay: an unanswered token is caught +language profiles: 27/27 controls hold +---- + +The Julia scaffold's rendered `mise.toml` declares `julia` and `just`, nothing +else. The Rust scaffold's declares `rust` and `just`. Neither declares Python, +Node, Go, Java, Cargo-for-Julia or Julia-for-Rust, and each is generated from the +languages the tree carries rather than from a list in a template. + +== The estate + +=== Method + +`scripts/survey-template-damage.sh` shallow-clones each repository and runs these +four gates against the clone — the same code a minted repository will run, not a +grep. Reproducible: + +---- +gh api -X GET search/code -f q='org:hyperpolymath "{{PROJECT_NAME}}"' \ + --jq '[.items[].repository.full_name] | unique | .[]' +scripts/survey-template-damage.sh --tsv owner/name owner/name … +---- + +Code search totals for the whole organisation, at the time of writing (each is a +separate query, so the populations overlap and none is a subset of another): + +[cols="1,1,3"] +|=== +| Query | Files | What it establishes + +| `org:hyperpolymath "{{PROJECT_NAME}}"` | 1536 | Unfilled tokens are not one + repository's accident. +| `org:hyperpolymath filename:mise.toml python` | 175 | 175 `mise.toml` files + mention Python. Python is banned estate-wide. +| `org:hyperpolymath filename:Containerfile ":latest"` | 421 | 421 `Containerfile` + files carry a floating tag somewhere. +| `org:hyperpolymath filename:Justfile "{{PROJECT_NAME}}"` | 33 | The mint's + own skipped-file class, in 33 `Justfile`s. +|=== + +=== What the survey found + +111 repositories surveyed (the union of the queries above). Result per gate: + +[cols="2,1,3"] +|=== +| Gate | Repositories failing | Reading + +| Unfilled tokens | 105 / 111 | The mint left braces in committed files. +| Banned tool declared in `mise.toml` | 84 / 111 | Includes every + `.jl` repository in the set. +| SPDX headers incomplete | 78 / 111 | The gate that shipped could not + have reported this. +| Floating container base image | 68 / 111 | `cgr.dev/chainguard`:latest. +| *All four* | 55 / 111 | The full template signature. +| Clean | 0 / 111 | — +|=== + +The 55 repositories carrying all four, in full: + +* `InvestigativeJournalism.jl` +* `JuliaKids.jl` +* `JuliaPackageSpitter.jl` +* `aerie` +* `alloyiser` +* `boinc-boinc` +* `bunsenite` +* `cafescripto` +* `cicd-squabbler` +* `cloud-sync-tuner` +* `conative-gating` +* `conflow` +* `cookie-rebound` +* `dafniser` +* `deed-core` +* `deed-ecosystem` +* `developer-ecosystem` +* `echidna` +* `excel-economic-numbers-tool` +* `filesoup` +* `formatrix-docs` +* `fraying-model-computational-testbed` +* `gnpl` +* `gv-clade-index` +* `http-capability-gateway` +* `ideas-to-alphas` +* `idrisiser` +* `iseriser` +* `jtv-lang` +* `julia-ecosystem` +* `k9-ecosystem` +* `kitchenspeak` +* `lithoglyph` +* `lucidscript` +* `lustreiser` +* `natsci-studio` +* `nesy-solver` +* `otpiser` +* `panll` +* `patallm-gallery` +* `patch-bridge` +* `polyglot-i18n` +* `proof-burrower` +* `proven-tests-and-benches` +* `pseudoscript` +* `rattlescript` +* `scaffoldia` +* `session-sentinel` +* `snifs` +* `somethings-fishy` +* `squeakwell` +* `trigger` +* `ubicity` +* `vocarium` +* `wokelang` + +These are the repositories where the four defects coexist, which is the +signature of a single mint from the damaged template. The remaining 56 +have one or more of them, usually the token leak alone. + +Examples of individual rows, verbatim from the survey: + +---- +JuliaPackageSpitter.jl mise: banned tool(s) declared: black go isort java jest make node npm pip + prettier pytest python ruff vitest yarn + spdx: SPDX headers: 26/27 files carry a header + pins: Containerfile: floating base image 'cgr.dev/chainguard/wolfi-base:latest' + tokens: 75 unfilled token(s) in a tree that has no generator left +---- + +== Remediation + +The template is fixed here; the 111 repositories are not. Each needs a +per-repository change, and the shape of it is now mechanical: + +. Copy `scripts/render-mise.sh` and `build/just/provision-lib.sh` into the repository from the same revision of `hyperpolymath/rsr-template-repo`. Older mints do not contain `scripts/render-mise.sh`, and the renderer exits with an error when `build/just/provision-lib.sh` is missing. +. Re-render the toolchain: `scripts/render-mise.sh --root .` in the repository, + then delete the `[alias]` block (it routes `build`/`test`/`lint` to + cargo/npm/go/ruff/prettier/black, which is how a Julia package came to have a + `lint` that ran `ruff`). +. Pin or delete the `Containerfile`. A repository that builds no image should not + ship one; `scripts/pin-container-digests.sh` is for the ones that do. +. Fill the tokens from `PLACEHOLDERS.adoc`, or delete the lines that need them. + `scripts/check-mint-tokens.sh` lists every one. +. Add the SPDX headers `scripts/check-spdx-headers.sh` names. +. Replace the `@echo` `fmt`/`fmt-check`/`lint` recipes with real ones — for a + Julia package, `archetypes/julia-library/overlay/scripts/julia-quality.jl` is + the file to copy. + +That is a migration, not a merge request, and it is deliberately not attempted +here: a template PR that also rewrites 111 repositories is a PR nobody can +review. + +== What this PR does not prove + +* `just repo-init` was not run end to end. The recipe needs `rustc` (its mint + tooling is single-file Rust compiled on demand), `nickel` (the arrival pack) + and `uuidgen`; this environment has none of the three and installing them from + the package indexes available would have meant an installer outside the + estate's provenance. What was verified instead: the recipe body parses as bash + (`just --show repo-init | bash -n`), and `tests/e2e/language_profiles_mint_test.sh` + reproduces its overlay → prune → substitute → rename → render ordering and runs + the gates on the result. The remaining risk is in the parts of the recipe this + test does not touch, and the CI job that runs the real mint + (`tests/e2e/use_template_mint_test.sh`) is the place that closes it. +* The contractile probes changed here (`must.k9.ncl`, `trust.k9.ncl`) were not + executed: they need `nickel`/`contractile`. The scripts they now call are + tested; the plumbing from the contractile to the script is not. +* Nothing was pushed to any of the 111 repositories, and no issue was opened + against them. + +== Reproducing this report + +---- +bash scripts/check-spdx-headers.sh # the template: 174/174 +bash scripts/check-mise-language.sh # the template: consistent +bash scripts/check-container-pins.sh # the template: pass +bash scripts/check-mint-tokens.sh # 51 answered, none leaked +bash tests/workflows/mint_gates_test.sh # 30/30 +bash tests/e2e/language_profiles_mint_test.sh # 27/27 +bash scripts/survey-template-damage.sh --tsv owner/name … +---- diff --git a/docs/status/READINESS.adoc b/docs/status/READINESS.adoc index effb64e5..b34e6a11 100644 --- a/docs/status/READINESS.adoc +++ b/docs/status/READINESS.adoc @@ -40,19 +40,19 @@ evidence doesn't support the claim. *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/descriptiles/STATE.a2ml` or CI. + must cite counts and live in `docs/status/ROADMAP.adoc` 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. + `docs/status/ROADMAP.adoc` `== 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. + feedback fed back. ROADMAP.adoc `== 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. + value, no harm in the wild. ROADMAP.adoc `== Field signal` populated. *Publication gate:* non-abstract implementation claims require *B+*. Below B, any publication must be explicitly abstract or provisional. @@ -65,7 +65,7 @@ Below B, any publication must be explicitly abstract or provisional. |=== | Metric | Value | Source -| Test count | __ | `.machine_readable/descriptiles/STATE.a2ml` or CI +| Test count | __ | `docs/status/ROADMAP.adoc` 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 @@ -113,8 +113,8 @@ CRG v2.0 requires two new pieces of evidence on top of D: ** 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 — "`. +** Populate `== Dogfooding status` in `docs/status/ROADMAP.adoc` with one entry + per capability: ` — done — `. . *Deep code and folder annotation.* ** Per-directory orientation READMEs in every non-trivial source subtree. @@ -142,21 +142,21 @@ component. Candidate diversity axes: * Different topology (star, mesh, peer-to-peer). * Different trust model (same-org, federated, adversarial). -Populate `STATE.a2ml`: +Populate `docs/status/ROADMAP.adoc`: -* `[external-targets]` — target-id → `" — — "`. -* `[issues-fed-back]` — issue-id → `" — — "`. +* `== 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]`. +currently under other roadmap sections 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: +`== Field signal` in `docs/status/ROADMAP.adoc` with multi-source entries: * External users beyond the six B-targets. * Third-party writeups, talks, papers, or testimonials. @@ -179,8 +179,10 @@ Real-world external feedback confirming value. Populate * `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/descriptiles/STATE.a2ml` — authoritative state (canonical keys - `[dogfooding-status]`, `[external-targets]`, `[issues-fed-back]`, - `[field-signal]`). +* `docs/status/ROADMAP.adoc` — evidence journal (sections + `== Dogfooding status`, `== External targets`, `== Issues fed back`, + `== Field signal`, and a `Declared CRG grade:` line). +* `*_chora.deed` (repo deed) — authoritative phase and maturity (`(status)`, + `(maturity)`). _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 index bafe0ce0..85970955 100644 --- a/docs/status/ROADMAP.adoc +++ b/docs/status/ROADMAP.adoc @@ -1,23 +1,69 @@ // SPDX-License-Identifier: CC-BY-SA-4.0 // Copyright (c) Jonathan D.A. Jewell -= YOUR Template Repo Roadmap += rsr-template-repo Roadmap -== Current Status +The journal of the template itself: milestones, blockers and next actions. +A repo minted from the template does not inherit it: `just repo-init` +replaces this file with `build/templates/ROADMAP.adoc.in`. -Initial development phase. +Phase and maturity are not recorded here. They live in the repo deed, +`rsr-template-repo_chora.deed`, in the `(status …)` and `(maturity …)` +clauses (`just state-phase` prints both). + +This file took over the journal half of the retired STATE record +(rsr-template-repo#209), last +updated there on 2026-09-19. STATE also recorded version 0.3.0; the release +version is 0.1.0 (`Justfile`, `CITATION.cff`, tag `v0.1.0`, deed +`(meta :version …)`). == Milestones -=== v0.1.0 - Foundation -* [ ] Core functionality -* [ ] Basic documentation -* [ ] CI/CD pipeline +[cols="5,1",options="header"] +|=== +| Milestone | Done + +| Phase 0: Core scaffolding (justfile, CI/CD, machine-readable) | 100% +| Phase 1: ABI/FFI standard (Idris2/Zig templates) | 100% +| Phase 1b: AI Gatekeeper Protocol (AI manifest, now the repo deed) | 100% +| Phase 1c: TOPOLOGY.md standard and guide | 100% +| Phase 1d: Maintenance gate (axes, checklist, approach) | 100% +| Phase 1e: Trustfile / contractiles | 100% +| Phase 2: Container ecosystem templates (stapeln) | 100% +| Phase 2b: www/ site-operations bundle + .well-known migration (#53) | 100% +| Phase 2c: Forge & Sustain mechanics — provenance at mint, self-name passes, drift gate, update mechanism (ADR-0003, ratified 2026-09-19) | 100% +| Phase 2d: julia-library archetype overlay + e2e mint test (recon P1.2) | 100% +| Phase 3: Multi-forge sync hardening | 0% +| Phase 4: Guix reproducible shells | 50% +| Phase 4b: RSR oracle dogfood gate in CI (recon P0.2; hypatia M-3 SSOT-path fix is the precondition) | 0% +|=== + +== Blockers + +. Hypatia M-3: `mix hypatia.rsr_score --standards` resolves the SSOT at the + pre-reorg path (`rhodium-standard-repositories/spec/`). A one-line fix is + prepared (recon P0.2/01), pending its PR. The dogfood job works around it + with an explicit `--ssot` until then. +. Estate-wide `actions.lock` sweep (D38/D39 ruling 2026-09-19): the grace + window closed on 2026-10-01. The sweep's estate-wide status is not recorded + here. This repo's own lockfile verifies (`gh actions-lock --no-fix`, rc=0, + 2026-10-02). + +== Next actions + +* Wire the RSR oracle dogfood job in dogfood-gate.yml (recon P0.2) once the hypatia M-3 fix lands +* Record where the estate-wide actions.lock sweep stands now that the 2026-10-01 window has closed (gatekeeper repos first) +* Rebase rsr-julia-library-template-repo onto this spine (recon P1.3 procedure; ADR-0003 now accepted) +* Validate container templates across wolfi-base and static Chainguard images +* Harden multi-forge sync for GitLab/Bitbucket mirroring edge cases +* Expand Guix development shell templates + +== Maintenance runs -=== v1.0.0 - Stable Release -* [ ] Full feature set -* [ ] Comprehensive tests -* [ ] Production ready +No maintenance run has been recorded. Reports go to +`docs/reports/maintenance/latest.json`. -== Future Directions +== Ecosystem -_To be determined based on community feedback._ +Part of the RSR Framework and the stapeln ecosystem. The repos it depends on +(stapeln, selur-compose, cerro-torre, svalinn, vordr, k9-svc) are the +`(related …)` entries of the deed's `(ecosystem …)` clause. diff --git a/launcher.sh b/launcher.sh new file mode 100755 index 00000000..8fb0d7fb --- /dev/null +++ b/launcher.sh @@ -0,0 +1,42 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# @launcher-deed begin +# ;; SPDX-License-Identifier: MPL-2.0 +# (praxis-deed +# :schema-version "1.0.0" +# :canonical-name "rsr-template-repo-launcher" +# :beholding-chora #u5"estate/chora" +# (artefact :type "launcher" :version "0.1.0" +# :generator "provision-set") +# (app :name "rsr-template-repo" :display "rsr-template-repo" +# :url "https://github.com/hyperpolymath/rsr-template-repo" :archetype "library") +# (compliance :standard-version "0.6.0" +# :standards ("launcher-standard.adoc" +# "PROVISIONING-STANDARD.adoc")) +# (modes :accepted ("--setup" "--doctor" "--heal" "--ai-setup" "--help" "--version" +# "--start" "--stop" "--status" "--auto" "--integ" "--disinteg")) +# (platforms :supported ("linux" "macos" "windows")) +# (lifecycle-phases :covered ("provision" "diagnose" "heal") +# :deferred ("install" "run"))) +# @launcher-deed end +# +# The launcher for a library / tool / theory / docs repository +# (launcher-standard 0.6.0, archetype profile). Every mode is implemented in +# build/just/provision-modes.sh, and every provisioning mode delegates to the +# Justfile. This file is minted by `provision-set`; do not hand-edit it. +# Repo-specific facts belong in .machine_readable/descriptiles/provisioning_praxis.deed. +set -uo pipefail + +REPO_DIR="$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")" && pwd)" + +if [ ! -f "$REPO_DIR/build/just/provision-modes.sh" ]; then + echo "launcher.sh: build/just/provision-modes.sh is missing — this checkout is incomplete." >&2 + echo "Re-clone, or restore it: git checkout -- build/just/provision-modes.sh" >&2 + exit 1 +fi +# shellcheck source=build/just/provision-modes.sh +. "$REPO_DIR/build/just/provision-modes.sh" + +hp_launcher_main "$@" diff --git a/mise.lock b/mise.lock new file mode 100644 index 00000000..504562b2 --- /dev/null +++ b/mise.lock @@ -0,0 +1,157 @@ +# @generated - this file is auto-generated by `mise lock` https://mise.jdx.dev/dev-tools/mise-lock.html + +[[tools.just]] +version = "1.56.0" +backend = "aqua:casey/just" + +[tools.just."platforms.linux-arm64"] +checksum = "sha256:c8c1d656e9f47569ec1ae2bf8779af2621cdeea6bbbba3b0cacd64f951d25e2b" +url = "https://github.com/casey/just/releases/download/1.56.0/just-1.56.0-aarch64-unknown-linux-musl.tar.gz" +url_api = "https://api.github.com/repos/casey/just/releases/assets/472074960" + +[tools.just."platforms.linux-arm64-musl"] +checksum = "sha256:c8c1d656e9f47569ec1ae2bf8779af2621cdeea6bbbba3b0cacd64f951d25e2b" +url = "https://github.com/casey/just/releases/download/1.56.0/just-1.56.0-aarch64-unknown-linux-musl.tar.gz" +url_api = "https://api.github.com/repos/casey/just/releases/assets/472074960" + +[tools.just."platforms.linux-x64"] +checksum = "sha256:fa2a8ec1015d9df5330941ade12437488fc40d33f9c9f8cd4eb70a26de11b639" +url = "https://github.com/casey/just/releases/download/1.56.0/just-1.56.0-x86_64-unknown-linux-musl.tar.gz" +url_api = "https://api.github.com/repos/casey/just/releases/assets/472074624" + +[tools.just."platforms.linux-x64-musl"] +checksum = "sha256:fa2a8ec1015d9df5330941ade12437488fc40d33f9c9f8cd4eb70a26de11b639" +url = "https://github.com/casey/just/releases/download/1.56.0/just-1.56.0-x86_64-unknown-linux-musl.tar.gz" +url_api = "https://api.github.com/repos/casey/just/releases/assets/472074624" + +[tools.just."platforms.macos-arm64"] +checksum = "sha256:f35798d4bcdc4db020eef7d2853ad98bbfb97a4d29ee695ba042f18e7fedcc11" +url = "https://github.com/casey/just/releases/download/1.56.0/just-1.56.0-aarch64-apple-darwin.tar.gz" +url_api = "https://api.github.com/repos/casey/just/releases/assets/472074635" + +[tools.just."platforms.macos-x64"] +checksum = "sha256:09b35ff6d17023ffae37ce408d1a78a976d9e001cae54b88e238f7f40db9b783" +url = "https://github.com/casey/just/releases/download/1.56.0/just-1.56.0-x86_64-apple-darwin.tar.gz" +url_api = "https://api.github.com/repos/casey/just/releases/assets/472074650" + +[tools.just."platforms.windows-x64"] +checksum = "sha256:804f5b2fe94291d0df38fd8dfc5620afbf3496f8f11c1915b42a87323234f0ba" +url = "https://github.com/casey/just/releases/download/1.56.0/just-1.56.0-x86_64-pc-windows-msvc.zip" +url_api = "https://api.github.com/repos/casey/just/releases/assets/472075917" + +[[tools.shellcheck]] +version = "0.11.0" +backend = "aqua:koalaman/shellcheck" + +[tools.shellcheck."platforms.linux-arm64"] +checksum = "sha256:12b331c1d2db6b9eb13cfca64306b1b157a86eb69db83023e261eaa7e7c14588" +url = "https://github.com/koalaman/shellcheck/releases/download/v0.11.0/shellcheck-v0.11.0.linux.aarch64.tar.xz" +url_api = "https://api.github.com/repos/koalaman/shellcheck/releases/assets/279056934" + +[tools.shellcheck."platforms.linux-arm64-musl"] +checksum = "sha256:12b331c1d2db6b9eb13cfca64306b1b157a86eb69db83023e261eaa7e7c14588" +url = "https://github.com/koalaman/shellcheck/releases/download/v0.11.0/shellcheck-v0.11.0.linux.aarch64.tar.xz" +url_api = "https://api.github.com/repos/koalaman/shellcheck/releases/assets/279056934" + +[tools.shellcheck."platforms.linux-x64"] +checksum = "sha256:8c3be12b05d5c177a04c29e3c78ce89ac86f1595681cab149b65b97c4e227198" +url = "https://github.com/koalaman/shellcheck/releases/download/v0.11.0/shellcheck-v0.11.0.linux.x86_64.tar.xz" +url_api = "https://api.github.com/repos/koalaman/shellcheck/releases/assets/279056942" + +[tools.shellcheck."platforms.linux-x64-musl"] +checksum = "sha256:8c3be12b05d5c177a04c29e3c78ce89ac86f1595681cab149b65b97c4e227198" +url = "https://github.com/koalaman/shellcheck/releases/download/v0.11.0/shellcheck-v0.11.0.linux.x86_64.tar.xz" +url_api = "https://api.github.com/repos/koalaman/shellcheck/releases/assets/279056942" + +[tools.shellcheck."platforms.macos-arm64"] +checksum = "sha256:56affdd8de5527894dca6dc3d7e0a99a873b0f004d7aabc30ae407d3f48b0a79" +url = "https://github.com/koalaman/shellcheck/releases/download/v0.11.0/shellcheck-v0.11.0.darwin.aarch64.tar.xz" +url_api = "https://api.github.com/repos/koalaman/shellcheck/releases/assets/279056932" + +[tools.shellcheck."platforms.macos-x64"] +checksum = "sha256:3c89db4edcab7cf1c27bff178882e0f6f27f7afdf54e859fa041fca10febe4c6" +url = "https://github.com/koalaman/shellcheck/releases/download/v0.11.0/shellcheck-v0.11.0.darwin.x86_64.tar.xz" +url_api = "https://api.github.com/repos/koalaman/shellcheck/releases/assets/279056930" + +[tools.shellcheck."platforms.windows-x64"] +checksum = "sha256:8a4e35ab0b331c85d73567b12f2a444df187f483e5079ceffa6bda1faa2e740e" +url = "https://github.com/koalaman/shellcheck/releases/download/v0.11.0/shellcheck-v0.11.0.zip" +url_api = "https://api.github.com/repos/koalaman/shellcheck/releases/assets/279056944" + +[[tools.trivy]] +version = "0.74.0" +backend = "aqua:aquasecurity/trivy" + +[tools.trivy."platforms.linux-arm64"] +checksum = "sha256:b94ce1976bbf3c15b514b605ee88be7c6d94a29be2302847ff01cb794d47aad5" +url = "https://github.com/aquasecurity/trivy/releases/download/v0.74.0/trivy_0.74.0_Linux-ARM64.tar.gz" +url_api = "https://api.github.com/repos/aquasecurity/trivy/releases/assets/514339429" +provenance = "cosign" + +[tools.trivy."platforms.linux-arm64-musl"] +checksum = "sha256:b94ce1976bbf3c15b514b605ee88be7c6d94a29be2302847ff01cb794d47aad5" +url = "https://github.com/aquasecurity/trivy/releases/download/v0.74.0/trivy_0.74.0_Linux-ARM64.tar.gz" +url_api = "https://api.github.com/repos/aquasecurity/trivy/releases/assets/514339429" +provenance = "cosign" + +[tools.trivy."platforms.linux-x64"] +checksum = "sha256:2ae6fe3ee734b7fdf11335663e18c75ea12dccc76062f09f164a3b0f8be4371a" +url = "https://github.com/aquasecurity/trivy/releases/download/v0.74.0/trivy_0.74.0_Linux-64bit.tar.gz" +url_api = "https://api.github.com/repos/aquasecurity/trivy/releases/assets/514339431" +provenance = "cosign" + +[tools.trivy."platforms.linux-x64-musl"] +checksum = "sha256:2ae6fe3ee734b7fdf11335663e18c75ea12dccc76062f09f164a3b0f8be4371a" +url = "https://github.com/aquasecurity/trivy/releases/download/v0.74.0/trivy_0.74.0_Linux-64bit.tar.gz" +url_api = "https://api.github.com/repos/aquasecurity/trivy/releases/assets/514339431" +provenance = "cosign" + +[tools.trivy."platforms.macos-arm64"] +checksum = "sha256:1caada5e0e2091909357c7525d3aa76f4b660b13821bc143b190c7483e31cc11" +url = "https://github.com/aquasecurity/trivy/releases/download/v0.74.0/trivy_0.74.0_macOS-ARM64.tar.gz" +url_api = "https://api.github.com/repos/aquasecurity/trivy/releases/assets/514339464" +provenance = "cosign" + +[tools.trivy."platforms.macos-x64"] +checksum = "sha256:472816f6888dda689d075c30254d4210b4d1035acf365aa72332f584c2f60485" +url = "https://github.com/aquasecurity/trivy/releases/download/v0.74.0/trivy_0.74.0_macOS-64bit.tar.gz" +url_api = "https://api.github.com/repos/aquasecurity/trivy/releases/assets/514339388" +provenance = "cosign" + +[tools.trivy."platforms.windows-x64"] +checksum = "sha256:94c40e0696e4b907a74b7b2e1438d5d72ebaca83115817407f568a002d520842" +url = "https://github.com/aquasecurity/trivy/releases/download/v0.74.0/trivy_0.74.0_windows-64bit.zip" +url_api = "https://api.github.com/repos/aquasecurity/trivy/releases/assets/514339469" +provenance = "cosign" + +[[tools.zig]] +version = "0.16.0" +backend = "core:zig" + +[tools.zig."platforms.linux-arm64"] +checksum = "sha256:ea4b09bfb22ec6f6c6ceac57ab63efb6b46e17ab08d21f69f3a48b38e1534f17" +url = "https://ziglang.org/download/0.16.0/zig-aarch64-linux-0.16.0.tar.xz" + +[tools.zig."platforms.linux-arm64-musl"] +checksum = "sha256:ea4b09bfb22ec6f6c6ceac57ab63efb6b46e17ab08d21f69f3a48b38e1534f17" +url = "https://ziglang.org/download/0.16.0/zig-aarch64-linux-0.16.0.tar.xz" + +[tools.zig."platforms.linux-x64"] +checksum = "sha256:70e49664a74374b48b51e6f3fdfbf437f6395d42509050588bd49abe52ba3d00" +url = "https://ziglang.org/download/0.16.0/zig-x86_64-linux-0.16.0.tar.xz" + +[tools.zig."platforms.linux-x64-musl"] +checksum = "sha256:70e49664a74374b48b51e6f3fdfbf437f6395d42509050588bd49abe52ba3d00" +url = "https://ziglang.org/download/0.16.0/zig-x86_64-linux-0.16.0.tar.xz" + +[tools.zig."platforms.macos-arm64"] +checksum = "sha256:b23d70deaa879b5c2d486ed3316f7eaa53e84acf6fc9cc747de152450d401489" +url = "https://ziglang.org/download/0.16.0/zig-aarch64-macos-0.16.0.tar.xz" + +[tools.zig."platforms.macos-x64"] +checksum = "sha256:0387557ed1877bc6a2e1802c8391953baddba76081876301c522f52977b52ba7" +url = "https://ziglang.org/download/0.16.0/zig-x86_64-macos-0.16.0.tar.xz" + +[tools.zig."platforms.windows-x64"] +checksum = "sha256:68659eb5f1e4eb1437a722f1dd889c5a322c9954607f5edcf337bc3684a75a7e" +url = "https://ziglang.org/download/0.16.0/zig-x86_64-windows-0.16.0.zip" diff --git a/mise.toml b/mise.toml index 02ec7f2d..55154df7 100644 --- a/mise.toml +++ b/mise.toml @@ -1,88 +1,22 @@ -# Every tool name below was checked against `mise registry` AND resolved with -# `mise ls-remote` before being written. The previous version of this file named -# 13 tools that do not exist in the registry, so mise emitted ~25 lines of -# warnings on every shell entry while installing none of them. -# -# This file is a TEMPLATE. Repos minted from it inherit it verbatim, so add -# your project's actual language toolchain here after minting — pinned to the -# same versions your CI uses, so local and CI agree. +# SPDX-License-Identifier: MPL-2.0 +# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# The toolchain for rsr-template-repo (idris2, zig). Specs are `latest`; mise.lock +# records the concrete version and per-platform checksum of each, so every +# checkout installs the same bits. Refresh both with: just toolchain-refresh +# Canon: hyperpolymath/standards 3-practice/provisioning (TRUST-DEFAULTS §toolchain). +# Estate policy: no python, node/npm/yarn, make or nix here. JavaScript runs Bun > Deno > +# pnpm from one package.json, so a repository with one pins all three (LANGUAGE-POLICY §1.4). +# +# Idris2 is not a mise tool: it comes from pack (`just setup` says how). +# A repository created from this template gets this file re-minted for its own +# languages by `launch-scaffolder provision-set realign` (the deed's :repo differs). + +[settings] +lockfile = true [tools] -# Language runtimes -node = "latest" -python = "latest" -rust = "latest" -go = "latest" +just = "latest" +shellcheck = "latest" +trivy = "latest" # just deps-audit zig = "latest" -java = "latest" -bun = "latest" -deno = "latest" # was `denojs` — not a registry name - -# Package managers / task runner -npm = "latest" -yarn = "latest" -pnpm = "latest" -just = "latest" # the estate's task runner (Justfile) - -# Formatting & linting -black = "latest" -ruff = "latest" -prettier = "latest" -shfmt = "latest" -stylua = "latest" - -# Build tools -cmake = "latest" -make = "latest" -ninja = "latest" - -# --------------------------------------------------------------------------- -# REMOVED — none of these resolve in the mise registry, so they installed -# nothing and only produced warnings. Grouped by why they were wrong: -# -# Already provided by a tool that IS listed above: -# cargo -> ships with `rust` -# gofmt -> ships with `go` -# pip -> ships with `python` -# -# Project-level dependencies, not system tools. These belong in -# package.json / pyproject.toml / mix.exs, not in a toolchain manager: -# vitest, jest, pytest, isort -# -# Base system binaries that mise should not be shadowing on Linux: -# git, gnu-sed, gnu-grep, gnu-tar -# (If a GNU-vs-BSD coreutils difference ever actually bites on macOS, add -# `coreutils`, which does exist in the registry, rather than these names.) -# -# Task runner that never installed: -# go-task -> not a registry name. NB the bare name `task` does not work -# either: `mise registry` LISTS it as `aqua:go-task/task`, but resolving -# `task@latest` still fails. Appearing in `mise registry` output is NOT -# sufficient to conclude a name resolves — check with `mise ls-remote`. -# `just` is listed above instead. -# --------------------------------------------------------------------------- - -[env] -NODE_ENV = "development" -PYTHONDONTWRITEBYTECODE = "1" -PYTHONUNBUFFERED = "1" - -# --------------------------------------------------------------------------- -# REMOVED — an `[alias]` section holding what were clearly meant to be tasks: -# -# [alias] -# task = "go-task" -# build = "cargo build --release || npm run build || go build" -# test = "cargo test || npm test || go test ./..." -# lint = "ruff check . || prettier --check . || black --check ." -# fmt = "ruff format . || prettier --write . || black ." -# -# mise's `[alias]` maps an alias to a TOOL PLUGIN — it does not define tasks, -# so none of these ever ran. mise also warns that `[alias]` is deprecated in -# favour of `[tool_alias]`. -# -# They are not re-added as `[tasks]`: the estate drives builds through the -# Justfile, and a second task runner sharing the verbs `build`/`test`/`lint`/ -# `fmt` — one of which silently falls through `||` chains into a different -# language's build — is worse than one. Use `just `. -# --------------------------------------------------------------------------- diff --git a/rsr-template-repo_chora.deed b/rsr-template-repo_chora.deed index 4248ef8e..9fe0104e 100644 --- a/rsr-template-repo_chora.deed +++ b/rsr-template-repo_chora.deed @@ -2,14 +2,170 @@ ; ; The repo deed of rsr-template-repo: one-deed-per-repo doctrine (standards#837, ; owner ruling 2026-09-19, Option A). Folds the former ply manifest tree -; (0.N-AI-MANIFEST.a2ml, 82 directories) and the family-7 AI -; allocation manifest (root 0-AI-MANIFEST.a2ml) into deed clauses. -; Generated by the #837 pilot emitter; every byte gated by deed_lint.py. +; (82 per-directory manifests) and the family-7 AI allocation manifest +; into deed clauses. +; The ply, manifest and canon clauses come from the #837 pilot emitter. The +; identity, clade, forges, lineage, status, maturity, ecosystem, meta and +; agentic clauses carry the former CLADE, META, ECOSYSTEM, AGENTIC and STATE +; records (#209), translated field for field under the standards mapping +; specs (1-formats/deed/mappings/). STATE's journal is docs/status/ROADMAP.adoc. +; The anchor, neurosym, playbook, ensaid, bot-directives, integrations, +; policies and rsr-profile clauses at the end carry every other record this +; repo used to keep under .machine_readable/: the deed is the one +; machine-readable description of the repo. scripts/deed-field.sh reads any +; field; scripts/deed-clause.sh is the one writer. (repo-deed :schema-version "1.0.0" :canonical-name "rsr-template-repo" :beholding-chora #u5"estate/chora" :repo-uuid #u5"github.com/hyperpolymath/rsr-template-repo" + ; The canon pin: which release of hyperpolymath/standards canon.lock this + ; repo implements. It is the ONLY canon pin in this deed (deed_canon + ; refuses zero or two); the (rsr-profile) clause below declares + ; capabilities and carries no pin. It moved here so the pin could follow a + ; canon release (#215). + ; Read by: dogfood-gate.yml `Canon lockstep` (reverse direction), + ; standards scripts/check-canon-lockstep.sh assertion 3 (forward), and + ; build/just/repo-init.just (writes the child's (provenance) clause at mint). Every hash MUST + ; equal canon.lock [canon.artifacts]; canon.lock [canon.lockstep].order is + ; spine-adopts-then-canon-releases, so this clause moves FIRST. + (canon + :version "2.1.3" + :criteria-sha256 "6a5aa8857bd0d0d58ef48827938ca17c251b6b854dacf59d306388d61694d82a" + :gates-sha256 "2f31f46d4753432e0aa8c9c28f339e18e062c98dc6e6ef4ecbb76993cf37638b" + :lockstep-since "2026-09-17" + ; A canon change this repo cannot satisfy is a change made in the WRONG + ; ORDER, not a rejected change: land the spine's adoption first, then the + ; canon change is a one-line bump. + :order "spine-adopts-then-canon-releases") + ; >>> repo-identity (repo-init replaces this block at mint) + ; The template's OWN identity. `just repo-init` swaps everything between + ; these two markers for build/templates/identity.deed.in, filled for the + ; new repo. Before that swap existed every minted repo inherited this + ; block's uuid and canonical-name and told arriving agents it WAS the + ; template (corrected in chronicles-of-slavia and scaffoldia 2026-07-16). + ; The uuid is not stored: it is uuid5(URL namespace, the header + ; :repo-uuid name). Only that typed name is written down; a hex form here + ; fails ADR-008's strict v8 gate. + ; Identity, clade, forges, lineage, status: mapping clade-to-repo-deed. + (identity + :primary-forge github + :owner "hyperpolymath" + :prefixed-name "rm-rsr-template-repo") + (clade + :primary rm + :primary-name "Repo Management & Tooling" + :secondary () + :assigned "2026-03-16" + :rationale "Repo Management & Tooling (`rm`): the core value proposition is scaffolding repositories — CI/CD, AI manifests, ABI/FFI seams, governance — that other projects are instantiated from. `gv` was previously claimed as a secondary and is dropped: the template SHIPS governance files, but shipping them is not being a governance project. That authority lives in `standards` and `metadatastician-governance`. The inherited [\"gv\"] propagated into every repo created from this template, where it was even less meant.") + (forges + :github "hyperpolymath/rsr-template-repo" + :gitlab "hyperpolymath/rsr-template-repo" + :bitbucket "hyperpolymath/rsr-template-repo") + (lineage + :type standalone + :parent "" + :born "2026-03-16" + :previous-names ()) + (status + :phase active + :since "2026-03-16" + :present #t + :aliases () + :merged-into "" + :superseded-by "" + :successors () + :ended "" + (history + (entry :phase active :since "2026-03-16" :note "the estate's canonical repository template; in production use"))) + ; Maturity has its own clause (owner decision 2026-10-02; standards + ; 1-formats/deed/vocabulary/maturity.adoc). No :since: the date the + ; template reached production was never recorded. Milestones, next actions + ; and blockers live in docs/status/ROADMAP.adoc. + (maturity + :level production) + ; Ecosystem: mapping meta-ecosystem-to-repo-deed. + (ecosystem + :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." + :not ("a project in its own right" + "Scaffoldia (the full-featured repo designer)" + "standards (the canon source this template operationalises)") + :pipeline-position "foundation" + :chain "standards → rsr-template-repo → (every estate repo)" + :pipeline-notes "rsr-template-repo turns the RSR standard into runnable scaffolding. New repos are created from it via `just repo-init`, which substitutes the {{PLACEHOLDER}} tokens." + :coordination standards + (related :name "standards" :relationship standard-source :notes "Defines the RSR standard, contractile canon, and policies that this template operationalises.") + (related :name "stapeln" :relationship build-tooling :notes "Layer-based container build system; the template ships stapeln.toml scaffolding.") + (related :name "selur-compose" :relationship build-tooling :notes "Service composition; the template ships selur-compose.toml scaffolding.") + (related :name "k9-svc" :relationship validation-tooling :notes "Runs the self-validating k9.ncl checks (.machine_readable/self-validating/).") + (related :name "cerro-torre" :relationship signing-tooling :notes "Container/image signing provider referenced by the container scaffolding.") + (related :name "svalinn" :relationship verification-tooling :notes "Supply-chain verification referenced by the container scaffolding.") + (related :name "vordr" :relationship verification-tooling :notes "Build/artifact verification referenced by the container scaffolding.")) + ; <<< repo-identity + ; Meta: mapping meta-ecosystem-to-repo-deed. A minted repo keeps this + ; clause (self-name pass applied) and edits it as its own. + (meta + :version "0.1.0" + :last-updated "2026-04-11" + :type library + :languages () + :license MPL-2.0 + :author "Jonathan D.A. Jewell (hyperpolymath)" + :build-tool just + :container-runtime podman + :ci-platform github-actions + :package-manager guix + :scoping-first #t + :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") + :corrective-first #t + :adaptive-second #t + :adaptive-focus "scope-change reconciliation, stale-reference removal, obsolete-work culling" + :perfective-third #t + :perfective-source "axis-1 honest state after corrective/adaptive updates" + (axis-3 + :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. ->TypeScript spread)" + :effects-evidence "benchmark execution/results and maintainer status dialogue/review")) + ; Agent permissions and integrity: mapping agentic-neurosym-playbook-to-repo-deed. + ; What 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 relicense an existing file, and never run an automated licence + ; sweep (LICENCE-POLICY.adoc A2). New files get correct SPDX from birth. + ; - Never assume a licence. Read standards/3-practice/LICENCE-POLICY.adoc: Rule 1 + ; defaults to MPL-2.0 (code) / CC-BY-SA-4.0 (prose), but Rule 3 + ; (co-developed), Rule 4 (network-deployed services) and Rule 5 + ; (games) are AGPL-3.0-or-later, and Rule 2 names the PMPL register. + ; This clause declares WHAT agents may do; the (bot-directives) clause of + ; this deed declares HOW they work (methodology, coverage, debt, rra). + ; Hooks: on enter, read this deed, then docs/status/ROADMAP.adoc; on exit, + ; update ROADMAP.adoc and the (bot-directives (coverage)) and + ; (bot-directives (debt)) clauses with scripts/deed-clause.sh; on commit, + ; run `just validate-rsr`. + (agentic + :version "0.1.0" + :last-updated "2026-04-11" + (permissions :source #t :tests #t :docs #t :config #t :create-files #t) + (integrity + :fail-closed #t + :require-evidence-per-step #t + :allow-silent-skip #f + :require-rerun-after-fix #t + :release-claim-requires-hard-pass #t) + (methodology :instructions-clause "bot-directives" :default-mode hybrid)) (manifest :version "0.1.0" :last-updated "{{CURRENT_DATE}}" @@ -28,14 +184,12 @@ (ply (directory :ply 1 :path ".github") (directory :id "machine-readable-pillar" :ply 1 :path ".machine_readable" :description "Registry for all machine-readable metadata, policies, and internal\nautomation scripts." - (canonical-locations :agentic "descriptiles/AGENTIC.a2ml" :ai_configs "ai/" :anchors "descriptiles/anchors/" :clade "descriptiles/CLADE.a2ml" :compliance "compliance/" :ecosystem "descriptiles/ECOSYSTEM.a2ml" :meta "descriptiles/META.a2ml" :neurosym "descriptiles/NEUROSYM.a2ml" :playbook "descriptiles/PLAYBOOK.a2ml" :policies "policies/" :scripts "scripts/" :state "descriptiles/STATE.a2ml") - :invariants ("Metadata files MUST follow a2ml format" "Internal automation MUST live in scripts/ subfolder") + (canonical-locations :ai_configs "ai/" :anchor "rsr-template-repo_chora.deed (anchor)" :compliance "compliance/" :neurosym "rsr-template-repo_chora.deed (neurosym)" :playbook "rsr-template-repo_chora.deed (playbook)" :policies "rsr-template-repo_chora.deed (policies)" :scripts "scripts/") + :invariants ("Repo metadata MUST live in the repo deed (rsr-template-repo_chora.deed) and follow the DEED grammar" "Internal automation MUST live in scripts/ subfolder") (directory :id "ai-registry" :ply 2 :path ".machine_readable/ai" :description "Sub-registry for ai metadata.") (directory :id "configs-registry" :ply 2 :path ".machine_readable/configs" :description "Sub-registry for configs metadata.") (directory :ply 0 :path ".machine_readable/descriptiles" :description "This manifest declares the AI-assistant context for the descriptiles machine-readable metadata directory." - :invariants ("No duplicate files in root directory" "Single source of truth: this directory is authoritative" "No stale metadata") - (directory :ply 0 :path ".machine_readable/descriptiles/anchors" :description "This manifest declares the AI-assistant context for the anchor machine-readable metadata directory." - :invariants ("Multiple versions with different dates are permitted" "No other A2ML files in this directory" "Single source of truth for anchor documents"))) + :invariants ("No duplicate files in root directory" "Single source of truth: this directory is authoritative" "No stale metadata")) (directory :id "policies-registry" :ply 2 :path ".machine_readable/policies" :description "Sub-registry for policies metadata.") (directory :id "automation-scripts-unit" :ply 2 :path ".machine_readable/scripts" :description "Internal automation logic for the project lifecycle, forge sync,\nverification triggers, and maintenance." (canonical-locations :forge "forge/" :lifecycle "lifecycle/" :maintenance "maintenance/" :verification "verification/") @@ -43,7 +197,7 @@ (directory :id "automation-unit-lifecycle" :ply 3 :path ".machine_readable/scripts/lifecycle" :description "Internal automation logic for project lifecycle.") (directory :id "automation-unit-verification" :ply 3 :path ".machine_readable/scripts/verification" :description "Internal automation logic for project verification."))) (directory :id "container-templates" :ply 1 :path "build/container" :version "1.0.0" :description "Container templates for the stapeln container ecosystem. This directory\nprovides Podman-Chainguard-stapeln templates that are customised via\n`just container-init` or `just repo-init` during project bootstrap.\n\nAll files use {{PLACEHOLDER}} tokens that are substituted with project-\nspecific values during initialisation." :purpose "Provide a complete, security-first container deployment story for any\nRSR-compliant repository. The templates cover the full lifecycle:\nbuild, sign, verify, deploy, monitor, and govern." :overview "The stapeln container ecosystem comprises six tools:\n\nselur — Container orchestration with zero-copy IPC. Reads compose.toml.\ncerro-torre — Verified container packaging (.ctp bundles), Ed25519 signing.\nsvalinn — Policy-driven edge gateway (auth, rate limits, CORS, trust).\nvordr — Runtime monitoring (health, crashes, resources, logs).\nrokur — Secrets management (runtime injection, no baked secrets).\nk9-svc — Nickel deployment components (Kennel/Yard/Hunt trust levels)." - :context ("https://a2ml.org/ns/v2" "https://stapeln.dev/ns/v1") + :context ("https://stapeln.dev/ns/v1") (canonical-locations :build_pipeline "build/container/stapeln/ct-build.sh" :compose "build/container/stapeln/compose.toml" :compose_example "build/container/stapeln/compose.example.toml" :compose_portable "build/container/compose.yaml" :compose_portable_example "build/container/compose.example.yaml" :containerfile "build/container/Containerfile" :containerignore "build/container/.containerignore" :deployment "build/container/stapeln/deploy.k9.ncl" :entrypoint "build/container/entrypoint.sh" :gatekeeper "build/container/stapeln/.gatekeeper.yaml" :just_module "build/just/container.just" :manifest "build/container/stapeln/manifest.toml" :monitoring "build/container/stapeln/vordr.toml" :secrets_gate "build/container/stapeln/rokur.toml") :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)") (file-relationships @@ -54,7 +208,7 @@ (file :name "ct-build.sh" :role "Build Pipeline" :description "Shell script implementing the 5-stage pipeline: build (Podman),\npack (cerro-torre .ctp), sign (Ed25519), verify, push (optional).\nDegrades gracefully when cerro-torre tools are not installed." :depends-on ("Containerfile" "manifest.toml")) (file :name "entrypoint.sh" :role "Container Entrypoint" :description "Startup script with signal handling (SIGTERM, SIGINT), logging, and\nexec into the main application process." :depends-on ()) (file :name "vordr.toml" :role "Runtime Monitoring" :description "Vordr monitoring configuration. Health endpoint probing, crash\ndetection, resource thresholds, and structured log output." :depends-on ()) - (file :name "deploy.k9.ncl" :role "Deployment Component" :description "k9-svc deployment specification at Hunt trust level. Full pedigree\n(L1-L5), environment configs, container config, and rolling\ndeployment strategy." :depends-on ("compose.toml" "ct-build.sh")) + (file :name "deploy.k9.ncl.in" :role "Deployment Component (template)" :description "k9-svc deployment component at the Hunt leash, K9 contract v1.0.0:\npedigree with capability grant, side effects and signature block;\nenvironment configs, container config, rolling deployment strategy,\ndeploy scripts and Just recipes. `just container-init` renders it to\ndeploy.k9.ncl once no placeholder token is left." :depends-on ("compose.toml" "ct-build.sh")) (file :name "compose.example.toml" :role "Example" :description "Fully-commented multi-service example (Rust API + Elixir worker +\nsvalinn gateway). Copy to compose.toml and customise." :depends-on ()) )) (directory :id "docs-pillar" :ply 1 :path "docs" :description "Technical documentation hub. The root contains high-level orientation\n(README, Quickstart, State-Visualizer). Specialized tracks live in\nsubdirectories." @@ -149,4 +303,812 @@ (directory :ply 2 :path "verification/tests") (directory :id "verification-unit-traceability" :ply 2 :path "verification/traceability" :description "High-assurance verification unit for traceability. \nCritical for safety-of-life and aerospace-grade deployment standards.")) ) + ; ANCHOR — the authoritative anchor: semantic authority, implementation policy + ; and the golden path. The CLAUDE.md arrival pack reads anchor/golden-path and hashes this clause (ANCHOR@…). + (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." + ) + (metadata + :version "1.0.0" + :last-updated "{{CURRENT_DATE}}") + (identity + :project "{{PROJECT_NAME}}" + ; language | library | service | tool + :kind "{{PROJECT_KIND}}" + :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 #t + :must-declare-authority #t + :must-have-anchor #t + :must-have-golden-path #t) + (semantic-authority-files + :language-spec "SPECIFICATION.md" + :formal-proofs "docs/proofs/PROOFS.adoc" + :type-theory "docs/theory/THEORY.adoc" + :algorithms "docs/theory/ALGORITHMS.adoc")) + ; NEUROSYM — neurosymbolic integration metadata: the meaning of operations. + ; Configuration for Hypatia scanning and symbolic reasoning. + (neurosym + (metadata + :version "0.1.0" + :last-updated "2026-04-11") + (hypatia-config + :scan-enabled #t + ; quick | standard | deep + :scan-depth "standard" + :report-format "logtalk") + (symbolic-rules + ; Custom symbolic rules for this project + ; (rule :name "no-unsafe-ffi" :pattern "believe_me|unsafeCoerce" :severity "critical") + ) + (neural-config + ; Neural pattern detection settings + ; confidence-threshold = 0.85 + ; model = "hypatia-v2" + )) + ; PLAYBOOK — operational playbook: how permitted actions run. + ; Runbooks, incident response, deployment procedures. + (playbook + (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 the repo deed (*_chora.deed) (status) clause and docs/status/ROADMAP.adoc 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 the repo deed (meta :version), 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")) + ; eNSAID environment configuration — per-repo configuration for PanLL and + ; eNSAID-compatible tools. + ; Spec: https://github.com/hyperpolymath/standards/tree/main/1-formats/sub-specs/ensaid-config + (ensaid + :version "1.0.0" + :tool "panll" + ; Workspace mode, protection, and execution policy + (workspace + ; rhodium | gold | silver | bronze + :mode "rhodium" + ; open | guarded | locked + :protection "open" + ; live | dry-run | approval-required + :execution "live") + ; User/repo-level display and behaviour preferences + (preferences + ; high | medium | low (drift aura intensity) + :humidity "medium" + ; workspace arrangement ID + :default-arrangement "default-3-panel" + ; auto-connect panels to backends on load + :auto-connect #t) + ; Panel visibility, enablement, and isolation overrides + (panels + :version "1.0.0" + ; By default, all panels are available. Uncomment to restrict: + ; (enabled :id "valence-shell" :isolation "native" :auto-connect #t) + ; (enabled :id "editor-bridge" :isolation "native" :auto-connect #t) + ; Panels to hide for this repo context: + ; (disabled :ids ()) + ) + ; Automation Router event-driven cross-panel rules + (workflows + :version "1.0.0" + ; Example: rebuild on file save + ; (rule :name "build-on-save" + ; (trigger :event "file-changed" :pattern "src/**/*.res") + ; (condition :panel "build-dashboard" :field "watchMode" :equals #t) + ; (action :panel "build-dashboard" :message "TriggerBuild" (args :target "game")) + ; :approval "auto-fire") ; auto-fire | require-approval | approve-once | dry-run-first + ) + ; Panel clade trait and capability overrides + (clades + :version "1.0.0" + ; Example: add a custom capability to a panel clade + ; (override :id "build-dashboard" (traits :has-work-items #t) :capabilities-add ("CustomCheck")) + ) + ; Custom panel bundles for this repo's workflow + (portfolios + :version "1.0.0")) + ; Bot directives — what agents and bots read at session start and update at + ; session end. Human guide: + ; .machine_readable/bot_directives/README.adoc. + (bot-directives + ; methodology — 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 (methodology layer) in hyperpolymath/standards + (methodology + (metadata + :version "1.0.0" + :last-updated "{{CURRENT_DATE}}" + :spec "https://github.com/hyperpolymath/standards/blob/main/1-formats/a2ml/agentic/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" + ; Hard ceiling for ring expansion (0-3) + :ring-ceiling 2 + ; Max waves before requiring user "keep going" + :wave-cap 2 + ; Every session must ship code, not just designs + :spike-required #t + ; ============================================================================ + ; 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 + (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. + (convergent-budget + ; % for new modules, compilation fixes, wiring, integration + :structural 70 + ; % for bugs found, broken imports, stale references + :corrective 20 + ; % for SPDX headers, doc updates, formatting, style + :perfective 10) + ; ============================================================================ + ; 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. + (unique-strength + :description "{{PROJECT_UNIQUE_STRENGTH}}" + :deepen-not-broaden #t) + ; ============================================================================ + ; 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. + (divergent-invariants + ; 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)", + :rules ()) + ; 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. + (known-constraints + ; Customise per project. Examples: + ; "End-to-end build has never been verified", + ; "libproject.so does not exist yet — all bindings call stubs", + :constraints ()) + ; ============================================================================ + ; STATE FILE VALIDATION + ; ============================================================================ + ; Phase 0 reads the repo deed (status) clause and docs/status/ROADMAP.adoc first, + ; but they may be broken. + ; These rules detect corrupt/template/stale state files. + (state-validation + ; A regex, not a literal list. The list form named the exact strings it was + ; meant to catch ("{{PROJECT}}"), so `just repo-init` substituted the detector along + ; with everything else and shipped reject-if-contains = ["MY_PROJECT", ...] — + ; a guard against unfilled tokens that had been eaten by the filling. The + ; escaped pattern below contains no token for init to match, and covers every + ; upper-snake token rather than the three anyone remembered to enumerate. + ; Enforced by scripts/check-no-placeholders.sh. + :reject-if-matches ("\\{\\{[A-Z][A-Z0-9_]*\\}\\}") + :reject-if-contains ("rsr-template-repo") + :reject-if-project-name-mismatch #t + :staleness-threshold-days 90 + :fallback-files ("TODO.md" "TODO.adoc" "ROADMAP.adoc" "README.adoc")))) + ; coverage — 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 (methodology layer) in hyperpolymath/standards + (coverage + (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)) + ; debt — Meander debt list + ; Things found but not fixed. Carried between sessions. + ; Becomes the next session's Phase 0 input. + ; + ; Reference: ADR-002 (methodology layer) in hyperpolymath/standards + (debt + (metadata + :version "1.0.0" + :last-updated "{{CURRENT_DATE}}")) + ; rra — directives for Robot Repo Automaton (RRA) enforcing the Platonic Ideal root. + (rra + :target "robot-repo-automaton" + (module + :name "root-cleaner" + ; mode can be "enforce" (auto-commit) or "putative" (write to /.auto-rr/ for human review) + (policy + :mode "putative" + :strictness "high") + ; Files that are strictly allowed to exist at the root. CLAUDE.md is the + ; generated arrival pack; git/Claude/pre-commit all read it from the ROOT. + ; The pattern ".*" allows hidden dotfiles implicitly; RRA checks specific + ; dotfile rules below. + (allow-list + :files ("README.adoc" "CHANGELOG.adoc" "Justfile" "LICENSE" "rsr-template-repo_chora.deed" "CITATION.cff" "CLAUDE.md") + :patterns (".*")) + ; Relocation rules: move heavy prose out of the root + (relocations + (move :pattern "*.adoc" :dest "docs/" :except ("README.adoc" "CHANGELOG.adoc")) + (move :pattern "GOVERNANCE.*" :dest "docs/") + (move :pattern "ARCHITECTURE.*" :dest "docs/") + (move :file "MAINTAINERS.adoc" :dest "docs/")) + ; Consolidation rules: reduce the dotfile "wall of noise" + (consolidations + ; Merge legacy environment trackers into mise + (merge :sources (".envrc" ".tool-versions") :engine "mise-translator" :dest ".config/mise.toml") + ; Ensure standard git attributes are consolidated + (merge :sources (".gitattributes-legacy" ".gitattributes-os") :dest ".gitattributes")) + ; Explicitly ignore certain paths from being cleaned + (ignores + :dirs ("src/" "tests/" ".git/" "docs/" ".machine_readable/"))))) + ; Optional ecosystem integrations. + ; Each clause is opt-in; delete the ones your project does not use. + (integrations + ; OPTIONAL: Feedback-o-Tron Integration — Autonomous Bug Reporting + ; Delete this clause if your project does not use feedback-o-tron. + (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 #t + :audit-logging #t + :auto-file-upstream "on-external-dependency-failure")) + ; OPTIONAL: Proven Integration — Formally Verified Safety Library + ; Delete this clause if your project does not use the proven library. + ; See https://github.com/hyperpolymath/proven for details. + (proven + (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")) + ; OPTIONAL: VeriSimDB Feed — Cross-Repo Analytics Data Store + ; Delete this clause if your project does not feed data to VeriSimDB. + ; See https://github.com/hyperpolymath/nextgen-databases for details. + (verisimdb + (integration + :name "verisimdb" + :type "data-feed" + :repository "https://github.com/hyperpolymath/nextgen-databases" + :data-store "verisimdb-data") + (feed-config + :emit-scan-results #t + :emit-build-metrics #t + :emit-dependency-graph #t + :format "hexad" + :destination "verisimdb-data/feeds/")) + ; OPTIONAL: Vexometer Integration — Irritation Surface Analysis + ; Delete this clause if your project does not use vexometer. + (vexometer + (integration + :name "vexometer" + :type "friction-measurement" + :repository "https://github.com/hyperpolymath/vexometer") + (measurement-config + :dimensions 10 + :emit-isa-reports #t + :lazy-eliminator #t + :satellite-interventions #t) + (hooks + :cli-tools "measure-on-error" + :ui-panels "measure-on-interaction" + :build-failures "measure-on-failure")) + ; groove — Groove Protocol manifest: the API surfaces this project exposes + ; Consumed by the Groove bridge / + ; zig-unified-api-adapter for snap-on/snap-off service discovery. Edit it to + ; match your project's actual APIs; `just groove-setup` writes :port and the + ; :enabled flags through scripts/deed-clause.sh. + ; See: https://github.com/hyperpolymath/standards/tree/main/groove-protocol + (groove + :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 + ; 0 = not assigned yet — run `just groove-setup` to assign + :port 0 + ; 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 () + ; API surfaces this project exposes (dodeca-API). Remove the ones you don't use. + (api-surfaces + (rest :enabled #t :path "/api/v1") + (grpc :enabled #f :port-offset 1) + (graphql :enabled #f :path "/graphql") + (websocket :enabled #f :path "/ws") + (sse :enabled #f :path "/events") + (groove :enabled #t :path "/.well-known/groove")))) + ; Maintenance and development policies, machine-readable canonical. + ; Human companions live in + ; docs/governance/. + (policies + ; Canonical maintenance governance model + (maintenance-axes + (metadata + :version "1.0.0" + :last-updated "{{CURRENT_DATE}}" + :scope "repo") + (discovery + :human-entrypoints ( + "README.adoc" + "docs/governance/MAINTENANCE-CHECKLIST.adoc" + "docs/governance/SOFTWARE-DEVELOPMENT-APPROACH.adoc" + ) + :machine-entrypoints ( + "*_chora.deed (policies (maintenance-axes))" + "*_chora.deed (policies (maintenance-checklist))" + "*_chora.deed (policies (software-development-approach))" + "*_chora.deed" + ".machine_readable/ai/README.adoc" + "*_chora.deed (bot-directives)" + ) + :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 #t + :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 #t + :adaptive-second #t + :adaptive-focus "scope changes, stale references, obsolete work culling" + :perfective-third #t + :perfective-source "honest state from axis-1 after corrective/adaptive updates") + (axis-3-audit + :systems-check #t + :compliance-check #t + :effects-check #t + :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")) + ; Cross-repo maintenance baseline (machine-readable canonical) + (maintenance-checklist + (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 "*_chora.deed (policies (software-development-approach))") + (policy + :single-source #t + :notes "Use this clause as canonical machine policy and keep the AsciiDoc synchronized.") + (maintenance-axes + :scoping-first #t + :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 #t + :adaptive-second #t + :adaptive_examples ( + "scope-change reconciliation" + "stale-reference removal" + "obsolete-work culling" + ) + :perfective-third #t + :perfective_source "axis-1 honest state after corrective/adaptive updates") + (axis-3-audit-rules + :systems-check #t + :documentation-honesty-check #t + :safety-security-accounted-check #t + :effects-review-check #t + :benchmark-evidence-required #t + :maintainer-dialogue-review-required #t + :compliance-seams-check #t + :exception-register-required #t + :exception-bounded-scope-required #t + :policy-drift-contamination-check #t + :example-drift-risk "single TypeScript exception causing broad ->TypeScript migration" + :compliance-tooling "panic-attack" + :effects-tooling "ecological checking with sustainabot guidance") + (generic-cleanup-finish-off + :root-cleanup-required #t + :stale-work-cull-required #t + :docs-parity-required #t + :machine-human-sync-required #t + :compliance-finish-off-required #t + :effects-finish-off-required #t + :release-prep-summary-required #t + :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 ( + "*_chora.deed (anchor)" + ".machine_readable/contractiles/" + ".machine_readable/ai/" + ".machine_readable/bot_directives/" + ) + :contractiles_required ( + ".machine_readable/contractiles/must/" + ".machine_readable/contractiles/trust/" + ".machine_readable/contractiles/intend/" + ) + :security_required ("www/.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 #t + :well_known_metadata #t + :roadmap_honesty_with_dates #t + :ci_doc_format_policy #t) + (could + :generate_human_from_machine #t + :mode_aware_bots ("corrective" "adaptive" "perfective" "audit") + :topology_dashboard #t + :exception_registry #t)) + ; General software development approach (machine-readable) + (software-development-approach + (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 #t + :stale-work-cull #t + :docs-sync-human-machine #t + :compliance-audit #t + :effects-audit #t + :release-summary ("must" "should" "could") + :next-actions ("corrective" "adaptive" "perfective")) + (collaboration + :maintainer-dialogue-required #t + :dialogue-topics ("what changed" "why" "remaining risks"))) + ; Component Readiness Grades (CRG v1.0) — the machine-readable grade + ; standard; the human companion is docs/governance/CRG-CRITERIA.adoc. + (crg-criteria + (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 + :rules ( + "Each assessable component MUST have a grade from {X, F, E, D, C, B, A}." + "Each grade above X MUST be supported by evidence per section 4." + "Assessments MUST be recorded in a version-controlled location." + "Assessments MUST be reviewed at least once per release cycle." + "Release stages MUST respect minimum grade thresholds."))) + ; Triaxial Software Development Methodology — the machine-readable axes; + ; the human companion is docs/governance/TSDM.adoc. + (tsdm + :id "tsdm-standard" + :version "1.0.0" + (axes + (axis :ordinal 1 :name "Planning" :levels ("must" "should" "could")) + (axis :ordinal 2 :name "Maintenance" :levels ("corrective" "adaptive" "perfective")) + (axis :ordinal 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"))) + ; rsr-profile — this repo's declared RSR v2.0 capabilities. + ; It carries no canon pin: the (canon) clause above is the pin, exactly once. + ; + ; It declares which capabilities this repo has, + ; per 0-canon/TEMPLATE-APPLICABILITY-POLICY.adoc; the RSR v2.0 conformance oracle + ; (hypatia Hypatia.Rules.RsrConformance) uses `capabilities` to compute the + ; APPLICABLE criteria set — a gated criterion is scored only when its gating + ; capability appears below; everything else is `na` and excluded from the + ; denominator. + ; + ; rsr-template-repo is deliberately MAXIMAL: it ships scaffolding for FFI/ABI + ; seams, in-tree formal proofs, a container, a reproducible build, benchmarks, + ; a docs site, and the full governance trio — so a repo scaffolded FROM it can + ; adopt any of them. Its declared set is therefore near-total, which is exactly + ; what makes it the dogfood target (the gate requires Gold on the applicable + ; set). Every capability below is grounded in a file/dir that actually exists + ; in this tree; capabilities it does NOT have (rust, affinescript, mobile, + ; web-ui, api-service, published-package) are omitted so the oracle does not + ; score this repo against modules it does not carry. + (rsr-profile + :version "1.0.0" + :spec "rsr-criteria-v2" + :declares-against "2.1.1-draft" + ; Role in the estate pipeline: standards (canon) -> THIS (spine) -> scaffoldia + ; (composer) -> minted repos. A spine may carry capability-gated modules it + ; does not declare, for the repos minted from it; see [carrier] in the canon + ; gates table. A minted repo doing the same is still drift. + :role "spine" + ; Effective capability set (direct declaration; no preset shorthand used). + :capabilities ( + ; src/interface/ffi/build.zig + Zig FFI layer + "zig" + ; src/interface/abi.ipkg + src/interface/Abi/ (dependent-typed ABI) + "idris2" + ; scripts/*.sh automation + "bash" + ; src/ command-line entry scaffolding + "cli" + ; consumed/published as a library surface + "library" + ; C-ABI FFI seam (Zig), src/interface/ffi/ + "ffi" + ; formally specified ABI: src/interface/abi.ipkg + src/interface/Abi/ proofs + "abi" + ; verification/proofs/ (in-tree mechanised proofs) + "formal-proofs" + ; .github/workflows/pages.yml (casket/Pages) + "docs-site" + ; build/container/ + .devcontainer/Containerfile + "container" + ; build/guix.scm + "reproducible-build" + ; benches/ + "benchmarks" + ; full AUDIT/AFFIRMATION/GOVERNANCE/MAINTAINERS trio + "governance-tier" + ) + (notes + ; Capabilities intentionally NOT declared (no corresponding code in tree): + ; rust — no *.rs / Cargo.toml (the FFI/ABI layer is Zig + Idris2) + ; affinescript — no *.affine + ; mobile — no Tauri/Dioxus app + ; web-ui — no browser UI + ; api-service — not a network daemon + ; published-package — a scaffold template, not itself a registry artifact + :omitted-rationale "Declaring a capability this repo lacks would make the oracle score it against a module it does not carry — the over-scaffolding failure v2.0 fixes. See 0-canon/TEMPLATE-APPLICABILITY-POLICY.adoc.")) + ; Egress attestation (standards ADR-009; grammar + ; 1-formats/deed/spec/abnf/clauses/egress.abnf). Every job that reads a real + ; secret (anything but GITHUB_TOKEN) is listed with exactly the secrets it + ; reads, the endpoints outside GitHub it reaches, and what holds it to them. + ; Hypatia RE001 accepts an entry here in place of step-security/harden-runner + ; and reports drift between an entry and its workflow. A minted repo inherits + ; these entries with the workflows; when you add secrets.* to a job, or + ; delete a workflow listed here, change this clause in the same commit. + (egress + :policy "standards ADR-009" + (job + :workflow ".github/workflows/push-email-notify.yml" + :job "notify" + :secrets ("SMTP_HOST" "SMTP_PORT" "SMTP_USER" "SMTP_PASS") + :endpoints ("secret:SMTP_HOST") + :enforcement none + :reason "Sends the push notification by SMTP submission to the org mail host, whose name is itself a secret.") + (job + :workflow ".github/workflows/sonarqube.yml" + :job "sonarqube" + :secrets ("SONAR_TOKEN") + :endpoints ("sonarcloud.io" "*.sonarcloud.io" "binaries.sonarsource.com" "keyserver.ubuntu.com" "keys.openpgp.org") + :enforcement none + :reason "Uploads the CI-based analysis to SonarQube Cloud. Skipped when SONAR_TOKEN is unset. SonarSource/sonarqube-scan-action v8.3.0 downloads the scanner from binaries.sonarsource.com and, with signature verification on (its default), fetches the signing key from keyserver.ubuntu.com, falling back to keys.openpgp.org.") + (job + :workflow ".github/workflows/build-notification.yml" + :job "trigger-boj" + :secrets ("BOJ_SERVER_URL") + :endpoints ("secret:BOJ_SERVER_URL" "var:BOJ_SERVER_URL") + :enforcement none + :reason "Notifies the BoJ server of a push. The URL is the secret when set, else the variable that also gates the job.")) ) diff --git a/scripts/bench-stats.jq b/scripts/bench-stats.jq new file mode 100644 index 00000000..55f62eb2 --- /dev/null +++ b/scripts/bench-stats.jq @@ -0,0 +1,96 @@ +# SPDX-License-Identifier: MPL-2.0 +# +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# Shared statistics for the benchmark regression gate. +# +# ONE definition, included (`jq -L scripts 'include "bench-stats"; ...'`) by +# both scripts/compute-bench-baseline.sh and scripts/check-bench-regression.sh, +# so the baseline and the check cannot drift into computing different +# statistics. Inputs are proven-bench JSON v1 documents as written by +# `proven-bench --json` (benchmarks/Benchmark.idr, `runJSON`). + +# bench_errors: the list of shape errors in a proven-bench v1 run document. +# An empty list means the document is usable. Shape is checked, not merely +# presence: `log` of a zero or negative median is silently -inf/nan in jq, so +# a median that is not a positive number must be refused here. +def bench_errors: + if type != "object" then ["not a JSON object"] + else + [ (if .schema_version != 1 + then "schema_version is \(.schema_version | tojson), expected 1" else empty end), + (if .suite != "proven-bench" + then "suite is \(.suite | tojson), expected \"proven-bench\"" else empty end), + (if (.results | type) != "array" or (.results | length) < 3 + then "results must be an array of at least 3 workloads (each ratio needs >= 2 others)" + else empty end) + ] + + (if (.results | type) == "array" then + [ .results[] + | if type != "object" then "a result is not a JSON object" + elif (.name | type) != "string" or .name == "" then "a result has no name" + elif (.median_ns | type) != "number" or .median_ns <= 0 + then "\(.name): median_ns \(.median_ns | tojson) is not a positive number" + elif (.iterations | type) != "number" or .iterations <= 0 + then "\(.name): iterations \(.iterations | tojson) is not a positive number" + else empty end ] + + ([ .results[] | .name? | select(type == "string") ] + | group_by(.) | map(select(length > 1) | "duplicate workload name \(.[0] | tojson)")) + else [] end) + end; + +# checksum_errors: one error per workload whose checksum is not true. Applied +# to the CURRENT run only. It is deliberately not part of bench_errors, which +# also vets baseline inputs: before 2026-10-06 (#85) the checksum was an XOR +# parity that read False on every run whatever the predicates did, so the +# historical artifacts a baseline is cut from carry a checksum that means +# nothing. Since #85 the bench asserts it and exits non-zero itself; this is +# the second line of defence for a JSON that reached the gate anyway. +def checksum_errors: + [ .results[] + | select(.checksum != true) + | "\(.name): checksum is \(.checksum | tojson) - the workload is broken, its timing measures nothing" ]; + +# medians: {workload name: median_ns} for a valid run document. +def medians: .results | map({key: .name, value: .median_ns}) | from_entries; + +# iterations_map: {workload name: iterations} for a valid run document. +def iterations_map: .results | map({key: .name, value: .iterations}) | from_entries; + +# loo_ratios: {workload name: leave-one-out ratio} for a valid run document. +# Each workload's median divided by the GEOMETRIC mean of the medians of every +# OTHER workload in the same run. Leaving the workload itself out of its own +# denominator means a regression in workload W raises only W's ratio (and +# lowers the others'), so a slowdown can only ever be blamed on the workload +# that slowed down. +def loo_ratios: + medians as $m + | ($m | keys) as $ks + | reduce $ks[] as $k ({}; + .[$k] = $m[$k] / ([ $ks[] | select(. != $k) | $m[.] | log ] | add / length | exp)); + +# baseline_errors: the list of shape errors in a baseline document written by +# scripts/compute-bench-baseline.sh. An empty list means it is usable. +def baseline_errors: + if type != "object" then ["not a JSON object"] + else + [ (if .kind != "proven-bench-baseline" + then "kind is \(.kind | tojson), expected \"proven-bench-baseline\"" else empty end), + (if .schema_version != 1 + then "schema_version is \(.schema_version | tojson), expected 1" else empty end), + (if (.workloads | type) != "object" or (.workloads | length) < 3 + then "workloads must be an object holding at least 3 workloads" else empty end) + ] + + (if (.workloads | type) == "object" then + [ .workloads | to_entries[] + | .key as $n | .value + | if type != "object" then "\($n): entry is not a JSON object" + elif (.mean_median_ns | type) != "number" or .mean_median_ns <= 0 + then "\($n): mean_median_ns \(.mean_median_ns | tojson) is not a positive number" + elif (.mean_loo_ratio | type) != "number" or .mean_loo_ratio <= 0 + then "\($n): mean_loo_ratio \(.mean_loo_ratio | tojson) is not a positive number" + elif (.iterations | type) != "number" or .iterations <= 0 + then "\($n): iterations \(.iterations | tojson) is not a positive number" + else empty end ] + else [] end) + end; diff --git a/scripts/check-bench-regression.sh b/scripts/check-bench-regression.sh new file mode 100755 index 00000000..724f5d1a --- /dev/null +++ b/scripts/check-bench-regression.sh @@ -0,0 +1,157 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# Benchmark regression gate (ultraplan Phase 3b; ROADMAP 2a; DEBT I-1). +# +# Usage: scripts/check-bench-regression.sh +# +# Compares one proven-bench JSON v1 run against benchmarks/baseline.json and +# classifies each workload on the taxonomy's Six Sigma scale. +# +# WHY RATIOS, NOT NANOSECONDS +# --------------------------- +# CI runs on shared GitHub runners whose CPU class varies from run to run. +# Over 28 green main runs (2026-08-10 .. 2026-10-06) the same workload's +# absolute median ranged from 0.44x to 1.65x the baseline mean (a 3.8x +# spread); a gate on absolute time at the taxonomy's 50% would have failed +# green runs routinely, and a gate that fails randomly gets disabled. Much of +# that spread is common-mode — a slower machine slows every workload — so the +# primary statistic divides it out: each workload's median over the geometric +# mean of the OTHER workloads' medians in the same run (leave-one-out, see +# scripts/bench-stats.jq). Its spread over the same runs is 0.67x .. 1.51x. +# It does not vanish entirely, because runner classes do not slow every +# workload by the same factor (effectStackValid and ceremonyEndsProperly move +# together; relationTransitive and coveredCatAspect move together). +# +# THE TOLERANCES, AND HOW THEY WERE CHOSEN (manual override, stated) +# ------------------------------------------------------------------ +# * LOO_FAIL = 2.0. Max observed leave-one-out ratio vs the baseline: 1.515 +# over 28 main runs (2nd highest 1.431), 1.527 over 27 branch/PR runs. The +# taxonomy's 1.5x hard-fail would have failed green runs, so this departs +# from it (taxonomy Part IV permits a manual override with a reason; this is +# the reason). Margin: 2.0 / 1.527 = 1.31x. A 3x slowdown of one workload +# is caught even on the most favourable observed runner (3 x 0.67 = 2.02). +# * ABS_FAIL = 2.5, on absolute median vs baseline mean. The ratio statistic +# is BLIND to a uniform slowdown (every workload 3x slower leaves every ratio +# at 1.0), so this backstop catches what ratios cannot. Max observed 1.65 +# (main) / 1.62 (branches); margin 2.5 / 1.65 = 1.52x. A uniform 3x +# slowdown is caught; a uniform slowdown under 2.5x is NOT (stated blind +# spot, recorded in TEST-NEEDS.adoc Gap C). Likewise a CORRELATED slowdown +# of two of the four workloads partly hides itself: both 2.5x slower gives +# each a ratio of 2.5 / 2.5^(1/3) = 1.84x, under LOO_FAIL. +# * EXTRA = 0.5 on the ratio: below it a workload is EXTRAORDINARY — passed, +# but flagged for investigation (real improvement or measurement artefact). +# Min observed 0.67. +# * There is no separate "Acceptable" (soft-fail, 20-50%) band: the measured +# noise envelope already spans it, so a warning there would fire on green +# runs and carry no information. +# +# Exit codes (check-toolchain-pins.sh convention): +# 0 every workload Ordinary or Extraordinary +# 1 at least one workload Unacceptable (named on stdout) +# 2 NO CHECK WAS PERFORMED: a file is missing or malformed, or the workload +# sets / iteration counts disagree. A skip is not a pass. + +set -uo pipefail + +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" || { echo "FAIL: cannot locate script directory" >&2; exit 2; } + +LOO_FAIL=2.0 +ABS_FAIL=2.5 +EXTRA=0.5 + +# inert: report that no check was performed, and why, then exit 2. +inert() { + echo "bench-regression: $*" >&2 + echo "bench-regression: NO CHECK WAS PERFORMED - a skip is not a pass." >&2 + if [ -n "${GITHUB_ACTIONS:-}" ]; then + echo "::error title=Bench regression gate inert::$*" + fi + exit 2 +} + +# validate: refuse a file that is missing, unparseable, or ill-shaped. $1 is +# a label, $2 the path, $3 the bench-stats.jq error function to apply. +validate() { + local label="$1" f="$2" fn="$3" errs + [ -f "$f" ] || inert "$label '$f' does not exist" + if ! errs="$(jq -L "$SCRIPT_DIR" -r "include \"bench-stats\"; ${fn}[]" "$f")"; then + inert "$label '$f' is not parseable JSON" + fi + if [ -n "$errs" ]; then + printf '%s\n' "$errs" | sed "s|^| $label: |" >&2 + inert "$label '$f' is malformed" + fi +} + +[ "$#" -eq 2 ] || inert "usage: $0 " +CURRENT="$1" +BASELINE="$2" + +validate "baseline" "$BASELINE" baseline_errors +validate "current run" "$CURRENT" bench_errors +validate "current run" "$CURRENT" checksum_errors + +# A workload present on only one side is not a pass: either the bench lost a +# workload (nothing measured it) or the baseline is for a different workload +# set (nothing to compare it to). Same for a changed iteration count, which +# redefines the workload (Benchmark.idr: workloads are FROZEN). +mismatch="$(jq -L "$SCRIPT_DIR" -r --slurpfile b "$BASELINE" ' + include "bench-stats"; + ($b[0].workloads) as $base + | iterations_map as $cur + | ( [ $base | keys[] | select($cur[.] == null) | "MISSING from current run: \(.)" ] + + [ $cur | keys[] | select($base[.] == null) | "MISSING from baseline: \(.)" ] + + [ $cur | to_entries[] | select($base[.key] != null and $base[.key].iterations != .value) + | "iterations changed for \(.key): baseline \($base[.key].iterations), current \(.value) - cut a new baseline" ] + )[] +' "$CURRENT")" || inert "jq failed while comparing workload sets" +if [ -n "$mismatch" ]; then + printf '%s\n' "$mismatch" | sed 's/^/bench-regression: /' + inert "the current run and the baseline do not measure the same workloads" +fi + +# One line per workload: name, ratio-vs-baseline, absolute-vs-baseline, class. +verdicts="$(jq -L "$SCRIPT_DIR" -r --slurpfile b "$BASELINE" \ + --argjson loo_fail "$LOO_FAIL" --argjson abs_fail "$ABS_FAIL" --argjson extra "$EXTRA" ' + include "bench-stats"; + ($b[0].workloads) as $base + | loo_ratios as $loo + | medians as $med + | $base | keys[] + | . as $n + | ($loo[$n] / $base[$n].mean_loo_ratio) as $rx + | ($med[$n] / $base[$n].mean_median_ns) as $ax + | [ $n, + ($rx * 1000 | round / 1000 | tostring), + ($ax * 1000 | round / 1000 | tostring), + (if $rx > $loo_fail or $ax > $abs_fail then "UNACCEPTABLE" + elif $rx < $extra then "EXTRAORDINARY" + else "ORDINARY" end) ] + | @tsv +' "$CURRENT")" || inert "jq failed while classifying workloads" +[ -n "$verdicts" ] || inert "classification produced no verdicts" + +echo "bench-regression: $(basename "$CURRENT") vs $(basename "$BASELINE")" +echo "bench-regression: fail if ratio > ${LOO_FAIL}x baseline ratio, or absolute > ${ABS_FAIL}x baseline mean" +regressed=() +while IFS=$'\t' read -r name rx ax class; do + printf ' %-22s ratio %6sx absolute %6sx %s\n' "$name" "$rx" "$ax" "$class" + case "$class" in + UNACCEPTABLE) + regressed+=("$name") + if [ -n "${GITHUB_ACTIONS:-}" ]; then + echo "::error title=Benchmark regression::$name is Unacceptable: ratio ${rx}x (limit ${LOO_FAIL}x), absolute ${ax}x (limit ${ABS_FAIL}x)" + fi ;; + EXTRAORDINARY) + echo " ^ Extraordinary: real improvement or measurement artefact? Re-cut the baseline only if confirmed." ;; + esac +done <<<"$verdicts" + +if [ "${#regressed[@]}" -gt 0 ]; then + echo "bench-regression: FAIL - Unacceptable regression in: ${regressed[*]}" + exit 1 +fi +echo "bench-regression: OK - no workload regressed beyond tolerance" diff --git a/scripts/check-container-pins.sh b/scripts/check-container-pins.sh new file mode 100644 index 00000000..1784f31a --- /dev/null +++ b/scripts/check-container-pins.sh @@ -0,0 +1,227 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# check-container-pins.sh — every base image in a Containerfile is pinned by +# digest, and no Dockerfile is shipped. +# +# ── Why this exists ───────────────────────────────────────────────────────── +# +# The estate's Trustfile carries a check called `container-images-pinned`. Its +# probe, as shipped, was: +# +# test ! -f Containerfile || grep -q 'cgr.dev\|@sha256:' Containerfile +# +# which passes on `FROM cgr.dev/chainguard/wolfi-base:latest`. It asks "is one of +# the good registries named anywhere in the file", not "is every base image +# pinned", so the gate could not fail on the exact case it was named for — and a +# template that shipped two floating `:latest` stages passed it in every repo +# minted from it. +# +# A digest is the only reference that cannot move. A tag is a pointer the +# upstream may repoint at any time; `:latest` is a pointer that is *meant* to be +# repointed. So: +# +# * every FROM must carry `@sha256:<64 hex>`; +# * `FROM scratch` and `FROM ` are allowed (there is no remote +# image to pin); +# * a variable/ARG base is a FAIL: the pin would live at build time, outside +# the file the gate reads, so the check could not see it; +# * a Dockerfile is a FAIL (estate convention: Containerfile). +# +# ── Usage ─────────────────────────────────────────────────────────────────── +# check-container-pins.sh [--root DIR] [--quiet] +# +# Exit: 0 = pinned (or no Containerfile); 1 = findings; 2 = usage error. +# +# A repository that ships NO Containerfile passes: shipping one is the repo's +# choice, and the template now only ships it to archetypes that declare the +# `container` capability. What is not allowed is shipping a floating one. + +set -uo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" +QUIET=0 +while [ $# -gt 0 ]; do + case "$1" in + --root) ROOT="${2:-}"; shift 2 ;; + --quiet) QUIET=1; shift ;; + -h|--help) sed -n '2,40p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; + *) echo "check-container-pins: unknown option: $1" >&2; exit 2 ;; + esac +done +[ -d "$ROOT" ] || { echo "check-container-pins: not a directory: $ROOT" >&2; exit 2; } +ROOT="$(cd "$ROOT" && pwd)" + +ok() { [ "$QUIET" -eq 1 ] || printf ' \033[32mPASS\033[0m %s\n' "$1"; } +bad() { printf ' \033[31mFAIL\033[0m %s\n' "$1"; } +note() { [ "$QUIET" -eq 1 ] || printf ' %s\n' "$1"; } + +# Absolute paths, whichever source they came from. `git -C DIR ls-files` emits +# paths relative to DIR, so a relative result only resolved while the caller's +# cwd happened to BE the repository: `--root /elsewhere` silently found no +# Containerfiles at all and reported "nothing to pin". Measured while minting, +# where the gate runs from the template's cwd against a child tree. +list_files() { + if git -C "$ROOT" rev-parse --is-inside-work-tree >/dev/null 2>&1; then + git -C "$ROOT" ls-files -z --cached --others --exclude-standard \ + | while IFS= read -r -d '' f; do printf '%s\0' "$ROOT/$f"; done + else + find "$ROOT" -type f -print0 + fi | while IFS= read -r -d '' f; do + case "$f" in */.git/*|*/node_modules/*|*/target/*|*/_build/*|*/deps/*) continue ;; esac + # The index is not the work tree: the mint gates a tree it has already + # pruned but not yet committed, so git still lists paths that are gone. + [ -f "$f" ] || continue + printf '%s\n' "$f" + done +} + +mapfile -t FILES < <(list_files | sort -u) + +# Scope, stated rather than implied: +# * a DEV container (.devcontainer/) is a rebuild-daily development +# environment, not an artifact that ships, so it is out of this gate's +# remit — the same scope the estate's own Trustfile probe has (it reads the +# ROOT Containerfile only). It is named here so the exclusion is visible; +# * build/container/Containerfile, if a repository has one, is CARRIER data +# carried over from the template's container module: the template ships the +# module (not the Containerfile — see build/container/README.adoc), and +# prunes it from every archetype that declares no `container` capability. +# While this tree is the template (archetypes/ present), that path is not +# deployed from it. +IS_TEMPLATE=0 +[ -d "$ROOT/archetypes" ] && IS_TEMPLATE=1 + +CONTAINERFILES=() +DOCKERFILES=() +SKIPPED=() +for f in "${FILES[@]}"; do + rel="${f#"$ROOT"/}" + case "$rel" in + .devcontainer/*|*/.devcontainer/*) + case "${rel##*/}" in + Containerfile|Containerfile.*|*.Containerfile) SKIPPED+=("$rel (dev container)") ;; + esac + continue ;; + esac + case "$rel" in + build/container/Containerfile|container/Containerfile) + if [ "$IS_TEMPLATE" -eq 1 ]; then SKIPPED+=("$rel (carrier: template only)"); continue; fi ;; + esac + case "${rel##*/}" in + Dockerfile|Dockerfile.*|*.Dockerfile) DOCKERFILES+=("$rel") ;; + Containerfile|Containerfile.*|*.Containerfile|*.containerfile) CONTAINERFILES+=("$rel") ;; + esac +done + +FAILS=0 + +if [ ${#DOCKERFILES[@]} -gt 0 ]; then + bad "${#DOCKERFILES[@]} Dockerfile(s) — the estate spelling is Containerfile" + for f in "${DOCKERFILES[@]}"; do printf ' %s\n' "$f"; done + note "Rename to Containerfile and update the engine invocation (podman -f)." + FAILS=$((FAILS + 1)) +fi + +if [ "$QUIET" -eq 0 ] && [ ${#SKIPPED[@]} -gt 0 ]; then + for s in "${SKIPPED[@]}"; do printf ' \033[34minfo\033[0m out of scope: %s\n' "$s"; done +fi + +if [ ${#CONTAINERFILES[@]} -eq 0 ]; then + # FAILS is already non-zero when a Dockerfile was found above. Taking the + # "nothing to pin" success path there reported PASS for the one repository + # shape this branch exists to catch. + if [ "$FAILS" -ne 0 ]; then + note "Why: TRUST-DEFAULTS-POLICY §containers, Trustfile check container-images-pinned." + exit 1 + fi + ok "no shipped Containerfile — nothing to pin (shipping one is optional)" + exit 0 +fi + +# A reference is pinned when it names a digest and nothing else can move it. +is_pinned() { + local ref="$1" + case "$ref" in + *'$'*|*'@'*) : ;; # a variable or a digest: judged below + esac + case "$ref" in + *'$'*) return 1 ;; # build-time pin: not visible here + *@sha256:*) + local d="${ref##*@sha256:}" + case "$d" in + *[!0-9a-f]*) return 1 ;; + *) [ ${#d} -eq 64 ] && return 0 || return 1 ;; + esac + ;; + *) return 1 ;; + esac +} + +for cf in "${CONTAINERFILES[@]}"; do + STAGES=" " + HAD_FROM=0 + while IFS= read -r line; do + # FROM is case-insensitive and may carry --platform=; comments ignored. + stripped="$(printf '%s' "$line" | sed -e 's/^[[:space:]]*//' -e '/^#/d')" + case "$stripped" in [Ff][Rr][Oo][Mm][[:space:]]*) ;; *) continue ;; esac + HAD_FROM=1 + # shellcheck disable=SC2086 + set -- $stripped + shift # drop FROM + while [ $# -gt 0 ]; do # drop --platform=… and friends + case "$1" in --*) shift ;; *) break ;; esac + done + ref="${1:-}" + stage="" + if [ "${2:-}" = "AS" ] || [ "${2:-}" = "as" ]; then stage="${3:-}"; fi + # Register the stage name FIRST: `FROM image@sha256:… AS build` is a + # pinned line, so it `continue`s below, and a later `FROM build` then + # looked like an unpinned remote image because its stage had never been + # recorded. Measured on the ordinary multi-stage shape. + [ -n "$stage" ] && STAGES="$STAGES$stage " + if [ -z "$ref" ]; then + bad "$cf: FROM with no image reference" + FAILS=$((FAILS + 1)) + continue + fi + case "$ref" in + scratch) continue ;; + esac + case "$STAGES" in *" $ref "*) continue ;; esac # a previous stage, not an image + if is_pinned "$ref"; then + continue + fi + case "$ref" in + *:latest|*:latest@*) + bad "$cf: floating base image '$ref'" + note "pin: $ref@sha256: — resolve the digest with podman image inspect " ;; + *'$'*) + bad "$cf: base image from a variable '$ref' — the pin lives outside this file" + note "use a literal @sha256:, or the gate cannot see the pin" ;; + *@sha256:*) + bad "$cf: malformed digest in '$ref' (need exactly 64 lowercase hex)" + note "digests look like: cgr.dev/chainguard/wolfi-base@sha256:$(printf '0%.0s' $(seq 1 64))" ;; + *:*) + bad "$cf: base image '$ref' has a tag but no digest" + note "a tag can be repointed; add @sha256: beside it" ;; + *) + bad "$cf: base image '$ref' has no tag and no digest (implicit :latest)" + note "add @sha256:" ;; + esac + FAILS=$((FAILS + 1)) + done < "$ROOT/$cf" + if [ "$HAD_FROM" -eq 0 ]; then + bad "$cf: no FROM line — this file builds nothing" + FAILS=$((FAILS + 1)) + fi +done + +if [ "$FAILS" -eq 0 ]; then + ok "container base images pinned by digest (${#CONTAINERFILES[@]} Containerfile(s))" + exit 0 +fi +note "Why: TRUST-DEFAULTS-POLICY §containers, Trustfile check container-images-pinned." +exit 1 diff --git a/scripts/check-escape-hatches.sh b/scripts/check-escape-hatches.sh new file mode 100755 index 00000000..9577ac77 --- /dev/null +++ b/scripts/check-escape-hatches.sh @@ -0,0 +1,210 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# The honesty lint (from hyperpolymath/proven-tests-and-benches): fail if any +# proof escape hatch appears in Idris2 sources or if '%default total' is absent +# or placed after a declaration. +# +# Exit codes (proven-tests-and-benches 3-outcome convention): +# 0 no escape hatches found across >= 1 .idr file +# 1 at least one escape hatch or missing/misplaced '%default total' found +# 2 the scan could not be performed (missing/unreadable directory or 0 .idr +# files — a skip is NOT a pass) +set -uo pipefail + +if [ "$#" -gt 0 ]; then + SCOPE=("$@") +else + SCOPE=(src verification .machine_readable/coaptation) +fi + +LITERAL_PATTERNS='believe_me|assert_total|assert_smaller|%partial|%default (partial|covering)|unsafePerformIO|idris_crash' +PARTIAL_DECL='^[[:space:]]*((public )?export[[:space:]]+|private[[:space:]]+)?partial([[:space:]]|$)' +COVERING_DECL='^[[:space:]]*((public )?export[[:space:]]+|private[[:space:]]+)?covering([[:space:]]|$)' +COVERING_ALLOWED=() +HOLE_PATTERN='(^|[[:space:](=,[])\?[a-zA-Z_][a-zA-Z0-9_'"'"']*' + +missing=0 +for dir in "${SCOPE[@]}"; do + if [ ! -d "$dir" ]; then + echo "check-escape-hatches: scope directory '$dir' does not exist" >&2 + missing=1 + fi +done +if [ "$missing" -ne 0 ]; then + echo "FAIL: NO SCAN WAS PERFORMED — the scan scope is incomplete." >&2 + echo " A missing directory is not a clean result." >&2 + exit 2 +fi + +FIND_OUT="$(mktemp)" +trap 'rm -f "$FIND_OUT"' EXIT +if ! find "${SCOPE[@]}" -name '*.idr' -type f > "$FIND_OUT"; then + echo "check-escape-hatches: find failed while scanning scope (${SCOPE[*]})" >&2 + echo "FAIL: NO SCAN WAS PERFORMED — an unreadable directory is not a clean result." >&2 + exit 2 +fi +mapfile -t IDR_FILES < <(LC_ALL=C sort "$FIND_OUT") +if [ "${#IDR_FILES[@]}" -eq 0 ]; then + echo "check-escape-hatches: 0 .idr files found in scope (${SCOPE[*]})" >&2 + echo "FAIL: NO SCAN WAS PERFORMED — an empty proof corpus is not a pass." >&2 + exit 2 +fi + +echo "Scanning ${#IDR_FILES[@]} Idris2 file(s) for proof escape hatches in: ${SCOPE[*]}" + +hits=0 + +# Strip line and nested block comments once per file (preserving quoted comment +# markers inside Idris strings and exact line numbers) for all passes. +STRIP_DIR="$(mktemp -d)" +trap 'rm -f "$FIND_OUT"; rm -rf "$STRIP_DIR"' EXIT + +# strip_idr_comments FILE — print source without line/doc or nested block comments, +# preserving line numbers and quoted comment markers in string literals. +strip_idr_comments() { + awk ' + BEGIN { bs = sprintf("%c", 92); dq = sprintf("%c", 34); depth = 0 } + depth == 0 && /^[[:space:]]*\|\|\|/ { print ""; next } + depth == 0 && index($0, "--") == 0 && index($0, "{-") == 0 { print; next } + { + out = ""; in_str = 0; n = length($0) + for (i = 1; i <= n; i++) { + c = substr($0, i, 1) + if (depth > 0) { + if (c == "{" && i < n && substr($0, i + 1, 1) == "-") { depth++; i++ } + else if (c == "-" && i < n && substr($0, i + 1, 1) == "}") { depth--; i++ } + out = out " " + } else if (in_str) { + out = out c + if (c == bs && i < n) { + i++ + out = out substr($0, i, 1) + } else if (c == dq) { + in_str = 0 + } + } else { + if (c == "{" && i < n && substr($0, i + 1, 1) == "-") { + depth++ + i++ + out = out " " + } else if (c == dq) { + in_str = 1 + out = out c + } else if (c == "-" && i < n && substr($0, i + 1, 1) == "-") { + break + } else { + out = out c + } + } + } + print out + } + ' "$1" +} + +declare -A STRIPPED_FILE=() +idx_f=0 +for f in "${IDR_FILES[@]}"; do + idx_f=$((idx_f + 1)) + sf="$STRIP_DIR/$idx_f.idr" + strip_idr_comments "$f" > "$sf" + STRIPPED_FILE["$f"]="$sf" +done + +# scan_idr_code REGEX — print matching stripped lines as file:line:code. +# Scan IDR_FILES via STRIPPED_FILE; return 0 if any line matches, 1 otherwise. +scan_idr_code() { + local pattern="$1" f line_no=0 found=0 + for f in "${IDR_FILES[@]}"; do + line_no=0 + while IFS= read -r code || [ -n "$code" ]; do + line_no=$((line_no + 1)) + if [[ "$code" =~ $pattern ]]; then + printf '%s:%d:%s\n' "$f" "$line_no" "$code" + found=1 + fi + done < "${STRIPPED_FILE[$f]}" + done + return $(( 1 - found )) +} + +if scan_idr_code "$LITERAL_PATTERNS"; then + hits=1 +fi + +if scan_idr_code "$HOLE_PATTERN"; then + hits=1 +fi + +if scan_idr_code "$PARTIAL_DECL"; then + hits=1 +fi + +for f in "${IDR_FILES[@]}"; do + sf="${STRIPPED_FILE[$f]}" + mapfile -t cov_lines < "$sf" + for (( idx = 0; idx < ${#cov_lines[@]}; idx++ )); do + code="${cov_lines[$idx]}" + if [[ "$code" =~ $COVERING_DECL ]]; then + line_no=$((idx + 1)) + next_line="${cov_lines[$((idx + 1))]:-}" + name="$(printf '%s\n' "$next_line" | sed -E 's/^[[:space:]]*([^[:space:]:]+).*/\1/')" + allowed=0 + for pair in "${COVERING_ALLOWED[@]}"; do + [ "$pair" = "$f:$name" ] && allowed=1 + done + if [ "$allowed" -eq 0 ]; then + echo "$f:$line_no: covering $name is not on the I/O allowlist" + hits=1 + fi + fi + done +done + +# Require '%default total' to appear and precede all value/type declarations +# (only blank lines, comments, module headers, imports, namespaces, or benign +# compiler pragmas %hide/%logging/%unbound_implicits may precede it). +for f in "${IDR_FILES[@]}"; do + status="$(awk ' + /^[[:space:]]*$/ { next } + /^[[:space:]]*(module|import|namespace)[[:space:]]/ { next } + /^[[:space:]]*%(hide|logging|unbound_implicits|auto_implicit_depth)([[:space:]]|$)/ { next } + /^[[:space:]]*%default total([[:space:]]|$)/ { + if (saw_decl) { print "after_decl"; printed = 1; exit } + saw_total = 1 + next + } + { if (!saw_total) saw_decl = 1 } + END { + if (!printed) { + if (!saw_total) print "missing" + else print "ok" + } + } + ' "${STRIPPED_FILE[$f]}")" + case "$status" in + missing) + echo "$f: missing '%default total'" + hits=1 + ;; + after_decl) + echo "$f: '%default total' appears after a declaration (earlier definitions default to covering)" + hits=1 + ;; + esac +done + +if [ "$hits" -ne 0 ]; then + echo + echo "FAIL: proof escape hatch found. Actually-Proven content may not use these." + echo " Banned: believe_me, assert_total, assert_smaller, %partial," + echo " %default partial|covering, partial declarations," + echo " covering outside the I/O allowlist," + echo " unsafePerformIO, idris_crash, and hole syntax (?name)." + echo " Required: '%default total' before all declarations in every .idr file." + exit 1 +fi + +echo "OK: no proof escape hatches across ${#IDR_FILES[@]} file(s) in ${SCOPE[*]}" diff --git a/scripts/check-hypatia-ignore.sh b/scripts/check-hypatia-ignore.sh new file mode 100755 index 00000000..8ddd9dd4 --- /dev/null +++ b/scripts/check-hypatia-ignore.sh @@ -0,0 +1,168 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# check-hypatia-ignore.sh — the meta-rules that govern `.hypatia-ignore`. +# +# Hypatia reads `.hypatia-ignore` as a flat set of (rule_module, rule_type, +# path-fragment) exemptions and ORs them with its built-in defaults +# (lib/hypatia/scanner_suppression.ex). Three properties follow from that, and +# none of them are checked anywhere else: +# +# 1. Fragments are SUBSTRING matches, so an entry for `x.yml` also silences +# `x.yml.bak`, and one for `build/docs-seed/` silences +# `build/docs-seed-old/`. An entry that does not end at a path boundary is +# a suppression wider than its stated reason. +# 2. The set has no precedence: a directory-wide entry makes every narrower +# entry for the same (module, type) dead code, which reads as though the +# narrow case were considered when it was not. +# 3. Nothing ties an entry to the file it names, so a rename leaves an +# exemption that no longer applies to anything (or applies to the wrong +# thing) and nothing says so. +# +# The check enforces each of those as a rule about the rules, and requires the +# stated reason the file's own header promises. It does not and cannot check +# that Hypatia agrees: the built-in defaults live in another repository. +# +# ORDER OF THE LAYERS (authoritative statement: docs/HYPATIA-RULE-ORDER.adoc) +# rule-level total ban > built-in defaults = repo .hypatia-ignore > +# inline `# hypatia: allow` > baseline > grid normalisation +# The first two are Hypatia's; only `.hypatia-ignore` and inline directives are +# this repository's to get wrong. +# +# Exit contract (proven-tests-and-benches 3-outcome convention): +# 0 = every entry is well formed, bounded, live and explained +# 1 = at least one entry violates a rule above +# 2 = setup error (missing repo directory or ignore file) +set -euo pipefail + +REPO_ROOT="${1:-.}" +IGNORE="$REPO_ROOT/.hypatia-ignore" + +if [ ! -d "$REPO_ROOT" ]; then + echo "check-hypatia-ignore: repo directory '$REPO_ROOT' does not exist" >&2 + exit 2 +fi +if [ ! -f "$IGNORE" ]; then + echo "check-hypatia-ignore: no .hypatia-ignore at '$IGNORE'" >&2 + exit 2 +fi + +errors=0 +fail() { + echo "FAIL: $*" >&2 + errors=$((errors + 1)) +} +note() { echo " note: $*"; } + +entries="$(mktemp)" +trap 'rm -f "$entries"' EXIT + +lineno=0 +have_reason=0 +while IFS= read -r raw || [ -n "$raw" ]; do + lineno=$((lineno + 1)) + line="${raw%$'\r'}" + case "$line" in + '#'*) + # A comment opens a reason block: every entry directly beneath it — one + # or many, which is how this file groups them — inherits that reason. + have_reason=1 + continue + ;; + '') + # A blank line closes the block, so the next entry needs its own reason. + have_reason=0 + continue + ;; + esac + # ── format: /: | /*: | ────────── + if [[ "$line" != *:* ]]; then + fail "line ${lineno}: '${line}' has no ':'; a bare path exempts every rule for that path, which needs an explicit reason and the module/type form instead" + continue + fi + selector="${line%%:*}" + path="${line#*:}" + if [[ "$path" == *:* ]]; then + fail "line ${lineno}: '${line}' has more than one ':' (path fragments cannot contain ':')" + continue + fi + # Rule TYPES carry uppercase (SD022, RE001); rule MODULES do not. + if [[ ! "$selector" =~ ^[a-z][a-z0-9_]*/([A-Za-z0-9_]+|\*)$ ]]; then + fail "line ${lineno}: selector '${selector}' is not / or /*" + continue + fi + module="${selector%%/*}" + type="${selector##*/}" + if [[ -z "$path" ]]; then + fail "line ${lineno}: '${line}' has an empty path fragment" + continue + fi + + # ── rule 1: the fragment must end on a path boundary ──────────────────── + # Trailing '/' is a directory; anything else must look like a file name (it + # contains a dot in its last segment). A fragment that satisfies neither is a + # raw substring, and silences files its author never considered. + last_seg="${path##*/}" + if [[ "$path" != */ && "$last_seg" != *.* ]]; then + fail "line ${lineno}: path fragment '${path}' ends on neither '/' nor a file name (a raw substring match silences more than it names)" + fi + + # ── rule 3: the path it names must exist ──────────────────────────────── + if [[ ! -e "$REPO_ROOT/$path" ]]; then + fail "line ${lineno}: path '${path}' does not exist in this repository (a stale exemption keeps suppressing a path that was renamed, and no longer describes what it says)" + fi + + # ── reason: every entry belongs to an explained block ─────────────────── + # The file's header promises each entry carries a stated reason. A block of + # entries may share one comment (that is how the workflow families here are + # documented); a blank line starts a new block, and a new block needs a new + # reason. The group's entries keep `have_reason` set, so only the first entry + # after a blank line can fail. + if [ "$have_reason" -eq 0 ]; then + fail "line ${lineno}: '${line}' has no stated reason (the block above it does not begin with a comment)" + fi + + printf '%s\t%s\t%s\n' "$module" "$type" "$path" >> "$entries" +done < "$IGNORE" + +# ── rule 2: no duplicate, no entry subsumed by a broader one ─────────────── +if [ -s "$entries" ]; then + while IFS=$'\t' read -r module type path; do + # duplicate + if [ "$(awk -F'\t' -v m="$module" -v t="$type" -v p="$path" '$1 == m && $2 == t && $3 == p' "$entries" | wc -l)" -gt 1 ]; then + fail "duplicate entry ${module}/${type}:${path}" + fi + # subsumed: same module, and the other entry's type covers this one (same + # type or '*'), and the other path is a substring of this one (or equal). + broader="$(awk -F'\t' -v m="$module" -v t="$type" -v p="$path" ' + $1 == m && ($2 == t || $2 == "*") && $3 != p { + if (index(p, $3) > 0) print $2 ":" $3 + }' "$entries" | sort -u)" + if [ -n "$broader" ]; then + fail "${module}/${type}:${path} is already covered by ${module}/${broader} — one of the two is dead code" + fi + done < "$entries" +fi + +# ── advisory: grouping ──────────────────────────────────────────────────── +# The set is unordered to Hypatia but read in order by people. Modules should +# be contiguous so a reviewer sees one rule's story in one place. +seen="" +prev="" +while IFS=$'\t' read -r module _ _; do + [ -n "$module" ] || continue + if [ "$module" != "$prev" ]; then + case " $seen " in + *" $module "*) note "module '${module}' appears in more than one block; Hypatia does not care, reviewers do" ;; + esac + seen="$seen $module" + prev="$module" + fi +done < "$entries" + +if [ "$errors" -ne 0 ]; then + echo "check-hypatia-ignore: ${errors} rule violation(s) in .hypatia-ignore" >&2 + exit 1 +fi +echo "check-hypatia-ignore: $(grep -c . "$entries" 2>/dev/null || echo 0) exemption(s) well formed, bounded, live and explained" diff --git a/scripts/check-hypatia-rule-order.sh b/scripts/check-hypatia-rule-order.sh new file mode 100755 index 00000000..e02e2517 --- /dev/null +++ b/scripts/check-hypatia-rule-order.sh @@ -0,0 +1,204 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# check-hypatia-rule-order.sh — the sequencing rules for Hypatia's layers. +# +# `.machine_readable/policies/hypatia-rule-order.json` says which layer wins, +# which concern belongs to which workflow, and which clash each rule settles. +# The prose is docs/HYPATIA-RULE-ORDER.adoc. This script is what makes the +# statement binding: without it the table is one more description of the +# pipeline that can drift from the four files that implement it. +# +# What it refuses: +# +# * two layers with one rank, or a rank sequence with a hole (an "order" that +# leaves a layer's position to the reader); +# * a layer with no statement of what it overrides; +# * an owner that is not one of the four declared, a concern with no owner, or +# an owner path that does not exist; +# * a module exempted in .hypatia-ignore that the policy does not classify, or +# a classification for a module the ignore file no longer mentions (a policy +# describing a file that has moved on); +# * a scanner or grid pin in the policy that disagrees with the workflow or +# with the renderer digests the lane script verifies; +# * a clash with no stated resolution. +# +# Exit contract (proven-tests-and-benches 3-outcome convention): +# 0 = ordered, complete, consistent with the workflows and the ignore file +# 1 = a rule above is violated +# 2 = setup error (missing repo, policy, workflow, or ignore file) +set -euo pipefail + +REPO_ROOT="${1:-.}" +POLICY="$REPO_ROOT/.machine_readable/policies/hypatia-rule-order.json" +HYPATIA_WF="$REPO_ROOT/.github/workflows/hypatia-scan.yml" +LANE="$REPO_ROOT/scripts/verdict-grid-lane.sh" +IGNORE="$REPO_ROOT/.hypatia-ignore" + +for f in "$POLICY" "$HYPATIA_WF" "$LANE" "$IGNORE"; do + if [ ! -f "$f" ]; then + echo "check-hypatia-rule-order: missing $(basename "$f") (looked for $f)" >&2 + exit 2 + fi +done + +errors=0 +fail() { + echo "FAIL: $*" >&2 + errors=$((errors + 1)) +} + +jq -e 'type == "object"' "$POLICY" >/dev/null 2>&1 || { + echo "check-hypatia-rule-order: policy is not a JSON object" >&2 + exit 2 +} + +# ── shape ─────────────────────────────────────────────────────────────────── +jq -e '.schema == "hypatia-rule-order/1"' "$POLICY" >/dev/null 2>&1 || + fail "policy schema is not hypatia-rule-order/1" + +jq -e '(.layers | type == "array") and (.layers | length) >= 4' "$POLICY" >/dev/null 2>&1 || + fail "policy declares fewer than four layers" + +# ── ranks: unique, complete, and ascending in the order they are written ──── +ranks="$(jq -r '.layers[].rank' "$POLICY" | tr '\n' ' ')" +dupe_rank="$(jq -r '[.layers[].rank] | group_by(.) | map(select(length > 1) | .[0]) | join(",")' "$POLICY")" +[ -z "$dupe_rank" ] || fail "two layers share a rank: ${dupe_rank}" + +ascending="$(jq -r '[.layers[].rank] as $r | ($r == ($r | sort))' "$POLICY")" +[ "$ascending" = "true" ] || fail "layers are not written in ascending rank order (${ranks% }); the document is the sequence" + +count="$(jq -r '.layers | length' "$POLICY")" +expected="$(seq 1 "$count" | tr '\n' ' ')" +[ "${ranks% }" = "${expected% }" ] || + fail "ranks are ${ranks% } but a complete sequence from 1 to ${count} is required" + +# ── each layer states itself ──────────────────────────────────────────────── +# Fields are read as base64-encoded JSON, not @tsv: a tab is IFS whitespace, so +# an empty field would collapse and shift every field after it. That is exactly +# how a missing `overrides` used to be reported as a missing `scope`. +while read -r packed; do + [ -n "$packed" ] || continue + obj="$(printf '%s' "$packed" | jq -Rr '@base64d')" + rank="$(printf '%s' "$obj" | jq -r '.rank')" + id="$(printf '%s' "$obj" | jq -r '.id // ""')" + owner="$(printf '%s' "$obj" | jq -r '.owner // ""')" + overrides="$(printf '%s' "$obj" | jq -r '.overrides // ""')" + scope="$(printf '%s' "$obj" | jq -r '.scope // ""')" + [ -n "$id" ] || fail "layer ${rank} has no id" + [ -n "$scope" ] || fail "layer ${rank} (${id}) has no scope" + [ -n "$overrides" ] || fail "layer ${rank} (${id}) does not say what it overrides" + case "$owner" in + hypatia | this-repository | the-gate | the-grid) : ;; + *) fail "layer ${rank} (${id}) has owner '${owner}', which is not one of hypatia / this-repository / the-gate / the-grid" ;; + esac +done < <(jq -r '.layers[] | @base64' "$POLICY") + +jq -r '.layers[].id' "$POLICY" | sort | uniq -d | while read -r dup; do + [ -z "$dup" ] || echo "FAIL: layer id '${dup}' appears twice" >&2 +done +[ -z "$(jq -r '.layers[].id' "$POLICY" | sort | uniq -d)" ] || errors=$((errors + 1)) + +# ── concerns: one owner each, and the owner exists ────────────────────────── +jq -e '(.concerns | type == "array") and (.concerns | length) > 0' "$POLICY" >/dev/null 2>&1 || + fail "policy declares no concerns" + +jq -r '.concerns[].id' "$POLICY" | sort | uniq -d | while read -r dup; do + [ -z "$dup" ] || echo "FAIL: concern '${dup}' appears twice" >&2 +done +[ -z "$(jq -r '.concerns[].id' "$POLICY" | sort | uniq -d)" ] || errors=$((errors + 1)) + +while read -r packed; do + [ -n "$packed" ] || continue + obj="$(printf '%s' "$packed" | jq -Rr '@base64d')" + id="$(printf '%s' "$obj" | jq -r '.id // ""')" + owner="$(printf '%s' "$obj" | jq -r '.owner // ""')" + if [ -z "$owner" ]; then + fail "concern '${id}' has no owner" + elif [[ "$owner" == .* && ! -e "$REPO_ROOT/$owner" ]]; then + fail "concern '${id}' names '${owner}', which does not exist" + fi +done < <(jq -r '.concerns[] | @base64' "$POLICY") + +# ── clashes: every one has a resolution ───────────────────────────────────── +jq -e '(.clashes | type == "array") and (.clashes | length) > 0' "$POLICY" >/dev/null 2>&1 || + fail "policy records no clashes; the eight found are recorded in docs/HYPATIA-RULE-ORDER.adoc" + +while read -r packed; do + [ -n "$packed" ] || continue + obj="$(printf '%s' "$packed" | jq -Rr '@base64d')" + id="$(printf '%s' "$obj" | jq -r '.id // ""')" + resolution="$(printf '%s' "$obj" | jq -r '.resolution // ""')" + [ -n "$resolution" ] || fail "clash '${id}' has no stated resolution" +done < <(jq -r '.clashes[] | @base64' "$POLICY") + +jq -r '.clashes[].id' "$POLICY" | sort | uniq -d | while read -r dup; do + [ -z "$dup" ] || echo "FAIL: clash '${dup}' appears twice" >&2 +done +[ -z "$(jq -r '.clashes[].id' "$POLICY" | sort | uniq -d)" ] || errors=$((errors + 1)) + +# ── the ignore file and the policy must describe the same modules ─────────── +ignore_modules="$(sed -nE 's#^([a-z][a-z0-9_]*)/.*#\1#p' "$IGNORE" | sort -u)" +policy_modules="$(jq -r '.observed_modules[].module' "$POLICY" | sort -u)" + +while read -r m; do + [ -n "$m" ] || continue + grep -qxF "$m" <<< "$policy_modules" || + fail "module '${m}' is exempted in .hypatia-ignore but the policy does not classify it (add it to observed_modules)" +done <<< "$ignore_modules" + +while read -r m; do + [ -n "$m" ] || continue + grep -qxF "$m" <<< "$ignore_modules" || + fail "policy classifies module '${m}', but .hypatia-ignore no longer exempts it (the policy describes a file that has moved on)" +done <<< "$policy_modules" + +# a classified module must point at a layer that permits repository changes +while IFS=$'\t' read -r m layer; do + [ -n "$m" ] || continue + can="$(jq -r --argjson r "$layer" '.layers[] | select(.rank == $r) | .repository_can_change' "$POLICY")" + if [ -z "$can" ]; then + fail "module '${m}' points at layer ${layer}, which does not exist" + elif [ "$can" != "true" ]; then + fail "module '${m}' points at layer ${layer}, which this repository cannot change" + fi +done < <(jq -r '.observed_modules[] | [.module, .layer] | @tsv' "$POLICY") + +# ── pins must agree with the files that use them ──────────────────────────── +policy_hypatia="$(jq -r '.scanner.commit' "$POLICY")" +# sed -nE, not grep: under `set -e`, a grep that finds no pin terminates the +# script before the diagnostic below, which would turn a missing pin into a +# silent non-zero rather than a stated one. +wf_hypatia="$(sed -nE "s/.*HYPATIA_SHA: *'?([0-9a-f]{40})'?.*/\1/p" "$HYPATIA_WF" | head -n1)" +if [ -z "$wf_hypatia" ]; then + fail "hypatia-scan.yml declares no HYPATIA_SHA; the policy's scanner.commit cannot be verified" +elif [ "$policy_hypatia" != "$wf_hypatia" ]; then + fail "policy scanner.commit (${policy_hypatia:0:12}) does not match HYPATIA_SHA in hypatia-scan.yml (${wf_hypatia:0:12})" +fi + +policy_grid="$(jq -r '.grid.commit' "$POLICY")" +lane_grid="$(sed -nE 's/.*STANDARDS_SHA:-([0-9a-f]{40}).*/\1/p' "$LANE" | head -n1)" +if [ -z "$lane_grid" ]; then + fail "verdict-grid-lane.sh names no STANDARDS_SHA; the policy's grid.commit cannot be verified" +elif [ "$policy_grid" != "$lane_grid" ]; then + fail "policy grid.commit (${policy_grid:0:12}) does not match STANDARDS_SHA in scripts/verdict-grid-lane.sh (${lane_grid:0:12})" +fi + +for pair in "renderer_sha256:RENDERER_SHA256" "library_sha256:JQ_LIB_SHA256"; do + key="${pair%%:*}"; var="${pair##*:}" + want="$(jq -r --arg k "$key" '.grid[$k]' "$POLICY")" + got="$(sed -nE "s/.*${var}=\"([0-9a-f]{64})\".*/\1/p" "$LANE" | head -n1)" + if [ -z "$got" ]; then + fail "verdict-grid-lane.sh declares no ${var}; the policy's grid.${key} cannot be verified" + elif [ "$want" != "$got" ]; then + fail "policy grid.${key} (${want:0:12}) does not match ${var} in scripts/verdict-grid-lane.sh (${got:0:12})" + fi +done + +# ── verdict ──────────────────────────────────────────────────────────────── +if [ "$errors" -ne 0 ]; then + echo "check-hypatia-rule-order: ${errors} rule violation(s)" >&2 + exit 1 +fi +echo "check-hypatia-rule-order: $(jq -r '.layers | length' "$POLICY") layer(s) ordered, $(jq -r '.concerns | length' "$POLICY") concern(s) owned, $(jq -r '.clashes | length' "$POLICY") clash(es) resolved, $(jq -r '.observed_modules | length' "$POLICY") module(s) classified" diff --git a/scripts/check-ijson-jcs.sh b/scripts/check-ijson-jcs.sh new file mode 100755 index 00000000..9c0345a4 --- /dev/null +++ b/scripts/check-ijson-jcs.sh @@ -0,0 +1,152 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# Report or block JSON and JSON Lines files that are not I-JSON (RFC 7493) + +# JCS (RFC 8785) canonical, per metadatastician/standards 3-practice/JSON-POLICY.adoc +# (owner ruling D306) and DATA-FORMAT-ROUTING.adoc (transitional enforcement via +# hyperpolymath/ijson-jcs until a pinned metadatastician/kyq executable passes +# positive and negative tests). +# +# Usage: scripts/check-ijson-jcs.sh [--enforce] [PATH...] +# +# Exit contract (proven-tests-and-benches 3-outcome convention): +# 0 = pass (or report-only scan completed) +# 1 = --enforce found one or more non-canonical or invalid files +# 2 = setup/tooling error (missing binary, missing scan path): never a pass +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" + +enforce=0 +if [ "${1:-}" = "--enforce" ]; then + enforce=1 + shift +fi +if [ "$#" -eq 0 ]; then + set -- . +fi + +# Resolve the runner: +# - When IJSON_JCS is explicitly provided by the caller, honour it strictly +# (so a test passing IJSON_JCS=missing-bin gets exit 2, never a fallback). +# - Otherwise prefer the compiled hyperpolymath/ijson-jcs binary on PATH, and +# fall back to the local Bun RFC 7493/8785 implementation when offline. +RUNNER=() +RUNNER_STDIN=0 +if [ -n "${IJSON_JCS:-}" ]; then + if ! command -v "$IJSON_JCS" >/dev/null 2>&1; then + printf '%s: not found; install hyperpolymath/ijson-jcs or set IJSON_JCS\n' "$IJSON_JCS" >&2 + exit 2 + fi + RUNNER=("$IJSON_JCS") +elif [ "${IJSON_JCS_FORCE_JS:-0}" = "1" ] && command -v bun >/dev/null 2>&1 && [ -f "$SCRIPT_DIR/ijson-jcs-cli.js" ]; then + RUNNER=(bun "$SCRIPT_DIR/ijson-jcs-cli.js") + RUNNER_STDIN=1 +elif command -v ijson-jcs >/dev/null 2>&1; then + RUNNER=(ijson-jcs) +elif command -v bun >/dev/null 2>&1 && [ -f "$SCRIPT_DIR/ijson-jcs-cli.js" ]; then + RUNNER=(bun "$SCRIPT_DIR/ijson-jcs-cli.js") + RUNNER_STDIN=1 +else + printf 'ijson-jcs: neither ijson-jcs nor bun (for %s/ijson-jcs-cli.js) found\n' "$SCRIPT_DIR" >&2 + exit 2 +fi + +# A mistyped path must not turn into an empty, passing scan. +for path in "$@"; do + if [ ! -e "$path" ]; then + printf '%s: scan path does not exist\n' "$path" >&2 + exit 2 + fi +done + +# list_files PATH... — emit NUL-delimited .json/.jsonl paths, pruning .git, +# node_modules, target, and _build directories. +list_files() { + find "$@" \( -name .git -o -name node_modules -o -name target -o -name _build \) -prune \ + -o -type f \( -name '*.json' -o -name '*.jsonl' \) -print0 +} + +# is_jsonc_carve_out PATH — return 0 for devcontainer.json or .vscode JSON paths; +# return 1 otherwise. +is_jsonc_carve_out() { + case "$1" in + */devcontainer.json | devcontainer.json | */.vscode/*.json | .vscode/*.json) + return 0 + ;; + esac + return 1 +} + +# classify_json FILE — print CANONICAL, NOT_CANONICAL, or INVALID using RUNNER. +# Canonical files require a final LF. Checker errors become INVALID verdicts. +classify_json() { + local rc=0 + if [ "$RUNNER_STDIN" -eq 1 ]; then + "${RUNNER[@]}" check <"$1" >/dev/null 2>&1 || rc=$? + else + "${RUNNER[@]}" check "$1" >/dev/null 2>&1 || rc=$? + fi + if [ "$rc" = 0 ] && [ "$(tail -c 1 "$1" | od -An -c | tr -d ' ')" != '\n' ]; then + rc=1 + fi + case "$rc" in + 0) echo CANONICAL ;; + 1) echo NOT_CANONICAL ;; + *) echo INVALID ;; + esac +} + +# classify_jsonl FILE — print CANONICAL, NOT_CANONICAL, or INVALID for JSON Lines. +# Empty files are canonical; nonempty files require a final LF. Blank records +# or failed canonicalization yield INVALID; valid records must match JCS exactly. +classify_jsonl() { + local file="$1" line canon verdict=CANONICAL + if [ -s "$file" ] && [ "$(tail -c 1 "$file" | od -An -c | tr -d ' ')" != '\n' ]; then + verdict=NOT_CANONICAL + fi + while IFS= read -r line || [ -n "$line" ]; do + if [ -z "$line" ]; then + echo INVALID + return + fi + if ! canon="$(printf '%s' "$line" | "${RUNNER[@]}" canon 2>/dev/null)"; then + echo INVALID + return + fi + if [ "$canon" != "$line" ]; then + verdict=NOT_CANONICAL + fi + done <"$file" + echo "$verdict" +} + +total=0 canonical=0 noncanonical=0 invalid=0 skipped=0 +while IFS= read -r -d '' file; do + file="${file#./}" + if is_jsonc_carve_out "$file"; then + skipped=$((skipped + 1)) + continue + fi + total=$((total + 1)) + case "$file" in + *.jsonl) verdict="$(classify_jsonl "$file")" ;; + *) verdict="$(classify_json "$file")" ;; + esac + case "$verdict" in + CANONICAL) canonical=$((canonical + 1)) ;; + NOT_CANONICAL) noncanonical=$((noncanonical + 1)); printf 'NOT CANONICAL %s\n' "$file" ;; + *) invalid=$((invalid + 1)); printf 'INVALID %s\n' "$file" ;; + esac +done < <(list_files "$@" | sort -z) + +summary="ijson-jcs: ${total} file(s) checked, ${canonical} canonical, ${noncanonical} not canonical, ${invalid} invalid; ${skipped} JSONC carve-out(s) skipped" +echo "$summary" +if [ -n "${GITHUB_ACTIONS:-}" ] && [ "$enforce" -eq 0 ]; then + echo "::notice title=ijson-jcs (report-only)::${summary}. Fix with: ijson-jcs fix " +fi +if [ "$enforce" -eq 1 ] && [ $((noncanonical + invalid)) -gt 0 ]; then + exit 1 +fi +exit 0 diff --git a/scripts/check-invisible-characters.sh b/scripts/check-invisible-characters.sh index 8cc49fca..abde5044 100755 --- a/scripts/check-invisible-characters.sh +++ b/scripts/check-invisible-characters.sh @@ -41,7 +41,7 @@ if ! "$find_bin" "$scan_root" \ -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' \ - -o -name '*.a2ml' -o -name '*.txt' -o -name '*.just' \ + -o -name '*.deed' -o -name '*.k9' -o -name '*.ncl' -o -name '*.txt' -o -name '*.just' \ -o -name 'Justfile' -o -name 'Mustfile' -o -name 'Trustfile' -o -name 'Bustfile' \) \ -print0 > "$enumeration_file"; then echo "file enumeration failed: $scan_root" >&2 diff --git a/scripts/check-lock-sync.sh b/scripts/check-lock-sync.sh index 3088bbd5..ec8aeb0d 100755 --- a/scripts/check-lock-sync.sh +++ b/scripts/check-lock-sync.sh @@ -5,12 +5,16 @@ # workflow YAML, in BOTH directions (including job-level reusable-workflow refs), # AND that the lockfile is TRANSITIVELY CLOSED. # -# Three clauses, each of which alone is insufficient: +# Validation clauses, each of which alone is insufficient: # # 1. every `uses:` in a workflow is locked under THAT workflow's own path; # 2. every lockfile entry is still referenced by its workflow (no orphans); # 3. every ref NAMED anywhere in the lockfile resolves to a top-level # `dependencies:` record — the lockfile has no dangling edges. +# 4. every workflow file has a lockfile entry, even when it uses no actions; +# 5. dependency ref metadata is a string naming a short branch/tag, never a +# SHA or placeholder, and matches its key unless that key is a full SHA; +# 6. the lockfile version is the supported v0.0.3 format. # # Clause 3 is not decoration. It is the clause that catches the failure mode that # clauses 1 and 2 are structurally blind to, and it was added only after that @@ -38,7 +42,7 @@ # job-level refs and will not backfill -> the developer hand-adds the workflows: # entry to get green -> no dependencies: record -> CI dies silently, gate green. # -# Exit 0 only when all three clauses hold. Any violation exits 1. There is no +# Exit 0 only when all clauses hold. Any violation exits 1. There is no # warn-only mode: a desync means GitHub refuses to start the run, so it must fail # the job. A `::warning::` cannot fail a job and would be a vacuous gate. @@ -47,20 +51,16 @@ set -euo pipefail WF_DIR="${1:-.github/workflows}" LOCK="$WF_DIR/actions.lock" -# gawk is required: the parser uses 3-argument match(), a GNU extension. mawk -# (the Debian/Ubuntu default `awk`) does not support it, and a silent parse -# failure here would read as a clean pass - the exact failure mode this script -# exists to prevent. Probe it rather than trusting the name. +# Portable POSIX awk: avoids GNU gawk's 3-argument match() extension so the +# gate runs identically on Debian/Ubuntu minimal images (mawk) and gawk. AWK="" -for cand in gawk awk; do - if command -v "$cand" >/dev/null 2>&1 \ - && echo x | "$cand" '{ if (match($0, /(x)/, m) && m[1] == "x") exit 0; exit 1 }' 2>/dev/null; then +for cand in gawk mawk awk; do + if command -v "$cand" >/dev/null 2>&1; then AWK="$cand"; break fi done if [ -z "$AWK" ]; then - echo "check-lock-sync: FATAL: no awk supporting 3-argument match() (need gawk)" >&2 - echo "check-lock-sync: install it with: sudo apt-get install -y gawk" >&2 + echo "check-lock-sync: FATAL: no awk found on PATH" >&2 exit 1 fi @@ -103,23 +103,113 @@ function ck(r, at, s) { return tolower(substr(r, 1, at - 1)) substr(r, at) } +# Full commit identities supported by the upstream resolver (SHA-1/SHA-256). +# Keep the length checks separate from the regex for POSIX awk/mawk. +function fullsha(r) { + return r ~ /^[0-9a-fA-F]+$/ && (length(r) == 40 || length(r) == 64) +} + +# The v0.0.3 schema requires a string, not a YAML null, boolean, number or +# collection. Recognize plain single-line names without coercing those types +# into strings. Quoted names are handled separately, so e.g. "null" and +# "123" remain eligible literal refs. Tags/anchors/block scalars are outside +# the generated lockfile format; quote a literal name instead. +function plainstring(r, n) { + if (r == "" || r ~ /^(~|null|Null|NULL|true|True|TRUE|false|False|FALSE)$/) return 0 + if (r ~ /^[#&*!|>\[{]/ || substr(r, 1, 1) == "`" || substr(r, 1, 1) == "@") return 0 + n = r + gsub(/_/, "", n) + if (r ~ /^[-+0-9.]/ && (n ~ /^[-+]?([0-9]+(\.[0-9]*)?|\.[0-9]+)([eE][-+]?[0-9]+)?$/ || + n ~ /^[-+]?0[xX][0-9a-fA-F]+$/ || + n ~ /^[-+]?0[oO][0-7]+$/ || + n ~ /^[-+]?0[bB][01]+$/ || + n ~ /^[-+]?\.(inf|Inf|INF)$/ || n ~ /^\.(nan|NaN|NAN)$/)) return 0 + return 1 +} + +# Check short named-ref syntax without network access. Git allows one-level +# names for branches/tags, but lock metadata forbids the refs/ namespace +# prefix; see upstream lockfile.ValidEntryRef. Angle brackets +# are additionally rejected here because lock metadata must not be a template +# marker such as . Existence and commit resolution remain upstream +# checks; this gate does not claim to prove them from a name alone. +function namedref(r, count, part, j) { + if (index(r, "refs/") == 1) return 0 + if (r == "" || r == "@" || r ~ /[[:cntrl:] ]/ || r ~ /[~^:?*\\]/ || index(r, "[")) return 0 + if (index(r, "<") || index(r, ">") || index(r, "..") || index(r, "@{") || index(r, "//")) return 0 + if (r ~ /^\// || r ~ /\/$/ || r ~ /\.$/) return 0 + count = split(r, part, "/") + for (j = 1; j <= count; j++) + if (part[j] ~ /^\./ || part[j] ~ /\.lock$/) return 0 + return 1 +} + # ---------- pass 1: the lockfile ---------- FILENAME == lockfile { + if ($0 ~ /^version:[[:space:]]*/) { + verline = $0 + sub(/^version:[[:space:]]*/, "", verline) + sub(/[[:space:]]*$/, "", verline) + has_version = 1 + lock_version = verline + next + } if ($0 ~ /^workflows:[[:space:]]*$/) { inwf = 1; indep = 0; next } if ($0 ~ /^dependencies:[[:space:]]*$/) { inwf = 0; indep = 1; next } if ($0 ~ /^[a-z_]+:/) { inwf = 0; indep = 0; next } - # --- the dependencies: section, for clause 3 --- + # --- the dependencies: section, for clause 3 & self-SHA ref guard --- if (indep) { # " 'owner/repo@ref':" -- a top-level dependency record - if (match($0, /^ '([^']+)':/, m)) { - depkey = m[1] + if ($0 ~ /^ \047[^\047]+\047:/) { + depkey = $0 + sub(/^ \047/, "", depkey) + sub(/\047:.*$/, "", depkey) haverec[ck(depkey)] = 1; disp[ck(depkey)] = depkey + rawrec[depkey] = 1 + next + } + # " ref: '...'" -- the record needs a real branch/tag name, even + # when its dependency key and commit: are correctly pinned to a SHA. + if ($0 ~ /^ ref:/ && depkey != "") { + rval = $0 + # Preserve the separator before # until comments are stripped: a + # comment-only value is YAML null, not a branch named #missing. + sub(/[[:space:]]+#.*$/, "", rval) + sub(/^ ref:[[:space:]]*/, "", rval) + sub(/[[:space:]]*$/, "", rval) + hasref[depkey] = 1 + quote = substr(rval, 1, 1) + if (quote == "\047" || quote == "\042") { + # Match one complete scalar: inner single quotes must be doubled, + # and an unescaped double quote must end a double-quoted scalar. + if ((quote == "\047" && rval !~ /^\047([^\047]|\047\047)*\047$/) || + (quote == "\042" && rval !~ /^\042([^\042\\]|\\.)*\042$/)) { + invalidref[depkey] = rval + next + } + rval = substr(rval, 2, length(rval) - 2) + if (quote == "\047") gsub(/\047\047/, "\047", rval) + } else if (!plainstring(rval)) { + invalidscalar[depkey] = (rval == "" ? "" : rval) + next + } + keyref = substr(depkey, index(depkey, "@") + 1) + if (fullsha(rval)) { + selfsha[depkey] = rval + } else if (!namedref(rval)) { + invalidref[depkey] = (rval == "" ? "" : rval) + } else if (!fullsha(keyref) && rval != keyref) { + mismatchref[depkey] = rval + } next } # " - 'owner/repo@ref'" -- a nested uses: of that record - if (match($0, /^ - '([^']+)'/, m) && depkey != "") { - r = ck(m[1]); disp[r] = m[1] + if ($0 ~ /^ - \047[^\047]+\047/ && depkey != "") { + val = $0 + sub(/^ - \047/, "", val) + sub(/\047.*$/, "", val) + r = ck(val); disp[r] = val want[r] = 1 wantsrc[r] = wantsrc[r] " dependencies:" depkey next @@ -130,13 +220,18 @@ FILENAME == lockfile { if (!inwf) next # " '.github/workflows/x.yml':" or "... : []" - if (match($0, /^ '([^']+)':/, m)) { - cur = m[1] + if ($0 ~ /^ \047[^\047]+\047:/) { + cur = $0 + sub(/^ \047/, "", cur) + sub(/\047:.*$/, "", cur) seen_path[cur] = 1 next } - if (match($0, /^ - '([^']+)'[[:space:]]*$/, m) && cur != "") { - lr = ck(m[1]); disp[lr] = m[1]; lock[cur, lr] = 1 + if ($0 ~ /^ - \047[^\047]+\047[[:space:]]*$/ && cur != "") { + val = $0 + sub(/^ - \047/, "", val) + sub(/\047[[:space:]]*$/, "", val) + lr = ck(val); disp[lr] = val; lock[cur, lr] = 1 lockcount[cur]++ want[lr] = 1 wantsrc[lr] = wantsrc[lr] " " cur @@ -150,9 +245,10 @@ FNR == 1 { wf = FILENAME } { line = $0 sub(/[[:space:]]+#.*$/, "", line) # strip trailing comment - if (match(line, /^[[:space:]]*-?[[:space:]]*uses:[[:space:]]*(.+)$/, m)) { - raw = m[1] - gsub(/^["']|["']$/, "", raw) + if (line ~ /^[[:space:]]*-?[[:space:]]*uses:[[:space:]]*.+$/) { + raw = line + sub(/^[[:space:]]*-?[[:space:]]*uses:[[:space:]]*/, "", raw) + gsub(/^["\047]|["\047]$/, "", raw) gsub(/[[:space:]]+$/, "", raw) if (raw ~ /^\$\//) { dollar[wf] = dollar[wf] " " raw; next } # known corruption n = norm(raw) @@ -257,13 +353,68 @@ END { bad = 1 } + # --- clause 5: GitHub requires string-valued short source refs, matching + # mutable keys, never 40/64-hex commit identities as ref metadata. --- + nself = 0; selflist = "" + for (s in selfsha) { + nself++ + selflist = selflist sprintf("\n %s (ref: %s)", s, selfsha[s]) + } + if (nself > 0) { + printf "FAIL actions.lock: SELF-SHA REFS\n" + printf " %d dependencies: record(s) use a 40/64-hex SHA as ref: (rejected by GitHub runner):%s\n", nself, selflist + bad = 1 + } + + # Metadata belongs to each raw record, even when repository lookup folds + # case and another spelling of the same pin has its own valid ref. + for (d in rawrec) + if (!(d in hasref)) invalidref[d] = "" + ninvalid = 0; invalidlist = "" + for (d in invalidref) { + ninvalid++ + invalidlist = invalidlist sprintf("\n %s (ref: %s)", d, invalidref[d]) + } + if (ninvalid > 0) { + printf "FAIL actions.lock: INVALID NAMED REFS\n" + printf " %d dependencies: record(s) have missing, placeholder or malformed ref: metadata:%s\n", ninvalid, invalidlist + bad = 1 + } + + nscalar = 0; scalarlist = "" + for (d in invalidscalar) { + nscalar++ + scalarlist = scalarlist sprintf("\n %s (ref: %s)", d, invalidscalar[d]) + } + if (nscalar > 0) { + printf "FAIL actions.lock: INVALID REF SCALARS\n" + printf " %d dependencies: record(s) have non-string or unsupported YAML ref: values; quote literal names:%s\n", nscalar, scalarlist + bad = 1 + } + + nmismatch = 0; mismatchlist = "" + for (d in mismatchref) { + nmismatch++ + mismatchlist = mismatchlist sprintf("\n %s (ref: %s)", d, mismatchref[d]) + } + if (nmismatch > 0) { + printf "FAIL actions.lock: MISMATCHED REFS\n" + printf " %d dependencies: record(s) disagree with their mutable key refs:%s\n", nmismatch, mismatchlist + bad = 1 + } + + if (!has_version || lock_version != "\047v0.0.3\047") { + printf "FAIL actions.lock: INVALID VERSION (%s; expected \047v0.0.3\047)\n", (has_version ? lock_version : "missing") + bad = 1 + } + # --- a dependencies: record nothing names is dead weight, not fatal: report only --- nunref = 0 for (d in haverec) if (!(d in want)) nunref++ if (bad) { print "" - print "actions.lock is OUT OF SYNC with the workflow YAML, or is not transitively closed." + print "actions.lock is OUT OF SYNC, is not transitively closed, or has invalid pin metadata." print "GitHub refuses such a run at startup: zero jobs are created and the run" print "reports \"This run likely failed because of a workflow file issue.\"" print "" @@ -279,9 +430,12 @@ END { print " github/codeql-action/upload-sarif@ is REJECTED by the schema; collapse it" print " to github/codeql-action@." print " 4. For any UNLISTED WORKFLOWS above, add the path as a lockfile key. A workflow" - print " with no uses: takes an empty list: \x27.github/workflows/x.yml\x27: []" + print " with no uses: takes an empty list: \047.github/workflows/x.yml\047: []" print " `gh actions-lock` has been observed to OMIT such a workflow entirely; that" print " omission is itself the defect, so re-running the tool may not add it." + print " 5. Every dependency ref: must be a string naming a short branch or tag and" + print " match the key ref unless the key is a full SHA. Preserve the immutable" + print " commit: pin; do not replace ref: with that SHA, a placeholder or a refs/ name." exit 1 } printf "actions.lock is in sync and transitively closed:\n" @@ -289,6 +443,7 @@ END { printf " * every lockfile entry is still referenced\n" printf " * every ref named in the lockfile resolves to a dependencies: record (0 dangling edges)\n" printf " * every workflow file has a lockfile key (zero-uses: workflows included)\n" + printf " * dependency ref: metadata uses string-valued short names, matches mutable keys, and has no placeholders or SHAs\n" if (nunref > 0) printf " note: %d dependencies: record(s) are unreferenced - harmless, but prunable.\n", nunref } diff --git a/scripts/check-mint-tokens.sh b/scripts/check-mint-tokens.sh new file mode 100644 index 00000000..d45489fd --- /dev/null +++ b/scripts/check-mint-tokens.sh @@ -0,0 +1,214 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# check-mint-tokens.sh — every brace token the template can ship has an answer +# in `just repo-init`, or the file that carries it is not shipped. +# +# ── Why this exists ───────────────────────────────────────────────────────── +# +# A token with no answer is not a reminder, it is a defect that ships. Measured +# downstream: a minted Julia repo carried +# +# Justfile project := "{{PROJECT_NAME}}" tier := "{{tier}}" +# .envrc PROJECT_NAME="{{PROJECT_NAME}}" RSR_TIER="infrastructure" +# .reuse/dep5 Upstream-Name: {{PROJECT_NAME}} +# Containerfile # Copyright (c) ... ({{OWNER}}) +# devcontainer.json, .devcontainer/Containerfile {{PROJECT_NAME}} +# +# because the mint had no answer for those tokens IN THOSE FILES, and nothing +# checked. The repo's own `check-no-placeholders.sh` would have caught it — in +# the child, after the fact, on every push, which trains people to ignore red. +# +# This is the template-side check: it compares the token VOCABULARY the tree +# contains against the token vocabulary `repo-init` can answer, before a mint +# ever runs. A token in the left set and not the right one is a file that cannot +# be minted, and the fix is one of two things, chosen deliberately: +# +# * teach repo-init an answer (SED_ARGS, or the UNASSIGNED fallback for a +# judgement token), or +# * stop shipping the file. +# +# ── What counts ───────────────────────────────────────────────────────────── +# * scannable: tracked/untracked files, minus .machine_readable/mint-verbatim.txt +# fixtures, minus Justfiles and *.just (just's own {{ }} interpolation), minus +# binary/licence text — the same set repo-init's mint_files edits; +# * tokens: `{{[A-Za-z_][A-Za-z0-9_]*}}` — lowercase included, because the +# downstream damage included `{{tier}}`, and an uppercase-only scan would +# have reported full coverage of a tree that still carried it; +# * exempt: metasyntax ({{PLACEHOLDER}}, {{TOKEN}}, {{ANYTHING}}, +# {{UPPER_SNAKE}}) and the documents whose subject IS the vocabulary. +# +# ── Usage ─────────────────────────────────────────────────────────────────── +# check-mint-tokens.sh [--root DIR] [--quiet] +# +# Exit: 0 = every token is answerable; 1 = an unanswerable token; 2 = usage. + +set -uo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" +QUIET=0 +while [ $# -gt 0 ]; do + case "$1" in + --root) ROOT="${2:-}"; shift 2 ;; + --quiet) QUIET=1; shift ;; + -h|--help) sed -n '2,50p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; + *) echo "check-mint-tokens: unknown option: $1" >&2; exit 2 ;; + esac +done +[ -d "$ROOT" ] || { echo "check-mint-tokens: not a directory: $ROOT" >&2; exit 2; } +ROOT="$(cd "$ROOT" && pwd)" + +ok() { [ "$QUIET" -eq 1 ] || printf ' \033[32mPASS\033[0m %s\n' "$1"; } +bad() { printf ' \033[31mFAIL\033[0m %s\n' "$1"; } +note() { [ "$QUIET" -eq 1 ] || printf ' %s\n' "$1"; } +info() { [ "$QUIET" -eq 1 ] || printf ' \033[34minfo\033[0m %s\n' "$1"; } + +RECIPE="$ROOT/build/just/repo-init.just" +MINTED_TREE=0 +if [ ! -d "$ROOT/archetypes" ]; then + # "Minted" is the absence of archetypes/, NOT the absence of the generator. + # The mint carries build/just/repo-init.just into every child verbatim + # (.machine_readable/mint-verbatim.txt) and the child's Justfile imports it, + # so testing for the recipe never fired: children looked like the template, + # every token they carried counted as "the generator will answer this", and + # an unfilled {{PROJECT_NAME}} passed — in the gate and in + # survey-template-damage.sh, which reads it. + # + # archetypes/ is the marker because the mint deletes it (repo-init's prune + # step) and nothing else recreates it: a template checkout has it, a minted + # repository cannot. Where the generator IS present in a child, its answers + # are listed below but never used, which is the point: nothing can answer a + # token in a tree that has already been minted. + MINTED_TREE=1 +fi + +# ── The answer list, read from the generator itself ───────────────────────── +# Not a copy: a copy drifts, and a drifted copy would pass this gate while the +# mint still failed. Two forms are answered: +# * SED_ARGS entries: -e "s|${LB}TOKEN${RB}|value|g" +# * the UNASSIGNED fallback loop: for tok in TOKEN TOKEN … ; do +ANSWERS="" +[ "$MINTED_TREE" -eq 0 ] && ANSWERS="$({ + # shellcheck disable=SC2016 # the braces are literal text in the recipe + sed -n 's/.*s|\${LB}\([A-Za-z_][A-Za-z0-9_]*\)\${RB}|.*/\1/p' "$RECIPE" + awk ' + /for tok in/ { collecting = 1 } + collecting { + line = $0 + gsub(/\$\{LB\}|\$\{RB\}|\\/, " ", line) + n = split(line, w, /[^A-Z0-9_]+/) + for (i = 1; i <= n; i++) if (w[i] ~ /^[A-Z][A-Z0-9_]*$/ && length(w[i]) > 2) print w[i] + if ($0 ~ /;[[:space:]]*do/) collecting = 0 + }' "$RECIPE" +} | sort -u)" +# In memory, not /tmp/mint-tokens-answers.$$: this script is called in nested +# command substitutions (tests, the mint's pre-write gate), where a PID-named +# temp file is shared by the outer and inner shell often enough to hand one of +# them a half-written list — measured as an intermittent "the mint cannot +# answer {{PROJECT_NAME}}" on a tree where it demonstrably can. +if [ "$MINTED_TREE" -eq 1 ]; then + info "no archetypes/ — minted tree; no token has an answer here" +else + COUNT_ANSWERS=$(printf '%s\n' "$ANSWERS" | grep -c . || true) + [ "$COUNT_ANSWERS" -gt 0 ] || { bad "could not read any answered token from repo-init"; exit 2; } + info "repo-init answers $COUNT_ANSWERS token(s)" +fi + +# ── What the mint edits ───────────────────────────────────────────────────── +VERBATIM_LIST="$ROOT/.machine_readable/mint-verbatim.txt" +mapfile -t VERBATIM < <( + [ -f "$VERBATIM_LIST" ] && sed -e 's/#.*//' -e 's/[[:space:]]*$//' "$VERBATIM_LIST" | grep -v '^$' || true +) + +is_verbatim() { + local rel="$1" v + for v in "${VERBATIM[@]}"; do [ "$rel" = "$v" ] && return 0; done + return 1 +} + +# The vocabulary document, the prose about tokens, and the checkers themselves. +EXEMPT=( + ".machine_readable/ai/PLACEHOLDERS.adoc" + "PLACEHOLDERS.adoc" # the same vocabulary doc, at the root + "EXPLAINME.adoc" + "scripts/check-mint-tokens.sh" + "scripts/check-no-placeholders.sh" + # Generator internals. `src/generator.jl` and `templates/` are the code and + # the files that DO the substituting: `{{name}}`, `{{summary}}` and + # `{{uuid}}` there are Julia string interpolation over a generator variable, + # not mint tokens. They are searched for tokens in the generator's own + # source, not here. + "src/generator.jl" +) +is_exempt() { + local rel="$1" e + for e in "${EXEMPT[@]}"; do [ "$rel" = "$e" ] && return 0; done + case "$rel" in + Justfile|justfile|*/Justfile|*/justfile|*.just) return 0 ;; + templates/*) return 0 ;; + esac + return 1 +} + +list_files() { + if git -C "$ROOT" rev-parse --is-inside-work-tree >/dev/null 2>&1; then + git -C "$ROOT" ls-files -z --cached --others --exclude-standard + else + find "$ROOT" -type f -print0 + fi | sort -zu | while IFS= read -r -d '' f; do + rel="${f#"$ROOT"/}" + [ -f "$ROOT/$rel" ] && [ ! -L "$ROOT/$rel" ] || continue + case "$rel" in */.git/*) continue ;; esac + is_verbatim "$rel" && continue + grep -qIE '\{\{[A-Za-z_][A-Za-z0-9_]*\}\}' "$ROOT/$rel" 2>/dev/null || continue + printf '%s\n' "$rel" + done +} + +META='PLACEHOLDER|PLACEHOLDERS|ANYTHING|TOKEN|UPPER_SNAKE' +UNKNOWN=() +SEEN=() +while IFS= read -r rel; do + is_exempt "$rel" && continue + while IFS= read -r tok; do + [ -n "$tok" ] || continue + # Here-strings, not pipes: `grep -q` exits on its first match, which + # SIGPIPEs the writer, and under `set -o pipefail` that made the + # pipeline report 141 (no match) for token lists it HAD matched — + # measured as a different one or two tokens reported unanswerable on + # every run of the same unchanged tree. + grep -qxE "$META" <<< "$tok" && continue + grep -qxF -- "$tok" <<< "$ANSWERS" && continue + UNKNOWN+=("$rel: {{$tok}}") + SEEN+=("$tok") + # Lowercase tokens count too: the downstream damage included {{tier}}, and an + # uppercase-only scan reported the tree clean while it still carried it. + done < <(grep -ohE '\{\{[A-Za-z_][A-Za-z0-9_]*\}\}' "$ROOT/$rel" | tr -d '{}' | sort -u) +done < <(list_files) + +if [ ${#UNKNOWN[@]} -eq 0 ]; then + ok "every shipped brace token has an answer in repo-init" + exit 0 +fi + +if [ "$MINTED_TREE" -eq 1 ]; then + bad "${#UNKNOWN[@]} unfilled token(s) in a minted tree (no archetypes/, so nothing can answer them):" +else + bad "${#UNKNOWN[@]} token reference(s) the mint cannot answer:" +fi +for u in "${UNKNOWN[@]}"; do printf ' %s\n' "$u"; done +note "Unanswerable token(s): $(printf '%s\n' "${SEEN[@]}" | sort -u | tr '\n' ' ')" +if [ "$MINTED_TREE" -eq 1 ]; then + note "This repository was minted: the mint substituted what it could and the" + note "rest stayed literal. Fill them with the values in .machine_readable/ai/PLACEHOLDERS.adoc," + note "or delete the lines that need them." + exit 1 +fi +note "Fix one of two ways, deliberately:" +note " * teach repo-init (SED_ARGS, or the UNASSIGNED list for a judgement token), or" +note " * stop shipping the file that carries it." +note "A third way — filling it by hand after the mint — is how the downstream repos" +note "got the tokens in the first place." +exit 1 diff --git a/scripts/check-mise-language.sh b/scripts/check-mise-language.sh new file mode 100644 index 00000000..ac37905e --- /dev/null +++ b/scripts/check-mise-language.sh @@ -0,0 +1,232 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# check-mise-language.sh — the declared toolchain matches the repository's +# languages: nothing banned, nothing foreign, nothing missing. +# +# ── Why this exists ───────────────────────────────────────────────────────── +# +# The template's mise.toml declared nine runtimes: +# +# node python rust go zig java bun denojs +# npm yarn pnpm pip cargo go-task +# gofmt black isort ruff prettier shfmt stylua +# cmake make ninja git gnu-sed gnu-tar gnu-grep +# vitest pytest jest +# [alias] build/test/lint/fmt = a chain of Cargo, Node, Go and Ruff commands +# +# for every repository it seeded, including a Julia package. Two of those +# declarations are policy violations on their own (Python and Node are banned +# estate-wide), the alias block routed `just build` through Cargo/npm/Go, and +# the one runtime the repo actually needed was absent. The file was correct for +# no repository in particular and wrong for all of them. +# +# The fix is not to delete the polyglot list — it is to render the toolchain +# from the languages the repo declares, which `just repo-init` now does through +# `provision-lib.sh mise-tools`. This gate is the INVERSE check: it reads the +# shipped mise.toml back and fails when it and the tree disagree. +# +# ── Rules ─────────────────────────────────────────────────────────────────── +# 1. mise.toml exists (doctor PV-E20 is the runtime form of this). +# 2. No banned tool (LANGUAGE-POLICY §Banned Languages + no make/nix). +# 3. Every declared tool is needed by a detected language or is shared. +# 4. Every tool a detected language needs is declared. +# +# ── Usage ─────────────────────────────────────────────────────────────────── +# check-mise-language.sh [--root DIR] [--langs "julia"] [--tools "julia just"] +# [--quiet] +# +# --langs LIST language list to check against (default: provisioning engine) +# --tools LIST expected tool set (default: provisioning engine `mise-tools`) +# — for a fixture, so the gate can be driven without an engine. +# --detect when the repo ships no build/just/provision-lib.sh, detect the +# languages from the same marker files the engine uses. Audits +# repositories minted before the engine existed; a repo WITH the +# engine ignores this flag. +# +# Exit: 0 = consistent; 1 = findings; 2 = usage error. + +set -uo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" +LANGS="" +TOOLS="" +QUIET=0 +DETECT=0 +while [ $# -gt 0 ]; do + case "$1" in + --root) ROOT="${2:-}"; shift 2 ;; + --langs) LANGS="${2:-}"; shift 2 ;; + --tools) TOOLS="${2:-}"; shift 2 ;; + --quiet) QUIET=1; shift ;; + --detect) DETECT=1; shift ;; + -h|--help) sed -n '2,46p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; + *) echo "check-mise-language: unknown option: $1" >&2; exit 2 ;; + esac +done +[ -d "$ROOT" ] || { echo "check-mise-language: not a directory: $ROOT" >&2; exit 2; } +ROOT="$(cd "$ROOT" && pwd)" + +ok() { [ "$QUIET" -eq 1 ] || printf ' \033[32mPASS\033[0m %s\n' "$1"; } +bad() { printf ' \033[31mFAIL\033[0m %s\n' "$1"; } +note() { [ "$QUIET" -eq 1 ] || printf ' %s\n' "$1"; } +info() { [ "$QUIET" -eq 1 ] || printf ' \033[34minfo\033[0m %s\n' "$1"; } + +LIB="$ROOT/build/just/provision-lib.sh" +lib() { ( cd "$ROOT" && PROVISION_ROOT="$ROOT" bash "$LIB" "$@" 2>/dev/null ); } + +if [ -z "$LANGS" ] && [ -f "$LIB" ]; then + LANGS="$(lib langs | tr '\n' ' ')" +fi +if [ -z "$TOOLS" ] && [ -f "$LIB" ]; then + TOOLS="$(lib mise-tools | tr '\n' ' ')" +fi +# --detect: a reduced mirror of build/just/provision-lib.sh's detectors, for +# repositories minted before this engine existed (or before it shipped them). +# Those repositories have a mise.toml but no provision-lib.sh, so the gate +# cannot read its answer — and refusing to run leaves them unaudited forever. +# The mirror is deliberately narrow: same marker files, same MISE_BASE, same +# per-language binaries. It is NOT the source of truth; when provision-lib.sh is +# present its answer wins, and a disagreement is a bug in the mirror. +if [ -z "$LANGS" ] && [ "$DETECT" -eq 1 ]; then + # Same depths as provision-lib.sh's `first`, not root-only: the template's own + # seam puts Idris2 at src/interface/abi.ipkg and Zig at + # src/interface/ffi/build.zig, so a root-only mirror called those trees + # `docs` and graded them against the wrong toolchain. Depths are copied from + # detect_langs(), including its defaults (2 for the unmarked ones). + _find() { find "$ROOT" -maxdepth "${2:-2}" -not -path '*/.git/*' \ + -not -path '*/node_modules/*' -not -path '*/target/*' \ + -name "$1" -print -quit 2>/dev/null; } + _l=() + [ -n "$(_find Cargo.toml)" ] && _l+=(rust) + [ -n "$(_find '*.ipkg' 3)" ] && _l+=(idris2) + [ -n "$(_find Project.toml 1)" ] && _l+=(julia) + [ -n "$(_find build.zig 4)" ] && _l+=(zig) + [ -n "$(_find mix.exs)" ] && _l+=(elixir) + [ -n "$(_find gleam.toml)" ] && _l+=(gleam) + [ -n "$(_find dune-project)" ] && _l+=(ocaml) + { [ -n "$(_find '*.cabal')" ] || [ -n "$(_find stack.yaml 1)" ]; } && _l+=(haskell) + [ -n "$(_find package.json)" ] && _l+=(bun) + [ "${#_l[@]}" -eq 0 ] && _l+=(docs) + LANGS="${_l[*]}" + info "languages (detected from markers; provision-lib.sh absent): $LANGS" +fi +if [ -z "$TOOLS" ] && [ "$DETECT" -eq 1 ]; then + # MISE_BASE + RECIPE_TOOLS + lang_mise(), copied from provision-lib.sh. The + # mirror used to list each language's BINARIES instead (`mix erl`, `ghc cabal`, + # `dune`), which is lang_tools()'s answer, not the mise.mise table's: a tree + # declaring `erlang elixir` was failed for not declaring `mix`/`erl`, and a + # Rust tree declaring `rust` was failed for declaring a tool the engine + # installs. A mirror that disagrees with the engine is a bug in the mirror. + _t="just shellcheck trivy" + for l in $LANGS; do + case "$l" in + rust) _t="$_t rust" ;; + zig) _t="$_t zig" ;; + julia) _t="$_t julia" ;; + idris2) _t="$_t idris2" ;; + elixir) _t="$_t erlang elixir" ;; + gleam) _t="$_t erlang gleam" ;; + ocaml) _t="$_t opam" ;; + bun) _t="$_t bun deno pnpm" ;; + docs) _t="$_t lychee" ;; + esac + done + TOOLS="$_t" +fi + +if [ -z "$LANGS" ] || [ -z "$TOOLS" ]; then + bad "cannot determine the expected toolchain" + note "no build/just/provision-lib.sh in $ROOT, and --langs/--tools were not given." + note "For a repository minted before the engine existed, pass --detect." + note "This gate will not guess: a guessed toolchain set is how the template shipped one." + exit 2 +fi +LANGS="$(echo "$LANGS" | xargs)" +TOOLS="$(echo "$TOOLS" | xargs)" +info "languages: $LANGS" +info "expected tools: $TOOLS" + +MISE="$ROOT/mise.toml" +if [ ! -f "$MISE" ]; then + bad "mise.toml is missing — the toolchain is undeclared" + note "doctor's PV-E20 says the same; render it, do not hand-write nine runtimes." + exit 1 +fi + +# [tools] keys, quotes and comments stripped, one per line. Only the [tools] +# table: [env] and [alias] are not tool declarations. +declared() { + awk ' + /^[[:space:]]*\[tools\][[:space:]]*$/ { t = 1; next } + /^[[:space:]]*\[/ { t = 0 } + t && /^[[:space:]]*("[^"]*"|\047[^\047]*\047|[A-Za-z0-9_.-]+)[[:space:]]*=/ { + # Quoted keys are not decoration: TOML REQUIRES them for + # backend-qualified tools ("npm:prettier" = "latest"), so a parser + # that only saw bare keys never declared them — and a file declaring + # the banned tool passed this gate while the backend check below + # could not be reached for the syntax it exists to inspect. + line = $0 + sub(/[[:space:]]*=.*/, "", line) + gsub(/^[[:space:]]+|[[:space:]]+$/, "", line) + gsub(/^["\047]|["\047]$/, "", line) + print line + }' "$MISE" +} + +mapfile -t DECLARED < <(declared | sort -u) +if [ ${#DECLARED[@]} -eq 0 ]; then + bad "mise.toml declares no tools — an empty [tools] table installs nothing" + exit 1 +fi + +# Banned estate-wide. `make` and `nix` are in LANGUAGE-POLICY's toolchain rules; +# deno/pnpm are permitted (2026-10-14 ruling) so they are not here. +BANNED='python|python3|pip|pip3|poetry|black|ruff|isort|pytest|node|nodejs|npm|yarn|typescript|rescript|make|nix|go|golang|java|kotlin|gradle|maven|ruby|gem|vitest|jest|prettier|eslint' +FAILS=0 + +BANNED_HIT="" +for t in "${DECLARED[@]}"; do + # a backend-qualified name (cargo:foo) is judged on its backend + base="${t%%:*}" + if grep -qE "^($BANNED)$" <<< "$base"; then + BANNED_HIT="$BANNED_HIT $t" + fi +done +if [ -n "$BANNED_HIT" ]; then + bad "banned tool(s) declared:$BANNED_HIT" + note "LANGUAGE-POLICY §Banned Languages / JS-RUNTIME-POLICY. Python is banned" + note "estate-wide; JavaScript runs Bun > Deno > pnpm from one package.json." + FAILS=$((FAILS + 1)) +fi + +FOREIGN="" +MISSING="" +for t in "${DECLARED[@]}"; do + case " $TOOLS " in *" $t "*) continue ;; esac + FOREIGN="$FOREIGN $t" +done +for t in $TOOLS; do + case " ${DECLARED[*]} " in *" $t "*) continue ;; esac + MISSING="$MISSING $t" +done + +if [ -n "$FOREIGN" ]; then + bad "declared for no detected language:$FOREIGN" + note "languages: $LANGS. A tool for a language this repo does not carry is" + note "installed on every checkout and audits as a foreign dependency." + FAILS=$((FAILS + 1)) +fi +if [ -n "$MISSING" ]; then + bad "needed by a detected language but not declared:$MISSING" + note "the repo carries the language; its toolchain must be declared for it." + FAILS=$((FAILS + 1)) +fi + +if [ "$FAILS" -eq 0 ]; then + ok "mise.toml matches the declared languages ($LANGS): ${DECLARED[*]}" + exit 0 +fi +exit 1 diff --git a/scripts/check-no-a2ml.sh b/scripts/check-no-a2ml.sh new file mode 100755 index 00000000..fd9a5148 --- /dev/null +++ b/scripts/check-no-a2ml.sh @@ -0,0 +1,30 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# check-no-a2ml.sh — enforce the estate rule that no .a2ml file exists. The +# format is retired: a repo's facts are clauses of its deed (_chora.deed, +# deed.abnf) and its contracts are .k9 / .k9.ncl files. +# +# Usage: check-no-a2ml.sh [REPO_ROOT] +# Inspects tracked files when REPO_ROOT is a git work tree, and every file +# under it (minus .git/) otherwise, so an untracked mint is covered too. +# Exit: 0 none found; 1 one or more .a2ml files (listed); 2 bad path. +set -euo pipefail + +REPO_ROOT="${1:-.}" +[ -d "$REPO_ROOT" ] || { echo "ERROR: repository path does not exist: $REPO_ROOT" >&2; exit 2; } + +if git -C "$REPO_ROOT" rev-parse --is-inside-work-tree >/dev/null 2>&1; then + FOUND=$(git -C "$REPO_ROOT" ls-files -- '*.a2ml' '*.A2ML') +else + FOUND=$(find "$REPO_ROOT" -path '*/.git' -prune -o -type f -iname '*.a2ml' -printf '%P\n') +fi + +if [ -z "$FOUND" ]; then + echo "PASS: no .a2ml files in the inspected repository" + exit 0 +fi +echo "FAIL: .a2ml is a retired format; move these facts into the repo deed or a .k9 contract:" +printf ' %s\n' $FOUND +exit 1 diff --git a/scripts/check-no-placeholders.sh b/scripts/check-no-placeholders.sh index 810702e9..3946a92e 100755 --- a/scripts/check-no-placeholders.sh +++ b/scripts/check-no-placeholders.sh @@ -4,14 +4,14 @@ # # check-no-placeholders.sh — no repo may ship an unfilled {{PLACEHOLDER}}. # -# Estate rule (methodology.a2ml: reject-if-contains): a token that `just repo-init` +# Estate rule (the deed's (bot-directives (methodology)) reject-if-contains): a token that `just repo-init` # did not fill is debt, and in .github/settings.yml or SECURITY.md it is a # defect with consequences — probot/settings applies settings.yml on every push, # and a security policy that cites a key nobody holds is worse than one that # says "email us". # # This is the single implementation of that rule, called from two places: -# * .github/workflows/openssf-compliance.yml — on the repo as committed +# * .github/workflows/ossf-best-practices.yml (job openssf-compliance) — on the repo as committed # * tests/e2e/template_instantiation_test.sh — on a freshly init'd repo, # which is where a leak is still cheap to fix # It exists as a script rather than inline shell in each caller because the @@ -107,8 +107,14 @@ fi # basename remains as the last fallback for a checkout with no remote. REPO_NAME="${GITHUB_REPOSITORY:-}" if [ -z "$REPO_NAME" ]; then - REPO_NAME="$(git -C "$REPO_ROOT" config --get remote.origin.url 2>/dev/null \ - | sed -E 's#(\.git)?/?$##; s#^.*[:/]([^/]+/[^/]+)$#\1#')" + # `|| true` is load-bearing: a repository with NO origin remote (a fresh + # `git init` + commit, which is exactly what `just repo-init` produces + # before the first push) makes `git config` exit 1, and with `set -e` + + # `pipefail` that killed the whole gate — exit 1, no output, no finding. + # Measured on a minted tree that had no remote yet: the gate failed silently + # and looked like a token leak to anyone reading the exit code. + REPO_NAME="$( { git -C "$REPO_ROOT" config --get remote.origin.url 2>/dev/null \ + | sed -E 's#(\.git)?/?$##; s#^.*[:/]([^/]+/[^/]+)$#\1#' ; } || true )" fi [ -z "$REPO_NAME" ] && REPO_NAME="$(cd "$REPO_ROOT" && basename "$(pwd)")" case "$REPO_NAME" in @@ -124,8 +130,17 @@ ALLOWED=( ".machine_readable/ai/PLACEHOLDERS.adoc" # the token vocabulary itself "EXPLAINME.adoc" # prose explaining that tokens exist "scripts/check-no-placeholders.sh" # this file (the pattern above) - "tests/e2e/template_instantiation_test.sh" # names tokens in its answer list ) +# Template machinery the mint carries unchanged, whose fixtures name tokens on +# purpose (the e2e answer list, the Julia UUID test). One manifest, read by +# repo-init too, so the mint and this gate cannot disagree about what is a +# fixture: see .machine_readable/mint-verbatim.txt. +VERBATIM_LIST="$REPO_ROOT/.machine_readable/mint-verbatim.txt" +if [ -f "$VERBATIM_LIST" ]; then + while IFS= read -r v; do + [ -n "$v" ] && ALLOWED+=("$v") + done < <(sed -e 's/#.*//' -e 's/[[:space:]]*$//' "$VERBATIM_LIST") +fi is_allowed() { local rel="$1" @@ -147,6 +162,26 @@ is_allowed() { # teach people that this gate cries wolf. Real tokens name a real init variable. META_TOKENS='PLACEHOLDER|ANYTHING|TOKEN|UPPER_SNAKE' +# repo_files — every file of the repository holding an upper-snake token, as +# "$REPO_ROOT/". In a git work tree, "of the repository" means tracked or +# untracked-and-not-ignored, the same set `just repo-init` edits: a git-ignored +# cache such as _build/dependencies/ holds OTHER repositories' files, whose +# tokens are not this repo's leak. Outside git, every file is scanned. +repo_files() { + if git -C "$REPO_ROOT" rev-parse --is-inside-work-tree >/dev/null 2>&1; then + git -C "$REPO_ROOT" ls-files -z --cached --others --exclude-standard \ + | while IFS= read -r -d '' rel; do + [ -f "$REPO_ROOT/$rel" ] && [ ! -L "$REPO_ROOT/$rel" ] || continue + grep -qIE '\{\{[A-Z][A-Z0-9_]*\}\}' "$REPO_ROOT/$rel" 2>/dev/null \ + && printf '%s\n' "$REPO_ROOT/$rel" + done + else + grep -rlE '\{\{[A-Z][A-Z0-9_]*\}\}' "$REPO_ROOT" \ + --exclude-dir=.git --binary-files=without-match 2>/dev/null + fi + return 0 +} + LEAKS=() while IFS= read -r hit; do rel="${hit#"$REPO_ROOT"/}" @@ -156,8 +191,7 @@ while IFS= read -r hit; do | grep -qvE "^\{\{($META_TOKENS)\}\}$"; then LEAKS+=("$rel") fi -done < <(grep -rlE '\{\{[A-Z][A-Z0-9_]*\}\}' "$REPO_ROOT" \ - --exclude-dir=.git --binary-files=without-match 2>/dev/null | sort) +done < <(repo_files | sort) if [ ${#LEAKS[@]} -eq 0 ]; then echo "PASS: no unfilled {{PLACEHOLDER}} tokens" diff --git a/scripts/check-no-vlang.sh b/scripts/check-no-vlang.sh index aeb62fcb..39f3a538 100755 --- a/scripts/check-no-vlang.sh +++ b/scripts/check-no-vlang.sh @@ -26,7 +26,6 @@ if git -C "$REPO_ROOT" rev-parse --is-inside-work-tree >/dev/null 2>&1; then ':(exclude)scripts/check-no-vlang.sh' \ ':(exclude)tests/workflows/check_no_vlang_test.sh' \ ':(exclude).github/workflows/estate-rules.yml' \ - ':(exclude).machine_readable/descriptiles/PLAYBOOK.a2ml' \ 2>/dev/null || true) V_MODS=$(git -C "$REPO_ROOT" ls-files -- 'v.mod' '**/v.mod' 2>/dev/null || true) else @@ -37,7 +36,6 @@ else --exclude=check-no-vlang.sh \ --exclude=check_no_vlang_test.sh \ --exclude=estate-rules.yml \ - --exclude=PLAYBOOK.a2ml \ 2>/dev/null || true) V_MODS=$(find "$REPO_ROOT" -type f -name v.mod \ -not -path '*/.git/*' -not -path '*/affinescript/*' \ diff --git a/scripts/check-proofs.sh b/scripts/check-proofs.sh index 0135dfed..c06d0862 100755 --- a/scripts/check-proofs.sh +++ b/scripts/check-proofs.sh @@ -38,7 +38,7 @@ # source-root : directory the prover is invoked from, chosen so the module's # declared name matches its path (getting this wrong is hole #2). # gated : MUST compile. A failure fails this script and CI. -# quarantine : known-broken, tracked in STATE.a2ml. Must CONTINUE to fail; +# quarantine : known-broken, tracked in docs/status/ROADMAP.adoc. Must CONTINUE to fail; # if one starts compiling the script fails and tells you to # promote it, so the list cannot rot into a permanent excuse. # @@ -136,7 +136,7 @@ while IFS='|' read -r root rel status note; do echo "PASS" else echo "PASS -- UNEXPECTED (quarantined module now compiles)" - echo " Promote '$rel' to 'gated' in $MANIFEST_FILE and update STATE.a2ml." + echo " Promote '$rel' to 'gated' in $MANIFEST_FILE and update docs/status/ROADMAP.adoc." unexpected_pass=$((unexpected_pass + 1)) fi else diff --git a/scripts/check-required-contexts.sh b/scripts/check-required-contexts.sh new file mode 100755 index 00000000..235f28b9 --- /dev/null +++ b/scripts/check-required-contexts.sh @@ -0,0 +1,143 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# Verify that: +# 1. Every required status check context mapped in +# .machine_readable/required-contexts-allow.txt (and any non-empty +# required_status_checks context in .github/rulesets/*.json) resolves to +# an existing workflow under .github/workflows/ that runs on pull_request +# without path-filtering that could strand a PR (#219 defect class). +# 2. No workflow in .github/workflows/ invokes an admin bypass (`gh pr merge +# --admin`) — enforcing cicd-squabbler's core `squabble != bypass` +# invariant statically alongside the runtime binary. +# +# Exit contract (proven-tests-and-benches 3-outcome convention): +# 0 = all mapped required contexts are producible on pull_request and zero +# bypass commands exist in workflows +# 1 = phantom/path-stranded required context or admin-bypass workflow found +# 2 = setup error (missing repo directory, workflows directory, or allowfile) +set -euo pipefail + +REPO_ROOT="${1:-.}" +if [ ! -d "$REPO_ROOT" ]; then + echo "check-required-contexts: repo directory '$REPO_ROOT' does not exist" >&2 + exit 2 +fi +WORKFLOWS_DIR="$REPO_ROOT/.github/workflows" +ALLOW_FILE="$REPO_ROOT/.machine_readable/required-contexts-allow.txt" + +if [ ! -d "$WORKFLOWS_DIR" ]; then + echo "check-required-contexts: workflows directory '$WORKFLOWS_DIR' does not exist" >&2 + exit 2 +fi +if [ ! -f "$ALLOW_FILE" ]; then + echo "check-required-contexts: mapping file '$ALLOW_FILE' does not exist" >&2 + exit 2 +fi + +command -v bun >/dev/null 2>&1 || { + echo "check-required-contexts: bun is required to parse workflow YAML" >&2 + exit 2 +} + +bun run - "$REPO_ROOT" <<'JS' +import { readdirSync, readFileSync, existsSync } from "node:fs"; +import { join, resolve } from "node:path"; + +const root = resolve(process.argv[2]); +const wfDir = join(root, ".github/workflows"); +const allowPath = join(root, ".machine_readable/required-contexts-allow.txt"); +const rulesetsDir = join(root, ".github/rulesets"); + +let errors = 0; +/** Report a violation and increment the shared error count without exiting. */ +function fail(msg) { + console.error(`FAIL: ${msg}`); + errors++; +} + +// 1. Parse mapping file: " => <.github/workflows/foo.yml>" +const mapped = new Map(); +const lines = readFileSync(allowPath, "utf8").split(/\r?\n/); +for (let idx = 0; idx < lines.length; idx++) { + const trimmed = lines[idx].trim(); + if (!trimmed || trimmed.startsWith("#")) continue; + const parts = trimmed.split("=>").map((s) => s.trim()); + if (parts.length !== 2 || !parts[0] || !parts[1]) { + console.error(`check-required-contexts: malformed mapping at line ${idx + 1}: ${lines[idx]}`); + process.exit(2); + } + mapped.set(parts[0], parts[1]); +} +if (mapped.size === 0) { + console.error("check-required-contexts: 0 contexts mapped in required-contexts-allow.txt"); + process.exit(2); +} + +// 2. Also collect any required_status_checks declared in .github/rulesets/*.json +if (existsSync(rulesetsDir)) { + for (const name of readdirSync(rulesetsDir).sort()) { + if (!name.endsWith(".json")) continue; + const rs = JSON.parse(readFileSync(join(rulesetsDir, name), "utf8")); + for (const rule of rs.rules ?? []) { + if (rule.type === "required_status_checks") { + for (const check of rule.parameters?.required_status_checks ?? []) { + if (check.context && !mapped.has(check.context)) { + fail(`ruleset ${name} requires context '${check.context}', which has no producer mapping in .machine_readable/required-contexts-allow.txt`); + } + } + } + } + } +} + +// 3. Verify each mapped producer workflow exists, triggers on pull_request, and +// has no pull_request.paths / paths-ignore filter that can strand a PR. +for (const [ctx, relWf] of mapped.entries()) { + const fullWf = join(root, relWf); + if (!existsSync(fullWf)) { + fail(`required context '${ctx}' maps to missing workflow '${relWf}'`); + continue; + } + const doc = Bun.YAML.parse(readFileSync(fullWf, "utf8")); + const onBlock = doc?.on ?? doc?.true; + const triggers = + typeof onBlock === "string" + ? [onBlock] + : Array.isArray(onBlock) + ? onBlock.map(String) + : onBlock && typeof onBlock === "object" + ? Object.keys(onBlock) + : []; + if (!triggers.includes("pull_request")) { + fail(`required context '${ctx}' producer '${relWf}' does not trigger on pull_request`); + continue; + } + const prCfg = + onBlock && typeof onBlock === "object" && !Array.isArray(onBlock) + ? onBlock.pull_request + : null; + if (prCfg && typeof prCfg === "object") { + if (Object.hasOwn(prCfg, "paths") || Object.hasOwn(prCfg, "paths-ignore")) { + fail(`required context '${ctx}' producer '${relWf}' filters pull_request by paths — strands PRs that do not touch those paths`); + } + } +} + +// 4. Enforce squabble != bypass across all workflows: no workflow may call +// `gh pr merge ... --admin` (joining backslash line continuations first). +for (const name of readdirSync(wfDir).sort()) { + if (!name.endsWith(".yml") && !name.endsWith(".yaml")) continue; + const raw = readFileSync(join(wfDir, name), "utf8").replace(/\\\r?\n\s*/g, " "); + if (/gh\s+pr\s+merge\b[^\n]*--admin\b/.test(raw)) { + fail(`.github/workflows/${name} invokes 'gh pr merge --admin' (violates squabble != bypass)`); + } +} + +if (errors > 0) { + console.error(`check-required-contexts: ${errors} violation(s) found`); + process.exit(1); +} +console.log(`OK: ${mapped.size} required status context(s) verified producible on pull_request; 0 admin-bypass workflows`); +JS diff --git a/scripts/check-spdx-headers.sh b/scripts/check-spdx-headers.sh new file mode 100755 index 00000000..21c93d87 --- /dev/null +++ b/scripts/check-spdx-headers.sh @@ -0,0 +1,330 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# check-spdx-headers.sh — the SPDX gate, with the extension set derived from the +# languages the repository actually declares. +# +# ── Why this exists ───────────────────────────────────────────────────────── +# +# The gate this replaces was a fixed glob in every repository: +# +# find . -name '*.rs' -o -name '*.res' -o -name '*.gleam' | head -20 \ +# | xargs -r grep -L 'SPDX-License-Identifier' | wc -l | grep -q '^0$' +# +# It is wrong three ways, and each wrongness shipped into the repos it was +# copied into: +# +# 1. THE EXTENSIONS ARE ONE LANGUAGE'S. In a Julia, Elixir, Idris2, Zig, +# OCaml, Haskell or shell repository that find matches NOTHING. It then +# pipes an empty list to xargs, counts 0, and reports PASS. A check that +# examines zero files and reports PASS is worse than no check: it reports +# coverage it does not have. +# 2. `head -20` CAPS THE SCAN at twenty files, so a 400-file repository was +# surveyed 5% deep and graded on that. +# 3. Its answer does not depend on the repository at all, so it cannot notice +# the one thing it exists to notice: a new language arriving unscanned. +# +# So the extension set is derived, per repository: +# +# * the DECLARED languages come from the provisioning engine +# (`build/just/provision-lib.sh langs`) — the same detection `just doctor`, +# `just build` and `just fmt-check` use, so no two of them can disagree; +# * every other KNOWN source extension PRESENT in the tree is scanned too. A +# file the gate knows how to read but skipped is exactly the defect above, +# one layer down: the template's own Rust mint tools live in scripts/*.rs +# with no Cargo.toml, so a language-only derivation would have left them +# out. +# * a declared language with ZERO matching files is a FAIL (the declaration +# lies, or the scan looks in the wrong place); +# * a repository with no scanned file at all is a FAIL (examined nothing); +# * a BANNED language's source is a FAIL (LANGUAGE-POLICY: Python, TypeScript, +# Node, Go, Java; see §Banned Languages); +# * every matched file is checked — there is no cap. +# +# ── Usage ─────────────────────────────────────────────────────────────────── +# check-spdx-headers.sh [--root DIR] [--langs "julia zig"] [--exts "jl,zig"] +# [--allow-empty] [--quiet] +# +# --root DIR repository to scan (default: this script's repository) +# --langs LIST language list to derive from (default: detected via +# build/just/provision-lib.sh when present, else by manifest) +# --exts LIST skip derivation and scan exactly these extensions +# --allow-empty do not fail when nothing matched (test fixtures only; the +# shipped gate never runs with it) +# --quiet print failures only +# +# Exit: 0 = every matched file carries a header; 1 = findings; 2 = usage error. +# +# Canon: RSR-SPEC §1.3 (licensing); hyperpolymath/standards 0-canon/rsr. + +set -uo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/.." && pwd)" + +ROOT="$REPO_DIR" +LANGS="" +EXTS="" +ALLOW_EMPTY=0 +QUIET=0 + +while [ $# -gt 0 ]; do + case "$1" in + --root) ROOT="${2:-}"; shift 2 ;; + --langs) LANGS="${2:-}"; shift 2 ;; + --exts) EXTS="${2:-}"; shift 2 ;; + --allow-empty) ALLOW_EMPTY=1; shift ;; + --quiet) QUIET=1; shift ;; + -h|--help) sed -n '2,60p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; + *) echo "check-spdx-headers: unknown option: $1" >&2; exit 2 ;; + esac +done + +[ -d "$ROOT" ] || { echo "check-spdx-headers: not a directory: $ROOT" >&2; exit 2; } +ROOT="$(cd "$ROOT" && pwd)" + +ok() { [ "$QUIET" -eq 1 ] || printf ' \033[32mPASS\033[0m %s\n' "$1"; } +bad() { printf ' \033[31mFAIL\033[0m %s\n' "$1"; } +warn() { [ "$QUIET" -eq 1 ] || printf ' \033[33mWARN\033[0m %s\n' "$1"; } +note() { [ "$QUIET" -eq 1 ] || printf ' %s\n' "$1"; } +info() { [ "$QUIET" -eq 1 ] || printf ' \033[34minfo\033[0m %s\n' "$1"; } + +# Source extensions of language $1. One table, here, because this gate is the +# only consumer of the mapping; the language LIST is not duplicated — it comes +# from the provisioning engine, so a new language is detected in one place. +exts_for() { + case "$1" in + rust) echo "rs" ;; + julia) echo "jl" ;; + zig) echo "zig" ;; + idris2) echo "idr" ;; + elixir) echo "ex exs" ;; + gleam) echo "gleam" ;; + ocaml) echo "ml mli" ;; + haskell) echo "hs" ;; + bun) echo "js mjs cjs" ;; + affinescript) echo "affine" ;; + docs) echo "" ;; # prose repository: its shell scripts are still scanned + *) echo "" ;; + esac +} +# Shell, Nickel (the contracts), jq (the classifiers) and Guile (Guix) are estate +# formats rather than one language's, so they are scanned wherever they appear. +ESTATE_EXTS="sh ncl jq scm" +# Everything this gate can scan. +KNOWN_EXTS="rs jl zig idr ex exs gleam ml mli hs js mjs cjs affine sh ncl jq scm" +# Banned estate-wide (LANGUAGE-POLICY §Banned Languages). Their presence is a +# policy violation in itself, headers or not. +BANNED_EXTS="py pyi pyx ts tsx go java kt kts" + +has_ext() { # $1 list, $2 ext + case " $1 " in *" $2 "*) return 0 ;; esac + return 1 +} + +# ── Languages ─────────────────────────────────────────────────────────────── +if [ -z "$LANGS" ] && [ -z "$EXTS" ]; then + LIB="$ROOT/build/just/provision-lib.sh" + if [ -f "$LIB" ]; then + LANGS="$(cd "$ROOT" && PROVISION_ROOT="$ROOT" bash "$LIB" langs 2>/dev/null | tr '\n' ' ')" + fi +fi +if [ -z "$LANGS" ] && [ -z "$EXTS" ]; then + # No provisioning engine (a fixture, or a repo predating it): detect by the + # manifests this gate knows, so it still cannot report a vacuous PASS. + if [ -f "$ROOT/Cargo.toml" ]; then LANGS="rust" + elif [ -f "$ROOT/Project.toml" ]; then LANGS="julia" + elif [ -f "$ROOT/mix.exs" ]; then LANGS="elixir" + elif [ -f "$ROOT/gleam.toml" ]; then LANGS="gleam" + elif [ -f "$ROOT/dune-project" ]; then LANGS="ocaml" + elif [ -f "$ROOT/package.json" ]; then LANGS="bun" + else LANGS="docs" + fi +fi + +# ── Files ─────────────────────────────────────────────────────────────────── +# Tracked (respects .gitignore, never descends into vendored trees) when in a +# work tree; otherwise every file under --root. Same rule as repo-init's +# mint_files, so "the repository" means the same thing to both. +list_files() { + if git -C "$ROOT" rev-parse --is-inside-work-tree >/dev/null 2>&1; then + # Paths from `git -C DIR` are relative to DIR, not to the caller's cwd: + # prefix them, or every `head` below reads a same-named file in whatever + # directory the gate was invoked from (measured: a fixture that happened + # to share a path with the template read the TEMPLATE's copy and graded + # that). + git -C "$ROOT" ls-files -z --cached --others --exclude-standard \ + | while IFS= read -r -d '' f; do printf '%s\n' "$ROOT/$f"; done | { + while IFS= read -r f; do + case "$f" in + */node_modules/*|*/target/*|*/_build/*|*/deps/*|*/vendor/*) continue ;; + */tests/controls/*) continue ;; + esac + [ -f "$f" ] || continue # tracked but deleted from the work tree + printf '%s\n' "$f" + done + } + return 0 + fi + find "$ROOT" -type f -print0 | while IFS= read -r -d '' f; do + case "$f" in + */.git/*|*/node_modules/*|*/target/*|*/_build/*|*/deps/*|*/vendor/*) continue ;; + # Planted negative controls: their bytes ARE the input a control test + # asserts on, and one of them is deliberately a file with no header + # because that is what the control proves is catchable. + */tests/controls/*) continue ;; + esac + [ -f "$f" ] || continue + printf '%s\n' "$f" + done +} + +mapfile -t ALL_FILES < <(list_files | sort -u) + +# Extensions present in the tree, one per line. +present_exts() { + local f base e + for f in "${ALL_FILES[@]}"; do + base="${f##*/}" + case "$base" in *.*) e="${base##*.}" ;; *) e="" ;; esac + [ -n "$e" ] && printf '%s\n' "$e" + done | sort -u +} +mapfile -t PRESENT < <(present_exts) + +if [ -n "$EXTS" ]; then + SCAN_EXTS="$(echo "$EXTS" | tr ',' ' ' | xargs)" +else + # Derived: declared languages first (and a hole in this table is a finding, + # not a silent skip), then the estate formats, then any other known source + # extension that is actually present. + DERIVED="" + for l in $LANGS; do + got="$(exts_for "$l")" + if [ -z "$got" ] && [ "$l" != docs ]; then + bad "language '$l' is declared but this gate has no extension for it" + note "add it to exts_for() in $0 — an unscannable language is not a pass" + exit 1 + fi + for e in $got; do has_ext "$DERIVED" "$e" || DERIVED="$DERIVED $e"; done + done + SCAN_EXTS="$(echo "$DERIVED" | xargs)" + for e in $ESTATE_EXTS; do + has_ext " $SCAN_EXTS " "$e" || SCAN_EXTS="$SCAN_EXTS $e" + done + ORPHANS="" + for e in "${PRESENT[@]}"; do + has_ext "$KNOWN_EXTS" "$e" || continue + has_ext " $SCAN_EXTS " "$e" && continue + SCAN_EXTS="$SCAN_EXTS $e" + ORPHANS="$ORPHANS .$e" + done + SCAN_EXTS="$(echo "$SCAN_EXTS" | xargs)" + [ -n "$ORPHANS" ] && info "also scanning source present outside the declared languages:$ORPHANS" +fi + +# ── Banned languages ──────────────────────────────────────────────────────── +BANNED_HITS=() +for f in "${ALL_FILES[@]}"; do + base="${f##*/}" + case "$base" in *.*) e="${base##*.}" ;; *) continue ;; esac + has_ext "$BANNED_EXTS" "$e" && BANNED_HITS+=("${f#"$ROOT"/}") +done + +# ── Scan ──────────────────────────────────────────────────────────────────── +if [ -z "$SCAN_EXTS" ]; then + bad "no extensions derived and none given — nothing would be scanned" + exit 1 +fi + +info "languages: ${LANGS:-}" +info "scanning extensions: $SCAN_EXTS" + +SCANNED=() +declare -A COUNT=() +for f in "${ALL_FILES[@]}"; do + base="${f##*/}" + case "$base" in *.*) e="${base##*.}" ;; *) continue ;; esac + has_ext " $SCAN_EXTS " "$e" || continue + SCANNED+=("$f") + COUNT["$e"]=$(( ${COUNT["$e"]:-0} + 1 )) +done + +# Declared language, no files: the extension table and the detector disagree, or +# the declaration lies. Name the empty extension rather than leaving it to feel. +# A language is empty only when NO extension of that language matched. Several +# mappings list alternatives (.ex/.exs, .ml/.mli, .js/.mjs/.cjs), so judging each +# extension separately failed perfectly good repositories for the alternative +# they do not use — an Elixir tree with .ex and no .exs was "missing" a language +# it is written in. +EMPTY_DECL="" +for l in $LANGS; do + total=0 + exts="$(exts_for "$l")" + [ -n "$exts" ] || continue # `docs` maps to no extension: nothing to find + for e in $exts; do + total=$(( total + ${COUNT["$e"]:-0} )) + done + [ "$total" -eq 0 ] && EMPTY_DECL="$EMPTY_DECL $l($(echo "$exts" | sed 's/^ *//; s/ */, ./g; s/^/\./'))" +done +if [ -n "$EMPTY_DECL" ]; then + bad "declared language source not found:$EMPTY_DECL" + note "A language is declared but its files are absent. Either the declaration" + note "is wrong or the scan is looking in the wrong place; both are findings." + exit 1 +fi + +TOTAL=${#SCANNED[@]} +if [ "$TOTAL" -eq 0 ]; then + if [ "$ALLOW_EMPTY" -eq 1 ]; then + info "matched zero files (--allow-empty)" + exit 0 + fi + bad "matched ZERO files with extensions: $SCAN_EXTS" + note "A gate that examines nothing is not a pass. Either this repository has no" + note "source in any language it declares, or the scan is looking in the wrong" + note "place. Both are findings, not a green tick." + exit 1 +fi + +MISSING=() +for f in "${SCANNED[@]}"; do + # No `head | grep -q` pipe: with `set -o pipefail`, `grep -q` exiting on its + # first match SIGPIPEs `head` and flips a MATCH into a failure. It is a race + # (measured: a gate reporting different files each run over an unchanged + # tree), and on a slow filesystem it would be a false finding. + head10="$(head -10 "$f" 2>/dev/null || true)" + grep -q 'SPDX-License-Identifier' <<< "$head10" || MISSING+=("${f#"$ROOT"/}") +done + +if [ ${#BANNED_HITS[@]} -gt 0 ]; then + bad "${#BANNED_HITS[@]} banned-language source file(s) present:" + for f in "${BANNED_HITS[@]}"; do printf ' %s\n' "$f"; done + note "LANGUAGE-POLICY §Banned Languages: Python, TypeScript, Node, Go, Java." + note "Delete or port them; a header does not make them permitted." +fi + +if [ ${#MISSING[@]} -eq 0 ]; then + ok "SPDX headers: $TOTAL/$TOTAL files ($SCAN_EXTS)" + if [ "$QUIET" -eq 0 ]; then + for e in $SCAN_EXTS; do printf ' %s: %s\n' "$e" "${COUNT["$e"]:-0}"; done + fi +else + bad "SPDX headers: $((TOTAL - ${#MISSING[@]}))/$TOTAL files carry a header" + for f in "${MISSING[@]}"; do printf ' missing: %s\n' "$f"; done + note "Add the language's comment form in the first 10 lines:" + note " C family / rust / zig / js: // SPDX-License-Identifier: MPL-2.0" + note " shell / julia / elixir / hs: # SPDX-License-Identifier: MPL-2.0" + note " toml / yaml / ncl: # SPDX-License-Identifier: MPL-2.0" +fi + +# An explicit exit, not a trailing test. A script whose exit status comes from +# its last expression returns whatever that expression happened to be in some +# branch — this one returned 1 in a minted tree while printing PASS, which made +# `just repo-init` abort with "the minted tree fails a gate" and no failing gate +# in the log above it. +if [ ${#MISSING[@]} -eq 0 ] && [ ${#BANNED_HITS[@]} -eq 0 ]; then + exit 0 +fi +exit 1 diff --git a/scripts/check-template-conformance.sh b/scripts/check-template-conformance.sh new file mode 100755 index 00000000..c075877e --- /dev/null +++ b/scripts/check-template-conformance.sh @@ -0,0 +1,274 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# check-template-conformance.sh — the CHECK half of the template contract. +# +# ── Why this exists ────────────────────────────────────────────────────────── +# +# The estate's own comment in build/just/repo-init.just reads: +# +# "Copier/Cruft solved it with an answer-file + update + check; this estate +# hand-simulated it as recurring standardisation-PR campaigns. This is the +# answer-file." +# +# It built the answer-file — then .machine_readable/PROVENANCE.a2ml, now the +# repo deed's (provenance) clause — and then built neither the update nor the +# check. Nothing in this repository read that record. It was write-only. +# +# Four open defects are all the same missing half: +# +# #200 CONTRIBUTING.md shipped hardcoded template identity into children +# #201 the generated CLAUDE arrival pack retained the TEMPLATE's uuid, +# clade and "canonical template" purpose in a Julia child +# #203 a template work branch was copied into knot-knot with no common +# ancestor — git proved the trees byte-identical +# +# Each is a repo asserting provenance it does not have, and none could be +# detected because no check read the record. +# +# ── What it checks ─────────────────────────────────────────────────────────── +# +# Structural invariants (always, no network): +# T1 the repo deed carries a (provenance) clause +# (a repo still carrying only the retired PROVENANCE.a2ml is BLOCKED: +# that file is not read, it must be migrated into the deed first) +# T2 it does not name THIS repo as its own template (self-parent) +# T3 :template-branch / :template-commit / :template-tree are not UNASSIGNED +# T4 the repo carries no branches beyond its declared :extra-branches +# +# T2 is the #200/#201 class. T4 is #203. +# +# Drift report (only with --template PATH, and only ADVISORY): +# D1 template-owned paths missing from this repo +# D2 template-owned paths that differ from the template checkout +# +# Drift is advisory on purpose. A child is SUPPOSED to diverge; that is what +# minting is for. Reporting divergence as failure is how a gate becomes +# unpassable and then gets `continue-on-error`-ed, which is how the estate's +# Hypatia gate ended up unable to fire at all (measured twice: #49, #64). +# +# ── Usage ──────────────────────────────────────────────────────────────────── +# bash scripts/check-template-conformance.sh [--repo PATH] [--template PATH] +# [--report-only] [--quiet] +# +# --repo PATH the minted repo to check (default: this script's repo) +# --template PATH a template checkout, to enable the advisory drift report +# --report-only never exit non-zero (for rollout onto existing children) +# --quiet suppress the per-check PASS lines +# +# Exit: 0 conforming (or report-only), 1 findings, 2 usage/environment error. + +set -uo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/.." && pwd)" + +TARGET="$REPO_DIR" +TEMPLATE="" +REPORT_ONLY=0 +QUIET=0 + +while [ $# -gt 0 ]; do + case "$1" in + --repo) TARGET="${2:-}"; shift 2 ;; + --template) TEMPLATE="${2:-}"; shift 2 ;; + --report-only) REPORT_ONLY=1; shift ;; + --quiet) QUIET=1; shift ;; + -h|--help) sed -n '2,60p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; + *) echo "unknown option: $1" >&2; exit 2 ;; + esac +done + +[ -d "$TARGET" ] || { echo "check-template-conformance: not a directory: $TARGET" >&2; exit 2; } +TARGET="$(cd "$TARGET" && pwd)" + +PASS=0; FAIL=0; WARN=0 +ok() { PASS=$((PASS+1)); [ "$QUIET" -eq 1 ] || printf ' \033[32mPASS\033[0m %s\n' "$1"; } +bad() { FAIL=$((FAIL+1)); printf ' \033[31mFAIL\033[0m %s\n' "$1"; } +warn() { WARN=$((WARN+1)); printf ' \033[33mWARN\033[0m %s\n' "$1"; } +note() { [ "$QUIET" -eq 1 ] || printf ' %s\n' "$1"; } + +READ="$SCRIPT_DIR/deed-field.sh" +DEED="$(bash "$READ" --find "$TARGET" 2>/dev/null || true)" +RETIRED="$TARGET/.machine_readable/PROVENANCE.a2ml" + +finish() { + echo + if [ "$FAIL" -gt 0 ]; then + printf 'conformance: \033[31m%d failed\033[0m, %d passed, %d warnings\n' "$FAIL" "$PASS" "$WARN" + else + printf 'conformance: \033[32m%d passed\033[0m, %d warnings\n' "$PASS" "$WARN" + fi + if [ "$REPORT_ONLY" -eq 1 ]; then + echo "(report-only: not failing the run)" + exit 0 + fi + [ "$FAIL" -eq 0 ] +} + +# ── Self-skip: this IS the template ────────────────────────────────────────── +# Same convention as tests/e2e/template_instantiation_test.sh. archetypes/ and +# build/templates/ are template-only and are removed at mint, so their presence +# means this repo has not been instantiated and has no parent to conform to. +if [ -d "$TARGET/archetypes" ] || [ -d "$TARGET/build/templates" ]; then + echo "SKIP: $TARGET is a template (archetypes/ or build/templates/ present) — nothing to conform to." + exit 0 +fi + +echo "template conformance: $TARGET" +echo + +# ── T1: provenance exists ──────────────────────────────────────────────────── +if [ -n "$DEED" ] && bash "$READ" --has "$DEED" provenance; then + ok "T1 provenance present ($(basename "$DEED") (provenance))" +elif [ -f "$RETIRED" ]; then + bad "T1 BLOCKED: only the retired .machine_readable/PROVENANCE.a2ml — not read" + note "Move its facts into the repo deed's (provenance) clause and delete the" + note "a2ml file; this check will not parse the retired format." + finish + exit $? +else + bad "T1 no (provenance) clause in a repo deed — this repo cannot state what it was minted from" + note "A repo minted through the GitHub template UI, or by copying a tree, never" + note "runs repo-init and so never writes this clause. That is the #203 mechanism." + note "Recreate it by hand from the template commit you actually took." + finish + exit $? +fi + +# prov_get KEY — the value of :KEY in the deed's (provenance) clause, or empty. +prov_get() { + bash "$READ" "$DEED" provenance "$1" 2>/dev/null || true +} + +T_REPO="$(prov_get template-repo)" +T_BRANCH="$(prov_get template-branch)" +T_COMMIT="$(prov_get template-commit)" +T_TREE="$(prov_get template-tree)" + +# ── T2: no self-parent ─────────────────────────────────────────────────────── +SELF_SLUG="" +if command -v git >/dev/null 2>&1 && git -C "$TARGET" rev-parse --git-dir >/dev/null 2>&1; then + url="$(git -C "$TARGET" remote get-url origin 2>/dev/null || true)" + # normalise git@github.com:o/r.git and https://github.com/o/r(.git) to o/r. + # Strip the .git suffix FIRST: the previous single-sed form left it on, so + # SELF_SLUG became "owner/repo.git" and the T2 self-parent check silently + # never matched. Caught by its own negative control. + SELF_SLUG="$(printf '%s' "$url" \ + | sed -E 's|\.git$||; s|^[a-zA-Z][a-zA-Z0-9+.-]*://||; s|^git@||; s|:|/|' \ + | awk -F/ 'NF>=2 {print $(NF-1)"/"$NF}' || true)" +fi + +if [ -z "$T_REPO" ]; then + bad "T2 provenance has no :template-repo" +elif [ -n "$SELF_SLUG" ] && [ "$T_REPO" = "$SELF_SLUG" ]; then + bad "T2 provenance names THIS repo as its own template ($T_REPO) — self-parent" + note "This is the #200/#201 class: the repo is asserting template identity." + note "A child must point at the template it came from, not at itself." +else + ok "T2 parent is external${SELF_SLUG:+ (self=$SELF_SLUG, parent=$T_REPO)}" +fi + +# ── T3: the pin is real ────────────────────────────────────────────────────── +for pair in "template-branch:$T_BRANCH" "template-commit:$T_COMMIT" "template-tree:$T_TREE"; do + key="${pair%%:*}"; val="${pair#*:}" + if [ -z "$val" ] || [ "$val" = "UNASSIGNED" ]; then + bad "T3 $key is ${val:-missing} — the parent pin is not resolvable" + note "UNASSIGNED is honest at mint time when offline, but it must be filled" + note "in before the repo is published, or drift can never be detected." + else + ok "T3 $key = $val" + fi +done + +# ── T4: branch contract (#203) ─────────────────────────────────────────────── +# The template must never leak its work branches into a child. knot-knot got a +# byte-identical copy of coderabbit/fix-hypatia-scan-failures/f36ac704 with no +# common ancestor; git proved the tree equality. +if git -C "$TARGET" rev-parse --git-dir >/dev/null 2>&1; then + DEFAULT="$(git -C "$TARGET" symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||')" + if [ -z "$DEFAULT" ]; then + for cand in main master; do + git -C "$TARGET" show-ref --verify --quiet "refs/heads/$cand" && { DEFAULT="$cand"; break; } + done + fi + + # Declared extras: the :extra-branches list of the (provenance) clause. + DECLARED="$(bash "$READ" --list "$DEED" provenance extra-branches 2>/dev/null || true)" + + UNEXPECTED="" + while IFS= read -r br; do + [ -z "$br" ] && continue + [ "$br" = "$DEFAULT" ] && continue + printf '%s\n' "$DECLARED" | grep -qxF "$br" && continue + UNEXPECTED="$UNEXPECTED $br" + done < <(git -C "$TARGET" for-each-ref --format='%(refname:short)' refs/heads/ 2>/dev/null) + + if [ -n "$UNEXPECTED" ]; then + bad "T4 branch(es) not in the mint contract:${UNEXPECTED}" + note "Declared :extra-branches: ${DECLARED:-}" + note "This is the #203 signature. A template work branch (coderabbit/," + note "chore/, bot-task) copied wholesale into a child. Review each: keep it" + note "deliberately, or delete it. Do not force unrelated histories together." + else + ok "T4 branch contract honoured (default=${DEFAULT:-?}, declared extras=${DECLARED:-none})" + fi + + # Byte-identical-tree detector: the cheapest proof of a leaked snapshot. + # If a non-default branch's tree equals an ancestor's tree exactly, it very + # likely arrived by copy rather than by work. + while IFS= read -r br; do + [ -z "$br" ] && continue + [ "$br" = "$DEFAULT" ] && continue + t="$(git -C "$TARGET" rev-parse "$br^{tree}" 2>/dev/null || true)" + p="$(git -C "$TARGET" merge-base "$br" "${DEFAULT:-HEAD}" 2>/dev/null || true)" + if [ -n "$t" ] && [ -z "$p" ]; then + warn "T4b '$br' has NO common ancestor with ${DEFAULT:-HEAD} (unrelated history)" + note "tree=$t — this is the exact knot-knot signature." + fi + done < <(git -C "$TARGET" for-each-ref --format='%(refname:short)' refs/heads/ 2>/dev/null) +else + warn "T4 skipped — not a git checkout" +fi + +# ── D1/D2: advisory drift against a template checkout ──────────────────────── +if [ -n "$TEMPLATE" ]; then + if [ ! -d "$TEMPLATE" ]; then + echo " (--template path not a directory: $TEMPLATE)"; TEMPLATE="" + elif [ ! -f "$TEMPLATE/Justfile" ]; then + echo " (--template path does not look like the template: no Justfile)"; TEMPLATE="" + fi +fi + +if [ -n "$TEMPLATE" ]; then + TEMPLATE="$(cd "$TEMPLATE" && pwd)" + echo + echo "advisory drift vs $TEMPLATE" + MISSING=0; DRIFTED=0 + + # Paths the template owns: everything it ships except what it deliberately + # drops at mint (archetypes/, build/) and the repo deed, which every repo + # names after itself and which carries the answer-file. + while IFS= read -r rel; do + case "$rel" in + archetypes/*|build/*|.git/*|*_chora.deed) continue ;; + esac + if [ ! -e "$TARGET/$rel" ]; then + MISSING=$((MISSING+1)); [ "$MISSING" -le 15 ] && echo " MISSING $rel" + elif ! cmp -s "$TEMPLATE/$rel" "$TARGET/$rel"; then + DRIFTED=$((DRIFTED+1)); [ "$DRIFTED" -le 15 ] && echo " differs $rel" + fi + done < <(cd "$TEMPLATE" && git ls-files 2>/dev/null || find . -type f | sed 's|^\./||') + + [ "$MISSING" -eq 0 ] && [ "$DRIFTED" -eq 0 ] && echo " (none — no template-owned path diverged)" + [ "$MISSING" -gt 0 ] && warn "D1 $MISSING template-owned path(s) missing from this repo" + [ "$DRIFTED" -gt 0 ] && warn "D2 $DRIFTED template-owned path(s) differ from the template" + note "Advisory only. A child is SUPPOSED to diverge — but a path that diverged" + note "once is never healed by a later template update, and copier's own 3-way" + note "merge carries such a difference forward silently, with no conflict marker." + note "Decide per path: conform it, or record why it is deliberately forked." +fi + +finish +exit $? diff --git a/scripts/check-variant-drift.sh b/scripts/check-variant-drift.sh index c8ada3c0..0b28991e 100755 --- a/scripts/check-variant-drift.sh +++ b/scripts/check-variant-drift.sh @@ -4,10 +4,11 @@ # check-variant-drift.sh — verify the shared RSR spine of this variant # template stays convergent with its parent at the pinned commit. # -# Reads the contract at .machine_readable/descriptiles/VARIANT.a2ml: +# Reads the contract from the repo deed's (variant) clause +# (_chora.deed, read with scripts/deed-field.sh): # - every tracked file NOT declared added/removed/diverged/pending/operational # must be identical to the parent's copy at parent-pin, modulo the -# [normalise] rules (action-pin SHAs, self-name substitution); +# (normalise) rules (action-pin SHAs, self-name substitution); # - declared additions must exist here and not in the parent; # - declared removals must exist in the parent and not here. # @@ -18,26 +19,40 @@ set -euo pipefail PARENT_DIR="${1:?usage: check-variant-drift.sh [self-dir]}" SELF_DIR="${2:-.}" -CONTRACT="$SELF_DIR/.machine_readable/descriptiles/VARIANT.a2ml" +READ="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/deed-field.sh" -[ -f "$CONTRACT" ] || { echo "FAIL: contract not found: $CONTRACT"; exit 1; } +# The retired VARIANT.a2ml is not read: a repo still carrying one must be +# migrated to the (variant) clause, and saying so beats guessing at it. +if [ -f "$SELF_DIR/.machine_readable/descriptiles/VARIANT.a2ml" ]; then + echo "FAIL: $SELF_DIR carries the retired VARIANT.a2ml — move its contract into the deed's (variant) clause" + exit 1 +fi +DEED=$(bash "$READ" --find "$SELF_DIR") || { echo "FAIL: no single *_chora.deed in $SELF_DIR"; exit 1; } +bash "$READ" --has "$DEED" variant || { echo "FAIL: $DEED has no (variant) clause"; exit 1; } -SELF_NAME=$(sed -n 's/^project = "\(.*\)"/\1/p' "$CONTRACT" | head -1) -PARENT_SLUG=$(sed -n 's/^parent = "\(.*\)"/\1/p' "$CONTRACT" | head -1) +SELF_NAME=$(bash "$READ" "$DEED" variant project || true) +PARENT_SLUG=$(bash "$READ" "$DEED" variant parent || true) PARENT_NAME="${PARENT_SLUG##*/}" -PIN=$(sed -n 's/^parent-pin = "\([0-9a-f]*\)".*/\1/p' "$CONTRACT" | head -1) +PIN=$(bash "$READ" "$DEED" variant parent-pin || true) +[[ "$PIN" =~ ^[0-9a-f]{40}$ ]] || PIN="" + +# A minted repo is not yet a target for this gate: the mint renders tokens and +# rewrites files, so most spine files differ from the parent by design, and the +# (normalise) rules do not fold the mint's answers (ADR-0003). repo-init no +# longer recommends arming it there. Say so before the findings, rather than +# leave a reader to "fix" ~100 expected lines by declaring them diverged; the +# verdict itself is unchanged (a gate that turns itself green is no gate). +ROLE=$(bash "$READ" "$DEED" variant role 2>/dev/null || true) +if [ "$ROLE" = "minted-repo" ]; then + echo "NOTE: $DEED records :role \"minted-repo\". Rendered files are expected to differ" + echo " from the parent until (normalise) folds the mint's answers; check the" + echo " template pin with scripts/check-template-conformance.sh instead." +fi -# Extract the paths array of one [paths.
] block. +# section_paths SECTION — the path list :SECTION of the (variant (paths …)) +# clause, one per line; nothing when the key is absent. section_paths() { - awk -v sec="[paths.$1]" ' - $0 == sec { insec = 1; next } - insec && /^\[/ { insec = 0 } - insec && /^ *"/ { - line = $0 - sub(/^ *"/, "", line); sub(/".*$/, "", line) - print line - } - ' "$CONTRACT" + bash "$READ" --list "$DEED" variant/paths "$1" 2>/dev/null || true } ADDED=$(section_paths added) @@ -46,7 +61,9 @@ SKIP=$(printf '%s\n' "$(section_paths diverged)" \ "$(section_paths diverged-pending-upstream)" \ "$(section_paths operational-state)") -in_list() { # $1 = path, $2 = newline list (entries ending in / are prefixes) +# in_list PATH LIST — 0 when PATH is in the newline-separated LIST; an entry +# ending in / matches as a directory prefix. +in_list() { local p="$1" e while IFS= read -r e; do [ -z "$e" ] && continue @@ -58,17 +75,18 @@ in_list() { # $1 = path, $2 = newline list (entries ending in / are prefixes) return 1 } -# Fold operational state out of a file before comparison: action-pin SHAs, +# normalise FILE — print FILE with operational state folded out before comparison: action-pin SHAs, # then BOTH repo names → SELF (variant name first — it does not contain the # parent name as a substring, so order is safe). Folding both names on both # sides keeps inherited files that legitimately mention the parent by name # convergent, while still matching self-identity substitutions. -normalise() { # $1 = file +normalise() { sed -E -e 's/@[0-9a-f]{40}[^ ]*( # v[^ ]*)?/@PIN/g' \ -e "s/$SELF_NAME/SELF/g" -e "s/$PARENT_NAME/SELF/g" "$1" } DRIFT=0 +# report MSG — record one drift finding and mark the run failed. report() { DRIFT=1; echo "DRIFT: $*"; } if [ -n "$PIN" ] && [ -d "$PARENT_DIR/.git" ]; then @@ -117,6 +135,6 @@ done <<< "$REMOVED" if [ "$DRIFT" -eq 0 ]; then echo "PASS: spine convergent with $PARENT_SLUG@${PIN:0:12} (modulo declared variant paths)" else - echo "FAIL: undeclared drift against $PARENT_SLUG@${PIN:0:12} — update VARIANT.a2ml or re-converge" + echo "FAIL: undeclared drift against $PARENT_SLUG@${PIN:0:12} — update the deed's (variant) clause or re-converge" exit 1 fi diff --git a/scripts/check-workflow-edges.sh b/scripts/check-workflow-edges.sh new file mode 100755 index 00000000..6ab1fa74 --- /dev/null +++ b/scripts/check-workflow-edges.sh @@ -0,0 +1,232 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# check-workflow-edges.sh — the intra-repository half of the CICD-Squabbler gate. +# +# hyperpolymath/cicd-squabbler's `chains` command follows CROSS-repository CI +# edges: a reusable workflow or action pinned at a dead commit. This repository's +# verdict grid introduced edges of the same kind INSIDE one repository, which +# squabble cannot see and which fail silently: +# +# * `.github/workflows/fork-governance.yml` is triggered by +# `workflow_run: workflows: [...]`, which matches a workflow's `name:`, not +# its file. Rename `name: Hypatia Security Scan` and the grid stops +# re-rendering — no error, no red check, just an orange row forever. +# * It reads artifacts by name (`--source :`). Rename an +# upload step's `name:` and the evidence vanishes the same way. +# * It names each scanner's pinned commit (`--hypatia-ref`, `--panic-ref`, +# `--pons-ref`) for the grid's profile hash. If the producer moves its pin +# and the reporter is not moved with it, two revisions look comparable when +# they are not. +# * One tool pinned at two different commits in two workflows is a clash, not +# a choice: whichever workflow ran last decides what the grid graded. +# +# Every check here is a rule about the pipeline's shape, not about the code +# under test, which is why it belongs beside `check-required-contexts.sh` in the +# squabble gate rather than in the manifest-janitor set. +# +# Exit contract (proven-tests-and-benches 3-outcome convention): +# 0 = every edge resolves and no tool is pinned twice +# 1 = a dead edge, an unproduced artifact, a stale pin, or a duplicate tool pin +# 2 = setup error (missing repo, workflows dir, or the reporter workflow) +# +# Deliberately NOT checked: that a producer's gate is "right". Gating is each +# producer's own decision (see the header of fork-governance.yml); this script +# only checks that the reporting edges still point at something. +set -euo pipefail + +REPO_ROOT="${1:-.}" +if [ ! -d "$REPO_ROOT" ]; then + echo "check-workflow-edges: repo directory '$REPO_ROOT' does not exist" >&2 + exit 2 +fi +WORKFLOWS_DIR="$REPO_ROOT/.github/workflows" +REPORTER="$WORKFLOWS_DIR/fork-governance.yml" +PUBLISHER="$WORKFLOWS_DIR/verdict-grid-publish.yml" + +if [ ! -d "$WORKFLOWS_DIR" ]; then + echo "check-workflow-edges: workflows directory '$WORKFLOWS_DIR' does not exist" >&2 + exit 2 +fi +if [ ! -f "$REPORTER" ]; then + echo "check-workflow-edges: reporter workflow '$REPORTER' does not exist" >&2 + exit 2 +fi +if [ ! -f "$PUBLISHER" ]; then + echo "check-workflow-edges: publisher workflow '$PUBLISHER' does not exist" >&2 + exit 2 +fi + +# ── helpers ───────────────────────────────────────────────────────────────── +errors=0 +fail() { + echo "FAIL: $*" >&2 + errors=$((errors + 1)) +} + +# workflow_name FILE — the `name:` of a workflow, or empty for `name:` absent. +# Only the FIRST top-level `name:` is read: `on: push: ...` keys and job names +# are indented, and a workflow with no `name:` is identified by its path alone. +workflow_name() { + awk ' + /^name:[[:space:]]*/ { sub(/^name:[[:space:]]*/, ""); gsub(/^["'"'"']|["'"'"']$/, ""); print; exit } + /^[^[:space:]#]/ { next } + ' "$1" +} + +# produced_artifacts FILE — every artifact name an upload-artifact step writes. +produced_artifacts() { + awk ' + /uses:[[:space:]]*actions\/upload-artifact@/ { in_upload = 1; next } + in_upload && /^[[:space:]]*- name:/ { in_upload = 0 } + in_upload && /^[[:space:]]*name:[[:space:]]/ { + sub(/^[[:space:]]*name:[[:space:]]*/, ""); gsub(/["'"'"']/, ""); print; in_upload = 0 + } + ' "$1" +} + +# env_pin FILE VAR — the value of a `VAR:` line in the workflow's env blocks. +env_pin() { + awk -v var="$2" ' + $0 ~ "^[[:space:]]*" var ":[[:space:]]" { + sub("^[[:space:]]*" var ":[[:space:]]*", ""); gsub(/["'"'"']/, ""); print; exit + } + ' "$1" +} + +# ── 1. workflow_run edges resolve to a workflow `name:` ───────────────────── +# `workflow_run: workflows:` is a YAML list under the trigger. Read it as text: +# the file is under this repository's control and a YAML parser is one more +# dependency for a check whose whole value is running where nothing else does. +edges="$(awk ' + /^on:/ { in_on = 1; next } + /^[^[:space:]#]/ { in_on = 0 } + in_on && /^[[:space:]]+workflow_run:/ { in_wr = 1; next } + in_wr && /^[[:space:]]+workflows:/ { in_list = 1; next } + in_list && /^[[:space:]]+- / { + sub(/^[[:space:]]*-[[:space:]]*/, ""); gsub(/["'"'"']/, ""); print; next + } + in_list && !/^[[:space:]]+- / { in_list = 0; in_wr = 0 } +' "$PUBLISHER")" + +if [ -z "$edges" ]; then + fail "verdict-grid-publish.yml declares no workflow_run trigger: the verdict grid would never re-render after a scanner finishes" +fi + +names_file="$(mktemp)" +trap 'rm -f "$names_file"' EXIT +for wf in "$WORKFLOWS_DIR"/*.yml "$WORKFLOWS_DIR"/*.yaml; do + [ -e "$wf" ] || continue + n="$(workflow_name "$wf")" + [ -n "$n" ] || continue + printf '%s\t%s\n' "$n" "$(basename "$wf")" >> "$names_file" +done + +while IFS= read -r edge; do + [ -n "$edge" ] || continue + if ! cut -f1 "$names_file" | grep -qxF "$edge"; then + fail "workflow_run edge '${edge}' names no workflow's name: — the grid will never re-render for it" + fi +done <<< "$edges" + +# Two files with the same `name:` means workflow_run fires for a workflow whose +# identity is ambiguous (and GitHub's UI shows two identical checks). +dupes="$(cut -f1 "$names_file" | sort | uniq -d)" +if [ -n "$dupes" ]; then + fail "two or more workflows share a name: (${dupes//$'\n'/, }) — workflow_run cannot tell them apart" +fi + +# ── 2. every evidence source is produced by the workflow it names ────────── +source_scan() { + awk '/--source[[:space:]]/ { for (i = 1; i <= NF; i++) if ($i == "--source") { print $(i + 1); break } }' "$1" +} +sources_pr="$(source_scan "$REPORTER")" +sources_pub="$(source_scan "$PUBLISHER")" +[ -n "$sources_pr" ] || fail "fork-governance.yml collects no evidence (--source :) — the grid would have no rows" +[ -n "$sources_pub" ] || fail "verdict-grid-publish.yml collects no evidence (--source :) — published grid would have no rows" +sources="$(printf '%s\n%s\n' "$sources_pr" "$sources_pub" | sed '/^$/d' | sort -u)" + +while IFS= read -r src; do + [ -n "$src" ] || continue + wf_file="${src%%:*}" + artifact="${src#*:}" + target="$WORKFLOWS_DIR/$wf_file" + if [ ! -f "$target" ]; then + fail "evidence source names '${wf_file}', which is not a workflow in .github/workflows/" + continue + fi + if ! produced_artifacts "$target" | grep -qxF "$artifact"; then + fail "evidence source '${wf_file}:${artifact}' names an artifact '${wf_file}' never uploads" + fi + if ! grep -Eq '^[[:space:]]+pull_request:' "$target"; then + fail "'${wf_file}' does not run on pull_request, so its artifact exists only after a push" + fi +done <<< "$sources" + +# ── 3. the reporter's tool pins equal the producers' pins ────────────────── +# Tool pin in the reporter (grid identity) vs the pin in the workflow that +# actually runs that tool. A mismatch makes the profile hash disagree with the +# binary that produced the findings. +check_pin() { # check_pin REPORTER REPORT_FLAG PRODUCER VAR + local report="$1" flag="$2" producer="$3" var="$4" + local in_reporter in_producer + in_reporter="$({ grep -o -- "${flag}[[:space:]]\\+[0-9a-f]\\{40\\}" "$report" || true; } | awk '{print $2}' | head -n1)" + in_producer="$(env_pin "$WORKFLOWS_DIR/$producer" "$var" | head -n1)" + if [ -z "$in_reporter" ]; then + fail "$(basename "$report") names no ${flag}; its findings would carry no tool identity" + return + fi + if [ -z "$in_producer" ]; then + fail "'${producer}' pins no ${var}, but the verdict claims ${flag} ${in_reporter:0:12}" + return + fi + if [ "$in_reporter" != "$in_producer" ]; then + fail "${flag} in $(basename "$report") (${in_reporter:0:12}) does not match ${var} in ${producer} (${in_producer:0:12})" + fi +} +for report in "$REPORTER" "$PUBLISHER"; do + check_pin "$report" --hypatia-ref hypatia-scan.yml HYPATIA_SHA + check_pin "$report" --panic-ref static-analysis-gate.yml PANIC_ATTACK_SHA + check_pin "$report" --pons-ref static-analysis-gate.yml PONS_SHA +done + +# ── 4. no tool pinned at two commits in this repository ──────────────────── +# panic-attack is pinned once for its scan and once for patch-bridge triage; the +# pair must agree, which is why both use env.PANIC_ATTACK_SHA. A literal second +# pin in another workflow is the clash this catches. +pins_file="$(mktemp)" +trap 'rm -f "$names_file" "$pins_file"' EXIT +for wf in "$WORKFLOWS_DIR"/*.yml "$WORKFLOWS_DIR"/*.yaml; do + [ -e "$wf" ] || continue + for var in HYPATIA_SHA HYPATIA_REF PANIC_ATTACK_SHA PONS_SHA; do + v="$(env_pin "$wf" "$var" | head -n1)" + [ -n "$v" ] || continue + case "$v" in + *'${{'* | 'latest' | 'HEAD') continue ;; # floating by design, documented at the pin + esac + printf '%s\t%s\t%s\n' "$var" "$v" "$(basename "$wf")" >> "$pins_file" + done +done +while IFS= read -r var; do + [ -n "$var" ] || continue + n="$(awk -F'\t' -v v="$var" '$1 == v {print $2}' "$pins_file" | sort -u | grep -c . || true)" + if [ "$n" -gt 1 ]; then + detail="$(awk -F'\t' -v v="$var" '$1 == v {printf "%s %s; ", substr($2, 1, 12), $3}' "$pins_file")" + fail "${var} is pinned at ${n} different commits in this repository (${detail%; })" + fi +done <<< "$(cut -f1 "$pins_file" | sort -u)" + +# HYPATIA_SHA and HYPATIA_REF are two spellings of the same pin. +h_sha="$(env_pin "$WORKFLOWS_DIR/hypatia-scan.yml" HYPATIA_SHA | head -n1)" +h_ref="$(env_pin "$WORKFLOWS_DIR/hypatia-scan.yml" HYPATIA_REF | head -n1)" +if [ -n "$h_sha" ] && [ -n "$h_ref" ] && [ "$h_sha" != "$h_ref" ]; then + fail "hypatia-scan.yml pins HYPATIA_SHA ${h_sha:0:12} and HYPATIA_REF ${h_ref:0:12}" +fi + +# ── verdict ──────────────────────────────────────────────────────────────── +if [ "$errors" -ne 0 ]; then + echo "check-workflow-edges: ${errors} broken edge(s)" >&2 + exit 1 +fi +echo "check-workflow-edges: all workflow edges resolve; $(printf '%s' "$edges" | grep -c . || true) workflow_run edge(s), $(printf '%s' "$sources" | grep -c . || true) evidence source(s)" diff --git a/scripts/compute-bench-baseline.sh b/scripts/compute-bench-baseline.sh new file mode 100755 index 00000000..d4bb0046 --- /dev/null +++ b/scripts/compute-bench-baseline.sh @@ -0,0 +1,118 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# Compute the benchmark baseline from proven-bench JSON v1 run files and emit +# RFC 7493 (I-JSON) + RFC 8785 (JCS) canonical JSON. +# +# Usage: scripts/compute-bench-baseline.sh ... > benches/baseline.json +# +# Exit codes: 0 baseline written to stdout; 2 no baseline could be computed. + +set -uo pipefail + +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" || { echo "FAIL: cannot locate script directory" >&2; exit 2; } +MIN_RUNS=10 + +# die MESSAGE... — abort baseline generation with exit status 2. +die() { + echo "compute-bench-baseline: $*" >&2 + echo "compute-bench-baseline: NO BASELINE WRITTEN." >&2 + exit 2 +} + +# run_id_of FILE — print the parent directory's name if it contains only digits; +# print nothing otherwise. +run_id_of() { + local parent + parent="$(basename "$(dirname "$1")")" + if [[ "$parent" =~ ^[0-9]+$ ]]; then + printf '%s' "$parent" + fi +} + +# validate_run FILE — require exactly one proven-bench v1 document, exiting 2 on +# missing, unparseable, or malformed input. Historical checksums are not validated. +validate_run() { + local f="$1" errs + [ -f "$f" ] || die "run file '$f' does not exist" + if ! errs="$(jq -L "$SCRIPT_DIR" -sr 'include "bench-stats"; + if length != 1 then ["expected exactly one benchmark document"] + else .[0] | bench_errors end | .[]' "$f")"; then + die "run file '$f' is not parseable JSON" + fi + if [ -n "$errs" ]; then + printf '%s\n' "$errs" | sed "s|^| $f: |" >&2 + die "run file '$f' is not a well-formed proven-bench v1 document" + fi +} + +[ "$#" -ge 1 ] || die "usage: $0 ... (at least $MIN_RUNS)" +if [ "$#" -lt "$MIN_RUNS" ]; then + die "BASELINE BOOTSTRAPPING: $#/$MIN_RUNS runs - the gate would be INERT; supply at least $MIN_RUNS" +fi + +declare -A SEEN_PATHS=() +declare -A SEEN_RUN_IDS=() +ids_json='[]' +for f in "$@"; do + validate_run "$f" + canon_path="$(realpath "$f" 2>/dev/null || printf '%s' "$f")" + if [ -n "${SEEN_PATHS[$canon_path]:-}" ]; then + die "duplicate source run file '$f' - supply $MIN_RUNS distinct runs" + fi + SEEN_PATHS["$canon_path"]=1 + + rid="$(run_id_of "$f")" + if [ -n "$rid" ]; then + if [ -n "${SEEN_RUN_IDS[$rid]:-}" ]; then + die "duplicate source run_id '$rid' - supply $MIN_RUNS distinct runs" + fi + SEEN_RUN_IDS["$rid"]=1 + fi + + ids_json="$(jq -c --arg id "$rid" '. + [ if $id == "" then null else $id end ]' <<<"$ids_json")" \ + || die "could not record provenance for '$f'" +done + +if ! jq -L "$SCRIPT_DIR" -s -e 'include "bench-stats"; + (map(iterations_map) | unique | length) == 1' "$@" >/dev/null; then + die "the run files disagree on the workload set or iteration counts - they measure different experiments" +fi + +RAW_JSON="$(jq -L "$SCRIPT_DIR" -cS -s --argjson ids "$ids_json" ' + include "bench-stats"; + (if length != ($ids | length) then error("expected one benchmark document per source file") else . end) as $runs + | ($runs[0] | iterations_map) as $iters + | ($runs | map(loo_ratios)) as $loo + | ($runs | map(medians)) as $med + | { + schema_version: 1, + kind: "proven-bench-baseline", + bench_schema_version: 1, + statistic: "leave-one-out ratio: a workload median divided by the geometric mean of the other workloads medians in the same run", + method: "arithmetic mean over the source runs (taxonomy: mean of the last 10 CI runs on main)", + note: "Manual tolerance override (taxonomy Part IV permits one with a stated reason): the checker fails at 2.0x the baseline ratio or 2.5x the baseline absolute median, not the taxonomy 1.5x, because 1.5x would have failed green runs on shared GitHub runners (max observed ratio 1.53x, absolute 1.65x). Measured numbers are in benchmarks/README.adoc and scripts/check-bench-regression.sh.", + window: ($runs | length), + sources: [ range(0; $runs | length) as $i + | { run_id: $ids[$i], commit: $runs[$i].commit } ], + workloads: ( $iters | keys | map({ + key: ., + value: { + iterations: $iters[.], + mean_median_ns: ([ $med[][.] ] | add / length), + mean_loo_ratio: ([ $loo[][.] ] | add / length) + } }) | from_entries ) + } +' "$@")" || die "jq failed while computing the baseline" + +if command -v ijson-jcs >/dev/null 2>&1; then + printf '%s' "$RAW_JSON" | ijson-jcs canon || die "ijson-jcs failed to canonicalize baseline" + printf '\n' +elif command -v bun >/dev/null 2>&1 && [ -f "$SCRIPT_DIR/ijson-jcs-cli.js" ]; then + printf '%s' "$RAW_JSON" | bun "$SCRIPT_DIR/ijson-jcs-cli.js" canon || die "ijson-jcs-cli.js failed to canonicalize baseline" + printf '\n' +else + die "neither ijson-jcs nor bun is available to canonicalize baseline" +fi diff --git a/scripts/deed-clause.sh b/scripts/deed-clause.sh new file mode 100755 index 00000000..3d9895f9 --- /dev/null +++ b/scripts/deed-clause.sh @@ -0,0 +1,160 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# deed-clause.sh — the one WRITER for a deed's clauses (scripts/deed-field.sh is +# the reader). Every recipe that changes a deed at mint or setup time — the +# child's (rsr-profile) / (variant) / (provenance) clauses, groove-setup's port +# and API-surface flags — goes through here, so an edit is scoped to one clause +# and never a sed over the whole file. +# +# Usage: +# deed-clause.sh get DEED PATH print the clause's source text +# deed-clause.sh replace DEED PATH FILE|- replace the clause with FILE's text +# (FILE carries its own indentation) +# deed-clause.sh append DEED PATH FILE|- add FILE's text as the clause's last child +# deed-clause.sh set DEED PATH KEY VALUE replace the value of top-level :KEY +# +# PATH is slash-separated below the document root, exactly as deed-field.sh +# takes it; an empty PATH is the root form itself (append only). The root is +# the first form headed by an ABNF doc-head: repo-deed, praxis-deed, +# estate-deed or estate-atlas-deed. +# +# A clause's leading comments — the comment-only lines directly above its +# opening line, with no blank line between — belong to it: `get` prints them +# and `replace` swaps them out together with the clause, so rationale written +# for the template does not survive into a replacement. +# +# VALUE for `set` is a deed literal written as it appears in the file: a +# string with its quotes ("x"), an integer, #t / #f, or a bare symbol. It +# replaces a scalar value only; a list value is refused. +# +# Writes are atomic (temp file + mv) and the result is re-read with +# deed-field.sh before it replaces the deed: a write that leaves the form +# unreadable fails and leaves the deed untouched. +# +# Exit: 0 done; 1 clause or key absent; 2 usage error, unreadable deed or a +# result that does not re-read. +set -euo pipefail + +here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +op="${1:-}"; deed="${2:-}"; path="${3-}" +# usage — print the Usage block above to stderr and exit 2. +usage() { sed -n '12,17p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//' >&2; exit 2; } +case "$op" in get|replace|append|set) ;; *) usage ;; esac +[ -n "$deed" ] && [ -r "$deed" ] || { echo "deed-clause.sh: no readable deed: '$deed'" >&2; exit 2; } +key=""; value=""; text="" +case "$op" in + replace|append) + src="${4:-}"; [ -n "$src" ] || usage + if [ "$src" = - ]; then text="$(cat)"; else text="$(cat "$src")"; fi ;; + set) + key="${4:-}"; value="${5-}" + [ -n "$key" ] && [ -n "$value" ] || usage + lit='^("([^"\\]|\\["\\nt])*"|#[tf]|-?[0-9]+|[A-Za-z][^ ()";]*)$' + [[ "$value" =~ $lit ]] || { echo "deed-clause.sh: not a deed scalar literal: $value" >&2; exit 2; } ;; +esac +[ "$op" = append ] || [ -n "$path" ] || { echo "deed-clause.sh: $op needs a clause PATH" >&2; exit 2; } + +# edit_deed -> the edited deed on stdout; exit 1 when PATH or KEY is absent +edit_deed() { +DC_TEXT="$text" DC_VALUE="$value" LC_ALL=C awk -v op="$op" -v path="$path" -v key="$key" ' +BEGIN { RS = "\001"; text = ENVIRON["DC_TEXT"]; value = ENVIRON["DC_VALUE"] } +{ + s = $0; n = length(s); i = 1; nt = 0 + while (i <= n) { + c = substr(s, i, 1) + if (c == ";") { while (i <= n && substr(s, i, 1) != "\n") i++; continue } + if (c == "(" || c == ")") { nt++; tok[nt] = c; b[nt] = i; f[nt] = i; i++; continue } + if (c == "\"") { + st = i; i++ + while (i <= n) { c = substr(s, i, 1); if (c == "\\") { i += 2; continue }; if (c == "\"") break; i++ } + nt++; tok[nt] = "S"; b[nt] = st; f[nt] = i; i++; continue + } + if (c == " " || c == "\t" || c == "\r" || c == "\n") { i++; continue } + st = i; v = "" + while (i <= n) { + c = substr(s, i, 1) + if (c == " " || c == "\t" || c == "\r" || c == "\n" || c == "(" || c == ")" || c == "\"" || c == ";") break + v = v c; i++ + } + nt++; tok[nt] = "A" v; b[nt] = st; f[nt] = i - 1 + } +} +# close_of(o) — token index of the ")" that closes the form opened at token o; 0 if unbalanced. +function close_of(o, d, t) { + d = 0 + for (t = o; t <= nt; t++) { + if (tok[t] == "(") d++ + else if (tok[t] == ")") { d--; if (d == 0) return t } + } + return 0 +} +# child(o, name) — token index of the direct child form (name …) of the form at o; 0 if absent. +function child(o, name, e, t, d) { + e = close_of(o); d = 0 + for (t = o + 1; t < e; t++) { + if (tok[t] == "(") { if (d == 0 && tok[t + 1] == "A" name) return t; d++ } + else if (tok[t] == ")") d-- + } + return 0 +} +# Start offset of the clause opening at byte p: its line start when "(" begins +# its own line, widened over the leading comment-only lines directly above. +function lead(p, ls, q, prev) { + ls = p + while (ls > 1 && substr(s, ls - 1, 1) != "\n") ls-- + if (substr(s, ls, p - ls) !~ /^[ ]*$/) return p + while (ls > 1) { + q = ls - 1; prev = q + while (prev > 1 && substr(s, prev - 1, 1) != "\n") prev-- + if (substr(s, prev, q - prev) ~ /^[ ]*;/) ls = prev; else break + } + return ls +} +END { + o = 0 + for (t = 1; t <= nt; t++) + if (tok[t] == "(" && tok[t + 1] ~ /^A(repo-deed|praxis-deed|estate-deed|estate-atlas-deed)$/) { o = t; break } + if (!o) exit 2 + if (path != "") { + np = split(path, part, "/") + for (p = 1; p <= np; p++) { o = child(o, part[p]); if (!o) exit 1 } + } + e = close_of(o); if (!e) exit 2 + if (op == "get") { st = lead(b[o]); printf "%s\n", substr(s, st, b[e] - st + 1); exit 0 } + if (op == "replace") { + st = lead(b[o]) + printf "%s%s%s", substr(s, 1, st - 1), text, substr(s, b[e] + 1); exit 0 + } + if (op == "append") { + # A closing ")" on its own line: the new child goes on the line above it. + ls = b[e]; while (ls > 1 && substr(s, ls - 1, 1) != "\n") ls-- + if (substr(s, ls, b[e] - ls) ~ /^[ ]*$/) printf "%s%s\n%s", substr(s, 1, ls - 1), text, substr(s, ls) + else printf "%s\n%s%s", substr(s, 1, b[e] - 1), text, substr(s, b[e]) + exit 0 + } + d = 0 + for (t = o + 1; t < e; t++) { + if (tok[t] == "(") { d++; continue } + if (tok[t] == ")") { d--; continue } + if (d != 0 || tok[t] != "A:" key) continue + if (tok[t + 1] == "(" || tok[t + 1] == ")") exit 1 + printf "%s%s%s", substr(s, 1, b[t + 1] - 1), value, substr(s, f[t + 1] + 1); exit 0 + } + exit 1 +} +' "$deed" +} + +if [ "$op" = get ]; then edit_deed; exit $?; fi +tmp="$(mktemp "${deed}.XXXXXX")" +trap 'rm -f "$tmp"' EXIT +rc=0; edit_deed > "$tmp" || rc=$? +[ "$rc" -eq 0 ] || exit "$rc" +# The result must still read as one balanced form with the same root. +bash "$here/deed-field.sh" --has "$tmp" "" \ + || { echo "deed-clause.sh: $op left $(basename "$deed") unreadable; not written" >&2; exit 2; } +chmod --reference="$deed" "$tmp" 2>/dev/null || true +mv "$tmp" "$deed" +trap - EXIT diff --git a/scripts/deed-field.sh b/scripts/deed-field.sh new file mode 100755 index 00000000..57d27c19 --- /dev/null +++ b/scripts/deed-field.sh @@ -0,0 +1,188 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# deed-field.sh — read one field out of a deed (_chora.deed, or any +# *_praxis.deed: the root is the first form with an ABNF doc-head). +# +# The repo deed holds what the descriptiles CLADE / META / ECOSYSTEM / STATE / +# AGENTIC .a2ml files used to hold (rsr-template-repo#209). This is the one +# shell reader for it, so that every gate, extractor and recipe asks the same +# question the same way. It is a READER: it never writes the deed. +# +# Usage: +# deed-field.sh DEED PATH KEY first value of :KEY in the clause at PATH +# deed-field.sh --list DEED PATH KEY the items of the list :KEY ( … ), one per line +# deed-field.sh --clause DEED PATH the clause, one token per line (for hashing) +# deed-field.sh --has DEED PATH exit 0 iff the clause exists +# deed-field.sh --find [DIR] print the one *_chora.deed in DIR (default .) +# deed-field.sh --uuid DEED the repo uuid, derived from :repo-uuid +# +# PATH names clauses below (repo-deed …), slash-separated: `status`, +# `agentic/integrity`, `meta/maintenance-axes`. An empty PATH is (repo-deed …) +# itself, so `deed-field.sh DEED "" canonical-name` reads the header. +# +# KEY is matched only at the top level of that clause, never inside a nested +# clause: `status` :phase is the clause's own phase, not a (history (entry …)) +# phase. Comments (`;` to end of line, outside strings) are ignored, layout is +# irrelevant, string escapes \" \\ \n \t are decoded, and the booleans #t / #f +# print as true / false, because every caller is a shell test. A tagged +# literal prints its string: `:repo-uuid #u5"github.com/o/r"` gives +# github.com/o/r, the uuid5 name (uuidgen --sha1 --namespace @url --name …). +# +# --uuid derives the uuid5 (RFC 9562, URL namespace) of the header :repo-uuid +# name. It uses uuidgen when that supports --sha1, else bun, and exits 2 when +# neither is available or the result is not uuid-shaped: it never guesses. +# +# Exit: 0 found; 1 clause or key absent (nothing printed); 2 usage error or no +# readable deed. --find exits 1 unless exactly one deed is present. +set -euo pipefail + +mode=value +case "${1:-}" in + --list|--clause|--has|--uuid) mode="${1#--}"; shift ;; + --find) + shopt -s nullglob + deeds=("${2:-.}"/*_chora.deed) + [ "${#deeds[@]}" -eq 1 ] || exit 1 + printf '%s\n' "${deeds[0]}" + exit 0 ;; +esac + +deed="${1:-}"; path="${2-}"; key="${3:-}" +[ "$mode" != uuid ] || { path=""; key=repo-uuid; } +if [ -z "$deed" ] || [ ! -r "$deed" ]; then + echo "deed-field.sh: no readable deed: '${deed}'" >&2; exit 2 +fi +if { [ "$mode" = value ] || [ "$mode" = list ]; } && [ -z "$key" ]; then + echo "deed-field.sh: KEY is required" >&2; exit 2 +fi + +# read_deed MODE -> run the clause reader over $deed for $path / $key +read_deed() { +awk -v mode="$1" -v path="$path" -v key="$key" ' +BEGIN { RS = "\001" } +{ + # Tokenise: "(" ")" , S , A. Comments are dropped here. + s = $0; n = length(s); i = 1; nt = 0 + while (i <= n) { + c = substr(s, i, 1) + if (c == ";") { while (i <= n && substr(s, i, 1) != "\n") i++; continue } + if (c == "(" || c == ")") { tok[++nt] = c; i++; continue } + if (c == "\"") { + v = ""; i++ + while (i <= n) { + c = substr(s, i, 1) + if (c == "\\") { + d = substr(s, i + 1, 1) + if (d == "n") v = v "\n"; else if (d == "t") v = v "\t"; else v = v d + i += 2; continue + } + if (c == "\"") break + v = v c; i++ + } + i++; tok[++nt] = "S" v; continue + } + if (c == " " || c == "\t" || c == "\r" || c == "\n") { i++; continue } + v = "" + while (i <= n) { + c = substr(s, i, 1) + if (c == " " || c == "\t" || c == "\r" || c == "\n" || c == "(" || c == ")" || c == "\"" || c == ";") break + v = v c; i++ + } + tok[++nt] = "A" v + } +} +# Index of the ")" token that closes the clause opening at token o, or 0. +function close_of(o, d, t) { + d = 0 + for (t = o; t <= nt; t++) { + if (tok[t] == "(") d++ + else if (tok[t] == ")") { d--; if (d == 0) return t } + } + return 0 +} +# First direct child clause of the clause opening at o whose head is name. +function child(o, name, e, t, d) { + e = close_of(o); d = 0 + for (t = o + 1; t < e; t++) { + if (tok[t] == "(") { if (d == 0 && tok[t + 1] == "A" name) return t; d++ } + else if (tok[t] == ")") d-- + } + return 0 +} +# A value token rendered for output: the type tag dropped, #t/#f as true/false. +function show(x) { + x = substr(x, 2) + if (x == "#t") return "true" + if (x == "#f") return "false" + return x +} +END { + o = 0 + for (t = 1; t <= nt; t++) + if (tok[t] == "(" && tok[t + 1] ~ /^A(repo-deed|praxis-deed|estate-deed|estate-atlas-deed)$/) { o = t; break } + if (!o) exit 1 + if (path != "") { + np = split(path, part, "/") + for (p = 1; p <= np; p++) { o = child(o, part[p]); if (!o) exit 1 } + } + e = close_of(o) + if (!e) exit 2 + if (mode == "has") exit 0 + if (mode == "clause") { for (t = o; t <= e; t++) print tok[t]; exit 0 } + d = 0 + for (t = o + 1; t < e; t++) { + if (tok[t] == "(") { d++; continue } + if (tok[t] == ")") { d--; continue } + if (d != 0 || tok[t] != "A:" key) continue + nx = tok[t + 1] + if (mode == "value") { + if (nx == "(" || nx == ")" || nx == "") exit 1 + # A tagged literal such as #u5"github.com/o/r" prints its string. + if (nx ~ /^A#[a-z0-9]+$/ && substr(tok[t + 2], 1, 1) == "S") nx = tok[t + 2] + print show(nx); exit 0 + } + if (nx != "(") exit 1 + le = close_of(t + 1); ld = 0 + for (u = t + 2; u < le; u++) { + if (tok[u] == "(") ld++ + else if (tok[u] == ")") ld-- + else if (ld == 0) print show(tok[u]) + } + exit 0 + } + exit 1 +} +' "$deed" +} + +# uuid5_url NAME -> the uuid5 of NAME in the RFC 9562 URL namespace +uuid5_url() { + if uuidgen --sha1 --namespace @url --name x >/dev/null 2>&1; then + uuidgen --sha1 --namespace @url --name "$1" + elif command -v bun >/dev/null 2>&1; then + bun -e ' + const h = new Bun.CryptoHasher("sha1"); + h.update(Buffer.from("6ba7b8119dad11d180b400c04fd430c8", "hex")); + h.update(process.argv[1]); + const b = h.digest().subarray(0, 16); + b[6] = (b[6] & 0x0f) | 0x50; + b[8] = (b[8] & 0x3f) | 0x80; + const x = b.toString("hex"); + console.log([x.slice(0, 8), x.slice(8, 12), x.slice(12, 16), x.slice(16, 20), x.slice(20)].join("-")); + ' "$1" + else + echo "deed-field.sh: --uuid needs uuidgen with --sha1, or bun" >&2; return 2 + fi +} + +if [ "$mode" = uuid ]; then + name="$(read_deed value)" || exit $? + id="$(uuid5_url "$name")" || exit 2 + [[ "$id" =~ ^[0-9a-f]{8}-[0-9a-f]{4}-5[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ ]] \ + || { echo "deed-field.sh: derived uuid is not uuid5-shaped: '$id'" >&2; exit 2; } + printf '%s\n' "$id" + exit 0 +fi +read_deed "$mode" diff --git a/scripts/emit-aggregate-inputs.sh b/scripts/emit-aggregate-inputs.sh new file mode 100755 index 00000000..f44be80b --- /dev/null +++ b/scripts/emit-aggregate-inputs.sh @@ -0,0 +1,91 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# Feed the proof-ladder files cited by Actually-Proven tests (from the JSON run +# report) into panic-attack's `aggregate`, which classifies each proof artifact +# (Closed/Holes/Refuted/Indeterminate) and folds it into a trust-tagged report. +# +# Exit contract (proven-tests-and-benches 3-outcome convention): +# 0 = all Actually-Proven ladder files classified Closed (or 0 Actually-Proven +# entries in a valid report) +# 1 = panic-attack aggregate reported a non-Closed verdict (Holes / Refuted) +# 2 = setup error: missing/unparseable report, missing jq, or missing +# panic-attack binary when Actually-Proven files require aggregation +# +# Usage: emit-aggregate-inputs.sh [panic-attack-binary] +set -euo pipefail + +REPORT="${1:-build/report/proven-tests-report.json}" +PANIC_ATTACK="${2:-panic-attack}" + +if [ ! -f "$REPORT" ]; then + echo "error: run report not found: $REPORT" >&2 + echo " run: ./build/exec/proven-tests --report $REPORT" >&2 + exit 2 +fi + +if ! command -v jq >/dev/null 2>&1; then + echo "error: jq is required to filter Actually-Proven entries in $REPORT" >&2 + exit 2 +fi + +WORK_DIR="$(mktemp -d)" +EXTRACT_TMP="$WORK_DIR/files" +trap 'rm -rf "$WORK_DIR"' EXIT +if ! jq -er ' + if (type != "object") or (.entries | type != "array") then + error("report must be an object with an entries array") + else + [ .entries[] + | select(.provenance == "Actually-Proven") + | (.proof_ladder // [])[] + | .proof_file + | select(type == "string" and length > 0) + ] | unique | .[] + end +' "$REPORT" > "$EXTRACT_TMP" 2>/dev/null; then + # Note: `jq -e` exits 4 when output is empty (`unique | .[]` produces zero + # items); distinguish malformed JSON/schema from a valid empty selection. + if ! jq -e 'type == "object" and (.entries | type == "array")' "$REPORT" >/dev/null 2>&1; then + echo "error: malformed or invalid run report: $REPORT" >&2 + exit 2 + fi + : > "$EXTRACT_TMP" +fi + +mapfile -t LADDER_FILES < "$EXTRACT_TMP" + +if [ "${#LADDER_FILES[@]}" -eq 0 ]; then + echo "no Actually-Proven proof-ladder files cited in $REPORT — nothing to aggregate" + exit 0 +fi + +echo "Actually-Proven proof-ladder files to aggregate:" +printf ' %s\n' "${LADDER_FILES[@]}" + +if ! command -v "$PANIC_ATTACK" >/dev/null 2>&1; then + echo "error: '$PANIC_ATTACK' not on PATH — cannot classify ${#LADDER_FILES[@]} Actually-Proven proof file(s)" >&2 + exit 2 +fi + +status=0 +idx=0 +for f in "${LADDER_FILES[@]}"; do + idx=$((idx + 1)) + output="$WORK_DIR/$idx.json" + label="$(basename "$f" .idr)-ladder" + echo "--- aggregate: $f (label=$label) ---" + if ! "$PANIC_ATTACK" aggregate --proof "$f" --label "$f=$label" --output "$output"; then + echo "error: aggregate failed for $f" >&2 + status=1 + elif ! jq -e ' + (.aggregated_proofs | type == "array" and length > 0) + and all(.aggregated_proofs[]; .verdict == "closed") + ' "$output" >/dev/null 2>&1; then + echo "error: aggregate reported a non-Closed verdict for $f" >&2 + status=1 + fi +done +exit "$status" diff --git a/scripts/gen-repo-map.sh b/scripts/gen-repo-map.sh index a9cdb64f..befe940f 100755 --- a/scripts/gen-repo-map.sh +++ b/scripts/gen-repo-map.sh @@ -13,7 +13,15 @@ # was a second whole-repo README contradicting the first. They rotted because # nothing checked them. A map that is regenerated and diffed in CI cannot. # -# Usage: bash scripts/gen-repo-map.sh [repo_root] +# Usage: bash scripts/gen-repo-map.sh [--worktree] [repo_root] +# +# --worktree maps the files `git add -A` would commit (tracked or untracked, +# not ignored, still on disk) instead of the index. `just repo-init` needs it: +# the mint runs before the child's first commit, so the index still lists +# what the mint removed (archetypes/, the template's deed name) and lacks what +# it created. Generated from the index there, the map was stale from birth, and +# Estate Rules failed at its freshness step on every run of lintel until +# lintel#8 regenerated it. On a committed tree the two modes agree. set -euo pipefail # Byte order, everywhere. `sort` is LOCALE-DEPENDENT: under en_US.UTF-8 it @@ -25,16 +33,29 @@ set -euo pipefail # locale, which is what tests/shape/repo_map_determinism_test.sh now does. export LC_ALL=C +MODE=index +if [ "${1:-}" = "--worktree" ]; then MODE=worktree; shift; fi REPO_ROOT="${1:-.}" cd "$REPO_ROOT" ALLOW=".machine_readable/root-allow.txt" OUT="docs/architecture/REPOSITORY-MAP.adoc" +# repo_files [PATH] — the files this map describes, under PATH when given. +repo_files() { + if [ "$MODE" = worktree ]; then + git ls-files -z --cached --others --exclude-standard -- "$@" \ + | while IFS= read -r -d '' f; do [ -e "$f" ] || [ -L "$f" ] && printf '%s\n' "$f"; done \ + | sort -u + else + git ls-files -- "$@" + fi +} + [ -f "$ALLOW" ] || { echo "ERROR: $ALLOW not found" >&2; exit 2; } mkdir -p "$(dirname "$OUT")" # Root entries, tracked shape only (mirrors check-root-shape.sh). -mapfile -t ENTRIES < <(git ls-files | awk -F/ '{print $1}' | sort -u) +mapfile -t ENTRIES < <(repo_files | awk -F/ '{print $1}' | sort -u) # name -> annotation, harvested from the allowlist's own comments. declare -A NOTE=() OPTIONAL=() @@ -60,7 +81,7 @@ done < "$ALLOW" # these counts were folded into the repo deed — standards#837 pilot.) declared_only() { local d="$1" n - n=$(git ls-files "$d" | awk -F/ '{print $NF}' \ + n=$(repo_files "$d" | awk -F/ '{print $NF}' \ | grep -vxE 'README\.adoc|\.gitkeep' | wc -l) [ "$n" -eq 0 ] } @@ -106,7 +127,7 @@ declared_only() { echo "your own repo - but do not read their emptiness as neglect here." echo first=1 - for d in $(git ls-files | grep '/' | sed 's|/[^/]*$||' | sort -u); do + for d in $(repo_files | grep '/' | sed 's|/[^/]*$||' | sort -u); do if declared_only "$d"; then [ $first -eq 1 ] && { echo "[cols=\"1\"]"; echo '|==='; first=0; } echo "| \`$d/\`" diff --git a/scripts/governance-badge.js b/scripts/governance-badge.js new file mode 100644 index 00000000..865aa885 --- /dev/null +++ b/scripts/governance-badge.js @@ -0,0 +1,1030 @@ +#!/usr/bin/env bun +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +// +// governance-badge.js - render and publish the estate's per-lane Shields +// endpoint badges. +// +// WHAT THIS OWNS +// +// Every RSR repo publishes one small JSON file per validation lane on a +// generated ORPHAN branch called `governance-badges`: +// +// badges/k9.json <- written by .github/workflows/dogfood-gate.yml +// +// README badges read those files straight from raw.githubusercontent.com, so +// the files are a public interface with a stable URL. This script is the only +// thing in the template that renders or publishes them; before it existed the +// mapping lived in inline `jq` in the workflow (and mapped `skipped` to RED), +// and publication lived in inline `gh api` shell that never compared bytes and +// treated EVERY API error as "branch missing". +// +// THE THREE INVARIANTS +// +// 1. Never a false green. Only a lane result of `success` may render +// brightgreen, and only when that lane's artifact is present, valid and +// byte-identical to what this script renders for `success`. +// 2. Byte equality, not "looks the same". An unchanged badge produces NO +// commit. Comparison is on exact bytes: the file is never re-serialised, +// re-ordered or canonicalised to make a comparison succeed. +// 3. Fail closed, and say which failure it was. A 404 means "missing"; a +// 401/403/429/5xx or a network error means "we do not know" and the run +// fails without writing anything. Only a 404 on both the file and the +// branch is allowed to create a branch. +// +// STATE MAPPING (total; every value lands in the table) +// +// lane result badge message badge colour +// --------------- -------------- ------------ +// success success brightgreen +// failure failure red +// skipped skipped lightgrey +// cancelled cancelled lightgrey +// unavailable unavailable lightgrey (lane evidence unusable) +// anything else unknown lightgrey (e.g. timed_out, neutral) +// +// A lightgrey badge means "this run did not produce a trustworthy +// success/failure result". It is deliberately NOT "green with stale data". +// +// USAGE +// +// governance-badge.js render --label K9 --state success [--out FILE] +// governance-badge.js publish --label K9 +// --lane-result .result> +// --artifact +// --branch governance-badges +// --path badges/k9.json +// [--repo owner/name] [--source-sha SHA] +// [--commit-message TEXT] +// [--api-url URL] [--token TOKEN] +// +// --repo defaults to GITHUB_REPOSITORY, --token to GITHUB_TOKEN/GH_TOKEN, +// --api-url to GITHUB_API_URL (set by Actions), else https://api.github.com. +// GOVERNANCE_BADGE_REQUEST_TIMEOUT_MS bounds each request, including reading +// its response body (default 30000 ms; positive integer up to 2147483647). +// +// EXIT CODES +// +// 0 published, or byte-identical so no commit was made +// 1 refused or failed: nothing was written, or the outcome is unknown +// (API/auth/network failure, malformed existing file, branch guard) +// 2 usage or configuration error (bad flag, missing token, unsafe branch) +// 3 a GREY badge was published because the lane's evidence was missing or +// malformed - the badge is honest, but the run must be looked at +// +// Runtime: Bun (estate first choice) or Node >= 18. Plain CommonJS and only +// node: builtins, so both run it unchanged; no dependencies, no third-party +// action is needed to use it. + +"use strict"; + +const { existsSync, readFileSync, statSync, writeFileSync, appendFileSync } = require("node:fs"); + +// --------------------------------------------------------------------------- +// Exit codes +// --------------------------------------------------------------------------- + +const EXIT_OK = 0; +const EXIT_REFUSED = 1; +const EXIT_USAGE = 2; +const EXIT_GREY_FAULT = 3; + +// --------------------------------------------------------------------------- +// The single state -> badge table +// --------------------------------------------------------------------------- + +const STATE_TABLE = Object.freeze({ + success: { message: "success", color: "brightgreen" }, + failure: { message: "failure", color: "red" }, + skipped: { message: "skipped", color: "lightgrey" }, + cancelled: { message: "cancelled", color: "lightgrey" }, + unavailable: { message: "unavailable", color: "lightgrey" }, + unknown: { message: "unknown", color: "lightgrey" }, +}); + +const MESSAGES = new Set(Object.values(STATE_TABLE).map((s) => s.message)); + +// oneLine - anything that reaches a log line is flattened first. The step log +// is evidence, and a value that comes from an argument, an artifact path or an +// API response must not be able to forge a line in it or to terminate a +// `::error::` workflow command early. +function oneLine(value) { + return String(value).replace(/[\r\n\u0000-\u001f\u007f]/g, " "); +} + +// normaliseState - anything not in the table becomes `unknown`, never success. +function normaliseState(raw) { + const key = String(raw === undefined || raw === null ? "" : raw).trim().toLowerCase(); + return Object.hasOwn(STATE_TABLE, key) ? key : "unknown"; +} + +// renderBadge - the canonical bytes. Key order and spacing are fixed here and +// nowhere else, so "did this change?" is a byte comparison. The trailing +// newline matches what the previous jq renderer emitted, which keeps the +// first run after an upgrade a no-op whenever the state has not changed. +function renderBadge(label, state) { + const entry = STATE_TABLE[normaliseState(state)]; + return ( + `{"schemaVersion":1,"label":${JSON.stringify(label)},` + + `"message":${JSON.stringify(entry.message)},` + + `"color":${JSON.stringify(entry.color)}}\n` + ); +} + +// inspectBadge - is this text a shield-endpoint object? +// +// pairing: "strict" message must be one of STATE_TABLE's, with exactly the +// colour this table pairs it with. Used for the lane +// artifact, which this script renders: anything else has +// been tampered with or came from a different renderer. +// pairing: "loose" a structurally valid shield badge of any shape (any +// non-empty message/colour). Used for the file already on +// the branch, which may predate this helper - e.g. the old +// inline jq wrote `skipped` in RED. Such a file is valid- +// but-different, so it is replaced rather than refused. +// +// Returns { ok, badge, errors }; never throws on bad input. +function inspectBadge(text, label, { pairing = "strict" } = {}) { + const errors = []; + let badge; + try { + badge = JSON.parse(text); + } catch (err) { + return { ok: false, badge: null, errors: [`not valid JSON (${err.message})`] }; + } + if (badge === null || typeof badge !== "object" || Array.isArray(badge)) { + return { ok: false, badge: null, errors: ["not a JSON object"] }; + } + if (badge.schemaVersion !== 1) { + errors.push(`schemaVersion is ${JSON.stringify(badge.schemaVersion)}, expected 1`); + } + if (label !== undefined && badge.label !== label) { + errors.push(`label is ${JSON.stringify(badge.label)}, expected ${JSON.stringify(label)}`); + } + if (typeof badge.message !== "string" || badge.message.length === 0) { + errors.push("message is missing or not a non-empty string"); + } else if (typeof badge.color !== "string" || badge.color.length === 0) { + errors.push("color is missing or not a non-empty string"); + } else if (pairing === "strict" && !MESSAGES.has(badge.message)) { + errors.push( + `message ${JSON.stringify(badge.message)} is not one of ${[...MESSAGES].join(", ")}`, + ); + } else if (pairing === "strict" && badge.color !== STATE_TABLE[badge.message].color) { + errors.push( + `message ${JSON.stringify(badge.message)} pairs with colour ` + + `${JSON.stringify(STATE_TABLE[badge.message].color)}, not ${JSON.stringify(badge.color)}`, + ); + } + return { ok: errors.length === 0, badge, errors }; +} + +// --------------------------------------------------------------------------- +// Errors +// --------------------------------------------------------------------------- + +class UsageError extends Error {} + +class RefusedError extends Error {} + +class ApiError extends Error { + /** Record an HTTP status (0 when unavailable) and a failure classification. */ + constructor(message, { status = 0, kind = "unexpected" } = {}) { + super(message); + this.status = status; + this.kind = kind; + } + + /** Whether this is a network or transient API failure eligible for retry. */ + get transient() { + return this.kind === "transient" || this.kind === "network"; + } +} + +/** + * Classify 401/403 as auth, 404 as missing, 409/422 as conflict, and 429/5xx + * as transient; all other statuses, including successful ones, are unexpected. + */ +function classifyStatus(status) { + if (status === 401 || status === 403) return "auth"; + if (status === 404) return "missing"; + if (status === 409 || status === 422) return "conflict"; + if (status === 429 || (status >= 500 && status <= 599)) return "transient"; + return "unexpected"; +} + +const KIND_ADVICE = { + auth: "the token cannot read/write this repository (401/403) - check the job's permissions", + missing: "the API reported the resource as missing (404)", + conflict: "the ref or file moved under us (409/422)", + transient: "the GitHub API is failing or rate-limiting (429/5xx)", + network: "the GitHub API could not be reached", + unexpected: "the GitHub API returned an unexpected response", +}; + +// --------------------------------------------------------------------------- +// GitHub REST client (fetch; no gh CLI, no checkout, no extra action) +// --------------------------------------------------------------------------- + +const MAX_RETRIES = 3; +const RETRY_DELAY_MS = Number(process.env.GOVERNANCE_BADGE_RETRY_DELAY_MS || 1000); +const MAX_CONFLICT_ATTEMPTS = 3; + +const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); + +/** Return the string value with all trailing slashes removed. */ +function trimTrailingSlashes(value) { + let base = String(value); + while (base.endsWith("/")) base = base.slice(0, -1); + return base; +} + +/** + * Send an authenticated request to apiUrl + apiPath, encoding a supplied body + * as JSON. Resolve to { status, ok, text }, including for HTTP error statuses. + * timeoutMs bounds the request and response-body read; no retries occur here. + * @throws {ApiError} If serialization, fetch, or reading the response body fails. + */ +async function request(method, apiPath, { token, apiUrl, body, timeoutMs = 30000 } = {}) { + const url = `${trimTrailingSlashes(apiUrl)}${apiPath}`; + const headers = { + Authorization: `Bearer ${token}`, + Accept: "application/vnd.github+json", + "X-GitHub-Api-Version": "2022-11-28", + "User-Agent": "hyperpolymath-governance-badge", + }; + if (body !== undefined) headers["Content-Type"] = "application/json"; + + let response; + try { + response = await fetch(url, { + method, + headers, + body: body === undefined ? undefined : JSON.stringify(body), + signal: AbortSignal.timeout(timeoutMs), + }); + } catch (err) { + throw new ApiError(`${method} ${apiPath} failed: ${err.message}`, { kind: "network" }); + } + let text = ""; + try { + text = await response.text(); + } catch (err) { + throw new ApiError(`${method} ${apiPath}: response body unreadable: ${err.message}`, { + status: response.status, + kind: "network", + }); + } + return { status: response.status, ok: response.ok, text }; +} + +/** + * Build an ApiError from an HTTP response, preferring its JSON message over + * a shortened text body. Invalid JSON falls back to the text body. + */ +function apiError(method, apiPath, response) { + const kind = classifyStatus(response.status); + let detail = response.text.slice(0, 300).replace(/\s+/g, " ").trim(); + try { + const parsed = JSON.parse(response.text); + if (parsed && typeof parsed.message === "string") detail = parsed.message; + } catch { + /* not JSON; keep the raw head */ + } + return new ApiError( + `${method} ${apiPath} -> HTTP ${response.status} (${KIND_ADVICE[kind] || "error"}): ${detail}`, + { status: response.status, kind }, + ); +} + +/** + * GET and parse a 200 response as JSON, with up to three attempts for + * network failures and 429/5xx only. A 404 is neither retried nor swallowed. + * @throws {ApiError} For other statuses or exhausted network/transient retries. + * @throws {SyntaxError} If a 200 response is not valid JSON; parsing is not retried. + */ +async function getJSON(apiPath, http) { + let lastError; + for (let attempt = 1; attempt <= MAX_RETRIES; attempt += 1) { + try { + const response = await request("GET", apiPath, http); + if (response.status === 200) return JSON.parse(response.text); + throw apiError("GET", apiPath, response); + } catch (err) { + if (!(err instanceof ApiError) || !err.transient) throw err; + lastError = err; + if (attempt < MAX_RETRIES) await sleep(RETRY_DELAY_MS * attempt); + } + } + throw lastError; +} + +// getWithRetry - GET returning the raw response, with bounded retries for +// NETWORK failures and 429/5xx only. A 404 (or 401/403) is an answer, not a +// transport failure, so it is returned immediately: the caller decides what +// "missing" means at its own endpoint. Retrying reads is what keeps a single +// blip from stranding a stale (possibly green) badge until the next push. +async function getWithRetry(apiPath, http) { + let lastError = null; + for (let attempt = 1; attempt <= MAX_RETRIES; attempt += 1) { + let response = null; + try { + response = await request("GET", apiPath, http); + } catch (err) { + if (!(err instanceof ApiError) || !err.transient) throw err; + lastError = err; + } + if (response) { + if (classifyStatus(response.status) !== "transient") return response; + lastError = apiError("GET", apiPath, response); + } + if (attempt < MAX_RETRIES) await sleep(RETRY_DELAY_MS * attempt); + } + throw lastError; +} + +/** + * POST JSON and return the parsed 200/201 response without retrying. + * Transient failures are surfaced so the publication loop can re-read and + * converge; every other status is fatal. + * @throws {ApiError} For network failures, other statuses, or invalid response JSON. + */ +async function postJSON(apiPath, body, http) { + const response = await request("POST", apiPath, { ...http, body }); + if (response.status === 200 || response.status === 201) { + try { + return JSON.parse(response.text); + } catch (err) { + throw new ApiError(`POST ${apiPath}: unreadable JSON response (${err.message})`, { + status: response.status, + kind: "unexpected", + }); + } + } + throw apiError("POST", apiPath, response); +} + +// --------------------------------------------------------------------------- +// Argument handling and guards +// --------------------------------------------------------------------------- + +/** + * Parse --key=value and --key value options, plus a bare --help flag. + * Return an option map with the last duplicate winning; names are not validated. + * @throws {UsageError} For positional arguments or options missing a value. + */ +function parseArgs(argv) { + const opts = {}; + for (let i = 0; i < argv.length; i += 1) { + const arg = argv[i]; + if (!arg.startsWith("--")) throw new UsageError(`unexpected argument: ${arg}`); + const eq = arg.indexOf("="); + if (eq !== -1) { + opts[arg.slice(2, eq)] = arg.slice(eq + 1); + continue; + } + const key = arg.slice(2); + if (key === "help") { + opts.help = true; + continue; + } + const value = argv[i + 1]; + if (value === undefined || value.startsWith("--")) { + throw new UsageError(`--${key} needs a value`); + } + opts[key] = value; + i += 1; + } + return opts; +} + +/** + * Return a trimmed label of 1-32 ASCII letters, digits, spaces, dots, underscores, + * or hyphens, starting with a letter or digit. + * @throws {UsageError} If the label does not match these restrictions. + */ +function requireLabel(raw) { + const label = String(raw || "").trim(); + if (!/^[A-Za-z0-9][A-Za-z0-9 ._-]{0,31}$/.test(label)) { + throw new UsageError(`--label must be 1-32 safe characters, got ${JSON.stringify(raw)}`); + } + return label; +} + +// The badge branch is generated output. It may never be a default/main branch: +// that is the difference between a badge refresh and a merge into source. +const FORBIDDEN_BRANCHES = new Set(["main", "master", "head"]); + +/** + * Return a trimmed branch name of 1-80 ASCII letters, digits, dots, underscores, + * or hyphens. The repository's default branch is checked separately by cmdPublish. + * @throws {UsageError} For other names or main/master/HEAD, ignoring case. + */ +function requireBranch(raw) { + const branch = String(raw || "").trim(); + if (!/^[A-Za-z0-9._-]{1,80}$/.test(branch)) { + throw new UsageError( + `--branch must be a simple branch name (letters, digits, . _ -), got ${JSON.stringify(raw)}`, + ); + } + if (FORBIDDEN_BRANCHES.has(branch.toLowerCase())) { + throw new UsageError( + `--branch ${branch} is a source branch; generated badges belong on an orphan branch such as governance-badges`, + ); + } + return branch; +} + +/** + * Return a trimmed badges/.json path, where name has 1-80 ASCII letters, + * digits, dots, underscores, or hyphens and contains no directory separators. + * @throws {UsageError} If the destination does not match this shape. + */ +function requireDest(raw) { + const dest = String(raw || "").trim(); + if (!/^badges\/[A-Za-z0-9._-]{1,80}\.json$/.test(dest)) { + throw new UsageError( + `--path must look like badges/.json (no traversal, no other directory), got ${JSON.stringify(raw)}`, + ); + } + return dest; +} + +/** Encode each path segment for a URL while preserving directory separators. */ +function encodePath(p) { + return p.split("/").map(encodeURIComponent).join("/"); +} + +// --------------------------------------------------------------------------- +// render +// --------------------------------------------------------------------------- + +/** + * Write the canonical badge to opts.out (overwriting it) or stdout and return 0. + * Unknown states become unknown/lightgrey; output directories are not created. + * @throws {UsageError} For an invalid label or missing state. + * @throws {Error} Propagates filesystem errors when writing opts.out. + */ +function cmdRender(opts) { + const label = requireLabel(opts.label); + if (opts.state === undefined) throw new UsageError("render needs --state"); + const state = normaliseState(opts.state); + const text = renderBadge(label, state); + if (opts.out) { + writeFileSync(opts.out, text); + console.log(`governance-badge: rendered ${oneLine(opts.out)} state=${state}`); + } else { + process.stdout.write(text); + } + return EXIT_OK; +} + +// --------------------------------------------------------------------------- +// Intent: what badge SHOULD this run publish? +// --------------------------------------------------------------------------- + +/** + * Resolve the lane result to { state, bytes, faults }, with canonical UTF-8 + * badge bytes. Only success reads artifact, a local file that must contain the + * canonical success badge for label; an artifact cannot turn a failed lane green. + * Missing/non-file, invalid, noncanonical, or contradictory evidence returns + * unavailable with a fault. Other lane states return no faults. + * @throws {Error} Propagates filesystem inspection and read errors. + */ +function resolveIntent({ label, laneResult, artifact }) { + const laneState = normaliseState(laneResult); + const faults = []; + + if (laneState !== "success") { + const state = laneState; + return { state, bytes: Buffer.from(renderBadge(label, state), "utf8"), faults }; + } + + const grey = (reason) => { + faults.push(reason); + return { + state: "unavailable", + bytes: Buffer.from(renderBadge(label, "unavailable"), "utf8"), + faults, + }; + }; + + if (!existsSync(artifact) || !statSync(artifact).isFile()) { + return grey(`the lane artifact ${artifact} is missing, so a "success" lane cannot be trusted`); + } + + // A file that exists, is regular, and still cannot be read (EACCES, a + // TOCTOU deletion between the stat above and here, an I/O error) is not a + // crash: it is evidence that cannot be checked, so the badge goes grey and + // the errno is named. Throwing here would exit 1 with a stack trace and no + // badge, which reads as "the publisher is broken" rather than "the lane + // evidence is unreadable" - and grey is the honest state either way. + let text; + try { + text = readFileSync(artifact, "utf8"); + } catch (err) { + return grey( + `the lane artifact ${artifact} could not be read (${err && err.code ? err.code : String(err)}),` + + ` so a "success" lane cannot be trusted`, + ); + } + const verdict = inspectBadge(text, label); + if (!verdict.ok) { + return grey(`the lane artifact ${artifact} is not a valid shield badge: ${verdict.errors.join("; ")}`); + } + if (text !== renderBadge(label, verdict.badge.message)) { + return grey(`the lane artifact ${artifact} is not byte-identical to the canonical render`); + } + if (verdict.badge.message !== "success") { + return grey( + `the lane job reports "success" but its artifact records ` + + `${JSON.stringify(verdict.badge.message)} - refusing to publish a green badge`, + ); + } + return { state: "success", bytes: Buffer.from(renderBadge(label, "success"), "utf8"), faults }; +} + +// --------------------------------------------------------------------------- +// Remote state: present / file absent / branch absent - and nothing else +// --------------------------------------------------------------------------- + +/** + * Read the published badge as { kind: "present", bytes, text, sha }, or return + * kind absent-file/absent-branch after a contents 404 and a ref 200/404. + * repo is owner/name; dest is the repository-relative badge path. + * @throws {ApiError} For failed reads, other statuses, invalid contents JSON, + * or missing encoding/content/sha fields. + * @throws {TypeError} If the decoded contents payload is null. + */ +async function readRemote({ repo, branch, dest, http }) { + const contentsPath = `/repos/${repo}/contents/${encodePath(dest)}?ref=${encodeURIComponent(branch)}`; + const response = await getWithRetry(contentsPath, http); + + if (response.status === 200) { + let payload; + try { + payload = JSON.parse(response.text); + } catch (err) { + throw new ApiError(`GET ${contentsPath}: unreadable JSON (${err.message})`, { + status: 200, + kind: "unexpected", + }); + } + if (payload.encoding !== "base64" || typeof payload.content !== "string" || !payload.sha) { + throw new ApiError( + `GET ${contentsPath}: unexpected contents payload ` + + `(encoding=${JSON.stringify(payload.encoding)}) - refusing to guess`, + { status: 200, kind: "unexpected" }, + ); + } + const bytes = Buffer.from(payload.content, "base64"); + return { kind: "present", bytes, text: bytes.toString("utf8"), sha: payload.sha }; + } + + if (response.status !== 404) { + // 401/403/429/5xx/anything else: we do NOT know. Never "missing". + throw apiError("GET", contentsPath, response); + } + + // The file is absent. That means "branch exists, file missing" ONLY if the + // branch is really there; a 404 on the ref means the branch is absent. Any + // other ref status is an outage and must not create a branch. + const refPath = `/repos/${repo}/git/ref/heads/${branch}`; + const refResponse = await getWithRetry(refPath, http); + if (refResponse.status === 200) return { kind: "absent-file" }; + if (refResponse.status === 404) return { kind: "absent-branch" }; + throw apiError("GET", refPath, refResponse); +} + +// --------------------------------------------------------------------------- +// Publishing +// --------------------------------------------------------------------------- + +/** Build the Contents API path for an owner/name repo and relative destination. */ +function contentsPathFor(repo, dest) { + return `/repos/${repo}/contents/${encodePath(dest)}`; +} + +/** + * Create or replace the badge through the Contents API. Supply the previously + * read blob sha for an update; omit it to create a file. A write may make a commit. + * Return the raw response without status validation or retries. + * @throws {ApiError} Propagates request failures, including unreadable responses. + */ +async function putFile({ repo, branch, dest, message, bytes, sha, http }) { + const body = { + message, + content: bytes.toString("base64"), + branch, + }; + if (sha) body.sha = sha; + return request("PUT", contentsPathFor(repo, dest), { ...http, body }); +} + +/** + * Create a branch containing only the badge, with no parent commits or base tree. + * Return { conflict: false, sha } on success, or { conflict: true } for a ref + * creation 409/422. Earlier Git objects are not rolled back on conflict or error. + * @throws {ApiError} For request failures, unexpected responses, or missing SHAs. + * @throws {RefusedError} If the returned commit explicitly has nonempty parents. + */ +async function createOrphanBranch({ repo, branch, dest, message, bytes, http }) { + const blob = await postJSON(`/repos/${repo}/git/blobs`, { + content: bytes.toString("base64"), + encoding: "base64", + }, http); + if (!blob || typeof blob.sha !== "string") { + throw new ApiError("POST /git/blobs returned no sha", { kind: "unexpected" }); + } + + const tree = await postJSON(`/repos/${repo}/git/trees`, { + tree: [{ path: dest, mode: "100644", type: "blob", sha: blob.sha }], + }, http); + if (!tree || typeof tree.sha !== "string") { + throw new ApiError("POST /git/trees returned no sha", { kind: "unexpected" }); + } + + const commit = await postJSON(`/repos/${repo}/git/commits`, { + message, + tree: tree.sha, + parents: [], + }, http); + if (!commit || typeof commit.sha !== "string") { + throw new ApiError("POST /git/commits returned no sha", { kind: "unexpected" }); + } + if (Array.isArray(commit.parents) && commit.parents.length !== 0) { + throw new RefusedError( + "the API returned a commit WITH parents for an orphan branch - refusing to publish " + + "a governance-badges branch that shares history with a source branch", + ); + } + + const ref = await request("POST", `/repos/${repo}/git/refs`, { + ...http, + body: { ref: `refs/heads/${branch}`, sha: commit.sha }, + }); + if (ref.status === 201 || ref.status === 200) return { conflict: false, sha: commit.sha }; + if (classifyStatus(ref.status) === "conflict") return { conflict: true }; + throw apiError("POST", `/repos/${repo}/git/refs`, ref); +} + +/** + * Append lines and a trailing newline to GITHUB_STEP_SUMMARY when set. + * Ignore an unset target and catch append errors without failing publication. + */ +function stepSummary(lines) { + const target = process.env.GITHUB_STEP_SUMMARY; + if (!target) return; + try { + appendFileSync(target, lines.join("\n") + "\n"); + } catch (err) { + console.log(`governance-badge: could not write the step summary: ${err.message}`); + } +} + +/** + * Append a key=value line to GITHUB_OUTPUT when set. Catch append errors + * without failing publication; an unset target is a no-op. + */ +function setOutput(key, value) { + const target = process.env.GITHUB_OUTPUT; + if (!target) return; + try { + appendFileSync(target, `${key}=${value}\n`); + } catch (err) { + console.log(`governance-badge: could not write $GITHUB_OUTPUT: ${err.message}`); + } +} + +/** + * Record a publication decision in the Actions summary and state/action/colour/ + * label outputs. Return 3 when faults is nonempty, even for unchanged content; + * otherwise return 0. This function does not publish or change the remote badge. + */ +function finish({ label, dest, branch, intent, action, commit, faults }) { + const entry = STATE_TABLE[intent.state]; + const where = oneLine(`${dest} on ${branch}`); + const commitId = oneLine(commit || ""); + + if (action === "unchanged") { + console.log( + `governance-badge: ${where} is byte-identical to the new badge ` + + `(state=${intent.state}, message=${entry.message}, colour=${entry.color}); ` + + `unchanged - no commit made`, + ); + } else { + const commitNote = commitId ? `, commit=${commitId}` : ""; + console.log( + `governance-badge: published ${where} ` + + `(state=${intent.state}, message=${entry.message}, colour=${entry.color}, ` + + `action=${action}${commitNote})`, + ); + } + + for (const fault of faults) { + console.log(`::error::${oneLine(fault)}`); + } + + stepSummary([ + "", + "### Governance badge", + "", + "| file | branch | state | message | colour | action |", + "|---|---|---|---|---|---|", + `| \`${dest}\` | \`${branch}\` | ${intent.state} | ${entry.message} | ${entry.color} | ${action}${commitId ? ` (\`${oneLine(String(commitId).slice(0, 12))}\`)` : ""} |`, + "", + action === "unchanged" + ? "The published badge already carried these exact bytes, so no commit was made." + : "The `governance-badges` branch is generated output: an orphan branch with no common ancestor with `main`. It must never be merged.", + faults.length ? `\n**Lane evidence was unusable:** ${faults.join("; ")}` : "", + "", + ]); + + setOutput("state", intent.state); + setOutput("action", action); + setOutput("colour", entry.color); + setOutput("label", label); + + if (faults.length) { + console.log( + `governance-badge: published a grey "${intent.state}" badge because this run's lane ` + + `evidence was unusable; failing the step so the fault is visible`, + ); + return EXIT_GREY_FAULT; + } + return EXIT_OK; +} + +/** + * Publish the lane's intended badge, leaving identical bytes unchanged and + * refusing invalid existing badges. Repository, token, and API URL options fall + * back to the environment; --source-sha contributes at most 12 characters to + * the default commit message. Missing branches are created without parents. + * Retry contents-write HTTP 409/422/429/5xx, ref-creation 409/422, and network/ + * transient failures during orphan creation by re-reading remote state, for + * at most three publication attempts. + * Return 0 on publication/no-op, or 3 for unusable lane evidence, even on no-op. + * @throws {UsageError} For missing configuration, invalid arguments, or targeting + * main/master/HEAD (ignoring case) or the repository's default branch. + * @throws {RefusedError} For metadata read failures, invalid existing badges, + * non-orphan commits, or exhausted publication attempts. + * @throws {ApiError} Propagates other API failures, including PUT network errors. + * @throws {Error} Propagates artifact filesystem and unexpected payload errors. + */ +async function cmdPublish(opts) { + const label = requireLabel(opts.label); + const branch = requireBranch(opts.branch); + const dest = requireDest(opts.path); + const laneResult = opts["lane-result"]; + if (laneResult === undefined) throw new UsageError("publish needs --lane-result"); + if (!opts.artifact) { + throw new UsageError( + "publish needs --artifact: the lane's badge.json is the evidence that a " + + '"success" result is real', + ); + } + const repo = opts.repo || process.env.GITHUB_REPOSITORY; + if (!repo) throw new UsageError("--repo (or GITHUB_REPOSITORY) is required"); + const token = opts.token || process.env.GITHUB_TOKEN || process.env.GH_TOKEN; + if (!token) throw new UsageError("GITHUB_TOKEN (or GH_TOKEN) is required"); + const apiUrl = opts["api-url"] || process.env.GITHUB_API_URL || "https://api.github.com"; + const timeoutMs = Number(process.env.GOVERNANCE_BADGE_REQUEST_TIMEOUT_MS ?? 30000); + if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2147483647) { + throw new UsageError("GOVERNANCE_BADGE_REQUEST_TIMEOUT_MS must be an integer from 1 to 2147483647"); + } + const http = { token, apiUrl, timeoutMs }; + + const intent = resolveIntent({ label, laneResult, artifact: opts.artifact }); + const sourceRevision = String(opts["source-sha"] || ""); + if (sourceRevision && !/^[a-f0-9]{40}$/.test(sourceRevision)) { + throw new UsageError("--source-sha must be a complete 40-character Git commit SHA"); + } + const sourceSha = sourceRevision.slice(0, 12); + const message = + opts["commit-message"] || + `badges: ${label} lane ${intent.state}${sourceSha ? ` (source ${sourceSha})` : ""}`; + + // Refuse to touch a source branch, whatever --branch said and whatever the + // repository's default branch happens to be called. + const repoInfo = await getJSON(`/repos/${repo}`, http).catch((err) => { + throw new RefusedError( + `cannot read repository metadata for ${repo}: ${err.message} - not treating this as "the branch is missing"`, + ); + }); + const defaultBranch = String((repoInfo && repoInfo.default_branch) || ""); + if (defaultBranch && defaultBranch === branch) { + throw new UsageError( + `--branch ${branch} is this repository's default branch; generated badges belong ` + + "on an orphan branch such as governance-badges", + ); + } + + // Badge content belongs to one source revision, not merely one runner. + // Older push jobs can finish after newer ones despite concurrency and + // cannot overwrite the current revision's published badge. + const assertSourceCurrent = async () => { + if (!sourceRevision) return; + if (!defaultBranch) { + throw new RefusedError("repository does not identify its default branch; cannot establish source freshness"); + } + let head; + try { + head = await getJSON(`/repos/${repo}/git/ref/heads/${encodeURIComponent(defaultBranch)}`, http); + } catch (err) { + throw new RefusedError(`cannot establish current ${defaultBranch} head: ${err.message}`); + } + const currentSha = head?.object?.sha; + if (currentSha !== sourceRevision) { + throw new RefusedError( + `superseded source commit ${sourceRevision.slice(0, 12)}: ${defaultBranch} is at ${String(currentSha || "").slice(0, 12)}; refusing stale badge publication`, + ); + } + }; + + let lastConflict = null; + for (let attempt = 1; attempt <= MAX_CONFLICT_ATTEMPTS; attempt += 1) { + await assertSourceCurrent(); + const remote = await readRemote({ repo, branch, dest, http }); + + if (remote.kind === "present") { + const verdict = inspectBadge(remote.text, label, { pairing: "loose" }); + if (!verdict.ok) { + throw new RefusedError( + `the existing ${dest} on ${branch} is not a valid shield badge ` + + `(${verdict.errors.join("; ")}); refusing to overwrite generated output ` + + "this tool did not produce. Repair or delete the file by hand, then re-run.", + ); + } + if (remote.bytes.equals(intent.bytes)) { + return finish({ label, dest, branch, intent, action: "unchanged", commit: null, faults: intent.faults }); + } + await assertSourceCurrent(); + let response; + try { + response = await putFile({ + repo, branch, dest, message, bytes: intent.bytes, sha: remote.sha, http, + }); + } catch (err) { + // A lost response is not proof that the PUT failed. Re-read + // remote bytes before another write, exactly as for HTTP 409. + if (err instanceof ApiError && err.transient) { + lastConflict = err; + await sleep(RETRY_DELAY_MS * attempt); + continue; + } + throw err; + } + if (response.status === 200 || response.status === 201) { + const sha = readJsonPath(response.text, "commit.sha"); + return finish({ label, dest, branch, intent, action: "updated", commit: sha, faults: intent.faults }); + } + const kind = classifyStatus(response.status); + if (kind === "conflict" || kind === "transient") { + lastConflict = apiError("PUT", contentsPathFor(repo, dest), response); + await sleep(RETRY_DELAY_MS * attempt); + continue; + } + throw apiError("PUT", contentsPathFor(repo, dest), response); + } + + if (remote.kind === "absent-file") { + await assertSourceCurrent(); + let response; + try { + response = await putFile({ repo, branch, dest, message, bytes: intent.bytes, http }); + } catch (err) { + if (err instanceof ApiError && err.transient) { + lastConflict = err; + await sleep(RETRY_DELAY_MS * attempt); + continue; + } + throw err; + } + if (response.status === 200 || response.status === 201) { + const sha = readJsonPath(response.text, "commit.sha"); + return finish({ label, dest, branch, intent, action: "created", commit: sha, faults: intent.faults }); + } + const kind = classifyStatus(response.status); + if (kind === "conflict" || kind === "transient") { + lastConflict = apiError("PUT", contentsPathFor(repo, dest), response); + await sleep(RETRY_DELAY_MS * attempt); + continue; + } + throw apiError("PUT", contentsPathFor(repo, dest), response); + } + + // remote.kind === "absent-branch": create an orphan branch. + let created; + try { + await assertSourceCurrent(); + created = await createOrphanBranch({ repo, branch, dest, message, bytes: intent.bytes, http }); + } catch (err) { + if (err instanceof ApiError && err.transient) { + lastConflict = err; + await sleep(RETRY_DELAY_MS * attempt); + continue; + } + throw err; + } + if (created.conflict) { + // Another run created the branch between our read and our write. + // Re-read and compare instead of forcing our ref over theirs. + lastConflict = new RefusedError( + `another run created ${branch} while this one was publishing; re-reading`, + ); + await sleep(RETRY_DELAY_MS * attempt); + continue; + } + return finish({ label, dest, branch, intent, action: "created-orphan-branch", commit: created.sha, faults: intent.faults }); + } + + throw new RefusedError( + `gave up after ${MAX_CONFLICT_ATTEMPTS} attempts without a trustworthy publication` + + (lastConflict ? `: ${lastConflict.message}` : ""), + ); +} + +/** + * Return the string at a dot-separated JSON path, or an empty string for invalid + * JSON, a missing path, or a non-string value. + */ +function readJsonPath(text, path) { + try { + const parsed = JSON.parse(text); + const parts = path.split("."); + let cursor = parsed; + for (const part of parts) cursor = cursor?.[part]; + return typeof cursor === "string" ? cursor : ""; + } catch { + return ""; + } +} + +// --------------------------------------------------------------------------- +// Entry point +// --------------------------------------------------------------------------- + +/** Print command usage, supported states, and exit codes to stdout. */ +function usage() { + console.log( + [ + "usage:", + " governance-badge.js render --label K9 --state success [--out FILE]", + " governance-badge.js publish --label K9 --lane-result success \\", + " --artifact FILE --branch governance-badges --path badges/k9.json \\", + " [--repo owner/name] [--source-sha SHA] [--commit-message TEXT]", + "", + "States: success | failure | skipped | cancelled | unavailable | unknown.", + "Exit: 0 ok/unchanged, 1 refused/failed, 2 usage, 3 grey published (lane evidence unusable).", + ].join("\n"), + ); +} + +/** + * Dispatch command-line arguments (excluding the runtime and script paths), + * returning 0 for help or the selected command's exit code. + * @throws {UsageError} For malformed options or an unknown command. + * @throws {Error} Propagates render/publication errors to the entry point's handler. + */ +async function main(argv) { + const command = argv[0]; + const opts = parseArgs(argv.slice(1)); + if (!command || command === "help" || opts.help || command === "--help" || command === "-h") { + usage(); + return EXIT_OK; + } + if (command === "render") return cmdRender(opts); + if (command === "publish") return cmdPublish(opts); + throw new UsageError(`unknown command: ${command}`); +} + +// process.exit() can truncate pending writes when stdout is a pipe (which is +// how Actions captures a step's log, and how the "unchanged" notice reaches the +// run page). Set the code and let the process drain and exit instead. +main(process.argv.slice(2)) + .then((code) => { + process.exitCode = code; + }) + .catch((err) => { + if (err instanceof UsageError) { + console.error(`governance-badge: ${oneLine(err.message)}`); + usage(); + process.exitCode = EXIT_USAGE; + return; + } + if (err instanceof RefusedError) { + console.error(`governance-badge: refused: ${oneLine(err.message)}`); + process.exitCode = EXIT_REFUSED; + return; + } + if (err instanceof ApiError) { + console.error(`governance-badge: ${oneLine(err.message)}`); + console.error( + "governance-badge: no write was attempted for an unknown remote state; " + + "an API error is never treated as a missing branch or file", + ); + process.exitCode = EXIT_REFUSED; + return; + } + console.error(`governance-badge: ${oneLine((err && err.stack) || err)}`); + process.exitCode = EXIT_REFUSED; + }); diff --git a/scripts/ijson-jcs-cli.js b/scripts/ijson-jcs-cli.js new file mode 100755 index 00000000..36cbfdd2 --- /dev/null +++ b/scripts/ijson-jcs-cli.js @@ -0,0 +1,408 @@ +#!/usr/bin/env bun +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +// +// ijson-jcs-cli.js — local Bun fallback matching hyperpolymath/ijson-jcs's CLI +// contract (`check`, `fix`, `canon`) for environments where the compiled Rust +// binary is not yet installed. CI installs and runs hyperpolymath/ijson-jcs +// directly at a pinned commit; both enforce RFC 7493 (I-JSON) + RFC 8785 (JCS) +// as transitional tooling until metadatastician/kyq passes positive/negative +// tests across its four-format scope. + +import { readFileSync } from "node:fs"; + +const EXIT_OK = 0; +const EXIT_NOT_CANONICAL = 1; +const EXIT_INVALID = 2; +const SAFE_MAX_INT = 9007199254740991n; // 2^53 - 1 (RFC 7493 §2.2) + +const USAGE = `ijson-jcs-cli.js - I-JSON (RFC 7493) parsing and JCS (RFC 8785) canonicalisation (stdin filter) + +USAGE: + ijson-jcs-cli.js check Read stdin; exit 0 if canonical, 1 if valid I-JSON but non-canonical, 2 if invalid + ijson-jcs-cli.js canon Read stdin; write canonical JCS (no trailing newline) to stdout +`; + +/** + * Decode a buffer strictly as UTF-8 without BOM (RFC 7493 §2.1). + * @param {Uint8Array} bytes + * @returns {string} + * @throws {Error} If a BOM is present. + * @throws {TypeError} If the bytes are not valid UTF-8. + */ +function decodeStrictUtf8(bytes) { + if (bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) { + throw new Error("UTF-8 BOM is forbidden in I-JSON"); + } + const decoder = new TextDecoder("utf-8", { fatal: true }); + return decoder.decode(bytes); +} + +/** + * Reject Unicode noncharacters and lone surrogates (RFC 7493 §2.1). + * @param {string} s + * @throws {Error} If the string contains a noncharacter or lone surrogate. + */ +function checkStringCodePoints(s) { + for (let k = 0; k < s.length; k++) { + const c = s.charCodeAt(k); + if (c >= 0xd800 && c <= 0xdfff) { + if (c <= 0xdbff && k + 1 < s.length) { + const c2 = s.charCodeAt(k + 1); + if (c2 >= 0xdc00 && c2 <= 0xdfff) { + const cp = ((c - 0xd800) << 10) + (c2 - 0xdc00) + 0x10000; + if ((cp & 0xfffe) === 0xfffe) { + throw new Error(`Unicode noncharacter U+${cp.toString(16).toUpperCase()}`); + } + k++; + continue; + } + } + throw new Error(`lone UTF-16 surrogate 0x${c.toString(16)}`); + } + if ((c >= 0xfdd0 && c <= 0xfdef) || c === 0xfffe || c === 0xffff) { + throw new Error(`Unicode noncharacter U+${c.toString(16).toUpperCase()}`); + } + } +} + +/** + * Parse `raw` strictly as RFC 7493 I-JSON, rejecting duplicate keys, + * integer tokens outside +/-(2^53-1), non-finite floats, lone surrogates, + * and Unicode noncharacters. + * @param {string} raw + * @returns {unknown} The parsed value, with objects represented as Maps. + * @throws {Error} If JSON syntax or the above validation rules are violated. + */ +function parseIJson(raw) { + let i = 0; + const n = raw.length; + + /** Advance the shared offset past any JSON whitespace. */ + function ws() { + while (i < n) { + const ch = raw[i]; + if (ch === " " || ch === "\t" || ch === "\n" || ch === "\r") i++; + else break; + } + } + + /** + * Read a quoted string at the shared offset and advance past its closing quote. + * Throws on malformed escapes, unterminated strings, or invalid code points. + */ + function parseString() { + if (raw[i] !== '"') throw new Error(`expected '"' at byte ${i}`); + i++; + let out = ""; + while (i < n) { + const ch = raw[i++]; + if (ch === '"') { + checkStringCodePoints(out); + return out; + } + if (ch.charCodeAt(0) < 0x20) { + throw new Error(`unescaped control character at offset ${i - 1}`); + } + if (ch === "\\") { + if (i >= n) throw new Error("unterminated escape sequence"); + const esc = raw[i++]; + if (esc === '"' || esc === "\\" || esc === "/") out += esc; + else if (esc === "b") out += "\b"; + else if (esc === "f") out += "\f"; + else if (esc === "n") out += "\n"; + else if (esc === "r") out += "\r"; + else if (esc === "t") out += "\t"; + else if (esc === "u") { + const hex = raw.slice(i, i + 4); + if (!/^[0-9a-fA-F]{4}$/.test(hex)) throw new Error("invalid \\u escape"); + i += 4; + const cp = parseInt(hex, 16); + if (cp >= 0xd800 && cp <= 0xdbff) { + if (raw.slice(i, i + 2) !== "\\u") throw new Error("unpaired high surrogate"); + const hex2 = raw.slice(i + 2, i + 6); + if (!/^[0-9a-fA-F]{4}$/.test(hex2)) throw new Error("invalid low surrogate escape"); + const cp2 = parseInt(hex2, 16); + if (cp2 < 0xdc00 || cp2 > 0xdfff) throw new Error("unpaired high surrogate"); + i += 6; + out += String.fromCodePoint(((cp - 0xd800) << 10) + (cp2 - 0xdc00) + 0x10000); + } else if (cp >= 0xdc00 && cp <= 0xdfff) { + throw new Error("unpaired low surrogate"); + } else { + out += String.fromCharCode(cp); + } + } else { + throw new Error(`invalid escape '\\${esc}'`); + } + } else { + out += ch; + } + } + throw new Error("unterminated string"); + } + + /** + * Read a JSON number at the shared offset, advancing past it and converting -0 to 0. + * Throws on malformed numbers, unsafe integer tokens, or non-finite results. + */ + function parseNumber() { + const start = i; + if (raw[i] === "-") i++; + if (i >= n) throw new Error("incomplete number"); + if (raw[i] === "0") { + i++; + if (i < n && raw[i] >= "0" && raw[i] <= "9") { + throw new Error("leading zero in number"); + } + } else if (raw[i] >= "1" && raw[i] <= "9") { + while (i < n && raw[i] >= "0" && raw[i] <= "9") i++; + } else { + throw new Error(`invalid number at offset ${start}`); + } + let isFloat = false; + if (i < n && raw[i] === ".") { + isFloat = true; + i++; + if (i >= n || raw[i] < "0" || raw[i] > "9") throw new Error("missing fraction digits"); + while (i < n && raw[i] >= "0" && raw[i] <= "9") i++; + } + if (i < n && (raw[i] === "e" || raw[i] === "E")) { + isFloat = true; + i++; + if (i < n && (raw[i] === "+" || raw[i] === "-")) i++; + if (i >= n || raw[i] < "0" || raw[i] > "9") throw new Error("missing exponent digits"); + while (i < n && raw[i] >= "0" && raw[i] <= "9") i++; + } + const token = raw.slice(start, i); + if (!isFloat) { + const mag = BigInt(token.startsWith("-") ? token.slice(1) : token); + if (mag > SAFE_MAX_INT) { + throw new Error(`integer ${token} exceeds IEEE-754 safe range +/-(2^53-1)`); + } + } + const num = Number(token); + if (!Number.isFinite(num)) { + throw new Error(`number ${token} overflows IEEE-754 double`); + } + return Object.is(num, -0) ? 0 : num; + } + + /** + * Read the next value after whitespace, advancing the shared offset. + * Objects become Maps; arrays retain their order. Throws on invalid syntax, + * duplicate decoded keys, or errors propagated from string or number parsing. + */ + function parseValue() { + ws(); + if (i >= n) throw new Error("unexpected end of input"); + const ch = raw[i]; + if (ch === '"') return parseString(); + if (ch === "-" || (ch >= "0" && ch <= "9")) return parseNumber(); + if (ch === "{") { + i++; + ws(); + const obj = new Map(); + if (raw[i] === "}") { + i++; + return obj; + } + let closedObj = false; + while (i < raw.length) { + ws(); + const key = parseString(); + if (obj.has(key)) { + throw new Error(`duplicate object key ${JSON.stringify(key)}`); + } + ws(); + if (raw[i] !== ":") throw new Error(`expected ':' after key ${JSON.stringify(key)}`); + i++; + const val = parseValue(); + obj.set(key, val); + ws(); + if (raw[i] === ",") { + i++; + continue; + } + if (raw[i] === "}") { + i++; + closedObj = true; + break; + } + throw new Error(`expected ',' or '}' at offset ${i}`); + } + if (!closedObj) throw new Error("unterminated object"); + return obj; + } + if (ch === "[") { + i++; + ws(); + const arr = []; + if (raw[i] === "]") { + i++; + return arr; + } + let closedArr = false; + while (i < raw.length) { + arr.push(parseValue()); + ws(); + if (raw[i] === ",") { + i++; + continue; + } + if (raw[i] === "]") { + i++; + closedArr = true; + break; + } + throw new Error(`expected ',' or ']' at offset ${i}`); + } + if (!closedArr) throw new Error("unterminated array"); + return arr; + } + if (raw.slice(i, i + 4) === "true") { + i += 4; + return true; + } + if (raw.slice(i, i + 5) === "false") { + i += 5; + return false; + } + if (raw.slice(i, i + 4) === "null") { + i += 4; + return null; + } + throw new Error(`unexpected token at offset ${i}`); + } + + const val = parseValue(); + ws(); + if (i !== n) throw new Error(`trailing characters at offset ${i}`); + return val; +} + +/** + * Compare two strings by UTF-16 code units (RFC 8785 §3.2.3). + * @param {string} a + * @param {string} b + */ +function compareUtf16(a, b) { + const len = Math.min(a.length, b.length); + for (let idx = 0; idx < len; idx++) { + const diff = a.charCodeAt(idx) - b.charCodeAt(idx); + if (diff !== 0) return diff; + } + return a.length - b.length; +} + +/** + * Serialize a validated value into RFC 8785 (JCS) canonical form. + * @param {unknown} val - A parsed value whose objects are Maps with string keys. + * @returns {string} + * @throws {Error} If a value is neither a JSON primitive, an array, nor a Map. + */ +function serializeJcs(val) { + if (val === null || typeof val === "boolean" || typeof val === "number" || typeof val === "string") { + return JSON.stringify(val); + } + if (Array.isArray(val)) { + return "[" + val.map(serializeJcs).join(",") + "]"; + } + if (val instanceof Map) { + const keys = [...val.keys()].sort(compareUtf16); + return "{" + keys.map((k) => JSON.stringify(k) + ":" + serializeJcs(val.get(k))).join(",") + "}"; + } + throw new Error("unsupported JSON value"); +} + +/** + * Return JCS text without a trailing newline from BOM-free UTF-8 I-JSON bytes. + * Propagates decoding and I-JSON validation errors. + */ +function canonicalString(bytes) { + const text = decodeStrictUtf8(bytes); + const parsed = parseIJson(text); + return serializeJcs(parsed); +} + +const encoder = new TextEncoder(); + +/** + * Check stdin against JCS, allowing a single trailing LF. + * Return 0 for canonical input, 1 for valid but non-canonical input, or 2 for + * caught read or validation errors, which are reported to stderr. + */ +function cmdCheckStdin() { + let bytes; + try { + bytes = readFileSync(0); + } catch (err) { + console.error(`INVALID : cannot read: ${err.message}`); + return EXIT_INVALID; + } + try { + const canon = encoder.encode(canonicalString(bytes)); + const stripped = + bytes.length > 0 && bytes[bytes.length - 1] === 0x0a + ? bytes.subarray(0, bytes.length - 1) + : bytes; + if (stripped.length !== canon.length) { + return EXIT_NOT_CANONICAL; + } + for (let idx = 0; idx < canon.length; idx++) { + if (stripped[idx] !== canon[idx]) { + return EXIT_NOT_CANONICAL; + } + } + return EXIT_OK; + } catch (err) { + console.error(`INVALID : ${err.message}`); + return EXIT_INVALID; + } +} + +/** + * Write stdin as JCS without a trailing newline and return 0. + * Return 2 and report caught read, validation, or write errors to stderr. + */ +function cmdCanon() { + let bytes; + try { + bytes = readFileSync(0); + } catch (err) { + console.error(`INVALID : cannot read: ${err.message}`); + return EXIT_INVALID; + } + try { + process.stdout.write(canonicalString(bytes)); + return EXIT_OK; + } catch (err) { + console.error(`INVALID : ${err.message}`); + return EXIT_INVALID; + } +} + +const args = process.argv.slice(2); +if (args.includes("-h") || args.includes("--help")) { + process.stdout.write(USAGE); + process.exit(EXIT_OK); +} +if (args.includes("-V") || args.includes("--version")) { + console.log("ijson-jcs-cli.js 0.1.0"); + process.exit(EXIT_OK); +} +if (args.length === 0) { + console.error("ijson-jcs: missing command"); + process.exit(EXIT_INVALID); +} +const [cmd, ...rest] = args; +if (rest.length > 0) { + console.error(`ijson-jcs: '${cmd}' reads stdin and takes no arguments`); + process.exit(EXIT_INVALID); +} +if (cmd === "check") process.exit(cmdCheckStdin()); +if (cmd === "canon") { + process.exitCode = cmdCanon(); +} else { + console.error(`ijson-jcs: unknown command '${cmd}'`); + process.exitCode = EXIT_INVALID; +} diff --git a/scripts/kyaml-format.sh b/scripts/kyaml-format.sh new file mode 100755 index 00000000..f348034b --- /dev/null +++ b/scripts/kyaml-format.sh @@ -0,0 +1,126 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# kyaml-format.sh — format arbitrary YAML as KYAML, or check that it already is +# (YAML-POLICY Y-3; KYAML adoption step 3, standards#1022). +# +# The rewriter is `yq -p yaml -o kyaml '.'`, verbatim — the one rewriter the +# step-2 comment-preservation proof (tools/yaml-comment-proof, standards#1021) +# covers. That proof does not generalise to any other rewriter, so this script +# deliberately adds none: no post-processing, no re-indenting, no sed. +# +# Usage: +# kyaml-format.sh [--check] FILE... +# +# (default) rewrite each FILE in place as KYAML when it is not already. +# --check rewrite nothing; exit 1 if any FILE is not already KYAML. +# +# Exit contract: +# 0 = every FILE is KYAML (after the rewrite, in format mode) +# 1 = --check: at least one FILE is not KYAML (each one is named) +# 2 = refused: no FILE given, a FILE is missing or unparseable, a FILE has no +# final newline, is a symlink in format mode, or the rewrite would change +# the parsed data. A refusal +# never rewrites that FILE and never counts as clean. +# +# Why the final-newline refusal: a `|` block scalar that ends at EOF with no +# line break is read differently by go-yaml (yq) and eemeli/yaml — measured on +# k9-contractile.yml, the trailing "\n" of its last run: body exists for one +# parser and not the other. Formatting such a file would silently pick one +# reading, so the script refuses it and names the fix instead. +set -uo pipefail + +MODE=format +if [ "${1:-}" = "--check" ]; then + MODE=check + shift +fi + +if [ "$#" -eq 0 ]; then + echo "kyaml-format: no files given (usage: kyaml-format.sh [--check] FILE...)" >&2 + exit 2 +fi + +command -v yq >/dev/null 2>&1 || { echo "kyaml-format: yq is not on PATH" >&2; exit 2; } + +TMP="$(mktemp -d)" +trap 'rm -rf "$TMP"' EXIT + +# canonical_data — prints the file's parsed value as key-sorted JSON; +# fails when the file does not parse. +canonical_data() { + yq -p yaml -o json -I 0 'sort_keys(..)' "$1" +} + +# kyaml_of — writes the KYAML rendering of to ; +# fails when does not parse. +kyaml_of() { + yq -p yaml -o kyaml '.' "$1" > "$2" +} + +# refuse — reports a file this script will not judge. +refuse() { + echo "::error file=$1::kyaml-format: REFUSED $1 — $2" >&2 + refused=$((refused + 1)) +} + +refused=0 drift=0 clean=0 rewritten=0 +i=0 +for f in "$@"; do + i=$((i + 1)) + out="$TMP/$i.kyaml" + if [ "$MODE" = format ] && [ -L "$f" ]; then + refuse "$f" "symlink; format its target explicitly"; continue + fi + if [ ! -f "$f" ]; then + refuse "$f" "no such file"; continue + fi + if [ -s "$f" ] && [ -n "$(tail -c1 "$f")" ]; then + refuse "$f" "no final newline; add one first (a trailing block scalar is ambiguous without it)"; continue + fi + if ! kyaml_of "$f" "$out" 2>"$TMP/err"; then + refuse "$f" "does not parse: $(head -1 "$TMP/err")"; continue + fi + if cmp -s "$f" "$out"; then + clean=$((clean + 1)); continue + fi + # The rewrite is only acceptable when it preserves the data exactly. + if ! before=$(canonical_data "$f") || ! after=$(canonical_data "$out") || [ "$before" != "$after" ]; then + refuse "$f" "the KYAML rendering does not parse to the same data"; continue + fi + if [ "$MODE" = check ]; then + echo "::error file=$f::kyaml-format: $f is not KYAML — run scripts/kyaml-format.sh $f" >&2 + drift=$((drift + 1)) + else + staged="" + if ! staged="$(mktemp "$(dirname "$f")/.kyaml.XXXXXX")" || ! cp -p "$f" "$staged" 2>/dev/null && ! : > "$staged"; then + [ -n "$staged" ] && rm -f "$staged" + refuse "$f" "could not stage temporary file in $(dirname "$f")" + continue + fi + if ! cat "$out" > "$staged" || ! cmp -s "$out" "$staged" || ! mv -f "$staged" "$f"; then + rm -f "$staged" + refuse "$f" "failed to atomically replace $f" + continue + fi + echo "kyaml-format: rewrote $f" + rewritten=$((rewritten + 1)) + fi +done + +total=$# +if [ "$refused" -gt 0 ]; then + echo "kyaml-format: $refused of $total file(s) REFUSED — not judged, not clean" >&2 + exit 2 +fi +if [ "$drift" -gt 0 ]; then + echo "kyaml-format: $drift of $total file(s) are not KYAML" >&2 + exit 1 +fi +if [ "$MODE" = check ]; then + echo "kyaml-format: all $total file(s) are KYAML" +else + echo "kyaml-format: $total file(s) KYAML ($rewritten rewritten, $clean already clean)" +fi +exit 0 diff --git a/scripts/merge-actions-lock.rs b/scripts/merge-actions-lock.rs new file mode 100644 index 00000000..53cd1394 --- /dev/null +++ b/scripts/merge-actions-lock.rs @@ -0,0 +1,228 @@ +// SPDX-License-Identifier: MPL-2.0 +// +// Merge an archetype's actions.lock fragment into the spine's lock at mint. +// +// An archetype that ships workflows must ship their lock records too. The +// julia-library archetype used to carry a whole actions.lock inside its +// overlay, and `cp -a` of the overlay REPLACED the spine's lock: every spine +// workflow lost its records, so each Julia mint started with Lock Sync red and +// its workflows refused at startup (ZeroInflatedCounts.jl and +// ResidualEvidenceTypes.jl, 2026-10-02). The records now live beside the +// overlay as a fragment and are merged in instead. +// +// Input is the format `gh actions-lock` writes (version 'v0.0.2'): a comment +// header, `version:`, then the `workflows:` and `dependencies:` maps, whose +// entries are single-quoted keys at four spaces followed by an indented body. +// The rules: +// +// * both files must carry the same `version:` line; +// * any other top-level key, or any line this shape does not explain, is +// refused rather than dropped; +// * entries are unioned per section. A key present in both files must have a +// byte-identical entry, or the merge is refused: two resolutions of one ref +// are a conflict for `gh actions-lock` to settle, not for this tool; +// * the output keeps the base's header and sorts each section by key in byte +// order, as `gh actions-lock` does, so a second merge changes nothing. + +#![forbid(unsafe_code)] +// +// The base file is rewritten in place. +// +// Usage: merge-actions-lock.rs + +use std::collections::BTreeMap; +use std::env; +use std::fs; +use std::process; + +/// The two maps an actions.lock holds, in the order the file writes them. +const SECTIONS: [&str; 2] = ["workflows", "dependencies"]; + +/// One parsed lock file: its comment header, its `version:` line, and each +/// section's entries keyed by the unquoted key, holding the entry's full text. +struct Lock { + header: Vec, + version: Option, + sections: [BTreeMap; 2], +} + +/// Parse a lock file's text, naming `path` and the line number in any error. +fn parse(path: &str, text: &str) -> Result { + let mut lock = Lock { + header: Vec::new(), + version: None, + sections: [BTreeMap::new(), BTreeMap::new()], + }; + let mut section: Option = None; + let mut current: Option = None; + let mut seen_body = false; + + for (i, line) in text.lines().enumerate() { + let at = |what: &str| format!("{}:{}: {}: {}", path, i + 1, what, line); + + if line.starts_with(" ") { + let (s, key) = match (section, ¤t) { + (Some(s), Some(k)) => (s, k.clone()), + _ => return Err(at("indented line outside an entry")), + }; + let entry = lock.sections[s] + .get_mut(&key) + .ok_or_else(|| at("entry body whose key was not recorded"))?; + entry.push_str(line); + entry.push('\n'); + continue; + } + + if let Some(rest) = line.strip_prefix(" '") { + let s = section.ok_or_else(|| at("entry outside a section"))?; + let end = rest.find("':").ok_or_else(|| at("unterminated key"))?; + let key = rest[..end].to_string(); + let tail = &rest[end + 2..]; + if !tail.is_empty() && tail != " []" { + return Err(at("unexpected text after key")); + } + if lock.sections[s].contains_key(&key) { + return Err(at("duplicate key")); + } + lock.sections[s].insert(key.clone(), format!("{}\n", line)); + current = Some(key); + continue; + } + + if line.starts_with('#') || line.trim().is_empty() { + // Comments and blank lines belong to the header only; anywhere + // else they would be silently lost on rewrite. + if seen_body { + return Err(at("comment or blank line after the header")); + } + lock.header.push(line.to_string()); + continue; + } + + if line.starts_with(' ') { + return Err(at("unrecognised indentation")); + } + + seen_body = true; + current = None; + if line.starts_with("version:") { + if lock.version.is_some() { + return Err(at("second version line")); + } + lock.version = Some(line.to_string()); + section = None; + continue; + } + let name = line.trim_end_matches(" {}").trim_end_matches(':'); + match SECTIONS.iter().position(|s| *s == name) { + Some(s) if line == format!("{}:", name) || line == format!("{}: {{}}", name) => { + section = Some(s); + } + _ => return Err(at("unknown top-level key")), + } + } + + if lock.version.is_none() { + return Err(format!("{}: no version line", path)); + } + Ok(lock) +} + +/// Fold `frag`'s entries into `base`, refusing a version mismatch or a key +/// whose entry differs between the two. Returns how many entries were new. +fn merge(base: &mut Lock, frag: &Lock, frag_path: &str) -> Result { + if base.version != frag.version { + return Err(format!( + "{}: version {:?} does not match the base's {:?}", + frag_path, + frag.version.as_deref().unwrap_or(""), + base.version.as_deref().unwrap_or("") + )); + } + let mut added = 0; + for (s, name) in SECTIONS.iter().enumerate() { + for (key, entry) in &frag.sections[s] { + match base.sections[s].get(key) { + Some(existing) if existing == entry => {} + Some(_) => { + return Err(format!( + "{}: {} entry '{}' differs from the base's; \ + regenerate with `gh actions-lock` instead of merging", + frag_path, name, key + )) + } + None => { + base.sections[s].insert(key.clone(), entry.clone()); + added += 1; + } + } + } + } + Ok(added) +} + +/// Render a lock in the layout `gh actions-lock` writes. +fn render(lock: &Lock) -> String { + let mut out = String::new(); + for line in &lock.header { + out.push_str(line); + out.push('\n'); + } + out.push_str(lock.version.as_deref().unwrap_or("")); + out.push('\n'); + for (s, name) in SECTIONS.iter().enumerate() { + if lock.sections[s].is_empty() { + out.push_str(&format!("{}: {{}}\n", name)); + continue; + } + out.push_str(&format!("{}:\n", name)); + for entry in lock.sections[s].values() { + out.push_str(entry); + } + } + out +} + +/// Read and parse one lock file, exiting with status 1 on any failure. +fn load(path: &str) -> Lock { + let text = fs::read_to_string(path).unwrap_or_else(|e| { + eprintln!("merge-actions-lock: cannot read {}: {}", path, e); + process::exit(1); + }); + parse(path, &text).unwrap_or_else(|e| { + eprintln!("merge-actions-lock: {}", e); + process::exit(1); + }) +} + +/// Merge the fragment named on the command line into the base lock, in place. +fn main() { + let args: Vec = env::args().skip(1).collect(); + if args.len() != 2 { + eprintln!("Usage: merge-actions-lock.rs "); + process::exit(2); + } + let (base_path, frag_path) = (&args[0], &args[1]); + let mut base = load(base_path); + let frag = load(frag_path); + + let added = merge(&mut base, &frag, frag_path).unwrap_or_else(|e| { + eprintln!("merge-actions-lock: {}", e); + process::exit(1); + }); + + // Write beside the target, then rename, so an interrupted mint never + // leaves a truncated lock behind. + let tmp = format!("{}.merge-tmp", base_path); + if let Err(e) = fs::write(&tmp, render(&base)).and_then(|_| fs::rename(&tmp, base_path)) { + eprintln!("merge-actions-lock: cannot write {}: {}", base_path, e); + let _ = fs::remove_file(&tmp); + process::exit(1); + } + println!( + " actions.lock: merged {} new entr{} from {}", + added, + if added == 1 { "y" } else { "ies" }, + frag_path + ); +} diff --git a/scripts/pin-container-digests.sh b/scripts/pin-container-digests.sh new file mode 100755 index 00000000..07754a4a --- /dev/null +++ b/scripts/pin-container-digests.sh @@ -0,0 +1,150 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# pin-container-digests.sh — turn a floating Containerfile into a pinned one. +# +# The template used to ship `FROM …:latest` twice and let the reader work out +# that `:latest` is a moving target. A template that ships it makes every child +# fail `container-images-pinned` until a human pins digests, so the fix has to be +# mechanical and it has to refuse to pretend: +# +# * a digest is exactly 64 lowercase hex characters, and nothing else is +# accepted — a truncated digest is a reference that resolves to nothing; +# * `pin` rewrites every FROM in the named files, leaving `scratch` and +# stage-relative FROMs alone; +# * with no digest it FAILS and says how to resolve one, because "pinned by +# default at some later date" is how the defect survived in the first place. +# +# ── Usage ─────────────────────────────────────────────────────────────────── +# pin-container-digests.sh --root DIR --base <64hex> [--runtime <64hex>] FILE... +# +# --base D digest for the FIRST (builder) FROM +# --runtime D digest for the remaining FROMs (default: --base) +# FILE... Containerfiles to rewrite, relative to --root +# +# Resolve a digest on a machine that can pull: +# podman pull cgr.dev/chainguard/wolfi-base:latest +# podman image inspect --format '{{index .RepoDigests 0}}' cgr.dev/chainguard/wolfi-base:latest +# -> cgr.dev/chainguard/wolfi-base@sha256:<64 hex> +# +# Exit: 0 = rewritten (or already pinned); 1 = no/invalid digest or bad FROM; +# 2 = usage error. + +set -uo pipefail + +ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +BASE="" +RUNTIME="" +FILES=() + +while [ $# -gt 0 ]; do + case "$1" in + --root) ROOT="${2:-}"; shift 2 ;; + --base) BASE="${2:-}"; shift 2 ;; + --runtime) RUNTIME="${2:-}"; shift 2 ;; + -h|--help) sed -n '2,40p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; + --*) echo "pin-container-digests: unknown option: $1" >&2; exit 2 ;; + *) FILES+=("$1"); shift ;; + esac +done + +[ -d "$ROOT" ] || { echo "pin-container-digests: not a directory: $ROOT" >&2; exit 2; } +[ ${#FILES[@]} -gt 0 ] || { echo "pin-container-digests: no Containerfile named" >&2; exit 2; } + +hex64() { case "${1:-}" in (*[!0-9a-f]*) return 1 ;; esac; [ ${#1} -eq 64 ]; } + +if ! hex64 "$BASE"; then + echo "FAIL: --base must be a 64-character lowercase hex digest (got '${BASE}')" >&2 + echo "" >&2 + echo "Resolve it where the image can be pulled:" >&2 + echo " podman pull cgr.dev/chainguard/wolfi-base:latest" >&2 + echo " podman image inspect --format '{{index .RepoDigests 0}}' cgr.dev/chainguard/wolfi-base:latest" >&2 + echo "" >&2 + echo "A Containerfile is not shipped unpinned, and this script will not invent" >&2 + echo "a digest: a wrong digest is a build that fails later, on someone else's" >&2 + echo "machine, with a supply-chain claim attached to it." >&2 + exit 1 +fi +[ -n "$RUNTIME" ] || RUNTIME="$BASE" +hex64 "$RUNTIME" || { echo "FAIL: --runtime must be 64 lowercase hex characters" >&2; exit 1; } + +rewrite_one() { + local path="$1" idx=0 tmp stages=" " head rest flag ref after base stage + [ -f "$path" ] || { echo "pin-container-digests: no such file: $path" >&2; return 1; } + tmp="$(mktemp)" + while IFS= read -r line || [ -n "$line" ]; do + stripped="$(printf '%s' "$line" | sed -e 's/^[[:space:]]*//')" + case "$stripped" in + [Ff][Rr][Oo][Mm][[:space:]]*) ;; + *) printf '%s\n' "$line" >> "$tmp"; continue ;; + esac + idx=$((idx + 1)) + # Split the instruction into FROM + flags + reference + whatever follows, + # so only the reference is ever rewritten. The previous sed replaced the + # tail of the whole line, which turned `FROM build` and `FROM scratch` + # into `build@sha256:…` / `scratch@sha256:…` — corrupting exactly the + # multi-stage files it should leave alone — and rewrote `AS ` + # whenever its spacing differed from the two forms the regex knew. + head="${stripped%%[[:space:]]*}" + rest="${stripped#"$head"}" + rest="${rest#"${rest%%[![:space:]]*}"}" + while :; do + case "$rest" in + --*) flag="${rest%%[[:space:]]*}" + head="$head $flag" + rest="${rest#"$flag"}" + rest="${rest#"${rest%%[![:space:]]*}"}" ;; + *) break ;; + esac + done + ref="${rest%%[[:space:]]*}" + after="${rest#"$ref"}" + stage="" + case "$after" in + [[:space:]]*[Aa][Ss][[:space:]]*) stage="${after##*[[:space:]]}" ;; + esac + # `FROM scratch` builds from nothing, and `FROM ` builds + # from a stage: neither names a remote image, so neither takes a digest. + case "$ref" in + scratch) printf '%s\n' "$line" >> "$tmp"; continue ;; + esac + case "$stages" in + *" $ref "*) printf '%s\n' "$line" >> "$tmp"; continue ;; + esac + [ -n "$stage" ] && stages="$stages$stage " + # A build-time variable is the file telling us the pin lives elsewhere. + case "$ref" in + *'$'*) printf '%s\n' "$line" >> "$tmp"; continue ;; + esac + if printf '%s' "$ref" | grep -q '@sha256:[0-9a-f]\{64\}$'; then + printf '%s\n' "$line" >> "$tmp"; continue + fi + base="${ref%%@sha256:*}" + case "${base##*:}" in + *[!0-9]*) base="${base%:*}" ;; # a tag, not a registry port + esac + case "${ref##*@}" in + sha256:*) : ;; # partial/malformed digest: drop it + esac + if [ "$idx" -eq 1 ]; then + printf '%s %s@sha256:%s%s\n' "$head" "$base" "$BASE" "$after" >> "$tmp" + else + printf '%s %s@sha256:%s%s\n' "$head" "$base" "$RUNTIME" "$after" >> "$tmp" + fi + done < "$path" + if ! cmp -s "$tmp" "$path"; then + cp "$tmp" "$path" + echo "pinned: ${path#"$ROOT"/} (${idx} FROM line(s))" + else + echo "already pinned: ${path#"$ROOT"/}" + fi + rm -f "$tmp" + return 0 +} + +rc=0 +for f in "${FILES[@]}"; do + case "$f" in /*) rewrite_one "$f" || rc=1 ;; *) rewrite_one "$ROOT/$f" || rc=1 ;; esac +done +exit "$rc" diff --git a/scripts/prune-archetype-modules.sh b/scripts/prune-archetype-modules.sh new file mode 100755 index 00000000..5780c57a --- /dev/null +++ b/scripts/prune-archetype-modules.sh @@ -0,0 +1,76 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# prune-archetype-modules.sh — remove the spine modules an archetype does not +# declare, so a mint carries only what its preset can honestly claim. +# +# ── Why this exists ───────────────────────────────────────────────────────── +# +# The spine is polyglot ON PURPOSE: it carries the ABI/FFI seam, the container +# module and the dev container so that SOME repository minted from it can use +# them. Carrying is the spine's job (standards' template-capability-gates calls +# it the `[carrier]` section). A CHILD carrying them without the capability is +# drift, and two of those modules are not harmless: +# +# * `build/container/` is a deployed artifact. Shipping it to a Julia library +# makes that library fail `container-images-pinned` from birth until someone +# pins a digest it does not need; before that it fails with a floating +# `:latest`, which is how the downstream repos got the defect. +# * anything Python-adjacent would be a policy violation outright. +# +# So an archetype declares what it drops, as data, in: +# +# archetypes//prune.txt one repository-relative path per line +# +# and this script applies it. Paths are removed only if present; a listed path +# that is absent is not an error (the spine may stop shipping a module), but it +# IS reported, because a stale prune entry means the archetype's record is out +# of date. +# +# ── Usage ─────────────────────────────────────────────────────────────────── +# prune-archetype-modules.sh [tree-root ...] +# +# Prints the paths it removed, one per line, so the caller can record them in +# the child's provenance ((variant (paths :removed …))). +# +# Exit: 0 = applied (possibly nothing to do); 2 = usage error. + +set -uo pipefail + +ARCH="${1:-}" +[ -n "$ARCH" ] || { echo "usage: prune-archetype-modules.sh [tree-root ...]" >&2; exit 2; } +shift +[ -d "$ARCH" ] || { echo "prune-archetype-modules: not a directory: $ARCH" >&2; exit 2; } + +LIST="$ARCH/prune.txt" +[ -f "$LIST" ] || exit 0 + +[ $# -gt 0 ] || set -- . + +for root in "$@"; do + [ -d "$root" ] || { echo "prune-archetype-modules: not a directory: $root" >&2; exit 2; } +done + +while IFS= read -r raw; do + p="${raw%%#*}" + p="$(printf '%s' "$p" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')" + [ -n "$p" ] || continue + case "$p" in + /*|*..*) echo "prune-archetype-modules: refusing non-relative path: $p" >&2; exit 2 ;; + esac + found=0 + for root in "$@"; do + if [ -e "$root/$p" ]; then + rm -rf "${root:?}/$p" + found=1 + fi + done + if [ "$found" -eq 1 ]; then + printf '%s\n' "$p" + else + printf 'prune-archetype-modules: %s lists %s, which the spine does not ship (stale entry)\n' \ + "$ARCH" "$p" >&2 + fi +done < "$LIST" +exit 0 diff --git a/scripts/prune-dependabot-ecosystems.rs b/scripts/prune-dependabot-ecosystems.rs index fb0cacf3..f232adf0 100644 --- a/scripts/prune-dependabot-ecosystems.rs +++ b/scripts/prune-dependabot-ecosystems.rs @@ -17,6 +17,8 @@ // // Usage: prune-dependabot-ecosystems.rs +#![forbid(unsafe_code)] + use std::env; use std::fs; use std::path::Path; diff --git a/scripts/render-mise.sh b/scripts/render-mise.sh new file mode 100755 index 00000000..92dd92c6 --- /dev/null +++ b/scripts/render-mise.sh @@ -0,0 +1,176 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# render-mise.sh — render mise.toml from the languages the repository actually +# carries, instead of inheriting the template's list. +# +# ── Why this exists ───────────────────────────────────────────────────────── +# +# The provisioning standard says mise.toml is MINTED per repository +# (PROVISIONING-STANDARD §1: "the toolchain: latest in mise.toml, made concrete +# and checksummed in mise.lock"). The canon's own template carries +# `__MISE_TOOLS_TOML__` for exactly that reason. `just repo-init` never rendered +# it — so every mint inherited the template's own toolchain verbatim. +# +# The template's list used to be nine runtimes (python, node, rust, go, zig, +# java, bun, denojs, …) plus npm/yarn/pnpm/pip/cargo/go-task, black/ruff/isort/ +# prettier/stylua/gofmt/shfmt, cmake/make/ninja, vitest/pytest/jest and an +# [alias] block routing build/test/lint/fmt through Cargo/npm/Go/ruff/black. A +# minted Julia package therefore installed Python (banned estate-wide), Node +# (banned), Go, Java and Cargo, declared no Julia at all, and `just build` ran +# `cargo build`. Fixing that file in one child fixes one child; rendering it at +# mint is what fixes the next N. +# +# The language→tool table is NOT here. It lives in build/just/provision-lib.sh +# (`mise_tools`), the engine `just doctor`, `just setup` and `just dev-shell` +# already read, so this render and the doctor cannot disagree about what a Julia +# repository needs. +# +# ── Behaviour ─────────────────────────────────────────────────────────────── +# * writes mise.toml with [settings] lockfile = true and the [tools] table; +# * leaves the file untouched (byte-identical) when nothing changed; +# * DELETES mise.lock when the tool set changes, because a lock that pins the +# previous toolchain is a false statement of what this repo installs, and +# `mise install` would honour it. The operator regenerates it with +# `just toolchain-refresh` (needs mise; a mint is often offline). +# +# ── Usage ─────────────────────────────────────────────────────────────────── +# render-mise.sh [--root DIR] [--langs "julia zig"] [--check] +# +# --check do not write; exit 1 if mise.toml is not what the tree implies +# +# Exit: 0 = rendered (or already correct); 1 = --check mismatch / render failed; +# 2 = usage or environment error. + +set -uo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" +LANGS="" +CHECK_ONLY=0 +while [ $# -gt 0 ]; do + case "$1" in + --root) ROOT="${2:-}"; shift 2 ;; + --langs) LANGS="${2:-}"; shift 2 ;; + --check) CHECK_ONLY=1; shift ;; + -h|--help) sed -n '2,45p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; + *) echo "render-mise: unknown option: $1" >&2; exit 2 ;; + esac +done +[ -d "$ROOT" ] || { echo "render-mise: not a directory: $ROOT" >&2; exit 2; } +ROOT="$(cd "$ROOT" && pwd)" + +LIB="$ROOT/build/just/provision-lib.sh" +[ -f "$LIB" ] || { echo "render-mise: $LIB is missing; the language table is not guessable" >&2; exit 2; } + +lib() { ( cd "$ROOT" && PROVISION_ROOT="$ROOT" bash "$LIB" "$@" 2>/dev/null ); } +[ -n "$LANGS" ] || LANGS="$(lib langs | tr '\n' ' ')" +LANGS="$(echo "$LANGS" | xargs)" +# Pass the language list explicitly: `mise-tools` without arguments re-detects +# from the tree, which is what made --langs cosmetic — it relabelled the file +# 'the toolchain for this repository (julia)' while installing the docs +# toolchain, so a fixture that asked for julia got just/shellcheck/lychee. +# shellcheck disable=SC2086 +TOOLS="$(lib mise-tools $LANGS | tr '\n' ' ' | xargs)" +if [ -z "$TOOLS" ]; then + echo "render-mise: the engine returned no tools for languages '${LANGS}'" >&2 + exit 2 +fi + +render() { + cat < Deno > pnpm from one package.json (LANGUAGE-POLICY §1.4). +# +# Hand-edited project tools belong below the table's end, never by replacing it: +# \`scripts/check-mise-language.sh\` fails when a tool matches no detected +# language, and when a detected language's tool is missing. + +[settings] +lockfile = true + +[tools] +EOF + for t in $TOOLS; do + case "$t" in + trivy) echo "trivy = \"latest\" # just deps-audit" ;; + shellcheck) echo "shellcheck = \"latest\" # the shell scripts" ;; + just) echo "just = \"latest\"" ;; + *) printf '%s = "latest"\n' "$t" ;; + esac + done +} + +NEW="$(render)" +CURRENT="" +[ -f "$ROOT/mise.toml" ] && CURRENT="$(cat "$ROOT/mise.toml")" + +if [ "$NEW" = "$CURRENT" ]; then + echo "mise.toml already matches the declared languages (${LANGS}) — unchanged" + exit 0 +fi + +if [ "$CHECK_ONLY" -eq 1 ]; then + # --check compares the TOOLCHAIN, not the prose. Comparing the whole rendered + # file made the check impossible to pass on any repository that wrote its own + # header — the template itself included — so it was a permanently red light + # rather than a finding, and a permanently red light is not a check. + # It still fails, which is the part that matters: a missing tool, a foreign + # tool, or a toolchain rendered for the wrong language all differ as a SET. + declare_tools() { + awk ' + /^[[:space:]]*\[tools\][[:space:]]*$/ { t = 1; next } + /^[[:space:]]*\[/ { t = 0 } + t && /^[[:space:]]*("[^"]*"|\047[^\047]*\047|[A-Za-z0-9_.-]+)[[:space:]]*=/ { + line = $0 + sub(/[[:space:]]*=.*/, "", line) + gsub(/^[[:space:]]+|[[:space:]]+$/, "", line) + gsub(/^["\047]|["\047]$/, "", line) + print line + }' "$1" + } + HAVE="$(declare_tools "$ROOT/mise.toml" 2>/dev/null | sort -u | xargs)" + WANT="$(printf '%s\n' $TOOLS | sort -u | xargs)" + if [ "$HAVE" = "$WANT" ]; then + echo "mise.toml declares exactly this tree's toolchain (${LANGS}) — ok" + exit 0 + fi + echo "mise.toml does NOT declare this tree's toolchain (${LANGS})" >&2 + echo " is: ${HAVE:-}" >&2 + echo " want: ${WANT}" >&2 + echo " rewrite it with: scripts/render-mise.sh --root ." >&2 + exit 1 +fi + +# The OLD tool set, before overwriting: needed to decide about mise.lock. +OLD_TOOLS="" +if [ -f "$ROOT/mise.toml" ]; then + OLD_TOOLS="$(awk ' + /^[[:space:]]*\[tools\][[:space:]]*$/ { t = 1; next } + /^[[:space:]]*\[/ { t = 0 } + t && /^[[:space:]]*[A-Za-z0-9_.-]+[[:space:]]*=/ { + line = $0; sub(/[[:space:]]*=.*/, "", line) + gsub(/^[[:space:]]+|[[:space:]]+$/, "", line); print line + }' "$ROOT/mise.toml" | sort -u | xargs 2>/dev/null)" +fi + +printf '%s\n' "$NEW" > "$ROOT/mise.toml" +echo "mise.toml rendered for: ${LANGS:-?}" +echo " tools: $(echo "$TOOLS" | xargs)" +OLD_SORTED="$(printf '%s\n' $OLD_TOOLS | sort | xargs 2>/dev/null)" +NEW_SORTED="$(printf '%s\n' $TOOLS | sort | xargs 2>/dev/null)" +if [ -f "$ROOT/mise.lock" ] && [ "$OLD_SORTED" != "$NEW_SORTED" ]; then + rm -f "$ROOT/mise.lock" + echo " mise.lock removed: it pinned the previous toolchain, which is no longer" + echo " this repository's. Regenerate with: just toolchain-refresh (needs mise)." +fi +exit 0 diff --git a/scripts/resolve-template-pin.sh b/scripts/resolve-template-pin.sh new file mode 100755 index 00000000..d7af5f60 --- /dev/null +++ b/scripts/resolve-template-pin.sh @@ -0,0 +1,186 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# resolve-template-pin.sh — name the TEMPLATE commit a tree was minted from. +# +# `just repo-init` records that commit in the deed's (provenance) and +# (variant) clauses. It used to read it from local git (`git rev-parse HEAD`), +# which is right only inside a checkout OF the template. GitHub's "Use this +# template" button instead creates a new repository whose one root commit has +# the template's tree but none of its history, and repo-init then runs inside +# THAT repository. Local HEAD is the child's own commit. Measured on +# metadatastician/lintel, 2026-10-14: the mint recorded +# :template-branch "claude/mint-lintel" :template-commit "197ebf0…" +# a branch and commit of lintel itself, absent from rsr-template-repo. The +# answer-file then pointed at nothing, and the drift gate it feeds had no +# parent to diff against. +# +# Two cases, decided by the checkout's own origin, never guessed: +# +# origin IS the template → this is a template checkout. Local HEAD is the +# truth about what is in hand, including unpushed +# work (the #203 rationale), so it is recorded. +# origin is anything else → this is a child (or an exported copy). The +# template commit is found by TREE EQUALITY: a +# commit of the template whose tree equals the +# child's root-commit tree, or failing that the +# tree of the work tree as it stands. Equal trees +# are equal content, byte for byte — the same +# proof check-template-conformance.sh uses for +# leaked branches. No match is a loud failure; +# the child's own HEAD is never recorded. +# +# Usage: +# resolve-template-pin.sh --slug OWNER/REPO [--url URL] [--commit SHA] [--dir DIR] +# +# --slug the template's owner/repo (repo-init derives it from the Justfile) +# --url where to read the template's history +# (default https://github.com/OWNER/REPO.git; a local path works) +# --commit assert the template commit instead of searching; it must exist in +# the template's history, and its own tree is what gets recorded +# --dir the checkout being minted (default .) +# +# Output on success, one per line: branch=… commit=… tree=… source=… +# source is one of template-checkout | root-commit | work-tree | asserted +# Exit: 0 resolved; 1 not resolvable (reason on stderr); 2 usage. +set -euo pipefail + +SLUG="" URL="" COMMIT="" DIR="." +while [ $# -gt 0 ]; do + case "$1" in + --slug) SLUG="${2:-}"; shift 2 ;; + --url) URL="${2:-}"; shift 2 ;; + --commit) COMMIT="${2:-}"; shift 2 ;; + --dir) DIR="${2:-}"; shift 2 ;; + *) echo "resolve-template-pin: unknown argument: $1" >&2; exit 2 ;; + esac +done +[[ "$SLUG" =~ ^[A-Za-z0-9._-]+/[A-Za-z0-9._-]+$ ]] \ + || { echo "resolve-template-pin: --slug OWNER/REPO is required (got '${SLUG}')" >&2; exit 2; } +URL="${URL:-https://github.com/${SLUG}.git}" + +die() { echo "resolve-template-pin: $*" >&2; exit 1; } + +git -C "$DIR" rev-parse --is-inside-work-tree >/dev/null 2>&1 \ + || die "$DIR is not a git work tree; repo-init needs one to know what it is minting" + +# slug_of URL — owner/repo of a git URL, lower-cased; nothing for a bare path +# with fewer than two components. Same normalisation as +# check-template-conformance.sh (strip .git first, then scheme, then git@). +slug_of() { + printf '%s' "$1" \ + | sed -E 's|/+$||; s|\.git$||; s|^[a-zA-Z][a-zA-Z0-9+.-]*://||; s|^[^@/]*@||; s|:|/|' \ + | awk -F/ 'NF>=2 {print tolower($(NF-1)"/"$NF)}' +} +ORIGIN="$(git -C "$DIR" config --get remote.origin.url 2>/dev/null || true)" +HEAD_SHA="$(git -C "$DIR" rev-parse --verify -q HEAD 2>/dev/null || true)" +want_slug="$(printf '%s' "$SLUG" | tr '[:upper:]' '[:lower:]')" + +# ── Case 1: a checkout of the template itself ────────────────────────────── +if [ -z "$COMMIT" ] && [ -n "$ORIGIN" ] && [ "$(slug_of "$ORIGIN")" = "$want_slug" ]; then + [ -n "$HEAD_SHA" ] || die "template checkout $DIR has no commit at HEAD" + branch="$(git -C "$DIR" rev-parse --abbrev-ref HEAD)" + [ "$branch" != HEAD ] || branch=UNASSIGNED + printf 'branch=%s\ncommit=%s\ntree=%s\nsource=template-checkout\n' \ + "$branch" "$HEAD_SHA" "$(git -C "$DIR" rev-parse 'HEAD^{tree}')" + exit 0 +fi + +# ── Case 2: a child, or an exported copy ─────────────────────────────────── +# Candidate trees, strongest first. A root commit is what "Use this template" +# wrote; it stays the template's tree even after the child grows commits. +CANDS=() +if [ -n "$HEAD_SHA" ]; then + while IFS= read -r root; do + [ -n "$root" ] && CANDS+=("$(git -C "$DIR" rev-parse "${root}^{tree}")") + done < <(git -C "$DIR" rev-list --max-parents=0 HEAD) +fi +# The work tree as `git add -A` would commit it (ignored paths excluded). Its +# objects go to a scratch store, so the checkout's own .git is not written. +SCRATCH="$(mktemp -d)" +trap 'rm -rf "$SCRATCH"' EXIT +GIT_DIR_ABS="$(cd "$DIR" && cd "$(git rev-parse --git-common-dir)" && pwd)" +mkdir -p "$SCRATCH/objects" +wt_tree="$(cd "$DIR" && GIT_INDEX_FILE="$SCRATCH/index" GIT_OBJECT_DIRECTORY="$SCRATCH/objects" \ + GIT_ALTERNATE_OBJECT_DIRECTORIES="$GIT_DIR_ABS/objects" \ + sh -c 'git add -A . && git write-tree')" \ + || die "could not compute the tree of the work tree in $DIR" +CANDS+=("$wt_tree") + +# The template's history, into a scratch bare repo. Over the network only the +# commits are needed (tree:0). A local path is cloned whole instead: that is +# cheap (hardlinks), and a filtered clone of a SHALLOW local source makes git +# lazily fetch the missing objects back from it, which deadlocked here +# (git 2.43, measured 2026-10-20). +TMPL="$SCRATCH/template.git" +FILTER=(--filter=tree:0) +case "$URL" in *://*|*@*:*) ;; *) FILTER=() ;; esac +if ! git clone -q --bare --no-tags "${FILTER[@]}" "$URL" "$TMPL" 2>"$SCRATCH/clone.err"; then + sed 's/^/ /' "$SCRATCH/clone.err" >&2 + die "cannot read the template's history from $URL + Set RSR_TEMPLATE_URL to a reachable clone of ${SLUG} (a local path works)." +fi +DEFAULT="$(git -C "$TMPL" symbolic-ref -q --short HEAD 2>/dev/null || true)" +if [ -n "$DEFAULT" ] && ! git -C "$TMPL" show-ref --verify --quiet "refs/heads/$DEFAULT"; then + DEFAULT="" +fi +# A detached source HEAD (a CI checkout of a pull request) is still history. +git -C "$TMPL" rev-parse -q --verify HEAD >/dev/null 2>&1 \ + && git -C "$TMPL" update-ref refs/source/HEAD HEAD + +# branch_of SHA — the default branch when it holds SHA, else the first branch +# that does, else UNASSIGNED (reachable only from a detached source HEAD). +branch_of() { + if [ -n "$DEFAULT" ] && git -C "$TMPL" merge-base --is-ancestor "$1" "refs/heads/$DEFAULT" 2>/dev/null; then + echo "$DEFAULT"; return + fi + local b + b="$(git -C "$TMPL" for-each-ref --count=1 --contains "$1" --format='%(refname:short)' refs/heads)" + echo "${b:-UNASSIGNED}" +} + +if [ -n "$COMMIT" ]; then + git -C "$TMPL" cat-file -e "${COMMIT}^{commit}" 2>/dev/null \ + || die "asserted template commit $COMMIT is not in the history of $URL" + COMMIT="$(git -C "$TMPL" rev-parse "${COMMIT}^{commit}")" + tree="$(git -C "$TMPL" rev-parse "${COMMIT}^{tree}")" + case " ${CANDS[*]} " in + *" $tree "*) ;; + *) echo "resolve-template-pin: WARN: the tree in hand differs from asserted $COMMIT's tree $tree" >&2 ;; + esac + printf 'branch=%s\ncommit=%s\ntree=%s\nsource=asserted\n' "$(branch_of "$COMMIT")" "$COMMIT" "$tree" + exit 0 +fi + +# Newest first along the default branch, then anywhere in the history. +REFS=() +[ -n "$DEFAULT" ] && REFS+=("refs/heads/$DEFAULT") +n=0 +for t in "${CANDS[@]}"; do + n=$((n + 1)) + for scope in "${REFS[@]}" --all; do + # awk reads to the end rather than exiting at the first hit: an early exit + # SIGPIPEs git log on a long history, and pipefail made that fatal + # (exit 141 against the real rsr-template-repo, 2026-10-20). + hit="$(git -C "$TMPL" log --format='%H %T' "$scope" | awk -v t="$t" '!found && $2 == t { print $1; found = 1 }')" + if [ -n "$hit" ]; then + if [ "$t" = "$wt_tree" ] && [ "$n" -eq "${#CANDS[@]}" ]; then src="work-tree"; else src="root-commit"; fi + printf 'branch=%s\ncommit=%s\ntree=%s\nsource=%s\n' "$(branch_of "$hit")" "$hit" "$t" "$src" + exit 0 + fi + done +done + +{ + echo "resolve-template-pin: no commit of ${SLUG} (read from $URL) has the tree this repo was minted from." + echo " searched for: ${CANDS[*]}" + echo " (root-commit trees first, then the current work tree)" + echo " This is a child of the template (origin ${ORIGIN:-}), so its own HEAD" + echo " is not a template commit and will not be recorded as one." + echo " Fix one of:" + echo " - mint before changing the tree the template gave you;" + echo " - RSR_TEMPLATE_URL= if the template commit is not on ${URL};" + echo " - RSR_TEMPLATE_COMMIT= to assert the template commit you took." +} >&2 +exit 1 diff --git a/scripts/rsr-campaign.sh b/scripts/rsr-campaign.sh index 27431f6e..834f321f 100644 --- a/scripts/rsr-campaign.sh +++ b/scripts/rsr-campaign.sh @@ -49,7 +49,8 @@ # # Per repository, per path: # -# declared diverged -> SKIPPED (the repo's VARIANT.a2ml says so) +# declared diverged -> SKIPPED (the repo deed's (variant) clause says so) +# retired VARIANT.a2ml -> BLOCKED (whole repo; migrate it to the deed first) # absent in repo -> ADDED # present, differs -> UPDATED # present, identical -> UNCHANGED @@ -96,6 +97,8 @@ set -euo pipefail PROG="$(basename "$0")" MANIFEST=""; REPOS_FILE=""; SPINE=""; WORK_DIR="" +# The deed reader ships beside this script, whatever --spine names. +CAMPAIGN_READ="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/deed-field.sh" BATCH=""; BATCH_SIZE=25; PUSH=0; APPLY=0; BRANCH=""; REPORT=""; BASE_REF="" ALLOW_TOKENS=0; SUBSTITUTE=1; QUIET=0 @@ -242,26 +245,22 @@ substitute() { # src-file repo-name -> stdout # --------------------------------------------------------------------------- # Divergence declarations # --------------------------------------------------------------------------- -# If the repository carries a VARIANT.a2ml, honour it: a path it declares +# If the repository's deed carries a (variant) clause, honour it: a path it declares # diverged is a decision already made, and a campaign must not silently reverse # a decision. Matches check-variant-drift.sh's in_list semantics, including the # 'dir/' prefix form. declared_diverged() { # repo-path path -> 0 if declared diverged - local dir="$1" want="$2" contract="$1/.machine_readable/descriptiles/VARIANT.a2ml" - [ -f "$contract" ] || return 1 - local e + local dir="$1" want="$2" deed e + deed="$(bash "$CAMPAIGN_READ" --find "$dir" 2>/dev/null)" || return 1 while IFS= read -r e; do [ -z "$e" ] && continue case "$e" in */) case "$want" in "$e"*) return 0 ;; esac ;; *) [ "$want" = "$e" ] && return 0 ;; esac - done < <(awk ' - $0 == "[paths.diverged]" || $0 == "[paths.diverged-pending-upstream]" || - $0 == "[paths.operational-state]" { insec = 1; next } - insec && /^\[/ { insec = 0 } - insec && /^ *"/ { line = $0; sub(/^ *"/,"",line); sub(/".*$/,"",line); print line } - ' "$contract") + done < <(for k in diverged diverged-pending-upstream operational-state; do + bash "$CAMPAIGN_READ" --list "$deed" variant/paths "$k" 2>/dev/null || true + done) return 1 } @@ -282,7 +281,7 @@ excluded() { # path -> 0 if excluded by the manifest REPORT="${REPORT:-$WORK_DIR/campaign-report.tsv}" printf 'repo\tpath\toutcome\tdetail\n' > "$REPORT" -ADDED=0; UPDATED=0; UNCHANGED=0; SKIPPED=0; REFUSED=0; NOCHANGE=0; FAILED=0 +ADDED=0; UPDATED=0; SKIPPED=0; REFUSED=0; NOCHANGE=0; FAILED=0 for repo in "${SELECTED[@]}"; do [ -z "$repo" ] && continue @@ -313,6 +312,15 @@ for repo in "${SELECTED[@]}"; do FAILED=$((FAILED+1)); continue fi + # A repo still carrying the retired VARIANT.a2ml has divergence decisions + # this script no longer reads. Treating it as "no contract" would let the + # campaign overwrite paths the repo declared diverged, so it is refused. + if [ -f "$dir/.machine_readable/descriptiles/VARIANT.a2ml" ]; then + printf '%s\t-\tBLOCKED\tcarries retired VARIANT.a2ml; migrate it to the deed (variant) clause first\n' "$repo" >> "$REPORT" + note " $repo: BLOCKED (retired VARIANT.a2ml)" + FAILED=$((FAILED+1)); continue + fi + repo_changed=0 repo_added=0; repo_updated=0; repo_skipped=0; repo_refused=0 @@ -320,14 +328,14 @@ for repo in "${SELECTED[@]}"; do while IFS= read -r rel; do [ -z "$rel" ] && continue case "$rel" in - *.gitkeep|*/.gitkeep) continue ;; + *.gitkeep) continue ;; esac if excluded "$rel"; then printf '%s\t%s\tEXCLUDED\tmanifest exclude\n' "$repo" "$rel" >> "$REPORT" repo_skipped=$((repo_skipped+1)); continue fi if declared_diverged "$dir" "$rel"; then - printf '%s\t%s\tDIVERGED\tdeclared in VARIANT.a2ml\n' "$repo" "$rel" >> "$REPORT" + printf '%s\t%s\tDIVERGED\tdeclared in the deed (variant) clause\n' "$repo" "$rel" >> "$REPORT" repo_skipped=$((repo_skipped+1)); continue fi diff --git a/scripts/run-proven-suite.sh b/scripts/run-proven-suite.sh new file mode 100755 index 00000000..35a7c2c6 --- /dev/null +++ b/scripts/run-proven-suite.sh @@ -0,0 +1,229 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# Unified 3-outcome test & proof runner grounded in hyperpolymath/proven-tests-and-benches. +# +# Usage: scripts/run-proven-suite.sh [--require-zig] [--bench] [--report FILE] +# +# Exit contract: +# 0 = every tier passed (Silence on clean tree + Firing on every negative mutant) +# 1 = a subject check, proof honesty lint, or contract test failed +# 2 = setup / cannot-look failure (missing tool or missing suite — never a pass) +set -uo pipefail + +REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +REQUIRE_ZIG=0 +RUN_BENCH=0 +REPORT_PATH="" +OWNED_REPORT_TMP="" +BENCH_TMP="" + +# Remove the runner-owned temporary report directory and benchmark file, if set. +cleanup() { + [ -n "$OWNED_REPORT_TMP" ] && rm -rf "$OWNED_REPORT_TMP" + [ -n "$BENCH_TMP" ] && rm -f "$BENCH_TMP" +} +trap cleanup EXIT + +while [ "$#" -gt 0 ]; do + case "$1" in + --require-zig) REQUIRE_ZIG=1; shift ;; + --bench) RUN_BENCH=1; shift ;; + --report) + [ "$#" -ge 2 ] || { echo "run-proven-suite: --report needs a path" >&2; exit 2; } + REPORT_PATH="$2" + shift 2 + ;; + *) echo "run-proven-suite: unknown option '$1'" >&2; exit 2 ;; + esac +done + +cd "$REPO_ROOT" || exit 2 + +if [ -z "$REPORT_PATH" ]; then + OWNED_REPORT_TMP="$(mktemp -d)" + REPORT_PATH="$OWNED_REPORT_TMP/proven-tests-report.json" +else + mkdir -p "$(dirname "$REPORT_PATH")" || { echo "run-proven-suite: cannot create report parent directory" >&2; exit 2; } +fi + +subject_failures=0 +setup_failures=0 + +# run_lane LABEL COMMAND... — run a lane and accumulate its outcome without +# propagating its exit status: 2 increments setup_failures; other nonzero +# statuses increment subject_failures. +run_lane() { + local label="$1" rc=0 + shift + printf '==> [proven-suite] %s\n' "$label" + "$@" || rc=$? + case "$rc" in + 0) printf ' PASS (0): %s\n' "$label" ;; + 2) + printf ' INERT/SETUP (2): %s\n' "$label" >&2 + setup_failures=$((setup_failures + 1)) + # A workflow annotation, because the lane table is printed at the end of a + # 200-line log: a red job whose only account of itself is "Process + # completed with exit code 1" cannot be triaged without the raw log, and + # the annotations endpoint is the one part of that failure GitHub exposes + # to the API. + [ "${GITHUB_ACTIONS:-}" = "true" ] && \ + printf '::warning title=proven-suite lane could not run::%s (exit 2)\n' "$label" + ;; + *) + printf ' FAIL (%d): %s\n' "$rc" "$label" >&2 + subject_failures=$((subject_failures + 1)) + [ "${GITHUB_ACTIONS:-}" = "true" ] && \ + printf '::error title=proven-suite lane failed::%s (exit %d)\n' "$label" "$rc" + ;; + esac +} + +# require_file PATH — return 0 for an existing regular file; otherwise increment +# setup_failures and return 1. +require_file() { + if [ ! -f "$1" ]; then + printf ' INERT/SETUP (2): missing required gate script: %s\n' "$1" >&2 + setup_failures=$((setup_failures + 1)) + return 1 + fi + return 0 +} + +# ── Tier 1: Idris2 honesty lint + proof-ladder report ──────────────────────── +if require_file scripts/check-escape-hatches.sh; then + run_lane "Idris2 proof escape-hatch & totality gate" \ + bash scripts/check-escape-hatches.sh src verification .machine_readable/coaptation +fi + +mapfile -t PROOF_FILES < <(find src verification .machine_readable/coaptation -name '*.idr' -type f | LC_ALL=C sort) + +# Only claim "Actually-Proven" when the Idris2 typechecker discharges every +# module in the corpus; static escape-hatch totality verification without the +# Idris2 kernel is recorded honestly as "Static-Checked" (never overclaiming). +PROOF_PROVENANCE="Static-Checked" +if command -v idris2 >/dev/null 2>&1; then + idris_ok=1 + for pf in "${PROOF_FILES[@]}"; do + if ! idris2 --check "$pf" >/dev/null 2>&1; then + idris_ok=0 + subject_failures=$((subject_failures + 1)) + printf ' FAIL (1): idris2 --check %s\n' "$pf" >&2 + fi + done + if [ "$idris_ok" -eq 1 ] && [ "${#PROOF_FILES[@]}" -gt 0 ]; then + PROOF_PROVENANCE="Actually-Proven" + fi +fi + +{ + printf '{"entries":[{"name":"rsr-idris2-proof-corpus","proof_ladder":[' + first=1 + for pf in "${PROOF_FILES[@]}"; do + [ "$first" -eq 1 ] || printf ',' + first=0 + printf '{"proof_file":"%s"}' "$pf" + done + printf '],"provenance":"%s"}],"schema_version":1}\n' "$PROOF_PROVENANCE" +} > "$REPORT_PATH" + +if require_file scripts/emit-aggregate-inputs.sh; then + run_lane "Proof-ladder aggregation (emit-aggregate-inputs)" \ + bash scripts/emit-aggregate-inputs.sh "$REPORT_PATH" +fi + +# ── Tier 2: Repository invariant & estate data-format gates ────────────────── +require_file scripts/check-root-shape.sh && \ + run_lane "Root shape bidirectional allowlist" bash scripts/check-root-shape.sh . +require_file scripts/check-ijson-jcs.sh && \ + run_lane "I-JSON (RFC 7493) + JCS (RFC 8785) canonical gate" bash scripts/check-ijson-jcs.sh --enforce . +require_file scripts/check-lock-sync.sh && \ + run_lane "Workflow actions.lock integrity" bash scripts/check-lock-sync.sh .github/workflows +require_file scripts/check-required-contexts.sh && \ + run_lane "Required status contexts producibility gate" bash scripts/check-required-contexts.sh . +# The verdict grid's edges: a workflow_run that names no workflow's `name:`, an +# artifact the named producer never uploads, a pin the producer moved without +# the reporter, or one tool pinned at two commits. Each fails silently in +# production, so it is checked here as well as in the CICD Squabbler gate. +require_file scripts/check-workflow-edges.sh && \ + run_lane "Workflow edges (producer -> verdict grid)" bash scripts/check-workflow-edges.sh . +require_file scripts/check-hypatia-ignore.sh && \ + run_lane "Hypatia exemption meta-rules (.hypatia-ignore)" bash scripts/check-hypatia-ignore.sh . +# The layer order, the ownership table and the clash resolutions are stated in +# .machine_readable/policies/hypatia-rule-order.json and implemented across four +# files. This lane is what keeps that statement from drifting away from them. +require_file scripts/check-hypatia-rule-order.sh && \ + run_lane "Hypatia rule order & clash resolution" bash scripts/check-hypatia-rule-order.sh . +require_file .github/hooks/validate-deed.sh && \ + run_lane "CHORA deed validation & retired .a2ml refusal" bash .github/hooks/validate-deed.sh +require_file .github/hooks/validate-k9.sh && \ + run_lane "K9 pedigree & contract validation" bash .github/hooks/validate-k9.sh + +# ── Tier 3: Silence + Firing contract & E2E test suites ────────────────────── +require_file tests/proven_suite_test.sh && \ + run_lane "Proven tools Silence + Firing self-tests" bash tests/proven_suite_test.sh +require_file tests/workflows/check_ijson_jcs_test.sh && \ + run_lane "I-JSON/JCS Silence + Firing self-tests" bash tests/workflows/check_ijson_jcs_test.sh +require_file tests/workflows/squabble_gate_test.sh && \ + run_lane "CICD-Squabbler & required-context Silence + Firing self-tests" bash tests/workflows/squabble_gate_test.sh +require_file tests/shape/check_root_shape_test.sh && \ + run_lane "Root shape Silence + Firing self-tests" bash tests/shape/check_root_shape_test.sh +require_file www/tests/run-all.sh && \ + run_lane "Site & .well-known boundary + planted controls" bash www/tests/run-all.sh + +# ── Tier 4: Zig FFI unit tests + E2E mint instantiation ────────────────────── +# Run Zig FFI tests in a temporary copy with project placeholders filled in. +# Remove the copy on return and propagate the zig build test exit status. +run_zig_ffi_tests() { + local work tok_lc tok_uc + work="$(mktemp -d)" + # shellcheck disable=SC2064 + trap "rm -rf '$work'" RETURN + cp -R src/interface/ffi "$work/ffi" + tok_lc="{{""project}}" + tok_uc="{{""PROJECT}}" + sed -i -e "s/${tok_lc}/test_project/g" -e "s/${tok_uc}/TEST_PROJECT/g" \ + "$work/ffi/build.zig" "$work/ffi/src/main.zig" "$work/ffi/test/integration_test.zig" 2>/dev/null || true + (cd "$work/ffi" && zig build test) +} + +if command -v zig >/dev/null 2>&1; then + run_lane "Zig FFI ABI layout & memory-leak unit tests" run_zig_ffi_tests +elif [ "$REQUIRE_ZIG" -eq 1 ]; then + printf ' INERT/SETUP (2): zig compiler required (--require-zig) but missing on PATH\n' >&2 + setup_failures=$((setup_failures + 1)) +else + printf '==> [proven-suite] Zig FFI unit tests: skipped locally (pass --require-zig in CI to fail-closed)\n' +fi + +if command -v rustc >/dev/null 2>&1 && command -v just >/dev/null 2>&1; then + require_file tests/e2e/template_instantiation_test.sh && \ + run_lane "Template mint instantiation E2E" bash tests/e2e/template_instantiation_test.sh . +fi + +# ── Tier 5: Benchmark regression gate (optional --bench) ───────────────────── +if [ "$RUN_BENCH" -eq 1 ]; then + if ! command -v jq >/dev/null 2>&1; then + printf ' INERT/SETUP (2): jq required for --bench regression gate\n' >&2 + setup_failures=$((setup_failures + 1)) + elif require_file benches/template_bench.sh && require_file scripts/check-bench-regression.sh && require_file benches/baseline.json; then + BENCH_TMP="$(mktemp)" + run_lane "Template benchmark execution (--json)" \ + bash -c "bash benches/template_bench.sh --json . > '$BENCH_TMP'" + run_lane "Six-Sigma leave-one-out benchmark regression gate" \ + bash scripts/check-bench-regression.sh "$BENCH_TMP" benches/baseline.json + fi +fi + +if [ "$setup_failures" -gt 0 ]; then + printf 'proven-suite: SETUP/INERT FAILURE (%d setup, %d subject)\n' "$setup_failures" "$subject_failures" >&2 + exit 2 +fi +if [ "$subject_failures" -gt 0 ]; then + printf 'proven-suite: SUBJECT FAILURE (%d failing lane(s))\n' "$subject_failures" >&2 + exit 1 +fi +printf 'proven-suite: ALL LANES PASSED\n' +exit 0 diff --git a/scripts/strip-instruction-blocks.rs b/scripts/strip-instruction-blocks.rs index eb2060d2..b33f5ed3 100644 --- a/scripts/strip-instruction-blocks.rs +++ b/scripts/strip-instruction-blocks.rs @@ -12,19 +12,20 @@ // terminator of a preceding comment. That is what keeps an SPDX comment that // sits immediately above an instructions block intact. // -// Usage: strip-instruction-blocks.rs [ROOT] (default ROOT = .) +// Usage: strip-instruction-blocks.rs FILE... or ... - < newline-separated paths + +#![forbid(unsafe_code)] use std::env; use std::fs; +use std::io::{self, Read}; use std::path::{Path, PathBuf}; +use std::process; const MARKER: &str = "TEMPLATE INSTRUCTIONS"; const OPEN: &str = ""; -/// Directories never descended into. Mirrors the Ruby original. -const SKIP_DIRS: [&str; 5] = [".git", "node_modules", ".venv", "target", "dist"]; - /// Remove every HTML comment whose body contains MARKER, then collapse runs of /// three or more newlines to two. /// @@ -99,70 +100,81 @@ fn collapse_blank_runs(s: &str) -> String { out } -fn process(path: &Path, changed: &mut usize) { - let bytes = match fs::read(path) { - Ok(b) => b, - Err(_) => return, - }; - // Non-UTF-8 and unreadable files are skipped, never rewritten blind. +fn process(path: &Path, changed: &mut usize) -> Result<(), String> { + let bytes = fs::read(path).map_err(|e| format!("{}: {}", path.display(), e))?; + // Non-UTF-8 files are skipped, never rewritten blind. let text = match String::from_utf8(bytes) { Ok(t) => t, - Err(_) => return, + Err(_) => return Ok(()), }; if !text.contains(MARKER) { - return; + return Ok(()); } let updated = strip_blocks(&text); if updated == text { - return; - } - if fs::write(path, updated).is_err() { - return; + return Ok(()); } + fs::write(path, updated).map_err(|e| format!("{}: {}", path.display(), e))?; println!(" instruction block: stripped from {}", path.display()); *changed += 1; + Ok(()) } -fn walk(root: &Path, changed: &mut usize) { - // Explicit stack rather than recursion: deep trees must not blow the stack. - let mut stack: Vec = vec![root.to_path_buf()]; - while let Some(dir) = stack.pop() { - let entries = match fs::read_dir(&dir) { - Ok(e) => e, - Err(_) => continue, - }; - for entry in entries.flatten() { - let path = entry.path(); - let ft = match entry.file_type() { - Ok(ft) => ft, - Err(_) => continue, - }; - if ft.is_symlink() { - continue; - } - if ft.is_dir() { - let skip = path - .file_name() - .and_then(|n| n.to_str()) - .map(|n| SKIP_DIRS.contains(&n)) - .unwrap_or(false); - if skip { - continue; - } - stack.push(path); - continue; - } - if ft.is_file() { - process(&path, changed); - } +/// The files to clean: every argument, where `-` reads one path per line +/// from stdin. A directory is refused rather than walked. This tool used to +/// walk its ROOT argument, and so entered git-ignored caches: minting +/// metadatastician/lintel it edited the pinned sibling checkouts under +/// _build/dependencies/, breaking their pins, and it stripped the fixture +/// blocks of the template's own tests, which the mint's leftover check +/// exempts. Which files belong to a repository is the caller's question +/// (repo-init asks git: its mint_files), not a guess made here. +fn targets(args: &[String]) -> Result, String> { + let mut out = Vec::new(); + for a in args { + if a == "-" { + let mut buf = String::new(); + io::stdin() + .read_to_string(&mut buf) + .map_err(|e| format!("stdin: {}", e))?; + out.extend(buf.lines().filter(|l| !l.is_empty()).map(PathBuf::from)); + } else { + out.push(PathBuf::from(a)); + } + } + for p in &out { + if p.is_dir() { + return Err(format!( + "{} is a directory; pass files (e.g. `git ls-files | {} -`)", + p.display(), + "strip-instruction-blocks" + )); } } + Ok(out) } fn main() { - let root = env::args().nth(1).unwrap_or_else(|| ".".to_string()); + let args: Vec = env::args().skip(1).collect(); + if args.is_empty() { + eprintln!("usage: strip-instruction-blocks FILE... | strip-instruction-blocks - < list"); + process::exit(2); + } + let files = match targets(&args) { + Ok(f) => f, + Err(e) => { + eprintln!("strip-instruction-blocks: {}", e); + process::exit(2); + } + }; let mut changed = 0usize; - walk(Path::new(&root), &mut changed); + for f in &files { + if let Err(e) = process(f, &mut changed) { + // Fail loudly: a file the caller named that cannot be read or + // written is not "clean", it is unchecked. + eprintln!("strip-instruction-blocks: {}", e); + process::exit(1); + } + } if changed > 0 { println!(" instruction blocks: {} file(s) cleaned", changed); } else { diff --git a/scripts/survey-template-damage.sh b/scripts/survey-template-damage.sh new file mode 100755 index 00000000..408298d3 --- /dev/null +++ b/scripts/survey-template-damage.sh @@ -0,0 +1,96 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# survey-template-damage.sh — which already-scaffolded repositories carry the +# damage this template shipped? +# +# A template defect is not one repository's problem. Every repository minted from +# the template while it shipped a nine-runtime `mise.toml`, a floating +# `Containerfile` and unfilled `{{TOKEN}}`s carries the same damage, permanently +# — the mint copies the files once and nothing goes back to fix them. +# +# This script takes repository names, clones each shallowly, and runs THIS +# template's gates against the clone. It is deliberately not a grep: the gates +# are the same code that a minted repository runs, so a repository reported +# clean here is clean by the same standard the next mint will be held to. +# +# Usage: +# scripts/survey-template-damage.sh hyperpolymath/A.jl hyperpolymath/B.jl … +# scripts/survey-template-damage.sh --from-search 'org:hyperpolymath filename:Justfile "{{PROJECT_NAME}}"' +# options: --keep (leave the clones), --tsv (machine-readable table only) +# +# Exit: 0 survey completed (whatever it found); 1 could not complete; 2 usage. +# This is a survey: it never edits a repository. + +set -uo pipefail + +SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +GATES_DIR="$SELF_DIR" +KEEP=0 +TSV=0 +QUERY="" +REPOS=() + +while [ $# -gt 0 ]; do + case "$1" in + --keep) KEEP=1; shift ;; + --tsv) TSV=1; shift ;; + --from-search) QUERY="${2:-}"; shift 2 ;; + -h|--help) sed -n '2,40p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; + -*) echo "survey-template-damage: unknown option: $1" >&2; exit 2 ;; + *) REPOS+=("$1"); shift ;; + esac +done + +if [ -n "$QUERY" ]; then + command -v gh >/dev/null 2>&1 || { echo "survey: --from-search needs gh" >&2; exit 2; } + # Code search caps at 100 items per page and 1000 results; that is enough for + # an inventory, and the count printed below says when it is not. + mapfile -t FOUND < <(gh api -X GET search/code -f q="$QUERY" -f per_page=100 \ + --jq '[.items[].repository.full_name] | unique | .[]' 2>/dev/null) + TOTAL="$(gh api -X GET search/code -f q="$QUERY" --jq '.total_count' 2>/dev/null || echo '?')" + echo "# search: $QUERY" + echo "# search hits (files): $TOTAL; repositories listed: ${#FOUND[@]}" + REPOS+=("${FOUND[@]}") +fi + +if [ "${#REPOS[@]}" -eq 0 ]; then + echo "survey-template-damage: no repositories given" >&2 + echo " pass owner/name arguments, or --from-search ''" >&2 + exit 2 +fi + +WORK="$(mktemp -d)" +[ "$KEEP" -eq 1 ] && echo "# clones kept in $WORK" || trap 'rm -rf "$WORK"' EXIT + +gate() { # $1 gate script, $2 repo dir, rest: extra gate args + local script="$1" dir="$2"; shift 2 + local out st + out="$(bash "$GATES_DIR/$script" --root "$dir" "$@" 2>&1)"; st=$? + if [ "$st" -eq 0 ]; then printf 'CLEAN'; return; fi + printf '%s' "$(printf '%s\n' "$out" \ + | sed -E 's/\x1b\[[0-9;]*m//g' \ + | grep -m1 -E '^ *FAIL' \ + | sed -E 's/^ *FAIL *//' | tr '\t' ' ')" +} + +printf 'repo\tmise\tspdx\tpins\ttokens\n' +for repo in "${REPOS[@]}"; do + dir="$WORK/$(printf '%s' "$repo" | tr '/' '_')" + if ! git clone --depth 1 --quiet "https://github.com/$repo.git" "$dir" 2>/dev/null; then + printf '%s\tCLONE-FAILED\t-\t-\t-\n' "$repo" + continue + fi + # --detect: these repositories were minted before the provisioning engine + # shipped with them, so the gate detects the languages from markers. + m="$(gate check-mise-language.sh "$dir" --detect)" + s="$(gate check-spdx-headers.sh "$dir")" + c="$(gate check-container-pins.sh "$dir")" + t="$(gate check-mint-tokens.sh "$dir")" + printf '%s\t%s\t%s\t%s\t%s\n' "$repo" "$m" "$s" "$c" "$t" + # --keep exists so an operator can open the checkout behind a verdict. This + # line deleted it anyway, leaving an empty directory and no way to reproduce + # what the gate saw. + [ "$KEEP" -eq 1 ] || rm -rf "$dir" +done diff --git a/scripts/sweep-wellknown.sh b/scripts/sweep-wellknown.sh index 1dc6db75..671898f7 100755 --- a/scripts/sweep-wellknown.sh +++ b/scripts/sweep-wellknown.sh @@ -57,7 +57,6 @@ TREES_DIR="" WORK="" BRANCH="chore/well-known-to-www" MIGRATOR="" -SUITE="" usage() { cat <<'EOF' @@ -204,12 +203,12 @@ fi if [ -n "$BATCH" ]; then start=$(( (BATCH - 1) * BATCH_SIZE )) - REPOS=(${REPOS[@]:$start:$BATCH_SIZE}) + REPOS=("${REPOS[@]:$start:$BATCH_SIZE}") [ ${#REPOS[@]} -gt 0 ] || die "batch $BATCH is empty" note "batch $BATCH of size $BATCH_SIZE: ${#REPOS[@]} repository(ies)" fi if [ -n "$LIMIT" ] && [ "$LIMIT" -lt ${#REPOS[@]} ]; then - REPOS=(${REPOS[@]:0:$LIMIT}) + REPOS=("${REPOS[@]:0:$LIMIT}") fi note "selected ${#REPOS[@]} repository(ies) from $OWNER; work dir $WORK" @@ -222,6 +221,10 @@ gh_api() { # path... "$@" } +# Classify OWNER/$1 for migration: Pages/CDN markers (review-pages) take precedence +# over RSR markers (sweep); repositories with neither need review-other. +# API failures yield unknown and truncated trees yield review-other, both with +# success status. root_wk and www_wk indicate .well-known file presence. classify_repo() { # repo -> "class|root_wk|www_wk|notes"; paths cached in $WORK/trees/ local repo="$1" local json paths="" @@ -287,11 +290,11 @@ classify_repo() { # repo -> "class|root_wk|www_wk|notes"; paths cached in $WORK/ local class if [ "$pages" = yes ]; then - class=review-pages + class="review-pages" elif [ "$rsr" = yes ]; then - class=sweep + class="sweep" else - class=review-other + class="review-other" notes="${notes:+$notes; }no RSR marker found" fi [ -n "$marker" ] && notes="${notes:+$notes; }marker: $marker" diff --git a/scripts/validate-template.sh b/scripts/validate-template.sh index ec785687..775731d3 100755 --- a/scripts/validate-template.sh +++ b/scripts/validate-template.sh @@ -14,6 +14,11 @@ set -euo pipefail REPO_ROOT="${1:-.}" VERBOSE="${2:-0}" +# This script's own directory, for the gates it now delegates to. It was +# referenced by the SPDX phase without ever being set; under `set -euo pipefail` +# that aborted the run at Phase 6 with "SCRIPT_DIR: unbound variable" — the +# validator stopped before its last two phases and reported a bare exit 1. +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" ERRORS=0 WARNINGS=0 @@ -57,9 +62,8 @@ check_file_exists() { # The repo deed's FILENAME carries the repository name (filename dispatch: # _chora.deed, stem = repo slug — deed.abnf v1.0.0), so the check is a -# glob, not a literal. Pre-deed era this slot was 0-AI-MANIFEST.a2ml; the -# family-7 allocation manifest and the ply tree folded into the deed -# (standards#837 pilot). +# glob, not a literal. The family-7 allocation manifest and the ply tree are +# folded into the deed (standards#837 pilot). check_deed_exists() { local description="${1:-}" local f @@ -139,14 +143,6 @@ check_abi_file_exists() { 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 @@ -167,7 +163,13 @@ echo "" check_deed_exists "repo deed (universal AI entry point)" check_file_exists "README.adoc" "High-level pitch" check_file_either "EXPLAINME.adoc" "docs/EXPLAINME.adoc" "Developer deep-dive" -check_file_exists "LICENSE" "License file" +# Either spelling: `LICENSE` is the forge-facing copy, `LICENSE.adoc` the estate +# document (root-allow.txt permits both, requires neither specifically). +if [ -f "$REPO_ROOT/LICENSE" ] || [ -f "$REPO_ROOT/LICENSE.adoc" ]; then + log_pass "License file" +else + log_error "Required file missing: LICENSE (or LICENSE.adoc)" +fi check_file_exists "Justfile" "Task runner" check_file_either "AUDIT.adoc" "docs/AUDIT.adoc" "Release audit gate" @@ -187,11 +189,17 @@ echo "" log_info "Phase 2: Machine-readable metadata (.machine_readable/)" echo "" -check_file_exists ".machine_readable/descriptiles/STATE.a2ml" "Project state" -check_file_exists ".machine_readable/descriptiles/META.a2ml" "Architecture decisions" -check_file_exists ".machine_readable/descriptiles/ECOSYSTEM.a2ml" "Ecosystem position" -check_file_exists ".machine_readable/descriptiles/anchors/ANCHOR.a2ml" "Semantic boundary anchor" -check_file_exists ".machine_readable/policies/MAINTENANCE-AXES.a2ml" "Maintenance axes" +# Project state, architecture axes, ecosystem position, the anchor and the +# maintenance axes are clauses of the repo deed (rsr-template-repo#209). +DEED_FILE=$(bash "$REPO_ROOT/scripts/deed-field.sh" --find "$REPO_ROOT" || true) +for clause in status maturity meta ecosystem anchor policies/maintenance-axes; do + if [ -z "$DEED_FILE" ] || ! bash "$REPO_ROOT/scripts/deed-field.sh" --has "$DEED_FILE" "$clause"; then + log_error "Repo deed lacks the ($clause …) clause" + fi +done +if ! bash "$REPO_ROOT/scripts/check-no-a2ml.sh" "$REPO_ROOT" >/dev/null; then + log_error "Retired .a2ml files present (run scripts/check-no-a2ml.sh)" +fi #============================================================================== # VALIDATION PHASE 3: REQUIRED WORKFLOWS (17 minimum) @@ -217,7 +225,11 @@ REQUIRED_WORKFLOWS=( # none of the 55 repos carrying it ever adopted Bun. This list was not # updated, so it has required two files the template deliberately no longer # ships — which is why validate-template.sh has been red since that merge. - "runtime-policy.yml" + # runtime-policy.yml is folded into governance in turn (standards + # cicd-regularisation spec §14): "Language / package anti-pattern policy" + # fails any tracked package-lock.json and the "JS runtimes" jobs check each + # lock against package.json. So governance.yml is what this list requires. + "governance.yml" "secret-scanner.yml" ) @@ -320,7 +332,7 @@ 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/descriptiles/STATE.a2ml"; do + for file in "$REPO_ROOT/README.adoc" "$REPO_ROOT/Justfile" "$REPO_ROOT"/*_chora.deed; do if [ -f "$file" ]; then if has_placeholder "$file"; then log_warning "File contains unresolved placeholders: $(basename "$file")" @@ -337,51 +349,20 @@ echo "" log_info "Phase 6: SPDX License Headers" echo "" -# Check source files for SPDX headers (excluding build artifacts). -# -# Scans the whole repository, not just src/, and every estate source language — -# not just Idris2 and Zig. -# -# This used to be `find "$REPO_ROOT/src" ... \( -name "*.idr" -o -name "*.zig" \)`. -# That is fine for the template, whose only sources are src/interface/{abi,ffi}, -# but wrong for the repos instantiated from it: a multi-language project keeps -# code in core-zig/, beam/, clients/, normalizer/ and so on, so the scan saw a -# handful of files and printed "SPDX headers: 10/10 (100%)". Measured across all -# languages the same repo was at 172/188 (91%) — the number was not wrong, it was -# answering a much narrower question than it appeared to. +# Check source files for SPDX headers, using the language-derived gate. # -# Uses `git ls-files` so it follows .gitignore and never descends into vendored -# or build directories; falls back to `find` outside a work tree. -SPDX_EXTS='idr|zig|rs|ex|exs|res|resi|factor|fs|lean|jl|gleam|ml|mli|hs|sh|nix|scm' -if git -C "$REPO_ROOT" rev-parse --is-inside-work-tree >/dev/null 2>&1; then - SOURCE_FILES=$(git -C "$REPO_ROOT" ls-files \ - | grep -E "\.($SPDX_EXTS)$" \ - | sed "s|^|$REPO_ROOT/|" || true) +# This phase used to carry its own extension glob (SPDX_EXTS='idr|zig|rs|…'). +# Two problems, both of the fake-gate class: the glob is the same in every repo, +# so the gate cannot notice a language arriving that it does not name; and when +# the glob matched nothing it printed nothing and counted no error — a pass for +# having examined nothing. scripts/check-spdx-headers.sh derives the set from the +# languages the repository declares (via build/just/provision-lib.sh langs), +# scans every matched file with no cap, fails on a declared language with no +# files, and fails when it matched zero files. +if bash "$SCRIPT_DIR/check-spdx-headers.sh" --root "$REPO_ROOT" --quiet; then + log_pass "SPDX headers: every source file of every declared language" else - SOURCE_FILES=$(find "$REPO_ROOT" -type f \ - ! -path "*/.git/*" ! -path "*/.zig-cache/*" ! -path "*/zig-cache/*" \ - ! -path "*/node_modules/*" ! -path "*/target/*" ! -path "*/_build/*" \ - ! -path "*/.lake/*" ! -path "*/deps/*" \ - 2>/dev/null | grep -E "\.($SPDX_EXTS)$" || true) -fi -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 + log_error "SPDX header gate failed — see the findings above (scripts/check-spdx-headers.sh)" fi #============================================================================== @@ -453,11 +434,15 @@ if [ -f "$REPO_ROOT/TOPOLOGY.adoc" ] || [ -f "$REPO_ROOT/TOPOLOGY.md" ] || \ 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 +# CONTRIBUTING may live at root or in .github/, and this estate writes .adoc. +# The check demanded `.md` and failed a repository whose CONTRIBUTING.adoc has +# been there all along — a required-file check that names the wrong spelling is +# a permanent red build, which is indistinguishable from a build nobody reads. +if [ -f "$REPO_ROOT/CONTRIBUTING.md" ] || [ -f "$REPO_ROOT/.github/CONTRIBUTING.md" ] \ + || [ -f "$REPO_ROOT/CONTRIBUTING.adoc" ] || [ -f "$REPO_ROOT/.github/CONTRIBUTING.adoc" ]; then [ "$VERBOSE" = "1" ] && log_pass "Contribution guide found" else - log_error "Required file missing: CONTRIBUTING.md (root or .github/)" + log_error "Required file missing: CONTRIBUTING.{md,adoc} (root or .github/)" fi # Governance can be at root or in docs/governance/ diff --git a/scripts/verdict-grid-lane.sh b/scripts/verdict-grid-lane.sh new file mode 100755 index 00000000..45ba8269 --- /dev/null +++ b/scripts/verdict-grid-lane.sh @@ -0,0 +1,550 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# verdict-grid-lane.sh — collect, render and post the Hypatia verdict grid. +# +# Policy: metadatastician/standards docs/VERDICT-GRID-SPEC.adoc (a findings +# lane has one row per reporter: Hypatia, panic-attack, pons asinorum and every +# gitbot-fleet member the repository enrols). The renderer itself is NOT copied +# here: it stays in standards and is fetched at the pinned commit and checked +# against a recorded sha256, the way scripts/kyaml-format.sh is. A copy in this +# repository would be a second implementation that can drift from the one the +# estate tests; this script only decides WHAT the renderer is given and WHAT +# happens when it cannot run. +# +# WHY THIS IS A SCRIPT AND NOT INLINE SHELL +# +# The previous wiring claimed a grid that did not exist: .github/workflows/ +# README.adoc described a `verdict` job, a `verdict-grid` artifact and a +# `` comment, and no workflow produced any of +# them. The claim survived because nothing could test it. Everything below is +# therefore split into subcommands a test can drive with a stub `gh` and a +# stub renderer: discovery of another workflow's evidence, the renderer's +# absence or corruption, badge validity, and comment create-vs-update. +# +# SUBCOMMANDS +# +# collect Find the run of a producing workflow for one commit, download the +# artifact it produced, and record what was found (or why not). +# render Assemble the renderer's arguments, verify the renderer's digest, +# run it, and validate what it wrote. Never executes an unverified +# renderer; never reports a missing one as a pass. +# comment Post the grid to the pull request, updating the comment it posted +# last time (one comment per lane per PR, found by its marker). +# previous Write the body of the marker comment this lane posted last time, +# so the next render can fill its "since previous revision" column. +# validate Check the shapes of the evidence files (Hypatia array, panic and +# pons status envelopes, enrolment manifest) without rendering. +# +# EXIT CONTRACT (proven-tests-and-benches 3-outcome convention) +# +# 0 did what was asked. For `render`, that includes a grid whose verdict is +# orange or red: the verdict is not this script's exit code. +# 1 the requested work failed (unverified renderer, unreadable output, +# comment API failure). The grid is then absent or replaced by the orange +# "indeterminate" report, never by a green one. +# 2 usage error: a required argument is missing or malformed. +# +# ENVIRONMENT +# +# GH_BIN `gh` to use (default: gh). Tests point this at a stub. +# GITHUB_REPOSITORY owner/name, defaults for --repo. +# GITHUB_OUTPUT when set, `state=` and `evidence=` are appended. +# GITHUB_STEP_SUMMARY when set, the rendered grid is appended. + +set -euo pipefail + +MARKER='' +ORANGE_BADGE='{"schemaVersion":1,"label":"Hypatia grid","message":"indeterminate","color":"orange"}' + +# The renderer is pinned by commit AND by digest. The digest is what makes the +# pin meaningful: a commit can be rewritten out from under a moving tag, and a +# wrongly resolved ref would otherwise run unreviewed code in a job that holds +# pull-requests: write. +STANDARDS_REPO="${VERDICT_GRID_STANDARDS_REPO:-metadatastician/standards}" +STANDARDS_SHA="${VERDICT_GRID_STANDARDS_SHA:-8e48b1caade08a552646adeab66558ac43b4360d}" +RENDERER_SHA256="3ee93552920dfc7c472e763a040cbaed8f38ed4b8af151f5d5076d3124211388" +JQ_LIB_SHA256="5681fcefe09480d82b7fa13a6fcb0c389f16467fe7abbace66986cca83114544" + +usage() { + sed -n '5,60p' "$0" | sed 's/^# \{0,1\}//' >&2 + exit 2 +} + +note() { printf '%s\n' "$*"; } +warn() { printf '::warning::%s\n' "$*"; } +fail() { printf '::error::%s\n' "$*" >&2; } + +# set_output KEY VALUE — append to $GITHUB_OUTPUT when it exists. +set_output() { + [[ -n "${GITHUB_OUTPUT:-}" ]] || return 0 + printf '%s=%s\n' "$1" "$2" >> "$GITHUB_OUTPUT" +} + +gh_bin() { printf '%s' "${GH_BIN:-gh}"; } + +# ───────────────────────────────────────────────────────────────────────────── +# collect — another workflow's artifact, for this commit +# ───────────────────────────────────────────────────────────────────────────── + +# collect_source WORKFLOW ARTIFACT DEST SHA — one source. +# Appends one JSON object to COLLECTED (a file), and downloads when found. +collect_source() { + local workflow="$1" artifact="$2" dest="$3" sha="$4" + local gh run_id="" reason="" status="" found=false + gh="$(gh_bin)" + + if [[ ! -x "$gh" ]] && ! command -v "$gh" >/dev/null 2>&1; then + reason="gh is not available, so ${workflow} evidence could not be fetched" + else + # The runs of this workflow for exactly this commit, newest first. A + # run that is still in progress has no artifact yet; it is reported as + # "not yet", never silently treated as a clean scan. + if ! run_id="$("$gh" run list --repo "$REPO" --workflow "$workflow" \ + --commit "$sha" --event pull_request --limit 20 \ + --json databaseId,status,conclusion,event 2>/dev/null \ + | jq -r '[.[] | select(.event == "pull_request" and .status == "completed")] | sort_by(.databaseId) | last | .databaseId // empty')"; then + run_id="" + fi + if [[ -z "$run_id" ]]; then + reason="no run of ${workflow} is recorded for ${sha:0:12}" + else + status="$("$gh" run view "$run_id" --repo "$REPO" --json status,conclusion 2>/dev/null \ + | jq -r '"\(.status)/\(.conclusion // "none")"' 2>/dev/null || true)" + if "$gh" run download "$run_id" --repo "$REPO" --name "$artifact" --dir "$dest" \ + >/dev/null 2>&1; then + found=true + reason="" + else + reason="run ${run_id} of ${workflow} has no readable ${artifact} artifact (${status:-unknown state})" + fi + fi + fi + + jq -cn --arg workflow "$workflow" --arg artifact "$artifact" --arg run "$run_id" \ + --arg status "$status" --arg reason "$reason" --argjson found "$found" \ + '{workflow: $workflow, artifact: $artifact, run_id: ($run | if . == "" then null else (tonumber? // .) end), + state: $status, found: $found, reason: ($reason | if . == "" then null else . end)}' \ + >> "$COLLECTED" + if [[ "$found" == true ]]; then + note "collected ${artifact} from ${workflow} (run ${run_id})" + else + warn "${reason:-${artifact} was not collected}" + fi +} + +cmd_collect() { + local out="" sha="" + COLLECTED="" + SOURCES=() + while [[ $# -gt 0 ]]; do + case "$1" in + --out) out="$2"; shift 2 ;; + --sha) sha="$2"; shift 2 ;; + --source) SOURCES+=("$2"); shift 2 ;; + --repo) REPO="$2"; shift 2 ;; + *) fail "unknown option: $1"; usage ;; + esac + done + [[ -n "$out" && -n "$sha" ]] || usage + [[ -n "${REPO:-}" ]] || { fail "--repo (or GITHUB_REPOSITORY) is required"; exit 2; } + [[ ${#SOURCES[@]} -gt 0 ]] || { fail "at least one --source is required"; exit 2; } + mkdir -p "$out" + COLLECTED="$out/collection.jsonl" + : > "$COLLECTED" + local spec workflow artifact dest + for spec in "${SOURCES[@]}"; do + IFS=':' read -r workflow artifact <<< "$spec" + [[ -n "$workflow" && -n "$artifact" ]] || { fail "bad --source '$spec' (want workflow-file:artifact-name)"; exit 2; } + dest="$out/$artifact" + mkdir -p "$dest" + collect_source "$workflow" "$artifact" "$dest" "$sha" + done + jq -s '.' "$COLLECTED" > "$out/collection.json" + rm -f "$COLLECTED" + local missing + missing="$(jq -r '[.[] | select(.found | not) | "\(.artifact) (\(.workflow))"] | join("; ")' "$out/collection.json")" + set_output evidence_missing "$missing" + note "evidence: $(jq -r '[.[] | select(.found) | .artifact] | join(", ")' "$out/collection.json")" + # Collection never fails the lane: a scanner that has not reported yet is + # orange in the grid, which is the honest reading. The step says which. + [[ -z "$missing" ]] || warn "grid rows without evidence this run: ${missing}" + return 0 +} + +# ───────────────────────────────────────────────────────────────────────────── +# validate — the evidence shapes the grid reads +# ───────────────────────────────────────────────────────────────────────────── + +# validate_hypatia FILE — an array of objects (paths may be absolute). +validate_hypatia() { + local file="$1" + [[ -e "$file" ]] || { warn "no Hypatia findings at ${file}: its row renders orange"; return 0; } + if ! jq -e 'type == "array" and all(.[]; type == "object")' "$file" >/dev/null 2>&1; then + fail "${file} is not one JSON array of findings; the grid will read it as unreadable evidence" + return 1 + fi + # The grid normalises severity words and makes a row orange on anything it + # does not know. Name the offending values here instead of in the comment. + local unknown + unknown="$(jq -r '[.[] | (.severity // "") | ascii_downcase] | unique + | map(select(. != "critical" and . != "high" and . != "error" and . != "medium" + and . != "warn" and . != "warning" and . != "low" + and . != "info" and . != "informational" and . != "note" and . != "suggestion")) + | join(", ")' "$file")" + [[ -z "$unknown" ]] || warn "${file} carries severity words the grid does not recognise: ${unknown}" + return 0 +} + +# validate_envelope FILE TOOL — a scanner status envelope (VERDICT-GRID-SPEC). +# Bare arrays are the historical shape and are rejected by name, because a bare +# array cannot say "the scanner did not run" and so renders a clean row for a +# scan that never happened. +validate_envelope() { + local file="$1" tool="$2" + [[ -e "$file" ]] || { warn "no ${tool} evidence at ${file}: its row renders orange"; return 0; } + if ! jq -e 'type == "object"' "$file" >/dev/null 2>&1; then + fail "${file} is not a ${tool} status envelope (a bare array cannot say \"did not run\")" + return 1 + fi + if ! jq -e 'has("status") and (.status | type == "string")' "$file" >/dev/null 2>&1; then + fail "${file} has no string \"status\"; the grid cannot tell a scan from a non-scan" + return 1 + fi + local status + status="$(jq -r '.status' "$file")" + case "$status" in + ran) + if ! jq -e '(.report | type) == "object"' "$file" >/dev/null 2>&1; then + fail "${file} says status=ran but carries no report object" + return 1 + fi + ;; + not_run | error | not_applicable) + if [[ "$(jq -r '.reason // ""' "$file")" == "" ]]; then + warn "${file} says status=${status} without a reason; the grid will show an unexplained orange row" + fi + ;; + *) + warn "${file} carries status=${status}, which is not ran/not_run/error/not_applicable" + ;; + esac + return 0 +} + +validate_enrolment() { + local file="$1" + [[ -e "$file" ]] || { warn "no enrolment manifest at ${file}: every fleet row renders orange"; return 0; } + if ! jq -e 'type == "object" and (.reporters | type) == "object"' "$file" >/dev/null 2>&1; then + fail "${file} is not an enrolment manifest; the grid renders it as unreadable evidence" + return 1 + fi + return 0 +} + +cmd_validate() { + local hyp="" pan="" pon="" enrol="" rc=0 + while [[ $# -gt 0 ]]; do + case "$1" in + --hypatia) hyp="$2"; shift 2 ;; + --panic) pan="$2"; shift 2 ;; + --pons) pon="$2"; shift 2 ;; + --enrolment) enrol="$2"; shift 2 ;; + *) fail "unknown option: $1"; usage ;; + esac + done + [[ -n "$hyp$pan$pon$enrol" ]] || usage + [[ -z "$hyp" ]] || validate_hypatia "$hyp" || rc=1 + [[ -z "$pan" ]] || validate_envelope "$pan" "panic-attack" || rc=1 + [[ -z "$pon" ]] || validate_envelope "$pon" "pons-asinorum" || rc=1 + [[ -z "$enrol" ]] || validate_enrolment "$enrol" || rc=1 + return "$rc" +} + +# ───────────────────────────────────────────────────────────────────────────── +# render — the canonical renderer, verified +# ───────────────────────────────────────────────────────────────────────────── + +# verified_renderer DIR — echoes the renderer path when both files exist and +# both digests match. Anything else returns 1 and says which check failed. +verified_renderer() { + local dir="$1" file lib + file="$dir/scripts/verdict-grid.sh" + lib="$dir/scripts/lib/verdict-grid.jq" + if [[ ! -f "$file" || ! -f "$lib" ]]; then + fail "the verdict grid renderer is not available at ${dir}/scripts/verdict-grid.sh; the grid renders indeterminate (orange), never green" + return 1 + fi + if ! printf '%s %s\n' "$RENDERER_SHA256" "$file" | sha256sum -c --strict >/dev/null 2>&1; then + fail "${file} does not match the recorded sha256 (${RENDERER_SHA256}); refusing to run an unverified renderer" + return 1 + fi + if ! printf '%s %s\n' "$JQ_LIB_SHA256" "$lib" | sha256sum -c --strict >/dev/null 2>&1; then + fail "${lib} does not match the recorded sha256 (${JQ_LIB_SHA256}); refusing to run an unverified renderer" + return 1 + fi + printf '%s' "$file" +} + +# fallback_report DIR REASON — the orange "indeterminate" rendering. +# Orange is the spec's word for "the evidence or the renderer was not +# available". Writing a green badge here would be the one unthinkable outcome. +fallback_report() { + local out="$1" reason="$2" + mkdir -p "$out" + printf '%s\n' "$ORANGE_BADGE" > "$out/badge.json" + { + printf '%s\n' "$MARKER" + printf '🟠 **indeterminate** · the verdict grid could not be rendered · `%s`\n' "${SHA:0:12}" + printf '\n%s\n' "$reason" + printf '\n_Orange means the evidence for this lane was unavailable, not that the repository passed._\n' + } > "$out/report.md" + jq -n --arg state "orange" --arg reason "$reason" --arg sha "$SHA" \ + '{state: $state, identity: {lane: "hypatia", sha: $sha}, reason: $reason, + reporters: [], sources: []}' > "$out/report.json" + set_output state orange +} + +cmd_render() { + local out="" renderer_dir="" hyp="" pan="" pon="" backs="" enrol="" prev="" + local url="" pr="local" href="" pref="" qref="" changed="" lane="hypatia" + local renderer_sha="$RENDERER_SHA256" lib_sha="$JQ_LIB_SHA256" + local excludes=() + SHA=""; RUN_ID="local" + while [[ $# -gt 0 ]]; do + case "$1" in + --out) out="$2"; shift 2 ;; + --renderer-dir) renderer_dir="$2"; shift 2 ;; + --renderer-sha256) renderer_sha="$2"; shift 2 ;; + --lib-sha256) lib_sha="$2"; shift 2 ;; + --hypatia) hyp="$2"; shift 2 ;; + --panic) pan="$2"; shift 2 ;; + --pons) pon="$2"; shift 2 ;; + --report-backs) backs="$2"; shift 2 ;; + --enrolment) enrol="$2"; shift 2 ;; + --previous) prev="$2"; shift 2 ;; + --sha) SHA="$2"; shift 2 ;; + --run) RUN_ID="$2"; shift 2 ;; + --url) url="$2"; shift 2 ;; + --pr) pr="$2"; shift 2 ;; + --repo) REPO="$2"; shift 2 ;; + --lane) lane="$2"; shift 2 ;; + --hypatia-ref) href="$2"; shift 2 ;; + --panic-ref) pref="$2"; shift 2 ;; + --pons-ref) qref="$2"; shift 2 ;; + --changed) changed="$2"; shift 2 ;; + --exclude-prefix) excludes+=("$2"); shift 2 ;; + *) fail "unknown option: $1"; usage ;; + esac + done + [[ -n "$out" ]] || usage + [[ -n "$SHA" ]] || usage + renderer_dir="${renderer_dir:-.standards-grid}" + + RENDERER_SHA256="$renderer_sha" + JQ_LIB_SHA256="$lib_sha" + mkdir -p "$out" + + local renderer="" + if ! renderer="$(verified_renderer "$renderer_dir")"; then + fallback_report "$out" "The renderer pinned in ${STANDARDS_REPO}@${STANDARDS_SHA:0:12} was missing or did not match its recorded sha256." + return 0 + fi + + local args=( + render --out "$out" + --lane "$lane" + --sha "$SHA" --run "$RUN_ID" --pr "$pr" --repo "$REPO" + --hypatia-ref "$href" --panic-ref "$pref" --pons-ref "$qref" + ) + [[ -z "$url" ]] || args+=(--url "$url") + [[ -z "$hyp" || ! -e "$hyp" ]] || args+=(--hypatia "$hyp") + [[ -z "$pan" || ! -e "$pan" ]] || args+=(--panic "$pan") + [[ -z "$pon" || ! -e "$pon" ]] || args+=(--pons "$pon") + [[ -z "$backs" || ! -d "$backs" ]] || args+=(--report-backs "$backs") + [[ -z "$enrol" || ! -e "$enrol" ]] || args+=(--enrolment "$enrol") + [[ -z "$prev" || ! -e "$prev" ]] || args+=(--previous "$prev") + [[ -z "$changed" || ! -e "$changed" ]] || args+=(--changed "$changed") + if [[ ${#excludes[@]} -gt 0 ]]; then + local prefix + for prefix in "${excludes[@]}"; do + [[ -z "$prefix" ]] || args+=(--exclude-prefix "$prefix") + done + fi + + local rc=0 + bash "$renderer" "${args[@]}" > "$out/.render.log" 2>&1 || rc=$? + if [[ "$rc" -ne 0 ]]; then + cat "$out/.render.log" >&2 || true + # 2 is a usage error inside the renderer: our own arguments are wrong, + # so fix them rather than pretending the lane is indeterminate. + if [[ "$rc" -eq 2 ]]; then + fail "the verdict grid renderer rejected this invocation (exit 2); see its output above" + return 2 + fi + fallback_report "$out" "The renderer exited ${rc}; see the job log." + return 0 + fi + + if ! jq -e '.state | type == "string"' "$out/report.json" >/dev/null 2>&1; then + fallback_report "$out" "The renderer wrote no readable report.json." + return 0 + fi + if ! jq -e '.schemaVersion == 1 and (.label | type == "string") + and (.message | type == "string") and (.color | type == "string")' \ + "$out/badge.json" >/dev/null 2>&1; then + fallback_report "$out" "The renderer wrote a badge.json that is not a shields endpoint badge." + return 0 + fi + + local state + state="$(jq -r '.state' "$out/report.json")" + set_output state "$state" + set_output badge "$(jq -c . "$out/badge.json")" + note "verdict grid: state=${state} badge=$(jq -r '.message + "/" + .color' "$out/badge.json")" + if [[ -n "${GITHUB_STEP_SUMMARY:-}" && -s "$out/report.md" ]]; then + cat "$out/report.md" >> "$GITHUB_STEP_SUMMARY" + fi + return 0 +} + +# ───────────────────────────────────────────────────────────────────────────── +# previous / comment — one comment per lane per PR, updated in place +# ───────────────────────────────────────────────────────────────────────────── + +# marker_comment_id REPO PR — id of the last comment carrying the marker, or "". +marker_comment_id() { + local repo="$1" pr="$2" gh + gh="$(gh_bin)" + "$gh" api --paginate --slurp "repos/${repo}/issues/${pr}/comments" 2>/dev/null \ + | jq -r --arg marker "$MARKER" ' + [.[][] | select(.user.login == "github-actions[bot]" and ((.body // "") | contains($marker)))] | last | .id // empty' 2>/dev/null || true +} + +cmd_previous() { + local out="" + while [[ $# -gt 0 ]]; do + case "$1" in + --out) out="$2"; shift 2 ;; + --pr) PR="$2"; shift 2 ;; + --repo) REPO="$2"; shift 2 ;; + *) fail "unknown option: $1"; usage ;; + esac + done + [[ -n "$out" ]] || usage + : > "$out" + if [[ -z "${PR:-}" || "$PR" == "local" || -z "${REPO:-}" ]]; then + note "no pull request to read a previous grid from" + return 0 + fi + local gh body_tmp + gh="$(gh_bin)" + body_tmp="$(mktemp)" + "$gh" api --paginate --slurp "repos/${REPO}/issues/${PR}/comments" 2>/dev/null \ + | jq -r --arg marker "$MARKER" ' + [.[][] | select(.user.login == "github-actions[bot]" and ((.body // "") | contains($marker)))] | last | .body // ""' > "$body_tmp" 2>/dev/null \ + || : > "$body_tmp" + # An empty JSON string renders as a bare newline: a blank body is no body. + if [[ -n "$(tr -d '[:space:]' < "$body_tmp")" ]]; then + cat "$body_tmp" > "$out" + fi + rm -f "$body_tmp" + if [[ -s "$out" ]]; then + note "read the previous verdict grid from PR #${PR}" + else + note "no previous verdict grid on PR #${PR}: the delta column will say so" + fi + return 0 +} + +body_with_marker() { + local file="$1" + if head -n1 "$file" | grep -Fq "$MARKER"; then + cat "$file" + else + printf '%s\n' "$MARKER" + cat "$file" + fi +} + +cmd_comment() { + local report="" dry_run=0 + while [[ $# -gt 0 ]]; do + case "$1" in + --report) report="$2"; shift 2 ;; + --pr) PR="$2"; shift 2 ;; + --repo) REPO="$2"; shift 2 ;; + --dry-run) dry_run=1; shift ;; + *) fail "unknown option: $1"; usage ;; + esac + done + [[ -n "$report" && -f "$report/report.md" ]] || usage + [[ -n "${REPO:-}" ]] || usage + + if [[ -z "${PR:-}" || "$PR" == "local" || "$PR" == "null" ]]; then + note "not a pull request run: the grid stays in the job summary and the verdict-grid artifact" + set_output comment skipped-no-pr + return 0 + fi + + local body + body="$(body_with_marker "$report/report.md")" + if [[ "$dry_run" -eq 1 ]]; then + printf '%s\n' "$body" + set_output comment dry-run + return 0 + fi + + local gh + gh="$(gh_bin)" + local id="" + id="$(marker_comment_id "$REPO" "$PR")" + + # A process-level temp file, removed by the EXIT trap: a RETURN trap would + # fire after this function's locals are gone, under `set -u` an error. + PAYLOAD="$(mktemp)" + jq -n --arg body "$body" '{body: $body}' > "$PAYLOAD" + + if [[ -n "$id" ]]; then + if "$gh" api -X PATCH "repos/${REPO}/issues/comments/${id}" --input "$PAYLOAD" >/dev/null; then + note "updated the existing verdict grid comment (${id})" + set_output comment updated + return 0 + fi + fail "could not update the existing verdict grid comment (${id})" + return 1 + fi + if "$gh" api -X POST "repos/${REPO}/issues/${PR}/comments" --input "$PAYLOAD" >/dev/null; then + note "posted the verdict grid comment" + set_output comment created + return 0 + fi + fail "could not post the verdict grid comment" + return 1 +} + +cleanup() { [[ -z "${PAYLOAD:-}" ]] || rm -f "$PAYLOAD"; } + +main() { + local cmd="${1:-}" + [[ -n "$cmd" ]] || usage + shift + REPO="${GITHUB_REPOSITORY:-}" + PAYLOAD="" + trap cleanup EXIT + case "$cmd" in + collect) cmd_collect "$@" ;; + validate) cmd_validate "$@" ;; + render) cmd_render "$@" ;; + comment) cmd_comment "$@" ;; + previous) cmd_previous "$@" ;; + help | --help | -h) usage ;; + *) + fail "unknown command: ${cmd}" + usage + ;; + esac +} + +main "$@" diff --git a/session/custom-checks.k9.ncl b/session/custom-checks.k9.ncl index 6f6f36b2..7f6c01a9 100644 --- a/session/custom-checks.k9.ncl +++ b/session/custom-checks.k9.ncl @@ -5,6 +5,7 @@ K9! { pedigree = { schema_version = "1.0.0", + component_type = "session:custom-checks", metadata = { name = "custom-session-checks", version = "0.1.0", diff --git a/src/interface/ffi/build.zig b/src/interface/ffi/build.zig index 2607c110..0596e52c 100644 --- a/src/interface/ffi/build.zig +++ b/src/interface/ffi/build.zig @@ -1,19 +1,29 @@ // 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 +// Template FFI build (Zig 0.15.2+). +// +// zig build test runs the unit tests in src/main.zig and test/integration_test.zig +// +// src/main.zig carries template tokens until `just repo-init` fills them, so the +// test step compiles only in an instantiated repository. const std = @import("std"); pub fn build(b: *std.Build) void { - _ = b.standardTargetOptions(.{}); - _ = b.standardOptimizeOption(.{}); + const target = b.standardTargetOptions(.{}); + const optimize = 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. + const test_step = b.step("test", "Run the FFI unit and integration tests"); + for ([_][]const u8{ "src/main.zig", "test/integration_test.zig" }) |path| { + const t = b.addTest(.{ + .root_module = b.createModule(.{ + .root_source_file = b.path(path), + .target = target, + .optimize = optimize, + .link_libc = true, // main.zig allocates with std.heap.c_allocator + }), + }); + test_step.dependOn(&b.addRunArtifact(t).step); + } } diff --git a/src/interface/ffi/src/main.zig b/src/interface/ffi/src/main.zig index f1b26333..0c21d087 100644 --- a/src/interface/ffi/src/main.zig +++ b/src/interface/ffi/src/main.zig @@ -25,6 +25,16 @@ fn clearError() void { last_error = null; } +/// Duplicate a byte slice as a NUL-terminated buffer across Zig 0.15/0.16/0.17 +/// (`Allocator.dupeZ` was removed in Zig 0.17). +/// The caller owns the returned slice and must free it with `allocator`. +/// Propagates allocation failure. +fn dupeZ(allocator: std.mem.Allocator, bytes: []const u8) ![:0]u8 { + const buf = try allocator.allocSentinel(u8, bytes.len, 0); + @memcpy(buf[0..bytes.len], bytes); + return buf; +} + //============================================================================== // Core Types (must match src/abi/Types.idr) //============================================================================== @@ -38,8 +48,8 @@ pub const Result = enum(c_int) { null_pointer = 4, }; -/// Library handle (opaque to prevent direct access) -pub const Handle = opaque { +/// Library handle. C sees only a pointer, so the fields stay private to Zig. +pub const Handle = struct { // Internal state hidden from C allocator: std.mem.Allocator, initialized: bool, @@ -110,7 +120,9 @@ export fn {{project}}_process(handle: ?*Handle, input: u32) Result { //============================================================================== /// Get a string result (example) -/// Caller must free the returned string +/// Return a NUL-terminated "Example result" owned by the caller; free it with +/// `{{project}}_free_string`. Return null and set the thread-local error for a +/// null or uninitialized handle, or allocation failure. Clear the error on success. export fn {{project}}_get_string(handle: ?*Handle) ?[*:0]const u8 { const h = handle orelse { setError("Null handle"); @@ -123,7 +135,7 @@ export fn {{project}}_get_string(handle: ?*Handle) ?[*:0]const u8 { } // Example: allocate and return a string - const result = h.allocator.dupeZ(u8, "Example result") catch { + const result = dupeZ(h.allocator, "Example result") catch { setError("Failed to allocate string"); return null; }; @@ -180,14 +192,15 @@ export fn {{project}}_process_array( // Error Handling //============================================================================== -/// Get the last error message -/// Returns null if no error +/// Get the last error message. +/// Return an allocated NUL-terminated copy of the current thread's error, or +/// null if no error is set or allocation fails. Leave the stored error unchanged. +/// Caller must free a non-null returned string with `{{project}}_free_string`. 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; + const c_str = dupeZ(allocator, err) catch return null; return c_str.ptr; } @@ -210,7 +223,7 @@ export fn {{project}}_build_info() [*:0]const u8 { //============================================================================== /// Callback function type (C ABI) -pub const Callback = *const fn (u64, u32) callconv(.C) u32; +pub const Callback = *const fn (u64, u32) callconv(.c) u32; /// Register a callback export fn {{project}}_register_callback( @@ -258,6 +271,10 @@ test "lifecycle" { defer {{project}}_free(handle); try std.testing.expect({{project}}_is_initialized(handle) == 1); + + const str = {{project}}_get_string(handle) orelse return error.StringFailed; + defer {{project}}_free_string(str); + try std.testing.expectEqualStrings("Example result", std.mem.span(str)); } test "error handling" { @@ -265,6 +282,7 @@ test "error handling" { try std.testing.expectEqual(Result.null_pointer, result); const err = {{project}}_last_error(); + defer {{project}}_free_string(err); try std.testing.expect(err != null); } diff --git a/tests/aspect_tests.sh b/tests/aspect_tests.sh index 028b2c04..d56f6a31 100755 --- a/tests/aspect_tests.sh +++ b/tests/aspect_tests.sh @@ -54,7 +54,8 @@ while IFS= read -r -d '' f; do 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) +# Tracked files only: build caches (.zig-cache, target/, _build/) are not source. +done < <(git ls-files -z -- 'src/*.rs' 'src/*.zig' 'src/*.res' 'src/*.ex' 'src/*.exs' 'src/*.gleam' 'src/*.idr' 'src/*.sh' 2>/dev/null) if [ "$MISSING_SPDX" -eq 0 ]; then pass "All source files have SPDX headers" @@ -76,8 +77,19 @@ 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) +# Coq/Lean/Haskell/OCaml dangerous patterns, in proof sources only and with +# comments stripped: prose that names a banned pattern ("NO Admitted allowed") +# is not a use of it. +# shellcheck disable=SC2016 # the single-quoted program is Perl, not shell +DANGEROUS_PROOF=$(git ls-files -z -- 'src/*.v' 'verification/*.v' 'src/*.lean' 'verification/*.lean' \ + 'src/*.hs' 'verification/*.hs' 'src/*.ml' 'verification/*.ml' 2>/dev/null | + xargs -0 -r perl -0777 -ne ' + my $f = $ARGV; my $s = $_; + if ($f =~ /\.(v|ml)$/) { $s =~ s/\(\*.*?\*\)/ /gs } + if ($f =~ /\.lean$/) { $s =~ s{/-.*?-/}{ }gs; $s =~ s/--[^\n]*//g } + if ($f =~ /\.hs$/) { $s =~ s/\{-.*?-\}/ /gs; $s =~ s/--[^\n]*//g } + print "$f: $1\n" while $s =~ /\b(Admitted|sorry|unsafeCoerce|Obj\.magic)\b/g; + ' || true) if [ -n "$DANGEROUS_PROOF" ]; then fail "Dangerous proof patterns found:" echo "$DANGEROUS_PROOF" | head -5 diff --git a/tests/e2e.sh b/tests/e2e.sh index 15384908..16eee4e8 100755 --- a/tests/e2e.sh +++ b/tests/e2e.sh @@ -135,11 +135,11 @@ echo "" # now its only caller was benches/template_bench.sh, which discards the exit # code with `|| true` because a benchmark wants a duration, not a verdict — # so the test could fail on every run and nothing said so. -INSTANTIATION_TEST="$(dirname "$0")/e2e/template_instantiation_test.sh" +INSTANTIATION_TEST="$SCRIPT_DIR/e2e/template_instantiation_test.sh" if [ -f "$INSTANTIATION_TEST" ]; then echo "" echo "── Template instantiation ─────────────────────────────────────" - if bash "$INSTANTIATION_TEST" "$(dirname "$0")/.."; then + if bash "$INSTANTIATION_TEST" "$PROJECT_DIR"; then green "PASS: template instantiation" PASS=$((PASS + 1)) else diff --git a/tests/e2e/julia_fmt_test.sh b/tests/e2e/julia_fmt_test.sh new file mode 100644 index 00000000..403953fb --- /dev/null +++ b/tests/e2e/julia_fmt_test.sh @@ -0,0 +1,73 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# Execute the formatting command shipped to Julia repos, with positive and +# negative controls in every scanned directory. Requires the real Julia and +# JuliaFormatter toolchain; package provisioning may need network access. +# Usage: JULIA_BIN=/path/to/julia bash tests/e2e/julia_fmt_test.sh +set -euo pipefail +repo=$(git rev-parse --show-toplevel) +fixture=$(mktemp -d) +trap 'rm -rf "$fixture"' EXIT +# Print all arguments as a failure message to stderr and exit the test with status 1. +fail() { echo "FAIL: $*" >&2; exit 1; } +julia_bin=$(command -v "${JULIA_BIN:-julia}") || fail 'Julia is required (set JULIA_BIN)' +# The workflow invokes `julia`; respect JULIA_BIN even if it has another name. +mkdir -p "$fixture/bin" +ln -s "$julia_bin" "$fixture/bin/julia" + +# Run the entire literal command, including the file enumeration and current +# JuliaFormatter API. Reimplementing that loop here hid the original bugs. +awk ' + /^ fmt:/ { job = 1; next } + job && /^ [A-Za-z0-9_-]+:/ { exit } + job && /^ run: \|$/ { copying = 1; next } + copying { sub(/^ /, ""); print } +' "$repo/archetypes/julia-library/overlay/.github/workflows/julia-ci.yml.in" > "$fixture/check-format.sh" +[ -s "$fixture/check-format.sh" ] || fail 'formatting command not found in workflow' +work="$fixture/package" +mkdir -p "$work/src/nested" "$work/test/nested" "$work/test/cases/nested" +cd "$work" + +# Reset the three scanned Julia files to formatted contents in the package fixture. +clean_files() { + printf 'x = 1\n' > src/example.jl + printf 'y = 2\n' > test/runtests.jl + printf 'z = 3\n' > test/cases/example.jl +} +# Print SHA-256 checksums for scanned and nested fixture files to detect rewrites. +snapshot() { + sha256sum src/example.jl test/runtests.jl test/cases/example.jl \ + src/nested/ignored.jl test/nested/ignored.jl test/cases/nested/ignored.jl +} +# Run the shipped formatter check with the selected Julia binary, logging both +# output streams to format.log in the fixture; return the check's exit status. +run_fmt() { + PATH="$fixture/bin:$PATH" bash -e "$fixture/check-format.sh" > "$fixture/format.log" 2>&1 +} + +# Nested directories are not files. Their deliberately invalid contents +# also prove that this shallow scan does not start recursing accidentally. +for dir in src/nested test/nested test/cases/nested; do + printf 'this is deliberately invalid Julia (((\n' > "$dir/ignored.jl" +done +clean_files +before=$(snapshot) +run_fmt || { cat "$fixture/format.log" >&2; fail 'formatted files did not pass'; } +[ "$(snapshot)" = "$before" ] || fail 'positive formatting check rewrote input files' +echo 'PASS: formatted files pass; directories are ignored; input files are unchanged' + +for file in src/example.jl test/runtests.jl test/cases/example.jl; do + clean_files + printf 'x=1\n' > "$file" + before=$(snapshot) + if run_fmt; then fail "unformatted $file passed"; fi + grep -qF 'not formatted' "$fixture/format.log" \ + && grep -qF "$file" "$fixture/format.log" \ + || { cat "$fixture/format.log" >&2; fail "$file failed without a formatting diagnostic"; } + [ "$(snapshot)" = "$before" ] || fail "formatting check rewrote $file" + echo "PASS: unformatted $file is rejected without rewriting any input" +done + +rm src/example.jl test/runtests.jl test/cases/example.jl +run_fmt || { cat "$fixture/format.log" >&2; fail 'directories without files did not pass'; } +echo 'PASS: empty file selection passes without trying to read directories' diff --git a/tests/e2e/julia_mint_test.sh b/tests/e2e/julia_mint_test.sh index 69052e21..2962b1e6 100644 --- a/tests/e2e/julia_mint_test.sh +++ b/tests/e2e/julia_mint_test.sh @@ -10,8 +10,9 @@ # repo-init hunks it depends on (PACKAGE_UUID derivation; .in renames). # # Owner rulings exercised here (2026-09-19): -# D7 - the package uuid is generated at mint (derived, stable, v5) -# D6 - the minted workflows are lock-SSOT compliant (actions.lock ships) +# D7 - the package uuid is generated at mint (stable UUIDv8 profile C) +# D6 - the minted workflows are lock-SSOT compliant (the archetype's +# lock fragment merges into the spine's actions.lock) # # Usage: # JULIA_BIN=/path/to/julia bash tests/e2e/julia_mint_test.sh @@ -28,28 +29,51 @@ SCRATCH="${SCRATCH:-$(mktemp -d /tmp/julia-mint-test.XXXXXX)}" trap 'rm -rf "$SCRATCH"' EXIT PASS=0; FAIL=0 +# Print the assertion description in $1 and increment the global PASS count. ok() { echo " PASS: $1"; PASS=$((PASS+1)); } +# Print the assertion description in $1 and increment FAIL without exiting, +# allowing subsequent assertions to run before the final failure summary. bad() { echo " FAIL: $1"; FAIL=$((FAIL+1)); } command -v "$JULIA" >/dev/null 2>&1 || { echo "SKIP: no julia binary (JULIA_BIN)"; exit 0; } [ -d "$OVERLAY" ] || { echo "FAIL: overlay not found at $OVERLAY"; exit 1; } -cd "$SCRATCH" +# Keep the bounded UUID/timeout checks and the real formatter regression +# controls reachable from this acceptance entry point. +if bash "$REPO_DIR/tests/workflows/julia_library_test.sh"; then + ok "UUID generator branches and Julia CI timeouts" +else + bad "UUID generator branches or Julia CI timeouts" +fi +if JULIA_BIN="$JULIA" bash "$REPO_DIR/tests/e2e/julia_fmt_test.sh"; then + ok "shipped formatting command (positive and negative controls)" +else + bad "shipped formatting command" +fi + +cd "$SCRATCH" || exit 1 # ── 1. overlay copy (as repo-init does) ──────────────────────────────── cp -a "$OVERLAY/." . # ── 2. token substitution (as repo-init does) + hunk A (uuid derivation) -OWNER=hyperpolymath; REPO=mintcheck; PROJECT_NAME=MintCheck +export OWNER=hyperpolymath REPO=mintcheck PROJECT_NAME=MintCheck AUTHOR="Jonathan D.A. Jewell"; AUTHOR_EMAIL="owner@hyperpolymath.dev" -FORGE=https://github.com; CURRENT_YEAR=$(date +%Y) +export FORGE=https://github.com +CURRENT_YEAR=$(date +%Y) LB='{{'; RB='}}' -REPO_UUID=$(python3 -c "import uuid; print(uuid.uuid5(uuid.NAMESPACE_URL, '${FORGE}/${OWNER}/${REPO}'))") -if command -v uuidgen >/dev/null 2>&1; then - PACKAGE_UUID=$(uuidgen --sha1 --namespace "$REPO_UUID" --name "julia:${REPO}") -else - PACKAGE_UUID=$(python3 -c "import uuid; print(uuid.uuid5(uuid.UUID('${REPO_UUID}'), 'julia:${REPO}'))") -fi +# Execute the shipped rule rather than a copied UUID algorithm. The previous +# v5 copy let this acceptance test pass while exercising the retired mint. +export ARCHETYPE=julia-library +UUID_RULE=$(awk ' + /^ if \[ "\$ARCHETYPE" = "julia-library" \]; then$/ { copying = 1 } + copying { last = ($0 ~ /^ fi$/); sub(/^ /, ""); print; if (last) exit } +' "$REPO_DIR/build/just/repo-init.just") +[ -n "$UUID_RULE" ] || { bad "package UUID block not found in repo-init"; exit 1; } +UUID_SCRIPT=$(mktemp) +printf '%s\n' "$UUID_RULE" > "$UUID_SCRIPT" +# shellcheck disable=SC1090 +. "$UUID_SCRIPT" for f in $(grep -rl "{{" . 2>/dev/null || true); do tmp=$(mktemp) sed -e "s|${LB}PROJECT_NAME${RB}|${PROJECT_NAME}|g" \ @@ -81,20 +105,20 @@ else fi # ── 4b. lock coverage (D6: actions.lock is the pin truth) ────────────── -if python3 - <<'PY' -import re, sys, pathlib -wfdir = pathlib.Path(".github/workflows") -lock_text = (wfdir / "actions.lock").read_text() -for wf in sorted(wfdir.glob("*.yml")): - uses = {m.group(1) for line in wf.read_text().splitlines() - if (m := re.match(r'\s*uses:\s*(\S+)', line))} - sect = re.search(r"'" + re.escape(str(wf)) + r"':\s*\n((?:\s+-\s+'[^']+'\n?)*)", lock_text) - locked = set(re.findall(r"-\s+'([^']+)'", sect.group(1))) if sect else set() - if uses - locked: - print(f" MISSING in lock: {wf.name}: {sorted(uses - locked)}") - sys.exit(1) -PY -then ok "every uses: ref is in actions.lock"; else bad "lockfile coverage gap"; fi +# A minted tree holds the spine's workflows and lock as well as the +# overlay's. Bring them in, merge the archetype's lock fragment as repo-init +# does, and run the estate's own checker on the result. +for wf in "$REPO_DIR"/.github/workflows/*.yml; do + [ -e ".github/workflows/$(basename "$wf")" ] || cp "$wf" .github/workflows/ +done +cp "$REPO_DIR/.github/workflows/actions.lock" .github/workflows/actions.lock +if bash "$REPO_DIR/scripts/rust-tool.sh" merge-actions-lock \ + .github/workflows/actions.lock "$REPO_DIR/archetypes/julia-library/actions.lock" \ + && bash "$REPO_DIR/scripts/check-lock-sync.sh" .github/workflows; then + ok "merged actions.lock passes check-lock-sync" +else + bad "lockfile coverage gap" +fi # ── 5. Pkg.instantiate + Pkg.test (Test + Aqua) ──────────────────────── if "$JULIA" --project=. -e 'using Pkg; Pkg.instantiate(); Pkg.precompile()' >/tmp/julia-mint-inst.log 2>&1; then @@ -110,16 +134,81 @@ fi # ── 6. uuid derivation (D7) ──────────────────────────────────────────── MINTED_UUID=$(sed -n 's/^uuid = "\(.*\)".*/\1/p' Project.toml | head -1) -if python3 - "$MINTED_UUID" "$PACKAGE_UUID" <<'PY' -import sys, uuid -minted, derived = sys.argv[1], sys.argv[2] -assert minted == derived, f"minted {minted} != derived {derived}" -assert uuid.UUID(minted).version == 5 -PY -then ok "package uuid is the derived v5"; else bad "package uuid derivation"; fi -RE_MINT=$(python3 -c "import uuid; print(uuid.uuid5(uuid.UUID('${REPO_UUID}'), 'julia:${REPO}'))") +if [ "$MINTED_UUID" = "$PACKAGE_UUID" ] \ + && [ "$MINTED_UUID" = b4839a75-05b9-8c83-a497-2aa751ab7f19 ] \ + && [[ "$MINTED_UUID" =~ ^[0-9a-f]{8}-[0-9a-f]{4}-8[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ ]]; then + ok "package uuid is the expected UUIDv8 profile C identity" +else + bad "package uuid derivation" +fi +RE_MINT=$( + # shellcheck disable=SC1090 + . "$UUID_SCRIPT" >/dev/null + printf '%s\n' "$PACKAGE_UUID" +) +rm -f "$UUID_SCRIPT" [ "$RE_MINT" = "$MINTED_UUID" ] && ok "re-mint derives the same uuid (stable identity)" || bad "uuid not stable across re-mints" +# ── 7. JET analysis — the SHIPPED invocation, actually executed ──────── +# +# Issue #202: the overlay emitted `JET.test_package(path=".", julia_version="1")` +# — the path/string form REMOVED in JET v0.12.0. It threw MethodError before +# analysing anything, and nothing in this repository ever executed it, so it +# shipped to every minted Julia repo. Syntax-checking the YAML could not catch +# it; only running it can. +# +# Both controls are mandatory: +# positive — the clean minted package passes. +# negative — an injected inference error IS detected. If the negative control +# passes, this test is vacuous and its "PASS" means nothing. +# +# JET goes in its own environment so the package's Project.toml is untouched, +# mirroring what the shipped workflow now does. +JET_PKG=$(sed -n 's/^name = "\([^"]*\)".*/\1/p' Project.toml | head -1) +JET_SRC="src/${JET_PKG}.jl" +JET_ENV="$SCRATCH/.jet-env" + +# Provision JET 0.12 in JET_ENV, develop the fixture package from SCRATCH, +# and run test_package on JET_PKG; return Julia's status for the controls below. +run_jet() { + "$JULIA" -e " + using Pkg + Pkg.activate(\"$JET_ENV\") + Pkg.develop(path=\"$SCRATCH\") + Pkg.add(Pkg.PackageSpec(name=\"JET\", version=\"0.12\")) + using ${JET_PKG}, JET + if !hasmethod(JET.test_package, (Module,)) + error(\"JET \", pkgversion(JET), + \" has no test_package(::Module); the overlay pins an API that moved\") + end + JET.test_package(${JET_PKG}) + " +} + +if [ -n "$JET_PKG" ] && [ -f "$JET_SRC" ]; then + # positive control + if run_jet >/tmp/julia-mint-jet.log 2>&1; then + ok "JET: clean package passes (positive control)" + else + bad "JET: clean package failed — inspect; if this is an API/infra failure it is NOT a findings failure" + tail -12 /tmp/julia-mint-jet.log | sed 's/^/ /' + fi + + # negative control — inject a concrete inference error INSIDE the module. + # Inside a function body, so the module still loads and JET can analyse it; + # a bare top-level call would throw at load time and prove nothing. + cp "$JET_SRC" "$JET_SRC.bak" + sed -i '/^end # module/i neg_control() = "string" + 1' "$JET_SRC" + if run_jet >/tmp/julia-mint-jet-neg.log 2>&1; then + bad "JET: injected inference error was NOT detected — this canary cannot fail, so its PASS is vacuous" + else + ok "JET: injected inference error detected (negative control)" + fi + mv "$JET_SRC.bak" "$JET_SRC" +else + bad "JET: could not locate the minted package module (name=${JET_PKG:-}, src=$JET_SRC)" +fi + echo echo "julia mint test: $PASS passed, $FAIL failed" [ "$FAIL" -eq 0 ] diff --git a/tests/e2e/language_profiles_mint_test.sh b/tests/e2e/language_profiles_mint_test.sh new file mode 100644 index 00000000..0fc1f05d --- /dev/null +++ b/tests/e2e/language_profiles_mint_test.sh @@ -0,0 +1,294 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# language_profiles_mint_test.sh — mint a Julia package and a Rust CLI from this +# template's own tree and archetypes, then run the estate gates on both. +# +# ── What this proves, and what it does not ───────────────────────────────── +# +# It proves the LANGUAGE-CONDITIONAL parts of the mint end to end: +# * the archetype overlay is applied and its *.in files get their final names; +# * the archetype's prune.txt removes modules the preset does not declare; +# * mise.toml is RENDERED for the languages the tree actually carries (the +# step the mint used to skip, which is how a Julia package came to declare +# Python, Node, Go and Cargo while requiring none of them and no Julia); +# * the gates the template enforces — SPDX, container pins, mise/language +# match, answered tokens — pass on both scaffolds; +# * replaying the historical damage (the nine-runtime mise.toml, a floating +# Containerfile, an unanswered token) makes those same gates fail. +# +# It does NOT run `just repo-init` itself. The full recipe needs rustc (its mint +# tools are single-file Rust compiled on demand), nickel (the arrival pack) and +# uuidgen; this harness has none of the three, and the CI job that does run the +# real mint is tests/e2e/use_template_mint_test.sh. What this test DOES use is +# the recipe's own overlay/prune/rename ordering and its own token answer list, +# read from build/just/repo-init.just at run time, so the two cannot drift into +# agreeing by accident. +# +# Usage: bash tests/e2e/language_profiles_mint_test.sh [--keep] +# Exit: 0 all controls hold; 1 a control failed. + +set -uo pipefail + +REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" + +# A minted repository carries this test but not the archetypes it mints from +# (`just repo-init` deletes archetypes/). Skipping is the honest outcome there; +# failing would be a red build in every child for a test about the parent. +if [ ! -d "$REPO_DIR/archetypes" ]; then + echo "SKIP: $REPO_DIR has no archetypes/ — this is a minted repository." + echo " Language-profile minting is a template-side check; run it in" + echo " hyperpolymath/rsr-template-repo." + exit 0 +fi + +WORK="$(mktemp -d)" +if [ "${1:-}" = "--keep" ]; then echo "keeping $WORK"; else trap 'rm -rf "$WORK"' EXIT; fi + +CHECKS=0; FAILED=0 +pass() { CHECKS=$((CHECKS+1)); printf ' \033[32mPASS\033[0m %s\n' "$1"; } +bad() { CHECKS=$((CHECKS+1)); FAILED=$((FAILED+1)); printf ' \033[31mFAIL\033[0m %s\n' "$1"; } +note() { printf ' %s\n' "$1"; } + +# The tokens repo-init can answer, read from the recipe (not copied). +ANSWERS="$(bash "$REPO_DIR/scripts/check-mint-tokens.sh" --root "$REPO_DIR" 2>&1 >/dev/null || true)" +ANSWERS="$(sed -n 's/.*repo-init answers \([0-9]*\).*/\1/p' <<<"$(bash "$REPO_DIR/scripts/check-mint-tokens.sh" --root "$REPO_DIR" 2>/dev/null)" )" +[ -n "$ANSWERS" ] || { echo "FAIL: could not read the answer count from check-mint-tokens.sh" >&2; exit 1; } +mapfile -t ANSWER_TOKENS < <( + sed -n 's/.*repo-init answers.*//p' /dev/null + # reuse the gate's own extraction by asking it to report, via the recipe + sed -n 's/.*s|\${LB}\([A-Z][A-Z0-9_]*\)\${RB}|.*/\1/p' "$REPO_DIR/build/just/repo-init.just" + awk '/for tok in/ { c=1 } c { line=$0; gsub(/\$\{LB\}|\$\{RB\}|\\/, " ", line) + n=split(line,w,/[^A-Z0-9_]+/); for(i=1;i<=n;i++) if (w[i] ~ /^[A-Z][A-Z0-9_]*$/ && length(w[i])>2) print w[i] + if ($0 ~ /;[[:space:]]*do/) c=0 }' "$REPO_DIR/build/just/repo-init.just" + echo PROJECT + echo project +) +mapfile -t ANSWER_TOKENS < <(printf '%s\n' "${ANSWER_TOKENS[@]}" | sort -u) + +# Value for each answer, mirroring what a human would type at the prompts. +declare -A V=( + [PROJECT_NAME]="Demo Package" [PROJECT]="DEMO_PACKAGE" [project]="demo_package" + [OWNER]="example-owner" [FORGE]="github.com" + [AUTHOR]="Jane Doe" [AUTHOR_EMAIL]="jane@example.org" [AUTHOR_ORG]="Example University" + [AUTHOR_LAST]="Doe" [AUTHOR_FIRST]="Jane" [AUTHOR_INITIALS]="J." + [CURRENT_YEAR]="2026" [CURRENT_DATE]="2026-10-30" [DATE]="2026-10-30" + [SECURITY_EMAIL]="security@example.org" [CONDUCT_EMAIL]="conduct@example.org" + [LICENSE]="MPL-2.0" [CONDUCT_TEAM]="Code of Conduct Committee" [RESPONSE_TIME]="48 hours" + [MAIN_BRANCH]="main" [WEBSITE]="https://github.com/example-owner/demo" + [SERVICE_NAME]="demo" [PORT]="8080" [REGISTRY]="ghcr.io/example-owner" + [EMAIL]="jane@example.org" [VERSION]="0.1.0" + [OPENSSF_BP_ID]="" [OPENSSF_PROJECT_ID]="" +) +for tok in "${ANSWER_TOKENS[@]}"; do : "${V[$tok]:=UNASSIGNED}"; done + +# ── 1. The spine, as the mint sees it: tracked files only ─────────────────── +make_tree() { # $1 dir, $2 repo slug, $3 archetype + local dir="$1" slug="$2" arch="$3" + mkdir -p "$dir" + ( cd "$REPO_DIR" && git ls-files -z --cached --others --exclude-standard \ + | while IFS= read -r -d '' f; do + case "$f" in tests/*|archetypes/*|build/templates/*|build/docs-seed/*) continue ;; esac + [ -f "$f" ] && printf '%s\0' "$f" + done | tar --null -T - -cf - ) | tar xf - -C "$dir" + # the overlay: recorded first, exactly as the recipe does + if [ -n "$arch" ]; then + mapfile -t OF < <( cd "$REPO_DIR/archetypes/$arch/overlay" && find . -type f | sed 's|^\./||' | sort ) + cp -a "$REPO_DIR/archetypes/$arch/overlay/." "$dir/" + if [ -f "$REPO_DIR/archetypes/$arch/prune.txt" ]; then + bash "$REPO_DIR/scripts/prune-archetype-modules.sh" "$REPO_DIR/archetypes/$arch" "$dir" >/dev/null + fi + # substitute, then give the overlay's *.in files their final names + substitute "$dir" "$slug" + for of in "${OF[@]}"; do + case "$of" in + src/PACKAGE.jl.in) continue ;; + *.in) [ -f "$dir/$of" ] && mv "$dir/$of" "$dir/${of%.in}" ;; + esac + done + if [ "$arch" = "julia-library" ] && [ -f "$dir/src/PACKAGE.jl.in" ]; then + local pkg + pkg="$(sed -n 's/^name = "\([^"]*\)".*/\1/p' "$dir/Project.toml" | head -1)" + [ -n "$pkg" ] && mv "$dir/src/PACKAGE.jl.in" "$dir/src/$pkg.jl" + fi + else + substitute "$dir" "$slug" + fi + # the mint removes these before it renders anything derived + rm -rf "$dir/archetypes" "$dir/build/docs-seed" "$dir/build/templates" + bash "$REPO_DIR/scripts/render-mise.sh" --root "$dir" >/dev/null + ( cd "$dir" && git init -q -b main && git add -A \ + && git -c user.name=t -c user.email=t@example.org -c commit.gpgsign=false commit -qm mint ) +} + +substitute() { # $1 dir, $2 repo slug + local dir="$1" slug="$2" f tok + V[REPO]="$slug" + # DERIVE the identifier tokens from the slug, exactly as repo-init does + # (`tr '[:lower:]-.' '[:upper:]__'` and its lowercase twin). They were fixed + # to demo_package, so the Rust fixture generated `demo_package::about()` in a + # crate named demo_rust — a scaffold that cannot compile, reported as a pass + # because this harness never compiles. + V[PROJECT]="$(printf '%s' "$slug" | tr '[:lower:]-.' '[:upper:]__')" + V[project]="$(printf '%s' "$slug" | tr '[:upper:]-.' '[:lower:]__')" + local args=() + for tok in "${ANSWER_TOKENS[@]}"; do + args+=(-e "s|{{${tok}}}|${V[$tok]}|g") + done + while IFS= read -r f; do + case "$f" in + *Justfile|*.just|*.png|*.jpg|*.gif) continue ;; + esac + [ -f "$dir/$f" ] && sed -i "${args[@]}" "$dir/$f" 2>/dev/null || true + done < <( cd "$dir" && find . -type f | sed 's|^\./||' ) +} + +echo "── Julia scaffold ─────────────────────────────────────────" +J="$WORK/DemoPackage.jl" +make_tree "$J" "DemoPackage.jl" "julia-library" + +[ -f "$J/Project.toml" ] && pass "Julia: Project.toml has its final name" \ + || bad "Julia: Project.toml missing (the .in rename did not run)" +grep -q '^name = "Demo Package"' "$J/Project.toml" 2>/dev/null \ + && pass "Julia: package name rendered from the archetype token" \ + || bad "Julia: package name not rendered" +[ -f "$J/src/Demo Package.jl" ] || [ -f "$J/src/DemoPackage.jl" ] || ls "$J/src"/*.jl >/dev/null 2>&1 \ + && pass "Julia: module file named after the package" \ + || bad "Julia: module file not renamed from PACKAGE.jl.in" +[ -e "$J/build/container" ] && bad "Julia: build/container/ survived prune.txt" \ + || pass "Julia: build/container/ pruned (no unpinnable Containerfile ships)" +grep -q '^julia = "latest"' "$J/mise.toml" && pass "Julia: mise declares julia" \ + || bad "Julia: mise does not declare julia" +if grep -qE '^(python|node|npm|yarn|pip|black|ruff|go|java|cargo) =' "$J/mise.toml"; then + bad "Julia: mise declares a banned or foreign tool" +else + pass "Julia: mise declares no banned or foreign tool" +fi +[ -f "$J/scripts/julia-quality.jl" ] && pass "Julia: quality verbs wired (scripts/julia-quality.jl)" \ + || bad "Julia: quality script missing" +[ -e "$J/src/interface" ] && bad "Julia: src/interface/ (Idris2/Zig seam) survived prune.txt" \ + || pass "Julia: src/interface/ pruned — a Julia package needs no Idris2 or Zig" +if grep -qE '^(idris2|zig) =' "$J/mise.toml"; then + bad "Julia: mise installs a toolchain the preset never declared" +else + pass "Julia: mise installs only the detected language's toolchain" +fi +grep -q ':fmt-check' "$J/.machine_readable/descriptiles/provisioning_praxis.deed" \ + && pass "Julia: fmt/fmt-check/lint overrides shipped in the provisioning deed" \ + || bad "Julia: provisioning deed has no verb overrides" + +echo "" +echo "── Rust scaffold ──────────────────────────────────────────" +R="$WORK/demo-rust" +make_tree "$R" "demo-rust" "rust-cli" + +[ -f "$R/Cargo.toml" ] && pass "Rust: Cargo.toml has its final name" \ + || bad "Rust: Cargo.toml missing" +[ -f "$R/src/main.rs" ] && [ -f "$R/src/lib.rs" ] && [ -f "$R/tests/cli.rs" ] \ + && pass "Rust: sources rendered from the overlay's .in files" \ + || bad "Rust: expected src/main.rs, src/lib.rs and tests/cli.rs" +grep -q '^name = "demo-rust"' "$R/Cargo.toml" && pass "Rust: crate name is the repo slug" \ + || bad "Rust: crate name not rendered" +grep -q '^rust = "latest"' "$R/mise.toml" && pass "Rust: mise declares rust" \ + || bad "Rust: mise does not declare rust" +if grep -qE '^(python|node|npm|yarn|pip|black|ruff|go|java) =' "$R/mise.toml"; then + bad "Rust: mise declares a banned tool" +else + pass "Rust: mise declares no banned tool" +fi +[ -e "$R/build/container" ] && bad "Rust: build/container/ survived prune.txt" \ + || pass "Rust: build/container/ pruned" +[ -e "$R/src/interface" ] && bad "Rust: src/interface/ (Idris2/Zig seam) survived prune.txt" \ + || pass "Rust: src/interface/ pruned — a Rust CLI needs no Idris2 or Zig" +if grep -qE '^(idris2|zig) =' "$R/mise.toml"; then + bad "Rust: mise installs a toolchain the preset never declared" +else + pass "Rust: mise installs only the detected language's toolchain" +fi +# The identifier tokens are derived from the slug, so the generated code must name +# the crate the slug produces (demo-rust -> demo_rust). Fixing {{project}} to a +# constant made this scaffold reference a crate that cannot exist. +grep -q 'demo_rust' "$R/src/main.rs" && pass "Rust: generated code uses the slug-derived crate name" \ + || bad "Rust: generated code does not use the slug-derived crate name (demo_rust)" + +echo "" +echo "── Gates on both scaffolds ────────────────────────────────" +for d in "$J" "$R"; do + name="$(basename "$d")" + if bash "$REPO_DIR/scripts/check-spdx-headers.sh" --root "$d" --quiet; then + pass "$name: SPDX gate passes"; else bad "$name: SPDX gate fails"; fi + if bash "$REPO_DIR/scripts/check-mise-language.sh" --root "$d" --quiet; then + pass "$name: mise/language gate passes"; else bad "$name: mise/language gate fails"; fi + if bash "$REPO_DIR/scripts/check-container-pins.sh" --root "$d" --quiet; then + pass "$name: container pin gate passes"; else bad "$name: container pin gate fails"; fi + if bash "$REPO_DIR/scripts/check-mint-tokens.sh" --root "$d" --quiet; then + pass "$name: no unanswered token survives the mint"; else bad "$name: a token survived"; fi + if bash "$REPO_DIR/scripts/check-no-placeholders.sh" "$d" >/dev/null 2>&1; then + pass "$name: placeholder gate passes"; else bad "$name: placeholder gate fails"; fi +done + +echo "" +echo "── Replay the downstream damage ───────────────────────────" +# The exact mise.toml the template shipped until 2026-10-01, and which +# JuliaPackageSpitter.jl still carries. A Julia repo with it MUST fail. +cp "$J/mise.toml" "$WORK/mise.good" +cat > "$J/mise.toml" <<'OLD' +[tools] +node = "latest" +python = "latest" +rust = "latest" +go = "latest" +zig = "latest" +java = "latest" +bun = "latest" +denojs = "latest" +npm = "latest" +yarn = "latest" +pnpm = "latest" +pip = "latest" +cargo = "latest" +go-task = "latest" + +[alias] +build = "cargo build --release || npm run build || go build" +test = "cargo test || npm test || go test ./..." +lint = "ruff check . || prettier --check . || black --check ." +fmt = "ruff format . || prettier --write . || black ." +OLD +if bash "$REPO_DIR/scripts/check-mise-language.sh" --root "$J" --quiet; then + bad "damage replay: the nine-runtime mise.toml PASSED a language gate" +else + pass "damage replay: the nine-runtime mise.toml is caught" +fi +cp "$WORK/mise.good" "$J/mise.toml" + +# A floating Containerfile, as the template used to ship at the root. +cat > "$J/Containerfile" <<'OLD' +FROM cgr.dev/chainguard/wolfi-base:latest AS build +FROM cgr.dev/chainguard/static:latest +OLD +if bash "$REPO_DIR/scripts/check-container-pins.sh" --root "$J" --quiet; then + bad "damage replay: a floating Containerfile PASSED the pin gate" +else + pass "damage replay: a floating Containerfile is caught" +fi +rm -f "$J/Containerfile" + +# An unanswered token, as five files carried downstream. +printf 'project := "{{tier}}"\n' >> "$J/README.adoc" +if bash "$REPO_DIR/scripts/check-mint-tokens.sh" --root "$J" --quiet; then + bad "damage replay: an unanswered token PASSED the token gate" +else + pass "damage replay: an unanswered token is caught" +fi +sed -i '/project := "{{tier}}"/d' "$J/README.adoc" + +echo "" +echo "── Summary ────────────────────────────────────────────────" +if [ "$FAILED" -eq 0 ]; then + printf 'language profiles: \033[32m%d/%d controls hold\033[0m\n' "$CHECKS" "$CHECKS" + exit 0 +fi +printf 'language profiles: \033[31m%d of %d controls failed\033[0m\n' "$FAILED" "$CHECKS" +exit 1 diff --git a/tests/e2e/template_instantiation_test.sh b/tests/e2e/template_instantiation_test.sh index 5fd44593..661f61e3 100755 --- a/tests/e2e/template_instantiation_test.sh +++ b/tests/e2e/template_instantiation_test.sh @@ -14,16 +14,14 @@ # Test configuration -TEMPLATE_ROOT="${1:-.}" +TEMPLATE_ROOT="$(cd "${1:-.}" && pwd)" TEST_DIR="${TMPDIR:-/tmp}/rsr-template-test-$$" TEST_REPO_NAME="test-instantiated-repo" TEST_OWNER="test-owner" -TEST_FORGE="github" TEST_AUTHOR="Test Author" TEST_AUTHOR_EMAIL="test@example.com" TEST_PROJECT_NAME="Test Project" TEST_DESCRIPTION="A test project instantiated from the RSR template" -TEST_PRIMARY_LANGUAGE="Rust" if [ ! -d "$TEMPLATE_ROOT/archetypes" ]; then echo "Self-skipping: archetypes/ not found (repo is already instantiated)." @@ -112,7 +110,9 @@ rm -rf "$TEST_REPO_PATH/.claude" # The origin is set to the INSTANTIATED name deliberately, for the same reason # the check below clears GITHUB_REPOSITORY: we want the checker to judge this as # a real minted repo, not to exempt itself as a template. -if [ -d "$TEST_REPO_PATH/.git" ]; then +# -e, not -d: in a linked worktree .git is a FILE pointing at the source +# repo, and leaving it would make the git init below act on the source. +if [ -e "$TEST_REPO_PATH/.git" ]; then rm -rf "$TEST_REPO_PATH/.git" log_pass ".git directory removed (fresh clone)" fi @@ -172,6 +172,7 @@ INIT_ANSWERS=( "$TEST_AUTHOR_EMAIL" # Author email "" # Author organization "" # Previous/alt email + "" # Author ORCID iD -> none (line dropped) "$TEST_DESCRIPTION" # Project description "" # Forge domain -> default "" # Security email -> default @@ -193,9 +194,28 @@ if [ -d "$TEST_REPO_PATH/build/container" ]; then fi INIT_ANSWERS+=("Y") # Proceed? -if ! (cd "$TEST_REPO_PATH" && printf '%s\n' "${INIT_ANSWERS[@]}" | just repo-init) > "$TEST_DIR/init.log" 2>&1; then +# Provenance is resolved by tree equality against the template's history +# (scripts/resolve-template-pin.sh). Read it from the checkout under test, not +# from GitHub: this copy is of the work tree in hand. A dirty work tree has no +# commit to name, so that case mints unpinned, loudly, rather than failing for +# a reason that has nothing to do with instantiation. +PIN_ENV=(RSR_TEMPLATE_URL="$TEMPLATE_ROOT") +if [ -n "$(git -C "$TEMPLATE_ROOT" status --porcelain 2>/dev/null)" ]; then + log_warn "template work tree is dirty — minting with RSR_ALLOW_UNPINNED=1" + PIN_ENV+=(RSR_ALLOW_UNPINNED=1) +fi + +if ! (cd "$TEST_REPO_PATH" && printf '%s\n' "${INIT_ANSWERS[@]}" | env "${PIN_ENV[@]}" just repo-init) > "$TEST_DIR/init.log" 2>&1; then log_error "just repo-init failed:" cat "$TEST_DIR/init.log" >&2 + # The lane's verdict is one line in a 200-line log; the reason is the last + # few lines of init.log. Emit them as an annotation so the failure is + # legible where the failure is reported (PR check list, API, the log + # summary), not only to whoever downloads the raw log. + if [ "${GITHUB_ACTIONS:-}" = "true" ]; then + printf '::error title=just repo-init failed::%s\n' \ + "$(tail -n 40 "$TEST_DIR/init.log" | awk '{printf "%s%%0A", $0}')" + fi exit 1 fi @@ -207,24 +227,23 @@ log_pass "just repo-init completed" log_step "Checking rendered Guix package identity" -for guix_file in build/guix.scm; do - if [ ! -f "$TEST_REPO_PATH/$guix_file" ]; then - log_error "$guix_file is missing after instantiation" - exit 1 - fi - if ! grep -qF "(name \"$TEST_REPO_NAME\")" "$TEST_REPO_PATH/$guix_file"; then - log_error "$guix_file does not use the lowercase repository slug as its Guix name" - exit 1 - fi - if ! grep -qF "(home-page \"https://github.com/$TEST_OWNER/$TEST_REPO_NAME\")" "$TEST_REPO_PATH/$guix_file"; then - log_error "$guix_file does not contain the rendered project home page" - exit 1 - fi - if grep -q 'rsr-template-repo' "$TEST_REPO_PATH/$guix_file"; then - log_error "$guix_file still contains the template repository identity" - exit 1 - fi -done +guix_file="build/guix.scm" +if [ ! -f "$TEST_REPO_PATH/$guix_file" ]; then + log_error "$guix_file is missing after instantiation" + exit 1 +fi +if ! grep -qF "(name \"$TEST_REPO_NAME\")" "$TEST_REPO_PATH/$guix_file"; then + log_error "$guix_file does not use the lowercase repository slug as its Guix name" + exit 1 +fi +if ! grep -qF "(home-page \"https://github.com/$TEST_OWNER/$TEST_REPO_NAME\")" "$TEST_REPO_PATH/$guix_file"; then + log_error "$guix_file does not contain the rendered project home page" + exit 1 +fi +if grep -q 'rsr-template-repo' "$TEST_REPO_PATH/$guix_file"; then + log_error "$guix_file still contains the template repository identity" + exit 1 +fi log_pass "Guix package names and home pages were rendered correctly" @@ -264,9 +283,14 @@ log_step "Checking for un-deleted template instruction blocks" # CODE_OF_CONDUCT.md, each one naming "Squisher Corpus" as the project it # protects and routing conduct reports to the wrong repository. Measured # 2026-08-04. Catch it by name instead. -LEFTOVER=$(grep -rl 'TEMPLATE INSTRUCTIONS' "$TEST_REPO_PATH" \ - --exclude-dir=.git 2>/dev/null \ - | grep -vE '/(scripts/strip-instruction-blocks\.rs|build/just/repo-init\.just|tests/e2e/template_instantiation_test\.sh|tests/workflows/mint_cleanup_test\.sh)$' || true) +# Over the repository's own files only (git-ignored copies are not this repo's), +# minus the machinery the mint carries verbatim: the same manifest repo-init's +# leftover check reads, so the two cannot disagree about what is exempt. +LEFTOVER=$(cd "$TEST_REPO_PATH" && git ls-files --cached --others --exclude-standard \ + | grep -vxF -f <(sed -e 's/#.*//' -e 's/[[:space:]]*$//' .machine_readable/mint-verbatim.txt | grep -v '^$') \ + | while IFS= read -r f; do + [ -f "$f" ] && grep -q 'TEMPLATE INSTRUCTIONS' "$f" && echo "$TEST_REPO_PATH/$f" + done || true) if [ -n "$LEFTOVER" ]; then log_error "just repo-init left a TEMPLATE INSTRUCTIONS block in:" echo "$LEFTOVER" | sed 's/^/ /' >&2 @@ -298,15 +322,15 @@ log_step "Verifying build system works after instantiation" if [ -f "$TEST_REPO_PATH/src/interface/ffi/build.zig" ]; then if command -v zig &> /dev/null; then - cd "$TEST_REPO_PATH/src/interface/ffi" - if ZIG_GLOBAL_CACHE_DIR="$TEST_DIR/zig-global-cache" \ - ZIG_LOCAL_CACHE_DIR="$TEST_DIR/zig-local-cache" zig build 2>&1; then - log_pass "Zig build successful" + cd "$TEST_REPO_PATH/src/interface/ffi" || exit 1 + if ZIG_GLOBAL_CACHE_DIR="${ZIG_GLOBAL_CACHE_DIR:-$TEST_DIR/zig-global-cache}" \ + ZIG_LOCAL_CACHE_DIR="${ZIG_LOCAL_CACHE_DIR:-$TEST_DIR/zig-local-cache}" zig build test 2>&1; then + log_pass "Zig build and FFI unit/integration tests successful" else - log_error "Zig build failed" + log_error "Zig build test failed" exit 1 fi - cd - > /dev/null + cd - > /dev/null || exit 1 else # Zig is OPTIONAL at this point. Everything this e2e exists to prove # about instantiation - placeholders, instruction blocks, structure - @@ -336,7 +360,7 @@ for file in "${CRITICAL_FILES[@]}"; do if [ -f "$TEST_REPO_PATH/$file" ]; then # Check that it's not just a template (contains some actual content) if grep -q "$TEST_PROJECT_NAME\|$TEST_AUTHOR\|$TEST_REPO_NAME" "$TEST_REPO_PATH/$file" 2>/dev/null || \ - [ $(wc -l < "$TEST_REPO_PATH/$file") -gt 10 ]; then + [ "$(wc -l < "$TEST_REPO_PATH/$file")" -gt 10 ]; then log_pass "File instantiated: $file" else log_error "File appears to be a template: $file" @@ -354,12 +378,10 @@ done log_step "Verifying machine-readable metadata" -METADATA_FILES=( - ".machine_readable/descriptiles/STATE.a2ml" - ".machine_readable/descriptiles/META.a2ml" -) - -for file in "${METADATA_FILES[@]}"; do +# Identity, state, meta and ecosystem are clauses of the minted repo's own +# deed (rsr-template-repo#209); the journal is docs/status/ROADMAP.adoc. +CHILD_DEED="${TEST_REPO_NAME}_chora.deed" +for file in "$CHILD_DEED" "docs/status/ROADMAP.adoc"; do if [ -f "$TEST_REPO_PATH/$file" ]; then log_pass "Metadata file exists: $file" else @@ -367,6 +389,53 @@ for file in "${METADATA_FILES[@]}"; do exit 1 fi done +# The a2ml format is retired estate-wide: a mint carries no .a2ml file +# anywhere, not merely none of the names that used to be descriptiles. +A2ML_LEFT=$(cd "$TEST_REPO_PATH" && find . -path ./.git -prune -o -name '*.a2ml' -print) +if [ -n "$A2ML_LEFT" ]; then + log_error "mint carries retired .a2ml files:" + echo "$A2ML_LEFT" >&2 + exit 1 +fi +log_pass "Mint carries no .a2ml file" +# The template's identity must not survive into the mint: its clade, its +# maturity, its uuid name, or an unfilled token. +DEED_READ="$TEST_REPO_PATH/scripts/deed-field.sh" +CHILD="$TEST_REPO_PATH/$CHILD_DEED" +if [ "$(bash "$DEED_READ" "$CHILD" clade primary)" != "UNASSIGNED" ] \ + || [ "$(bash "$DEED_READ" "$CHILD" maturity level)" != "experimental" ] \ + || [ "$(bash "$DEED_READ" "$CHILD" status phase)" != "incubating" ] \ + || [ "$(bash "$DEED_READ" "$CHILD" ecosystem project)" != "$TEST_REPO_NAME" ] \ + || [ "$(bash "$DEED_READ" "$CHILD" "" repo-uuid)" != "github.com/${TEST_OWNER}/${TEST_REPO_NAME}" ]; then + log_error "child deed still carries the template's identity, or lacks its own" + exit 1 +fi +# Unfilled tokens in the child deed are caught by check-no-placeholders.sh +# above, which scans every file and exempts metasyntactic tokens such as +# the {{PLACEHOLDER}} the deed's prose mentions. +log_pass "Child deed carries the minted repo's identity" + +# Mint-time clauses (rsr-template-repo#209 follow-up): the profile is the +# minimal one, not the template's maximal spine profile; provenance and the +# variant record name the template commit; exactly one canon pin survives. +if [ "$(bash "$DEED_READ" "$CHILD" rsr-profile role 2>/dev/null || true)" = "spine" ]; then + log_error "child (rsr-profile) is still the template's spine profile" + exit 1 +fi +for clause in "provenance template-commit" "variant parent-pin"; do + # shellcheck disable=SC2086 + val=$(bash "$DEED_READ" "$CHILD" $clause 2>/dev/null || true) + if [ -z "$val" ]; then + log_error "child deed has no ($clause) value" + exit 1 + fi +done +CANON_N=$(grep -cE '^[[:space:]]*[(]canon([[:space:]]|$)' "$CHILD" || true) +if [ "$CANON_N" != "1" ]; then + log_error "child deed carries $CANON_N (canon …) clauses, need exactly 1" + exit 1 +fi +log_pass "Child deed carries minimal (rsr-profile), (variant), (provenance) and one (canon)" #============================================================================== # WWW SITE-OPERATIONS BUNDLE (issue #53) diff --git a/tests/e2e/use_template_mint_test.sh b/tests/e2e/use_template_mint_test.sh new file mode 100755 index 00000000..fb4652c3 --- /dev/null +++ b/tests/e2e/use_template_mint_test.sh @@ -0,0 +1,228 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# use_template_mint_test.sh — mint a repository created the way GitHub's +# "Use this template" button creates one, and check what the mint wrote. +# +# Why. On 2026-10-14 metadatastician/lintel was created with that button (one +# root commit whose tree equals rsr-template-repo c9bce25, none of its history) +# and minted in place with RSR_NON_INTERACTIVE=1 just repo-init. Every defect +# below needed a hand correction there, and no test had ever run a full mint: +# tests/e2e/template_instantiation_test.sh runs nowhere in CI, and it mints an +# uncommitted copy, which is not how real children are born. +# +# (a) provenance named the CHILD's own HEAD as the template commit; +# (b) the self-name and strip passes rewrote template-machinery tests, and +# tests/workflows/self_name_pass_test.sh then failed in the child; +# (c) the strip pass edited git-ignored sibling checkouts under _build/; +# (d) the closing advice armed a drift gate that a fresh mint cannot pass; +# plus a repository map generated from the stale index (Estate Rules red). +# +# This test drives the REAL recipe end to end, then asserts each property, +# with a negative control beside each new check so it cannot pass vacuously. +# It needs just, rustc, uuidgen, nickel and file, and fails (never skips) +# without them. Network-free: the template's history is read from a local +# snapshot via RSR_TEMPLATE_URL. +# +# Usage: bash tests/e2e/use_template_mint_test.sh [--keep] +set -euo pipefail +repo=$(git rev-parse --show-toplevel) +work=$(mktemp -d) +if [ "${1:-}" = "--keep" ]; then echo "keeping $work"; else trap 'rm -rf "$work"' EXIT; fi + +fail() { + echo "FAIL: $*" >&2 + # One annotation per failure, so the reason reaches the check list and the + # API and not only the raw log. + if [ "${GITHUB_ACTIONS:-}" = "true" ]; then + printf '::error title=use-this-template mint::%s\n' "$(printf '%s' "$*" | tr '\n' ' ')" + fi + exit 1 +} +pass() { echo "PASS: $*"; } +g() { git -c user.name=t -c user.email=t@example.org -c commit.gpgsign=false "$@"; } + +for tool in just rustc uuidgen nickel file; do + command -v "$tool" >/dev/null 2>&1 \ + || fail "$tool is required to run a real mint (not skipping: a skipped mint test is how this went untested)" +done + +# The four tests the lintel mint broke or rewrote. +FIXTURE_TESTS=( + tests/workflows/self_name_pass_test.sh + tests/workflows/template_conformance_test.sh + tests/e2e/template_instantiation_test.sh + tests/workflows/mint_cleanup_test.sh +) + +# ── 1. The template: this checkout's tree, committed or not, on main ──────── +T="$work/template" +g clone -q --no-local "$repo" "$T" +g -C "$T" checkout -q -B main +(cd "$repo" && git ls-files -z --cached --others --exclude-standard \ + | while IFS= read -r -d '' f; do { [ -e "$f" ] || [ -L "$f" ]; } && printf '%s\0' "$f"; done \ + | tar --null -T - -cf -) > "$work/tree.tar" +(cd "$T" && git ls-files -z | xargs -0 rm -f && tar xf "$work/tree.tar") +g -C "$T" add -A +g -C "$T" commit -q --allow-empty -m "template under test" +T_COMMIT=$(g -C "$T" rev-parse HEAD) +T_TREE=$(g -C "$T" rev-parse 'HEAD^{tree}') +T_OWNER=$(sed -n -E 's/^OWNER[[:space:]]*:=[[:space:]]*"([^"]+)".*/\1/p' "$T/Justfile" | head -1) +TEMPLATE_REPO=$(sed -n -E 's/^REPO[[:space:]]*:=[[:space:]]*"([^"]+)".*/\1/p' "$T/Justfile" | head -1) +T_SLUG="$T_OWNER/$TEMPLATE_REPO" + +# use_template DIR — what "Use this template" creates: one root commit with +# the template's tree, no shared history, origin = the new repository. +use_template() { + rm -rf "$1"; mkdir -p "$1" + g -C "$T" archive "$T_COMMIT" | tar x -C "$1" + g -C "$1" init -q -b main + g -C "$1" add -A + g -C "$1" commit -q -m "Initial commit" + g -C "$1" remote add origin git@github.com:example-owner/mint-check.git +} + +# mint DIR LOG — the non-interactive mint, isolated from this host's defaults +# file and global git config (an ORCID or signing key there would leak in). +mint() { + local cfg="$work/cfg"; mkdir -p "$cfg"; : > "$cfg/gitconfig" + (cd "$1" && env -i PATH="$PATH" HOME="$HOME" TMPDIR="${TMPDIR:-/tmp}" \ + ${RUSTUP_HOME:+RUSTUP_HOME="$RUSTUP_HOME"} ${CARGO_HOME:+CARGO_HOME="$CARGO_HOME"} \ + XDG_CONFIG_HOME="$cfg" GIT_CONFIG_GLOBAL="$cfg/gitconfig" GIT_CONFIG_NOSYSTEM=1 \ + RSR_NON_INTERACTIVE=1 RSR_TEMPLATE_URL="$T" RSR_MINT_TOOL_CACHE="$work/tools" \ + PROJECT_NAME="Mint Check" REPO=mint-check OWNER=example-owner \ + AUTHOR="Example Author" AUTHOR_EMAIL=author@example.org \ + timeout 900 just repo-init "$2" 2>&1 +} + +# ── 2. The child, with an ignored cache and an untracked probe ────────────── +C="$work/child" +use_template "$C" +[ "$(g -C "$C" rev-parse 'HEAD^{tree}')" = "$T_TREE" ] || fail 'fixture: the child tree is not the template tree' +C_HEAD=$(g -C "$C" rev-parse HEAD) +# The probe carries all three things the rewrite passes act on. +LB='{{'; RB='}}' +probe=" +${TEMPLATE_REPO} by ${LB}OWNER${RB}" +# An ignored sibling checkout, like lintel's _build/dependencies//. +mkdir -p "$C/_build/dependencies/sibling" +printf '%s\n' "$probe" > "$C/_build/dependencies/sibling/README.md" +g -C "$C" check-ignore -q _build/dependencies/sibling/README.md || fail 'fixture: _build/ is not ignored' +# Positive twin of the ignored cache: the same content in an untracked, +# not-ignored file IS the repository's and must be rewritten. Without it, an +# untouched cache could mean "the passes never ran" rather than "scoped". +printf '%s\n' "$probe" > "$C/mint-probe.md" +ignored_list() { (cd "$C" && git ls-files -o -i --exclude-standard | LC_ALL=C sort); } +IGN_LIST=$(ignored_list) +IGN_BEFORE=$(cd "$C" && printf '%s\n' "$IGN_LIST" | xargs -d '\n' sha256sum) +[ -n "$IGN_LIST" ] || fail 'fixture: no ignored files to protect' + +# ── 3. Negative control for (a): an unrecognisable tree aborts, untouched ─── +N="$work/no-match" +use_template "$N" +printf 'edited before minting\n' >> "$N/README.adoc" +g -C "$N" commit -q --amend -am "Initial commit" +if mint "$N" "$work/no-match.log"; then fail 'a tree matching no template commit was minted'; fi +grep -q 'mint aborted before writing anything' "$work/no-match.log" \ + || { cat "$work/no-match.log" >&2; fail 'the no-match abort did not say why'; } +[ -z "$(g -C "$N" status --porcelain)" ] || fail 'the aborted mint wrote to the tree' +pass "(a-) a child whose tree matches no template commit aborts before writing" + +# ── 4. Negative control for the manifest: a stale entry aborts, untouched ─── +M="$work/stale" +use_template "$M" +printf 'tests/workflows/no_such_test.sh\n' >> "$M/.machine_readable/mint-verbatim.txt" +g -C "$M" commit -q --amend -am "Initial commit" +if mint "$M" "$work/stale.log"; then fail 'a stale mint-verbatim entry was accepted'; fi +grep -q 'stale entry' "$work/stale.log" || { cat "$work/stale.log" >&2; fail 'the stale-entry abort did not say why'; } +[ -z "$(g -C "$M" status --porcelain)" ] || fail 'the stale-manifest mint wrote to the tree' +pass "(b-) a stale mint-verbatim entry stops the mint before it writes" + +# ── 5. The mint ───────────────────────────────────────────────────────────── +mint "$C" "$work/mint.log" || { + cat "$work/mint.log" >&2 + if [ "${GITHUB_ACTIONS:-}" = "true" ]; then + printf '::error title=just repo-init failed::%s\n' \ + "$(tail -n 40 "$work/mint.log" | awk '{printf "%s%%0A", $0}')" + fi + fail 'just repo-init failed on a Use-this-template child' +} +pass "the non-interactive mint completes on a Use-this-template child" +DEED="$C/mint-check_chora.deed" +[ -f "$DEED" ] || fail 'the child deed was not renamed to mint-check_chora.deed' +field() { bash "$C/scripts/deed-field.sh" "$DEED" "$@"; } + +# ── (a) provenance names the template's commit and tree ───────────────────── +[ "$(field provenance template-repo)" = "$T_SLUG" ] || fail "template-repo is $(field provenance template-repo), want $T_SLUG" +[ "$(field provenance template-commit)" = "$T_COMMIT" ] || fail "template-commit is $(field provenance template-commit), want $T_COMMIT" +[ "$(field provenance template-tree)" = "$T_TREE" ] || fail "template-tree is $(field provenance template-tree), want $T_TREE" +[ "$(field provenance template-branch)" = main ] || fail "template-branch is $(field provenance template-branch), want main" +[ "$(field variant parent-pin)" = "$T_COMMIT" ] || fail "variant parent-pin is $(field variant parent-pin), want $T_COMMIT" +if grep -qF "$C_HEAD" "$DEED"; then fail "the deed records the child's own commit $C_HEAD"; fi +pass "(a) provenance and variant name template commit ${T_COMMIT:0:12} and its tree, never the child's HEAD" + +# ── (b) the fixture tests are carried unchanged, and pass in the child ────── +while IFS= read -r v; do + g -C "$C" diff --quiet HEAD -- "$v" || fail "the mint modified $v, listed in mint-verbatim.txt" +done < <(sed -e 's/#.*//' -e 's/[[:space:]]*$//' "$C/.machine_readable/mint-verbatim.txt" | grep -v '^$') +for t in "${FIXTURE_TESTS[@]}"; do + g -C "$C" diff --quiet HEAD -- "$t" || fail "the mint modified $t" + (cd "$C" && RSR_MINT_TOOL_CACHE="$work/tools" bash "$t") > "$work/fixture.log" 2>&1 \ + || { cat "$work/fixture.log" >&2; fail "$t fails in the minted child"; } +done +pass "(b) the four template-machinery tests are byte-identical and pass in the child" + +# ── (c) nothing outside the repository's own files changed ────────────────── +[ "$(cd "$C" && printf '%s\n' "$IGN_LIST" | xargs -d '\n' sha256sum)" = "$IGN_BEFORE" ] \ + || fail 'the mint changed git-ignored files' +# The one ignored file the mint may CREATE is the arrival pack's declared +# build artefact (.gitignore, arrival-pack/README.adoc), which `just claude-md` +# writes on every run. Any other new ignored file is a write outside the repo. +new_ignored=$(comm -13 <(printf '%s\n' "$IGN_LIST") <(ignored_list) \ + | grep -vxF .machine_readable/arrival-pack/claude-md-data.json || true) +[ -z "$new_ignored" ] || { echo "$new_ignored" >&2; fail 'the mint created files outside the repository'; } +if grep -q 'TEMPLATE INSTRUCTIONS' "$C/mint-probe.md"; then fail 'probe: the strip pass skipped a repository file'; fi +if grep -qF "$TEMPLATE_REPO" "$C/mint-probe.md"; then fail 'probe: the self-name pass skipped a repository file'; fi +if grep -qF "${LB}OWNER${RB}" "$C/mint-probe.md"; then fail 'probe: the substitution pass skipped a repository file'; fi +# The probe stays: it was a repository file at mint, so the map lists it. +pass "(c) ignored files are byte-identical, none created but the arrival-pack artefact; the same content in a repository file was rewritten" + +# ── (d) the drift gate is no longer recommended for a minted repo ─────────── +if grep -q 'arm the drift gate' "$work/mint.log"; then fail 'repo-init still recommends arming the drift gate'; fi +grep -q 'scripts/check-template-conformance.sh' "$work/mint.log" || fail 'repo-init does not point at the conformance check' +g -C "$C" add -A +g -C "$C" commit -q -m "mint" +(cd "$C" && bash scripts/check-template-conformance.sh --quiet) > "$work/conf.log" 2>&1 \ + || { cat "$work/conf.log" >&2; fail 'the conformance check fails on a fresh mint'; } +# The gate itself must still FAIL here (no silent green), say why, and not +# list the mint's own removals, which the (variant) clause now declares. +if (cd "$C" && bash scripts/check-variant-drift.sh "$T") > "$work/drift.log" 2>&1; then + fail 'the drift gate turned green on a minted repo without (normalise) support: suspicious' +fi +grep -q 'records :role "minted-repo"' "$work/drift.log" || fail 'the drift gate does not explain its minted-repo findings' +if grep -q 'declare in paths.removed' "$work/drift.log"; then + grep 'declare in paths.removed' "$work/drift.log" >&2; fail 'the mint removed paths it did not declare' +fi +pass "(d) stage 8 points at the conformance check (green); the drift gate still fails loudly, removals declared" + +# ── The repository map is regenerated last ────────────────────────────────── +# Same check Estate Rules runs, on the committed mint: regenerate from the +# index and require no difference. +(cd "$C" && bash scripts/gen-repo-map.sh . >/dev/null) +g -C "$C" diff --quiet -- docs/architecture/REPOSITORY-MAP.adoc \ + || { g -C "$C" diff -- docs/architecture/REPOSITORY-MAP.adoc | head -20 >&2; fail 'the committed map is stale'; } +# Negative control: index mode, run where the mint runs it (before the first +# commit, after a removal), reproduces the stale map lintel shipped. +SM="$work/stale-map" +use_template "$SM" +(cd "$SM" && rm -rf archetypes && bash scripts/gen-repo-map.sh . >/dev/null) +grep -q '^| `archetypes' "$SM/docs/architecture/REPOSITORY-MAP.adoc" \ + || fail 'control: index mode no longer shows the pre-commit staleness; this check is vacuous' +pass "the committed map is fresh (the index-mode control reproduces lintel's stale map)" + +(cd "$C" && env -u GITHUB_REPOSITORY bash scripts/check-no-placeholders.sh .) > "$work/ph.log" 2>&1 \ + || { cat "$work/ph.log" >&2; fail 'the minted child fails its own placeholder gate'; } +pass "the minted child passes its own placeholder gate" + +echo "PASS: Use-this-template mint" diff --git a/tests/ffi_strings_test.sh b/tests/ffi_strings_test.sh new file mode 100644 index 00000000..4879ed16 --- /dev/null +++ b/tests/ffi_strings_test.sh @@ -0,0 +1,111 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# Regression tests for the dupeZ compatibility helper and its two callers. +# Instantiate only the FFI fixture, using the repository's zig build test. +# Usage: bash tests/ffi_strings_test.sh (requires Zig 0.15.2+) +set -euo pipefail +repo=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd) +work=$(mktemp -d) +trap 'rm -rf "$work"' EXIT +command -v zig >/dev/null || { echo 'FAIL: Zig is required' >&2; exit 1; } +zig_bin=$(command -v zig) +# Resolve mise shims while still inside the configured repository. +if command -v mise >/dev/null 2>&1; then + zig_bin=$(mise which zig 2>/dev/null || printf '%s' "$zig_bin") +fi +cp -R "$repo/src/interface/ffi" "$work/ffi" +sed -i -e 's/{{project}}/test_project/g' -e 's/{{PROJECT}}/TEST_PROJECT/g' \ + "$work/ffi/build.zig" "$work/ffi/src/main.zig" "$work/ffi/test/integration_test.zig" +# Tests share the production module so the private helper can be exercised +# with the leak-detecting allocator without changing the public FFI surface. +cat >> "$work/ffi/src/main.zig" <<'ZIG' + +test "dupeZ owns a sentinel terminated copy including empty and binary inputs" { + for ([_][]const u8{ "", "abc", "héllo 😀", "a\x00b" }) |input| { + const copy = try dupeZ(std.testing.allocator, input); + defer std.testing.allocator.free(copy); + try std.testing.expectEqualSlices(u8, input, copy); + try std.testing.expectEqual(@as(u8, 0), copy.ptr[copy.len]); + } + var input = [_]u8{ 'a', 'b' }; + const copy = try dupeZ(std.testing.allocator, &input); + defer std.testing.allocator.free(copy); + input[0] = 'z'; + try std.testing.expectEqualStrings("ab", copy); +} + +test "dupeZ propagates allocation failure without leaking" { + var failing = std.testing.FailingAllocator.init(std.testing.allocator, .{ .fail_index = 0 }); + try std.testing.expectError(error.OutOfMemory, dupeZ(failing.allocator(), "data")); +} + +test "get_string returns independent owned C strings and clears an old error" { + const handle = test_project_init() orelse return error.InitFailed; + defer test_project_free(handle); + _ = test_project_process(null, 0); + const first = test_project_get_string(handle) orelse return error.StringFailed; + defer test_project_free_string(first); + const second = test_project_get_string(handle) orelse return error.StringFailed; + defer test_project_free_string(second); + try std.testing.expect(first != second); + try std.testing.expectEqualStrings("Example result", std.mem.span(first)); + try std.testing.expectEqual(@as(u8, 0), first[14]); + try std.testing.expect(test_project_last_error() == null); +} + +test "last_error copies survive subsequent error clearing" { + const handle = test_project_init() orelse return error.InitFailed; + defer test_project_free(handle); + try std.testing.expect(test_project_get_string(null) == null); + const first = test_project_last_error() orelse return error.ExpectedError; + defer test_project_free_string(first); + const second = test_project_last_error() orelse return error.ExpectedError; + defer test_project_free_string(second); + try std.testing.expect(first != second); + try std.testing.expectEqualStrings("Null handle", std.mem.span(first)); + try std.testing.expectEqual(Result.ok, test_project_process(handle, 0)); + try std.testing.expect(test_project_last_error() == null); + try std.testing.expectEqualStrings("Null handle", std.mem.span(second)); +} + +test "get_string reports allocation failure on an initialized handle" { + var failing = std.testing.FailingAllocator.init(std.testing.allocator, .{ .fail_index = 0 }); + var handle = Handle{ .allocator = failing.allocator(), .initialized = true }; + defer clearError(); + try std.testing.expect(test_project_get_string(&handle) == null); + const message = test_project_last_error() orelse return error.ExpectedError; + defer test_project_free_string(message); + try std.testing.expectEqualStrings("Failed to allocate string", std.mem.span(message)); +} + +test "an empty C string still needs allocation for its sentinel" { + var failing = std.testing.FailingAllocator.init(std.testing.allocator, .{ .fail_index = 0 }); + try std.testing.expectError(error.OutOfMemory, dupeZ(failing.allocator(), "")); +} + +test "get_string refuses an uninitialized handle before allocating" { + var failing = std.testing.FailingAllocator.init(std.testing.allocator, .{ .fail_index = 0 }); + var handle = Handle{ .allocator = failing.allocator(), .initialized = false }; + defer clearError(); + try std.testing.expect(test_project_get_string(&handle) == null); + const message = test_project_last_error() orelse return error.ExpectedError; + defer test_project_free_string(message); + try std.testing.expectEqualStrings("Handle not initialized", std.mem.span(message)); + try std.testing.expect(!failing.has_induced_failure); +} + +test "freeing one error copy preserves the stored error and other copies" { + defer clearError(); + try std.testing.expect(test_project_get_string(null) == null); + const first = test_project_last_error() orelse return error.ExpectedError; + test_project_free_string(first); + const second = test_project_last_error() orelse return error.ExpectedError; + defer test_project_free_string(second); + try std.testing.expectEqualStrings("Null handle", std.mem.span(second)); + test_project_free_string(null); + const third = test_project_last_error() orelse return error.ExpectedError; + defer test_project_free_string(third); + try std.testing.expectEqualStrings("Null handle", std.mem.span(third)); +} +ZIG +(cd "$work/ffi" && "$zig_bin" build test) diff --git a/tests/invisible-characters-test.sh b/tests/invisible-characters-test.sh index f73e3f2a..596a310f 100755 --- a/tests/invisible-characters-test.sh +++ b/tests/invisible-characters-test.sh @@ -34,10 +34,10 @@ printf 'newline name:\302\240\n' > "$fixtures/with newline.md" # Estate-shaped files that the extension filter did not cover until 2026-09-02: -# .a2ml carries repo IDENTITY (uuid, forge, lineage), and the recipe files are -# extensionless. An invisible character in either is exactly the kind of damage +# the repo deed carries repo IDENTITY (uuid, forge, lineage), and the recipe +# files are extensionless. An invisible character in either is exactly the kind of damage # this scanner exists to find, and both were silently skipped. -printf 'uuid\302\240= "x"\n' > "$fixtures/IDENTITY.a2ml" +printf '(repo-deed :repo-uuid\302\240"x")\n' > "$fixtures/fixture_chora.deed" printf 'test:\n\techo\302\240hi\n' > "$fixtures/Justfile" "$scanner" "$fixtures" "$results" "$blocking_results" diff --git a/tests/proven_suite_test.sh b/tests/proven_suite_test.sh new file mode 100755 index 00000000..b3317d8f --- /dev/null +++ b/tests/proven_suite_test.sh @@ -0,0 +1,452 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# Silence + Firing + Setup-error test suite for the proven-tests-and-benches +# toolchain wired in scripts/: +# - scripts/check-escape-hatches.sh +# - scripts/compute-bench-baseline.sh +# - scripts/check-bench-regression.sh +# - scripts/emit-aggregate-inputs.sh +# +# Every negative fixture is generated ephemerally in $WORK (mktemp -d) so no +# static escape-hatch token ever resides in a tracked .idr file. +set -euo pipefail + +REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +WORK="$(mktemp -d)" +trap 'rm -rf "$WORK"' EXIT + +pass=0 +fail=0 + +assert_rc() { # assert_rc