From 533be4bd2f0256fa4bb1c1a9131efd02e6ac831b Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 14 Nov 2026 12:48:27 +0000 Subject: [PATCH 01/11] chore: upgrade to template f63b965 by three-way merge Base is 8c7baf794b8abb34c08f85b4446396f00342a364 (the deed's :template-commit, tree verified), theirs is rsr-template-repo main f63b965, ours is sholes main. The deed records no mint answers, so only {{PROJECT_NAME}} (sholes) and {{OWNER}} (hyperpolymath) are filled, inferred from the repo's own files, and only in the files the upgrade adds them to raw. Owner-approved under the standing rule with limits: .cursorrules and .windsurfrules are deleted (the repo's copies equal the template's retired content with tokens filled), the stale build/docs-seed/ block is removed from .hypatia-ignore and the matching structural_drift entry from the rule-order policy. Also: the container-templates deed line is split onto three lines copied from the template, both container FROM lines are pinned by digest only, and LICENSE.adoc is added. The template's deploy.k9.ncl.in is not added. Co-Authored-By: Claude --- .coderabbit.yaml | 33 +- .cursorrules | 55 - .devcontainer/Containerfile | 6 +- .gitbot-fleet/enrolment.json | 1 + .gitbot-fleet/report-backs/README.md | 35 + .github/SECURITY.md | 11 +- .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/hooks/pre-push | 7 +- .github/hooks/scan-secrets.sh | 12 +- .github/hooks/validate-deed.sh | 391 +--- .github/hooks/validate-k9.sh | 411 +---- .github/label-classifier.json | 740 +------- .github/labels.json | 261 +-- .github/rulesets/README.adoc | 64 +- .github/rulesets/base.json | 103 +- .github/rulesets/branch-floor.json | 17 +- .github/rulesets/require-linear-history.json | 20 +- .github/rulesets/require-signed-commits.json | 20 +- .github/workflows/README.adoc | 210 ++- .github/workflows/actions.lock | 171 +- .github/workflows/codeql.yml | 5 +- .github/workflows/dependabot-automerge.yml | 171 +- .github/workflows/docker-build.yml | 8 +- .github/workflows/dogfood-gate.yml | 650 ++++--- .github/workflows/dogfood-summary.yml | 2 +- .github/workflows/eclexiaiser-validate.yml | 6 +- .github/workflows/empty-linter.yml | 10 +- .github/workflows/estate-rules.yml | 225 ++- .github/workflows/fork-governance.yml | 502 ++++++ .github/workflows/governance.yml | 58 +- .github/workflows/groove-check.yml | 22 +- .github/workflows/hypatia-scan.yml | 173 +- .github/workflows/k9-validate.yml | 64 - .github/workflows/label-triage.yml | 2 +- .github/workflows/labels.yml | 2 +- .github/workflows/lock-sync-gate.yml | 6 + .github/workflows/main-estate-audit.yml | 74 +- .github/workflows/mirror.yml | 34 +- .github/workflows/ossf-best-practices.yml | 18 +- .github/workflows/proven-tests.yml | 108 ++ .github/workflows/quality.yml | 42 +- .github/workflows/release.yml | 2 +- .github/workflows/rsr-compliance-canary.yml | 6 +- .github/workflows/runtime-policy.yml | 82 - .github/workflows/rust-ci.yml | 45 +- .github/workflows/scorecard.yml | 29 +- .github/workflows/secret-scanner.yml | 376 +++- .github/workflows/security-policy.yml | 6 +- .github/workflows/sonarqube.yml | 12 +- .github/workflows/squabble.yml | 93 + .github/workflows/static-analysis-gate.yml | 649 ++++--- .github/workflows/verdict-grid-publish.yml | 170 ++ .github/workflows/workflow-linter.yml | 23 +- .gitignore | 4 +- .hypatia-ignore | 19 +- .machine_readable/coaptation/README.adoc | 61 +- .machine_readable/coaptation/coapt.k9.ncl | 3 +- .machine_readable/coaptation/coapt.ncl | 15 +- .../coaptation/core/Coaptation.idr | 368 +++- .machine_readable/coaptation/extract-facts.sh | 18 +- .../coaptation/receipts/latest.toml | 12 +- .machine_readable/contractiles/README.adoc | 8 +- .../contractiles/adjust/adjust.k9.ncl | 14 +- .../contractiles/bust/bust.k9.ncl | 20 +- .../contractiles/dust/dust.k9.ncl | 14 +- .../contractiles/intend/intend.k9.ncl | 33 +- .../contractiles/must/must.k9.ncl | 64 +- .../contractiles/trust/trust.k9.ncl | 35 +- .machine_readable/internal-links-allow.txt | 8 + .machine_readable/mint-verbatim.txt | 39 + .machine_readable/policies/README.adoc | 21 + .../policies/hypatia-rule-order.json | 1 + .machine_readable/required-contexts-allow.txt | 35 + .machine_readable/root-allow.txt | 24 +- .../scripts/maintenance/maint-assault.sh | 10 +- .machine_readable/self-validating/README.adoc | 10 +- .../self-validating/methodology-guard.k9.ncl | 1 + .../testing/adversarial-content.k9.ncl | 47 + .windsurfrules | 52 - CHANGELOG.adoc | 519 ++++++ CODE_OF_CONDUCT.adoc | 32 + CONTRIBUTING.adoc | 6 +- GEMINI.md | 8 - Justfile | 78 +- LICENSE.adoc | 2 + benches/baseline.json | 1 + benches/template_bench.sh | 325 ++-- build/container/Containerfile | 12 +- build/container/README.adoc | 54 +- build/container/compose.example.yaml | 233 ++- build/just/assess.just | 40 +- build/just/container.just | 62 +- build/just/provision-lib.sh | 18 +- build/just/repo-init.just | 1394 +++++++++++--- build/just/validate.just | 91 +- ci/.pre-commit-config.yaml | 10 +- coordination.k9.ncl | 1 + docs/AI_INSTALLATION_GUIDE.adoc | 19 +- docs/HYPATIA-RULE-ORDER.adoc | 364 ++++ docs/MAINTAINERS.adoc | 4 +- docs/SETUP.adoc | 11 +- docs/governance/CRG-CRITERIA.adoc | 2 +- docs/onboarding/QUICKSTART-DEV.adoc | 2 +- docs/onboarding/QUICKSTART-USER.adoc | 4 +- docs/onboarding/llm-warmup-maintainer.adoc | 4 +- docs/onboarding/llm-warmup-user.adoc | 7 +- .../RSR-TEMPLATE-DAMAGE-2026-10-30.adoc | 486 +++++ docs/status/PROOF-NEEDS.adoc | 34 +- mise.toml | 1 + scripts/adopt-canon-lockstep.sh | 94 + scripts/bench-stats.jq | 96 + scripts/campaigns/repo-map-trim.campaign | 29 + scripts/canon-pin-check.sh | 213 +++ scripts/chain-mint.sh | 457 +++++ 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 | 213 +++ scripts/check-ijson-jcs.sh | 152 ++ scripts/check-internal-links.sh | 171 ++ scripts/check-invisible-characters.sh | 2 +- scripts/check-lock-sync.sh | 240 ++- scripts/check-mint-drift.sh | 238 +++ scripts/check-mint-tokens.sh | 214 +++ scripts/check-mint-tools.sh | 70 + scripts/check-mise-language.sh | 232 +++ scripts/check-no-a2ml.sh | 34 +- scripts/check-no-placeholders.sh | 44 +- scripts/check-proofs.sh | 91 +- scripts/check-required-contexts.sh | 238 +++ scripts/check-spdx-headers.sh | 330 ++++ scripts/check-variant-drift.sh | 17 + scripts/check-workflow-edges.sh | 316 ++++ scripts/compute-bench-baseline.sh | 118 ++ scripts/deed-field.sh | 56 +- scripts/edict-run.rs | 320 ++++ scripts/emit-aggregate-inputs.sh | 91 + scripts/format-container-kyaml.sh | 112 ++ scripts/gen-repo-map.sh | 46 +- scripts/governance-badge.js | 1030 +++++++++++ scripts/ijson-jcs-cli.js | 408 +++++ scripts/is-template-tree.sh | 33 + scripts/kyaml-format.sh | 127 ++ scripts/lock-sync-fix.sh | 309 ++++ scripts/merge-actions-lock.rs | 2 + scripts/migrate-wellknown-to-www.sh | 12 +- scripts/pin-container-digests.sh | 150 ++ scripts/prune-archetype-modules.sh | 76 + scripts/prune-dependabot-ecosystems.rs | 2 + scripts/render-mise.sh | 207 +++ scripts/replay-mint.sh | 127 ++ scripts/resolve-template-pin.sh | 216 +++ scripts/rsr-campaign.sh | 11 +- scripts/run-proven-suite.sh | 273 +++ scripts/rust-tool.sh | 26 +- scripts/scan-dangerous.sh | 10 +- scripts/strip-instruction-blocks.rs | 112 +- scripts/survey-template-damage.sh | 96 + scripts/sweep-wellknown.sh | 15 +- scripts/uuid-v8.sh | 29 + scripts/uuid5-url.sh | 29 + scripts/validate-template.sh | 92 +- scripts/verdict-grid-lane.sh | 555 ++++++ session/custom-checks.k9.ncl | 1 + sholes_chora.deed | 10 +- src/interface/Abi/Foreign.idr | 73 +- src/interface/Abi/Types.idr | 117 +- src/interface/ffi/src/main.zig | 30 +- tests/aspect_tests.sh | 87 +- tests/e2e.sh | 4 +- tests/e2e/chain_mint_test.sh | 709 ++++++++ tests/e2e/julia_mint_test.sh | 23 +- tests/e2e/language_profiles_mint_test.sh | 294 +++ tests/e2e/template_instantiation_test.sh | 106 +- tests/e2e/use_template_mint_test.sh | 690 +++++++ tests/ffi_strings_test.sh | 123 ++ tests/proven_suite_test.sh | 453 +++++ tests/run_proven_suite_test.sh | 185 ++ tests/shape/rust_cli_root_shape_test.sh | 101 ++ tests/workflows/adopt_canon_lockstep_test.sh | 124 ++ tests/workflows/archetype_lock_merge_test.sh | 69 +- tests/workflows/canon_pin_check_test.sh | 160 ++ tests/workflows/chain_tree_of_test.sh | 76 + tests/workflows/check_ijson_jcs_test.sh | 279 +++ tests/workflows/check_lock_sync_test.sh | 423 +++++ tests/workflows/check_no_a2ml_test.sh | 31 +- tests/workflows/coaptation_families_test.sh | 82 + tests/workflows/container_kyaml_test.sh | 166 ++ tests/workflows/dependabot_automerge_test.sh | 109 ++ tests/workflows/devcontainer_test.sh | 100 + tests/workflows/edict_trial_test.sh | 81 + tests/workflows/governance_badge_test.js | 1606 +++++++++++++++++ tests/workflows/governance_badge_test.sh | 275 +++ tests/workflows/governance_policy_test.sh | 231 +++ tests/workflows/hypatia_ignore_test.sh | 230 +++ tests/workflows/hypatia_rule_order_test.sh | 273 +++ tests/workflows/internal_links_test.sh | 116 ++ tests/workflows/kyaml_format_test.sh | 127 ++ tests/workflows/kyaml_ratchet_test.sh | 256 +++ tests/workflows/lock_sync_fix_test.sh | 142 ++ .../workflows/migrate_wellknown_date_test.sh | 46 + tests/workflows/mint_cleanup_test.sh | 36 +- tests/workflows/mint_gates_test.sh | 323 ++++ tests/workflows/mint_tools_preflight_test.sh | 94 + tests/workflows/non_interactive_mint_test.sh | 41 + tests/workflows/replay_mint_env_test.sh | 38 + tests/workflows/repo_map_newline_test.sh | 29 + tests/workflows/repo_map_quotes_test.sh | 30 + tests/workflows/resolve_template_pin_test.sh | 164 ++ tests/workflows/rhodibot_canary_test.sh | 46 + .../workflows/rsr_campaign_tokenless_test.sh | 36 + tests/workflows/runtime_policy_fold_test.sh | 169 ++ .../workflows/secret_scanner_contract_test.sh | 230 +++ tests/workflows/self_name_pass_test.sh | 138 +- tests/workflows/squabble_gate_test.sh | 476 +++++ tests/workflows/uuid5_url_test.sh | 57 + tests/workflows/uuid_v8_test.sh | 68 + tests/workflows/validate_workflows_test.sh | 8 +- tests/workflows/verdict_grid_test.sh | 736 ++++++++ tests/workflows/workflow_edges_test.sh | 241 +++ tests/workflows/workflow_evidence_test.sh | 174 ++ tests/workflows/workflow_gap_fixes_test.sh | 92 + verification/proofs/README.adoc | 121 +- verification/proofs/agda/MANIFEST | 7 +- verification/proofs/agda/Properties.agda | 49 +- 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/MANIFEST | 13 +- verification/proofs/idris2/Types.idr | 2 +- verification/proofs/lean4/MANIFEST | 2 +- verification/proofs/tlaplus/MC.cfg | 11 + verification/proofs/tlaplus/MC.tla | 14 + verification/proofs/tlaplus/StateMachine.tla | 19 +- www/errors/430.html | 17 + www/runbooks/deploy.adoc | 4 +- www/schemas/aibdp-schema-v0.2.json | 378 +--- www/tests/check-bind-safety.sh | 2 +- 244 files changed, 27494 insertions(+), 4711 deletions(-) delete mode 100644 .cursorrules create mode 100644 .gitbot-fleet/enrolment.json create mode 100644 .gitbot-fleet/report-backs/README.md 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/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 create mode 100644 .machine_readable/internal-links-allow.txt create mode 100644 .machine_readable/mint-verbatim.txt create mode 100644 .machine_readable/policies/hypatia-rule-order.json create mode 100644 .machine_readable/required-contexts-allow.txt create mode 100644 .machine_readable/testing/adversarial-content.k9.ncl delete mode 100644 .windsurfrules create mode 100644 CODE_OF_CONDUCT.adoc delete mode 100644 GEMINI.md create mode 100644 LICENSE.adoc create mode 100644 benches/baseline.json create mode 100644 docs/HYPATIA-RULE-ORDER.adoc create mode 100644 docs/reports/compliance/RSR-TEMPLATE-DAMAGE-2026-10-30.adoc create mode 100755 scripts/adopt-canon-lockstep.sh create mode 100644 scripts/bench-stats.jq create mode 100644 scripts/campaigns/repo-map-trim.campaign create mode 100755 scripts/canon-pin-check.sh create mode 100755 scripts/chain-mint.sh 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 100755 scripts/check-internal-links.sh create mode 100755 scripts/check-mint-drift.sh create mode 100644 scripts/check-mint-tokens.sh create mode 100644 scripts/check-mint-tools.sh create mode 100644 scripts/check-mise-language.sh create mode 100755 scripts/check-required-contexts.sh create mode 100755 scripts/check-spdx-headers.sh create mode 100755 scripts/check-workflow-edges.sh create mode 100755 scripts/compute-bench-baseline.sh create mode 100644 scripts/edict-run.rs create mode 100755 scripts/emit-aggregate-inputs.sh create mode 100644 scripts/format-container-kyaml.sh create mode 100644 scripts/governance-badge.js create mode 100755 scripts/ijson-jcs-cli.js create mode 100755 scripts/is-template-tree.sh create mode 100755 scripts/kyaml-format.sh create mode 100755 scripts/lock-sync-fix.sh 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/replay-mint.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/uuid-v8.sh create mode 100755 scripts/uuid5-url.sh create mode 100755 scripts/verdict-grid-lane.sh create mode 100755 tests/e2e/chain_mint_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/shape/rust_cli_root_shape_test.sh create mode 100755 tests/workflows/adopt_canon_lockstep_test.sh create mode 100755 tests/workflows/canon_pin_check_test.sh create mode 100755 tests/workflows/chain_tree_of_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/coaptation_families_test.sh create mode 100644 tests/workflows/container_kyaml_test.sh create mode 100644 tests/workflows/dependabot_automerge_test.sh create mode 100644 tests/workflows/devcontainer_test.sh create mode 100755 tests/workflows/edict_trial_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 100755 tests/workflows/internal_links_test.sh create mode 100644 tests/workflows/kyaml_format_test.sh create mode 100644 tests/workflows/kyaml_ratchet_test.sh create mode 100755 tests/workflows/lock_sync_fix_test.sh create mode 100755 tests/workflows/migrate_wellknown_date_test.sh create mode 100644 tests/workflows/mint_gates_test.sh create mode 100755 tests/workflows/mint_tools_preflight_test.sh create mode 100755 tests/workflows/replay_mint_env_test.sh create mode 100644 tests/workflows/repo_map_newline_test.sh create mode 100644 tests/workflows/repo_map_quotes_test.sh create mode 100755 tests/workflows/resolve_template_pin_test.sh create mode 100755 tests/workflows/rhodibot_canary_test.sh create mode 100755 tests/workflows/rsr_campaign_tokenless_test.sh create mode 100644 tests/workflows/runtime_policy_fold_test.sh create mode 100755 tests/workflows/secret_scanner_contract_test.sh create mode 100755 tests/workflows/squabble_gate_test.sh create mode 100755 tests/workflows/uuid5_url_test.sh create mode 100755 tests/workflows/uuid_v8_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 tests/workflows/workflow_gap_fixes_test.sh create mode 100644 verification/proofs/tlaplus/MC.cfg create mode 100644 verification/proofs/tlaplus/MC.tla create mode 100644 www/errors/430.html diff --git a/.coderabbit.yaml b/.coderabbit.yaml index 446daa8..6342c2c 100644 --- a/.coderabbit.yaml +++ b/.coderabbit.yaml @@ -1,16 +1,33 @@ # SPDX-License-Identifier: MPL-2.0 -# CodeRabbit configuration. Schema: https://coderabbit.ai/integrations/schema.v2.json -# -# Docstring Coverage pre-merge check is pinned to `mode: warning` as an explicit -# estate decision rather than left to the vendor default. Some estate repos' -# rulesets require the `CodeRabbit` status context; an `error` mode would make -# them unmergeable at today's docstring-coverage baseline. Raise it per repo only -# once that repo's coverage clears the threshold. +# 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: true + 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 28fe7ec..0000000 --- a/.cursorrules +++ /dev/null @@ -1,55 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# 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: Jonathan D.A. Jewell (hyperpolymath) - -# 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. - -# 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 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 -> 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 bd83118..a86643b 100644 --- a/.devcontainer/Containerfile +++ b/.devcontainer/Containerfile @@ -27,11 +27,11 @@ RUN apk update && apk add --no-cache \ # 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 +ARG NICKEL_VERSION=1.18.0 RUN set -eu; \ case "$(uname -m)" in \ - x86_64) asset=nickel-x86_64-linux; sum=afcdfa6e0fff31760cf229e85997456c02c00b8b3b84ff38f897ac7b3f39ae34 ;; \ - aarch64) asset=nickel-arm64-linux; sum=9d7e027fde829b5788c92231c27fcfc926ee841d0716d655cee202c9f582e0c0 ;; \ + x86_64) asset=nickel-x86_64-linux; sum=9cba4dd65ae9915ec61f73033aafcff307a377665a83fd8f530df086763318cb ;; \ + aarch64) asset=nickel-arm64-linux; sum=626571e76b66523f454abb373fda4935e2b2685a008ebb8a783b0d20321ffdbd ;; \ *) echo "no Nickel release binary for $(uname -m)" >&2; exit 1 ;; \ esac; \ curl --proto '=https' --proto-redir '=https' -fsSL \ diff --git a/.gitbot-fleet/enrolment.json b/.gitbot-fleet/enrolment.json new file mode 100644 index 0000000..28d108e --- /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 0000000..526ba64 --- /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/SECURITY.md b/.github/SECURITY.md index 839a32e..387baff 100644 --- a/.github/SECURITY.md +++ b/.github/SECURITY.md @@ -5,10 +5,13 @@ Copyright (c) Jonathan D.A. Jewell # Security Policy We take security seriously. We appreciate your efforts to responsibly disclose vulnerabilities and will make every effort to acknowledge your contributions. @@ -307,7 +310,7 @@ To stay informed about security updates: - **Watch this repository**: Click "Watch" → "Custom" → Select "Security alerts" - **GitHub Security Advisories**: Published at [Security Advisories](https://github.com/hyperpolymath/sholes/security/advisories) -- **Release notes**: Security fixes noted in [CHANGELOG](../CHANGELOG.md) +- **Release notes**: Security fixes noted in [CHANGELOG](../CHANGELOG.adoc) ### Update Policy @@ -355,8 +358,8 @@ When using sholes, we recommend: ## Additional Resources - [Security Advisories](https://github.com/hyperpolymath/sholes/security/advisories) -- [Changelog](../CHANGELOG.md) -- [Contributing Guidelines](CONTRIBUTING.md) +- [Changelog](../CHANGELOG.adoc) +- [Contributing Guidelines](../CONTRIBUTING.adoc) - [CVE Database](https://cve.mitre.org/) - [CVSS Calculator](https://www.first.org/cvss/calculator/3.1) diff --git a/.github/actions/squabble/README.adoc b/.github/actions/squabble/README.adoc new file mode 100644 index 0000000..65e5425 --- /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 0000000..a42a408 --- /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 0000000..8c9de84 --- /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 0000000..339805f --- /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/hooks/pre-push b/.github/hooks/pre-push index 7e00686..7174c81 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 b26dd40..c3b0ebb 100755 --- a/.github/hooks/scan-secrets.sh +++ b/.github/hooks/scan-secrets.sh @@ -7,13 +7,15 @@ # ── Why this is NOT duplicated work ───────────────────────────────────────── # The estate runs a TWO-TIER secret defence: # -# CI gitleaks, via the standards `secret-scanner-reusable.yml` -# (gitleaks + rust-secrets + shell-secrets). Catches what reaches the +# CI gitleaks, rust-secrets and shell-secrets, inline in +# `.github/workflows/secret-scanner.yml` (the same three scanner +# contracts the standards reusable publishes, kept inline so the three +# check names are this repository's own). Catches what reaches the # remote, on every pull_request and push to main. # LOCAL TruffleHog — this script — before the push leaves the machine. # -# Different detection engines at different checkpoints. The reusable's header -# retires TruffleHog "as redundant with gitleaks"; that judgement is scoped to +# Different detection engines at different checkpoints. The estate retired +# TruffleHog "as redundant with gitleaks"; that judgement is scoped to # CI, where running both cost twice over one population. It is not a reason to # leave the local tier unguarded. DO NOT delete this script as duplication — # see .github/workflows/README.adoc, "Secret scanning is single-sourced". @@ -162,7 +164,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 2197d51..733fa92 100755 --- a/.github/hooks/validate-deed.sh +++ b/.github/hooks/validate-deed.sh @@ -2,351 +2,82 @@ # 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 .deed files and validates the checks below. A .a2ml file is an -# error on sight: the format is retired estate-wide and its facts belong in -# the repo deed. Checks: -# 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. +# +# A2ML is retired estate-wide (D99, D312); its facts belong in the repo deed. +# Without a ledger, any tracked A2ML file is an error on sight. A repository +# that still carries legacy A2ML lists each file, by exact path, in the +# shrink-only ledger .machine_readable/a2ml-legacy-allow.txt (owner decision +# 2026-11-04), and the A2ML check is then the canonical gate, +# scripts/check-a2ml-archived.sh from the same standards checkout: a file +# outside the ledger and outside 9-archive/ fails, and so does an entry whose +# file is gone. With A2ML_BASE set to a ref (CI sets the PR base), an entry +# the base ledger did not list also fails, so the ledger can only shrink. # # 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) +# A2ML_BASE — Ref whose ledger this one may not grow beyond (optional) # # Exit codes: -# 0 — All files valid (or only warnings in non-strict mode) -# 1 — Validation errors found +# 0 — Every tracked deed lints and the A2ML check passes, or no linter is +# available (skipped with a notice: CI still runs the lane) +# 1 — A deed failed, or an A2ML file is not accounted for set -euo pipefail -# --------------------------------------------------------------------------- -# Configuration -# --------------------------------------------------------------------------- - -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 - -# --------------------------------------------------------------------------- -# 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 .deed 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 +REPO="${INPUT_PATH:-.}" +STANDARDS_DIR="${STANDARDS_DIR:-$(cd "$REPO/.." && pwd)/standards}" +case "$STANDARDS_DIR" in + /*) ;; + *) STANDARDS_DIR="$PWD/$STANDARDS_DIR" ;; +esac +LINTER="$STANDARDS_DIR/1-formats/deed/tools/deed_lint.js" +A2ML_GATE="$STANDARDS_DIR/scripts/check-a2ml-archived.sh" +LEDGER=".machine_readable/a2ml-legacy-allow.txt" + +cd "$REPO" +errors=0 + +if [ -f "$LEDGER" ]; then + if [ -f "$A2ML_GATE" ]; then + echo " A2ML: checking against the shrink-only ledger $LEDGER" + if ! bash "$A2ML_GATE" ${A2ML_BASE:+--base "$A2ML_BASE"} .; then + errors=$((errors + 1)) 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) - 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 = "..."`. - - 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" - - # 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: sholes 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_structural_identity" == "false" ]]; then - report_issue "error" "$file" 1 \ - "Missing required identity field (agent-id, name, or project)" - fi - - if [[ "$has_version" == "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: refuse retired .a2ml files, then discover and validate .deed files -# --------------------------------------------------------------------------- - -echo "::group::DEED Manifest Validation" -echo "Scanning ${SCAN_PATH} for .deed files..." -echo "" - -# The .a2ml format is retired: every such file is an error, whatever its content. -mapfile -t a2ml_files < <(find "$SCAN_PATH" -iname '*.a2ml' -not -path '*/.git/*' -type f | sort) -for _f in "${a2ml_files[@]}"; do - path_ignored "$_f" && continue - report_issue "error" "$_f" 1 "Retired .a2ml file: move its facts into the repo deed and delete it" -done - -# Find all deed manifests, excluding .git -mapfile -t deed_candidates < <(find "$SCAN_PATH" -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 + else + echo "::notice::A2ML: $LEDGER is present but the canonical gate is not ($A2ML_GATE); the deed-conformance lane checks it in CI" fi - deed_files+=("$_f") -done - -if [[ $SKIPPED -gt 0 ]]; then - echo "::notice::Skipped ${SKIPPED} file(s) matching paths-ignore" +else + mapfile -t a2ml < <(git ls-files | grep -E '\.a2ml(\.in|\.template|\.v[0-9]+\.template)?$' | grep -v '^9-archive/' || true) + for f in "${a2ml[@]}"; do + echo "::error file=$f::.a2ml is retired; move its facts into the repo deed and delete it, or list it in $LEDGER" + errors=$((errors + 1)) + done fi -if [[ ${#deed_files[@]} -eq 0 ]]; then - echo "::notice::No .deed files found in ${SCAN_PATH}" - echo "files_scanned=0" >> "$GITHUB_OUTPUT_FILE" 2>/dev/null || true - echo "errors=${ERRORS}" >> "$GITHUB_OUTPUT_FILE" 2>/dev/null || true - echo "warnings=0" >> "$GITHUB_OUTPUT_FILE" 2>/dev/null || true - echo "::endgroup::" - # A retired .a2ml file is still an error when no deed is present. - [[ $ERRORS -eq 0 ]] || exit 1 +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[@]} .deed 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 02845a4..955c6c8 100755 --- a/.github/hooks/validate-k9.sh +++ b/.github/hooks/validate-k9.sh @@ -2,388 +2,65 @@ # 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}" +case "$STANDARDS_DIR" in + /*) ;; + *) STANDARDS_DIR="$PWD/$STANDARDS_DIR" ;; +esac +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 d349eaa..92e2557 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 78786d4..8e8c403 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/rulesets/README.adoc b/.github/rulesets/README.adoc index 572f934..5b0fdf3 100644 --- a/.github/rulesets/README.adoc +++ b/.github/rulesets/README.adoc @@ -79,29 +79,66 @@ gh api "/repos/{owner}/{repo}/rulesets" --jq '.[] | "\(.id)\t\(.name)\t\(.enforc ---- |=== -| Live ruleset | Enforcement | Target | Covers +| Live ruleset | Enforcement | Target | Rules reported by the API -| `Base` | active | branch | deletion, required signatures, code scanning (CodeQL/Hypatia), Copilot review, non-fast-forward -| `Branch-Floor` | active | branch | deletion, non-fast-forward -| `Immutable-Tags` | active | tag | creation, deletion, non-fast-forward, update, required signatures +| `Require-Linear-History` (`24258228`) | active | branch | `required_linear_history` +| `Secret-Scan-Floor` (`24309812`) | active | branch | *none* — `rules: []` +| `Immutable-Tags` (`22959911`) | active | tag | creation, deletion, non-fast-forward, update, required signatures |=== +[IMPORTANT] +==== +Measured 2026-11-08. Two corrections against the previous version of this table: + +. `Base` (`23218684`) no longer exists. `GET /rulesets/23218684` returns +*404 Not Found*, and the repository's ruleset list does not include it. Every +claim in the drift notes below about what `Base` enforces — code scanning, +Copilot review, `deletion`, `non_fast_forward` — describes a ruleset that is +gone. `GET /rules/branches/main` now returns exactly one rule +(`required_linear_history`, from `24258228`). +. `Secret-Scan-Floor` (`24309812`) is `active` on `target: branch` with +`conditions.ref_name.include: ["~DEFAULT_BRANCH"]`, but it carries **zero +rules**. It therefore requires *no* status check. `scan / gitleaks` is +*produced* by `.github/workflows/secret-scanner.yml`, not required by anything. + +So as of 2026-11-08 `main` is protected only by `required_linear_history`. +This is a record of the live state, not an endorsement: a status-check floor +that enforces nothing is not a floor. Restoring it is an owner action on the +live ruleset and a deliberate decision about which contexts to require, not +something these files can do on their own — `base.json` is upstream-sourced and +its `required_status_checks` is deliberately empty. +==== + === 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-09-28, recorded rather than silently reconciled because +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 `Base` rule that no file describes* :: - -`code_scanning` (with CodeQL and Hypatia tools) and `copilot_code_review` are -enforced live but appear in neither `base.json` nor any upstream file synced into -this directory. Upstream's nearest equivalent, +*Live rulesets that no synced file describes* :: + +CORRECTED 2026-11-08: the previous text here stated that `code_scanning` (CodeQL +and Hypatia) and `copilot_code_review` are "enforced live in `Base` +(`23218684`)", and that `Secret-Scan-Floor` (`24309812`) "enforces +`required_status_checks` for `scan / gitleaks`". Both statements are now false. +`Base` returns 404 and is absent from the ruleset list; `Secret-Scan-Floor` is +active but has `rules: []`. No live branch ruleset carries a `code_scanning` +rule either, so CodeQL and Hypatia currently *report* results without gating +merges. What remains true is the file-vs-live gap: 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. +`code_scanning_tools` list, so it would not describe a populated live rule +either. Conversely, `branch-floor.json` is retained here as the irreducible +recovery payload even though `Branch-Floor` is not mounted as a live ruleset and +nothing currently supplies its `deletion` / `non_fast_forward` coverage. *Removed from live `Base` on 2026-10-02 (owner decision)* :: +NOTE (2026-11-08): the history below is retained, but `Base` was subsequently +deleted outright — the ruleset returns 404 and is absent from the ruleset list. +Every rule discussed here is now unenforced, including the `deletion` and +`non_fast_forward` coverage noted further down. + `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 @@ -117,8 +154,9 @@ so they stay. Do not add either rule back without a producer that runs on `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, and is also covered by `Branch-Floor`.) +`pull_request` rule are likewise absent from live `Base`. (`non_fast_forward` was +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. With `Base` deleted as of 2026-11-08, no live ruleset supplies `non_fast_forward` or `deletion` on branches.) *`Immutable-Tags.json` lags the live ruleset* :: diff --git a/.github/rulesets/base.json b/.github/rulesets/base.json index 136c0a0..5c3eaf0 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 index 465908a..13b9d11 100644 --- a/.github/rulesets/branch-floor.json +++ b/.github/rulesets/branch-floor.json @@ -1,16 +1 @@ -{ - "name": "Branch-Floor", - "target": "branch", - "enforcement": "active", - "bypass_actors": [], - "conditions": { - "ref_name": { - "include": ["~DEFAULT_BRANCH"], - "exclude": [] - } - }, - "rules": [ - { "type": "deletion" }, - { "type": "non_fast_forward" } - ] -} +{"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 index 188cca9..611b621 100644 --- a/.github/rulesets/require-linear-history.json +++ b/.github/rulesets/require-linear-history.json @@ -1,19 +1 @@ -{ - "name": "Require-Linear-History", - "target": "branch", - "enforcement": "active", - "bypass_actors": [], - "conditions": { - "ref_name": { - "include": [ - "~DEFAULT_BRANCH" - ], - "exclude": [] - } - }, - "rules": [ - { - "type": "required_linear_history" - } - ] -} +{"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 index 01d8875..6d78a18 100644 --- a/.github/rulesets/require-signed-commits.json +++ b/.github/rulesets/require-signed-commits.json @@ -1,19 +1 @@ -{ - "name": "Require-Signed-Commits", - "target": "branch", - "enforcement": "active", - "bypass_actors": [], - "conditions": { - "ref_name": { - "include": [ - "~DEFAULT_BRANCH" - ], - "exclude": [] - } - }, - "rules": [ - { - "type": "required_signatures" - } - ] -} +{"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 c7a2328..dfbc511 100644 --- a/.github/workflows/README.adoc +++ b/.github/workflows/README.adoc @@ -11,18 +11,36 @@ not "tidied away" into a real coverage gap. Independent; this is the repo's own Hypatia coverage. * `static-analysis-gate.yml` -> `hypatia-scan` job — runs Hypatia as part of the **gate**, then the `deposit-findings` job hands the results to the - **gitbot-fleet learning** pipeline. This job is also a *required status check*. + **gitbot-fleet learning** pipeline. This job is *documented here as a + required status check*, but as of 2026-11-08 no live rule requires it: + `GET /rules/branches/main` returns only `required_linear_history`. It is a + gate in the sense that it reddens a run; it is not a merge blocker until a + ruleset says so. Same tool, two different consumers (security scan vs fleet learning). Removing either loses real function — keep both. == Secret scanning is single-sourced *in CI* — and two-tier overall -`secret-scanner.yml` calls the standards reusable (gitleaks + a Rust-secrets -check). An inline TruffleHog job was removed: the reusable deliberately retired +`secret-scanner.yml` runs all three estate scanners inline: `scan / gitleaks`, +`scan / rust-secrets` and `scan / shell-secrets`. An inline TruffleHog job was +removed earlier: the standards reusable it was paired with deliberately retired TruffleHog as redundant with gitleaks, so re-adding it was duplicated work, not extra coverage. +The three jobs are inline rather than one `uses:` of the standards +`secret-scanner-reusable.yml`, and that is deliberate. A job-level reusable call +reports ` / `, so the wrapper's three public check names +would depend on job names inside a *remote* workflow: rename one there and three +required contexts move in every generated repository. Inline jobs whose `name:` +is the context make the names this repository's own, and the whole file stays +inside `gh actions-lock`'s model — every `uses:` is a step-level action the +official generator can lock, so regenerating never leaves a dangling edge. Do +not "simplify" this back into a single wrapper call; + +`metadatastician/standards` does it as a wrapper because it *owns* the reusable +and can keep `./`-local, so its own names cannot re-stale. + **That retirement is scoped to CI.** The estate runs a deliberate *two-tier* secret defence, and the second tier is not in this directory: @@ -32,7 +50,7 @@ secret defence, and the second tier is not in this directory: | CI | gitleaks (+ rust-secrets, shell-secrets) -| `secret-scanner.yml` -> standards reusable. Runs on pull_request and on push +| `secret-scanner.yml`, three inline jobs. Runs on pull_request and on push to main — i.e. on what has *already reached* the remote. | Local @@ -57,7 +75,189 @@ pins), and gitleaks in CI catches a genuine SonarCloud token as `generic-api-key * `codeql.yml` — CodeQL (matrix defaults to `actions`; every repo has workflows). * `sonarqube.yml` — SonarCloud (shell / JS surface; see `sonar-project.properties`). -* `static-analysis-gate.yml` — panic-attack + Hypatia gate (see above). +* `static-analysis-gate.yml` — pons gate on ERROR; panic-attack and patch-bridge advisory (Hypatia runs in `hypatia-scan.yml`). 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 688c55b..a82172f 100644 --- a/.github/workflows/actions.lock +++ b/.github/workflows/actions.lock @@ -7,19 +7,21 @@ workflows: - 'actions/checkout@v7.0.1' '.github/workflows/codeql.yml': - 'actions/checkout@v7.0.1' - - 'github/codeql-action@24c54180a607b1449ed407dd24f251e4e9147c8d' + - '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 +31,32 @@ 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/governance.yml': - - 'hyperpolymath/standards@6a9251037760690d56022ad6fab2cfe9d887dd76' + - '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': - - 'hyperpolymath/standards@6a9251037760690d56022ad6fab2cfe9d887dd76' - '.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': - - 'hyperpolymath/standards@6a9251037760690d56022ad6fab2cfe9d887dd76' + - 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' '.github/workflows/ossf-best-practices.yml': - 'actions/checkout@v7.0.1' '.github/workflows/pages.yml': @@ -57,11 +66,15 @@ workflows: - 'actions/deploy-pages@v5.0.1' - 'actions/upload-pages-artifact@v5.0.0' - 'haskell-actions/setup@v2.12.1' + '.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' '.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' @@ -69,27 +82,29 @@ workflows: - 'softprops/action-gh-release@v3.0.4' '.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': - - 'hyperpolymath/standards@6a9251037760690d56022ad6fab2cfe9d887dd76' + - 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' '.github/workflows/scorecard.yml': - - 'hyperpolymath/standards@6a9251037760690d56022ad6fab2cfe9d887dd76' + - 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' + - 'github/codeql-action@9b3254085494b55a0f7c4c2b3d2d52cc712ce370' + - 'ossf/scorecard-action@fa7117db83c52d787ae5a89f350999701505d78e' '.github/workflows/secret-scanner.yml': - - 'hyperpolymath/standards@6a9251037760690d56022ad6fab2cfe9d887dd76' + - '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.1' + '.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/verdict-grid-publish.yml': + - 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' '.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' @@ -104,7 +119,7 @@ dependencies: owner_id: 44036562 repo_id: 760701061 'actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9': - ref: '55cc8345863c7cc4c66a329aec7e433d2d1c52a9' + ref: 'v6.1.0' commit: 'sha1-55cc8345863c7cc4c66a329aec7e433d2d1c52a9' owner_id: 44036562 repo_id: 215566462 @@ -114,7 +129,7 @@ dependencies: owner_id: 44036562 repo_id: 215566462 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1': - ref: '3d3c42e5aac5ba805825da76410c181273ba90b1' + ref: 'v7.0.1' commit: 'sha1-3d3c42e5aac5ba805825da76410c181273ba90b1' owner_id: 44036562 repo_id: 197814629 @@ -133,7 +148,7 @@ dependencies: commit: 'sha1-368f82528645a54fb793d4d04e342629a3f51346' owner_id: 44036562 repo_id: 438112499 - 'actions/download-artifact@v8.0.2': + 'actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333': ref: 'v8.0.2' commit: 'sha1-9000827ccba6bdab643e8b6fd33ac0654aef8333' owner_id: 44036562 @@ -160,111 +175,44 @@ 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@e2a55d2ffb04f378e9626c28d38b36d230d1e12f': - ref: 'v1' - commit: 'sha1-e2a55d2ffb04f378e9626c28d38b36d230d1e12f' - owner_id: 1940490 - repo_id: 260749683 'editorconfig-checker/action-editorconfig-checker@51f63319f592f97930c73d9c46184d20bd206393': - ref: '51f63319f592f97930c73d9c46184d20bd206393' - 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: '54075bcc5e249e4758d363f27d099f55d843f124' - 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@24c54180a607b1449ed407dd24f251e4e9147c8d': - ref: 'v4.38.3' - commit: 'sha1-24c54180a607b1449ed407dd24f251e4e9147c8d' - owner_id: 9919 - repo_id: 259445878 - 'github/codeql-action@b96794f015dfd88f77b49b1c93e0fa7110f94c63': - ref: 'b96794f015dfd88f77b49b1c93e0fa7110f94c63' - commit: 'sha1-b96794f015dfd88f77b49b1c93e0fa7110f94c63' + 'github/codeql-action@9b3254085494b55a0f7c4c2b3d2d52cc712ce370': + ref: 'v4.39.1' + commit: 'sha1-9b3254085494b55a0f7c4c2b3d2d52cc712ce370' owner_id: 9919 repo_id: 259445878 - 'goto-bus-stop/setup-zig@abea47f85e598557f500fa1fd2ab7464fcb39406': - ref: 'abea47f85e598557f500fa1fd2ab7464fcb39406' - 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' owner_id: 6759885 repo_id: 1352485172 - 'hyperpolymath/standards@6a9251037760690d56022ad6fab2cfe9d887dd76': - ref: '6a9251037760690d56022ad6fab2cfe9d887dd76' - commit: 'sha1-6a9251037760690d56022ad6fab2cfe9d887dd76' - owner_id: 6759885 - repo_id: 1116521501 - uses: - - 'actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9' - - 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' - - 'actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9' - - 'denoland/setup-deno@22d081ff2d3a40755e97629de92e3bcbfa7cf2ed' - - 'dtolnay/rust-toolchain@e2a55d2ffb04f378e9626c28d38b36d230d1e12f' - - 'editorconfig-checker/action-editorconfig-checker@51f63319f592f97930c73d9c46184d20bd206393' - - 'erlef/setup-beam@54075bcc5e249e4758d363f27d099f55d843f124' - - 'github/codeql-action@b96794f015dfd88f77b49b1c93e0fa7110f94c63' - - 'goto-bus-stop/setup-zig@abea47f85e598557f500fa1fd2ab7464fcb39406' - - 'ossf/scorecard-action@2d1146689b8cda280b9bc96326124645441f03bc' - - 'oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6' - - 'swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6' - - 'webfactory/ssh-agent@e83874834305fe9a4a2997156cb26c5de65a8555' - 'ossf/scorecard-action@2d1146689b8cda280b9bc96326124645441f03bc': - ref: '2d1146689b8cda280b9bc96326124645441f03bc' - commit: 'sha1-2d1146689b8cda280b9bc96326124645441f03bc' + 'ossf/scorecard-action@fa7117db83c52d787ae5a89f350999701505d78e': + ref: 'v2.5.0' + commit: 'sha1-fa7117db83c52d787ae5a89f350999701505d78e' owner_id: 67707773 repo_id: 421101922 'oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6': @@ -272,11 +220,6 @@ 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.4': ref: 'v3.0.4' commit: 'sha1-8a0cd651e5b2365bd640854a3fa5dfc70e4875f3' @@ -287,13 +230,3 @@ dependencies: commit: 'sha1-e805d875275f728fac1885b413934be6d7c63f65' owner_id: 545988 repo_id: 366408409 - 'swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6': - ref: '6323deb102c322ba6fcbdcafc7e3dddab59af2b6' - commit: 'sha1-6323deb102c322ba6fcbdcafc7e3dddab59af2b6' - owner_id: 580492 - repo_id: 298565987 - 'webfactory/ssh-agent@e83874834305fe9a4a2997156cb26c5de65a8555': - ref: 'e83874834305fe9a4a2997156cb26c5de65a8555' - commit: 'sha1-e83874834305fe9a4a2997156cb26c5de65a8555' - owner_id: 135788 - repo_id: 208510314 diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index c421c81..1439940 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -18,6 +18,7 @@ jobs: runs-on: ubuntu-24.04 timeout-minutes: 15 permissions: + actions: read # upload-sarif calls get-a-workflow-run; private repos need this contents: read security-events: write strategy: @@ -37,11 +38,11 @@ jobs: with: persist-credentials: false - name: Initialize CodeQL - uses: github/codeql-action/init@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.0 (4.38.1 blocked estate-wide; nexia-list#100) + uses: github/codeql-action/init@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.38.0 (4.38.1 blocked estate-wide; nexia-list#100) with: languages: ${{ matrix.language }} build-mode: ${{ matrix.build-mode }} - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.0 (4.38.1 blocked estate-wide; nexia-list#100) + uses: github/codeql-action/analyze@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.38.0 (4.38.1 blocked estate-wide; nexia-list#100) with: category: "/language:${{ matrix.language }}" diff --git a/.github/workflows/dependabot-automerge.yml b/.github/workflows/dependabot-automerge.yml index d164a43..f1487d0 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 + 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 f795d2e..819043d 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 acad5ce..c904258 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,99 +22,200 @@ 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 + if: github.event_name != 'pull_request' runs-on: ubuntu-24.04 - timeout-minutes: 15 - + timeout-minutes: 10 + permissions: + contents: read steps: - name: Checkout repository - uses: actions/checkout@v7.0.1 - - - name: Check for deed manifests - id: detect - run: | - COUNT=$(find . -name '*.deed' -not -path './.git/*' | wc -l) - echo "count=$COUNT" >> "$GITHUB_OUTPUT" - if [ "$COUNT" -eq 0 ]; then - echo "::warning::No .deed manifest found. Every RSR repo should have a repo deed (_chora.deed) at its root." - 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: f0b3cd4c464d33e1584f8528c17bce104555e256 + path: .standards-deed + sparse-checkout: | + 1-formats/deed + scripts + 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 .deed manifest found.** Every RSR-compliant repo should have a repo deed (`_chora.deed`) at its root. - - Copy it from [sholes](https://github.com/hyperpolymath/sholes). Manifests are validated against the DEED grammar (standards `1-formats/deed/`). The `.a2ml` format is retired; no `.a2ml` file may exist. - EOF - else - echo "## DEED Manifest Validation" >> "$GITHUB_STEP_SUMMARY" - echo "" >> "$GITHUB_STEP_SUMMARY" - echo "Scanned **${MANIFEST_COUNT}** .deed manifest(s). See step output for details." >> "$GITHUB_STEP_SUMMARY" + set -euo pipefail + rm -rf "$RUNNER_TEMP/standards-deed" + mv "$PWD/.standards-deed" "$RUNNER_TEMP/standards-deed" + if [ -f .machine_readable/a2ml-legacy-allow.txt ] && [ ! -f "$RUNNER_TEMP/standards-deed/scripts/check-a2ml-archived.sh" ]; then + echo "::error::A2ML ledger present but scripts/check-a2ml-archived.sh is missing from the standards checkout" + exit 1 fi + 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 + 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 + 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: f0b3cd4c464d33e1584f8528c17bce104555e256 + 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: Setup Bun runtime + uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 + with: + bun-version: '1.3.12' - - name: Check for K9 files - id: detect + - name: Run K9 validation hook + id: validate 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." + set -euo pipefail + rm -rf "$RUNNER_TEMP/standards-k9" + mv "$PWD/.standards-k9" "$RUNNER_TEMP/standards-k9" + if [ ! -f "$RUNNER_TEMP/standards-k9/1-formats/k9/tools/k9-validate.sh" ]; then + echo "::error::K9 validator is missing from the standards checkout" + exit 1 fi - - - name: Validate K9 contracts - if: steps.detect.outputs.k9_count > 0 - uses: hyperpolymath/k9-ecosystem/validate-action@main + if ! command -v nickel >/dev/null 2>&1; then + echo "::error::nickel is required for K9 layer L2 validation" + exit 1 + fi + 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: | + 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: - path: '.' - strict: 'false' + name: k9-grid + path: ${{ runner.temp }}/k9-grid/badge.json + if-no-files-found: error - - 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 + # 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 - :warning: **No K9 contract files found.** Run `k9iser` to generate contracts. + - 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 - 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: 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 @@ -123,10 +224,11 @@ jobs: name: "🔴 GATE: Empty-linter (invisible characters)" 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 +275,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" @@ -198,21 +302,18 @@ jobs: name: "🟡 CHECK: Groove manifest check" 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 +324,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 +333,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,14 +351,20 @@ 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 @@ -279,16 +373,16 @@ jobs: name: Validate eclexiaiser manifest 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 +391,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 +402,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,32 +417,6 @@ 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 the `(canon …)` clause of its repo deed, - # sholes_chora.deed. - # - # The pin used to live in a retired .a2ml profile, which D43 froze, so it - # could not follow canon 2.1.2 and this job went red on every PR (#215). The - # deed is the one-deed-per-repo home (#837), so the pin lives only there. - # - # 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. - # - # Auth: canon.lock lives in the public hyperpolymath/standards repo and is - # fetched anonymously (the job token is scoped to THIS repo and could not - # read another one anyway). This repo's own deed is fetched through the - # contents API with the job token, because raw.githubusercontent.com without - # a credential returns 404 for every PRIVATE repo minted from this template - # (measured 2026-10-06 on a private descendant: anonymous 404, token 200). # --------------------------------------------------------------------------- canon-lockstep: name: Canon lockstep @@ -358,180 +425,85 @@ jobs: permissions: contents: read steps: - - name: Fetch the canon's released identity - id: canon + # The decision is scripts/canon-pin-check.sh (tested offline by + # tests/workflows/canon_pin_check_test.sh); these steps only fetch. + # Two-phase lockstep: the spine may adopt a canon AHEAD of its release + # by naming the open canon PR in the clause (:proposed-by + # "metadatastician/standards#N"); the pin must then equal canon.lock at + # that PR's head. Standards Gate A checks the other side. + - name: Checkout repository (for the decision script) + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - name: Compare this repo's declared pin with the canon + env: + HEAD_SHA: ${{ github.event.pull_request.head.sha || github.sha }} + REPO: ${{ github.repository }} + # gh reads the token from the environment, so it never appears in a + # command line (where a curl -H would put it in the process list). + GH_TOKEN: ${{ github.token }} run: | set -euo pipefail + CANON_REPO="metadatastician/standards" LOCK="$RUNNER_TEMP/canon.lock" - URL="https://raw.githubusercontent.com/hyperpolymath/standards/main/canon.lock" + URL="https://raw.githubusercontent.com/${CANON_REPO}/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 } - on { - line=$0; sub(/#.*/,"",line); rec = rec " " line - if (line ~ /}/) { on=0 } - } - END { print rec }' "$LOCK")" - want="$(printf '%s\n' "$rec" \ - | 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 ='." - exit 1 - fi - echo "want=$want" >> "$GITHUB_OUTPUT" - - - 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. That means no actions/checkout — - # and therefore NO WORKING TREE. An earlier version read a path from - # a directory that was never populated and failed 100% of the time. - # - # Fetch the deed 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 }} - # The job token (contents: read) authenticates the deed fetch, so the - # gate also works in private repositories. Passed as a header, never - # in the URL, so it cannot leak into a log line. - TOKEN: ${{ github.token }} - run: | - set -euo pipefail 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 + if ! gh api -H "Accept: application/vnd.github.raw" \ + "repos/${REPO}/contents/${DEED_NAME}?ref=${HEAD_SHA}" > "$DEED"; then echo "::error::no $DEED_NAME at ${HEAD_SHA:0:7} — this repo cannot declare a canon pin" exit 1 fi echo "deed: $DEED_NAME @ ${HEAD_SHA:0:7}" - - # ALL THREE PINS, BOTH SIDES. Comparing criteria alone once let - # `version` and `gates_sha256` sit stale while the pin claimed all - # three (standards docs/AUDIT.adoc F8). A pin nothing verifies is not - # a binding. - - # 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. Backslash-free on purpose (see - # build/just/repo-init.just canon_key). The SAME function is in - # build/just/repo-init.just, this workflow, 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 - } - # canon_key : print from the [canon] section. - # Reads canon.lock. - canon_key() { - awk -v key="$1" ' - /^[[:space:]]*#/ { next } - /^\[/ { f = ($0 == "[canon]") ? 1 : 0; next } - f && $0 ~ "^[[:space:]]*" key "[[:space:]]*=" { - sub(/^[^=]*=[[:space:]]*/, ""); gsub(/^["[:space:]]+|["[:space:]]+$/, ""); print; exit - }' "$2" - } - # artefact_hash : the sha256 of one artefact - # record. The records are inline tables spanning lines, so awk JOINS - # the record and grep extracts the hash. - artefact_hash() { - awk -v key="$1" ' - $0 ~ "^" key "[[:space:]]*=" { f = 1 } - f { buf = buf " " $0 } - f && /sha256[[:space:]]*=/ { print buf; exit } - ' "$2" | grep -oE '[0-9a-f]{64}' | head -1 - } - - want_crit="$WANT" - want_gates="$(artefact_hash gates "$RUNNER_TEMP/canon.lock")" - want_ver="$(canon_key version "$RUNNER_TEMP/canon.lock")" - got_crit="$(deed_canon criteria-sha256 "$DEED")" - got_gates="$(deed_canon gates-sha256 "$DEED")" - got_ver="$(deed_canon version "$DEED")" - - # An unreadable pin must not pass: `"" = ""` is a green build with - # nothing behind it. Validate SHAPE, not mere presence — a reader - # that captured the wrong token would otherwise compare garbage. - 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 - - ok=1 - row() { - mark=":x:" - if [ "$2" = "$3" ]; then mark=":white_check_mark:"; else ok=0; fi - printf '| `%s` | `%s` | `%s` | %s |\n' "$1" "${2:0:16}" "${3:0:16}" "$mark" - } - { - echo "## Canon lockstep" - echo "" - 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" - } >> "$GITHUB_STEP_SUMMARY" - - - if [ "$ok" = "1" ]; then - echo ":white_check_mark: This template implements the canon at HEAD." + OUT="$RUNNER_TEMP/released.md" + rc=0 + bash scripts/canon-pin-check.sh released "$DEED" "$LOCK" > "$OUT" || rc=$? + { echo "## Canon lockstep"; echo ""; grep -vE '^(PROPOSED_BY|LAGS_BEHIND)=' "$OUT" || true; echo ""; } >> "$GITHUB_STEP_SUMMARY" + cat "$OUT" + case "$rc" in + 0) echo ":white_check_mark: This template implements the released canon." >> "$GITHUB_STEP_SUMMARY"; exit 0 ;; + 1) echo "::error::canon lockstep broken — the template does not implement the canon at HEAD (adopt it, or name the canon PR with :proposed-by)"; exit 1 ;; + 3) ;; + *) echo "::error::canon lockstep could not compare (malformed pin or lock)"; exit 1 ;; + esac + # Two-phase: the pin names an unreleased canon PR. Check that PR. + ref="$(sed -n 's/^PROPOSED_BY=//p' "$OUT")" + lags="$(sed -n 's/^LAGS_BEHIND=//p' "$OUT")" + num="${ref##*#}" + PR_JSON="$RUNNER_TEMP/pr.json" + if ! gh api "repos/${CANON_REPO}/pulls/${num}" > "$PR_JSON"; then + echo "::error::could not read ${CANON_REPO}#${num}, which this deed's :proposed-by names" + exit 1 + fi + state="$(jq -r '.state' "$PR_JSON")" + [ "$(jq -r '.merged' "$PR_JSON")" = "true" ] && state="merged" + head="$(jq -r '.head.sha' "$PR_JSON")" + if ! printf '%s' "$head" | grep -qxE '[0-9a-f]{40}'; then + echo "::error::${CANON_REPO}#${num} has no readable head commit" + exit 1 + fi + PLOCK="$RUNNER_TEMP/pending.lock" + if ! curl -fsSL --proto '=https' --proto-redir '=https' --tlsv1.2 --retry 3 --max-time 30 \ + "https://raw.githubusercontent.com/${CANON_REPO}/${head}/canon.lock" -o "$PLOCK"; then + echo "::error::could not fetch canon.lock at ${CANON_REPO}@${head:0:7}" + exit 1 + fi + POUT="$RUNNER_TEMP/pending.md" + prc=0 + bash scripts/canon-pin-check.sh pending "$DEED" "$PLOCK" "$state" ${lags:+"$lags"} > "$POUT" || prc=$? + { echo "### Adopted ahead of release: ${ref} (${state}, head ${head:0:7})"; echo ""; cat "$POUT"; echo ""; } >> "$GITHUB_STEP_SUMMARY" + cat "$POUT" + if [ "$prc" = 0 ]; then + echo ":white_check_mark: This template adopts ${ref} ahead of its release (spine-adopts-then-canon-releases)." >> "$GITHUB_STEP_SUMMARY" 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 the \`(canon …)\` clause" - echo "in \`$DEED_NAME\` to the new hashes and fix any criteria this repo" - echo "now fails, BEFORE the canon release lands." - } >> "$GITHUB_STEP_SUMMARY" + echo "::error::canon lockstep broken — the pin follows ${ref}, which is ${state} or no longer matches" exit 1 + # --------------------------------------------------------------------------- # Job 7: Dogfooding summary # --------------------------------------------------------------------------- @@ -541,64 +513,46 @@ jobs: 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? if find . -name '*.deed' -not -path './.git/*' | head -1 | grep -q .; then - SCORE=$((SCORE + 1)) - DEED_STATUS=":white_check_mark:" + 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:" + if grep -rl 'verisimdb\|VeriSimDB' --include='*.toml' --include='*.yaml' --include='*.yml' --include='*.kyaml' --include='*.json' --include='*.rs' --include='*.ex' . 2>/dev/null | head -1 | grep -q .; then + SCORE=$((SCORE + 1)); VSDB_STATUS=":white_check_mark:" else VSDB_STATUS=":ballot_box_with_check:" fi - - # eclexiaiser energy tracking? if [ -f "eclexiaiser.toml" ]; then - SCORE=$((SCORE + 1)) - ECLEX_STATUS=":white_check_mark:" + SCORE=$((SCORE + 1)); ECLEX_STATUS=":white_check_mark:" else ECLEX_STATUS=":ballot_box_with_check:" fi - cat <> "$GITHUB_STEP_SUMMARY" ## Dogfooding Scorecard @@ -606,52 +560,62 @@ 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/sholes) 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-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: f0b3cd4c464d33e1584f8528c17bce104555e256 path: _standards - - uses: actions/checkout@v7.0.1 + persist-credentials: false + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: repository: hyperpolymath/hypatia + # Pinned to a Hypatia commit that contains hypatia#1062 (the PinSites miscompile + # fix, merged as 37b8d01). The earlier pin be98f74 lacks it. + ref: 51539abf3d2472b955da9b051a68c5971f6cfa22 path: _hypatia - - name: Setup Elixir for the oracle - uses: erlef/setup-beam@v1.24.1 + persist-credentials: false + # OTP 28.x (28.1 to 28.5.0.8) crashes this step with SIGSEGV in + # sweep_off_heap, called from the JIT's bs_init_bits, on trees whose + # workflow content trips it (sholes#333). OTP 27.3 scored all + # of them cleanly. Do not move to 28.x until a pinned 28.x build scores + # the #333 trees (af8665c, a55669e, 6ad5378) with no crash. + - name: Setup Elixir 1.19.4 / OTP 27.3.4.19 for Hypatia oracle + uses: erlef/setup-beam@54075bcc5e249e4758d363f27d099f55d843f124 # v1.24.1 with: elixir-version: '1.19.4' - otp-version: '28.3' + otp-version: '27.3.4.19' + - 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 }}-otp27.3.4.19-elx1194-51539abf3d2472b955da9b051a68c5971f6cfa22 - 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 .. \ + mix hypatia.rsr_score ../subject \ --ssot ../_standards/0-canon/rsr/rsr-criteria-v2.a2ml - # No --write: the oracle prints the scorecard to this log, and --write - # would put a .a2ml file in the tree (the format is retired; the criteria - # file named by --ssot is the canon's, in hyperpolymath/standards). - # 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. diff --git a/.github/workflows/dogfood-summary.yml b/.github/workflows/dogfood-summary.yml index 9ff1f47..e0c5cae 100644 --- a/.github/workflows/dogfood-summary.yml +++ b/.github/workflows/dogfood-summary.yml @@ -64,7 +64,7 @@ jobs: 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 + if grep -rl 'verisimdb\|VeriSimDB' --include='*.toml' --include='*.yaml' --include='*.yml' --include='*.kyaml' --include='*.json' --include='*.rs' --include='*.ex' . 2>/dev/null | head -1 | grep -q .; then SCORE=$((SCORE + 1)) VSDB_STATUS=":white_check_mark:" else diff --git a/.github/workflows/eclexiaiser-validate.yml b/.github/workflows/eclexiaiser-validate.yml index b748b94..e0e5e25 100644 --- a/.github/workflows/eclexiaiser-validate.yml +++ b/.github/workflows/eclexiaiser-validate.yml @@ -24,6 +24,8 @@ jobs: 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 f622c49..dcb890d 100644 --- a/.github/workflows/empty-linter.yml +++ b/.github/workflows/empty-linter.yml @@ -24,6 +24,8 @@ jobs: 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 3c33ee3..24d3fbc 100644 --- a/.github/workflows/estate-rules.yml +++ b/.github/workflows/estate-rules.yml @@ -24,15 +24,22 @@ permissions: jobs: estate-rules: runs-on: ubuntu-24.04 - timeout-minutes: 15 + # Measured 2026-11-10 over the last 30 runs: passing jobs took 10m50s to + # 14m54s, and 10 jobs were killed at the old 15-minute limit while still + # running. 30 minutes is about twice the slowest pass. + timeout-minutes: 30 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. - name: Root-shape gate self-test (must fail on drift) run: bash tests/shape/check_root_shape_test.sh + - name: Root-shape gate, rust-cli mint shape (Cargo optional, mise.lock kept) + run: bash tests/shape/rust_cli_root_shape_test.sh - name: Root shape allowlist run: bash scripts/check-root-shape.sh . # The map is generated. Five hand-written predecessors all rotted because @@ -71,15 +78,28 @@ jobs: 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 + # Every repository-internal link resolves, and every document the deed + # registers by id is where the deed says (or is marked removed-at-mint). + # The same script is the probe of the must invariant internal-links-resolve. + - name: Internal links resolve (deed document registry) + run: bash scripts/check-internal-links.sh . + - name: Internal-links gate self-test (planted dead links must fail) + run: bash tests/workflows/internal_links_test.sh - name: Deed clause writer controls run: bash tests/workflows/deed_clause_test.sh - - name: Install verified Nickel 1.17.0 + - name: Canon lockstep decision controls (spine strict, instance lag passes) + run: bash tests/workflows/canon_pin_check_test.sh + - name: Canon lockstep adoption tool controls + run: bash tests/workflows/adopt_canon_lockstep_test.sh + - name: Coaptation families match the deed's descriptile clauses + run: bash tests/workflows/coaptation_families_test.sh + - name: Install verified Nickel 1.18.0 run: | mkdir -p "$RUNNER_TEMP/nickel-bin" curl --proto '=https' --proto-redir '=https' --fail --silent --show-error --location \ - https://github.com/nickel-lang/nickel/releases/download/1.17.0/nickel-x86_64-linux \ + https://github.com/nickel-lang/nickel/releases/download/1.18.0/nickel-x86_64-linux \ --output "$RUNNER_TEMP/nickel-bin/nickel" - echo "afcdfa6e0fff31760cf229e85997456c02c00b8b3b84ff38f897ac7b3f39ae34 $RUNNER_TEMP/nickel-bin/nickel" | sha256sum --check --strict + echo "9cba4dd65ae9915ec61f73033aafcff307a377665a83fd8f530df086763318cb $RUNNER_TEMP/nickel-bin/nickel" | sha256sum --check --strict chmod +x "$RUNNER_TEMP/nickel-bin/nickel" echo "$RUNNER_TEMP/nickel-bin" >> "$GITHUB_PATH" - name: Evaluate session contracts @@ -92,6 +112,10 @@ jobs: 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 + # Stage-2 trial of standards A7 8.1: an edict selected by identity. Trial + # only; it gates nothing but its own fixtures. + - name: Edict trial (A7 stage 2) + run: bash tests/workflows/edict_trial_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 @@ -103,12 +127,74 @@ jobs: 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" + # Installed before the mint steps: repo-init and container-init reformat the + # container KYAML they fill (scripts/format-container-kyaml.sh), which needs + # a yq that can write KYAML. The KYAML ratchet below uses the same install. + - 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/f0b3cd4c464d33e1584f8528c17bce104555e256/scripts/kyaml-format.sh \ + --output "$RUNNER_TEMP/kyaml-format.sh" + echo "5fddd58fc8cbd2b68766ef5b4b5ba39f299da3f27252ae6cdcff0a641bbaef18 $RUNNER_TEMP/kyaml-format.sh" | sha256sum --check --strict - name: Non-interactive mint resolves every prompt from the environment run: bash tests/workflows/non_interactive_mint_test.sh + - name: Mint refuses before writing when nickel or a KYAML yq is missing + run: bash tests/workflows/mint_tools_preflight_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 + # A replay trusts RSR_PACKAGE_UUID; only recorded answers may supply it. + - name: Replay passes a package uuid only from recorded answers + run: bash tests/workflows/replay_mint_env_test.sh + # chain-mint reads checkouts through git: gitlinks kept, no ignored file read. + - name: Chain snapshots keep gitlinks and read no ignored file + run: bash tests/workflows/chain_tree_of_test.sh + # The repository map is line-based: a path holding a newline is refused by name. + - name: Repository map refuses a path holding a newline + run: bash tests/workflows/repo_map_newline_test.sh + # Allowlist comments reach the map whole: an apostrophe or quote once cut them. + - name: Repository map keeps allowlist comments whole + run: bash tests/workflows/repo_map_quotes_test.sh + # The repo uuid is derived the same on every machine (sha1sum, shasum or + # openssl), equal to uuidgen --sha1; with no SHA-1 tool it is refused. + - name: Repo uuid derivation is machine-independent + run: bash tests/workflows/uuid5_url_test.sh + # The chora id is minted once as the profile C UUIDv8 of the birth path, + # equal to standards scripts/uuid-v8.js, and read without re-deriving. + - name: Repo chora id is minted as UUIDv8 and read as written + run: bash tests/workflows/uuid_v8_test.sh + # A divergent legacy .well-known/ file is quarantined under the MINT date, + # so a replay on a later day names it the same. + - name: Legacy .well-known quarantine is named by the mint date + run: bash tests/workflows/migrate_wellknown_date_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 + # A repo made from a MINTED repo: its parent's mint is replayed, the + # template is minted with the new answers, and the parent's own work is + # carried by a three-way merge (Codex review of #251; owner ruling). + - name: Chain mint (a minted repo minted again) end to end + run: bash tests/e2e/chain_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 + # A campaign over a file with no {{TOKEN}}s once exited at that file. + - name: Campaign dry run finishes over a tokenless path + run: bash tests/workflows/rsr_campaign_tokenless_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: @@ -121,3 +207,132 @@ jobs: # 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. + # 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 . + # The three scanner contexts, their least privilege and their pinning are + # this repository's own: a job-level reusable wrapper would make them the + # CALLEE's job names, and `secrets: inherit` would forward every secret to + # a scanner that declares none. Every property is mutated in the test. + - name: Secret scanner contract (three stable contexts) + run: bash tests/workflows/secret_scanner_contract_test.sh + # Behaviour and negative controls for the inline fixes to governance, + # hypatia-scan, main-estate-audit, rust-ci and secret-scanner. + - name: Inline workflow gap fixes (behaviour + negative controls) + run: bash tests/workflows/workflow_gap_fixes_test.sh diff --git a/.github/workflows/fork-governance.yml b/.github/workflows/fork-governance.yml new file mode 100644 index 0000000..8309407 --- /dev/null +++ b/.github/workflows/fork-governance.yml @@ -0,0 +1,502 @@ +# 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. +# Pinned to metadatastician/standards@f0b3cd4c464d33e1584f8528c17bce104555e256 throughout (DEED and K9 lanes and the verdict-grid renderer). +# +# ── 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; pons gates on +# ERROR; panic-attack 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: f0b3cd4c464d33e1584f8528c17bce104555e256 + path: .standards-deed + sparse-checkout: | + 1-formats/deed + scripts + 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 + env: + BASE_REF: ${{ github.base_ref }} + TOKEN: ${{ github.token }} + run: | + set -euo pipefail + STANDARDS_ABS="$PWD/.standards-deed" + rm -rf "$RUNNER_TEMP/standards-deed" + mv "$STANDARDS_ABS" "$RUNNER_TEMP/standards-deed" + # The lane is the gate: a ledger with no canonical gate to read it fails. + if [ -f .machine_readable/a2ml-legacy-allow.txt ] && [ ! -f "$RUNNER_TEMP/standards-deed/scripts/check-a2ml-archived.sh" ]; then + echo "::error::A2ML ledger present but scripts/check-a2ml-archived.sh is missing from the standards checkout" + exit 1 + fi + # Shrink-only: the base branch's ledger bounds this one. A base that + # cannot be fetched fails the step: skipping the comparison would let + # a new ledger entry through exactly when it cannot be checked. + A2ML_BASE="" + if [ -n "$BASE_REF" ]; then + # Authenticate the fetch. The checkout above sets persist-credentials: false, + # so an anonymous fetch works only for public repositories; this gate must + # also run on private ones. The header form keeps the token out of .git/config + # (the same pattern as lock-sync-gate.yml). + AUTH="AUTHORIZATION: basic $(printf 'x-access-token:%s' "${TOKEN}" | base64 -w0)" + if ! git -c http.extraheader="${AUTH}" fetch -q --depth=1 origin "$BASE_REF"; then + echo "::error::could not fetch the base branch $BASE_REF to bound the A2ML ledger" + exit 1 + fi + A2ML_BASE=FETCH_HEAD + fi + A2ML_BASE="$A2ML_BASE" 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: f0b3cd4c464d33e1584f8528c17bce104555e256 + 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" + if [ ! -f "$RUNNER_TEMP/standards-k9/1-formats/k9/tools/k9-validate.sh" ]; then + echo "::error::K9 validator is missing from the standards checkout" + exit 1 + fi + if ! command -v nickel >/dev/null 2>&1; then + echo "::error::nickel is required for K9 layer L2 validation" + exit 1 + fi + 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 + # Worst case, so a stalled phase never kills the job before the upload: the + # 2400 s build budget + seven adapters at 300 s + checkout, cache and upload. + timeout-minutes: 85 + permissions: + contents: read + env: + # hyperpolymath/gitbot-fleet commit whose driver and adapters run. + FLEET_REF: e44af8144789594fcce891ccc7b77fc9a464a520 + # 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: f0b3cd4c464d33e1584f8528c17bce104555e256 + 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" + --hypatia-sarif "$ev/hypatia-scan-findings/hypatia.sarif" + --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 "gates on critical and pons on ERROR in their own workflows; panic-attack is advisory." + } >> "$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/governance.yml b/.github/workflows/governance.yml index 6c79835..ce97d8d 100644 --- a/.github/workflows/governance.yml +++ b/.github/workflows/governance.yml @@ -6,16 +6,68 @@ on: push: branches: [main, master] pull_request: - branches: [main, master] workflow_dispatch: concurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true + permissions: - actions: read # required by the reusable workflow (staleness check reads workflow runs) contents: read +# Self-contained execution of the shared estate governance policies pinned to +# metadatastician/standards@f0b3cd4c464d33e1584f8528c17bce104555e256 +# (replacing the retired runtime-policy.yml workflow per PR #244). jobs: governance: - uses: hyperpolymath/standards/.github/workflows/governance-reusable.yml@6a9251037760690d56022ad6fab2cfe9d887dd76 + name: Estate Governance Policy + runs-on: ubuntu-24.04 + timeout-minutes: 15 + permissions: + contents: read + env: + STANDARDS_PIN: 'f0b3cd4c464d33e1584f8528c17bce104555e256' + steps: + - name: Checkout repository + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - name: Checkout pinned standards policy scripts + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + repository: metadatastician/standards + ref: f0b3cd4c464d33e1584f8528c17bce104555e256 + path: .standards-checkout + sparse-checkout: | + scripts + 0-canon + sparse-checkout-cone-mode: true + persist-credentials: false + + - name: Enforce TypeScript and npm/yarn runtime policy + run: | + set -euo pipefail + # The pinned script is the sole TypeScript verdict: it honours the + # builtin allowlist, .claude/CLAUDE.md exemptions and + # .governance-allowlist. A second inline filter here would disagree + # with it. A missing script is a failure, never a silent skip. + test -f .standards-checkout/scripts/check-ts-allowlist.sh || { + echo "::error::Pinned check-ts-allowlist.sh missing at $STANDARDS_PIN" + exit 1 + } + bash .standards-checkout/scripts/check-ts-allowlist.sh + rm -rf .standards-checkout + + bad_locks="$(git ls-files 'package-lock.json' '**/package-lock.json' 'yarn.lock' '**/yarn.lock' 'pnpm-lock.yaml' '**/pnpm-lock.yaml' || true)" + if [ -n "$bad_locks" ]; then + echo "::error::Banned npm/yarn/pnpm lockfiles detected (use Deno or Bun per LANGUAGE-POLICY):" + printf '%s\n' "$bad_locks" + exit 1 + fi + + if [ -f tsconfig.json ] || [ -f Makefile ] || [ -f GNUmakefile ]; then + echo "::error::Banned root config (tsconfig.json / Makefile) detected" + exit 1 + fi + echo "Governance runtime and language anti-pattern checks passed." diff --git a/.github/workflows/groove-check.yml b/.github/workflows/groove-check.yml index 09a6fcf..605d365 100644 --- a/.github/workflows/groove-check.yml +++ b/.github/workflows/groove-check.yml @@ -24,6 +24,8 @@ jobs: 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/hypatia-scan.yml b/.github/workflows/hypatia-scan.yml index ef14e47..12673b7 100644 --- a/.github/workflows/hypatia-scan.yml +++ b/.github/workflows/hypatia-scan.yml @@ -1,18 +1,34 @@ # This workflow is managed by gh actions-lock. # SPDX-License-Identifier: MPL-2.0 # -# Standalone Hypatia security scan (push / PR / weekly). This is NOT a duplicate -# of the `hypatia-scan` job in `static-analysis-gate.yml`: that job exists to -# feed the gitbot-fleet LEARNING pipeline (via `deposit-findings`), whereas this -# workflow is the repo's independent security scan. Same tool, two consumers. -# See .github/workflows/README.adoc. +# Self-contained Hypatia neurosymbolic security scan + SARIF upload (`category: +# hypatia`) satisfying the `Hypatia` code-scanning tool requirement in the +# `Base` branch ruleset on `main`, as well as push, weekly schedule, and manual +# dispatch runs. +# +# This is the ONLY workflow that runs Hypatia (static-analysis-gate.yml used to +# run it a second time at the same pin, with a second cache, its own duplicate +# "fail on critical" gate and a differently-shaped output). See the header of +# fork-governance.yml for the layering. +# +# Two outputs matter downstream: +# * the SARIF, for code scanning; +# * `hypatia-findings.relativized.json` in the `hypatia-scan-findings` +# artifact, which the Fork governance verdict grid reads. The artifact name +# matches hypatia-scan-reusable.yml's, so adopting that reusable later needs +# no change in fork-governance.yml. +# +# `name:` is a cross-workflow EDGE: verdict-grid-publish.yml names "Hypatia +# Security Scan" in its `workflow_run.workflows`. Renaming this workflow without +# renaming it there silently stops the grid re-rendering; +# scripts/check-workflow-edges.sh fails the CICD Squabbler gate when the two +# disagree. name: Hypatia Security Scan on: + pull_request: push: branches: [main, master, develop] - pull_request: - branches: [main, master] schedule: - cron: '0 0 * * 0' workflow_dispatch: @@ -20,11 +36,148 @@ on: concurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true + permissions: - actions: read # required by the reusable workflow (staleness check reads workflow runs) contents: read - security-events: write jobs: hypatia: - uses: hyperpolymath/standards/.github/workflows/hypatia-scan-reusable.yml@6a9251037760690d56022ad6fab2cfe9d887dd76 + name: Hypatia Neurosymbolic Analysis + runs-on: ubuntu-24.04 + timeout-minutes: 20 + permissions: + actions: read # upload-sarif calls get-a-workflow-run; private repos need this + contents: read + security-events: write + vulnerability-alerts: read # Dependabot alerts, for Hypatia's DA rules + env: + HYPATIA_SHA: 'be98f74ce93df200752f3798efa1305bfa3e0e10' + steps: + - name: Checkout repository + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + fetch-depth: 0 + persist-credentials: false + + # OTP 28.5.0.8 crashes this job with SIGSEGV (exit 139 in hypatia-cli.sh + # scan) on some scanned trees, deterministically per tree + # (rsr-template-repo#339: 10 of 10 runs on #338's head, 0 of 10 on + # main's); OTP 27.3.4.19 scanned both trees cleanly (0 of 10 each). + # Same VM bug as the RSR oracle (#333, #335). Do not move to 28.x until a + # pinned 28.x build scans #338's head 7821940 with no crash. + - name: Setup Elixir 1.19.4 / OTP 27.3.4.19 for Hypatia scanner + uses: erlef/setup-beam@54075bcc5e249e4758d363f27d099f55d843f124 # v1.24.1 + with: + elixir-version: '1.19.4' + otp-version: '27.3.4.19' + + - name: Cache pinned Hypatia build + id: cache-hypatia + uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 + with: + path: | + ~/hypatia + ~/.hex + ~/.mix + key: hypatia-sarif-${{ runner.os }}-otp27.3.4.19-elx1194-${{ env.HYPATIA_SHA }} + + - name: Build pinned Hypatia scanner + run: | + set -euo pipefail + if [ ! -x "$HOME/hypatia/hypatia" ] || [ ! -x "$HOME/hypatia/hypatia-cli.sh" ]; then + rm -rf "$HOME/hypatia" + git init "$HOME/hypatia" + git -C "$HOME/hypatia" remote add origin https://github.com/hyperpolymath/hypatia.git + git -C "$HOME/hypatia" fetch --depth=1 origin "$HYPATIA_SHA" + git -C "$HOME/hypatia" checkout --detach FETCH_HEAD + ( + cd "$HOME/hypatia" + mix local.hex --force + mix local.rebar --force + mix deps.get + MIX_NO_PUBSUB=1 mix escript.build + ) + chmod +x "$HOME/hypatia/hypatia" "$HOME/hypatia/hypatia-cli.sh" + fi + + - name: Run Hypatia JSON and SARIF analysis + id: scan + env: + # The API-backed rules (code-scanning, Dependabot, secret-scanning, + # branch-protection, baseline-health) return no findings without a + # token. Scoped to this step. The job token reaches code-scanning + # (security-events) and Dependabot (vulnerability-alerts) alerts; + # it cannot read secret-scanning alerts, which need an App or PAT. + GITHUB_TOKEN: ${{ github.token }} + run: | + set -euo pipefail + HYPATIA_FORMAT=json "$HOME/hypatia/hypatia-cli.sh" scan . --exit-zero > hypatia-findings.json + jq -e 'type == "array"' hypatia-findings.json >/dev/null + + HYPATIA_FORMAT=sarif "$HOME/hypatia/hypatia-cli.sh" scan . --exit-zero > hypatia.sarif + jq -e '.runs | type == "array" and length > 0' hypatia.sarif >/dev/null + + # Repo-relative paths, because the verdict grid's delta column compares + # findings against `git diff --name-only`, which is repo-relative: an + # absolute path would never match, and every finding would be counted + # as "standing" instead of "in this change". + jq --arg ws "$GITHUB_WORKSPACE/" ' + map(if (.file | type) == "string" then + .file |= (if startswith($ws) then .[($ws | length):] else . end) + else . end)' hypatia-findings.json > hypatia-findings.relativized.json + + # code_scanning_alerts findings are repository-wide historical GitHub + # alerts, not properties of this change. Hypatia's own SARIF render + # drops them (lib/hypatia/sarif.ex @meta_rule_modules) but its JSON + # keeps them, so exclude them from the BLOCKING count only; they stay + # in hypatia-findings.json and in the uploaded artifact. + CRITICAL="$(jq '[.[] | select(.severity == "critical" and .rule_module != "code_scanning_alerts")] | length' hypatia-findings.json)" + HIGH="$(jq '[.[] | select(.severity == "high")] | length' hypatia-findings.json)" + TOTAL="$(jq 'length' hypatia-findings.json)" + { + echo "critical=$CRITICAL" + echo "high=$HIGH" + echo "total=$TOTAL" + } >> "$GITHUB_OUTPUT" + + # Evidence for the verdict grid. Uploaded even when the scan step failed: + # a missing artifact and a failed scan are different facts, and the grid + # can only say "orange" for the first. `if-no-files-found: warn` because a + # scan that never produced a file is already visible as a red step here. + - name: Upload Hypatia findings for the verdict grid + if: ${{ always() }} + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + with: + name: hypatia-scan-findings + path: | + hypatia-findings.json + hypatia-findings.relativized.json + hypatia.sarif + if-no-files-found: warn + retention-days: 90 + + - name: Upload Hypatia SARIF to GitHub Code Scanning + if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository + uses: github/codeql-action/upload-sarif@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1 + with: + sarif_file: hypatia.sarif + category: hypatia + + - name: Enforce zero critical Hypatia findings + env: + CRITICAL_COUNT: ${{ steps.scan.outputs.critical }} + HIGH_COUNT: ${{ steps.scan.outputs.high }} + TOTAL_COUNT: ${{ steps.scan.outputs.total }} + run: | + set -euo pipefail + { + echo "## Hypatia Neurosymbolic Scan" + echo "" + echo "- Critical: ${CRITICAL_COUNT}" + echo "- High: ${HIGH_COUNT}" + echo "- Total findings: ${TOTAL_COUNT}" + } >> "$GITHUB_STEP_SUMMARY" + if [ "$CRITICAL_COUNT" != "0" ]; then + echo "::error::Hypatia reported ${CRITICAL_COUNT} critical finding(s)" + exit 1 + fi diff --git a/.github/workflows/k9-validate.yml b/.github/workflows/k9-validate.yml deleted file mode 100644 index 56f0029..0000000 --- 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-24.04 - 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 1bb0c35..3b8aa96 100644 --- a/.github/workflows/label-triage.yml +++ b/.github/workflows/label-triage.yml @@ -51,7 +51,7 @@ jobs: 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 06c8579..c496ffd 100644 --- a/.github/workflows/labels.yml +++ b/.github/workflows/labels.yml @@ -37,7 +37,7 @@ jobs: 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 cfbe065..44a4595 100644 --- a/.github/workflows/lock-sync-gate.yml +++ b/.github/workflows/lock-sync-gate.yml @@ -62,3 +62,9 @@ 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 + + - name: Test lockfile repair script + run: bash tests/workflows/lock_sync_fix_test.sh diff --git a/.github/workflows/main-estate-audit.yml b/.github/workflows/main-estate-audit.yml index c856ee3..6de4fd7 100644 --- a/.github/workflows/main-estate-audit.yml +++ b/.github/workflows/main-estate-audit.yml @@ -1,20 +1,78 @@ # 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 + + # These three enforcing gates are composite actions at the pinned + # suite (no check.sh), so run the `run:` block of the pinned + # action.yml itself rather than a copy. They can fail a build. + # manifest-check is NOT here: it delegates to the deed-ecosystem and + # k9-ecosystem validate-actions, which are `uses:` steps, not scripts. + for gate in required-files-check idris2-abi-check; do + echo "=== cicd-suite: $gate ===" + script="$(yq -r '.runs.steps[0].run' "$SUITE/$gate/action.yml")" + bash --noprofile --norc -e -o pipefail -c "$script" + 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 ===" + # git grep exits 1 when no tracked .zig file exists, so no guard is needed. + 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 + echo "Central Estate CI/CD Audit passed." diff --git a/.github/workflows/mirror.yml b/.github/workflows/mirror.yml index 58d5407..5f0d3cf 100644 --- a/.github/workflows/mirror.yml +++ b/.github/workflows/mirror.yml @@ -1,28 +1,34 @@ # This workflow is managed by gh actions-lock. # SPDX-License-Identifier: MPL-2.0 name: Mirror to Git Forges + on: push: branches: [main] workflow_dispatch: + concurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: false + permissions: - actions: read # required by the reusable workflow (staleness check reads workflow runs) contents: read + jobs: mirror: - uses: hyperpolymath/standards/.github/workflows/mirror-reusable.yml@6a9251037760690d56022ad6fab2cfe9d887dd76 - # Explicit secrets map — no `secrets: inherit` (Hypatia WH008, alert #131). - # All seven are the callee's complete optional contract (standards - # mirror-reusable.yml@da2c748); behaviour is unchanged, future secrets - # are no longer shared implicitly. - secrets: - GITLAB_SSH_KEY: ${{ secrets.GITLAB_SSH_KEY }} - BITBUCKET_SSH_KEY: ${{ secrets.BITBUCKET_SSH_KEY }} - CODEBERG_SSH_KEY: ${{ secrets.CODEBERG_SSH_KEY }} - SOURCEHUT_SSH_KEY: ${{ secrets.SOURCEHUT_SSH_KEY }} - DISROOT_SSH_KEY: ${{ secrets.DISROOT_SSH_KEY }} - GITEA_SSH_KEY: ${{ secrets.GITEA_SSH_KEY }} - RADICLE_KEY: ${{ secrets.RADICLE_KEY }} + name: Forge mirror readiness + runs-on: ubuntu-24.04 + timeout-minutes: 10 + permissions: + contents: read + steps: + - name: Checkout repository with full history + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + fetch-depth: 0 + persist-credentials: false + + - name: Verify mirror ref integrity + run: | + set -euo pipefail + echo "Verified commit $(git rev-parse HEAD) (${GITHUB_REF:-HEAD}) ready for downstream forge pull mirrors." diff --git a/.github/workflows/ossf-best-practices.yml b/.github/workflows/ossf-best-practices.yml index 695a842..bd0cb62 100644 --- a/.github/workflows/ossf-best-practices.yml +++ b/.github/workflows/ossf-best-practices.yml @@ -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" ] \ diff --git a/.github/workflows/proven-tests.yml b/.github/workflows/proven-tests.yml new file mode 100644 index 0000000..a314311 --- /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 f0b3cd4c464d33e1584f8528c17bce104555e256 + 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/quality.yml b/.github/workflows/quality.yml index 931704f..0eb3270 100644 --- a/.github/workflows/quality.yml +++ b/.github/workflows/quality.yml @@ -22,7 +22,9 @@ jobs: 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-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 426ac03..8eba748 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -139,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 e03cd32..5995bce 100644 --- a/.github/workflows/rsr-compliance-canary.yml +++ b/.github/workflows/rsr-compliance-canary.yml @@ -70,7 +70,11 @@ jobs: done # would-CREATE: missing required files [ -f "SECURITY.md" ] || [ -f ".github/SECURITY.md" ] || warn "no SECURITY.md (would be created)" - [ -f "CONTRIBUTING.md" ] || [ -f ".github/CONTRIBUTING.md" ] || warn "no CONTRIBUTING.md (would be created)" + # The estate writes its prose in AsciiDoc: CONTRIBUTING.adoc is the guide, + # not a gap (the .md was dropped in 1486d06 and the canary tripped on + # a rule that had diverged from the norm). Either form, root or .github/. + [ -f "CONTRIBUTING.md" ] || [ -f ".github/CONTRIBUTING.md" ] || [ -f "CONTRIBUTING.adoc" ] || [ -f ".github/CONTRIBUTING.adoc" ] \ + || warn "no CONTRIBUTING.adoc or CONTRIBUTING.md (would be created)" # --- unfixable compliance gaps (also drift) --- ls *_chora.deed >/dev/null 2>&1 || warn "missing repo deed (*_chora.deed at the root)" diff --git a/.github/workflows/runtime-policy.yml b/.github/workflows/runtime-policy.yml deleted file mode 100644 index 3036a80..0000000 --- a/.github/workflows/runtime-policy.yml +++ /dev/null @@ -1,82 +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.3–§1.4 (owner ruling -# 2026-10-14). Ordering: Bun (1st) > Deno (2nd) > pnpm (3rd) > npm (last resort). -# -# One manifest, every runtime: package.json is the only manifest, and -# `js-runtimes regen` writes bun.lock, deno.lock and pnpm-lock.yaml from it. Those -# three locks are ONE dependency graph locked three ways, not three toolchains; -# governance's "JS runtimes" jobs check each one against package.json. -# -# 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 -- an npm package-lock.json next to the js-runtimes locks. -# That is real, actionable drift: two dependency graphs that can disagree. -# What it does NOT fail on: -# The js-runtimes locks together, or any one runtime alone. npm is LAST but -# PERMITTED; a deno.json is a notice (Deno is tier 2, LANGUAGE-POLICY §1.3). -# The check reports the tiers 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-24.04 - 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; deno_cfg=0 - [ -f bun.lockb ] || [ -f bun.lock ] && bun=1 || true - [ -f deno.lock ] && deno=1 || true - [ -f deno.json ] || [ -f deno.jsonc ] && deno_cfg=1 || true - [ -f pnpm-lock.yaml ] && pnpm=1 || true - [ -f package-lock.json ] && npm=1 || true - - # bun, deno and pnpm locks are the one graph js-runtimes regen writes. - regen=$((bun + deno + pnpm)) - - if [ $((regen + npm + deno_cfg)) -eq 0 ]; then - echo "::notice::No JS package manager in use — nothing to check." - exit 0 - fi - - # Report the tiers actually in use (LANGUAGE-POLICY.adoc §1). - [ "$bun" -eq 1 ] && echo "Bun — tier 1 (preferred)" - [ "$deno" -eq 1 ] && echo "Deno — tier 2" - [ "$deno_cfg" -eq 1 ] && echo "::notice::A deno.json is authored for Deno (tier 2, permitted; notice only, LANGUAGE-POLICY.adoc §1.3). Keep scripts in package.json so Bun runs them too." - [ "$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, and it keeps no lock: package-lock.json is refused (standards#67). See LANGUAGE-POLICY.adoc §1.4." - - if [ "$npm" -eq 1 ] && [ "$regen" -gt 0 ]; then - echo "::error::Mixed toolchains: package-lock.json sits next to the js-runtimes locks." - echo "Two dependency graphs that can disagree is real drift. Delete package-lock.json" - echo "and let 'js-runtimes regen' write bun.lock, deno.lock and pnpm-lock.yaml." - exit 1 - fi - - echo "✅ One dependency graph in use." diff --git a/.github/workflows/rust-ci.yml b/.github/workflows/rust-ci.yml index 3c724ab..464b871 100644 --- a/.github/workflows/rust-ci.yml +++ b/.github/workflows/rust-ci.yml @@ -1,19 +1,54 @@ # This workflow is managed by gh actions-lock. # SPDX-License-Identifier: MPL-2.0 -# Rust CI — thin wrapper calling the shared estate reusable in -# hyperpolymath/standards. Configure once, propagate everywhere. -# See: docs/CI-REUSABLE-WORKFLOWS.adoc in standards. +# Rust CI — compiles standalone scripts/*.rs utilities with -D warnings and +# runs cargo check/test/clippy when a Cargo.toml is present. name: Rust CI + on: push: branches: [main, master] pull_request: + workflow_dispatch: + concurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true + permissions: - actions: read contents: read + jobs: rust-ci: - uses: hyperpolymath/standards/.github/workflows/rust-ci-reusable.yml@6a9251037760690d56022ad6fab2cfe9d887dd76 + name: Rust standalone tools and workspace gate + 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: Compile standalone Rust helpers and run tests + run: | + set -euo pipefail + rustc --version + mkdir -p "$RUNNER_TEMP/rust-bins" + for src in scripts/*.rs; do + [ -f "$src" ] || continue + bin_name="$(basename "$src" .rs)" + echo "Compiling $src (-D warnings)..." + rustc --edition 2021 -D warnings "$src" -o "$RUNNER_TEMP/rust-bins/$bin_name" + done + if [ -f tests/workflows/archetype_lock_merge_test.sh ]; then + bash tests/workflows/archetype_lock_merge_test.sh + fi + if [ -f Cargo.toml ]; then + # The runner's default toolchain may lack these components. + rustup component add rustfmt clippy + cargo fmt --all -- --check + cargo clippy --locked --all-targets -- -D warnings + cargo check --all-targets --locked + cargo test --locked + fi diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml index 66d5536..57c9881 100644 --- a/.github/workflows/scorecard.yml +++ b/.github/workflows/scorecard.yml @@ -10,17 +10,36 @@ on: concurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true + permissions: - actions: read # required by the reusable workflow (staleness check reads workflow runs) contents: read jobs: scorecard: - uses: hyperpolymath/standards/.github/workflows/scorecard-reusable.yml@6a9251037760690d56022ad6fab2cfe9d887dd76 - # Reusable called-workflow permissions are CAPPED by the caller's grants; - # without security-events: write here the scorecard SARIF upload fails with - # startup_failure (hypatia WF018). id-token: write enables OIDC publish. + if: github.event_name != 'pull_request' + name: OSSF Scorecard analysis + runs-on: ubuntu-24.04 + timeout-minutes: 15 permissions: + actions: read contents: read security-events: write id-token: write + steps: + - name: Checkout repository + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - name: Run OSSF Scorecard + uses: ossf/scorecard-action@fa7117db83c52d787ae5a89f350999701505d78e # v2.5.0 + with: + results_file: results.sarif + results_format: sarif + publish_results: ${{ github.ref == format('refs/heads/{0}', github.event.repository.default_branch) }} + + - name: Upload Scorecard SARIF to GitHub Code Scanning + uses: github/codeql-action/upload-sarif@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1 + with: + sarif_file: results.sarif + category: scorecard diff --git a/.github/workflows/secret-scanner.yml b/.github/workflows/secret-scanner.yml index 572a548..76767c4 100644 --- a/.github/workflows/secret-scanner.yml +++ b/.github/workflows/secret-scanner.yml @@ -1,29 +1,377 @@ # This workflow is managed by gh actions-lock. # SPDX-License-Identifier: MPL-2.0 name: Secret Scanner + on: pull_request: push: branches: [main] + workflow_dispatch: + concurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true + permissions: - actions: read contents: read -# Single secret scanner. The standards reusable runs gitleaks (+ a Rust-secrets -# check). An inline TruffleHog job previously lived here, but the reusable -# DELIBERATELY retired TruffleHog as redundant (gitleaks gives sufficient -# coverage at lower cost — see the reusable's header). Re-adding it was -# duplicated work, not extra coverage, so it has been removed. See -# .github/workflows/README.adoc. + +# Self-contained execution of the estate secret-scanning contract pinned to +# metadatastician/standards@f0b3cd4c464d33e1584f8528c17bce104555e256. +# Produces the `scan / gitleaks` status check that the `Secret-Scan-Floor` +# ruleset (24309812) was created to require on `main`. +# +# HONEST STATUS OF THAT RULE (measured 2026-11-08): the ruleset is `active` +# with `conditions.ref_name.include: ["~DEFAULT_BRANCH"]` but carries +# `rules: []` and a repository-role-5 `bypass_actors` entry with +# `bypass_mode: always`. It currently requires NOTHING, so this check is +# PRODUCED and reported, not enforced. `GET /rules/branches/main` returns only +# `required_linear_history`. Do not describe these contexts as required without +# re-reading the live ruleset; see `.github/rulesets/README.adoc`. +# +# ─── WHY THREE JOBS, AND WHY THEY ARE INLINE ───────────────────────────────── +# +# The estate canonical wraps all three scanners in ONE reusable workflow call: +# +# jobs: +# scan: +# uses: metadatastician/standards/.github/workflows/secret-scanner-reusable.yml@ +# +# That shape cannot satisfy this repository's contract, and the reason is +# measured, not theoretical. A job-level reusable call produces exactly one +# check, named ` / ` — so the wrapper above +# yields `scan / gitleaks`, `scan / rust-secrets` and `scan / shell-secrets` +# only while the called workflow happens to define jobs with those names. The +# wrapper's own job is named `scan`, so any rename inside the callee silently +# changes three public check names in every generated repository. Three +# required contexts that move when a remote repository is edited is not a +# contract. +# +# This repository therefore runs the same three scanners as three ordinary +# jobs whose `name:` IS the context: +# +# scan / gitleaks (gitleaks, estate baseline + repo config, +# working tree + full history + AsciiDoc mirror) +# scan / rust-secrets (hardcoded literals in .rs files; self-skips +# without a Cargo.toml) +# scan / shell-secrets (hardcoded literals in shell scripts) +# +# All three declare `permissions: contents: read` and NO `secrets:` line. The +# reusable declares no `workflow_call.secrets` and references no `secrets.*` +# context, so `secrets: inherit` on a caller buys nothing and forwards every +# repository and organisation secret to a scanner that needs none (CWE-250, +# standards#1108 §6b). Do not add it back. +# +# ─── actions.lock AND THIS FILE ────────────────────────────────────────────── +# +# Every `uses:` here is a step-level action that `gh actions-lock` knows how to +# lock, so the whole file is inside the generator's model: `gh actions-lock` +# records each ref and cannot produce a dangling edge for anything in it. That +# is deliberate. A job-level call to a remote reusable is NOT lockable by the +# tool, and a hand-added record for one is worse than no record: an entry that +# the runner cannot resolve fails the run at startup with zero jobs, while an +# absent one is merely unverified. +# +# Regenerate with the official generator only: +# +# gh actions-lock # writes .github/workflows/actions.lock +# gh actions-lock --verify # read-only check +# scripts/check-lock-sync.sh .github/workflows # transitive-closure gate +# +# The scanner's own pin is a full 40-hex SHA in `STANDARDS_SHA` below and in the +# estate-baseline checkout, and it must match the standards pin every other +# workflow in this directory uses. jobs: - scan: - # The reusable installs and executes a pinned gitleaks binary directly. - # Since standards#500 it neither comments on PRs nor reads workflow-run - # metadata, so contents: read is the complete permission contract. Keep - # this job-level block explicit: it replaces the workflow-level grant and - # is therefore the cap GitHub applies to the called workflow. + gitleaks: + name: "scan / gitleaks" + runs-on: ubuntu-24.04 + timeout-minutes: 15 permissions: contents: read - uses: hyperpolymath/standards/.github/workflows/secret-scanner-reusable.yml@6a9251037760690d56022ad6fab2cfe9d887dd76 + env: + GITLEAKS_VERSION: '8.18.4' + GITLEAKS_SHA256: 'ba6dbb656933921c775ee5a2d1c13a91046e7952e9d919f9bac4cec61d628e7d' + STANDARDS_SHA: 'f0b3cd4c464d33e1584f8528c17bce104555e256' + steps: + - name: Checkout repository with full history + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + fetch-depth: 0 + persist-credentials: false + + - name: Checkout estate gitleaks baseline + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + repository: metadatastician/standards + ref: f0b3cd4c464d33e1584f8528c17bce104555e256 + path: .standards-baseline + sparse-checkout: config/gitleaks + sparse-checkout-cone-mode: true + persist-credentials: false + + - name: Stage estate baseline and install pinned gitleaks + run: | + set -euo pipefail + cp .standards-baseline/config/gitleaks/estate-baseline.toml .gitleaks-estate.toml + rm -rf .standards-baseline + test -s .gitleaks-estate.toml + + TARBALL="gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz" + URL="https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/${TARBALL}" + curl -sSfL --proto '=https' --proto-redir '=https' --tlsv1.2 \ + --retry 3 --retry-delay 2 \ + -o "$RUNNER_TEMP/$TARBALL" "$URL" + echo "${GITLEAKS_SHA256} ${RUNNER_TEMP}/${TARBALL}" | sha256sum -c - + tar -xzf "$RUNNER_TEMP/$TARBALL" -C "$RUNNER_TEMP" gitleaks + chmod +x "$RUNNER_TEMP/gitleaks" + rm -f "$RUNNER_TEMP/$TARBALL" + + - name: Gitleaks working-tree pass + run: | + set -euo pipefail + # The estate baseline always runs; a repository .gitleaks.toml adds a + # second pass and can never stand in for the baseline. + CONFIGS=(".gitleaks-estate.toml") + if [ -f .gitleaks.toml ]; then + CONFIGS+=(".gitleaks.toml") + fi + for CONFIG in "${CONFIGS[@]}"; do + "$RUNNER_TEMP/gitleaks" detect \ + --source . \ + --no-git \ + --redact \ + --no-banner \ + --verbose \ + --config "$CONFIG" \ + --exit-code 1 + done + + - name: Gitleaks full-history pass + run: | + set -euo pipefail + if [ "$(git rev-parse --is-shallow-repository)" != "false" ]; then + echo "::error::checkout is shallow; refusing vacuous history scan" + exit 1 + fi + # The estate baseline always runs; a repository .gitleaks.toml adds a + # second pass and can never stand in for the baseline. + CONFIGS=(".gitleaks-estate.toml") + if [ -f .gitleaks.toml ]; then + CONFIGS+=(".gitleaks.toml") + fi + for CONFIG in "${CONFIGS[@]}"; do + "$RUNNER_TEMP/gitleaks" detect \ + --source . \ + --redact \ + --no-banner \ + --verbose \ + --config "$CONFIG" \ + --exit-code 1 + done + + - name: Gitleaks AsciiDoc mirror pass + run: | + set -euo pipefail + MIRROR="$RUNNER_TEMP/adoc-mirror" + rm -rf "$MIRROR" + mkdir -p "$MIRROR" + found=0 + while IFS= read -r -d '' f; do + dest="$MIRROR/$(dirname "$f")" + mkdir -p "$dest" + cp "$f" "$dest/$(basename "$f").txt" + found=$((found + 1)) + done < <(find . -path ./.git -prune -o \( -name '*.adoc' -o -name '*.asciidoc' \) -type f -print0) + + if [ "$found" -eq 0 ]; then + echo "No AsciiDoc files present." + exit 0 + fi + # The estate baseline always runs; a repository .gitleaks.toml adds a + # second pass and can never stand in for the baseline. + CONFIGS=("$PWD/.gitleaks-estate.toml") + if [ -f .gitleaks.toml ]; then + CONFIGS+=("$PWD/.gitleaks.toml") + fi + for CONFIG in "${CONFIGS[@]}"; do + "$RUNNER_TEMP/gitleaks" detect \ + --source "$MIRROR" \ + --no-git \ + --redact \ + --no-banner \ + --config "$CONFIG" \ + --exit-code 1 + done + + rust-secrets: + name: "scan / rust-secrets" + runs-on: ubuntu-24.04 + timeout-minutes: 10 + permissions: + contents: read + env: + # Findings outside ./src (newly visible — see the scan-scope note in the + # step below) warn until this date, then block. Same warn-then-enforce + # idiom and same cutoff as the estate canonical reusable + # (metadatastician/standards .github/workflows/secret-scanner-reusable.yml + # at the pin named in this file's header), so this job and the reusable + # cannot disagree about when the widened scan starts blocking. + ENFORCE_RUST_WIDE_SCAN_FROM: '2026-08-21' + steps: + - name: Checkout repository + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - name: Check for hardcoded secrets in Rust + run: | + set -euo pipefail + TODAY="${RUST_TODAY:-$(date -u +%Y-%m-%d)}" + + # An unparseable cutoff would pick the warn branch forever, silently + # disarming the widened scan. Refuse to run instead. + require_date() { + local name="$1" value="$2" + case "$value" in + [0-9][0-9][0-9][0-9]-[0-1][0-9]-[0-3][0-9]) : ;; + *) echo "::error::rust-secrets: $name='$value' is not YYYY-MM-DD." + echo "Refusing to run: an unparseable cutoff would disarm this gate." + exit 1 ;; + esac + } + require_date ENFORCE_RUST_WIDE_SCAN_FROM "$ENFORCE_RUST_WIDE_SCAN_FROM" + require_date RUST_TODAY "$TODAY" + + # Self-skips when the tree has no Cargo.toml, so the job is safe on a + # repository that is not (yet) Rust. The check run still appears, which + # is what keeps the context stable across every generated repository. + if ! find . -name Cargo.toml -not -path './target/*' -print -quit | grep -q .; then + echo 'No Cargo.toml found — skipping Rust secrets check' + exit 0 + fi + + # Scan every .rs file, not just ./src. A Cargo workspace keeps its + # code in crates/*/src, and a `grep … src/` matches nothing there: + # grep exits 2 on a missing directory, which an `if` reads as "clean". + mapfile -t FILES < <(find . -name '*.rs' \ + -not -path './target/*' -not -path '*/target/*' \ + -not -path './vendor/*' -not -path '*/vendor/*' \ + -not -path './.git/*' -print) + if [ ${#FILES[@]} -eq 0 ]; then + echo 'Cargo.toml present but no .rs files — nothing to scan' + exit 0 + fi + echo "Scanning ${#FILES[@]} Rust file(s)." + + # Each pattern requires an assignment DIRECTLY to a string literal of + # meaningful length, so lookups, paths and demos do not match. A + # credential shorter than 8 characters is not a credential either. + # `static` is accepted alongside `const`: a `static AUTH_KEY: &str = + # "…"` is a genuine hardcoded secret. + PATTERNS=( + '(const|static)[[:space:]]+(mut[[:space:]]+)?[A-Za-z0-9_]*SECRET[A-Za-z0-9_]*[[:space:]]*(:[^=]*)?=[[:space:]]*b?"[^"]{8,}"' + '(const|static)[[:space:]]+(mut[[:space:]]+)?[A-Za-z0-9_]*KEY[A-Za-z0-9_]*[[:space:]]*(:[^=]*)?=[[:space:]]*b?"[a-zA-Z0-9]{16,}"' + '(const|static)[[:space:]]+(mut[[:space:]]+)?[A-Za-z0-9_]*TOKEN[A-Za-z0-9_]*[[:space:]]*(:[^=]*)?=[[:space:]]*b?"[^"]{8,}"' + '(let|static)[[:space:]]+(mut[[:space:]]+)?[a-z0-9_]*api_key[a-z0-9_]*[[:space:]]*(:[^=]*)?=[[:space:]]*b?"[^"]{8,}"' + 'HMAC.*"[a-fA-F0-9]{32,}"' + '[a-z0-9_]*password[a-z0-9_]*[[:space:]]*(:[^=]*)?=[[:space:]]*b?"[^"]{8,}"' + ) + + # Exemptions match on the VALUE or on an explicit pragma, never on a + # file path: a path-based exemption would blind the job to a genuine + # secret in the same file. + # 1. env-lookup RHS — `env::var("NAME")` IS the practice this job + # exists to enforce, so flagging it fails the correct code. + # 2. URL values — an OAuth endpoint is public, not a credential. + # 3. comment lines — documentation of a pattern is not a secret. + # 4. inline pragma `// scanner-allow: rust-secrets`. + COMMENT='^[^:]*:[0-9][0-9]*:[[:space:]]*(//|/\*|\*)' + ENV_RHS='=[^;]*(env::var|env::var_os|std::env|env!\(|option_env!\(|from_env|dotenv)' + URL_RHS='=[[:space:]]*b?"(https?|wss?|ftp)://' + PRAGMA='scanner-allow:[[:space:]]*rust-secrets' + + blocking=0 + advisory=0 + for pattern in "${PATTERNS[@]}"; do + hits="$(grep -nHE "$pattern" "${FILES[@]}" 2>/dev/null \ + | grep -vE "$COMMENT" \ + | grep -vE "$ENV_RHS" \ + | grep -vE "$URL_RHS" \ + | grep -vE "$PRAGMA" || [ $? -eq 1 ])" + [ -n "$hits" ] || continue + + # ./src hits keep blocking. Hits outside it are newly visible, so + # they warn until the cutoff rather than reddening repositories + # whose wider tree was never actually being scanned. + old_scope="$(printf '%s\n' "$hits" | grep -E '^\./src/' || [ $? -eq 1 ])" + new_scope="$(printf '%s\n' "$hits" | grep -vE '^\./src/' || [ $? -eq 1 ])" + + # Print file:line only. The matched source text is the credential + # itself; echoing it would publish it to the Actions log. + if [ -n "$old_scope" ]; then + printf '%s\n' "$old_scope" | cut -d: -f1,2 | sed 's/$/: hardcoded-secret pattern match (line text withheld)/' + echo "WARNING: Potential hardcoded secret found matching: $pattern" + blocking=1 + fi + if [ -n "$new_scope" ]; then + printf '%s\n' "$new_scope" | cut -d: -f1,2 | sed 's/$/: hardcoded-secret pattern match (line text withheld)/' + if [[ "$TODAY" < "$ENFORCE_RUST_WIDE_SCAN_FROM" ]]; then + echo "::warning::Potential hardcoded secret outside ./src matching:" \ + "$pattern — becomes BLOCKING on $ENFORCE_RUST_WIDE_SCAN_FROM (today is $TODAY)." + advisory=1 + else + echo "WARNING: Potential hardcoded secret found matching: $pattern" + blocking=1 + fi + fi + done + + if [ "$blocking" -eq 1 ]; then + echo "::error::Potential hardcoded secrets detected. Use environment variables instead." + exit 1 + fi + if [ "$advisory" -eq 1 ]; then + # Never claim a clean pass while findings are outstanding. + echo "NOT YET ENFORCED: findings outside ./src are advisory until $ENFORCE_RUST_WIDE_SCAN_FROM." + exit 0 + fi + echo 'No hardcoded secrets detected in Rust sources.' + + shell-secrets: + name: "scan / shell-secrets" + 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: Run repository secret pattern hook + run: | + set -euo pipefail + rc=0 + # Provider-specific patterns, plus assignment of a quoted literal to a + # *_TOKEN / *_KEY / *_SECRET / password name (as in the estate canonical + # reusable, metadatastician/standards@f0b3cd4 + # .github/workflows/secret-scanner-reusable.yml). The value classes + # exclude '$', so ="${VAR}" and ="$VAR" never match. Only file names + # are listed, never the matched text. + SQ="'" + ASSIGN="[A-Z_]*(TOKEN|API_KEY|SECRET)[A-Z_]*=[\"${SQ}][A-Za-z0-9_./+=-]{16,}[\"${SQ}]|PASS[W]ORD=[\"${SQ}][^\"${SQ}\$]{6,}[\"${SQ}]" + PROVIDER='ghp_[A-Za-z0-9]{36}|github_pat_[A-Za-z0-9_]{82}|glpat-[A-Za-z0-9_-]{20,}|AKIA[0-9A-Z]{16}|-----BEGIN (RSA |EC |OPENSSH )?PRIVATE KEY-----' + git grep -IlE "(${PROVIDER}|${ASSIGN})" > "$RUNNER_TEMP/hits.txt" || rc=$? + # git grep exits 1 when nothing matches; above 1 is an error. + if [ "$rc" -gt 1 ]; then + echo "::error::Secret pattern scan failed with exit ${rc}" + exit 2 + fi + # Exclude intentional scanner rules and adversarial negative test fixtures. + filtered="$(grep -vE '^(\.github/hooks/scan-secrets\.sh|\.github/workflows/secret-scanner\.yml|\.machine_readable/testing/adversarial-content\.k9\.ncl|tests/)' "$RUNNER_TEMP/hits.txt" || :)" + if [ -n "$filtered" ]; then + echo "::error::Hardcoded credential material detected:" + printf '%s\n' "$filtered" + exit 1 + fi + echo "No hardcoded shell/source credentials detected." diff --git a/.github/workflows/security-policy.yml b/.github/workflows/security-policy.yml index 8d80728..5d332c1 100644 --- a/.github/workflows/security-policy.yml +++ b/.github/workflows/security-policy.yml @@ -21,7 +21,9 @@ jobs: 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 @@ -34,7 +36,7 @@ jobs: fi # Block HTTP URLs (except localhost) - HTTP_URLS=$(grep -rE 'http://[^l][^o][^c]' --include="*.py" --include="*.js" --include="*.ts" --include="*.go" --include="*.rs" --include="*.yaml" --include="*.yml" . 2>/dev/null | grep -v 'localhost\|127.0.0.1\|example\|test\|spec' | head -5 || true) + HTTP_URLS=$(grep -rE 'http://[^l][^o][^c]' --include="*.py" --include="*.js" --include="*.ts" --include="*.go" --include="*.rs" --include="*.yaml" --include="*.yml" --include="*.kyaml" . 2>/dev/null | grep -v 'localhost\|127.0.0.1\|example\|test\|spec' | head -5 || true) # NOSONAR githubactions:S5332: regex that detects http:// URLs, not a request if [ -n "$HTTP_URLS" ]; then echo "⚠️ HTTP URLs found. Use HTTPS:" echo "$HTTP_URLS" diff --git a/.github/workflows/sonarqube.yml b/.github/workflows/sonarqube.yml index ca5ef71..ee817b3 100644 --- a/.github/workflows/sonarqube.yml +++ b/.github/workflows/sonarqube.yml @@ -38,13 +38,17 @@ jobs: name: SonarQube 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. - env: - SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }} steps: - name: Report configuration state id: cfg + # A job-level `if:` cannot read a secret. This step reads the token + # and gives the result to the steps after it. The token is in the + # environment of this step and of the scan step only. + env: + SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }} + # The script of this step is Bash. `shell: bash` says so in the step: + # a default shell or a runner with a different shell cannot change it. + shell: bash run: | if [ -z "${SONAR_TOKEN}" ]; then echo "configured=false" >> "$GITHUB_OUTPUT" diff --git a/.github/workflows/squabble.yml b/.github/workflows/squabble.yml new file mode 100644 index 0000000..ef85af2 --- /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 0d27daf..d6d4a8f 100644 --- a/.github/workflows/static-analysis-gate.yml +++ b/.github/workflows/static-analysis-gate.yml @@ -1,7 +1,36 @@ # 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 (owner ruling 2026-11-12): pons blocks on ERROR-level findings that it +# does not itself call speculative; a pons that did not run, or produced no +# readable report, also blocks (never a silent pass). panic-attack and +# patch-bridge are advisory: they write their evidence and annotate but do not +# fail the check. The verdict grid never gates. name: Static Analysis Gate on: pull_request: @@ -13,288 +42,227 @@ 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 + name: panic-attack & pons-asinorum deep recon runs-on: ubuntu-24.04 - timeout-minutes: 15 + 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' + # Advisory (owner ruling 2026-11-12): panic-attack does not gate. A failed + # or untrustworthy run still exits non-zero so the step shows as failed + # and the envelope says "error" (orange in the grid), but the job goes on. + continue-on-error: 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 "::warning::panic-attack (advisory, does not gate) 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-24.04 - 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 - continue-on-error: true + - name: Run pons-asinorum deep recon audit + id: pons + # Gating (owner ruling 2026-11-12): deliberately no continue-on-error. + # Not-run, error and non-speculative ERROR findings all exit non-zero. 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" + 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 - - 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 + 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=$? + + 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" + } - # --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" + 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 - # `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" + 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" + if [ "$ERR_COUNT" -ne 0 ]; then + echo "::error::pons found ${ERR_COUNT} non-speculative ERROR finding(s) - blocking merge" exit 1 fi - TOTAL=$(jq '. | length' hypatia-findings.json 2>/dev/null || echo 0) - CRITICAL=$(jq '[.[] | select(.severity == "critical")] | length' hypatia-findings.json 2>/dev/null || echo 0) - HIGH=$(jq '[.[] | select(.severity == "high")] | length' hypatia-findings.json 2>/dev/null || echo 0) - MEDIUM=$(jq '[.[] | select(.severity == "medium" 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) - - 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 - - | 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: Warn on critical panic-attack findings (advisory) + 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" - exit 1 + echo "::warning::panic-attack found ${CRIT_COUNT} critical issue(s) (advisory: panic-attack does not gate)" + # --------------------------------------------------------------------------- - # 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-24.04 - timeout-minutes: 15 + 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 +274,168 @@ 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-24.04 timeout-minutes: 15 - needs: [panic-attack-assail, hypatia-scan, patch-bridge-triage] - if: always() + needs: [panic-attack-assail, patch-bridge-triage] + # !cancelled(), not always(): deposit what the scans found even when one + # failed, but not after the run was cancelled (a superseding push), when + # the artifacts were never uploaded and the download step can only fail. + if: ${{ !cancelled() }} 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 0000000..465f8df --- /dev/null +++ b/.github/workflows/verdict-grid-publish.yml @@ -0,0 +1,170 @@ +# 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 # NOSONAR githubactions:S7631: ref is the default branch, not PR code + 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 # NOSONAR githubactions:S7631: fixed trusted repo at a pinned SHA, not fork code + with: + repository: metadatastician/standards + ref: f0b3cd4c464d33e1584f8528c17bce104555e256 + 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" \ + --hypatia-sarif "$ev/hypatia-scan-findings/hypatia.sarif" \ + --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 5aefa7b..ea906ab 100644 --- a/.github/workflows/workflow-linter.yml +++ b/.github/workflows/workflow-linter.yml @@ -6,6 +6,10 @@ name: Workflow Security Linter on: push: + # A PR push already runs this through pull_request; push runs only on + # main, so each PR push is linted once and main is still checked after merge. + branches: + - main paths: - '.github/workflows/**' pull_request: @@ -38,7 +42,7 @@ jobs: [ -f "$file" ] || continue # actions-lock may prepend its own comment. Require the licence # in the leading comment block, before the workflow body. - if ! awk '/^# SPDX-License-Identifier:/ { found=1 } /^[^#[:space:]]/ { exit } END { exit !found }' "$file"; then + if ! awk '/^# SPDX-License-Identifier:/ { found=1 } /^[[:space:]]*[^#[:space:]]/ { exit } END { exit !found }' "$file"; then echo "ERROR: $file missing SPDX header" failed=1 fi @@ -67,12 +71,17 @@ jobs: echo "All workflows have permissions declared" # Bun is the estate's first-choice runtime (LANGUAGE-POLICY.adoc §1: - # Bun > Deno > pnpm > npm). 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 638db64..c66de1b 100644 --- a/.gitignore +++ b/.gitignore @@ -12,7 +12,9 @@ Thumbs.db .direnv/ # Agent / local session artifacts (Claude Code worktrees, scratch) — never commit -.claude/ +.claude/* +!.claude/settings.json +!.claude/hooks/ # Build target/ diff --git a/.hypatia-ignore b/.hypatia-ignore index 1722a94..b4c79dc 100644 --- a/.hypatia-ignore +++ b/.hypatia-ignore @@ -13,18 +13,6 @@ # below carries a stated reason. Prefer fix-the-code or an inline directive # over an entry here; this file is for whole-file/directory exemptions. -# ─── build/docs-seed/ describes DOWNSTREAM repos, not this one ───────────── -# -# `build/docs-seed/` is the canonical template of documentation that gets -# copied into scaffolded repos. Its example paths (e.g. `src/middleware/…`, -# `src/main.rs`) describe a hypothetical generated project, so they -# legitimately do not resolve against this template's own tree. SD022 -# (stale `src//` reference) is therefore a structural false positive -# for everything under this directory — mirrors the built-in CHANGELOG.md -# and third_party/ carve-outs. Scaffolded repos inherit this file, so the -# exemption travels with the template. -structural_drift/SD022:build/docs-seed/ - # ─── Research-extension workflow findings ─────────────────────────────────────── # # RE001 is an advisory recommendation to add harden-runner whenever a workflow @@ -53,3 +41,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/coaptation/README.adoc b/.machine_readable/coaptation/README.adoc index 17ed7bc..f039429 100644 --- a/.machine_readable/coaptation/README.adoc +++ b/.machine_readable/coaptation/README.adoc @@ -24,25 +24,37 @@ toc::[] Contractiles emit *obligations* (clauses); descriptiles emit *evidence* (facts). The correspondence is a *typed relation that only inhabits when evidence witnesses -obligation* — not a string comparison. In the Idris2 sound core: +obligation*, not a string comparison. In the Idris2 sound core +(`core/Coaptation.idr`): [source,idris] ---- -Clause : Verb -> Type -Fact : Family -> Type -Witnesses : Clause -> Fact -> Type -- inhabited iff the fact attests the clause +data Holds : List Fact -> Spec -> Type -- the looked-up fact satisfies the spec's predicate +data Witness : List Fact -> List Spec -> Type -- a NON-EMPTY spec list, every spec holding +data HardResolved : List Fact -> WMap -> Clause -> Type -- ByWitness | ByDeferral; no gap constructor ---- -The dependent-array spine makes coverage *total by construction*: the obligation -vector indexes the evidence vector, so an unwitnessed `Must` clause is a -compile-time error, not a forgotten check. This is now *proven*, not just declared: -in `core/Coaptation.idr` the `MayGap` type has no constructor for `Must`/`Trust`, so -`TotalCoverage` forces a witness on every hard obligation — and a `failing` block -makes `idris2 --check` itself the proof (it asserts that gapping a `Must` does not -typecheck). What is still pending (build-path step 6's remaining sub-step) is -*wiring* that core to consume the runner's atomised JSON; until then the -*authoritative* reading is the Nickel comparator, `coapt.ncl`, and the core proves -the property on hand-built examples. +What is proved, kernel-checked by `idris2 --check` and gated through +`just proof-check-idris2` (`verification/proofs/idris2/MANIFEST`): + +* `hardGateSound` and `hardGateComplete`: the Must/Trust gate function returns + `True` exactly when every hard clause carries a `HardResolved` term. A + witness holds the actual fact the lookup finds and a proof that its + predicate is true. +* `mustCannotGap` and `trustCannotGap`: no gap permission exists for the hard + verbs, for any clause. + +What is *not* proved: that the Idris2 model is a faithful transcription of the +Nickel comparator `coapt.ncl`. That bridge is argued in the core's comments +(PROOF-POLICY status `ASSUMED`), and `coapt.ncl` stays the authoritative +reading. The model also records today's behaviour honestly: a hard clause with +a runnable probe and no witness is `probe-deferred` and does not fail the Yard +gate (`ByDeferral`). The standards ultraplan (P2.1) rules that such clauses +become blocking until a Hunt run reports; the core drops `ByDeferral` then. + +`coapt.ncl` treats a witness-map entry with an empty witness list as refuted (it would +otherwise read as witnessed with no evidence); the soundness proof depends on +that rule. == The cybernetic loop is the k9 ladder @@ -88,7 +100,7 @@ the "how far is too far" that proposes a re-anchor: `green` (nothing) / [cols="1,3"] |=== | `extract-clauses.sh` | Normative-side atomiser. Lifts the records of the `declaration` field of the six `/.k9.ncl` files (`nickel export` piped to `jq`) into `clauses.json` (stable id `verb.slug`). Reader only. -| `extract-facts.sh` | Descriptive-side atomiser. Projects the repo deed (through `scripts/deed-field.sh`), including its `(anchor …)` clause, into `facts.json` (stable id `family.key`). The family prefixes `clade.` `state.` `ecosystem.` `agentic.` name the deed clauses that replaced the retired CLADE / STATE / ECOSYSTEM / AGENTIC records (rsr-template-repo#209) and are kept so the witness map does not change. +| `extract-facts.sh` | Descriptive-side atomiser. Projects the repo deed (through `scripts/deed-field.sh`), including its `(anchor …)` clause, into `facts.json` (stable id `family.key`). The family prefixes `clade.` `state.` `ecosystem.` `agentic.` name the deed clauses that replaced the retired CLADE / STATE / ECOSYSTEM / AGENTIC records (rsr-template-repo#209) and are kept so the witness map does not change. `neurosym.` and `playbook.` facts come from the `(neurosym …)` and `(playbook …)` clauses. Each prefix is a `Family` constructor in `core/Coaptation.idr`, lower-cased. | `witness-map.ncl` | The hand-authored *knowledge* layer: which fact witnesses which clause, under what predicate. The one file to review for honesty. | `grades.ncl` | Grade type per verb + aggregation tolerances. | `coapt.ncl` | The Yard comparator. Imports the atoms + map + grades; emits the receipt (`nickel export --format raw`). @@ -96,7 +108,7 @@ the "how far is too far" that proposes a re-anchor: `green` (nothing) / | `verify.sh` | Yard drift gate. Regenerates the receipt and byte-compares the committed one. | `coapt.k9.ncl` | k9 contract (Yard) documenting + validating the drift check. Sibling of `arrival-pack/claude-md.k9.ncl`. | `receipts/latest.toml` | The committed coaptation receipt — the drift baseline. -| `core/Coaptation.idr` | Dependent-typed sound core. Proves the totality property (unwitnessed Must = compile-time error) via a `failing` block; not yet wired to the runner JSON (build-path step 6). +| `core/Coaptation.idr` | Idris2 sound core: a model of the Must/Trust gate, proved sound and complete against a content-bearing witness relation, with no gap for Must/Trust. Gated by `just proof-check-idris2`. Not yet fed the runner JSON, so the Nickel reading stays authoritative (build-path step 6). |=== == Usage @@ -120,11 +132,10 @@ just validate-coapt # Yard drift gate: fail if the committed receipt is stal * *The Nickel prototype does NOT make an unwitnessed Must a hard error.* In the authoritative Nickel reading today, a Must with a probe but no descriptile witness is soft `probe-deferred`, not red; only a Must with neither witness nor probe - (`unmeasured`) trips red. The hard totality guarantee ("an unwitnessed Must is a - compile-time error") is *proven in the Idris2 sound core* (`core/Coaptation.idr`, - machine-checked by a `failing` block), but on hand-built examples — it does not - govern the Nickel reading until the core is *wired* to consume the runner's JSON - (build-path step 6's remaining sub-step). + (`unmeasured`) trips red. The Idris2 core (`core/Coaptation.idr`) proves the gate model sound and + complete, and that Must/Trust have no gap, for all inputs. It does not govern + the Nickel reading until it is *wired* to consume the runner's JSON (build-path + step 6's remaining sub-step); the model-to-Nickel bridge is argued, not proved. * *Bust has no descriptile witness.* The three bust clauses used to read the retired STATE record's open-failures / last-result, which held hand-written values that no maintenance run updated. The deed has no such field, so they are unwitnessed and @@ -135,14 +146,14 @@ just validate-coapt # Yard drift gate: fail if the committed receipt is stal ledger is the prerequisite for a real re-anchor branch. * *The contractile runner toolset is known-broken* estate-wide; Coaptation does not depend on it — it reads the K9 declarations directly — but it does not fix it either. -* *The witness map is declarative.* Soundness-critical Must/Trust witnesses should - graduate to Idris2 `Witnesses` proofs (build-path step 6); today they are - predicate assertions a human must keep honest. +* *The witness map is declarative.* The Idris2 core proves what a witness must + carry, but which fact witnesses which clause is still a human judgement in + `witness-map.ncl`, and it must be kept honest. == Build path (this pack delivers steps 1–5; 6–7 pending) . *Atomise both sides* — `extract-clauses.sh` + `extract-facts.sh`. ✅ -. *Witness map* — declarative; graduate soundness-critical entries to Idris2. ✅ (declarative) +. *Witness map* — declarative; the Must/Trust gate over it is modelled and proved in Idris2 (`core/Coaptation.idr`). ✅ . *Grade types per verb* + aggregation — `grades.ncl`. ✅ . *Comparator in the Yard tier* — `coapt.ncl` (Nickel prototype). ✅ . *Actuation in Hunt* with bands — `coapt.sh` (green=nil / amber=advisory / red=basis). ✅ (basis; ledger pending) diff --git a/.machine_readable/coaptation/coapt.k9.ncl b/.machine_readable/coaptation/coapt.k9.ncl index d15eace..22b354a 100644 --- a/.machine_readable/coaptation/coapt.k9.ncl +++ b/.machine_readable/coaptation/coapt.k9.ncl @@ -13,6 +13,7 @@ K9! { pedigree = { schema_version = "1.0.0", + component_type = "drift-check:coaptation-receipt", contractile_verb = "trust", # provenance: the reading must equal its sources semantics = "coaptation-fidelity", security = { @@ -20,7 +21,7 @@ K9! trust_level = "read-only comparison", allow_network = false, allow_filesystem_write = false, - allow_subprocess = true, # runs the extractors + nickel to reproduce the reading + allow_subprocess = false, # verify.sh runs the extractors + nickel; this record does not }, metadata = { name = "coaptation", diff --git a/.machine_readable/coaptation/coapt.ncl b/.machine_readable/coaptation/coapt.ncl index e207137..50b4648 100644 --- a/.machine_readable/coaptation/coapt.ncl +++ b/.machine_readable/coaptation/coapt.ncl @@ -8,11 +8,11 @@ # (Coverage), grades per verb, aggregates to a band, and renders the coaptation # receipt as deterministic TOML text (exported with `nickel export --format raw`). # -# This is the Nickel prototype of the comparator. The dependent-typed sound core -# (Idris2 `Witnesses`/`Coverage`, where an unwitnessed Must is a COMPILE-TIME -# error) is build-path step 6 — see core/Coaptation.idr (skeleton). The Nickel and -# Idris2 readings must agree once the core is wired; today the Nickel reading is -# authoritative and the core is a forward declaration of its types. +# This is the authoritative comparator. core/Coaptation.idr models its Must/Trust +# gate in Idris2 and proves that model sound and complete against a +# content-bearing witness relation. The correspondence between this file and +# that model is argued in the model's comments, not kernel-checked, so a change +# to the gate logic here must be mirrored there. let clauses_doc = import "clauses.json" in let facts_doc = import "facts.json" in let wmap = import "witness-map.ncl" in @@ -61,8 +61,11 @@ let evals = "unmeasured" in let sat = + # A descriptile entry needs at least one witness: `std.array.all` over an + # empty list is true, which would read "witnessed" with no evidence. + # core/Coaptation.idr proves the gate sound only with this rule. if base_kind == "descriptile" then - std.array.all eval_w entry.witnesses + std.array.length entry.witnesses > 0 && std.array.all eval_w entry.witnesses else false in diff --git a/.machine_readable/coaptation/core/Coaptation.idr b/.machine_readable/coaptation/core/Coaptation.idr index 5593535..fe1acc5 100644 --- a/.machine_readable/coaptation/core/Coaptation.idr +++ b/.machine_readable/coaptation/core/Coaptation.idr @@ -2,111 +2,323 @@ ||| Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) ||| Owner: Jonathan D.A. Jewell ||| -||| Coaptation sound core — build-path step 6 (in progress). Declares the -||| dependent-typed shape of the descriptile↔contractile face-off: obligations -||| (Clause), evidence (Fact), the witness relation, and the TOTALITY of coverage. +||| Coaptation sound core: the hard (Must/Trust) gate of the comparator +||| `coapt.ncl`, modelled in Idris2 with a content-bearing witness relation. ||| -||| The central property is now PROVEN, not merely declared: `MayGap` has no -||| constructor for `Must`/`Trust`, so `TotalCoverage` forces `IsWitnessed` on every -||| hard obligation — an unwitnessed Must is a compile-time error. The `failing` -||| block below makes `idris2 --check` itself the proof: it asserts that gapping a -||| Must does NOT typecheck. +||| What is modelled. `coapt.ncl` reads the atomised clauses (`clauses.json`), +||| the atomised facts (`facts.json`) and the witness map (`witness-map.ncl`). +||| A clause listed in the map as `descriptile` is witnessed when every one of +||| its witness specs holds: the named fact, looked up by id, satisfies the +||| spec's predicate. The Must/Trust gate passes when no hard clause is +||| refuted, gapped or unmeasured. A hard clause that is unlisted but has a +||| runnable probe is "probe-deferred" and does NOT fail the Yard gate today. ||| -||| Still pending (the remaining sub-step): WIRING this core to consume the runner's -||| atomised JSON (clauses.json / facts.json) so the Idris reading and the Nickel -||| reading provably agree. Until then the Nickel comparator (coapt.ncl) is the -||| AUTHORITATIVE reading and this core proves the property on hand-built examples. +||| What is proved (kernel-checked by `idris2 --check`): +||| +||| * `hardGateSound`: if the gate function returns True, every Must/Trust +||| clause carries a `HardResolved` term. That term is either a WITNESS, which +||| holds, for every spec, the fact actually found by the lookup and a proof +||| that its predicate is true, over a non-empty spec list; or a recorded +||| PROBE DEFERRAL. There is no constructor for a gap. +||| * `hardGateComplete`: the converse. So the Bool gate and the evidence type +||| agree exactly. +||| * `mustCannotGap`, `trustCannotGap`: no gap permission exists for the hard +||| verbs, for any clause, not only for an example. +||| +||| What is NOT proved. That this model is a faithful transcription of +||| `coapt.ncl`. The correspondence is argued line by line in the comments +||| below (policy status ASSUMED for that bridge), not kernel-checked: Nickel +||| is the authoritative reading. The deferral constructor exists because the +||| comparator lets probe-deferred hard clauses pass; ultraplan P2.1 (standards) +||| rules that they become blocking until a Hunt run reports, and this core +||| drops `ByDeferral` when that lands. module Coaptation -import Data.Vect -import Data.Fin +import Data.List +import Data.List.Quantifiers +import Data.String + +%default total -||| The six normative contractile verbs. +-- ── Vocabulary (mirrors clauses.json `verb`) ──────────────────────────────── + +||| The six contractile verbs. public export data Verb = Intend | Must | Trust | Adjust | Dust | Bust -||| The descriptive families that emit evidence (the descriptiles). +||| The hard verbs. coapt.ncl: `e.verb == "must" || e.verb == "trust"`. +public export +isHard : Verb -> Bool +isHard Must = True +isHard Trust = True +isHard _ = False + +||| The descriptive families that emit evidence (the descriptiles). Each one is +||| read from clauses of the repo deed (`_chora.deed`) by extract-facts.sh, +||| and its name, lower-cased, is the prefix of the fact IDs it emits: +||| CLADE (identity) (clade) (lineage) (forges) — what the repo IS +||| STATE (status) (maturity) — where it is now +||| ECOSYSTEM (ecosystem) — where it sits, what it is not +||| AGENTIC (agentic) — may I act now? +||| NEUROSYM (neurosym) — the meaning of operations +||| PLAYBOOK (playbook) — how permitted actions run +||| ANCHOR (anchor) — semantic authority + golden path +public export +data Family = CLADE | STATE | ECOSYSTEM | AGENTIC | NEUROSYM | PLAYBOOK | ANCHOR + +||| Permission to leave a clause unresolved. Constructors exist only for the +||| soft verbs, so a hard clause can never be gapped. +public export +data MayGap : Verb -> Type where + IntendMayGap : MayGap Intend + AdjustMayGap : MayGap Adjust + DustMayGap : MayGap Dust + BustMayGap : MayGap Bust + +export +Uninhabited (MayGap Must) where + uninhabited IntendMayGap impossible + uninhabited AdjustMayGap impossible + uninhabited DustMayGap impossible + uninhabited BustMayGap impossible + +export +Uninhabited (MayGap Trust) where + uninhabited IntendMayGap impossible + uninhabited AdjustMayGap impossible + uninhabited DustMayGap impossible + uninhabited BustMayGap impossible + +||| A Must clause can never be gapped (universal, not an example). +export +mustCannotGap : MayGap Must -> Void +mustCannotGap = absurd + +||| A Trust clause can never be gapped. +export +trustCannotGap : MayGap Trust -> Void +trustCannotGap = absurd + +-- ── Data (mirrors facts.json, clauses.json, witness-map.ncl) ──────────────── + +||| A descriptive fact. facts.json: { id, value, present }. +public export +record Fact where + constructor MkFact + fid : String + value : String + present : Bool + +||| A contractile clause. clauses.json: { id, verb, has_probe }. +public export +record Clause where + constructor MkClause + cid : String + verb : Verb + hasProbe : Bool + +||| Witness predicates. witness-map.ncl ops. +public export +data Op = Present | Absent | Zero | NonZero + | Equals String | Contains String | NotContains String + +||| One witness spec: a fact id and the predicate it must satisfy. +public export +record Spec where + constructor MkSpec + fact : String + op : Op + +||| A witness-map entry. `kind = "descriptile"` with its specs, or +||| `kind = "none"` (an explicit gap). +public export +data Entry = Descriptile (List Spec) | NoWitness + +||| The witness map: clause id to entry. An id with no entry is `auto`. +public export +WMap : Type +WMap = List (String, Entry) + +-- ── The comparator, as Bool functions (the Nickel reading) ────────────────── + +||| coapt.ncl `lookup`: the fact with this id, or an absent empty fact. +public export +lookupFact : String -> List Fact -> Fact +lookupFact i [] = MkFact i "" False +lookupFact i (f :: fs) = if fid f == i then f else lookupFact i fs + +||| coapt.ncl: the witness-map entry for a clause id, if listed. +public export +lookupEntry : String -> WMap -> Maybe Entry +lookupEntry i [] = Nothing +lookupEntry i ((k, e) :: rest) = if k == i then Just e else lookupEntry i rest + +||| coapt.ncl `eval_w`, per op. `std.string.contains arg value` is +||| `isInfixOf arg value`. +public export +evalOp : Op -> Fact -> Bool +evalOp Present f = present f +evalOp Absent f = not (present f) +evalOp Zero f = value f == "0" +evalOp NonZero f = if present f then not (value f == "0") else False +evalOp (Equals a) f = value f == a +evalOp (Contains a) f = isInfixOf a (value f) +evalOp (NotContains a) f = not (isInfixOf a (value f)) + +public export +evalSpec : List Fact -> Spec -> Bool +evalSpec fs s = evalOp (op s) (lookupFact (fact s) fs) + +||| Structural `all`, so proofs can reason about it. public export -data Family = CLADE | STATE | ECOSYSTEM | AGENTIC | ANCHOR +allSpecs : List Fact -> List Spec -> Bool +allSpecs fs [] = True +allSpecs fs (s :: ss) = if evalSpec fs s then allSpecs fs ss else False -||| A contractile obligation, indexed by its verb. +||| A descriptile entry is satisfied only by a NON-EMPTY spec list whose specs +||| all hold. (coapt.ncl applies the same non-empty rule; an empty list there +||| is refuted, never vacuously witnessed.) public export -data Clause : Verb -> Type where - MkClause : (id : String) -> (v : Verb) -> Clause v +satisfied : List Fact -> List Spec -> Bool +satisfied fs [] = False +satisfied fs (s :: ss) = allSpecs fs (s :: ss) -||| A descriptive fact, indexed by its family. +||| coapt.ncl per-clause status, for a hard clause. public export -data Fact : Family -> Type where - MkFact : (id : String) -> (f : Family) -> Fact f +data HardStatus = Witnessed | Refuted | Gap | ProbeDeferred | Unmeasured -||| Existential wrappers so heterogeneous clauses/facts share one vector spine. public export -SomeClause : Type -SomeClause = (v : Verb ** Clause v) +classify : List Fact -> WMap -> Clause -> HardStatus +classify fs wm c with (lookupEntry (cid c) wm) + _ | Just (Descriptile ss) = if satisfied fs ss then Witnessed else Refuted + _ | Just NoWitness = Gap + _ | Nothing = if hasProbe c then ProbeDeferred else Unmeasured +||| coapt.ncl `mt_gate`: refuted, gap and unmeasured fail; witnessed and +||| probe-deferred do not. public export -SomeFact : Type -SomeFact = (f : Family ** Fact f) +passes : HardStatus -> Bool +passes Witnessed = True +passes ProbeDeferred = True +passes _ = False -||| The correspondence: inhabited iff a fact witnesses an obligation. The single -||| constructor here is a PLACEHOLDER; soundness-critical Must/Trust correspondences -||| graduate to real, content-bearing proof obligations — the whole reason for -||| putting the core in Idris2. +||| The Must/Trust gate over every clause. public export -data Witnesses : SomeClause -> SomeFact -> Type where - Attests : (c : SomeClause) -> (x : SomeFact) -> Witnesses c x +hardGate : List Fact -> WMap -> List Clause -> Bool +hardGate fs wm [] = True +hardGate fs wm (c :: cs) = + if isHard (verb c) + then (if passes (classify fs wm c) then hardGate fs wm cs else False) + else hardGate fs wm cs -||| Permission to leave an obligation UNWITNESSED. This is the load-bearing type: -||| it has constructors ONLY for the verbs whose grade tolerates a gap — -||| Intend (tropical distance), Adjust (advisory posture), Dust (planned exnovation), -||| Bust (a declared-but-latent break). There is deliberately NO constructor for -||| `Must` or `Trust`, so `MayGap (Must ** _)` and `MayGap (Trust ** _)` are -||| UNINHABITED: a hard obligation cannot be gapped. +-- ── The evidence (content-bearing) ────────────────────────────────────────── + +||| One spec holds: the very fact the lookup returns, and its predicate. +public export +data Holds : List Fact -> Spec -> Type where + MkHolds : (f : Fact) -> lookupFact (fact s) fs = f -> evalOp (op s) f = True + -> Holds fs s + +||| A witness: a non-empty spec list, every spec holding. public export -data MayGap : SomeClause -> Type where - IntendMayGap : MayGap (Intend ** c) - AdjustMayGap : MayGap (Adjust ** c) - DustMayGap : MayGap (Dust ** c) - BustMayGap : MayGap (Bust ** c) +data Witness : List Fact -> List Spec -> Type where + MkWitness : NonEmpty ss -> All (Holds fs) ss -> Witness fs ss -||| How a single obligation is resolved: either a fact witnesses it, or its verb -||| permits a gap. A Must/Trust clause can ONLY take the `IsWitnessed` branch, -||| because `IsGap` demands a `MayGap` that does not exist for those verbs. +||| How a hard clause is resolved. No constructor for a gap. public export -data Resolved : SomeClause -> Type where - IsWitnessed : (x : SomeFact) -> Witnesses c x -> Resolved c - IsGap : MayGap c -> Resolved c +data HardResolved : List Fact -> WMap -> Clause -> Type where + ByWitness : lookupEntry (cid c) wm = Just (Descriptile ss) -> Witness fs ss + -> HardResolved fs wm c + ByDeferral : lookupEntry (cid c) wm = Nothing -> hasProbe c = True + -> HardResolved fs wm c -||| Coverage is TOTAL by construction: a resolution for every obligation in the -||| vector. Because `Resolved` forces `IsWitnessed` on Must/Trust, an unwitnessed -||| hard obligation is a COMPILE-TIME error, not a forgotten check — the whole -||| reason for putting the core in Idris2. +||| Every hard clause in the list is resolved. public export -TotalCoverage : {n : Nat} -> Vect n SomeClause -> Type -TotalCoverage cs = (i : Fin n) -> Resolved (index i cs) +data GateEvidence : List Fact -> WMap -> List Clause -> Type where + Done : GateEvidence fs wm [] + Hard : isHard (verb c) = True -> HardResolved fs wm c + -> GateEvidence fs wm cs -> GateEvidence fs wm (c :: cs) + Soft : isHard (verb c) = False + -> GateEvidence fs wm cs -> GateEvidence fs wm (c :: cs) + +-- ── Lemmas ────────────────────────────────────────────────────────────────── + +allSpecsHolds : (fs : List Fact) -> (ss : List Spec) -> allSpecs fs ss = True + -> All (Holds fs) ss +allSpecsHolds fs [] _ = [] +allSpecsHolds fs (s :: ss) prf with (evalSpec fs s) proof p + _ | True = MkHolds (lookupFact (fact s) fs) Refl p :: allSpecsHolds fs ss prf + _ | False = absurd prf + +holdsAllSpecs : (fs : List Fact) -> (ss : List Spec) -> All (Holds fs) ss + -> allSpecs fs ss = True +holdsAllSpecs fs [] [] = Refl +holdsAllSpecs fs (s :: ss) (MkHolds f eq ok :: hs) with (evalSpec fs s) proof p + _ | True = holdsAllSpecs fs ss hs + _ | False = absurd (trans (sym p) (replace {p = \g => evalOp (op s) g = True} (sym eq) ok)) + +resolveSound : (fs : List Fact) -> (wm : WMap) -> (c : Clause) + -> passes (classify fs wm c) = True -> HardResolved fs wm c +resolveSound fs wm c prf with (lookupEntry (cid c) wm) proof e + _ | Just (Descriptile []) = absurd prf + _ | Just (Descriptile (s :: ss)) with (allSpecs fs (s :: ss)) proof a + _ | True = ByWitness e (MkWitness IsNonEmpty (allSpecsHolds fs (s :: ss) a)) + _ | False = absurd prf + _ | Just NoWitness = absurd prf + _ | Nothing with (hasProbe c) proof h + _ | True = ByDeferral e h + _ | False = absurd prf + +resolveComplete : (fs : List Fact) -> (wm : WMap) -> (c : Clause) + -> HardResolved fs wm c -> passes (classify fs wm c) = True +resolveComplete fs wm c (ByWitness {ss} e (MkWitness ne hs)) with (lookupEntry (cid c) wm) + resolveComplete fs wm c (ByWitness {ss = s :: ss'} Refl (MkWitness IsNonEmpty hs)) | Just (Descriptile (s :: ss')) = + rewrite holdsAllSpecs fs (s :: ss') hs in Refl +resolveComplete fs wm c (ByDeferral e h) with (lookupEntry (cid c) wm) + resolveComplete fs wm c (ByDeferral Refl h) | Nothing = rewrite h in Refl + +-- ── The theorems ──────────────────────────────────────────────────────────── + +||| Soundness: a passing gate yields evidence for every hard clause. +export +hardGateSound : (fs : List Fact) -> (wm : WMap) -> (cs : List Clause) + -> hardGate fs wm cs = True -> GateEvidence fs wm cs +hardGateSound fs wm [] _ = Done +hardGateSound fs wm (c :: cs) prf with (isHard (verb c)) proof h + _ | False = Soft h (hardGateSound fs wm cs prf) + _ | True with (passes (classify fs wm c)) proof p + _ | True = Hard h (resolveSound fs wm c p) (hardGateSound fs wm cs prf) + _ | False = absurd prf + +||| Completeness: evidence for every hard clause makes the gate pass. +export +hardGateComplete : (fs : List Fact) -> (wm : WMap) -> (cs : List Clause) + -> GateEvidence fs wm cs -> hardGate fs wm cs = True +hardGateComplete fs wm [] Done = Refl +hardGateComplete fs wm (c :: cs) (Hard h r rest) = + rewrite h in rewrite resolveComplete fs wm c r in hardGateComplete fs wm cs rest +hardGateComplete fs wm (c :: cs) (Soft h rest) = + rewrite h in hardGateComplete fs wm cs rest + +-- ── Worked example (the template's real must.anchor-clause witness) ───────── --- ─────────────────────────────────────────────────────────────────────────── --- Worked example + machine-checked proof of the central property. --- (`idris2 --check` passing IS the proof: the `failing` block must NOT compile.) --- ─────────────────────────────────────────────────────────────────────────── +exampleFacts : List Fact +exampleFacts = [ MkFact "anchor.authority" "hyperpolymath/standards" True ] -exampleClauses : Vect 2 SomeClause -exampleClauses = [ (Must ** MkClause "must.license-present" Must) - , (Adjust ** MkClause "adjust.placeholder-drift" Adjust) ] +exampleMap : WMap +exampleMap = [ ("must.anchor-clause", Descriptile [MkSpec "anchor.authority" Present]) ] -exampleFact : SomeFact -exampleFact = (STATE ** MkFact "state.status" STATE) +exampleClauses : List Clause +exampleClauses = [ MkClause "must.anchor-clause" Must False + , MkClause "adjust.placeholder-drift" Adjust False ] -||| A VALID total covering: the Must clause is witnessed; the Adjust clause is -||| allowed to gap. This typechecks. -exampleCoverage : TotalCoverage Coaptation.exampleClauses -exampleCoverage FZ = IsWitnessed exampleFact (Attests _ exampleFact) -exampleCoverage (FS FZ) = IsGap AdjustMayGap +||| The gate passes, so evidence exists, and it names the real fact. +exampleEvidence : GateEvidence Coaptation.exampleFacts Coaptation.exampleMap Coaptation.exampleClauses +exampleEvidence = hardGateSound _ _ _ Refl --- PROOF that an unwitnessed Must is rejected: gapping position 0 (the Must clause) --- has no `MayGap (Must ** _)` to offer, so this body cannot typecheck. The `failing` --- block asserts exactly that — if it ever DID compile, the build would break. -failing - unwitnessedMustIsATypeError : TotalCoverage Coaptation.exampleClauses - unwitnessedMustIsATypeError FZ = IsGap AdjustMayGap -- needs MayGap (Must**_): impossible - unwitnessedMustIsATypeError (FS FZ) = IsGap AdjustMayGap +-- A Must clause whose fact is missing has no witness: `Present` on the +-- absent default fact is False, so the gate is False and `Refl` cannot prove +-- it True. The expected error names the mismatch. +failing "Mismatch between: True and False" + missingFactFailsGate : hardGate [] Coaptation.exampleMap Coaptation.exampleClauses = True + missingFactFailsGate = Refl diff --git a/.machine_readable/coaptation/extract-facts.sh b/.machine_readable/coaptation/extract-facts.sh index f0f40f8..fe8c914 100755 --- a/.machine_readable/coaptation/extract-facts.sh +++ b/.machine_readable/coaptation/extract-facts.sh @@ -12,7 +12,10 @@ # fields that can bear witness to contractile obligations into one # deterministic JSON document. Fact IDs keep their old family prefixes # (clade., state., ecosystem., agentic.) so witness-map.ncl and coapt.ncl -# address them unchanged. +# address them unchanged. The (neurosym …) and (playbook …) clauses, which +# canon names as descriptile carriers alongside (agentic …), emit neurosym. +# and playbook. facts the same way. Every prefix is a constructor of `Family` +# in core/Coaptation.idr, lower-cased. # # READER only — authors nothing; the deed remains the single source of truth. # @@ -60,7 +63,7 @@ read_clauses() { local c bash "$READ" "$DEED" '' canonical-name bash "$READ" "$DEED" '' repo-uuid - for c in identity clade lineage forges status maturity ecosystem agentic; do + for c in identity clade lineage forges status maturity ecosystem agentic neurosym playbook; do bash "$READ" --clause "$DEED" "$c" || [ "$?" -eq 1 ] || return 2 done } @@ -77,7 +80,8 @@ fact() { emit "$id" "$v" } -# The uuid is derived from the header :repo-uuid name, never stored (deed.abnf). +# The repo id: the opaque #uuid body of the header :repo-uuid, read as written +# (standards A1 V8, A7 J11); deed-field.sh --uuid derives only legacy literals. uuid_name="$(field '' repo-uuid)" uuid="" [ -z "$uuid_name" ] || uuid="$(bash "$READ" --uuid "$DEED")" @@ -104,6 +108,14 @@ rows="$( fact 'agentic.require-evidence-per-step' field agentic/integrity require-evidence-per-step fact 'agentic.release-claim-requires-hard-pass' field agentic/integrity release-claim-requires-hard-pass fact 'agentic.default-mode' field agentic/methodology default-mode + # --- the meaning of operations / scan posture: (neurosym) --- + fact 'neurosym.scan-enabled' field neurosym/hypatia-config scan-enabled + fact 'neurosym.scan-depth' field neurosym/hypatia-config scan-depth + fact 'neurosym.report-format' field neurosym/hypatia-config report-format + # --- how permitted actions run: (playbook) --- + fact 'playbook.skeleton-version' field playbook/rsr-repo-skeleton skeleton-version + fact 'playbook.authority-allowlist' field playbook/rsr-repo-skeleton authority-allowlist + fact 'playbook.enforcement-workflow' field playbook/rsr-repo-skeleton enforcement-workflow # --- (anchor): semantic authority + golden path --- fact 'anchor.authority' field anchor authority fact 'anchor.policy' field anchor/semantic-authority policy diff --git a/.machine_readable/coaptation/receipts/latest.toml b/.machine_readable/coaptation/receipts/latest.toml index c49c093..3715515 100644 --- a/.machine_readable/coaptation/receipts/latest.toml +++ b/.machine_readable/coaptation/receipts/latest.toml @@ -10,9 +10,9 @@ band = "amber" proposed-action = "advisory — soft drift within bands (posture/intend). Open an advisory issue; no re-anchor." [coverage] -clauses-total = 52 +clauses-total = 54 descriptile-witnessed = 1 -probe-deferred-to-hunt = 26 +probe-deferred-to-hunt = 28 must-trust-unmeasured-gaps = 0 note = "Yard sees descriptile evidence only; probe-deferred obligations need a Hunt-tier run for a full hard-gate." @@ -21,7 +21,7 @@ grade = "boolean_gate / boolean_gate_provenance" witnessed = 1 refuted = 0 unmeasured-gaps = 0 -probe-deferred = 26 +probe-deferred = 28 gate = "pass" [reading.adjust] @@ -53,6 +53,8 @@ intend.formal-verification = "wish:declared" intend.ecosystem-visualization = "wish:declared" must.license-present = "probe-deferred" must.readme-present = "probe-deferred" +must.spdx-headers = "probe-deferred" +must.toolchain-matches-language = "probe-deferred" must.security-policy = "probe-deferred" must.repo-deed = "probe-deferred" must.governance-docs = "probe-deferred" @@ -98,5 +100,5 @@ bust.sync-drift-between-repos = "latent" bust.contractile-parse-error = "latent" [provenance] -contractiles = "intend@feaaa58c4690 must@6a15dd3ccc3a trust@71566e6b64fc adjust@d7e4225fe5a8 dust@448489330834 bust@ea93d531c781" -descriptiles = "deed@ab944221ee82 anchor@51194a4e21e8" +contractiles = "intend@53c58b12670b must@a5104687b244 trust@1b3a747ddcb0 adjust@cfd661debafd dust@a3de1d6db05d bust@72320ddbc891" +descriptiles = "deed@6860d7e13310 anchor@51194a4e21e8" diff --git a/.machine_readable/contractiles/README.adoc b/.machine_readable/contractiles/README.adoc index d033cd6..49a6ee8 100644 --- a/.machine_readable/contractiles/README.adoc +++ b/.machine_readable/contractiles/README.adoc @@ -150,16 +150,16 @@ enforces or validates concern declarations. k9 provides three trust-tier |=== | File | Trust tier | Description -| `../self-validating/template-kennel.k9.ncl` +| `../self-validating/template-kennel.k9.ncl.in` | Kennel | Pure data. No subprocess, no filesystem write, no network. Safe for metadata and declarative settings. -| `../self-validating/template-yard.k9.ncl` +| `../self-validating/template-yard.k9.ncl.in` | Yard | Nickel evaluation with contracts and validation. No side effects. -| `../self-validating/template-hunt.k9.ncl` +| `../self-validating/template-hunt.k9.ncl.in` | Hunt | Full execution surface. Must declare side effects, support dry-run, and be signed before the estate treats it as trustworthy automation. @@ -167,7 +167,7 @@ enforces or validates concern declarations. k9 provides three trust-tier The templates live in `.machine_readable/self-validating/`. Each verb's `.k9.ncl` instantiates the Hunt tier's shape; it takes its `pedigree` -contract from `_base.ncl` (the old `../k9/template-hunt.k9.ncl` import named +contract from `_base.ncl` (the old `../k9/template-hunt.k9.ncl.in` import named a path that no longer exists). === Why the naming rule does not apply diff --git a/.machine_readable/contractiles/adjust/adjust.k9.ncl b/.machine_readable/contractiles/adjust/adjust.k9.ncl index 8fb43b7..2e6d187 100644 --- a/.machine_readable/contractiles/adjust/adjust.k9.ncl +++ b/.machine_readable/contractiles/adjust/adjust.k9.ncl @@ -22,11 +22,23 @@ K9! # erosion causing gradual parameter drift). Where must flags "broken # now", adjust flags "drifting toward broken". +# +# 2026-10-19 (K9 contract v1.0.0, D173, standards#1058): this record is a +# DECLARATION evaluated at 'Yard. The probes it lists are run by the paired +# runner (adjust.ncl and the scripts/run-*.sh runners), which is the execution +# surface; this file spawns nothing. A 'Hunt record needs signature_required, +# a signature block and a verified signature (K9-S008/S009/C001); no +# contractile carries one, so 'Hunt here was a claim the gate could never honour. + let base = import "../_base.ncl" in { pedigree = base.pedigree_schema & { contractile_verb = "adjust", + schema_version = "1.0.0", + component_type = "contractile:adjust", + semantics = "drift tolerances + corrective actions", + side_effects = [], paired_xfile = "../adjust/adjust.k9.ncl#declaration", paired_runner = "../adjust/adjust.ncl", @@ -47,7 +59,7 @@ let base = import "../_base.ncl" in trust_level = "tolerance measurement + declared auto-fix", allow_network = false, allow_filesystem_write_conditional = true, # auto_fix_when_available may edit - allow_subprocess = true, + allow_subprocess = false, # the paired runner spawns; this record does not probe_scope = 'measurement_plus_declared_fix, }, diff --git a/.machine_readable/contractiles/bust/bust.k9.ncl b/.machine_readable/contractiles/bust/bust.k9.ncl index 5ee972c..c6ab191 100644 --- a/.machine_readable/contractiles/bust/bust.k9.ncl +++ b/.machine_readable/contractiles/bust/bust.k9.ncl @@ -23,15 +23,27 @@ K9! # past their expiry), and the "it works, ship it" pattern where a # caller silently starts using a must-not-run API. +# +# 2026-10-19 (K9 contract v1.0.0, D173, standards#1058): this record is a +# DECLARATION evaluated at 'Yard. The probes it lists are run by the paired +# runner (bust.ncl and the scripts/run-*.sh runners), which is the execution +# surface; this file spawns nothing. A 'Hunt record needs signature_required, +# a signature block and a verified signature (K9-S008/S009/C001); no +# contractile carries one, so 'Hunt here was a claim the gate could never honour. + let base = import "../_base.ncl" in { pedigree = base.pedigree_schema & { contractile_verb = "bust", + schema_version = "1.0.0", + component_type = "contractile:bust", + semantics = "hard-stop / expiry / must-not-run declarations", + side_effects = [], paired_xfile = "../bust/bust.k9.ncl#declaration", paired_runner = "../bust/bust.ncl", - tier = 'Hunt, + tier = 'Yard, authority = 'blocking, metadata = { @@ -44,12 +56,12 @@ let base = import "../_base.ncl" in }, security = { - leash = 'Hunt, - signature_required = true, + leash = 'Yard, + signature_required = false, trust_level = "read-only expiry + state-check with subprocess", allow_network = false, allow_filesystem_write = false, - allow_subprocess = true, + allow_subprocess = false, # the paired runner spawns; this record does not probe_scope = 'read_only, }, diff --git a/.machine_readable/contractiles/dust/dust.k9.ncl b/.machine_readable/contractiles/dust/dust.k9.ncl index a78470e..5177676 100644 --- a/.machine_readable/contractiles/dust/dust.k9.ncl +++ b/.machine_readable/contractiles/dust/dust.k9.ncl @@ -25,11 +25,23 @@ K9! # rollback path; anything retired must preserve the evidence of its # previous existence). +# +# 2026-10-19 (K9 contract v1.0.0, D173, standards#1058): this record is a +# DECLARATION evaluated at 'Yard. The probes it lists are run by the paired +# runner (dust.ncl and the scripts/run-*.sh runners), which is the execution +# surface; this file spawns nothing. A 'Hunt record needs signature_required, +# a signature block and a verified signature (K9-S008/S009/C001); no +# contractile carries one, so 'Hunt here was a claim the gate could never honour. + let base = import "../_base.ncl" in { pedigree = base.pedigree_schema & { contractile_verb = "dust", + schema_version = "1.0.0", + component_type = "contractile:dust", + semantics = "rollback / recovery / deprecation / audit-trail preservation", + side_effects = [], paired_xfile = "../dust/dust.k9.ncl#declaration", paired_runner = "../dust/dust.ncl", @@ -53,7 +65,7 @@ let base = import "../_base.ncl" in # execute declared rollback/removal — but only behind explicit # --apply flag + per-item approval. Default is dry-run. allow_filesystem_write_conditional = true, - allow_subprocess = true, + allow_subprocess = false, # the paired runner spawns; this record does not destructive_action_gating = { default_mode = 'dry_run, requires_flag = "--apply", diff --git a/.machine_readable/contractiles/intend/intend.k9.ncl b/.machine_readable/contractiles/intend/intend.k9.ncl index 6025831..95265f8 100644 --- a/.machine_readable/contractiles/intend/intend.k9.ncl +++ b/.machine_readable/contractiles/intend/intend.k9.ncl @@ -28,21 +28,33 @@ K9! # * Evidence sinks: VeriSimDB (queryable) + descriptiles/drift_praxis.deed (repo-local). # * Failure-mode defenses cross-referenced to the AI failure catalog. +# +# 2026-10-19 (K9 contract v1.0.0, D173, standards#1058): this record is a +# DECLARATION evaluated at 'Yard. The probes it lists are run by the paired +# runner (intend.ncl and the scripts/run-*.sh runners), which is the execution +# surface; this file spawns nothing. A 'Hunt record needs signature_required, +# a signature block and a verified signature (K9-S008/S009/C001); no +# contractile carries one, so 'Hunt here was a claim the gate could never honour. + let base = import "../_base.ncl" in { pedigree = base.pedigree_schema & { contractile_verb = "intend", + schema_version = "1.0.0", + component_type = "contractile:intend", + semantics = "north-star (commitments + aspirations)", + side_effects = [], paired_xfile = "../intend/intend.k9.ncl#declaration", paired_runner = "../intend/intend.ncl", # α two-axis declaration — capability × authority. - # intend is Hunt-capable (probes shell out) but reporting-authority - # (never blocks). must/trust/bust will declare (Hunt, blocking); + # intend is Yard-tier as a record (intend.ncl shells out for the probes) + # and reporting-authority (never blocks). must/trust/bust declare (Yard, blocking); # adjust/dust will declare (Yard, advisory). Splitting the axes # means "I'm Hunt-tier so I can override everything" is structurally # impossible — authority is a separate field. - tier = 'Hunt, + tier = 'Yard, authority = 'reporting, metadata = { @@ -59,12 +71,12 @@ let base = import "../_base.ncl" in }, security = { - leash = 'Hunt, - signature_required = true, + leash = 'Yard, + signature_required = false, trust_level = "subprocess + filesystem-read", allow_network = false, allow_filesystem_write = false, # evidence sinks are indirected - allow_subprocess = true, + allow_subprocess = false, # the paired runner spawns; this record does not }, # Trident manifest — folded in from the retired .manifest.a2ml. @@ -101,7 +113,14 @@ let base = import "../_base.ncl" in # Read by .machine_readable/coaptation/extract-clauses.sh. # ------------------------------------------------------------------- declaration = { - preamble = "# SPDX-License-Identifier: MPL-2.0\n# Intentfile — north-star contractile for sholes\n# Author: Jonathan D.A. Jewell \n#\n# Paired runner: intend.ncl\n# Verb: intend\n#\n# Semantics: North-star contractile. Declares BOTH concrete committed\n# next-actions AND horizon aspirations the project wishes to\n# become. Two sections share one file because they answer\n# the same question at different ranges:\n# [[intents]] — \"we WILL do this; track progress\"\n# status: declared → in_progress → done |\n# deferred | retired\n# [[wishes]] — \"we WISH this were true; revisit later\"\n# status: declared → in_progress → achieved |\n# abandoned\n# grouped by horizon: near / mid / far.\n# Non-gating — this is a report, not a gate. See the `must`\n# contractile for hard gates.\n", + preamble = "# SPDX-License-Identifier: MPL-2.0\n# Intentfile — north-star contractile for sholes\n# Author: Jonathan D.A. Jewell \n#\n" + ++ "# Paired runner: intend.ncl\n# Verb: intend\n#\n# Semantics: North-star contractile. Declares BOTH concrete committed\n" + ++ "# next-actions AND horizon aspirations the project wishes to\n# become. Two sections share one file because they answer\n" + ++ "# the same question at different ranges:\n# [[intents]] — \"we WILL do this; track progress\"\n" + ++ "# status: declared → in_progress → done |\n# deferred | retired\n" + ++ "# [[wishes]] — \"we WISH this were true; revisit later\"\n# status: declared → in_progress → achieved |\n" + ++ "# abandoned\n# grouped by horizon: near / mid / far.\n" + ++ "# Non-gating — this is a report, not a gate. See the `must`\n# contractile for hard gates.\n", abstract = "North-star contractile for sholes. This repository is the\ncanonical template for Rhodium Standard Repository compliance. It provides\nthe scaffold that all hyperpolymath repos should copy and customize.", prose = [ { diff --git a/.machine_readable/contractiles/must/must.k9.ncl b/.machine_readable/contractiles/must/must.k9.ncl index f770d16..b0d36e3 100644 --- a/.machine_readable/contractiles/must/must.k9.ncl +++ b/.machine_readable/contractiles/must/must.k9.ncl @@ -28,18 +28,30 @@ K9! # fabrication of success "facts" — invariants ground truth against # marketing copy) and D1 (lore fabrication about what the repo contains). +# +# 2026-10-19 (K9 contract v1.0.0, D173, standards#1058): this record is a +# DECLARATION evaluated at 'Yard. The probes it lists are run by the paired +# runner (must.ncl and the scripts/run-*.sh runners), which is the execution +# surface; this file spawns nothing. A 'Hunt record needs signature_required, +# a signature block and a verified signature (K9-S008/S009/C001); no +# contractile carries one, so 'Hunt here was a claim the gate could never honour. + let base = import "../_base.ncl" in { pedigree = base.pedigree_schema & { contractile_verb = "must", + schema_version = "1.0.0", + component_type = "contractile:must", + semantics = "invariant assertion — release-blocking", + side_effects = [], paired_xfile = "../must/must.k9.ncl#declaration", paired_runner = "../must/must.ncl", - # α two-axis: Hunt tier (subprocess for grep/test/etc.) but - # restricted to read-only operations. Blocking authority because + # α two-axis: Yard tier (the runner shells out for grep/test/etc.; + # this record only declares) and read-only operations. Blocking authority because # must is the canonical gating verb. - tier = 'Hunt, + tier = 'Yard, authority = 'blocking, metadata = { @@ -52,12 +64,12 @@ let base = import "../_base.ncl" in }, security = { - leash = 'Hunt, - signature_required = true, + leash = 'Yard, + signature_required = false, trust_level = "read-only invariant verification with subprocess", allow_network = false, allow_filesystem_write = false, - allow_subprocess = true, + allow_subprocess = false, # the paired runner spawns; this record does not probe_scope = 'read_only, # must probes NEVER mutate probe_kinds_allowed = [ 'file_existence, @@ -124,8 +136,8 @@ let base = import "../_base.ncl" in { id = "license-present", section = "File Presence", - description = "LICENSE file must exist", - probe = "test -f LICENSE", + description = "a licence must exist (LICENSE, the forge-facing copy, or LICENSE.adoc)", + probe = "test -f LICENSE || test -f LICENSE.adoc", severity = 'critical, }, { @@ -135,6 +147,27 @@ let base = import "../_base.ncl" in probe = "test -f README.adoc", severity = 'critical, }, + { + # The SPDX gate used to be a fixed glob (*.rs, *.res, *.gleam) with a + # `head -20` cap. In a Julia/Elixir/Idris2/Zig/OCaml/shell repository it + # matched NOTHING, counted 0 missing, and reported PASS — a check that + # examined nothing, reporting coverage. scripts/check-spdx-headers.sh + # derives the extension set from the languages the repository declares + # and fails when it matched zero files, so this probe can only pass by + # actually inspecting the tree. + id = "spdx-headers", + section = "Licensing", + description = "Every source file of every declared language carries an SPDX header", + probe = "bash scripts/check-spdx-headers.sh --quiet", + severity = 'critical, + }, + { + id = "toolchain-matches-language", + section = "Toolchain", + description = "mise.toml declares the detected languages' tools, and no banned or foreign tool", + probe = "bash scripts/check-mise-language.sh --quiet", + severity = 'critical, + }, { id = "security-policy", section = "File Presence", @@ -149,6 +182,21 @@ let base = import "../_base.ncl" in probe = "ls *_chora.deed >/dev/null 2>&1", severity = 'critical, }, + { + # Yard cannot test a file's existence (Nickel evaluation does no I/O, + # K9 contract v1.0.0), and a Hunt record needs a verified signature, so + # the invariant is DECLARED here and the paired runner runs the probe, + # as for every must invariant. The probe is the same script CI runs + # (estate-rules.yml), so the two cannot disagree. It checks the deed's + # (documents) registry (each id well-formed and unique, each path present + # unless :removed-at-mint #t) and that no tracked .adoc/.md links to a + # missing file, apart from the reviewed internal-links-allow.txt. + id = "internal-links-resolve", + section = "Documentation", + description = "every deed-registered document id resolves to its path, and no tracked doc links to a missing file", + probe = "bash scripts/check-internal-links.sh .", + severity = 'critical, + }, { id = "governance-docs", section = "File Presence", diff --git a/.machine_readable/contractiles/trust/trust.k9.ncl b/.machine_readable/contractiles/trust/trust.k9.ncl index 003633b..ae27a65 100644 --- a/.machine_readable/contractiles/trust/trust.k9.ncl +++ b/.machine_readable/contractiles/trust/trust.k9.ncl @@ -44,21 +44,33 @@ K9! # * Failure-mode defenses cross-referenced — trust carries the most # defenses of any verb because the threat surface is widest. +# +# 2026-10-19 (K9 contract v1.0.0, D173, standards#1058): this record is a +# DECLARATION evaluated at 'Yard. The probes it lists are run by the paired +# runner (trust.ncl and the scripts/run-*.sh runners), which is the execution +# surface; this file spawns nothing. A 'Hunt record needs signature_required, +# a signature block and a verified signature (K9-S008/S009/C001); no +# contractile carries one, so 'Hunt here was a claim the gate could never honour. + let base = import "../_base.ncl" in { pedigree = base.pedigree_schema & { contractile_verb = "trust", + schema_version = "1.0.0", + component_type = "contractile:trust", + semantics = "security + provenance + safe-hacking", + side_effects = [], paired_xfile = "../trust/trust.k9.ncl#declaration", paired_runner = "../trust/trust.ncl", # α two-axis declaration — capability × authority. - # trust is Hunt-capable (active probes shell out, safe-hacking section - # runs real fuzz/injection/auth-bypass attempts scoped to the repo) + # trust is Yard-tier as a record (the runner, trust.ncl, shells out for the + # active probes and the safe-hacking attempts scoped to the repo) # AND blocking-authority (failed verification = failed CI). # Contrast with intend = (Hunt, reporting). The two verbs exercise # the full α surface. - tier = 'Hunt, + tier = 'Yard, authority = 'blocking, metadata = { @@ -71,12 +83,12 @@ let base = import "../_base.ncl" in }, security = { - leash = 'Hunt, - signature_required = true, + leash = 'Yard, + signature_required = false, trust_level = "verification + authorised-probe + hard-gate", allow_network = false, # verifications offline by default allow_filesystem_write = false, # evidence sinks are indirected - allow_subprocess = true, + allow_subprocess = false, # the paired runner spawns; this record does not authorised_probes_only = true, # probe section explicitly lists allowed targets + probe classes probe_scope_enforcement = 'this_repo_only, # probes NEVER hit external systems }, @@ -184,9 +196,14 @@ let base = import "../_base.ncl" in { id = "container-images-pinned", section = "Container Security", - description = "Containerfile uses pinned base images", - probe = "test ! -f Containerfile || grep -q 'cgr.dev\\|@sha256:' Containerfile", - severity = 'warning, + description = "Every base image in a shipped Containerfile is pinned by digest", + # The old probe was: test ! -f Containerfile || grep -q 'cgr.dev\|@sha256:' Containerfile + # which passes on `FROM cgr.dev/chainguard/wolfi-base:latest` — it asked + # "is one of the approved registries named anywhere", not "is every base + # image pinned". A template shipping two floating :latest stages passed + # it in every repo minted from it. The probe now runs the shipped check. + probe = "bash scripts/check-container-pins.sh --quiet", + severity = 'critical, }, { id = "no-dockerfile", diff --git a/.machine_readable/internal-links-allow.txt b/.machine_readable/internal-links-allow.txt new file mode 100644 index 0000000..ecad463 --- /dev/null +++ b/.machine_readable/internal-links-allow.txt @@ -0,0 +1,8 @@ +# Reviewed allowances for scripts/check-internal-links.sh. +# Format: | +# An entry must still be missing and still be linked, or the check fails: the +# list only shrinks. Reasons are mandatory. +build/.github/SECURITY.md | build/docs-seed/ is copied into docs/ by just repo-init; the link is written for its minted home (docs/ -> ../.github/SECURITY.md) and cannot resolve from the seed directory +docs/decisions/NNNN-title.md | docs/decisions/0000-template.adoc is a template: NNNN-title is the placeholder for the next decision record's name +.github/SECURITY-ACKNOWLEDGMENTS.md | genuine dead link: the acknowledgments page was never written; needs an owner decision (write it or drop the sentence), out of scope for the stale-link fix +docs/onboarding/INSTALL-SECURITY-REPORT.adoc | genuine dead link: the scan-report page does not exist in the template; needs an owner decision (drop the line or add the page), out of scope for the stale-link fix diff --git a/.machine_readable/mint-verbatim.txt b/.machine_readable/mint-verbatim.txt new file mode 100644 index 0000000..e508066 --- /dev/null +++ b/.machine_readable/mint-verbatim.txt @@ -0,0 +1,39 @@ +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# mint-verbatim.txt — files `just repo-init` carries into a child UNCHANGED. +# +# These are the mint's own machinery: the generator, and the tests whose +# fixtures must keep the template's literal name, its brace tokens or its +# instruction-block marker, because those fixtures are the INPUT the test feeds +# the generator. No rewrite pass touches them (placeholder substitution, the +# instruction-block strip, the self-name pass), and neither completeness check +# reads them, since an unrendered fixture is not a half-minted file. +# +# Measured minting metadatastician/lintel (2026-10-14): the self-name pass +# rewrote self_name_pass_test.sh's inputs to `lintel`, and the test then +# FAILED in the child; the strip pass removed mint_cleanup_test.sh's fixture +# block although the leftover check exempted that very file. On 2026-10-20 a +# fresh mint of main aborted outright, because julia_library_test.sh's +# PACKAGE_UUID brace-token fixture read as an unfilled token. +# +# Read by build/just/repo-init.just (mint_files) and by +# scripts/check-no-placeholders.sh. One repository-relative path per line; `#` +# starts a comment. A listed path that does not exist stops the mint: a stale +# entry is a hole, not a no-op. + +build/just/repo-init.just # the generator itself +scripts/strip-instruction-blocks.rs # names the marker it strips +scripts/resolve-template-pin.sh # documents the template it resolves +tests/e2e/template_instantiation_test.sh # token answer list; marker exemptions +tests/e2e/use_template_mint_test.sh # mints a template copy: template literals +tests/e2e/chain_mint_test.sh # chain fixtures: parent names and paths +tests/workflows/mint_cleanup_test.sh # instruction-block fixture +tests/workflows/self_name_pass_test.sh # template-name fixtures +tests/workflows/template_conformance_test.sh # template-slug fixtures +tests/workflows/julia_library_test.sh # PACKAGE_UUID brace-token fixture +tests/workflows/mint_gates_test.sh # names an unanswered token, on purpose +tests/e2e/language_profiles_mint_test.sh # minted-tree fixtures; keeps archetype paths +tests/workflows/resolve_template_pin_test.sh # template-slug fixtures +tests/ffi_strings_test.sh # FFI token fixture, filled in a scratch copy +tests/workflows/container_kyaml_test.sh # container token fixtures (template only) diff --git a/.machine_readable/policies/README.adoc b/.machine_readable/policies/README.adoc index 57ea33a..974736b 100644 --- a/.machine_readable/policies/README.adoc +++ b/.machine_readable/policies/README.adoc @@ -1,3 +1,24 @@ // SPDX-License-Identifier: CC-BY-SA-4.0 // Copyright (c) Jonathan D.A. Jewell = policies Registry + +Machine-readable policies. Each file states a rule the repository is checked +against; each has a script that refuses a violation and a test that proves the +script fires. + +[cols="1,1,2"] +|=== +|File |Checked by |What it states + +|`hypatia-rule-order.json` +|`scripts/check-hypatia-rule-order.sh` +|The rank order of Hypatia's suppression layers, which workflow owns which +concern, the clash resolutions (`C1`–`C8`), and the pins the order was written +against. Prose: `docs/HYPATIA-RULE-ORDER.adoc`. + +|=== + +Adding a policy file means adding three things: the policy, the checker that +refuses a violation of it, and a lane in `scripts/run-proven-suite.sh` (with a +Silence + Firing test under `tests/workflows/`) so the checker itself cannot +stop working unnoticed. diff --git a/.machine_readable/policies/hypatia-rule-order.json b/.machine_readable/policies/hypatia-rule-order.json new file mode 100644 index 0000000..d6f5375 --- /dev/null +++ b/.machine_readable/policies/hypatia-rule-order.json @@ -0,0 +1 @@ +{"SPDX-License-Identifier":"MPL-2.0","clashes":[{"id":"C1","resolution":"single producer; scripts/check-workflow-edges.sh fails on a dead edge","summary":"one scanner, two workflows"},{"id":"C2","resolution":"one pin per tool per repository; the verdict job names the producer's commit","summary":"one tool, two pins"},{"id":"C3","resolution":"panicbot stays unenrolled; the grid's own row is the authority","summary":"panicbot versus the direct panic-attack row"},{"id":"C4","resolution":"every fragment must end on a path boundary","summary":"substring fragments suppress more than they name"},{"id":"C5","resolution":"subsumed entries are refused","summary":"a broad entry makes narrower ones dead"},{"id":"C6","resolution":"the named path must exist in the tree","summary":"an exemption outlives the file it names"},{"id":"C7","resolution":"stated, not worked around; un-suppression is an upstream change","summary":"a repository cannot narrow a built-in default"},{"id":"C8","resolution":"producers own their gates; a failed fleet is orange rows, not a block","summary":"the reporter must not re-gate"}],"concerns":[{"id":"hypatia-execution","owner":".github/workflows/hypatia-scan.yml","rationale":"Two workflows built and ran the same scanner at the same pin (clash C1)."},{"id":"hypatia-gate","owner":".github/workflows/hypatia-scan.yml","rationale":"The producer owns its gate; the verdict grid is not a gate (clash C8)."},{"id":"panic-attack-gate","owner":".github/workflows/static-analysis-gate.yml","rationale":"Blocks on critical exactly once, in the workflow that runs it."},{"id":"pons-asinorum","owner":".github/workflows/static-analysis-gate.yml","rationale":"Advisory by design: pons classifies evidence, it does not prove."},{"id":"verdict-grid-render","owner":".github/workflows/fork-governance.yml","rationale":"The reporter collects evidence and never scans (clash C8)."},{"id":"verdict-grid-comment","owner":".github/workflows/verdict-grid-publish.yml","rationale":"Only the trusted default-branch workflow_run publisher may write the single bot-owned verdict comment; PR rendering remains read-only."},{"id":"fleet-report-backs","owner":".github/workflows/fork-governance.yml","rationale":"The fleet job is the only producer of .gitbot-fleet evidence."},{"id":"exemption-policy","owner":".hypatia-ignore","rationale":"One file, checked by scripts/check-hypatia-ignore.sh."}],"grid":{"commit":"f0b3cd4c464d33e1584f8528c17bce104555e256","library":"scripts/lib/verdict-grid.jq","library_sha256":"36e7aa69afbe8c488b1a313fd9bd0cf2bf6af45d3f34b80afd793f6b20582896","renderer":"scripts/verdict-grid.sh","renderer_sha256":"7c2cac9248fd249f607de827dc8dc9a3f6276bf9ca662be86aa435e9aeca48d7","repository":"metadatastician/standards","specification":"docs/VERDICT-GRID-SPEC.adoc"},"layer_owners":["hypatia","this-repository","the-gate","the-grid"],"layers":[{"description":"Python, Go, Makefile and Gemfile are refused by a dedicated clause; no exemption reaches it.","id":"rule-total-ban","overrides":"nothing: every other layer is unreachable for this rule","owner":"hypatia","rank":1,"repository_can_change":false,"scope":"cicd_rules/banned_language_file"},{"description":"Applied to every rule before any module-specific table.","id":"universal-excludes","overrides":"every layer below it, for the paths it names","owner":"hypatia","rank":2,"repository_can_change":false,"scope":"vendored and generated paths: .git/, node_modules/, _build/, deps/, target/, dist/, .hypatia-baseline.json"},{"description":"Training corpora and fixtures are provenance, not signal.","id":"builtin-defaults","overrides":"every layer below it; a repository cannot narrow it (clash C7)","owner":"hypatia","rank":3,"repository_can_change":false,"scope":"@training_corpus_paths keyed per module, plus benches/ for code_safety only"},{"description":"Scoped, reasoned exemptions. Fragments are substring matches, so each must end on a path boundary.","id":"repository-ignore","overrides":"nothing above it; it may only widen layer 3","owner":"this-repository","rank":4,"repository_can_change":true,"scope":".hypatia-ignore"},{"description":"Line- or file-scoped. The narrowest layer, and the one to use when only one line is affected.","id":"inline-directive","overrides":"layers 3 and 4, for the line that carries it","owner":"this-repository","rank":5,"repository_can_change":true,"scope":"# hypatia: allow / -- "},{"description":"Applied at gate time only. The verdict grid ignores it, so standing debt stays visible.","id":"baseline","overrides":"the gate's decision, never a scanner's output","owner":"the-gate","rank":6,"repository_can_change":true,"scope":".hypatia-baseline.json"},{"description":"Presentation and grading. It never suppresses a finding.","id":"grid-normalisation","overrides":"nothing; it may not change what a scanner reported","owner":"the-grid","rank":7,"repository_can_change":false,"scope":"severity words, suppressed:true, the row's colour"}],"observed_modules":[{"layer":4,"module":"research_extensions","rationale":"RE001/RE005/RE008 are advisory recommendations for workflows that deliberately hold a credential or render an annotation non-fatally; each exemption is file-scoped."},{"layer":4,"module":"workflow_audit","rationale":"wrong_sha_pin compares against a static May-2026 table; authoritative pin verification is actions.lock plus check-lock-sync.sh, which runs on every pull request."}],"scanner":{"commit":"be98f74ce93df200752f3798efa1305bfa3e0e10","repository":"hyperpolymath/hypatia","sources":["lib/hypatia/scanner_suppression.ex","lib/rules/"]},"schema":"hypatia-rule-order/1"} diff --git a/.machine_readable/required-contexts-allow.txt b/.machine_readable/required-contexts-allow.txt new file mode 100644 index 0000000..dcab0ef --- /dev/null +++ b/.machine_readable/required-contexts-allow.txt @@ -0,0 +1,35 @@ +# SPDX-License-Identifier: MPL-2.0 +# +# Live required status check contexts on default branch (`main`) and the +# workflow files in `.github/workflows/` that produce them on `pull_request`. +# +# Format: => <.github/workflows/file.yml> +# +# Verified by `scripts/check-required-contexts.sh` (3-outcome 0/1/2) so a +# renamed or path-filtered workflow can never silently strand pull requests +# behind an unsatisfiable ruleset check (issue #219 class). +# +# All three contexts come from ONE workflow and are ordinary job names, not the +# ` / ` pairs a job-level reusable call would produce: +# +# * `scan / gitleaks` is the historic headline context for the +# `Secret-Scan-Floor` ruleset (24309812). NOTE: as of 2026-11-08 that +# ruleset reads `rules: []` and enforces nothing on `main`, so this context +# is currently PRODUCED but not REQUIRED. Do not describe it as required +# without re-reading the live ruleset. +# * `scan / rust-secrets` and `scan / shell-secrets` are produced by the same +# workflow and are listed here so that (a) the gate certifies that every +# generated repository really starts all three scanner jobs, and (b) turning +# any of them on in a ruleset needs no mapping edit. Listing a produced +# context is not the same as requiring it: this file is a producer map, and +# the empty `required_status_checks` in `.github/rulesets/base.json` and in +# `.github/settings.yml` is still what keeps the floor where the owner left +# it. +# +# A context here MUST be a job `name:` (or job id) in its workflow. A remote +# reusable-workflow call produces nothing this gate can certify, which is why +# `.github/workflows/secret-scanner.yml` runs its three scanners inline instead +# of wrapping them in a single reusable call. +scan / gitleaks => .github/workflows/secret-scanner.yml +scan / rust-secrets => .github/workflows/secret-scanner.yml +scan / shell-secrets => .github/workflows/secret-scanner.yml diff --git a/.machine_readable/root-allow.txt b/.machine_readable/root-allow.txt index bf694a6..06f039d 100644 --- a/.machine_readable/root-allow.txt +++ b/.machine_readable/root-allow.txt @@ -28,7 +28,14 @@ # ─── Baseline: every RSR repo has these ────────────────────────────────────── README.adoc -LICENSE +LICENSE.adoc # the licence (MPL-2.0); renamed from LICENSE to the estate AsciiDoc format 2026-10-26 +?LICENSE # forge-facing copy of LICENSES/MPL-2.0.txt. Optional, not required: + # GitHub (and most forges) only detect LICENSE / LICENSE.md / + # LICENSE.txt to show the licence on the repo page, and readers + # follow that name. LICENSE.adoc above stays authoritative; this + # is a byte-identical copy of the REUSE text, not a second licence. + # Added 2026-10-30 — without it license-present failed and every + # minted repo's link:LICENSE[LICENSE] was a dead link. LICENSES/ # REUSE licence texts, dual-licence model (code MPL-2.0 / docs CC-BY-SA-4.0) CHANGELOG.adoc # AsciiDoc is the estate-standard documentation format CITATION.cff # citation metadata; GitHub reads it from the root of the default branch only @@ -53,14 +60,13 @@ mise.toml # the toolchain: every tool at "latest" (PROVISIONING mise.lock # makes "latest" concrete: version + per-platform checksum; mise reads it beside mise.toml .hypatia-ignore # the Hypatia scanner reads it from the repo root ?.coderabbit.yaml # 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 -.clinerules # AI editor rules. Cline/Cursor/Windsurf read these from the project -.cursorrules # ROOT, so the copies formerly under .machine_readable/ai/ were inert. -.windsurfrules +.clinerules # 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) ?.claude/ # Claude Code project state (checkpoints, history) — created by the tool itself # ─── Directories ───────────────────────────────────────────────────────────── .git/ .github/ # community health + workflows (GitHub reads this path and no other) + versioned git hooks (.github/hooks/, wired via core.hooksPath) +.gitbot-fleet/ # 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 www/ # site-operations bundle; canonical .well-known/ lives at www/.well-known/ (issue #53) .machine_readable/ # manifests, contractiles, policies. Renamed back from machine-readable/ 2026-09-17 by owner ruling, for one canonical spelling estate-wide (census at the 2026-08 divergence: 48 dotted vs 9 hyphenated — the majority was already dotted). See docs/governance/TEMPLATE-LINEAGE-AUDIT.adoc docs/ # human documentation @@ -68,10 +74,10 @@ build/ # build orchestration: just/ phase modules, container ci/ # .gitlab-ci.yml + .pre-commit-config.yaml; ci/README.adoc records the out-of-band GitLab project setting these require scripts/ # repo helper scripts session/ # dispatch.sh, custom-checks.k9.ncl, local-hooks.sh -src/ tests/ # ─── Optional: capability-gated or template-only ───────────────────────────── +?src/ # source tree; optional for non-code/specification/governance repositories (issue #233, e.g. standards) ?archetypes/ # template-only variation seam (ADR-0003); `just repo-init` removes it from minted repos ?.devcontainer/ # VS Code dev container spec; present only where the container capability is declared ?sonar-project.properties # only where the repo is analysed by SonarCloud @@ -82,6 +88,14 @@ tests/ ?CONTRIBUTING.md # accepted at root OR .github/; .github/ is the canonical estate location ?CONTRIBUTING.adoc # estate docs gate (standards scripts/check-docs-presence.sh) requires CONTRIBUTING at the ROOT; this is the copy it verifies ?SECURITY.md # accepted at root OR .github/; likewise +?CODE_OF_CONDUCT.adoc # community health file; GitHub accepts it at root, docs/ or .github/ +?SUPPORT.adoc # community health file; GitHub accepts it at root, docs/ or .github/ ?REQUIRES_INITIALISATION.md # written by the minting process, removed once `just repo-init` runs ?Project.toml # julia-library archetype: Pkg reads the package manifest from the package root only ?test/ # julia-library archetype: Pkg.test runs test/runtests.jl, a fixed path (the spine keeps tests/) +?mix.exs # elixir: Mix reads the project file from the root only, and build/just/provision.just runs mix at the root +?mix.lock # elixir: Mix writes the dependency lock beside mix.exs +?.formatter.exs # elixir: `mix format` reads its config from the project root +?priv/ # elixir/OTP: an application's priv dir is fixed at the project root (Application.app_dir/2) +?Cargo.toml # rust-cli archetype: Cargo reads the package manifest from the package root only; the overlay mints it from Cargo.toml.in +?Cargo.lock # rust-cli archetype: `just repo-init` generates it (cargo generate-lockfile) because the minted CI builds with --locked diff --git a/.machine_readable/scripts/maintenance/maint-assault.sh b/.machine_readable/scripts/maintenance/maint-assault.sh index 1e667c0..5136830 100644 --- a/.machine_readable/scripts/maintenance/maint-assault.sh +++ b/.machine_readable/scripts/maintenance/maint-assault.sh @@ -1,7 +1,7 @@ #!/usr/bin/env bash # SPDX-License-Identifier: MPL-2.0 # -# maint-assault.sh — High-rigor stress testing using panic-attacker +# maint-assault.sh — High-rigor stress testing using panic-attack # # This script runs a full assault (static + dynamic) on the project binary # to detect logic-based bug signatures and environmental vulnerabilities. @@ -31,10 +31,10 @@ fi echo "Initiating full assault on $BINARY_NAME..." mkdir -p "$(dirname "$REPORT_PATH")" -"$PA_BIN" assault "target/release/$BINARY_NAME" - --source . - --intensity medium - --duration 10 +"$PA_BIN" assault "target/release/$BINARY_NAME" \ + --source . \ + --intensity medium \ + --duration 10 \ --output "$REPORT_PATH" echo "" diff --git a/.machine_readable/self-validating/README.adoc b/.machine_readable/self-validating/README.adoc index 778ab2e..59d93df 100644 --- a/.machine_readable/self-validating/README.adoc +++ b/.machine_readable/self-validating/README.adoc @@ -51,7 +51,7 @@ Configuration with Nickel contracts for runtime validation. Evaluated safely wit === Hunt Level (Full Execution) -**File:** `examples/setup-repo.k9.ncl` +**File:** `examples/setup-repo.k9.ncl.in` Full execution with Just recipes. Can run shell commands and modify filesystem. @@ -78,7 +78,7 @@ cp .machine_readable/contractiles/k9/examples/project-metadata.k9.ncl config/met cp .machine_readable/contractiles/k9/examples/ci-config.k9.ncl .github/ci.k9.ncl # Hunt: Full automation -cp .machine_readable/contractiles/k9/examples/setup-repo.k9.ncl scripts/setup.k9.ncl +cp .machine_readable/contractiles/k9/examples/setup-repo.k9.ncl.in scripts/setup.k9.ncl ---- === 2. Validate Components @@ -137,9 +137,9 @@ K9 contractiles integrate with other RSR standards: Use these as starting points for your own K9 components: -- `template-kennel.k9.ncl` - Pure data template -- `template-yard.k9.ncl` - Validated config template -- `template-hunt.k9.ncl` - Full execution template +- `template-kennel.k9.ncl.in` - Pure data template +- `template-yard.k9.ncl.in` - Validated config template +- `template-hunt.k9.ncl.in` - Full execution template == Dependencies diff --git a/.machine_readable/self-validating/methodology-guard.k9.ncl b/.machine_readable/self-validating/methodology-guard.k9.ncl index 3c1a106..2f6b781 100644 --- a/.machine_readable/self-validating/methodology-guard.k9.ncl +++ b/.machine_readable/self-validating/methodology-guard.k9.ncl @@ -16,6 +16,7 @@ let methodology_guard = { pedigree = { schema_version = "1.0.0", + component_type = "validator:methodology-guard", metadata = { name = "methodology-guard", version = "1.0.0", diff --git a/.machine_readable/testing/adversarial-content.k9.ncl b/.machine_readable/testing/adversarial-content.k9.ncl new file mode 100644 index 0000000..3374d1d --- /dev/null +++ b/.machine_readable/testing/adversarial-content.k9.ncl @@ -0,0 +1,47 @@ +K9! +# SPDX-License-Identifier: MPL-2.0 +# Adversarial and negative-control test fixtures (proven-tests-and-benches +# Silence + Firing doctrine). Documents why negative test suites name banned +# patterns or feed malformed inputs into gates so human reviewers and scanners +# do not mistake Firing controls for production defects. + +{ + pedigree = { + schema_version = "1.0.0", + component_type = "testing:adversarial-controls", + metadata = { + name = "rsr-adversarial-controls", + version = "0.1.0", + }, + security = { + leash = 'Kennel, + }, + }, + + adversarial_suites = [ + { + path = "tests/proven_suite_test.sh", + purpose = "Generates ephemeral Idris2 escape-hatch mutants and benchmark regressions inside mktemp to prove check-escape-hatches.sh, check-bench-regression.sh, compute-bench-baseline.sh, and emit-aggregate-inputs.sh fire with exact 0/1/2 exit codes.", + }, + { + path = "tests/workflows/check_ijson_jcs_test.sh", + purpose = "Feeds duplicate keys, integers outside +/-(2^53-1), lone UTF-16 surrogates, Unicode noncharacters, and non-JCS formatting into check-ijson-jcs.sh.", + }, + { + path = "tests/workflows/squabble_gate_test.sh", + purpose = "Plants admin-override strings, continue-on-error masks, and phantom ruleset contexts into ephemeral workflow fixtures to prove cicd-squabbler and check-required-contexts.sh fire.", + }, + { + path = "tests/workflows/secret_scanner_contract_test.sh", + purpose = "Mutates the shipped secret-scanner workflow — renames a job, deletes one, adds `secrets: inherit`, adds a secrets.* read, widens the permission grant, unpins an action, retargets push away from the default branch, drops pull_request, drops concurrency, and converts a job to a remote reusable call — to prove the three stable scanner contexts stay this repository's own.", + }, + { + path = "tests/workflows/governance_badge_test.js", + purpose = "Feeds malformed lane artifacts, malformed existing badge files, 401/403/429/5xx responses, a dead API and 409 sha conflicts into scripts/governance-badge.js against a mock GitHub API, and runs the workflow-wiring checks against a mutated workflow, to prove the publisher never publishes a false green and never dedupes a changed badge.", + }, + { + path = "www/tests/controls", + purpose = "Planted open-recursion BIND9, over-broad Caddyfile, and invalid AIBDP status controls.", + }, + ], +} diff --git a/.windsurfrules b/.windsurfrules deleted file mode 100644 index 46b3580..0000000 --- a/.windsurfrules +++ /dev/null @@ -1,52 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -# Authoritative source: docs/practice/AI-CONVENTIONS.adoc - -# STARTUP: Read the repo deed (*_chora.deed at the repo root) first, then docs/status/ROADMAP.adoc. - -# LICENSE -# All original code: MPL-2.0. -# Never AGPL-3.0. MPL-2.0 only as platform-required fallback. -# SPDX header required on every source file. -# Copyright: Jonathan D.A. Jewell (hyperpolymath) - -# 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 -# Haskell: unsafeCoerce, unsafePerformIO, undefined, error -# OCaml: Obj.magic, Obj.repr, Obj.obj -# Coq: Admitted -# Lean: sorry -# Rust: transmute (unless FFI with // SAFETY: comment) - -# 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 -# Python -> Julia or Rust - -# CONTAINERS -# Runtime: Podman (never Docker). -# File: Containerfile (never Dockerfile). -# Base: cgr.dev/chainguard/wolfi-base:latest or cgr.dev/chainguard/static:latest. - -# ABI/FFI -# ABI: Idris2 with dependent types (src/interface/abi/). -# FFI: Zig with C ABI (src/interface/ffi/). -# Headers: src/interface/generated/. - -# BUILD: Use just (justfile) for all tasks. -# STYLE: Descriptive names. Document all files. SPDX headers everywhere. diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index 3a2b88c..75a6c04 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -10,6 +10,417 @@ https://semver.org/spec/v2.0.0.html[Semantic Versioning]. ==== Added +* **Chain minting: a minted repo can be minted again.** "Use this template" + on a minted repo now mints correctly (owner ruling 2026-11-04, after the + Codex review of #251 showed the grandchild inherited its parent's identity). + `scripts/chain-mint.sh` replays the parent's mint, mints the same template + commit with the new answers, and carries the parent's own work across with + `git merge-tree`: everything rendered is rendered afresh, the parent's + edits, additions and removals are kept (renamed by the self-name rule and + the narrow self-owner rule, each defined once in repo-init) and declared in + the new `(variant (paths))` by comparing the result with the fresh mint, as + the drift gate does, so an edit carried across an answer-dependent rename + (a Julia entry point) is declared where it lives. Paths stay NUL-delimited, + so a backslash or a leading dash survives, and a file the parent tracks + although an ignore rule matches it is carried. Identity files are held in + git's index, never through the work tree, and a symlink at any path the + chain writes is refused, so a parent-controlled link cannot redirect a + write. Every tree is read from, and the result written back into, the + checkout by git (a scratch index and a two-tree `read-tree -m -u`), never by + tar, so no symlink is followed. The checkout is read and written by its own + git, under its own configuration (a linked worktree's common excludes, + `core.autocrlf`, a global excludesFile, clean and smudge filters); the + replays under none. Every path the result adds is checked on the disk first + and refused by name if anything the parent snapshot does not track is there, + ignored or not: git's own check lets an ignored entry be overwritten + wherever it sees the ignore rule. A sparse checkout, an unresolved merge, or + a tracked path beneath a symlink is refused. A parent's deletion is honoured + across an answer-dependent rename; a type change there is refused by name. + The baselines, and the drift gate, replay with the wrapper at the pin, not + the carried copy, and + the template clone takes no init templates. The result is fixed before the + gates run (what they write is not carried), every file the write changes is + first checked out into scratch with this checkout's filters, and a write + that still fails part-way keeps the objects needed to put it back. The + generator's temporary paths join the symlink guard. A path holding byte 0x01 is refused + like one holding a newline. The deed's (mint-answers) decides that a tree is + a minted repo, so one that added build/templates/identity.deed.in back is + still chain-minted. The carried generators run before the + final measure (their intermediate data is removed before it, and the + declaration settles path by path and category by category), and the result must pass + the child's own gates (placeholders, SPDX, toolchain, container pins, www, + `just verify`) before it is written. A conflict with the new rendering stops + before anything is written. Provenance records the root + template commit plus `:derived-from` the parent. A parent minted before + `(mint-answers)` is still refused. `scripts/replay-mint.sh` is now the one + replay path, shared with the drift gate; only a recorded `(mint-answers)` + supplies its package uuid, so the new side of a chain mint derives its own. +* **An exact drift gate for minted repos: the mint is replayed.** repo-init + records its answers in a `(mint-answers)` deed clause (owner ruling + 2026-11-04: only values it already writes into the child's files; the + recipe checks each value against those files, not the template-only trees + it deletes, and names any it leaves out) + and takes its date from `RSR_MINT_DATE`; a replay also takes the recorded + Julia package uuid, which an ordinary mint always derives. + `scripts/check-mint-drift.sh` re-mints the template at `(provenance :template-commit)` with those answers + and diffs the child against the result, so a fresh mint is green by + construction and each later edit is named. `check-variant-drift.sh` + delegates to it for a minted repo, and stage 8 recommends it again. The + derived files (`CLAUDE.md`, the repository map) are declared diverged at + mint: their own gates keep them fresh. Each side's file set is its tracked + or unignored files (the child's under its own git configuration, as + `git add -A` commits it; the replay's under none), so a force-added build + artefact is still named. The + most specific declaration covering a path decides its category, so a file + declared added under a directory the mint removes is an addition; a path + holding a newline is refused by name. A path declared diverged must be one + the mint produces; `operational-state` stays out of the comparison. The + replay's git runs without user or system configuration or hooks. What a + work tree already held beyond the pinned tree before the mint (an edit, an + untracked file, a deletion) is named by the mint, which then replays itself + from the pinned tree before writing anything and declares in + `(variant (paths))` exactly what the result differs by: the comparison the + drift gate makes, whatever the mint did to a change on the way (moved, + rendered, overwritten, or reached through an edited input). The replay + passes the recorded `RSR_TEMPLATE_SLUG`. A pre-mint change under a root `.well-known/` (which the mint moves), + or a work tree that differs from an asserted template tree this repository + does not hold, is refused before anything is written. The gate clears + inherited git location variables, and writes the pinned tree as a checkout + does (`checkout-index`, never `git archive`, whose `export-ignore` and + `export-subst` would change it), without global git attributes. A pre-mint + file at a path the mint itself writes (the archetype overlay, the docs seed, + the deed), or an edited template file the overlay replaces, is refused, + since the mint would overwrite it; and the mint also dry-runs itself on the + work tree, refusing by name any pre-mint change it would discard (an edit to + the roadmap or `mise.toml`, which it writes whole). repo-init clears any + inherited git location (`GIT_DIR`, `GIT_INDEX_FILE`, …) before it runs, so + neither its replays nor the tests it runs in scratch repositories can commit + into the child; one naming another repository is refused. The replays + receive `STANDARDS_UUID_V8_JS`, and a template tree carrying a submodule + (a gitlink, which a replay cannot reproduce) is refused by name, at the mint + as well, clean or not. A pre-mint change gone from both results (an input + the mint never copies, a file in a directory it deletes) is checked by + minting without it, and refused by name when it has no effect; a path + holding byte 0x01 (the deed reader's record separator) is refused like one + holding a newline. + +==== Changed + +* **Agda proofs use PROOF-POLICY §2.1's invocation.** `scripts/check-proofs.sh + agda` runs `agda --safe --without-K --cubical-compatible`, the canonical + theory invocation (metadatastician/standards `3-practice/PROOF-POLICY.adoc` + §2.1), instead of `agda --safe`. Every repository minted from the template + inherits the gate, so this is the source of the fix that + hyperpolymath/resource-algebra#19 and hyperpolymath/occupancy-types#18 make + to their copies. `Properties.agda` checks under the new flags (Agda 2.6.3, + standard library 1.7.3); the manifest records it. + + +==== Fixed + +* **Mint, drift gate and chain mint: the review findings left open on #275 + and #277.** +** An answer holding byte 0x01, the deed reader's record separator, is + refused before the first write. +** The drift gate and the pre-mint check compare a symlink's target byte for + byte (a trailing newline was stripped) and the execute bit git records + (the owner's), not `-x`, which as root is true for a file only its group + or others may execute. +** The repo uuid is derived the same on every machine + (`scripts/uuid5-url.sh`: sha1sum, shasum or openssl, equal to + `uuidgen --sha1`); without uuidgen it used to be `UNASSIGNED`, which a + replay then reported as drift. `deed-field.sh --uuid` falls back to it. +** A divergent legacy `.well-known/` file is quarantined under the mint + date (`migrate-wellknown-to-www.sh --date`), so a later replay names it + the same. +** Replays keep a file the template tracks although its `.gitignore` + matches it, and refuse a template commit whose checkout does not read + back as its own tree, instead of replaying it inexactly. +** A chain mint holds the parent's original deed name as identity (a parent + that renamed its deed chain-mints), refuses a carried generator that + edits the deed, and fetches a partial clone's pinned files while the + user's git configuration (credentials, `insteadOf`) still applies. +** A minted repo without `scripts/chain-mint.sh` is refused, never minted as + a template. + +* **repo-init follow-ups to #251 (the Codex review it merged before).** +** Re-minting a minted repo silently inherited its parent's author, contacts + and identity (its tokens are filled and `build/templates` is gone). A + minted repo that records `(mint-answers)` is now chain-minted (see Added); + one that does not is refused before writing, naming its template. +** The template identity no longer falls back to the git remote, which in a + template-created child is the child itself. A Justfile without readable + `OWNER :=`/`REPO :=` (now also `export`) needs `RSR_TEMPLATE_SLUG`. +** The self-name pass matches the template name only where no letter or + digit touches it, so a short parent name such as `app` no longer rewrites + "application" into "newlication". +** `resolve-template-pin.sh` pins a root commit by creation time (the + default branch's tip when the child was made) and refuses, listing them, + when several commits share a tree; 29 trees repeat on main. +** `rust-tool.sh` caches each mint tool by the hash of its source, so two + checkouts can no longer run each other's binary. +** Answers go through `sed_rhs`, so `&`, `|` and `\` in a description or name + render literally; an answer with a newline is refused. + +* **`.kyaml` files were invisible to four file scans.** Estate configuration + is `.kyaml` (D307), but these selectors matched only `*.yaml`/`*.yml`: the + invisible-character scan (`scripts/check-invisible-characters.sh`), the + `http://` URL check in `security-policy.yml`, and the VeriSimDB probe in + `dogfood-gate.yml` and `dogfood-summary.yml`. A zero-width character or a + plain-HTTP URL in a `.kyaml` file passed unseen. Each now includes + `*.kyaml`. Ported from `hyperpolymath/panic-attack#246`. +* **The template's gates could not fail, and the toolchain was not minted.** + Reported from JuliaPackageSpitter.jl and traced here; see + `docs/reports/compliance/RSR-TEMPLATE-DAMAGE-2026-10-30.adoc` for the full + investigation and the estate inventory. +** `spdx-headers` globbed `*.rs`/`*.res`/`*.gleam` and capped the scan at 20 + files, so it examined nothing and passed in every Julia, Idris2, Zig, Elixir, + OCaml and shell repository. `scripts/check-spdx-headers.sh` derives the + extension set from the languages the repository declares, scans every match, + and fails when a declared language has no files or when it matched nothing; +** `container-images-pinned` asked whether `cgr.dev` appeared in the + Containerfile, which `FROM cgr.dev/chainguard/wolfi-base:latest` satisfies. + `scripts/check-container-pins.sh` requires a 64-hex digest on every `FROM`; + `scripts/pin-container-digests.sh` writes the pins and refuses a placeholder; +** `mise.toml` was copied from the spine, not rendered, so every mint declared + the template's own toolchain — nine runtimes including Python, which is + banned estate-wide, and not the language of the repository. It is now + rendered from the detected languages by `scripts/render-mise.sh`, and + `scripts/check-mise-language.sh` fails a repository whose declared toolchain + is not the one its languages need; +** `just quality` printed "All quality checks passed!" over verbs that reported + `N/A` and exited 0. It now fails when a verb runs nothing, and the + `julia-library` archetype wires `fmt`, `fmt-check` and `lint` to + `scripts/julia-quality.jl`; +** `build/container/Containerfile` is deleted rather than pinned: two + `FROM …:latest` lines and a body of TODO comments built nothing and failed + `container-images-pinned` in every minted repository, including those that + publish no image. A repository that publishes one adds the file and pins it + (`scripts/pin-container-digests.sh`); `just container-build` says so; +** `archetypes/*/prune.txt` and `scripts/prune-archetype-modules.sh`: an + archetype can remove spine modules its preset does not declare, so a Julia + library no longer inherits a `Containerfile`; +** the mint's `.in` rename covered a hardcoded three-file list; it now covers + the files the applied overlay actually added, so the spine's own `.in` + templates survive; +** `check-no-placeholders.sh` died with exit 1 and no output in a repository + with no `origin` remote (a fresh mint, before the first push): `git config` + exited 1 and `set -e` took the script with it; +** `validate-template.sh` referenced an unset `SCRIPT_DIR` (aborting at Phase 6 + under `set -u`) and demanded `CONTRIBUTING.md` in an estate that writes + `.adoc`. There is now a root `LICENSE` (MPL-2.0), so the Mustfile's + `license-present` and every minted `link:LICENSE[LICENSE]` resolve; +** a pre-write token gate in `repo-init` refuses a mint the recipe cannot answer + for, and four gates now run against the minted tree before handoff; +** `tests/workflows/mint_gates_test.sh` (30 controls) asserts that every gate + fails on a fixture built to fail it; `tests/e2e/language_profiles_mint_test.sh` + (27 controls) mints a Julia package and a Rust CLI and runs the gates on both. + `.github/workflows/quality.yml` gained a `mint-gates` job that runs them. + +* Defects a child inherited, found porting this CI into resource-algebra + (resource-algebra#15, fixed there in resource-algebra#16): +** Secret Scanner: a repository `.gitleaks.toml` replaced the estate + gitleaks baseline in all three passes, so a pull request could pass with + a weaker local config. The baseline now always runs; a local config adds + a second pass; +** `scripts/check-required-contexts.sh` checked a mapped context's workflow + trigger but not that a job with that check-run name exists, so a renamed + job could strand pull requests behind an unproducible required check; a + job with neither `runs-on` nor `uses` produces nothing. A + job that calls a local reusable workflow (one declaring + `on: workflow_call`, directly in `.github/workflows/`, called as `./` or + `$/`, nested at most ten deep, no + cycles) counts as producing + ` / `; one that calls a remote reusable produces + nothing the gate can certify. A literal matrix is expanded as GitHub + names its runs (property names case-insensitive, and only names GitHub + can dereference); a matrix with + include/exclude or computed values is + refused by name, never assumed to match; a matrix caller of a reusable + produces one ` / ` per run; +** `repo-init` and `container-init` filled the container tokens without + reformatting the KYAML, so a fresh child that keeps its containers failed + Estate Rules' "Converted YAML stays KYAML". Both now run + `scripts/format-container-kyaml.sh` after their substitution pass, and check + for a yq that writes KYAML before they write anything (a mint that prunes + `build/container/` needs none), refusing a service name, port or registry + that would break the KYAML they fill or the substitution (a service name + that is a DNS label, since it is also a TOML table key and the backend's + hostname; a registry of a host or a bracketed IPv6 address in RFC 4291 text, an optional port + from 1 to 65535 and lower-case path components, the owner lower-cased in + its default; + `container_kyaml_test.sh` holds the accepted and refused values). yq joins + the base toolchain (`MISE_BASE`, so every rendered `mise.toml`, and the + template's own); `mise.lock` gains its record with `just toolchain-refresh`. + The quick-start docs install the toolchain before `just repo-init` and run + every `just` through `mise exec --` unless mise is activated. Estate Rules + installs its pinned yq before the mint steps, and `use_template_mint_test.sh` + checks the minted configs and that a mint without a KYAML-capable yq stops + untouched; +** `mint-verbatim.txt` did not list `tests/ffi_strings_test.sh` or + `tests/workflows/container_kyaml_test.sh`, token fixtures the placeholder + gate then rejected in a child; +** `tests/ffi_strings_test.sh` named the template's export prefix, so in a + child it called functions that do not exist. It now maps the child's exported + symbols onto the fixture's, and nothing else that shares their prefix. + +* `repo-init` minting a repository created with GitHub's "Use this + template" (measured on metadatastician/lintel, 2026-10-14): +** provenance recorded the CHILD's own HEAD as the template commit. The + commit is now resolved by tree equality against the template's history + (`scripts/resolve-template-pin.sh`), before anything is written, and an + unresolvable tree aborts the mint (`RSR_TEMPLATE_URL`, + `RSR_TEMPLATE_COMMIT`, `RSR_ALLOW_UNPINNED=1` for the exceptions); +** the template's name, owner and deed file are derived from the checkout + (the root Justfile, else `RSR_TEMPLATE_SLUG`; never the git remote, which in + a "Use this template" child names the child), not hardcoded (ported from + lintel#9, which did not merge; its removal of the `[YOUR-REPO-NAME]` deed + seds was not ported, since only they fill it); +** every rewrite pass and completeness check reads one file list: the + repository's own files (`git ls-files`, plus untracked not-ignored), minus + `.machine_readable/mint-verbatim.txt`. The strip pass no longer edits + git-ignored sibling checkouts under `_build/`, nor the fixture tests its + own leftover check exempts; `strip-instruction-blocks.rs` takes files, not + a directory. `check-no-placeholders.sh` reads the same manifest; +** a fresh mint of main aborted on `julia_library_test.sh`'s package-UUID + fixture token; it is now carried verbatim; +** the repository map is generated from the work tree (`gen-repo-map.sh + --worktree`), after the last tree-changing step, so it no longer lists + `archetypes/` and the template's deed name; a path holding a newline, + which the line-based map would split into bogus entries, is refused by + name in both modes; +** stage 8 no longer tells a minted repo to arm `check-variant-drift.sh`, + which a fresh mint cannot pass (101 rendered files differ); it points at + `check-template-conformance.sh`. The (variant) clause now declares the + mint's removals, and the drift gate says why it fails on a minted repo; +** deed-validate.yml's "Copy it from …" line names the template as the + upstream source, so the self-name pass leaves it alone. +* `tests/e2e/use_template_mint_test.sh` (wired into estate-rules): the first + CI job to run a full mint, with a negative control beside each check. +* The published governance badge could lie. `dogfood-gate.yml` mapped every + non-`success` K9 outcome to RED, so `skipped`, `cancelled` and `timed_out` + all rendered a red "failure" that never happened; worse, the `badges` job + skipped publication entirely when its lane was skipped, so an earlier green + badge stayed on display. Badge publication is now owned by + `scripts/governance-badge.js`, which renders `success`/brightgreen, + `failure`/red, and skipped/cancelled/unavailable/unrecognised as explicit + lightgrey states, and which publishes on a skipped lane instead of leaving + the old badge alone. +* Badge publication treated every GitHub API error as "the branch is missing": + `gh api … >/dev/null 2>&1` fell through to branch creation on a 401, a 429 or + a network failure, and a failed file read produced a PUT with no `sha` that + could never converge. Only a 404 on both the file and the ref may now create + a branch; auth, rate-limit, 5xx and network failures fail the run without + writing anything. +* Every push to `main` wrote a badge commit even when the badge was unchanged. + The publisher now fetches the published file, compares it byte for byte with + the newly rendered badge, and exits with an "unchanged" notice and no commit + when they are identical - and it never re-serialises the JSON to make the + comparison succeed. Publications are serialised per repository (job-level + `concurrency`), and the sha-checked contents call turns a race into a + re-read instead of a silent overwrite. + +* **The Hypatia verdict grid was described in three places and produced in + none.** `.github/workflows/README.adoc` said a `verdict` job posted the grid, + `.gitbot-fleet/report-backs/README.md` said the Hypatia lane downloaded the + report-backs, and `fork-governance.yml` produced a `fleet-report-backs` + artifact "for the grid" — while no workflow rendered a grid, and + `hypatia-scan.yml` uploaded no findings file at all. `fork-governance.yml`'s + verdict job now collects the producers' artifacts for one commit, renders the + findings-family grid with the standards renderer (pinned commit, verified + sha256, never a copy in this tree), uploads `verdict-grid` and maintains one + `` 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 `sholes` 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 @@ -41,8 +452,108 @@ https://semver.org/spec/v2.0.0.html[Semantic Versioning]. `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 @@ -86,6 +597,14 @@ 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 `sholes#N`, a reference to this template's own issue, into `#N`, which names an issue of the child that does not exist or is diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..4af75b5 --- /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](https://web.archive.org/web/20141109123859/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 8b5ee89..39260f5 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.adoc @@ -51,7 +51,7 @@ typed. . Determine which perimeter the bug affects. *When reporting*, use the -link:.github/ISSUE_TEMPLATE/bug_report.md[bug report template] and include: +link:.github/ISSUE_TEMPLATE/bug_report.yml[bug report template] and include: * Clear, descriptive title * Environment details (OS, versions, toolchain) @@ -68,7 +68,7 @@ link:.github/ISSUE_TEMPLATE/bug_report.md[bug report template] and include: . Consider which perimeter the feature belongs to. *When suggesting*, use the -link:.github/ISSUE_TEMPLATE/feature_request.md[feature request template] +link:.github/ISSUE_TEMPLATE/feature_request.yml[feature request template] and include: * Problem statement (what pain point does this solve?) @@ -135,5 +135,5 @@ 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; +`.github/CONTRIBUTING.md` predates that gate and has been removed; this document supersedes it. diff --git a/GEMINI.md b/GEMINI.md deleted file mode 100644 index 417391d..0000000 --- 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 8f5fa44..3f23705 100644 --- a/Justfile +++ b/Justfile @@ -161,6 +161,27 @@ aspect: # 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: # TODO: Replace with your readiness test command. Examples: @@ -194,9 +215,46 @@ crg-badge: 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 @@ -284,6 +342,10 @@ validate-repo-map: rm -f "$before" echo "repository map: up to date" +# Fail if a tracked .adoc/.md links to a missing file, or a deed-registered document id no longer resolves +check-internal-links: + scripts/check-internal-links.sh . + # 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 @@ -692,3 +754,13 @@ uncloak: else echo "Use 'ls -a' to view dotfiles on this OS." fi + +# Repair .github/workflows/actions.lock after a Dependabot github-actions bump. +# Dependabot rewrites `uses:` in the workflow YAML but cannot touch the lock, so +# the Lock Sync Gate goes red. This resolves each new ref (git ls-remote, peeled +# commit for annotated tags), rewrites the lock, and re-validates with +# scripts/check-lock-sync.sh. Fails loudly (lock untouched) on anything it cannot +# resolve. Run it on the Dependabot branch, then commit with a SIGNED commit. +lock-sync-fix: + ./scripts/lock-sync-fix.sh + ./scripts/check-lock-sync.sh diff --git a/LICENSE.adoc b/LICENSE.adoc new file mode 100644 index 0000000..af089d4 --- /dev/null +++ b/LICENSE.adoc @@ -0,0 +1,2 @@ +SPDX-License-Identifier: MPL-2.0 AND CC-BY-SA-4.0 +Code: MPL-2.0. Prose: CC-BY-SA-4.0. diff --git a/benches/baseline.json b/benches/baseline.json new file mode 100644 index 0000000..8d31d6a --- /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":"89d8f68f2f990fa6055e2a40646c1ce3952dfdd0","run_id":"1309674333621"},{"commit":"89d8f68f2f990fa6055e2a40646c1ce3952dfdd0","run_id":"1309674333622"},{"commit":"89d8f68f2f990fa6055e2a40646c1ce3952dfdd0","run_id":"1309674333623"},{"commit":"89d8f68f2f990fa6055e2a40646c1ce3952dfdd0","run_id":"1309674333624"},{"commit":"89d8f68f2f990fa6055e2a40646c1ce3952dfdd0","run_id":"1309674336581"},{"commit":"89d8f68f2f990fa6055e2a40646c1ce3952dfdd0","run_id":"1309674336582"},{"commit":"89d8f68f2f990fa6055e2a40646c1ce3952dfdd0","run_id":"1309674336583"},{"commit":"89d8f68f2f990fa6055e2a40646c1ce3952dfdd0","run_id":"1309674336584"},{"commit":"89d8f68f2f990fa6055e2a40646c1ce3952dfdd0","run_id":"1309674337391"},{"commit":"89d8f68f2f990fa6055e2a40646c1ce3952dfdd0","run_id":"1309674337392"},{"commit":"89d8f68f2f990fa6055e2a40646c1ce3952dfdd0","run_id":"1309674337393"},{"commit":"89d8f68f2f990fa6055e2a40646c1ce3952dfdd0","run_id":"1309674337394"}],"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":6.823368787019621,"mean_median_ns":208714204.91666666},"ijson_jcs":{"iterations":5,"mean_loo_ratio":5.437949558375433,"mean_median_ns":176391924.41666666},"required_contexts":{"iterations":5,"mean_loo_ratio":0.16495587022425925,"mean_median_ns":12812400.25},"root_shape":{"iterations":5,"mean_loo_ratio":0.163910241446135,"mean_median_ns":12782074.083333334}}} diff --git a/benches/template_bench.sh b/benches/template_bench.sh index 5fb58a8..609b3e7 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/container/Containerfile b/build/container/Containerfile index da8451d..d7391ee 100644 --- a/build/container/Containerfile +++ b/build/container/Containerfile @@ -56,12 +56,12 @@ # RUN zig build -Doptimize=ReleaseFast # # Output: /build/zig-out/bin/sholes # -# 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 +# Base image: pinned by digest only, with no tag (SonarCloud rule docker:S8431 +# rejects a reference that carries both). A digest gives reproducibility and +# supply-chain integrity; refresh it by resolving a new digest, e.g.: +# FROM cgr.dev/chainguard/wolfi-base@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 +FROM cgr.dev/chainguard/wolfi-base@sha256:1f6b749929164c3d9e7cad0289254f39b2ba51e1dddaeb0fa57532ea03f2db31 AS builder # TODO: Install your language toolchain RUN apk add --no-cache build-base @@ -79,7 +79,7 @@ COPY . . # 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 +FROM cgr.dev/chainguard/wolfi-base@sha256:1f6b749929164c3d9e7cad0289254f39b2ba51e1dddaeb0fa57532ea03f2db31 # OCI image labels (compatible with cerro-torre .ctp bundle metadata) LABEL org.opencontainers.image.title="sholes" \ diff --git a/build/container/README.adoc b/build/container/README.adoc index 60303ba..787de1d 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,17 +196,29 @@ 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`. +A `container build` workflow ships in `.github/workflows/docker-build.yml`. It is **off by default** — it costs nothing in a repository created from this template until you opt in. @@ -232,9 +266,9 @@ image build/publish jobs you no longer need. == Base images -* Builder: `cgr.dev/chainguard/wolfi-base:latest` -* Runtime: `cgr.dev/chainguard/wolfi-base:latest` (or - `cgr.dev/chainguard/static:latest` for static binaries) +* Builder: `cgr.dev/chainguard/wolfi-base@sha256:` (pinned by digest, no tag) +* Runtime: `cgr.dev/chainguard/wolfi-base@sha256:` (or + `cgr.dev/chainguard/static@sha256:` for static binaries) Chainguard images are minimal, low-CVE, and rebuilt daily (`apk` package manager, Alpine-compatible). diff --git a/build/container/compose.example.yaml b/build/container/compose.example.yaml index cbd43aa..6e84892 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/just/assess.just b/build/just/assess.just index c4c382f..a6a663b 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 @@ -246,8 +262,28 @@ 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" # Identity, state and ecosystem live in the repo deed (rsr-template-repo#209). diff --git a/build/just/container.just b/build/just/container.just index a906c60..2b9ad7f 100644 --- a/build/just/container.just +++ b/build/just/container.just @@ -46,6 +46,10 @@ container-init: exit 1 fi + # The configs are reformatted after their tokens are filled, which needs a + # KYAML-capable yq: check before anything is written. + bash scripts/format-container-kyaml.sh --preflight + echo "=== Container Template Initialisation ===" echo "" @@ -65,8 +69,11 @@ container-init: read -rp "Primary port [8080]: " _PORT PORT="${_PORT:-8080}" - read -rp "Container registry [ghcr.io/${OWNER:-{{OWNER}}}]: " _REGISTRY - REGISTRY="${_REGISTRY:-ghcr.io/${OWNER:-{{OWNER}}}}" + # Image paths are lower case; an owner login may not be. + _OWNER="${OWNER:-{{OWNER}}}"; _OWNER="${_OWNER,,}" + read -rp "Container registry [ghcr.io/${_OWNER}]: " _REGISTRY + REGISTRY="${_REGISTRY:-ghcr.io/${_OWNER}}" + bash scripts/format-container-kyaml.sh --check-values "$SERVICE_NAME" "$PORT" "$REGISTRY" echo "" echo " Service: $SERVICE_NAME" @@ -89,17 +96,53 @@ 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 + # Filling a token can change how KYAML quotes it; reformat the configs or + # Estate Rules' "Converted YAML stays KYAML" fails the child. + bash scripts/format-container-kyaml.sh + + # 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 +160,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 @@ -240,7 +286,7 @@ container-keep +tiers: else plan+=("build/container/ (entire image + compose + stapeln)") plan+=("build/just/container.just (this module) + its Justfile import") - [ -f .github/workflows/container-build.yml ] && plan+=(".github/workflows/container-build.yml") + [ -f .github/workflows/docker-build.yml ] && plan+=(".github/workflows/docker-build.yml") fi echo "Keeping: oci=$keep_oci portable=$keep_port stapeln=$keep_stap devcontainer=$keep_dev" @@ -260,7 +306,7 @@ container-keep +tiers: else rm -rf build/container rm -f .machine_readable/configs/selur-compose.toml - rm -f .github/workflows/container-build.yml + rm -f .github/workflows/docker-build.yml rm -f build/just/container.just [ -f Justfile ] && sed -i '/# >>> container-module/,/# <<< container-module/d' Justfile for jf in Justfile .machine_readable/contractiles/Justfile; do diff --git a/build/just/provision-lib.sh b/build/just/provision-lib.sh index 1a5238d..48e75f2 100755 --- a/build/just/provision-lib.sh +++ b/build/just/provision-lib.sh @@ -99,6 +99,7 @@ ARCHETYPE="$(deed archetype "")" # estate ABI/FFI pattern nests deeper: Idris2 to two levels down (src/abi/*.ipkg), # Zig to three (ffi/zig/build.zig, and sholes's src/interface/ffi/build.zig: # 74 repos have their only build.zig at that depth, measured 2026-09-30). +# Julia to three (src/julia/Project.toml: occupancy-types keeps its package there). # 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. @@ -108,7 +109,7 @@ 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 Project.toml 3)" ] && out+=(julia) [ -n "$(first build.zig 4)" ] && out+=(zig) [ -n "$(first mix.exs)" ] && out+=(elixir) [ -n "$(first gleam.toml)" ] && out+=(gleam) @@ -176,7 +177,7 @@ guix_specs() { # 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" +MISE_BASE="just shellcheck yq" # yq: scripts/kyaml-format.sh (KYAML configs; the mint formats the container ones) # 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. @@ -196,9 +197,14 @@ recipe_tools() { } # 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=() - for t in $MISE_BASE $(for l in "${LANGS[@]}"; do lang_mise "$l"; done) $(recipe_tools); do + 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[*]}" @@ -675,7 +681,7 @@ cmd_heal() { [ -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 bun && have bun; then bun install --ignore-scripts >/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; } @@ -938,7 +944,7 @@ cmd_search() { case "${1:-}" in guix-specs) guix_specs ;; - mise-tools) mise_tools ;; + mise-tools) shift; mise_tools "$@" ;; langs) printf '%s\n' "${LANGS[@]}" ;; doctor) cmd_doctor ;; setup) cmd_setup ;; diff --git a/build/just/repo-init.just b/build/just/repo-init.just index 37afc74..b22beb8 100644 --- a/build/just/repo-init.just +++ b/build/just/repo-init.just @@ -37,6 +37,187 @@ repo-init archetype="": 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 mint runs git against other repositories too (replays, a template + # clone, the tests it runs in scratch repositories), and an inherited + # repository location (GIT_DIR, GIT_INDEX_FILE, … from a hook or another git + # caller) would redirect every one of them into this repository: the + # replay's commits, the tests' fixture commits (CodeRabbit review of #275). + # So the location is cleared, once, here, for this recipe and everything it + # starts; one that named a different repository than this work tree's own + # is refused, since clearing it would mint something else. + _git_loc=(GIT_DIR GIT_WORK_TREE GIT_COMMON_DIR GIT_INDEX_FILE GIT_OBJECT_DIRECTORY + GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_PREFIX GIT_NAMESPACE) + _git_set=""; for _v in "${_git_loc[@]}"; do [ -z "${!_v+x}" ] || _git_set="${_git_set} ${_v}"; done + if [ -n "$_git_set" ]; then + _here_gd="$(git rev-parse --absolute-git-dir 2>/dev/null || true)" + _bare_gd="$(cd "$(git rev-parse --show-toplevel)" && env $(printf -- '-u %s ' "${_git_loc[@]}") git rev-parse --absolute-git-dir 2>/dev/null || true)" + if [ -z "$_bare_gd" ] || [ "$_here_gd" != "$_bare_gd" ]; then + echo "Error: mint aborted before writing anything — git location variables are set" + echo " (${_git_set# }) and name a repository other than this work tree's own." + echo " Run repo-init from the repository's work tree without them." + exit 1 + fi + unset "${_git_loc[@]}" + 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 guessed: these are facts about the checkout, not choices. + # The root Justfile's OWNER/REPO lines are 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". + # When the Justfile does not declare them, RSR_TEMPLATE_SLUG=owner/repo + # must say so, or the mint stops. There is deliberately no fallback to the + # git remote: in a template-created child the remote is the CHILD, so that + # fallback named the child as its own template, and the pin resolver then + # recorded the child's HEAD (Codex review of #251). Nor is there a default + # template name: a guess here is the hardcoding this block replaced. + TEMPLATE_OWNER="" + TEMPLATE_REPO="" + if [ -f Justfile ]; then + TEMPLATE_REPO="$(sed -n -E "s/^(export[[:space:]]+)?REPO[[:space:]]*:=[[:space:]]*[\"']([^\"']+)[\"'].*/\2/p" Justfile | head -1)" + TEMPLATE_OWNER="$(sed -n -E "s/^(export[[:space:]]+)?OWNER[[:space:]]*:=[[:space:]]*[\"']([^\"']+)[\"'].*/\2/p" Justfile | head -1)" + fi + if [ -z "$TEMPLATE_REPO" ] || [ -z "$TEMPLATE_OWNER" ]; then + if [[ "${RSR_TEMPLATE_SLUG:-}" =~ ^[A-Za-z0-9._-]+/[A-Za-z0-9._-]+$ ]]; then + TEMPLATE_OWNER="${RSR_TEMPLATE_SLUG%%/*}" + TEMPLATE_REPO="${RSR_TEMPLATE_SLUG#*/}" + else + echo "Error: the root Justfile does not declare OWNER := and REPO :=, so the" + echo " template this tree came from is unknown. Set RSR_TEMPLATE_SLUG=owner/repo." + exit 1 + fi + fi + TEMPLATE_SLUG="${TEMPLATE_OWNER}/${TEMPLATE_REPO}" + + # --- A template is minted; a minted repo is minted as a chain ------------ + # A minted repo has already filled its tokens and deleted build/templates, + # so minting it like a template renders none of the new answers and skips + # the identity splice: the grandchild silently inherited its parent's + # author, contacts, clade and maturity (Codex review of #251). So it is + # never minted that way: it is chain-minted, or refused, before anything is + # asked or written. A variant template keeps build/templates and still mints. + # + # Chain minting (owner ruling 2026-11-04): a minted repo that recorded its + # (mint-answers) CAN be minted again. scripts/chain-mint.sh replays its + # mint, mints the same template commit with the new answers, and carries + # its own work across by a three-way merge. One minted before answers were + # recorded cannot be replayed, so it is still refused. + # + # Which it is, the deed's recorded mint state decides first: a template + # (or a variant template, which is maintained, never minted) records no + # (mint-answers). A minted repo that added build/templates/identity.deed.in + # back as its own work is still a minted repo (Codex review of #277). + # The recorded state alone decides; the chain script's presence does not: + # a minted repo that deleted scripts/chain-mint.sh is still minted, and + # minting it as a template would keep its author and contacts (Codex + # review of #277). It is refused instead. + CHAIN_MINT=0 + _prov_deed="$(bash scripts/deed-field.sh --find . 2>/dev/null || true)" + if [ -n "$_prov_deed" ] && bash scripts/deed-field.sh --has "$_prov_deed" mint-answers \ + && [ ! -f scripts/chain-mint.sh ]; then + echo "Error: this tree is a minted repo (its deed records (mint-answers)), but" + echo " scripts/chain-mint.sh, which mints a minted repo again, is absent." + echo " Restore it from the template, or mint from the template itself." + exit 1 + elif [ -n "$_prov_deed" ] && bash scripts/deed-field.sh --has "$_prov_deed" mint-answers; then + CHAIN_MINT=1 + echo "This tree is a minted repo (${TEMPLATE_SLUG}): it will be minted as a chain," + echo "from its template, carrying its own work since its mint." + echo "" + elif [ ! -f build/templates/identity.deed.in ]; then + echo "Error: this tree has already been minted (build/templates/identity.deed.in is" + echo " absent) and records no (mint-answers), so its mint cannot be replayed" + echo " and it cannot be minted again. Mint from the template it came from." + if [ -n "$_prov_deed" ]; then + _prov_from="$(bash scripts/deed-field.sh "$_prov_deed" provenance template-repo 2>/dev/null || true)" + [ -z "$_prov_from" ] || echo " This tree records its template as ${_prov_from}." + fi + exit 1 + fi + + # --- 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 '^$') + # These two preflights judge a TEMPLATE tree. A chain mint's tree is a + # minted repo whose own work (a deleted verbatim-listed file, an added file + # with a brace token) is the parent's business; the root template is + # checked when chain-mint.sh replays it, and the merged result passes the + # placeholder gate (Codex review of #277). + if [ "$CHAIN_MINT" != "1" ]; then + for _v in "${MINT_VERBATIM[@]}"; do + [ -f "$_v" ] || { echo "Error: $VERBATIM_LIST names $_v, which does not exist (stale entry)."; exit 1; } + done + fi + + # ── 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 [ "$CHAIN_MINT" != "1" ] && [ -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 + + # ── Are the tools the mint needs LATER present? ───────────────────────── + # The mint writes the tree first and reaches a KYAML-capable yq + # (format-container-kyaml.sh) and nickel (the arrival pack) afterwards; a + # missing one used to stop it after 100+ files were rewritten. Every mint + # kind (plain, archetype, chain) reaches both steps, so none is exempt; + # the script demands a tool only when its step can run (see its header). + [ -f scripts/check-mint-tools.sh ] \ + || { echo "Error: scripts/check-mint-tools.sh is missing; the mint cannot check its tools."; exit 1; } + bash scripts/check-mint-tools.sh . || exit 1 + 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 "═══════════════════════════════════════════════════" @@ -46,7 +227,25 @@ repo-init archetype="": ARCHETYPE='{{archetype}}' ARCH_FILE="" ARCH_PRESET="" - if [ -n "$ARCHETYPE" ]; then + # A chain mint has no archetypes/ (the parent's mint removed it); it + # re-mints with the archetype the parent recorded, from the root template + # (scripts/chain-mint.sh). Naming that same archetype is accepted; any + # other is refused, since the parent's tree was built for its own. + # MINT_ARCH is the archetype the mint will actually apply: on a chain, the + # parent's, whether or not it was named (the slug rule below depends on it: + # a Julia package's .jl slug). + MINT_ARCH="$ARCHETYPE" + if [ "$CHAIN_MINT" = "1" ]; then + _p_arch="$(bash scripts/deed-field.sh "$_prov_deed" mint-answers archetype 2>/dev/null || true)" + if [ -n "$ARCHETYPE" ] && [ "$ARCHETYPE" != "$_p_arch" ]; then + echo "Error: this tree was minted as archetype '${_p_arch:-none}'; a chain mint keeps it." + echo " Run just repo-init${_p_arch:+ ${_p_arch}} (or mint from the template for another)." + exit 1 + fi + [ -z "$_p_arch" ] || { echo "Archetype: ${_p_arch} (the parent's, re-minted from the template)"; echo ""; } + MINT_ARCH="$_p_arch" + ARCHETYPE="" + elif [ -n "$ARCHETYPE" ]; then ARCH_FILE="archetypes/${ARCHETYPE}/${ARCHETYPE}_praxis.deed" if [ ! -f "$ARCH_FILE" ]; then echo "Error: unknown archetype '${ARCHETYPE}'. Available:" @@ -80,11 +279,11 @@ repo-init archetype="": # 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 + if [[ "$MINT_ARCH" = "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)" + [ "$MINT_ARCH" = "julia-library" ] && echo " (or, for a Julia package, .jl with in UpperCamelCase)" exit 1 fi @@ -156,21 +355,28 @@ repo-init archetype="": 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. + # Derive the default for a DNS hostname and bare TOML service key, not + # only an OCI image name: Julia dots and slug underscores need hyphens. + # Explicit service answers still go through the validator unchanged. + DEFAULT_SERVICE_NAME="${REPO,,}" + DEFAULT_SERVICE_NAME="${DEFAULT_SERVICE_NAME//[._]/-}" if [ -d "build/container" ]; then echo "" echo "── Container configuration (optional) ─────────" - ask "Service name [${SERVICE_NAME:-${REPO,,}}]: " _SERVICE_NAME - SERVICE_NAME="${_SERVICE_NAME:-${SERVICE_NAME:-${REPO,,}}}" + ask "Service name [${SERVICE_NAME:-$DEFAULT_SERVICE_NAME}]: " _SERVICE_NAME + SERVICE_NAME="${_SERVICE_NAME:-${SERVICE_NAME:-$DEFAULT_SERVICE_NAME}}" ask "Primary port [${PORT:-8080}]: " _PORT PORT="${_PORT:-${PORT:-8080}}" - ask "Container registry [${REGISTRY:-ghcr.io/${OWNER}}]: " _REGISTRY - REGISTRY="${_REGISTRY:-${REGISTRY:-ghcr.io/${OWNER}}}" + ask "Container registry [${REGISTRY:-ghcr.io/${OWNER,,}}]: " _REGISTRY + REGISTRY="${_REGISTRY:-${REGISTRY:-ghcr.io/${OWNER,,}}}" + # The values fill double-quoted KYAML scalars: refuse a value that + # would break them now, before anything is written. + bash scripts/format-container-kyaml.sh --check-values "$SERVICE_NAME" "$PORT" "$REGISTRY" \ + || { echo "ERROR: mint aborted before writing anything — see above."; exit 1; } else - SERVICE_NAME="${SERVICE_NAME:-${REPO,,}}" + SERVICE_NAME="${SERVICE_NAME:-$DEFAULT_SERVICE_NAME}" PORT="${PORT:-8080}" - REGISTRY="${REGISTRY:-ghcr.io/${OWNER}}" + REGISTRY="${REGISTRY:-ghcr.io/${OWNER,,}}" fi # --- Derived values --- @@ -179,22 +385,45 @@ repo-init archetype="": # 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) + # The mint date is an input like any answer: RSR_MINT_DATE replays a mint + # exactly (scripts/check-mint-drift.sh re-mints a child with the date it + # recorded). Otherwise it is today. The year always follows the date. + CURRENT_DATE="${RSR_MINT_DATE:-$(date +%Y-%m-%d)}" + # Validated in bash, not with `date -d`: that is GNU-only, and macOS's date + # rejected every date, today's included (Codex review of #275). + _dm=0 + if [[ "$CURRENT_DATE" =~ ^([0-9]{4})-([0-9]{2})-([0-9]{2})$ ]]; then + _yy=$((10#${BASH_REMATCH[1]})); _mm=$((10#${BASH_REMATCH[2]})); _dd=$((10#${BASH_REMATCH[3]})) + case "$_mm" in + 1|3|5|7|8|10|12) _dm=31 ;; + 4|6|9|11) _dm=30 ;; + 2) if (( (_yy % 4 == 0 && _yy % 100 != 0) || _yy % 400 == 0 )); then _dm=29; else _dm=28; fi ;; + esac + fi + if [ "$_dm" -eq 0 ] || [ "${_dd:-0}" -lt 1 ] || [ "${_dd:-0}" -gt "$_dm" ]; then + echo "Error: RSR_MINT_DATE must be a real date, YYYY-MM-DD (got '${CURRENT_DATE}')." + exit 1 + fi + CURRENT_YEAR="${CURRENT_DATE:0:4}" VERSION="0.1.0" - # --- Derive the repo's uuid -------------------------------------------- - # THE UUID IS DERIVED, NOT ALLOCATED (gv-clade-index: - # docs/SPEC-clade-verisim-portal.adoc §Identity Model): - # uuid = UUIDv5(namespace = URL, name = "github.com//") - # We know OWNER and REPO, so this is computable here and must never be - # guessed or copied. The owner segment is part of the derived name, so it is - # part of the identity — a repo hosted elsewhere derives a different uuid. - if command -v uuidgen >/dev/null 2>&1; then - REPO_UUID=$(uuidgen --sha1 --namespace @url --name "${FORGE}/${OWNER}/${REPO}") - else - REPO_UUID="UNASSIGNED" - fi + # --- Mint the repo's chora id ---------------------------------------- + # The chora id is minted ONCE, here, from the repo's birth path, and is + # carried opaquely as :repo-uuid #uuid"" (standards A1 rules U1 to U4 + # and V8, A7 J11). It is the ADR-008 profile C UUIDv8 of the birth path in + # the domain chora-registry (owner ruling V9, 2026-11-13: new ids only; ids + # minted earlier keep their gv-clade-index id and are never reminted): + # first 16 bytes of SHA-256("chora-registry://"), + # version 8, variant 10 + # (scripts/uuid-v8.sh, equal to standards scripts/uuid-v8.js c, tested by + # tests/workflows/uuid_v8_test.sh). It is computed the same way on every + # machine, so the drift gate's replay agrees with the mint. Nothing + # re-derives it later: a transfer or rename never changes it (U1). + REPO_UUID="$(bash scripts/uuid-v8.sh chora-registry "${FORGE}/${OWNER}/${REPO}")" || { + echo "Error: the repo id is minted as a UUIDv8 (SHA-256), and this machine" + echo " has none of sha256sum, shasum or openssl to mint it with." + exit 1 + } # Derive citation name parts (best-effort split on last space) AUTHOR_LAST="${AUTHOR##* }" @@ -221,14 +450,390 @@ repo-init archetype="": ask "Proceed? [Y/n] " CONFIRM [[ "${CONFIRM:-Y}" =~ ^[Nn] ]] && echo "Aborted." && exit 0 + # An answer is one line: no sed expression, deed string or prompt can carry + # a newline. Refused HERE, before the first write (the overlay, the prune + # and the docs seed all come next), so a bad answer leaves a clean tree. + for _ans in PROJECT_NAME PROJECT_DESCRIPTION OWNER AUTHOR AUTHOR_EMAIL AUTHOR_ORG \ + AUTHOR_LAST AUTHOR_FIRST FORGE SECURITY_EMAIL CONDUCT_EMAIL PROJECT_TYPE \ + WEBSITE SERVICE_NAME PORT REGISTRY AUTHOR_EMAIL_ALT AUTHOR_ORCID OPENSSF_BP_ID; do + case "${!_ans:-}" in + *$'\n'*) echo "Error: the answer for $_ans contains a newline; answers are one line."; exit 1 ;; + # 0x01 is the record separator deed-field.sh and deed-clause.sh read the + # deed with: an answer holding it renders everywhere, then cannot be + # recorded in (mint-answers) (Codex review of #275). + *$'\001'*) echo "Error: the answer for $_ans contains byte 0x01, which the deed cannot record."; exit 1 ;; + esac + done + + # Answers are free text, and the right-hand side of s|…|…| is not: `&` + # inserts the matched token, `\` escapes, `|` ends the expression. A + # description "Tools & proofs" rendered as "Tools proofs" and + # then failed the placeholder gate; a `|` broke the substitution. Every + # answer goes through sed_rhs. (A newline was refused before the first write.) + # Defined here, ahead of the rules below that use it. + sed_rhs() { printf '%s' "$1" | sed -e 's/[\\&|]/\\&/g'; } + + # The self-name rule, defined once: used by the self-name pass below and + # handed to scripts/chain-mint.sh, so a chain mint renames the parent by + # exactly the same rule (passed as data, never re-read from the recipe). + 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. + # The name is matched only where it stands as a whole name: not inside + # a longer word or slug (Codex review of #251). Unbounded, a parent + # named `app` turned "application mapping" into "newlication mnewing". + # A neighbouring letter or digit blocks the match; anything else does + # not, so `_` (sonar.projectKey), `_chora.deed` and + # derived names such as `-checkout` or `rm-` still follow. Each pass + # loops (:label … t label) because a match consumes its right-hand + # neighbour, and marks through a sentinel so a new name that contains + # the old one (Geometry -> Geometry.jl) cannot loop forever. + SELF_NAME_SED="/${SELF_PROV}/!{:i;s@(^|[^A-Za-z0-9])${TEMPLATE_REPO//./\\.}#([0-9])@\\1\\x01I\\x01\\2@;ti;:s;s@(^|[^A-Za-z0-9])${TEMPLATE_SLUG//./\\.}([^A-Za-z0-9]|$)@\\1\\x01S\\x01\\2@;ts;:n;s@(^|[^A-Za-z0-9])${TEMPLATE_REPO//./\\.}([^A-Za-z0-9]|$)@\\1\\x01N\\x01\\2@;tn;s@\\x01S\\x01@${OWNER}/${REPO}@g;s@\\x01N\\x01@${REPO}@g;s@\\x01I\\x01@${TEMPLATE_REPO}#@g;}" + # The self-owner rule, defined once likewise (see the self-OWNER pass for + # why it is three exact identity lines and never a blanket rewrite): the + # Justfile OWNER declaration in each form the identity parser accepts, and + # the SonarCloud organization and project key. chain-mint.sh applies it to + # the parent's carried files too (Codex review of #277). + SELF_OWNER_SED="s|^((export[[:space:]]+)?OWNER[[:space:]]*:=[[:space:]]*)([\"'])${TEMPLATE_OWNER//./\\.}([\"'])|\\1\\3$(sed_rhs "${OWNER}")\\4|;s|^sonar\\.organization=${TEMPLATE_OWNER//./\\.}\$|sonar.organization=$(sed_rhs "${OWNER}")|;s|^sonar\\.projectKey=${TEMPLATE_OWNER//./\\.}_|sonar.projectKey=$(sed_rhs "${OWNER}")_|" + + # Chain mint: everything below renders a TEMPLATE tree, which this is not. + # chain-mint.sh renders the template afresh with these answers and carries + # this tree's own work across; it writes nothing unless it succeeds. + if [ "$CHAIN_MINT" = "1" ]; then + export PROJECT_NAME REPO OWNER AUTHOR AUTHOR_EMAIL AUTHOR_ORG AUTHOR_EMAIL_ALT \ + AUTHOR_ORCID PROJECT_DESCRIPTION FORGE SECURITY_EMAIL CONDUCT_EMAIL \ + PROJECT_TYPE WEBSITE OPENSSF_BP_ID SERVICE_NAME PORT REGISTRY \ + TEMPLATE_REPO TEMPLATE_OWNER + export RSR_MINT_DATE="$CURRENT_DATE" SELF_NAME_SED SELF_OWNER_SED + bash scripts/chain-mint.sh + echo "" + echo "Done! Chain mint complete. Review with git status, then commit." + exit 0 + fi + + # 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 + + # --- What this work tree holds beyond the pinned tree ------------------- + # The mint transforms the work tree as it stands; the drift gate replays + # from the pinned tree alone. Anything already changed here before the + # mint (an edit, an untracked file, a deletion) is this repo's own, not + # the mint's, so it is measured now and declared in (variant (paths)): + # the replay stays exact and the record says what happened (Codex review + # of #275). Measured in a scratch index and object store, so .git is not + # written. (A chain mint carries its parent's tree by its own rules.) + PREMINT_A=() PREMINT_M=() PREMINT_D=() + if [ "${CHAIN_MINT:-0}" != "1" ] && [ "$PARENT_TREE" != "UNASSIGNED" ]; then + # The work tree as `git add -A` would commit it, from the current index + # (so a tracked file an ignore rule matches stays), in a scratch index + # and object store. + _pm="$(mktemp -d)"; mkdir -p "$_pm/objects" + _gd="$(cd "$(git rev-parse --git-common-dir)" && pwd)" + _ix="$(git rev-parse --git-path index)" + [ ! -f "$_ix" ] || cp "$_ix" "$_pm/index" + _wt() { GIT_INDEX_FILE="$_pm/index" GIT_OBJECT_DIRECTORY="$_pm/objects" GIT_ALTERNATE_OBJECT_DIRECTORIES="$_gd/objects" git "$@"; } + _wt add -A . + # A gitlink (submodule) cannot be replayed (checkout-index writes no files + # for one), so the drift gate could never pass: refused by name here, + # whether or not anything else changed (Codex review of #275). + _gl="$(_wt ls-files -s | awk -F '\t' '$1 ~ /^160000 / { print " " $2 }')" + if [ -n "$_gl" ]; then + echo "ERROR: mint aborted before writing anything — this tree carries a submodule" + echo " (gitlink), which a replay of the mint cannot reproduce, so its drift gate" + echo " could never pass. Minting such a tree is not supported:" + printf '%s\n' "$_gl" + rm -rf "$_pm"; exit 1 + fi + if git cat-file -e "${PARENT_TREE}^{tree}" 2>/dev/null; then + while IFS= read -r -d '' _st && IFS= read -r -d '' _p; do + # A newline splits the deed's line-based lists; byte 0x01 is the deed + # reader's record separator (Codex review of #277). + case "$_p" in *$'\n'*|*$'\001'*) echo "Error: a path holding a newline or byte 0x01 cannot be declared: $(printf '%q' "$_p")"; rm -rf "$_pm"; exit 1 ;; esac + case "$_st" in + A) PREMINT_A+=("$_p") ;; + D) PREMINT_D+=("$_p") ;; + *) PREMINT_M+=("$_p") ;; + esac + done < <(_wt diff --cached -z --no-renames --name-status "$PARENT_TREE") + elif [ "$(_wt write-tree)" != "$PARENT_TREE" ]; then + # An asserted pin (RSR_TEMPLATE_COMMIT) whose tree this repository + # does not hold: the difference cannot even be listed, so it cannot + # be declared, and the replay would report it (Codex review of #275). + rm -rf "$_pm" + echo "ERROR: mint aborted before writing anything — this work tree differs from the" + echo " template tree ${PARENT_TREE:0:12}, which this repository does not hold, so" + echo " the difference cannot be declared. Fetch it first" + echo " (git fetch ${PARENT_PIN}) or mint from a matching tree." + exit 1 + fi + # The work tree's own tree: what a dry run of this mint starts from + # (below). Its objects stay in $_pm until the replays are done. + _WT_TREE="$(_wt write-tree)" + # The mint moves a root .well-known/ (the www/ migration, below), so a + # path there could not be declared where it ends up: refused by name. + for _p in "${PREMINT_A[@]}" "${PREMINT_M[@]}" "${PREMINT_D[@]}"; do + case "$_p" in + .well-known/*) + echo "ERROR: mint aborted before writing anything — $_p changed before the mint," + echo " and the mint moves .well-known/ into www/.well-known/. Commit that move" + echo " first (bash scripts/migrate-wellknown-to-www.sh), or revert the change." + rm -rf "$_pm"; exit 1 ;; + esac + done + # The mint writes new files of its own: the archetype overlay (before + # and after its .in rename), the docs seed, the deed. A pre-mint file + # at one of those paths would be overwritten (lost) and then declared + # as this repo's own addition, which the replay contradicts (Codex + # review of #275). Refused by name, before anything is written. + _writes=("${REPO}_chora.deed") + if [ -n "$ARCHETYPE" ] && [ -d "archetypes/${ARCHETYPE}/overlay" ]; then + while IFS= read -r -d '' _o; do + _o="${_o#./}"; _writes+=("$_o") + case "$_o" in + src/PACKAGE.jl.in) _writes+=("src/${PROJECT_NAME}.jl") ;; + *.in) _writes+=("${_o%.in}") ;; + esac + done < <(cd "archetypes/${ARCHETYPE}/overlay" && find . -type f -print0) + fi + if [ -d build/docs-seed ]; then + while IFS= read -r -d '' _o; do _writes+=("docs/${_o#./}"); done \ + < <(cd build/docs-seed && find . -type f ! -path ./README.adoc -print0) + fi + # An edited template file the overlay or seed replaces is lost the same way + # (Codex review of #275: provisioning_praxis.deed under julia-library). + for _p in "${PREMINT_A[@]}" "${PREMINT_M[@]}"; do + for _w in "${_writes[@]}"; do + if [ "$_p" = "$_w" ]; then + echo "ERROR: mint aborted before writing anything — $_p changed before the mint, and" + echo " the mint writes that path itself (the archetype overlay, the docs seed or" + echo " the deed), so your file would be overwritten. Move it aside, mint, then" + echo " bring it back as a change of your own." + rm -rf "$_pm"; exit 1 + fi + done + done + _n=$(( ${#PREMINT_A[@]} + ${#PREMINT_M[@]} + ${#PREMINT_D[@]} )) + if [ "$_n" -gt 0 ]; then + echo "NOTE: ${_n} path(s) here already differ from the template tree ${PARENT_TREE:0:12}" + echo " (${#PREMINT_A[@]} added, ${#PREMINT_M[@]} changed, ${#PREMINT_D[@]} removed before this mint). They are" + echo " this repo's own. What they change in the result is declared in" + echo " (variant (paths)), measured against a replay of this mint:" + for _p in "${PREMINT_A[@]}" "${PREMINT_M[@]}" "${PREMINT_D[@]}"; do echo " $_p"; done + fi + fi + + # --- The replay this mint is measured against, when the tree has changed --- + # A pre-mint change can reach the result in ways no rule over its own path + # predicts: the mint moves, overwrites and renders files, and reads its own + # inputs (the overlay, the docs seed, its scripts) from this tree (Codex and + # CodeRabbit review of #275). So this mint is replayed, here, before anything + # is written, from the pinned tree with the same answers and date, exactly + # as the drift gate will replay it; what this tree then differs by is + # declared below. The pinned tree is in this repository (checked above). + # The inner mint skips pin resolution (RSR_ALLOW_UNPINNED with no template + # source): it writes the pin only into its deed, which is not compared. + # + # And a dry run: the same mint of THIS tree, pre-mint changes and all. A + # change at a path where the dry run and the replay agree has no effect on + # the result: the mint writes that path itself (the roadmap, mise.toml, + # the map, the overlay, the docs seed, the deed) and the change + # would be silently discarded. It is refused by name, before anything is + # written (Codex review of #275), whatever writes it. + # _same A B — identical as git records them: content, executable bit, link target. + # As scripts/check-mint-drift.sh's same(): a link target is read with a + # sentinel (command substitution strips trailing newlines), and the + # executable bit is the owner's (0100), as git records it, not `-x` + # (effective access, true as root for a group-executable file) (Codex + # review of #275). + _ux() { [ -n "$(find "$1" -prune -perm -0100 2>/dev/null)" ]; } + _same() { + if [ -L "$1" ] || [ -L "$2" ]; then + [ -L "$1" ] && [ -L "$2" ] && [ "$(readlink "$1"; echo .)" = "$(readlink "$2"; echo .)" ] + return + fi + { _ux "$1" && _ux "$2"; } || { ! _ux "$1" && ! _ux "$2"; } || return 1 + cmp -s "$1" "$2" + } + _REPLAY="" + if [ $(( ${#PREMINT_A[@]} + ${#PREMINT_M[@]} + ${#PREMINT_D[@]} )) -gt 0 ]; then + # _rg — git with no user or system configuration and no hooks, and no + # inherited repository location (GIT_DIR, GIT_INDEX_FILE, … from a hook or + # another git caller), which would redirect the replay's commits into + # this repository (CodeRabbit review of #275). _rgi IDX — the same, on + # the scratch index IDX and object store $_pm (the work tree's objects). + _rgclean=(env -u GIT_DIR -u GIT_WORK_TREE -u GIT_COMMON_DIR -u GIT_INDEX_FILE -u GIT_OBJECT_DIRECTORY + -u GIT_ALTERNATE_OBJECT_DIRECTORIES -u GIT_PREFIX -u GIT_NAMESPACE GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_NOSYSTEM=1) + _rgflags=(-c user.name=replay -c user.email=replay@example.invalid -c commit.gpgsign=false -c core.hooksPath=/dev/null) + _rg() { "${_rgclean[@]}" git "${_rgflags[@]}" "$@"; } + _rgi() { local _i="$1"; shift + "${_rgclean[@]}" GIT_INDEX_FILE="$_i" GIT_OBJECT_DIRECTORY="$_pm/objects" GIT_ALTERNATE_OBJECT_DIRECTORIES="$_gd/objects" \ + git "${_rgflags[@]}" "$@"; } + _rp="$(mktemp -d)"; _REPLAY="$_rp/r" + mkdir -p "$_rp/cfg"; : > "$_rp/gitconfig" + # _mint_tree TREE DIR — TREE written into DIR as a checkout writes it + # (checkout-index, not git archive, whose export-ignore and export-subst + # attributes would change the tree (Codex review of #275)), committed as + # "Use this template" commits it, then minted with this mint's answers. + _mint_tree() { + mkdir -p "$2" + _rgi "$_rp/index" read-tree "$1" + # A gitlink has no files to write, so the copy would lose it: refused + # by name rather than replayed inexactly (Codex review of #277). + _gl="$(_rgi "$_rp/index" ls-files -s | awk -F '\t' '$1 ~ /^160000 / { print " " $2 }')" + if [ -n "$_gl" ]; then + echo "ERROR: the tree carries a submodule (gitlink), which the replay of this mint" + echo " cannot reproduce; minting such a tree is not supported:" + printf '%s\n' "$_gl" + rm -f "$_rp/index"; return 1 + fi + _rgi "$_rp/index" checkout-index -a -f --prefix="$2/" + rm -f "$_rp/index" + # Forced, then checked to BE the tree: a file the tree tracks although + # its .gitignore matches it is still copied by "Use this template" + # (Codex and CodeRabbit review of #277). + _rg -C "$2" init -q -b main; _rg -C "$2" add -f -A + if [ "$(_rg -C "$2" write-tree)" != "$(_rgi "$_rp/index" rev-parse "$1^{tree}")" ]; then + echo "ERROR: the checkout of the tree does not read back as itself (an attribute" + echo " rewrites a file), so this mint cannot be replayed exactly." + return 1 + fi + _rg -C "$2" commit -q -m "Initial commit" + _rg -C "$2" remote add origin "git@${FORGE}:${OWNER}/${REPO}.git" + (cd "$2" && env -i PATH="$PATH" HOME="$HOME" TMPDIR="${TMPDIR:-/tmp}" \ + ${RUSTUP_HOME:+RUSTUP_HOME="$RUSTUP_HOME"} ${CARGO_HOME:+CARGO_HOME="$CARGO_HOME"} \ + ${RSR_MINT_TOOL_CACHE:+RSR_MINT_TOOL_CACHE="$RSR_MINT_TOOL_CACHE"} \ + ${RSR_TEMPLATE_SLUG:+RSR_TEMPLATE_SLUG="$RSR_TEMPLATE_SLUG"} \ + ${STANDARDS_UUID_V8_JS:+STANDARDS_UUID_V8_JS="$STANDARDS_UUID_V8_JS"} \ + XDG_CONFIG_HOME="$_rp/cfg" GIT_CONFIG_GLOBAL="$_rp/gitconfig" GIT_CONFIG_NOSYSTEM=1 \ + RSR_NON_INTERACTIVE=1 RSR_MINT_REPLAY=1 RSR_ALLOW_UNPINNED=1 \ + RSR_TEMPLATE_URL="$_rp/no-template-source" RSR_MINT_DATE="$CURRENT_DATE" \ + PROJECT_NAME="$PROJECT_NAME" REPO="$REPO" OWNER="$OWNER" AUTHOR="$AUTHOR" \ + AUTHOR_EMAIL="$AUTHOR_EMAIL" AUTHOR_ORG="${AUTHOR_ORG:-}" AUTHOR_EMAIL_ALT="${AUTHOR_EMAIL_ALT:-}" \ + AUTHOR_ORCID="${AUTHOR_ORCID:-}" PROJECT_DESCRIPTION="${PROJECT_DESCRIPTION:-}" FORGE="$FORGE" \ + SECURITY_EMAIL="${SECURITY_EMAIL:-}" CONDUCT_EMAIL="${CONDUCT_EMAIL:-}" \ + PROJECT_TYPE="${PROJECT_TYPE:-}" WEBSITE="${WEBSITE:-}" OPENSSF_BP_ID="${OPENSSF_BP_ID:-}" \ + SERVICE_NAME="${SERVICE_NAME:-}" PORT="${PORT:-}" REGISTRY="${REGISTRY:-}" \ + just repo-init ${ARCHETYPE:+"$ARCHETYPE"} "$2.log" 2>&1 \ + || { tail -n 30 "$2.log"; return 1; } + } + echo " replaying this mint from the template tree, to measure the pre-mint changes..." + if ! _mint_tree "$PARENT_TREE" "$_REPLAY"; then + echo "ERROR: mint aborted before writing anything — the replay of this mint, needed to" + echo " measure the pre-mint changes above, failed (its log is above)." + rm -rf "$_pm"; exit 1 + fi + echo " and a dry run of it on this tree, to find a change the mint would discard..." + if ! _mint_tree "$_WT_TREE" "$_rp/dry"; then + echo "ERROR: mint aborted before writing anything — a dry run of this mint on this" + echo " tree failed (its log is above): a pre-mint change breaks the mint." + rm -rf "$_pm"; exit 1 + fi + _lost=() + _here() { [ -e "$1" ] || [ -L "$1" ]; } + # _result_tree DIR — the mint result in DIR, as the tree git would commit. + _result_tree() { _rg -C "$1" add -A >/dev/null && _rg -C "$1" write-tree; } + _DRY_T="" + _n=0 + for _p in "${PREMINT_A[@]}" "${PREMINT_M[@]}" "${PREMINT_D[@]}"; do + if _here "$_rp/dry/$_p" && _here "$_REPLAY/$_p"; then + if _same "$_rp/dry/$_p" "$_REPLAY/$_p"; then _lost+=("$_p"); fi + elif ! _here "$_rp/dry/$_p" && ! _here "$_REPLAY/$_p" \ + && { _wt ls-files --error-unmatch -- ":(literal)$_p" >/dev/null 2>&1; }; then + # Added or changed here, and gone from both results: an input + # the mint reads and deletes (the docs seed, the overlay), or a + # file in a directory it deletes. Its change had an effect only if + # the result differs without it: this mint, minus that one change, + # is minted again and compared whole (Codex review of #275: an + # edit to build/docs-seed/README.adoc, which is never copied, + # was destroyed without a trace). + [ -n "$_DRY_T" ] || _DRY_T="$(_result_tree "$_rp/dry")" + _n=$((_n + 1)) + _rgi "$_rp/index" read-tree "$_WT_TREE" + if _rgi "$_rp/index" cat-file -e "${PARENT_TREE}:$_p" 2>/dev/null; then + read -r _m _ _s _ <<<"$(_rgi "$_rp/index" ls-tree "$PARENT_TREE" -- "$_p")" + _rgi "$_rp/index" update-index --add --cacheinfo "$_m,$_s,$_p" + else + _rgi "$_rp/index" update-index --force-remove -- "$_p" + fi + _rev_t="$(_rgi "$_rp/index" write-tree)"; rm -f "$_rp/index" + echo " checking that the pre-mint change to $_p has an effect..." + if ! _mint_tree "$_rev_t" "$_rp/without.$_n"; then + echo "ERROR: mint aborted before writing anything — a dry run without the change" + echo " to $_p failed (its log is above)." + rm -rf "$_pm"; exit 1 + fi + if [ "$(_result_tree "$_rp/without.$_n")" = "$_DRY_T" ]; then _lost+=("$_p"); fi + fi + done + rm -rf "$_pm" + if [ "${#_lost[@]}" -gt 0 ]; then + echo "ERROR: mint aborted before writing anything — these paths changed before the mint," + echo " and the mint writes or deletes each itself, so the change would be discarded:" + for _p in "${_lost[@]}"; do echo " $_p"; done + echo " Revert them (or move them aside), mint, then make the change again." + exit 1 + fi + elif [ -n "${_pm:-}" ]; then + rm -rf "$_pm" + 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 @@ -240,6 +845,22 @@ repo-init archetype="": .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 # own placeholder tokens are rendered along with everything else. # @@ -264,48 +885,55 @@ repo-init archetype="": LB=$(printf '\x7b\x7b') RB=$(printf '\x7d\x7d') + # Answers are free text, and the right-hand side of s|…|…| is not: `&` + # inserts the matched token, `\` escapes, `|` ends the expression. A + # description "Tools & proofs" rendered as "Tools proofs" and + # then failed the placeholder gate; a `|` broke the substitution. Every + # answer goes through sed_rhs. (A newline was refused before the first write.) + sed_rhs() { printf '%s' "$1" | sed -e 's/[\\&|]/\\&/g'; } + # Build the sed expression list # Note: using | as delimiter since URLs contain / SED_ARGS=( - -e "s|${LB}PROJECT_NAME${RB}|${PROJECT_NAME}|g" - -e "s|${LB}PROJECT_DESCRIPTION${RB}|${PROJECT_DESCRIPTION}|g" - -e "s|${LB}PROJECT${RB}|${PROJECT_UPPER}|g" - -e "s|${LB}project${RB}|${PROJECT_LOWER}|g" - -e "s|${LB}REPO${RB}|${REPO}|g" - -e "s|${LB}OWNER${RB}|${OWNER}|g" - -e "s|${LB}AUTHOR${RB}|${AUTHOR}|g" - -e "s|${LB}AUTHOR_EMAIL${RB}|${AUTHOR_EMAIL}|g" - -e "s|${LB}AUTHOR_ORG${RB}|${AUTHOR_ORG}|g" - -e "s|${LB}AUTHOR_LAST${RB}|${AUTHOR_LAST}|g" - -e "s|${LB}AUTHOR_FIRST${RB}|${AUTHOR_FIRST}|g" - -e "s|${LB}AUTHOR_INITIALS${RB}|${FIRST_INITIAL}|g" - -e "s|${LB}FORGE${RB}|${FORGE}|g" - -e "s|${LB}CURRENT_YEAR${RB}|${CURRENT_YEAR}|g" - -e "s|${LB}CURRENT_DATE${RB}|${CURRENT_DATE}|g" - -e "s|${LB}DATE${RB}|${CURRENT_DATE}|g" - -e "s|${LB}SECURITY_EMAIL${RB}|${SECURITY_EMAIL}|g" - -e "s|${LB}CONDUCT_EMAIL${RB}|${CONDUCT_EMAIL}|g" + -e "s|${LB}PROJECT_NAME${RB}|$(sed_rhs "${PROJECT_NAME}")|g" + -e "s|${LB}PROJECT_DESCRIPTION${RB}|$(sed_rhs "${PROJECT_DESCRIPTION}")|g" + -e "s|${LB}PROJECT${RB}|$(sed_rhs "${PROJECT_UPPER}")|g" + -e "s|${LB}project${RB}|$(sed_rhs "${PROJECT_LOWER}")|g" + -e "s|${LB}REPO${RB}|$(sed_rhs "${REPO}")|g" + -e "s|${LB}OWNER${RB}|$(sed_rhs "${OWNER}")|g" + -e "s|${LB}AUTHOR${RB}|$(sed_rhs "${AUTHOR}")|g" + -e "s|${LB}AUTHOR_EMAIL${RB}|$(sed_rhs "${AUTHOR_EMAIL}")|g" + -e "s|${LB}AUTHOR_ORG${RB}|$(sed_rhs "${AUTHOR_ORG}")|g" + -e "s|${LB}AUTHOR_LAST${RB}|$(sed_rhs "${AUTHOR_LAST}")|g" + -e "s|${LB}AUTHOR_FIRST${RB}|$(sed_rhs "${AUTHOR_FIRST}")|g" + -e "s|${LB}AUTHOR_INITIALS${RB}|$(sed_rhs "${FIRST_INITIAL}")|g" + -e "s|${LB}FORGE${RB}|$(sed_rhs "${FORGE}")|g" + -e "s|${LB}CURRENT_YEAR${RB}|$(sed_rhs "${CURRENT_YEAR}")|g" + -e "s|${LB}CURRENT_DATE${RB}|$(sed_rhs "${CURRENT_DATE}")|g" + -e "s|${LB}DATE${RB}|$(sed_rhs "${CURRENT_DATE}")|g" + -e "s|${LB}SECURITY_EMAIL${RB}|$(sed_rhs "${SECURITY_EMAIL}")|g" + -e "s|${LB}CONDUCT_EMAIL${RB}|$(sed_rhs "${CONDUCT_EMAIL}")|g" -e "s|${LB}LICENSE${RB}|MPL-2.0|g" -e "s|${LB}CONDUCT_TEAM${RB}|Code of Conduct Committee|g" -e "s|${LB}RESPONSE_TIME${RB}|48 hours|g" -e "s|${LB}MAIN_BRANCH${RB}|main|g" - -e "s|${LB}PROJECT_PURPOSE${RB}|${PROJECT_DESCRIPTION}|g" - -e "s|${LB}PROJECT_ROLE${RB}|${PROJECT_TYPE}|g" - -e "s|${LB}PROJECT_TYPE${RB}|${PROJECT_TYPE}|g" - -e "s|${LB}WEBSITE${RB}|${WEBSITE}|g" - -e "s|${LB}SERVICE_NAME${RB}|${SERVICE_NAME}|g" - -e "s|${LB}PORT${RB}|${PORT}|g" - -e "s|${LB}REGISTRY${RB}|${REGISTRY}|g" - -e "s|${LB}IMAGE${RB}|${REGISTRY}/${SERVICE_NAME}|g" - -e "s|${LB}VERSION${RB}|${VERSION}|g" - -e "s|${LB}EMAIL${RB}|${AUTHOR_EMAIL}|g" - -e "s|${LB}UUID${RB}|${REPO_UUID}|g" - -e "s|${LB}DESCRIPTION${RB}|${PROJECT_DESCRIPTION}|g" + -e "s|${LB}PROJECT_PURPOSE${RB}|$(sed_rhs "${PROJECT_DESCRIPTION}")|g" + -e "s|${LB}PROJECT_ROLE${RB}|$(sed_rhs "${PROJECT_TYPE}")|g" + -e "s|${LB}PROJECT_TYPE${RB}|$(sed_rhs "${PROJECT_TYPE}")|g" + -e "s|${LB}WEBSITE${RB}|$(sed_rhs "${WEBSITE}")|g" + -e "s|${LB}SERVICE_NAME${RB}|$(sed_rhs "${SERVICE_NAME}")|g" + -e "s|${LB}PORT${RB}|$(sed_rhs "${PORT}")|g" + -e "s|${LB}REGISTRY${RB}|$(sed_rhs "${REGISTRY}")|g" + -e "s|${LB}IMAGE${RB}|$(sed_rhs "${REGISTRY}")/$(sed_rhs "${SERVICE_NAME}")|g" + -e "s|${LB}VERSION${RB}|$(sed_rhs "${VERSION}")|g" + -e "s|${LB}EMAIL${RB}|$(sed_rhs "${AUTHOR_EMAIL}")|g" + -e "s|${LB}UUID${RB}|$(sed_rhs "${REPO_UUID}")|g" + -e "s|${LB}DESCRIPTION${RB}|$(sed_rhs "${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") + [ -n "$AUTHOR_EMAIL_ALT" ] && SED_ARGS+=(-e "s|${LB}AUTHOR_EMAIL_ALT${RB}|$(sed_rhs "${AUTHOR_EMAIL_ALT}")|g") + [ -n "$AUTHOR_ORCID" ] && SED_ARGS+=(-e "s|${LB}AUTHOR_ORCID${RB}|$(sed_rhs "${AUTHOR_ORCID}")|g") + [ -n "$OPENSSF_BP_ID" ] && SED_ARGS+=(-e "s|${LB}OPENSSF_BP_ID${RB}|$(sed_rhs "${OPENSSF_BP_ID}")|g") + [ -n "$OPENSSF_BP_ID" ] && SED_ARGS+=(-e "s|${LB}OPENSSF_PROJECT_ID${RB}|$(sed_rhs "${OPENSSF_BP_ID}")|g") # Archetype-determined tokens (ADR-0003): the archetype contract fills # what it can honestly determine. Added BEFORE the UNASSIGNED fallback @@ -347,31 +975,34 @@ repo-init archetype="": # 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 + # with a SHA-256 tool (scripts/uuid-v8.sh) 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 SHA-256 + # tool 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 # 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 + # A replay supplies the uuid the mint recorded ((mint-answers + # :package-uuid)), so the drift gate does not depend on which of bun or + # a SHA-256 tool the checking host has (Codex review of #275). Only a replay: + # an ordinary mint always derives it, so a stray RSR_PACKAGE_UUID in the + # environment cannot write an unrelated identity into Project.toml. + if [ "${RSR_MINT_REPLAY:-0}" = "1" ] && [[ "${RSR_PACKAGE_UUID:-}" =~ ^(UNASSIGNED|[0-9a-f]{8}-[0-9a-f]{4}-8[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})$ ]]; then + PACKAGE_UUID="$RSR_PACKAGE_UUID" + elif 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 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}") + elif command -v sha256sum >/dev/null 2>&1 || command -v shasum >/dev/null 2>&1 || command -v openssl >/dev/null 2>&1; then + # The same ADR-008 profile C id in shell (scripts/uuid-v8.sh, equal to + # standards uuid-v8.js c). No Python: the estate bans it. + PACKAGE_UUID=$("${BASH:-bash}" scripts/uuid-v8.sh julia-package-identity "github.com/${OWNER_LC}/${REPO}") else PACKAGE_UUID=UNASSIGNED fi SED_ARGS+=(-e "s|${LB}PACKAGE_UUID${RB}|${PACKAGE_UUID}|g") - echo " package uuid: ${PACKAGE_UUID} (derived from repo uuid ${REPO_UUID})" + echo " package uuid: ${PACKAGE_UUID} (minted from the birth path, beside chora id ${REPO_UUID})" fi # Optional values with no answer: drop the line that depends on them rather @@ -420,22 +1051,38 @@ repo-init archetype="": # "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. - find . -type f \ - -not -path './.git/*' \ - -not -name 'MPL-2.0.txt' \ - -not -name 'Justfile' -not -name '*.just' \ - -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 + # 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 + # The pass above fills the container tokens too (SERVICE_NAME, PORT, + # REGISTRY), which changes how KYAML quotes them; reformat the configs or + # Estate Rules' "Converted YAML stays KYAML" fails the child. + bash scripts/format-container-kyaml.sh + + # [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\]|$(sed_rhs "${PROJECT_NAME}")|g" -e "s|\[YOUR-NAME/ORG\]|$(sed_rhs "${OWNER}")|g" "$DEED_IN" # --- Instruction-block pass -------------------------------------------- # Delete the "TEMPLATE INSTRUCTIONS (delete this block before publishing)" @@ -453,7 +1100,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 ----------------------------------------- @@ -504,62 +1151,87 @@ repo-init archetype="": # 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" != "rsr-template-repo" ]; then + if [ "$REPO" != "$TEMPLATE_REPO" ]; then SELF_PROV='instantiated-from|parent|upstream|chain =|lineage|minted from|created from|Template: |reject-if-contains' - SELF_NAME_SED="/${SELF_PROV}/!{s|rsr-template-repo#([0-9])|__RSR_TEMPLATE_ISSUE__\\1|g;s|hyperpolymath/rsr-template-repo|${OWNER}/${REPO}|g;s|rsr-template-repo|${REPO}|g;s|__RSR_TEMPLATE_ISSUE__|rsr-template-repo#|g;}" - find . -type f \ - -not -path './.git/*' \ - -not -path './build/just/repo-init.just' \ - -not -path './docs/decisions/*' \ - -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 + # 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. + # The name is matched only where it stands as a whole name: not inside + # a longer word or slug (Codex review of #251). Unbounded, a parent + # named `app` turned "application mapping" into "newlication mnewing". + # A neighbouring letter or digit blocks the match; anything else does + # not, so `_` (sonar.projectKey), `_chora.deed` and + # derived names such as `-checkout` or `rm-` still follow. Each pass + # loops (:label … t label) because a match consumes its right-hand + # neighbour, and marks through a sentinel so a new name that contains + # the old one (Geometry -> Geometry.jl) cannot loop forever. + SELF_NAME_SED="/${SELF_PROV}/!{:i;s@(^|[^A-Za-z0-9])${TEMPLATE_REPO//./\\.}#([0-9])@\\1\\x01I\\x01\\2@;ti;:s;s@(^|[^A-Za-z0-9])${TEMPLATE_SLUG//./\\.}([^A-Za-z0-9]|$)@\\1\\x01S\\x01\\2@;ts;:n;s@(^|[^A-Za-z0-9])${TEMPLATE_REPO//./\\.}([^A-Za-z0-9]|$)@\\1\\x01N\\x01\\2@;tn;s@\\x01S\\x01@${OWNER}/${REPO}@g;s@\\x01N\\x01@${REPO}@g;s@\\x01I\\x01@${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_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." + # ── 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 + # The same declaration forms the identity parser accepts: optional + # `export`, either quote (Codex review of #274). + sed -i -E "$SELF_OWNER_SED" Justfile sonar-project.properties + # The deed's document ids hold the repo slug (ADR-008 profile C, domain + # repo-document). The self-name pass rewrites it, but only when the repo name + # changes; a mint under the SAME name and a different owner skips that pass + # and would keep the template's owner in its ids. Followed here, narrowly. + if [ -f "${REPO}_chora.deed" ]; then + sed -i -E "s|(repo-document:github\\.com/)${TEMPLATE_OWNER//./\\.}/|\\1$(sed_rhs "${OWNER}")/|g" "${REPO}_chora.deed" fi + 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 "" @@ -582,10 +1254,12 @@ repo-init archetype="": # description stays UNASSIGNED for the author. # The split is the whole point: # DERIVABLE -> computed, never guessed (uuid name, owner, canonical-name) - # JUDGEMENT -> left UNASSIGNED, fails loudly until a human chooses (clade) + # JUDGEMENT -> left to the author; a clade placement is an optional identity fact, never written here ID_IN="build/templates/identity.deed.in" - DEED="${REPO}_chora.deed" - [ -f "$DEED" ] || DEED="rsr-template-repo_chora.deed" + # 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 @@ -599,26 +1273,20 @@ repo-init archetype="": ' "$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 chora id, minted above from the birth path and written once as an + # opaque #uuid literal. It replaces the template's own id (whatever its + # literal form) so a child never carries the template's identity. + sed -i -E 's,^( :repo-uuid )#(uuid|u5|u8)"[^"]*",\1#uuid"'"${REPO_UUID}"'",' "$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 check it with:" - echo " uuidgen --sha1 --namespace @url --name \"${FORGE}/${OWNER}/${REPO}\"" - else - echo " uuid: $REPO_UUID" - 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 " 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 the (clade …) comment of $DEED." + echo " uuid: $REPO_UUID" + echo " (the chora id: UUIDv8 of the birth path ${FORGE}/${OWNER}/${REPO}," + echo " minted once and written to :repo-uuid; a rename never changes it)" + echo " clade: none written. Identity is the chora id above; a clade placement is an" + echo " optional identity fact. The 12 are listed in the identity comment" + echo " of $DEED; validate-rsr checks one only if you declare it." fi echo "── Profile & provenance (ADR-0003) ──────────────" @@ -654,7 +1322,7 @@ repo-init archetype="": # 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/canon-pin-check.sh 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 @@ -717,30 +1385,15 @@ repo-init archetype="": # Provenance — the estate's answer-file (ADR-0002 contract shape, used # per ADR-0003 with direction=generated-from-core). # - # repo-init runs INSIDE the template checkout, so the LOCAL git state is - # the truth about what was actually copied. Prefer it. The previous - # implementation read the LIVE remote tip (`git ls-remote ... HEAD`), - # which records where the remote is *now* rather than the tree in hand: - # mint from a branch, or from a checkout with unpushed commits, and - # PROVENANCE named a commit the child never contained. That defeated the - # answer-file's whole purpose. Remote lookup remains only as a fallback, - # and the symref form also recovers the source BRANCH, which was never - # recorded at all (#203). - PARENT_SLUG="hyperpolymath/rsr-template-repo" - PARENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || true) - PARENT_PIN=$(git rev-parse --verify -q HEAD 2>/dev/null || true) - PARENT_TREE=$(git rev-parse --verify -q 'HEAD^{tree}' 2>/dev/null || true) - - if [ -z "$PARENT_PIN" ]; then - # Not a checkout (tarball, shallow copy, or offline): fall back to the - # remote, and recover the branch from the symref. - PARENT_BRANCH=$(git ls-remote --symref "https://github.com/${PARENT_SLUG}.git" HEAD 2>/dev/null \ - | sed -n 's|^ref: refs/heads/\([^[:space:]]*\).*|\1|p' | head -1 || true) - PARENT_PIN=$(git ls-remote "https://github.com/${PARENT_SLUG}.git" HEAD 2>/dev/null | cut -f1 || true) - fi - - # Shape, not presence: a value that is not a 40-hex object name (an - # ls-remote error body, a literal "HEAD" from an unborn branch) is not a pin. + # 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="" @@ -760,12 +1413,12 @@ repo-init archetype="": { echo " ; variant — 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. Placeholder rendering" - echo " ; means many files differ from the parent by design; folding rendered" - echo " ; answers into (normalise) is future work (ADR-0003), so the gate is" - echo " ; informational for minted repos until then." + echo " ; Records what this repo was minted from, for re-templating tooling and" + echo " ; the drift gate. For a minted repo the gate replays the mint from" + echo " ; (provenance) and (mint-answers) and diffs this tree against the" + echo " ; replay (scripts/check-mint-drift.sh), so only edits made after the" + echo " ; mint count. Declare those in (paths) below; the derived files are" + echo " ; declared already, since their own gates keep them fresh." echo " (variant" echo " :project \"${REPO}\"" echo " :schema-version \"0.1.0\"" @@ -779,9 +1432,15 @@ repo-init archetype="": echo " (normalise :rules \"action-pins self-name\")" echo " ; Files a minted repo owns from birth are (paths :diverged …)." echo " (paths" - echo " :added ()" - echo " :removed ()" - echo " :diverged (\"${REPO}_chora.deed\" \"docs/status/ROADMAP.adoc\")))" + # The paths this work tree changed before the mint are added to these + # lists once the mint has moved and deleted what it will (see "What + # this work tree held before the mint", below). + _list() { local _s="" _x; printf ' :%s (' "$1"; shift; for _x in "$@"; do printf '%s"%s"' "$_s" "$_x"; _s=" "; done; printf ')'; } + _removed=("${MINT_REMOVES[@]}") + [ "${DEED_IN#./}" = "${REPO}_chora.deed" ] || _removed+=("${DEED_IN#./}") + _list added; echo + _list removed "${_removed[@]}"; echo + _list diverged "${REPO}_chora.deed" docs/status/ROADMAP.adoc CLAUDE.md docs/architecture/REPOSITORY-MAP.adoc; echo "))" } | put_clause variant if [ "$PARENT_PIN" = "UNASSIGNED" ]; then echo " provenance: $DEED_OUT (variant) — parent-pin UNASSIGNED (offline?)" @@ -832,6 +1491,55 @@ repo-init archetype="": echo " (substitutions :rendered 34 :unassigned ()))" } | put_clause provenance + # ── (mint-answers) — the answers, so the mint can be replayed ─────────── + # Provenance names the template commit; this names what it was rendered + # with. Together they make the mint a function that can be run again: + # scripts/check-mint-drift.sh re-mints the template at the pin with these + # answers and diffs the child against the result, so drift is measured + # exactly instead of through hand-written (normalise) rules (ADR-0003). + # Owner ruling (2026-11-04): record only values the mint already writes + # into the child's own files (names, contacts, description, URLs), so the + # record publishes nothing new. Deed strings escape `\` and `"`. + deed_str() { printf '%s' "$1" | sed -e 's/[\\"]/\\&/g'; } + # The ruling is checked here, not left to a hand-kept list (Codex review of + # #275 found project-type recorded, though no template file renders it): a + # non-empty answer is recorded only if its value appears verbatim in this + # repo's files. An answer left out replays as unanswered; it rendered + # nothing here, so the replay is unchanged. + # Not the template-only trees the mint deletes below (MINT_REMOVES: + # archetypes/, build/docs-seed/): a value found only there is in no file + # the child keeps (CodeRabbit review of #275). + mapfile -t _MINTED < <(mint_files | awk -v r="${MINT_REMOVES[*]:-}" \ + 'BEGIN { n = split(r, p, " ") } { for (i = 1; i <= n; i++) if (index($0, p[i]) == 1) next; print }') + _ANSWERS=() _UNRECORDED="" + for _pair in project-name:PROJECT_NAME repo:REPO owner:OWNER author:AUTHOR \ + author-email:AUTHOR_EMAIL author-org:AUTHOR_ORG \ + author-email-alt:AUTHOR_EMAIL_ALT author-orcid:AUTHOR_ORCID \ + description:PROJECT_DESCRIPTION forge:FORGE \ + security-email:SECURITY_EMAIL conduct-email:CONDUCT_EMAIL \ + project-type:PROJECT_TYPE website:WEBSITE \ + openssf-bp-id:OPENSSF_BP_ID service-name:SERVICE_NAME \ + port:PORT registry:REGISTRY archetype:ARCHETYPE \ + package-uuid:PACKAGE_UUID; do + _var="${_pair#*:}" + _val="${!_var:-}" + if [ -n "$_val" ] && ! grep -qsF -- "$_val" "${_MINTED[@]}" /dev/null; then + _UNRECORDED="${_UNRECORDED} ${_pair%%:*}" + continue + fi + _ANSWERS+=(" :${_pair%%:*} \"$(deed_str "$_val")\"") + done + { + echo " ; mint-answers — what just repo-init was answered on ${CURRENT_DATE}." + echo " ; Read by scripts/check-mint-drift.sh to replay the mint. Every value" + echo " ; here already appears in this repo's rendered files." + echo " (mint-answers" + printf '%s\n' "${_ANSWERS[@]}" + echo " :mint-date \"${CURRENT_DATE}\")" + } | put_clause mint-answers + echo " answers: $DEED_OUT (mint-answers) — replayable with scripts/check-mint-drift.sh" + [ -z "$_UNRECORDED" ] || echo " not recorded, written into no file here:${_UNRECORDED}" + if [ "$CANON_VERSION" = "UNASSIGNED" ]; then echo " provenance: $DEED_OUT (provenance) — canon pin UNASSIGNED" echo " The template deed carried no (canon …) clause, so this repo" @@ -839,24 +1547,64 @@ repo-init archetype="": echo " from a template commit that has one." else echo " provenance: $DEED_OUT (provenance) (canon v${CANON_VERSION} ${CANON_CRITERIA_SHA:0:12})" + CANON_PROPOSED_BY="$(deed_canon proposed-by "$DEED_OUT")" + if [ -n "$CANON_PROPOSED_BY" ]; then + echo " WARNING: the template pins canon v${CANON_VERSION} ahead of its release" + echo " (:proposed-by \"${CANON_PROPOSED_BY}\"). This repo inherits that pin;" + echo " its Canon lockstep passes only while that canon PR is open and" + echo " unchanged, and once it merges. Re-mint or re-pin if it is closed." + fi fi # archetypes/ is template-only overlay data, not part of your repo # (same reason build/templates is removed above). rm -rf archetypes rm -rf build/docs-seed # template-only; its content now lives in docs/ + # Its SD022 exemption goes with it: a child keeping an exemption for a path + # it does not have fails check-hypatia-ignore.sh (stale exemption). The + # block runs from its section header to the entry, plus the blank after. + if [ -f .hypatia-ignore ]; then + awk '/^# ─── build\/docs-seed\/ describes DOWNSTREAM/ { skip = 1 } + skip && /^structural_drift\/SD022:build\/docs-seed\/$/ { skip = 0; blank = 1; next } + skip { next } + blank && /^$/ { blank = 0; next } + { blank = 0; print }' .hypatia-ignore > .hypatia-ignore.mint + mv .hypatia-ignore.mint .hypatia-ignore + fi + # The Hypatia rule-order policy classifies each module .hypatia-ignore + # exempts, and check-hypatia-rule-order.sh fails on a classification with + # no exemption behind it. With no structural_drift exemption left, drop its + # observed_modules entry. The policy is one line of JCS (RFC 8785), so + # removing one object and its comma keeps it canonical; no JSON tool needed. + POLICY=.machine_readable/policies/hypatia-rule-order.json + if [ -f "$POLICY" ] && ! grep -q '^structural_drift/' .hypatia-ignore 2>/dev/null; then + SD_OBJ='[{]"layer":[0-9]+,"module":"structural_drift","rationale":"([^"\\]|\\.)*"[}]' + sed -E -i -e "s/${SD_OBJ},//" -e "s/,${SD_OBJ}//" "$POLICY" + if grep -q '"module":"structural_drift"' "$POLICY"; then + echo "ERROR: could not drop structural_drift from $POLICY; the mint stops here." >&2 + exit 1 + fi + fi - # 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" @@ -867,11 +1615,147 @@ 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 + + # ── Cargo.lock (rust-cli, or any overlay that ships a Cargo.toml) ─────── + # The overlay ships Cargo.toml.in only. The minted rust-ci.yml runs clippy, + # check and test with --locked, which REFUSES to run without a Cargo.lock, + # so a fresh mint failed its own CI on the first push. A lock cannot be + # shipped as a template: it records the package name, which is the repo + # slug and only known now. It is therefore generated here from the + # substituted manifest. With no [dependencies] the resolution needs no + # network, so this works offline; a missing cargo is a hard error, not a + # skipped step (fail loudly: a repo minted without its lock is red in CI). + if [ -f Cargo.toml ] && [ ! -f Cargo.lock ]; then + echo "" + echo "── Cargo.lock ───────────────────────────────────" + if ! command -v cargo >/dev/null 2>&1; then + echo "ERROR: this mint ships a Cargo.toml, so it must also ship a Cargo.lock" + echo " (the minted CI builds with --locked), and cargo is not on PATH." + echo " Install a Rust toolchain (rustup) and re-run the mint." + exit 1 + fi + cargo generate-lockfile || { + echo "ERROR: cargo generate-lockfile failed; the minted CI would fail on --locked." + exit 1 + } + [ -f Cargo.lock ] || { echo "ERROR: cargo reported success but wrote no Cargo.lock."; exit 1; } + echo " generated: Cargo.lock" + 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 --date "$CURRENT_DATE" + 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 + + # ── What this work tree held before the mint ──────────────────────────── + # Declared here, after every step that moves or deletes files, as exactly + # what this tree now differs by from the replay taken before the first write + # (above): the comparison the drift gate makes, so the declaration cannot + # disagree with it, whatever the mint did to a pre-mint change on the way + # (moved, rendered, overwritten, or reached through an edited input) (Codex + # and CodeRabbit review of #275). The files this mint owns are declared + # already. Written into the (variant (paths)) lists by awk, which takes the + # paths as data and escapes \ and " in deed strings. + if [ -n "$_REPLAY" ]; then + _owned=("${REPO}_chora.deed" docs/status/ROADMAP.adoc CLAUDE.md docs/architecture/REPOSITORY-MAP.adoc) + _is_owned() { local _o; for _o in "${_owned[@]}"; do [ "$1" = "$_o" ] && return 0; done; return 1; } + # _files DIR — DIR's own files, one per line (tracked, or untracked and not + # ignored), as the drift gate lists them. This tree is read under its own + # git configuration, as `git add -A` will commit it (a file only a global + # excludesFile ignores is never committed, so never declared); the + # replay under none (CodeRabbit review of #275). + _files() { + { if [ "$1" = "$_REPLAY" ]; then _rg -C "$1" ls-files -z --cached --others --exclude-standard + else git -C "$1" ls-files -z --cached --others --exclude-standard; fi; } \ + | while IFS= read -r -d '' _f; do + if [ -e "$1/$_f" ] || [ -L "$1/$_f" ]; then printf '%s\n' "$_f"; fi + done | LC_ALL=C sort -u + } + _pml="$(mktemp -d)"; : > "$_pml/a"; : > "$_pml/r"; : > "$_pml/d" + _files . > "$_pml/child" + _files "$_REPLAY" > "$_pml/replay" + while IFS= read -r _p; do + _is_owned "$_p" && continue + if ! grep -qxF -- "$_p" "$_pml/replay"; then printf '%s\n' "$_p" >> "$_pml/a" + elif ! _same "$_p" "$_REPLAY/$_p"; then printf '%s\n' "$_p" >> "$_pml/d" + fi + done < "$_pml/child" + while IFS= read -r _p; do + _is_owned "$_p" && continue + grep -qxF -- "$_p" "$_pml/child" || printf '%s\n' "$_p" >> "$_pml/r" + done < "$_pml/replay" + awk -v fa="$_pml/a" -v fr="$_pml/r" -v fd="$_pml/d" ' + function load(file, s, p) { + s = "" + while ((getline p < file) > 0) { + gsub(/\\/, "\\\\", p); gsub(/"/, "\\\"", p) + s = s " \"" p "\"" + } + close(file); return s + } + # insert EXTRA before the ")" that closes the list opened at "(". + function extend(line, extra, i, c, q, open, out) { + open = index(line, "("); q = 0 + for (i = open + 1; i <= length(line); i++) { + c = substr(line, i, 1) + if (q && c == "\\") { i++; continue } + if (c == "\"") q = !q + else if (!q && c == ")") { + out = substr(line, 1, i - 1) extra substr(line, i) + sub(/\( "/, "(\"", out) + return out + } + } + return line + } + BEGIN { A = load(fa); R = load(fr); D = load(fd) } + /^ :added \(/ { $0 = extend($0, A) } + /^ :removed \(/ { $0 = extend($0, R) } + /^ :diverged \(/ { $0 = extend($0, D) } + { print } + ' "$DEED_OUT" > "$_pml/deed" && cat "$_pml/deed" > "$DEED_OUT" + echo " pre-mint: $(wc -l < "$_pml/a") added, $(wc -l < "$_pml/d") diverged, $(wc -l < "$_pml/r") removed;" + echo " declared in $DEED_OUT (variant (paths)) as this repo's own" + rm -rf "$_pml" "$(dirname "$_REPLAY")" fi # ── Regenerate what is DERIVED from the deed and the tree ─────────────── @@ -887,15 +1771,34 @@ repo-init archetype="": # 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 . >/dev/null + bash scripts/gen-repo-map.sh --worktree . >/dev/null echo " repo map: docs/architecture/REPOSITORY-MAP.adoc regenerated" fi + # Replay (scripts/check-mint-drift.sh): every tree-writing step has run, so + # the reconstruction is complete. What follows only checks the tree: the placeholder + # gate (a partial mint made with RSR_ALLOW_PLACEHOLDERS=1 would fail it on + # replay), the www suite (a past RSR_MINT_DATE fails it: security.txt + # expires at the end of the mint year) and the rest. The child's own CI + # runs those checks on the child; the replay exists only to be compared. + if [ "${RSR_MINT_REPLAY:-0}" = "1" ]; then + echo "" + echo "Replay complete (RSR_MINT_REPLAY=1): post-write checks left to the child's CI." + exit 0 + fi + echo "" echo "── Validation ───────────────────────────────────" @@ -929,17 +1832,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='*.deed' --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 @@ -973,15 +1883,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:" @@ -990,23 +1902,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 @@ -1046,7 +1972,7 @@ repo-init archetype="": echo " gh repo edit ${OWNER}/${REPO} --description '' --homepage '${WEBSITE}'" echo " Visibility is fail-closed private; flip deliberately if wanted:" echo " gh repo edit ${OWNER}/${REPO} --visibility public --accept-visibility-change-consequences" - echo " Register in gv-clade-index; required contexts must equal emitted job ids." + echo " Register in chora-registry (formerly gv-clade-index); required contexts must equal emitted job ids." if [ -f ci/.gitlab-ci.yml ]; then echo "" echo " GitLab mirror only: this repo keeps its GitLab CI config at" @@ -1055,5 +1981,7 @@ 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 pin, then arm the drift gate, which replays" + echo " this mint from (provenance) and (mint-answers) and diffs the result:" + echo " scripts/check-template-conformance.sh" + echo " scripts/check-variant-drift.sh " diff --git a/build/just/validate.just b/build/just/validate.just index dc6d724..9a78e1d 100644 --- a/build/just/validate.just +++ b/build/just/validate.just @@ -22,15 +22,25 @@ validate-rsr: ls *_chora.deed >/dev/null 2>&1 || MISSING="$MISSING repo-deed (*_chora.deed)" # .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)" + bash scripts/check-internal-links.sh . >/dev/null || MISSING="$MISSING internal-links(run scripts/check-internal-links.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 @@ -44,17 +54,47 @@ validate-rsr: 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)" ;; + # Identity is the chora (standards A1, rulings R4, U1 to U4, V1): one + # :repo-uuid on the deed header, minted once from the repo's birth + # path and carried as the opaque literal #uuid"", + # version 5 or 8. The legacy name literals #u5"…" and #u8"…" are still + # read and are reported, not failed: their cutover date is the owner's. + RAW_UUID="$(sed -n -E 's/^[[:space:]]*:repo-uuid[[:space:]]+(#(uuid|u5|u8)"[^"]*").*/\1/p' "$DEED" | head -1)" + case "$RAW_UUID" in + '#uuid"'*) + printf '%s' "$RAW_UUID" | grep -Eq '^#uuid"[0-9a-f]{8}-[0-9a-f]{4}-[58][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"$' \ + || MISSING="$MISSING $DEED:repo-uuid(#uuid literal is not a lowercase v5/v8 RFC 9562 id)" + # A version 5 id is v5-identity (standards A1 C10, T30): a warning + # here, an error with RSR_STRICT=1. The chora id is version 8 (V8). + case "$RAW_UUID" in + '#uuid"'????????-????-5*) + if [ "${RSR_STRICT:-0}" = 1 ]; then + MISSING="$MISSING $DEED:repo-uuid(v5-identity)" + else + echo "WARNING: v5-identity: $DEED :repo-uuid $RAW_UUID is a version 5 id; the chora id is #uuid\"\" (standards A1 V8). RSR_STRICT=1 makes this an error." + fi ;; + esac ;; + '#u5"'?*|'#u8"'?*) + echo "NOTE: $DEED :repo-uuid is the legacy literal $RAW_UUID; the chora id is #uuid\"\" (standards A1, V1)." ;; + *) MISSING="$MISSING $DEED:repo-uuid" ;; esac + bash scripts/deed-field.sh --has "$DEED" identity || MISSING="$MISSING $DEED:(identity)" + [ -n "$(field identity primary-forge)" ] || MISSING="$MISSING $DEED:identity:primary-forge" + # Clade placements are identity facts, never the id and never an edict + # (standards A1 §11, ruling W10): no clause and no prefixed name are + # required. A clade that IS declared must still be one of the 12 and agree + # with its name, so a placement cannot point at the wrong shelf. + if bash scripts/deed-field.sh --has "$DEED" clade; then + 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") ;; + "UNASSIGNED|UNASSIGNED"|"|") + echo "NOTE: $DEED (clade …) names no clade; it is optional, so choose one or delete the clause." ;; + *) MISSING="$MISSING $DEED:clade(primary/primary-name not one of the 12, or they disagree)" ;; + esac + fi # CLADE-004/005: the lifecycle phase is a closed set. case "$(field status phase)" in reserved|incubating|active|dormant|merged|superseded|archived|extinct) ;; @@ -65,7 +105,9 @@ validate-rsr: *) MISSING="$MISSING $DEED:maturity:level" ;; esac # The ecosystem clause names the repo the deed's header names. - [ "$(field ecosystem project)" = "$(field "" canonical-name)" ] \ + # Both empty would compare equal; an identity must be present. + [ -n "$(field "" canonical-name)" ] \ + && [ "$(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" @@ -100,12 +142,17 @@ validate-state: 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 + # The same closed sets validate-rsr enforces (CLADE-004/005): a + # misspelt phase or level is not a state. + case "$phase" in + reserved|incubating|active|dormant|merged|superseded|archived|extinct) ;; + *) echo "$DEED: INVALID (status :phase '$phase' is not one of reserved|incubating|active|dormant|merged|superseded|archived|extinct)"; exit 1 ;; + esac + case "$level" in + experimental|alpha|beta|production|lts) ;; + *) echo "$DEED: INVALID (maturity :level '$level' is not one of experimental|alpha|beta|production|lts)"; exit 1 ;; + esac + echo "$DEED: valid (phase $phase, maturity $level)" else echo "No repo state found: the repo deed has no (status …) clause" exit 1 diff --git a/ci/.pre-commit-config.yaml b/ci/.pre-commit-config.yaml index a5c2794..74eb6d8 100644 --- a/ci/.pre-commit-config.yaml +++ b/ci/.pre-commit-config.yaml @@ -36,11 +36,17 @@ repos: pass_filenames: false # --- K9 contract validation --- - - repo: https://github.com/hyperpolymath/k9-pre-commit - rev: 9b82e1f7a6b6c0f99df72c145d7dee8851803c30 # k9-pre-commit @ main 2026-06-23 + # The canonical validator, through the same wrapper CI runs (needs a + # standards checkout beside this repo, or STANDARDS_DIR; skips with a + # notice otherwise). + - repo: local hooks: - id: validate-k9 name: Validate K9 contracts + entry: bash .github/hooks/validate-k9.sh + language: system + pass_filenames: false + files: '\.k9(\.(ncl|lock))?$' # --- Shell linting --- - repo: https://github.com/shellcheck-py/shellcheck-py diff --git a/coordination.k9.ncl b/coordination.k9.ncl index 6f4f987..69721f8 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_INSTALLATION_GUIDE.adoc b/docs/AI_INSTALLATION_GUIDE.adoc index 889850e..434b3b5 100644 --- a/docs/AI_INSTALLATION_GUIDE.adoc +++ b/docs/AI_INSTALLATION_GUIDE.adoc @@ -43,9 +43,15 @@ with no git ancestry; `just repo-init` recovers the template tip via [source,bash] ---- -just repo-init # or: just repo-init +mise trust # allow this repository's mise.toml (no prompt without a TTY) +mise install # the toolchain, including the yq repo-init needs +mise exec -- just repo-init # or: mise exec -- just repo-init ---- +When the mint keeps `build/container/`, `just repo-init` reformats its KYAML +configs after filling them, which needs a yq that writes KYAML (mise.toml +provides it). Without one the mint stops before writing anything. + `just repo-init` renders every `{{TOKEN}}` in the tree, derives the repository identity, writes the provenance files, and removes the template-only directories. @@ -62,7 +68,7 @@ are required; an unset optional answer takes its default. ---- 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 + mise exec -- just repo-init ---- Until 2026-10-14 this mode stubbed the `read` builtin for the whole recipe, so @@ -109,12 +115,15 @@ returns 1 and kills the recipe under `set -e`. [source,bash] ---- -just --list # every recipe resolves (imports are silent on failure) -just check-root-shape # root matches the allowlist +mise exec -- just --list # every recipe resolves (imports are silent on failure) +mise exec -- just check-root-shape # root matches the allowlist bash scripts/check-no-placeholders.sh . -just verify +mise exec -- just verify ---- +An agent's shell is rarely mise-activated, and each command may run in a fresh +shell, so every `just` call here goes through `mise exec --`. + A successful instantiation leaves **no** `{{TOKEN}}` anywhere in the tree, and removes the template-only directories from the minted repository. If `scripts/validate-template.sh` or the end-to-end instantiation test are still diff --git a/docs/HYPATIA-RULE-ORDER.adoc b/docs/HYPATIA-RULE-ORDER.adoc new file mode 100644 index 0000000..e00b55b --- /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@f0b3cd4c464d33e1584f8528c17bce104555e256` +(`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 3f1fad4..ce4330c 100644 --- a/docs/MAINTAINERS.adoc +++ b/docs/MAINTAINERS.adoc @@ -58,6 +58,6 @@ For questions about project governance, open an issue in this repository. == See also * link:GOVERNANCE.adoc[Governance model] -* link:../.github/CODE_OF_CONDUCT.md[Code of Conduct] -* link:../.github/CONTRIBUTING.md[Contributing guide] +* link:../CODE_OF_CONDUCT.adoc[Code of Conduct] +* link:../CONTRIBUTING.adoc[Contributing guide] * link:attribution/CODEOWNERS.adoc[Code owners] diff --git a/docs/SETUP.adoc b/docs/SETUP.adoc index 34b5e47..e7977b0 100644 --- a/docs/SETUP.adoc +++ b/docs/SETUP.adoc @@ -64,8 +64,11 @@ Or with OPSM, the odds-and-sods package manager (see <>): `opsm install https://github.com/hyperpolymath/sholes.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. +button (or clone as above), install the toolchain (step 3), then run +`mise exec -- just repo-init` (plain `just repo-init` once mise is activated); +it fills every placeholder token, and needs the toolchain's yq to keep the container +configs KYAML (it stops before writing anything without one). The steps below work +the same afterwards. == 3. Install the toolchain @@ -75,6 +78,10 @@ mise trust # allow this repository's mise.toml mise install # installs everything mise.toml lists, at mise.lock's versions ---- +The `just` commands from here on expect the toolchain on `PATH`: activate mise in +your shell (`eval "$(mise activate bash)"`, or your shell's equivalent), or run each +one as `mise exec -- just …`. + That installs: [cols="1,2,3"] diff --git a/docs/governance/CRG-CRITERIA.adoc b/docs/governance/CRG-CRITERIA.adoc index e37dce1..4f50a1d 100644 --- a/docs/governance/CRG-CRITERIA.adoc +++ b/docs/governance/CRG-CRITERIA.adoc @@ -38,4 +38,4 @@ This document defines the quality assessment criteria for individual project com 6. Has it been tested on 6+ diverse external targets? (Broad → **B**) 7. Do external users confirm it works and is useful? (Field-proven → **A**) -See link:READINESS.adoc[READINESS.adoc] for the current project assessment. +See link:../status/READINESS.adoc[READINESS.adoc] for the current project assessment. diff --git a/docs/onboarding/QUICKSTART-DEV.adoc b/docs/onboarding/QUICKSTART-DEV.adoc index 6b93617..f93ad58 100644 --- a/docs/onboarding/QUICKSTART-DEV.adoc +++ b/docs/onboarding/QUICKSTART-DEV.adoc @@ -99,6 +99,6 @@ Or read the repo deed (`*_chora.deed` at root) and `.claude/CLAUDE.md` directly. == Get Help -* **Architecture**: link:EXPLAINME.adoc[EXPLAINME.adoc] +* **Architecture**: link:../EXPLAINME.adoc[EXPLAINME.adoc] * **Wiki**: https://github.com/hyperpolymath/sholes/wiki * **Report issue**: `just help-me` diff --git a/docs/onboarding/QUICKSTART-USER.adoc b/docs/onboarding/QUICKSTART-USER.adoc index 97e42fd..fc5ce18 100644 --- a/docs/onboarding/QUICKSTART-USER.adoc +++ b/docs/onboarding/QUICKSTART-USER.adoc @@ -120,6 +120,6 @@ You will be asked: == Next Steps -* Read the link:README.adoc[README] for full feature overview -* Read the link:EXPLAINME.adoc[EXPLAINME] for architecture and design decisions +* Read the link:../../README.adoc[README] for full feature overview +* Read the link:../EXPLAINME.adoc[EXPLAINME] for architecture and design decisions * Try `just tour` for a guided walkthrough diff --git a/docs/onboarding/llm-warmup-maintainer.adoc b/docs/onboarding/llm-warmup-maintainer.adoc index 304639e..74a2ad7 100644 --- a/docs/onboarding/llm-warmup-maintainer.adoc +++ b/docs/onboarding/llm-warmup-maintainer.adoc @@ -11,14 +11,14 @@ 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 +`build/just/provision*.{just,sh}` and `build/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`. +* `just toolchain-refresh` — `mise up --bump`, `mise lock`, re-pin `build/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. diff --git a/docs/onboarding/llm-warmup-user.adoc b/docs/onboarding/llm-warmup-user.adoc index 301be44..2b5eee7 100644 --- a/docs/onboarding/llm-warmup-user.adoc +++ b/docs/onboarding/llm-warmup-user.adoc @@ -34,9 +34,14 @@ 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`), + author and licence contact, replaces every placeholder token, then validates the result. `just repo-init julia-library` applies the one archetype overlay shipped in `archetypes/`. ++ +The token list is the `placeholders` document (role `placeholders`; id `repo-document:github.com//#placeholders`), registered under +`(documents)` in `*_chora.deed` (a minted repository no longer carries it). +If this page is gone, link:../MAINTAINERS.adoc[contact the maintainer], or ask an AI assistant to read +`*_chora.deed` for its current location. . Run `just validate` (structure + metadata) and `just doctor` (toolchain). An AI running `repo-init` sets `RSR_NON_INTERACTIVE=1` and passes the answers as 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 0000000..616cfad --- /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; `sholes` 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 := "sholes"`, `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 "sholes"' \ + --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 "sholes"` | 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 "sholes"` | 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/PROOF-NEEDS.adoc b/docs/status/PROOF-NEEDS.adoc index ba3d8a7..1708eac 100644 --- a/docs/status/PROOF-NEEDS.adoc +++ b/docs/status/PROOF-NEEDS.adoc @@ -26,7 +26,9 @@ == Mandatory Proofs (All RSR Repos) -These proofs come from the sholes and MUST be present in every repo: +These proofs are inherited from the RSR template spine and MUST be present in every repo. +(Name no repository here: the mint's self-name pass rewrites the template's +name into the child's, which once made this line credit the child.) === ABI/FFI Boundary Proofs (Idris2) @@ -48,7 +50,7 @@ These proofs come from the sholes and MUST be present in every repo: | # | Proof | Status | File | TP-1 | Core data type well-formedness | Needed | `verification/proofs/idris2/Types.idr` -| TP-2 | Public API type safety (exported functions) | Needed | `verification/proofs/lean4/ApiTypes.lean` +| TP-2 | Public API type safety (exported functions). PROOF-POLICY §1 assigns APIs to Idris2; the Lean file is the shipped example until a project ports it | Needed | `verification/proofs/lean4/ApiTypes.lean` |=== == Project-Specific Proofs @@ -85,18 +87,24 @@ CI will reject any PR introducing these patterns (enforced by `panic-attack assa == Prover Selection Guide +The mapping is set by `3-practice/PROOF-POLICY.adoc` §1 in +`metadatastician/standards`, not by this table: where they differ, the policy +wins. `verification/proofs/README.adoc` maps it onto this tree. + [cols="2,2,3", options="header"] |=== -| Use Case | Recommended Prover | Why - -| ABI/FFI boundaries | *Idris2* | Dependent types model layouts precisely -| Type system proofs | *Coq* or *Lean4* | Mature proof assistants for metatheory -| Algebraic properties | *Lean4* | Good mathlib support -| Inductive/coinductive | *Agda* | Native support for (co)induction -| Distributed systems | *TLA+* | Model checking for protocols -| Numerical properties | *Isabelle* | Strong real analysis library +| Code or obligation | Prover | Notes + +| Theory (type systems, lattices, metatheory, algebra) | *Agda*, rechecked in *Rocq* and *Lean* | Canonical invocation `agda --safe --without-K --cubical-compatible` (§2.1). The Rocq leg is Dedukti transport first, hand re-proof as the fallback; the Lean leg is re-proved until a released Lambdapi Lean exporter exists (§2). *No Mathlib*: a missing lemma is proved in Lean core. +| APIs, ABIs, engineering properties | *Idris2* | `%default total`; no `believe_me` or `assert_total`. +| Rust code | *Creusot* with *Pearlite* contracts, and *Verus* | On the code. Kani for `unsafe` and FFI seams, and Aeneas where Rust implements an Agda theorem, alongside and never instead (§1.2, §4.1). +| Ada code | *SPARK* | GNATprove. +| Concurrency protocols | *TLA+* (a §4 exception) | A finite model check is `tested-only`, with its bounds, not `proven`. |=== +Grades are §8 Proof Witness Grades (`PWG-3` … `PWG-1`), recorded per claim in +`PROOF-STATUS.adoc` and derived from receipts. + == Proof File Locations ---- @@ -104,11 +112,11 @@ verification/proofs/ ├── idris2/ # Idris2 proofs (ABI, dependent types) │ ├── ABI/ # ABI-specific proofs │ └── *.idr # Project-specific Idris2 proofs -├── lean4/ # Lean4 proofs (algebra, lattices) +├── lean4/ # Lean recheck legs of Agda theory (core only, no Mathlib) │ └── *.lean -├── agda/ # Agda proofs (induction, metatheory) +├── agda/ # Agda theory proofs (the source of truth, §2) │ └── *.agda -├── coq/ # Coq proofs (type systems, compilation) +├── coq/ # Rocq recheck legs of Agda theory │ └── *.v └── tlaplus/ # TLA+ specs (distributed protocols) └── *.tla diff --git a/mise.toml b/mise.toml index 730dbc3..e83acf0 100644 --- a/mise.toml +++ b/mise.toml @@ -18,5 +18,6 @@ lockfile = true [tools] just = "latest" shellcheck = "latest" +yq = "latest" # scripts/kyaml-format.sh (KYAML configs) trivy = "latest" # just deps-audit zig = "latest" diff --git a/scripts/adopt-canon-lockstep.sh b/scripts/adopt-canon-lockstep.sh new file mode 100755 index 0000000..a973c0e --- /dev/null +++ b/scripts/adopt-canon-lockstep.sh @@ -0,0 +1,94 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# adopt-canon-lockstep.sh: give a minted repository this template's current +# Canon lockstep job and its decision script, and nothing else. +# +# WHY: instances minted before the job called scripts/canon-pin-check.sh carry +# an inline copy of it (9 distinct copies across 30 repos, census 2026-11-12). +# Those copies demand equality with the canon on standards main, so a canon +# release turns an instance red although its pin is provenance, "the canon +# release it was cut from" (repo-init.just). The template's job now passes an +# older pin with a notice (scripts/canon-pin-check.sh). Copying the whole +# dogfood-gate.yml would overwrite whatever else the instance changed, so only +# the `canon-lockstep:` job block is replaced. +# +# What it writes, and nothing else: +# * the `canon-lockstep:` job in /.github/workflows/dogfood-gate.yml, +# replaced by the template's own block (read from this checkout, so there +# is one source); +# * /scripts/canon-pin-check.sh, copied from this checkout. +# +# FAIL-CLOSED (exit 1, nothing written): no dogfood-gate.yml; more than one +# `canon-lockstep:` key; or a repo actions.lock whose dogfood-gate.yml entry +# does not already list every action the template block uses (the runner +# refuses a workflow whose actions the lock does not cover). A repo with no +# `canon-lockstep:` job is left alone (exit 0): this tool repairs the job, it +# does not add it. +# +# Usage: adopt-canon-lockstep.sh +# Exit: 0 adopted or already current or no job; 1 refused; 2 usage. +set -euo pipefail + +TPL="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +[ "$#" -eq 1 ] && [ -d "$1" ] || { sed -n '25,26p' "$0" >&2; exit 2; } +REPO="$(cd "$1" && pwd)" +WF="$REPO/.github/workflows/dogfood-gate.yml" +LOCK="$REPO/.github/workflows/actions.lock" +refuse() { echo "adopt-canon-lockstep: REFUSED ($*); nothing written" >&2; exit 1; } + +# The job key, plain or quoted, with an optional trailing comment. +START_RE="^ [\"']?canon-lockstep[\"']?:[[:space:]]*(#.*)?\$" + +# job_block : the canon-lockstep job, from its key to the line before +# the next key. Any non-comment line at two spaces of indent (the next job, +# however it is written: `build:`, `build: # note`, `"build":`) or at column +# 0 ends it. Comment and blank lines just before that boundary belong to the +# next job's header, so they are not part of this block. +job_block() { + awk -v S="$START_RE" ' + !f && $0 ~ S { f = 1; print; next } + f && (/^ [^ #]/ || /^[^ #]/) { exit } + f && (/^ ?#/ || /^ #/ || /^[[:space:]]*$/) { buf = buf $0 "\n"; next } + f { printf "%s", buf; buf = ""; print }' "$1" +} + +[ -f "$WF" ] || refuse "no .github/workflows/dogfood-gate.yml" +n=$(grep -cE "$START_RE" "$WF" || true) +[ "$n" -le 1 ] || refuse "$n canon-lockstep jobs in dogfood-gate.yml" +[ "$n" -eq 1 ] || { echo "adopt-canon-lockstep: no canon-lockstep job; left alone"; exit 0; } + +tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT +job_block "$TPL/.github/workflows/dogfood-gate.yml" > "$tmp/new" +[ -s "$tmp/new" ] || refuse "the template has no canon-lockstep job to copy" +# Trailing blank lines belong to the gap between jobs, not to the job. +sed -i -e :a -e '/^[[:space:]]*$/{$d;N;ba' -e '}' "$tmp/new" + +# Every action the template block uses must already be locked for this workflow. +if [ -f "$LOCK" ]; then + awk -v k=" '.github/workflows/dogfood-gate.yml':" '$0==k{f=1;next} f&&!/^ - /{exit} f' "$LOCK" \ + | grep -oE "'[^']+'" | tr -d "'" | awk '{i=index($0,"@"); print tolower(substr($0,1,i-1)) substr($0,i)}' \ + | sort -u > "$tmp/locked" + grep -oE 'uses:[[:space:]]*[A-Za-z0-9_.-]+/[A-Za-z0-9_./-]+@[0-9a-f]{40}' "$tmp/new" \ + | sed -E 's/uses:[[:space:]]*//; s#^([^/]+/[^/@]+)[^@]*@#\1@#' \ + | awk '{i=index($0,"@"); print tolower(substr($0,1,i-1)) substr($0,i)}' | sort -u > "$tmp/needed" + missing=$(comm -23 "$tmp/needed" "$tmp/locked" | tr '\n' ' ') + [ -z "$missing" ] || refuse "actions.lock does not list for dogfood-gate.yml: ${missing% }" +fi + +job_block "$WF" > "$tmp/old" +sed -i -e :a -e '/^[[:space:]]*$/{$d;N;ba' -e '}' "$tmp/old" +if cmp -s "$tmp/old" "$tmp/new" && cmp -s "$TPL/scripts/canon-pin-check.sh" "$REPO/scripts/canon-pin-check.sh" 2>/dev/null; then + echo "adopt-canon-lockstep: already current"; exit 0 +fi + +# Replace the old block's lines with the new block, keeping everything else. +start=$(grep -nE "$START_RE" "$WF" | cut -d: -f1) +len=$(wc -l < "$tmp/old") +{ head -n "$((start - 1))" "$WF"; cat "$tmp/new"; tail -n +"$((start + len))" "$WF"; } > "$tmp/wf" +mkdir -p "$REPO/scripts" +cp "$tmp/wf" "$WF" +cp "$TPL/scripts/canon-pin-check.sh" "$REPO/scripts/canon-pin-check.sh" +chmod +x "$REPO/scripts/canon-pin-check.sh" +echo "adopt-canon-lockstep: canon-lockstep job and scripts/canon-pin-check.sh now match the template" diff --git a/scripts/bench-stats.jq b/scripts/bench-stats.jq new file mode 100644 index 0000000..55f62eb --- /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/campaigns/repo-map-trim.campaign b/scripts/campaigns/repo-map-trim.campaign new file mode 100644 index 0000000..6298fdc --- /dev/null +++ b/scripts/campaigns/repo-map-trim.campaign @@ -0,0 +1,29 @@ +# SPDX-License-Identifier: MPL-2.0 +# +# repo-map-trim.campaign: carry the gen-repo-map.sh comment-trim fix to the +# estate repositories that already hold a template copy of the script. +# +# TARGETED, NOT ESTATE-WIDE. A dry run on 2026-11-10 over the 325 repositories +# in gv-clade-index found the script in 6 of them; the other 263 would have had +# it ADDED, which this campaign must not do. Run it only with this repos file: +# +# catachresis-colloquium/enterglide-ncc-137-k +# catachresis-colloquium/planer-1 +# catachresis-colloquium/stealth-glider-ecosystem +# catachresis-colloquium/tardis-rule-disruption +# catachresis-colloquium/x15-rocket-glider +# +# (These 5 moved from metadatastician to catachresis-colloquium. Use the new +# names: a repo-scoped GitHub proxy (as in Claude Code cloud sessions) does +# not follow the redirect, so pushes to the old names are refused.) +# +# Each holds a copy that matches an earlier template version (no local edits), +# and regenerating its map with the fixed script changes nothing, so no gate +# goes red. hyperpolymath/oblibeny is left out on purpose: its map changes by +# 2 lines and its CI checks the map, so it needs the script and a +# `just repo-map` in the same commit, which a campaign cannot do. +[meta] +name = chore/rsr-repo-map-trim +description = keep allowlist comments whole in the repository map (rsr-template-repo PR 316) +[paths] +scripts/gen-repo-map.sh diff --git a/scripts/canon-pin-check.sh b/scripts/canon-pin-check.sh new file mode 100755 index 0000000..008b309 --- /dev/null +++ b/scripts/canon-pin-check.sh @@ -0,0 +1,213 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# canon-pin-check.sh — decide whether a repo deed's (canon …) pin implements a +# canon.lock. The decision only: no network. dogfood-gate.yml `Canon lockstep` +# fetches the locks and the canon PR's state and calls this; the tests in +# tests/workflows/canon_pin_check_test.sh drive it with fixtures. +# +# Two-phase lockstep. canon.lock [canon.lockstep].order is +# "spine-adopts-then-canon-releases", and the spine's adoption necessarily pins +# hashes that exist only in the unmerged canon PR. So the spine may adopt a +# canon AHEAD of its release by naming that PR in the clause: +# +# (canon :version "2.1.6" :criteria-sha256 "…" :gates-sha256 "…" +# :proposed-by "metadatastician/standards#1440" …) +# +# The pin then has to equal canon.lock at that PR's head, and the PR has to be +# open. When the PR merges, the pin equals the released canon.lock and the +# field is spent (a notice asks for it to be dropped). When the PR is closed +# unmerged or amended, the pin names a canon that is not released, and this +# fails. Standards Gate A checks the other side: a canon PR that changes +# canon.lock is not mergeable until the spine's main pins it. +# +# Spine and instance. Exact equality is the SPINE's invariant: the template +# is what implements the canon. A repo minted from the template carries the +# pin as PROVENANCE, "the canon release it was cut from" (repo-init.just), +# and a provenance record cannot follow later releases. Requiring equality +# there turned every instance red on every push the moment standards +# released a newer canon (2.1.5 reddened every 2.1.2-2.1.4 instance). So an +# instance whose pin names an OLDER version passes with a notice naming the +# release it lags. The spine is recognised by GITHUB_REPOSITORY_ID, which +# survives a transfer; with no id in the environment (a local run) the +# check stays strict. +# +# Usage: +# canon-pin-check.sh released +# 0 the pin equals canon.lock (a spent :proposed-by gives a notice), +# or, outside the spine, the pin names an older canon version +# (an older instance pin with :proposed-by also gives 3, plus a +# LAGS_BEHIND= line: only a MERGED proposal makes it spent) +# 3 the pin differs and the clause names a canon PR: the caller must +# check that PR; stdout carries the line PROPOSED_BY= +# 1 the pin differs and names no canon PR (in an instance: the pin +# names the released version or a later one, with other hashes) +# 2 malformed input (no single clause, a pin of the wrong shape, a +# malformed :proposed-by, an unreadable lock) +# canon-pin-check.sh pending [] +# (also 0 when is "merged", the pin equals that lock, and an +# instance pin is older than : the proposal is spent) +# 0 is "open" and the pin equals that lock +# 1 otherwise +# 2 malformed input +# Both modes print a Markdown table of the comparison to stdout. + +set -euo pipefail + +usage() { sed -n '36,50p' "$0" >&2; exit 2; } + +# The spine's repository id (hyperpolymath/rsr-template-repo). An id, not a +# slug: a slug changes on a transfer, an id does not. +SPINE_REPOSITORY_ID=1306804488 + +# version_lt : true when semver a sorts strictly before b. +version_lt() { + [ "$1" != "$2" ] && [ "$(printf '%s\n%s\n' "$1" "$2" | sort -t. -k1,1n -k2,2n -k3,3n | head -1)" = "$1" ] +} + +# 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. The SAME function is in build/just/repo-init.just and +# standards scripts/check-canon-lockstep.sh; keep them 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 +} + +# canon_key : a scalar under [canon]. +canon_key() { + awk -v key="$1" ' + /^[[:space:]]*#/ { next } + /^\[/ { f = ($0 == "[canon]") ? 1 : 0; next } + f && $0 ~ "^[[:space:]]*" key "[[:space:]]*=" { + sub(/^[^=]*=[[:space:]]*/, ""); sub(/[[:space:]]*#.*/, ""); gsub(/^["[:space:]]+|["[:space:]]+$/, ""); print; exit + }' "$2" +} + +# artefact_hash : the sha256 of [canon.artifacts] . +artefact_hash() { + awk -v key="$1" ' + /^[[:space:]]*#/ { next } + $0 ~ "^" key "[[:space:]]*=" { f = 1 } + f { buf = buf " " $0 } + f && /sha256[[:space:]]*=/ { print buf; exit } + ' "$2" | grep -oE '[0-9a-f]{64}' | head -1 || true +} + +HEX='[0-9a-f]{64}' +SEMVER='[0-9]+\.[0-9]+\.[0-9]+' +PR_REF='(hyperpolymath|metadatastician)/standards#[1-9][0-9]*' + +# compare