diff --git a/.github/GOVERNANCE.md b/.github/GOVERNANCE.md index 6cdeb93..3605a14 100644 --- a/.github/GOVERNANCE.md +++ b/.github/GOVERNANCE.md @@ -44,7 +44,7 @@ release schedules, contributor access, and community standards. - ADR statuses: `proposed`, `accepted`, `deprecated`, `superseded`, `rejected`. - ADRs provide a historical record of why decisions were made and what alternatives were considered. -- See `.machine_readable/META.a2ml` for the machine-readable ADR index. +- See `.machine_readable/descriptiles/META.a2ml` for the machine-readable ADR index. --- diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 3db2819..6472847 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -26,9 +26,9 @@ ### As Applicable -- [ ] `.machine_readable/STATE.a2ml` updated (if project state changed) -- [ ] `.machine_readable/ECOSYSTEM.a2ml` updated (if integrations changed) -- [ ] `.machine_readable/META.a2ml` updated (if architectural decisions changed) +- [ ] `.machine_readable/descriptiles/STATE.a2ml` updated (if project state changed) +- [ ] `.machine_readable/descriptiles/ECOSYSTEM.a2ml` updated (if integrations changed) +- [ ] `.machine_readable/descriptiles/META.a2ml` updated (if architectural decisions changed) - [ ] Documentation updated for user-facing changes - [ ] `TOPOLOGY.md` updated (if architecture changed) - [ ] `CHANGELOG` or release notes updated diff --git a/.github/workflows/actions.lock b/.github/workflows/actions.lock index 8f5ccd3..ed2ab1b 100644 --- a/.github/workflows/actions.lock +++ b/.github/workflows/actions.lock @@ -24,8 +24,7 @@ workflows: '.github/workflows/labels.yml': [] '.github/workflows/lock-sync-gate.yml': [] '.github/workflows/main-estate-audit.yml': - - 'actions/checkout@v7.0.1' - - 'hyperpolymath/cicd-suite@main' + - 'hyperpolymath/cicd-suite@354c425571c1f27b66dd141daeb0e90fa0c26dd9' '.github/workflows/mirror.yml': - 'actions/checkout@v7.0.1' - 'dtolnay/rust-toolchain@master' @@ -115,9 +114,29 @@ dependencies: commit: 'sha1-cdf488f595d80d6e07e03d4674febd5ab45fa938' owner_id: 9919 repo_id: 259445878 - 'hyperpolymath/cicd-suite@main': - ref: 'main' - commit: 'sha1-5a10b72e574ef63855fafd4568a4c178657f3294' + 'hyperpolymath/cicd-suite@354c425571c1f27b66dd141daeb0e90fa0c26dd9': + ref: '354c425571c1f27b66dd141daeb0e90fa0c26dd9' + commit: 'sha1-354c425571c1f27b66dd141daeb0e90fa0c26dd9' + owner_id: 6759885 + repo_id: 1326697643 + uses: + - 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1' + - 'hyperpolymath/cicd-suite@35868f090e4e42b142374d156f2d49a22ad577fd' + - 'hyperpolymath/cicd-suite@88c55e28f37b8dfc5a435e86f548737997746cc9' + - 'hyperpolymath/cicd-suite@c519c4520afbfe48f16aceb0706d7cfb1d649994' + 'hyperpolymath/cicd-suite@35868f090e4e42b142374d156f2d49a22ad577fd': + ref: '35868f090e4e42b142374d156f2d49a22ad577fd' + commit: 'sha1-35868f090e4e42b142374d156f2d49a22ad577fd' + owner_id: 6759885 + repo_id: 1326697643 + 'hyperpolymath/cicd-suite@88c55e28f37b8dfc5a435e86f548737997746cc9': + ref: '88c55e28f37b8dfc5a435e86f548737997746cc9' + commit: 'sha1-88c55e28f37b8dfc5a435e86f548737997746cc9' + owner_id: 6759885 + repo_id: 1326697643 + 'hyperpolymath/cicd-suite@c519c4520afbfe48f16aceb0706d7cfb1d649994': + ref: 'c519c4520afbfe48f16aceb0706d7cfb1d649994' + commit: 'sha1-c519c4520afbfe48f16aceb0706d7cfb1d649994' owner_id: 6759885 repo_id: 1326697643 uses: diff --git a/.github/workflows/dependabot-automerge.yml b/.github/workflows/dependabot-automerge.yml index c1dc228..214150c 100644 --- a/.github/workflows/dependabot-automerge.yml +++ b/.github/workflows/dependabot-automerge.yml @@ -42,8 +42,7 @@ on: types: [opened, reopened, synchronize] permissions: - contents: read # needed to enable auto-merge - pull-requests: write # needed to approve + contents: read # NB: keep narrow — do NOT add secrets: read or id-token: write here. jobs: @@ -51,6 +50,12 @@ jobs: # Only run for PRs actually authored by Dependabot. if: github.actor == 'dependabot[bot]' && github.event.pull_request.user.login == 'dependabot[bot]' runs-on: ubuntu-latest + # Only this job writes: `gh pr review --approve` needs pull-requests: write, + # and `gh pr merge --auto` needs contents: write (with contents: read the + # merge request is refused). + permissions: + contents: write + pull-requests: write steps: - name: Fetch Dependabot metadata diff --git a/.github/workflows/main-estate-audit.yml b/.github/workflows/main-estate-audit.yml index e249814..262042b 100644 --- a/.github/workflows/main-estate-audit.yml +++ b/.github/workflows/main-estate-audit.yml @@ -1,93 +1,35 @@ # This workflow is managed by gh actions-lock. - +# SPDX-License-Identifier: MPL-2.0 name: Central Estate CI/CD Audit +# Thin caller of the estate audit, which lives in hyperpolymath/cicd-suite as +# a reusable workflow and reports five component checks: governance, +# hygiene, manifests, languages, advisory. Do not copy the audit's steps in +# here. A copy freezes this repository at whatever cicd-suite commit its +# actions.lock happened to hold, and fixes made upstream never arrive. +# +# The pin is a full SHA, advanced weekly by track-estate-audit.yml (a PR +# whose own run of this audit is the check). +# +# ⚠ ONBOARDED in actions.lock at the full SHA, with the cicd-suite gate +# commits it reaches recorded as dependencies, the same form this +# repository's other cross-repository callers use (hypatia-scan.yml, +# secret-scanner.yml, scorecard.yml call hyperpolymath/standards at a full +# SHA and start normally). cicd-suite's own header records that an +# onboarded @main or tag ref startup-fails; a full SHA is not that case. +# If this run ever startup-fails with zero jobs, de-onboard it with +# cicd-suite/scripts/deonboard-estate-audit.sh and drop its entry from +# scripts/check-lock-sync.sh's expectations. + on: push: branches: [ "main" ] pull_request: branches: [ "main" ] +permissions: + contents: read + jobs: - estate-audit: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v7.0.1 - - - name: Required Files Gate - uses: hyperpolymath/cicd-suite/actions/required-files-check@main - - - name: Code Hygiene Gate - uses: hyperpolymath/cicd-suite/actions/code-hygiene-check@main - - - name: Manifest Validation Gate - uses: hyperpolymath/cicd-suite/actions/manifest-check@main - - - name: Idris2 ABI Purity Gate - uses: hyperpolymath/cicd-suite/actions/idris2-abi-check@main - - - name: Zig UnifiedApiAdapter API Gate - uses: hyperpolymath/cicd-suite/actions/zig-unified-api-adapter-check@main - - - name: Contractile Validation Gate - uses: hyperpolymath/cicd-suite/actions/contractile-validation-check@main - - - name: Recipes Set Validation Gate - uses: hyperpolymath/cicd-suite/actions/recipes-set-check@main - - - name: Affirmation Document Gate - uses: hyperpolymath/cicd-suite/actions/affirmation-check@main - - - name: Academic Referencing Gate - uses: hyperpolymath/cicd-suite/actions/referencing-check@main - - - name: Semantic Audit Gate - uses: hyperpolymath/cicd-suite/actions/semantic-audit-check@main - - - name: SPDX License Gate - uses: hyperpolymath/cicd-suite/actions/spdx-license-check@main - - - name: Proof Runner Gate - uses: hyperpolymath/cicd-suite/actions/proof-runner-check@main - - - name: PRAT Testing Gate - uses: hyperpolymath/cicd-suite/actions/prat-check@main - - - name: Panic Attack & Pons Gate - uses: hyperpolymath/cicd-suite/actions/custom-tools-check@main - - - name: WWW & Well-Known Compliance Gate - uses: hyperpolymath/cicd-suite/actions/www-compliance-check@main - - - name: BoJ Cartridge Validation Gate - uses: hyperpolymath/cicd-suite/actions/boj-cartridge-check@main - - - name: Formatting Validation Gate - uses: hyperpolymath/cicd-suite/actions/formatting-check@main - - - name: Accreditations & Badges Gate - uses: hyperpolymath/cicd-suite/actions/badges-check@main - - - name: Metrics Extraction Gate - uses: hyperpolymath/cicd-suite/actions/metrics-check@main - - - name: Linguist & Banned Languages Gate - uses: hyperpolymath/cicd-suite/actions/linguist-check@main - - - name: Test & Benchmarks Dashboard Gate - uses: hyperpolymath/cicd-suite/actions/tests-benches-check@main - - - name: Hosting & Site Status Gate - uses: hyperpolymath/cicd-suite/actions/hosting-check@main - - - name: Git-Sea Analytics Gate - uses: hyperpolymath/cicd-suite/actions/gitsea-check@main - - - name: Trust & Humans Validation Gate - uses: hyperpolymath/cicd-suite/actions/trust-humans-check@main - - - name: Are We UnAPI Gate (Secret Scanning) - uses: hyperpolymath/cicd-suite/actions/secrets-check@main - - - name: Reasonably Good Token Validation Gate - uses: hyperpolymath/cicd-suite/actions/vaulted-tokens-check@main + estate: + uses: hyperpolymath/cicd-suite/.github/workflows/main-estate-audit.yml@354c425571c1f27b66dd141daeb0e90fa0c26dd9 # cicd-suite main diff --git a/.github/workflows/openssf-compliance.yml b/.github/workflows/openssf-compliance.yml index 924a733..225c052 100644 --- a/.github/workflows/openssf-compliance.yml +++ b/.github/workflows/openssf-compliance.yml @@ -74,11 +74,11 @@ jobs: exit 1 fi - if [ ! -f ".machine_readable/STATE.a2ml" ]; then - echo "::error::.machine_readable/STATE.a2ml is required" + if [ ! -f ".machine_readable/descriptiles/STATE.a2ml" ]; then + echo "::error::.machine_readable/descriptiles/STATE.a2ml is required" exit 1 fi - echo ".machine_readable/STATE.a2ml: OK" + echo ".machine_readable/descriptiles/STATE.a2ml: OK" - name: Check CHANGELOG exists run: | @@ -96,8 +96,8 @@ jobs: # Collect all required files that exist for f in SECURITY.md SECURITY.adoc .github/SECURITY.md LICENSE LICENSE.txt \ CONTRIBUTING.md CONTRIBUTING.adoc README.md README.adoc \ - .machine_readable/STATE.a2ml .machine_readable/META.a2ml \ - .machine_readable/ECOSYSTEM.a2ml CHANGELOG.md CHANGELOG.adoc; do + .machine_readable/descriptiles/STATE.a2ml .machine_readable/descriptiles/META.a2ml \ + .machine_readable/descriptiles/ECOSYSTEM.a2ml CHANGELOG.md CHANGELOG.adoc; do [ -f "$f" ] && REQUIRED_FILES="$REQUIRED_FILES $f" done diff --git a/.machine_readable/0.1-AI-MANIFEST.a2ml b/.machine_readable/0.1-AI-MANIFEST.a2ml index 9d2bc7a..b868271 100644 --- a/.machine_readable/0.1-AI-MANIFEST.a2ml +++ b/.machine_readable/0.1-AI-MANIFEST.a2ml @@ -12,12 +12,12 @@ description: | automation scripts. canonical_locations: - state: "STATE.a2ml" - meta: "META.a2ml" - ecosystem: "ECOSYSTEM.a2ml" - agentic: "AGENTIC.a2ml" - neurosym: "NEUROSYM.a2ml" - playbook: "PLAYBOOK.a2ml" + state: "descriptiles/STATE.a2ml" + meta: "descriptiles/META.a2ml" + ecosystem: "descriptiles/ECOSYSTEM.a2ml" + agentic: "descriptiles/AGENTIC.a2ml" + neurosym: "descriptiles/NEUROSYM.a2ml" + playbook: "descriptiles/PLAYBOOK.a2ml" anchors: "anchors/" policies: "policies/" ai_configs: "ai/" diff --git a/.machine_readable/ECOSYSTEM.a2ml b/.machine_readable/ECOSYSTEM.a2ml deleted file mode 100644 index 7327fd3..0000000 --- a/.machine_readable/ECOSYSTEM.a2ml +++ /dev/null @@ -1,11 +0,0 @@ -;; SPDX-License-Identifier: MPL-2.0 -;; Ecosystem position and relationships -(ecosystem - (version "1.0.0") - (name "bofj-kitt") - (type "tooling") - (purpose "Shared Developer Environment Extension Kit (the SuperChainsaw) for the BoJ (Box of Justice) server") - (related-projects - (project (name "boj-server") (relation "host/consumer — the BoJ MCP gateway this kit extends")) - (project (name "rsr-template-repo") (relation "lineage — the RSR scaffold this repo was created from")) - (project (name "standards") (relation "governance — estate-wide reusable CI and session standards")))) diff --git a/.machine_readable/META.a2ml b/.machine_readable/META.a2ml deleted file mode 100644 index 9b18dd6..0000000 --- a/.machine_readable/META.a2ml +++ /dev/null @@ -1,10 +0,0 @@ -;; SPDX-License-Identifier: MPL-2.0 -;; Architecture decisions and development practices -(meta - (version "1.0.0") - (project "bofj-kitt") - (architecture-decisions) - (development-practices - (code-review "required") - (branch-protection "enabled") - (ci-cd "github-actions"))) diff --git a/.machine_readable/STATE.a2ml b/.machine_readable/STATE.a2ml deleted file mode 100644 index 5286a4e..0000000 --- a/.machine_readable/STATE.a2ml +++ /dev/null @@ -1,23 +0,0 @@ -;; SPDX-License-Identifier: MPL-2.0 -;; Project state — update throughout each session -(state - (metadata - (version "1.1.0") - (project "bofj-kitt") - (last-updated "2026-07-16")) - (project-context - (description "Shared Developer Environment Extension Kit (the SuperChainsaw) for the BoJ (Box of Justice) server") - (primary-language "not yet chosen — see docs/status/ROADMAP.adoc M3") - (status "pre-alpha")) - (current-position - (phase "design") - (completion-percentage 5) - (milestone "M0 — truthful identity and green governance CI")) - (testing-summary - (product-tests "none — no product code yet (pre-alpha scaffold)") - (workflow-tests "tests/workflows/validate_workflows_test.sh: governance workflows present + well-formed") - (aspect-checks "tests/aspect_tests.sh: repo-shape/observability/security scaffold")) - (critical-next-actions - ("M1 — finish remaining placeholder-token fills; restore a full SECURITY policy" - "M2 — specify the kit's first capability + BoJ integration contract" - "M3 — choose implementation language; re-add a real e2e workflow"))) diff --git a/.machine_readable/ai/.clinerules b/.machine_readable/ai/.clinerules index 63ce8cf..36c4302 100644 --- a/.machine_readable/ai/.clinerules +++ b/.machine_readable/ai/.clinerules @@ -2,7 +2,7 @@ # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) # Authoritative source: docs/AI-CONVENTIONS.md -# STARTUP: Read 0-AI-MANIFEST.a2ml first, then .machine_readable/STATE.a2ml. +# STARTUP: Read 0-AI-MANIFEST.a2ml first, then .machine_readable/descriptiles/STATE.a2ml. # LICENSE # All original code: MPL-2.0. diff --git a/.machine_readable/ai/.windsurfrules b/.machine_readable/ai/.windsurfrules index 63ce8cf..36c4302 100644 --- a/.machine_readable/ai/.windsurfrules +++ b/.machine_readable/ai/.windsurfrules @@ -2,7 +2,7 @@ # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) # Authoritative source: docs/AI-CONVENTIONS.md -# STARTUP: Read 0-AI-MANIFEST.a2ml first, then .machine_readable/STATE.a2ml. +# STARTUP: Read 0-AI-MANIFEST.a2ml first, then .machine_readable/descriptiles/STATE.a2ml. # LICENSE # All original code: MPL-2.0. diff --git a/.machine_readable/ai/AI.a2ml b/.machine_readable/ai/AI.a2ml index 7a351ef..9e7230b 100644 --- a/.machine_readable/ai/AI.a2ml +++ b/.machine_readable/ai/AI.a2ml @@ -7,8 +7,8 @@ - Prefer to keep generated files out of source control, and regenerate them with the documented commands before committing. ## Workflow -1. Inspect `.machine_readable/STATE.a2ml` for blockers and next actions. -2. Respect any constraints listed inside `.machine_readable/AGENTIC.a2ml` when tooling changes are requested. +1. Inspect `.machine_readable/descriptiles/STATE.a2ml` for blockers and next actions. +2. Respect any constraints listed inside `.machine_readable/descriptiles/AGENTIC.a2ml` when tooling changes are requested. 3. After finishing edits, update STATE with your outcomes and commit with a concise, imperative message. ## Delivery Promises diff --git a/.machine_readable/ai/README.adoc b/.machine_readable/ai/README.adoc index 121bbc8..4e4f653 100644 --- a/.machine_readable/ai/README.adoc +++ b/.machine_readable/ai/README.adoc @@ -18,5 +18,5 @@ Recommended machine read order: * `.machine_readable/policies/MAINTENANCE-AXES.a2ml` * `.machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml` * `.machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml` -* `.machine_readable/STATE.a2ml` -* `.machine_readable/META.a2ml` +* `.machine_readable/descriptiles/STATE.a2ml` +* `.machine_readable/descriptiles/META.a2ml` diff --git a/.machine_readable/6a2/AGENTIC.a2ml b/.machine_readable/descriptiles/AGENTIC.a2ml similarity index 100% rename from .machine_readable/6a2/AGENTIC.a2ml rename to .machine_readable/descriptiles/AGENTIC.a2ml diff --git a/.machine_readable/6a2/ECOSYSTEM.a2ml b/.machine_readable/descriptiles/ECOSYSTEM.a2ml similarity index 100% rename from .machine_readable/6a2/ECOSYSTEM.a2ml rename to .machine_readable/descriptiles/ECOSYSTEM.a2ml diff --git a/.machine_readable/6a2/META.a2ml b/.machine_readable/descriptiles/META.a2ml similarity index 100% rename from .machine_readable/6a2/META.a2ml rename to .machine_readable/descriptiles/META.a2ml diff --git a/.machine_readable/6a2/NEUROSYM.a2ml b/.machine_readable/descriptiles/NEUROSYM.a2ml similarity index 100% rename from .machine_readable/6a2/NEUROSYM.a2ml rename to .machine_readable/descriptiles/NEUROSYM.a2ml diff --git a/.machine_readable/6a2/PLAYBOOK.a2ml b/.machine_readable/descriptiles/PLAYBOOK.a2ml similarity index 94% rename from .machine_readable/6a2/PLAYBOOK.a2ml rename to .machine_readable/descriptiles/PLAYBOOK.a2ml index cdaebfd..5123b86 100644 --- a/.machine_readable/6a2/PLAYBOOK.a2ml +++ b/.machine_readable/descriptiles/PLAYBOOK.a2ml @@ -13,7 +13,7 @@ last-updated = "2026-04-11" # target = "container" # container | binary | library | wasm [incident-response] -# 1. Check .machine_readable/STATE.a2ml for current status +# 1. Check .machine_readable/descriptiles/STATE.a2ml for current status # 2. Review recent commits and CI results # 3. Run `just validate` to check compliance # 4. Run `just security` to audit for vulnerabilities @@ -61,7 +61,7 @@ enforcement-workflow = ".github/workflows/estate-rules.yml" # === Required directories === # .github/ CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, workflows/ -# .machine_readable/ AI manifests (0.1-AI-MANIFEST.a2ml), 6a2/ checkpoints, +# .machine_readable/ AI manifests (0.1-AI-MANIFEST.a2ml), descriptiles/ checkpoints, # contractiles/, configs/, anchors/, policies/, scripts/, svc/ # build/ contractile.just, flake.guix, guix.scm, Containerfile, # just/*.just (Justfile section imports) @@ -123,6 +123,9 @@ enforcement-workflow = ".github/workflows/estate-rules.yml" # vlang.sh + .github/workflows/estate-rules.yml. # 5. chore/-hygiene Repo-specific drift cleanup (case collisions, # template-derivation drift in titles, etc.). +# Move a legacy .machine_readable/6a2/ to +# .machine_readable/descriptiles/ and update every +# reference to the old path (Hypatia SD004, SD024). # === Reference scripts === # scripts/check-root-shape.sh Root allowlist validator diff --git a/.machine_readable/6a2/STATE.a2ml b/.machine_readable/descriptiles/STATE.a2ml similarity index 100% rename from .machine_readable/6a2/STATE.a2ml rename to .machine_readable/descriptiles/STATE.a2ml diff --git a/.machine_readable/policies/MAINTENANCE-AXES.a2ml b/.machine_readable/policies/MAINTENANCE-AXES.a2ml index 011df3d..7b0af8e 100644 --- a/.machine_readable/policies/MAINTENANCE-AXES.a2ml +++ b/.machine_readable/policies/MAINTENANCE-AXES.a2ml @@ -18,7 +18,7 @@ machine-entrypoints = [ ".machine_readable/policies/MAINTENANCE-AXES.a2ml", ".machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml", ".machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml", - ".machine_readable/META.a2ml", + ".machine_readable/descriptiles/META.a2ml", ".machine_readable/ai/README.adoc", ".machine_readable/bot_directives/README.scm", ] diff --git a/.machine_readable/svc/k9/methodology-guard.k9.ncl b/.machine_readable/svc/k9/methodology-guard.k9.ncl index 4eacd02..4cc4f2e 100644 --- a/.machine_readable/svc/k9/methodology-guard.k9.ncl +++ b/.machine_readable/svc/k9/methodology-guard.k9.ncl @@ -58,7 +58,7 @@ let methodology_guard = { state_not_template = { description = "STATE.a2ml must not contain template placeholders", severity = "warning", - file = ".machine_readable/6a2/STATE.a2ml", + file = ".machine_readable/descriptiles/STATE.a2ml", reject_patterns = ["{{PLACEHOLDER}}", "BOFJ_KITT", "rsr-template-repo"], }, diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index df3954f..202f37e 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -72,3 +72,25 @@ addressed: `.machine_readable/svc/k9/methodology-guard.k9.ncl` gain the `K9!` magic line and a pedigree block. The lasting fix is to migrate those bindings to the k9-coordination grammar in `standards`. +* Descriptiles moved to `.machine_readable/descriptiles/`, the canonical + location, from the retired `.machine_readable/6a2/`. The stale July copies + of `STATE`, `META` and `ECOSYSTEM` at `.machine_readable/` are removed: the + `6a2/` versions superseded them. Every workflow, recipe and document that + named the old paths now names the new ones (Hypatia SD004 and SD024). +* `.github/workflows/main-estate-audit.yml` — now a thin caller of + cicd-suite's reusable estate audit, pinned at a full SHA and recorded in + `actions.lock` with the gate commits it reaches. The old file was a copy of + the retired 26-step audit, frozen by its lock at a 2026-09-21 cicd-suite + commit: one day before the Required Files gate stopped dying on a + comment-only CODEOWNERS, and before upstream dropped the gates that cannot + run on a GitHub runner (custom-tools needs pons and panic-attack). The + audit now reports five checks: governance, hygiene, manifests, languages, + advisory. +* `docs/wikis/` removed: an empty template scaffold whose AsciiDoc + invariant contradicted the estate formatting gate (wiki content is `.md`). +* `Justfile` — the duplicate `guix-shell` recipe (a nix-to-guix rename + artefact) is removed, so the Justfile parses again; `tests/e2e.sh` debt + markers link #101. +* Workflow permissions — `main-estate-audit.yml` declares read-only + contents; the Dependabot auto-merge job gets the `contents: write` that + `gh pr merge --auto` needs. diff --git a/Justfile b/Justfile index 17dea27..d0256f8 100644 --- a/Justfile +++ b/Justfile @@ -52,7 +52,7 @@ info: @echo "Version: {{version}}" @echo "RSR Tier: {{tier}}" @echo "Recipes: $(just --summary | wc -w)" - @[ -f ".machine_readable/STATE.a2ml" ] && grep -oP 'phase\s*=\s*"\K[^"]+' .machine_readable/STATE.a2ml | head -1 | xargs -I{} echo "Phase: {}" || true + @[ -f ".machine_readable/descriptiles/STATE.a2ml" ] && grep -oP 'phase\s*=\s*"\K[^"]+' .machine_readable/descriptiles/STATE.a2ml | head -1 | xargs -I{} echo "Phase: {}" || true # Run Invariant Path overlay tools for this repository invariant-path *ARGS: @@ -558,17 +558,17 @@ import? "build/just/validate.just" # Update STATE.a2ml timestamp state-touch: - @if [ -f ".machine_readable/STATE.a2ml" ]; then \ - sed -i 's/last-updated = "[^"]*"/last-updated = "'"$(date +%Y-%m-%d)"'"/' .machine_readable/STATE.a2ml && \ + @if [ -f ".machine_readable/descriptiles/STATE.a2ml" ]; then \ + sed -i 's/last-updated = "[^"]*"/last-updated = "'"$(date +%Y-%m-%d)"'"/' .machine_readable/descriptiles/STATE.a2ml && \ echo "STATE.a2ml timestamp updated"; \ fi # Show current phase from STATE.a2ml state-phase: - @grep -oP 'phase\s*=\s*"\K[^"]+' .machine_readable/STATE.a2ml 2>/dev/null | head -1 || echo "unknown" + @grep -oP 'phase\s*=\s*"\K[^"]+' .machine_readable/descriptiles/STATE.a2ml 2>/dev/null | head -1 || echo "unknown" # ═══════════════════════════════════════════════════════════════════════════════ -# GUIX & GUIX +# GUIX # ═══════════════════════════════════════════════════════════════════════════════ # Enter Guix development shell (primary) @@ -579,10 +579,6 @@ guix-shell: guix-build: guix build -f guix.scm -# Enter Guix development shell (fallback) -guix-shell: - @if [ -f "flake.guix" ]; then guix develop; else echo "No flake.guix"; fi - # ═══════════════════════════════════════════════════════════════════════════════ # HYBRID AUTOMATION # ═══════════════════════════════════════════════════════════════════════════════ diff --git a/build/just/assess.just b/build/just/assess.just index 9b9d65d..11fb3ca 100644 --- a/build/just/assess.just +++ b/build/just/assess.just @@ -50,10 +50,10 @@ self-assess: fi done - if [ -d ".machine_readable/6a2" ]; then - echo " ✓ .machine_readable/6a2/ — KEEP (SCM checkpoint files)" + if [ -d ".machine_readable/descriptiles" ]; then + echo " ✓ .machine_readable/descriptiles/ — KEEP (SCM checkpoint files)" else - echo " ✗ .machine_readable/6a2/ — MISSING (RSR violation!)" + echo " ✗ .machine_readable/descriptiles/ — MISSING (RSR violation!)" fi if [ -d ".github/workflows" ]; then @@ -194,9 +194,9 @@ verify: check_file "LICENSE" check_either "CONTRIBUTING.md" "CONTRIBUTING.adoc" check_either "README.adoc" "README.md" - check_file ".machine_readable/STATE.a2ml" - check_file ".machine_readable/META.a2ml" - check_file ".machine_readable/ECOSYSTEM.a2ml" + check_file ".machine_readable/descriptiles/STATE.a2ml" + check_file ".machine_readable/descriptiles/META.a2ml" + check_file ".machine_readable/descriptiles/ECOSYSTEM.a2ml" check_either "CHANGELOG.md" "CHANGELOG.adoc" # Check at least 1 workflow exists diff --git a/build/just/groove.just b/build/just/groove.just index e7fae2c..d9f5d2d 100644 --- a/build/just/groove.just +++ b/build/just/groove.just @@ -82,7 +82,7 @@ verify-template: fi # Check for empty SCM files - for f in .machine_readable/6a2/STATE.a2ml .machine_readable/6a2/META.a2ml .machine_readable/6a2/ECOSYSTEM.a2ml; do + for f in .machine_readable/descriptiles/STATE.a2ml .machine_readable/descriptiles/META.a2ml .machine_readable/descriptiles/ECOSYSTEM.a2ml; do if [ -f "$f" ] && grep -q '{{'{{'}}' "$f" 2>/dev/null; then echo "⚠ $f still has template placeholders" FOUND=1 diff --git a/build/just/validate.just b/build/just/validate.just index 3776526..ba016f3 100644 --- a/build/just/validate.just +++ b/build/just/validate.just @@ -16,7 +16,7 @@ validate-rsr: for f in .editorconfig .gitignore Justfile README.adoc LICENSE 0-AI-MANIFEST.a2ml; do [ -f "$f" ] || MISSING="$MISSING $f" done - for f in .machine_readable/STATE.a2ml .machine_readable/META.a2ml .machine_readable/ECOSYSTEM.a2ml .machine_readable/anchors/ANCHOR.a2ml .machine_readable/policies/MAINTENANCE-AXES.a2ml .machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml .machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml; do + for f in .machine_readable/descriptiles/STATE.a2ml .machine_readable/descriptiles/META.a2ml .machine_readable/descriptiles/ECOSYSTEM.a2ml .machine_readable/anchors/ANCHOR.a2ml .machine_readable/policies/MAINTENANCE-AXES.a2ml .machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml .machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml; do [ -f "$f" ] || MISSING="$MISSING $f" done for f in licensing/exhibits/EXHIBIT-A-ETHICAL-USE.txt licensing/exhibits/EXHIBIT-B-QUANTUM-SAFE.txt licensing/texts/MPL-2.0.txt; do @@ -25,15 +25,15 @@ validate-rsr: for f in docs/governance/MAINTENANCE-CHECKLIST.adoc docs/governance/SOFTWARE-DEVELOPMENT-APPROACH.adoc; do [ -f "$f" ] || MISSING="$MISSING $f" done - if [ -f ".machine_readable/META.a2ml" ]; then - grep -q 'axis-1 = "must > intend > like"' .machine_readable/META.a2ml || MISSING="$MISSING META.a2ml:axis-1" - grep -q 'axis-2 = "corrective > adaptive > perfective"' .machine_readable/META.a2ml || MISSING="$MISSING META.a2ml:axis-2" - grep -q 'axis-3 = "systems > compliance > effects"' .machine_readable/META.a2ml || MISSING="$MISSING META.a2ml:axis-3" - grep -q 'scoping-first = true' .machine_readable/META.a2ml || MISSING="$MISSING META.a2ml:scoping-first" - grep -q 'idris-unsound-scan = "believe_me/assert_total"' .machine_readable/META.a2ml || MISSING="$MISSING META.a2ml:idris-unsound-scan" - grep -q 'audit-focus = "systems in place, documentation explains actual state, safety/security accounted for, observed effects reviewed"' .machine_readable/META.a2ml || MISSING="$MISSING META.a2ml:audit-focus" - grep -q 'compliance-focus = "seams/compromises/exception register, bounded exceptions, anti-drift checks"' .machine_readable/META.a2ml || MISSING="$MISSING META.a2ml:compliance-focus" - grep -q 'effects-evidence = "benchmark execution/results and maintainer status dialogue/review"' .machine_readable/META.a2ml || MISSING="$MISSING META.a2ml:effects-evidence" + if [ -f ".machine_readable/descriptiles/META.a2ml" ]; then + grep -q 'axis-1 = "must > intend > like"' .machine_readable/descriptiles/META.a2ml || MISSING="$MISSING META.a2ml:axis-1" + grep -q 'axis-2 = "corrective > adaptive > perfective"' .machine_readable/descriptiles/META.a2ml || MISSING="$MISSING META.a2ml:axis-2" + grep -q 'axis-3 = "systems > compliance > effects"' .machine_readable/descriptiles/META.a2ml || MISSING="$MISSING META.a2ml:axis-3" + grep -q 'scoping-first = true' .machine_readable/descriptiles/META.a2ml || MISSING="$MISSING META.a2ml:scoping-first" + grep -q 'idris-unsound-scan = "believe_me/assert_total"' .machine_readable/descriptiles/META.a2ml || MISSING="$MISSING META.a2ml:idris-unsound-scan" + grep -q 'audit-focus = "systems in place, documentation explains actual state, safety/security accounted for, observed effects reviewed"' .machine_readable/descriptiles/META.a2ml || MISSING="$MISSING META.a2ml:audit-focus" + grep -q 'compliance-focus = "seams/compromises/exception register, bounded exceptions, anti-drift checks"' .machine_readable/descriptiles/META.a2ml || MISSING="$MISSING META.a2ml:compliance-focus" + grep -q 'effects-evidence = "benchmark execution/results and maintainer status dialogue/review"' .machine_readable/descriptiles/META.a2ml || MISSING="$MISSING META.a2ml:effects-evidence" grep -q 'compliance-tooling = "panic-attack"' .machine_readable/policies/MAINTENANCE-AXES.a2ml || MISSING="$MISSING MAINTENANCE-AXES.a2ml:compliance-tooling" grep -q 'effects-tooling = "ecological checking with sustainabot guidance"' .machine_readable/policies/MAINTENANCE-AXES.a2ml || MISSING="$MISSING MAINTENANCE-AXES.a2ml:effects-tooling" grep -q 'source-human = "docs/governance/MAINTENANCE-CHECKLIST.adoc"' .machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml || MISSING="$MISSING MAINTENANCE-CHECKLIST.a2ml:source-human" @@ -47,12 +47,12 @@ validate-rsr: # Validate STATE.a2ml syntax validate-state: - @if [ -f ".machine_readable/STATE.a2ml" ]; then \ - grep -q '^\[metadata\]' .machine_readable/STATE.a2ml && \ - grep -q 'project\s*=' .machine_readable/STATE.a2ml && \ + @if [ -f ".machine_readable/descriptiles/STATE.a2ml" ]; then \ + grep -q '^\[metadata\]' .machine_readable/descriptiles/STATE.a2ml && \ + grep -q 'project\s*=' .machine_readable/descriptiles/STATE.a2ml && \ echo "STATE.a2ml: valid" || echo "STATE.a2ml: INVALID (missing required sections)"; \ else \ - echo "No .machine_readable/STATE.a2ml found"; \ + echo "No .machine_readable/descriptiles/STATE.a2ml found"; \ fi # Validate AI installation guide completeness (finishbot pre-release check) diff --git a/docs/0.1-AI-MANIFEST.a2ml b/docs/0.1-AI-MANIFEST.a2ml index 7f79301..a23be01 100644 --- a/docs/0.1-AI-MANIFEST.a2ml +++ b/docs/0.1-AI-MANIFEST.a2ml @@ -26,7 +26,6 @@ canonical_locations: whitepapers: "whitepapers/" standards: "standards/" legal: "legal/" - wikis: "wikis/" invariants: - "Primary documentation format MUST be AsciiDoc (.adoc)" diff --git a/docs/RSR_OUTLINE.adoc b/docs/RSR_OUTLINE.adoc index ea487d2..f2316c4 100644 --- a/docs/RSR_OUTLINE.adoc +++ b/docs/RSR_OUTLINE.adoc @@ -157,12 +157,13 @@ project/ │ ├── humans.txt │ └── security.txt ├── .machine_readable/ # ALL machine-readable content -│ ├── STATE.a2ml # Project state, progress, blockers -│ ├── META.a2ml # Architecture decisions, governance -│ ├── ECOSYSTEM.a2ml # Ecosystem position, relationships -│ ├── AGENTIC.a2ml # AI agent interaction patterns -│ ├── NEUROSYM.a2ml # Neurosymbolic integration config -│ ├── PLAYBOOK.a2ml # Operational runbook +│ ├── descriptiles/ # Machine-readable state and operational descriptiles +│ │ ├── STATE.a2ml # Project state, progress, blockers +│ │ ├── META.a2ml # Architecture decisions, governance +│ │ ├── ECOSYSTEM.a2ml # Ecosystem position, relationships +│ │ ├── AGENTIC.a2ml # AI agent interaction patterns +│ │ ├── NEUROSYM.a2ml # Neurosymbolic integration config +│ │ └── PLAYBOOK.a2ml # Operational runbook │ ├── bot_directives/ # Per-bot rules and constraints │ └── contractiles/ # Policy enforcement contracts │ ├── k9/ # Security levels (Kennel/Yard/Hunt) @@ -209,7 +210,7 @@ project/ * `Justfile` * `README.adoc` * `LICENSE` (MPL-2.0) -* `.machine_readable/STATE.a2ml` +* `.machine_readable/descriptiles/STATE.a2ml` * `.well-known/security.txt` * `.well-known/ai.txt` * `.well-known/humans.txt` diff --git a/docs/governance/CRG-AUDIT-TEMPLATE.adoc b/docs/governance/CRG-AUDIT-TEMPLATE.adoc index d76914d..749fa85 100644 --- a/docs/governance/CRG-AUDIT-TEMPLATE.adoc +++ b/docs/governance/CRG-AUDIT-TEMPLATE.adoc @@ -25,7 +25,7 @@ Evaluates the `bofj-kitt` repository against - Standard: `standards/component-readiness-grades/COMPONENT-READINESS-GRADES.md` - Template (criteria boilerplate): `rsr-template-repo/docs/governance/CRG-CRITERIA.adoc` - Self-declared grade (prior art): - * `.machine_readable/6a2/STATE.a2ml` → `grade = ""` + * `.machine_readable/descriptiles/STATE.a2ml` → `grade = ""` * `docs/READINESS.md` (if present) → per-component grades * Third-party badges (Glama, OpenSSF, etc.) if any — note date and scope - Audit date: 2026-08-05 @@ -65,7 +65,7 @@ Do *not* mark PRESENT without citing the path. | PRESENT / PARTIAL (count) / ABSENT | `.github/workflows/` -| `.machine_readable/6a2/` canonical A2ML +| `.machine_readable/descriptiles/` canonical A2ML | PRESENT (STATE, META, ECOSYSTEM, AGENTIC, NEUROSYM, PLAYBOOK) / ABSENT | Layout matches CLAUDE.md invariant @@ -141,7 +141,7 @@ RSR compliance verdict: *met* / *partial* / *not met* — Grade D floor satisfie Cite *from authoritative source* (STATE.a2ml or CI log). Do not re-count by filesystem grep — grade the evidence that already exists. -- `total-tests = N` (from `.machine_readable/6a2/STATE.a2ml` or CI). +- `total-tests = N` (from `.machine_readable/descriptiles/STATE.a2ml` or CI). - Breakdown by suite: list each named suite and its count. - CI: `.github/workflows/.yml` runs on push / tag / schedule. - Last green run: date + commit SHA. @@ -278,7 +278,7 @@ them. Examples: == Related Files - `docs/READINESS.md` — per-component table. Note v1.0-vs-v2.0 schema alignment. -- `.machine_readable/6a2/STATE.a2ml` — authoritative self-declared state. +- `.machine_readable/descriptiles/STATE.a2ml` — authoritative self-declared state. - `docs/governance/CRG-LIFT-PLAN-2026-08-05.adoc` — companion plan for D→C (and medium-term C→B) lifts. - `docs/governance/CRG-CRITERIA.adoc` — boilerplate criteria doc. diff --git a/docs/practice/AI-CONVENTIONS.adoc b/docs/practice/AI-CONVENTIONS.adoc index 7ccbf25..c2a8f6f 100644 --- a/docs/practice/AI-CONVENTIONS.adoc +++ b/docs/practice/AI-CONVENTIONS.adoc @@ -10,12 +10,12 @@ Per-tool config files (.cursorrules, .clinerules, etc.) reference this document. ## Session Startup 1. Read `0-AI-MANIFEST.a2ml` FIRST (mandatory gatekeeper). -2. Read `.machine_readable/STATE.a2ml` for current status and blockers. +2. Read `.machine_readable/descriptiles/STATE.a2ml` for current status and blockers. 3. Read `.machine_readable/anchors/ANCHOR.a2ml` for canonical authority boundaries. 4. Read `.machine_readable/policies/MAINTENANCE-AXES.a2ml` for maintenance/audit sequencing. 5. Read `.machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml` for baseline controls. 6. Read `.machine_readable/policies/SOFTWARE-DEVELOPMENT-APPROACH.a2ml` for execution order. -7. Read `.machine_readable/AGENTIC.a2ml` for agent constraints. +7. Read `.machine_readable/descriptiles/AGENTIC.a2ml` for agent constraints. ## License @@ -76,8 +76,8 @@ Use `just` (Justfile) for all build, test, lint, and format tasks. ## References - `0-AI-MANIFEST.a2ml` -- universal AI entry point -- `.machine_readable/AGENTIC.a2ml` -- agent permissions and constraints -- `.machine_readable/STATE.a2ml` -- current project state +- `.machine_readable/descriptiles/AGENTIC.a2ml` -- agent permissions and constraints +- `.machine_readable/descriptiles/STATE.a2ml` -- current project state - `.machine_readable/anchors/ANCHOR.a2ml` -- canonical authority and policy boundary - `.machine_readable/policies/MAINTENANCE-AXES.a2ml` -- canonical axis sequencing and audit requirements - `.machine_readable/policies/MAINTENANCE-CHECKLIST.a2ml` -- baseline maintenance checklist policy diff --git a/docs/status/READINESS.adoc b/docs/status/READINESS.adoc index 91c82ae..f80349f 100644 --- a/docs/status/READINESS.adoc +++ b/docs/status/READINESS.adoc @@ -40,7 +40,7 @@ evidence doesn't support the claim. *Evidence gates (v2.0 is stricter than v1.0):* * *D*: RSR-compliant + per-capability tests + documented scope. Test matrix - must cite counts and live in `.machine_readable/6a2/STATE.a2ml` or CI. + must cite counts and live in `.machine_readable/descriptiles/STATE.a2ml` or CI. * *C*: All of D, plus active dogfooding in home context with *no known home-context failures over an evidence window*, plus *deep per-file and per-directory annotation* (purpose, boundaries, invariants, @@ -65,7 +65,7 @@ Below B, any publication must be explicitly abstract or provisional. |=== | Metric | Value | Source -| Test count | __ | `.machine_readable/6a2/STATE.a2ml` or CI +| Test count | __ | `.machine_readable/descriptiles/STATE.a2ml` or CI | Formal-verification posture | __ | grep of proof dirs | Dangerous patterns (`assert_total`, `unsafeCoerce`, `Obj.magic`) | __ | grep 2026-08-05 | Per-unit README coverage | __ | filesystem scan of unit dirs @@ -179,7 +179,7 @@ Real-world external feedback confirming value. Populate * `docs/governance/CRG-AUDIT-.adoc` — formal audit (populate from `rsr-template-repo/docs/governance/CRG-AUDIT-TEMPLATE.adoc`). * `docs/practice/DOGFOOD-LOG.adoc` — dated dogfood evidence (required for C). -* `.machine_readable/6a2/STATE.a2ml` — authoritative state (canonical keys +* `.machine_readable/descriptiles/STATE.a2ml` — authoritative state (canonical keys `[dogfooding-status]`, `[external-targets]`, `[issues-fed-back]`, `[field-signal]`). diff --git a/docs/status/ROADMAP.adoc b/docs/status/ROADMAP.adoc index 0b79eab..1cbad7a 100644 --- a/docs/status/ROADMAP.adoc +++ b/docs/status/ROADMAP.adoc @@ -39,7 +39,7 @@ established this baseline. === M4 — First capability + tests (CRG D) * [ ] Ship one end-to-end capability (e.g. `kitt init` provisions a compliant environment; `kitt connect` registers it with a BoJ server). -* [ ] Per-capability unit + integration tests; record counts in `.machine_readable/6a2/STATE.a2ml`. +* [ ] Per-capability unit + integration tests; record counts in `.machine_readable/descriptiles/STATE.a2ml`. * [ ] Replace the placeholder fuzz README with a real harness. * [ ] Replace the generic template proofs under `verification/` with product proofs. diff --git a/docs/status/TEST-NEEDS.adoc b/docs/status/TEST-NEEDS.adoc index 030b225..101fe36 100644 --- a/docs/status/TEST-NEEDS.adoc +++ b/docs/status/TEST-NEEDS.adoc @@ -37,7 +37,7 @@ See `docs/status/ROADMAP.adoc` and * [ ] Land the first shippable kit capability (e.g. `kitt init` provisioning a compliant dev environment; `kitt connect` registering with a BoJ server). * [ ] Per-capability unit + integration tests, with counts recorded in - `.machine_readable/6a2/STATE.a2ml`. + `.machine_readable/descriptiles/STATE.a2ml`. * [ ] Re-add a real `.github/workflows/e2e.yml` exercising the capability end-to-end (the template placeholder was removed in the 2026-07-16 pass). * [ ] Replace the placeholder fuzz README with an actual harness once there is diff --git a/docs/wikis/0.2-AI-MANIFEST.a2ml b/docs/wikis/0.2-AI-MANIFEST.a2ml deleted file mode 100644 index f071ca8..0000000 --- a/docs/wikis/0.2-AI-MANIFEST.a2ml +++ /dev/null @@ -1,15 +0,0 @@ -# SPDX-License-Identifier: MPL-2.0 ---- -### [META] -id: "wikis-track" -level: 2 -parent: "../0.1-AI-MANIFEST.a2ml" - ---- -### [AI_MANIFEST] -description: | - Long-form collaborative documentation and project knowledge base. - This directory mirrors the content structure of the project wiki. - -invariants: - - "Primary wiki format MUST be AsciiDoc (.adoc)" diff --git a/docs/wikis/README.adoc b/docs/wikis/README.adoc deleted file mode 100644 index 71b60d1..0000000 --- a/docs/wikis/README.adoc +++ /dev/null @@ -1,15 +0,0 @@ -= Project Wikis -:toc: preamble -:icons: font - -This directory contains the source files for the project wiki. It is intended for long-form documentation, deep-dives, and community-maintained knowledge. - -== Structure - -* **Core Concepts:** Fundamental architectural ideas. -* **Workflows:** Step-by-step guides for contributors. -* **Glossary:** Definitions of project-specific terminology. - -== Wiki Synchronization - -Changes made here should be synchronised with the forge-hosted wiki (GitHub/GitLab) using the project's sync scripts. diff --git a/tests/e2e.sh b/tests/e2e.sh index 7729064..9804c14 100755 --- a/tests/e2e.sh +++ b/tests/e2e.sh @@ -69,7 +69,7 @@ echo "" # ─── Preflight ─────────────────────────────────────────────────────── bold "Preflight checks" -# TODO: Check that your binary/server is built +# TODO(#101): Check that your binary/server is built # Example: # BINARY="$PROJECT_DIR/target/release/my-tool" # if [ ! -f "$BINARY" ]; then @@ -78,14 +78,14 @@ bold "Preflight checks" # fi # green " Binary found: $BINARY" -# TODO: Check dependencies +# TODO(#101): Check dependencies # command -v curl >/dev/null 2>&1 || { red "curl not found"; exit 1; } # command -v jq >/dev/null 2>&1 || { red "jq not found"; exit 1; } echo "" # ═══════════════════════════════════════════════════════════════════════ -# TODO: Add your E2E test sections below. Examples: +# TODO(#101): Add your E2E test sections below. Examples: # ═══════════════════════════════════════════════════════════════════════ # ─── Example: CLI tool E2E ───────────────────────────────────────────