From 1f7125d765e1b0ad5fb7d7b8fabeb2eaa0017ece Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 14 Oct 2026 08:46:58 +0000 Subject: [PATCH 1/6] =?UTF-8?q?docs(claude):=20record=20owner=20norms=20?= =?UTF-8?q?=E2=80=94=20selector=20questions,=20stacked=20PRs,=20KYAML=20/?= =?UTF-8?q?=20I-JSON+JCS=20/=20UUID=20v8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Owner norms of 2026-10-14 for agent sessions in this repo: decisions are asked with the selector tool, work lands as stacked PRs, and findings are fixed at source before any baseline/ledger entry. The format standards point at their normative source in hyperpolymath/standards: YAML-POLICY §3.4 (KYAML, .kyaml; D280/D307/D293), the workflow gate in standards#1025, JSON-POLICY (I-JSON as JCS + LF; D306) and ADR-008 (UUID v8 profiles T and C; D305/D305b/D320). Placed at the repo root because .claude/ is gitignored here. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_019a95kk88TZ1iegsBK3kox3 --- CLAUDE.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..b121c4d --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,37 @@ + + +# CLAUDE.md — proof-burrower + +Instructions for AI agent sessions in this repository. Architecture and +status live in `docs/ARCHITECTURE.adoc` and `docs/EXPLAINME.adoc`. + +## Owner norms (2026-10-14) + +These come from the owner. The format rules point at their normative +source in `hyperpolymath/standards`; read that, not a paraphrase. + +### Asking the owner + +- Ask decisions with the selector tool (structured options, the + recommended one first, with what each option implies). Use prose only + for reports and explanations. +- Work lands as **stacked PRs**: small, each independently reviewable. +- Fix a finding at its source before reaching for a baseline or ledger. + The governance exemption ratchet rejects ledger growth. + +### Formats (standard, estate-wide) + +| Kind | Standard | Source | +|------|----------|--------| +| YAML | KYAML, formatted with standards `scripts/kyaml-format.sh` (mikefarah yq v4 with the KYAML encoder). Estate-owned config uses `.kyaml` unless a tool fixes the name. No Python YAML parser. | `3-practice/YAML-POLICY.adoc` §3.4 (D280, D307, D293) | +| Workflows | KYAML too, but only through the step 6 gate in `standards#1025` (Dependabot / `gh actions-lock` drift accepted in writing, lock coverage, `actionlint`, a run proof per workflow). Lockfiles such as `actions.lock` are tool-owned: never hand-edit or reformat them. | `YAML-POLICY.adoc` §5–§6 | +| JSON | I-JSON (RFC 7493) serialised as JCS (RFC 8785), plus exactly one final LF. Extensions do not change. JSONL is one JCS object per line. JSONC files (`devcontainer.json`, `.vscode/`) are exempt. | `3-practice/JSON-POLICY.adoc` (D306) | +| UUID | Version 8 for every identifier. Profile T (time-ordered: the v7 layout with the version nibble set to 8) for records and events. Profile C (bytes 0..15 of SHA-256(`domain:name`), registered `domain`, no `:`) for content ids. No v4/v7 minting in new code. This repo mints only through `crates/burrower-core/src/ids.rs`. | `docs/decisions/ADR-008-uuid-v8-estate-standard.adoc` (D305, D305b, D320) | + +Keep another format only where a consumer the owner does not control +would break (for example a tool that rewrites the file). Record why +beside the file. Tools the owner controls are changed to handle the +standard instead of being exempted. From 77131405259f3b940c69bf54e87afc39e9215270 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Wed, 14 Oct 2026 09:56:24 +0100 Subject: [PATCH 2/6] Update CLAUDE.md Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> Signed-off-by: Jonathan D.A. Jewell <6759885+hyperpolymath@users.noreply.github.com> --- CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index b121c4d..66816ad 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,5 +1,5 @@ From c70ca58860d72e449871a646a77e8def7d799b77 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Wed, 14 Oct 2026 09:56:42 +0100 Subject: [PATCH 3/6] Update CLAUDE.md Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> Signed-off-by: Jonathan D.A. Jewell <6759885+hyperpolymath@users.noreply.github.com> --- CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 66816ad..8ac0ede 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -29,7 +29,7 @@ source in `hyperpolymath/standards`; read that, not a paraphrase. | YAML | KYAML, formatted with standards `scripts/kyaml-format.sh` (mikefarah yq v4 with the KYAML encoder). Estate-owned config uses `.kyaml` unless a tool fixes the name. No Python YAML parser. | `3-practice/YAML-POLICY.adoc` §3.4 (D280, D307, D293) | | Workflows | KYAML too, but only through the step 6 gate in `standards#1025` (Dependabot / `gh actions-lock` drift accepted in writing, lock coverage, `actionlint`, a run proof per workflow). Lockfiles such as `actions.lock` are tool-owned: never hand-edit or reformat them. | `YAML-POLICY.adoc` §5–§6 | | JSON | I-JSON (RFC 7493) serialised as JCS (RFC 8785), plus exactly one final LF. Extensions do not change. JSONL is one JCS object per line. JSONC files (`devcontainer.json`, `.vscode/`) are exempt. | `3-practice/JSON-POLICY.adoc` (D306) | -| UUID | Version 8 for every identifier. Profile T (time-ordered: the v7 layout with the version nibble set to 8) for records and events. Profile C (bytes 0..15 of SHA-256(`domain:name`), registered `domain`, no `:`) for content ids. No v4/v7 minting in new code. This repo mints only through `crates/burrower-core/src/ids.rs`. | `docs/decisions/ADR-008-uuid-v8-estate-standard.adoc` (D305, D305b, D320) | +| UUID | Current policy: UUIDv7 for records and events, and UUIDv8 over JCS content bytes for content IDs. Keep this split until the corresponding `ids.rs` migration lands. Apply the Profile T/C rule and prohibit new v4/v7 minting after that migration. This repo mints only through `crates/burrower-core/src/ids.rs`. | `docs/decisions/ADR-008-uuid-v8-estate-standard.adoc` (D305, D305b, D320) | Keep another format only where a consumer the owner does not control would break (for example a tool that rewrites the file). Record why From 0e8c765e5a3cdc686cddb2ac3dc7a2d8826c78fe Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 14 Oct 2026 08:56:51 +0000 Subject: [PATCH 4/6] docs(claude): the exemption ratchet admits declared ledger growth scripts/check-exemption-ratchet.sh in standards rejects growth of a ledger unless a commit message or the PR body carries a `Ratchet-exception:` line naming that ledger. The norm said it rejects all growth. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_019a95kk88TZ1iegsBK3kox3 --- CLAUDE.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index b121c4d..18e65d5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -20,7 +20,8 @@ source in `hyperpolymath/standards`; read that, not a paraphrase. for reports and explanations. - Work lands as **stacked PRs**: small, each independently reviewable. - Fix a finding at its source before reaching for a baseline or ledger. - The governance exemption ratchet rejects ledger growth. + The governance exemption ratchet rejects ledger growth unless a commit + or the PR body carries a `Ratchet-exception:` line naming that ledger. ### Formats (standard, estate-wide) From cfa06cb33d18a841b36c0e5a2a4612d4e4cf136c Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 14 Oct 2026 09:40:50 +0000 Subject: [PATCH 5/6] fix(ci): regenerate actions.lock after the Dependabot actions bump (#110) #110 bumped four `uses:` refs and left actions.lock pinning the old ones: - github/codeql-action v4.38.2 -> v4.38.3 - hyperpolymath/smtp-notify-action v0.3.0 -> v0.5.0 - actions/upload-artifact v7.0.1 -> v7.0.2 - actions/download-artifact v8.0.1 -> v8.0.2 Since then "Governance / Actions lockfile verify" has been red on main. GitHub also refuses to start codeql.yml and static-analysis-gate.yml (startup_failure on every run), so the required "analyze (actions, none)" check never reports, and CodeQL has not scanned main since 11 Oct. Only actions.lock changes. It is the output of the estate repair order: gh actions-lock v0.2.0, relock-sha-keys, complete-job-refs, close-lock and prune-stale, run by `regen_lock` from standards scripts/regen-dependabot-locks.sh at ae36881b. GitHub Actions ran it on main e81d057, because Claude Code sessions cannot reach GitHub GraphQL. The lockfile schema moves v0.0.2 -> v0.0.3. Dependabot's lock support reads both versions. Verified: - in CI, check-actions-lock-gate.sh at this repo's governance pin (standards 8f2ee508): pass; - here, the decoded bytes match the CI job's SHA-256 (6a06b778...); - the same gate passes locally; - `gh actions-lock --verify-local` reports only the 7 known reusable-workflow false positives, which the gate accepts as coverage. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_019a95kk88TZ1iegsBK3kox3 --- .github/workflows/actions.lock | 36 +++++++++++++++++----------------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/.github/workflows/actions.lock b/.github/workflows/actions.lock index 3e97fa4..0ef3f14 100644 --- a/.github/workflows/actions.lock +++ b/.github/workflows/actions.lock @@ -1,13 +1,13 @@ # This file is machine-generated by `gh actions-lock`. # Do not edit by hand; run `gh actions-lock` to update. # Docs: https://gh.io/actions-lockfile -version: 'v0.0.2' +version: 'v0.0.3' workflows: '.github/workflows/boj-build.yml': - 'actions/checkout@v7.0.1' '.github/workflows/codeql.yml': - 'actions/checkout@v7.0.1' - - 'github/codeql-action@v4.38.2' + - 'github/codeql-action@v4.38.3' '.github/workflows/dependabot-automerge.yml': - 'dependabot/fetch-metadata@v3.1.0' '.github/workflows/dogfood-gate.yml': @@ -39,13 +39,13 @@ workflows: - 'actions/checkout@v7.0.1' - 'swatinem/rust-cache@v2.9.2' '.github/workflows/push-email-notify.yml': - - 'hyperpolymath/smtp-notify-action@v0.3.0' + - 'hyperpolymath/smtp-notify-action@v0.5.0' '.github/workflows/quality.yml': - 'actions/checkout@v7.0.1' - 'editorconfig-checker/action-editorconfig-checker@v3.0.0' '.github/workflows/release.yml': - 'actions/checkout@v7.0.1' - - 'actions/upload-artifact@v7.0.1' + - 'actions/upload-artifact@v7.0.2' - 'slsa-framework/slsa-github-generator@f7dd8c54c2067bafc12ca7a55595d5ee9b75204a' - 'softprops/action-gh-release@v3.0.3' '.github/workflows/rhodibot.yml': @@ -62,8 +62,8 @@ workflows: - 'actions/checkout@v7.0.1' '.github/workflows/static-analysis-gate.yml': - 'actions/checkout@v7.0.1' - - 'actions/download-artifact@v8.0.1' - - 'actions/upload-artifact@v7.0.1' + - 'actions/download-artifact@v8.0.2' + - 'actions/upload-artifact@v7.0.2' - 'erlef/setup-beam@v1.24.1' '.github/workflows/wellknown-enforcement.yml': - 'actions/checkout@v7.0.1' @@ -80,9 +80,9 @@ dependencies: commit: 'sha1-368f82528645a54fb793d4d04e342629a3f51346' owner_id: 44036562 repo_id: 438112499 - 'actions/download-artifact@v8.0.1': - ref: 'v8.0.1' - commit: 'sha1-3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c' + 'actions/download-artifact@v8.0.2': + ref: 'v8.0.2' + commit: 'sha1-9000827ccba6bdab643e8b6fd33ac0654aef8333' owner_id: 44036562 repo_id: 192626254 'actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f': @@ -90,9 +90,9 @@ dependencies: commit: 'sha1-bbbca2ddaa5d8feaa63e36b76fdaad77386f024f' owner_id: 44036562 repo_id: 192625955 - 'actions/upload-artifact@v7.0.1': - ref: 'v7.0.1' - commit: 'sha1-043fb46d1a93c77aae656e7c1c64a875d1fc6a0a' + 'actions/upload-artifact@v7.0.2': + ref: 'v7.0.2' + commit: 'sha1-cf430e030ddbb5b0abf93d22962f4752f3646cd9' owner_id: 44036562 repo_id: 192625955 'actions/upload-pages-artifact@v5.0.0': @@ -117,9 +117,9 @@ dependencies: commit: 'sha1-54075bcc5e249e4758d363f27d099f55d843f124' owner_id: 47606891 repo_id: 331103973 - 'github/codeql-action@v4.38.2': - ref: 'v4.38.2' - commit: 'sha1-2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2' + 'github/codeql-action@v4.38.3': + ref: 'v4.38.3' + commit: 'sha1-24c54180a607b1449ed407dd24f251e4e9147c8d' owner_id: 9919 repo_id: 259445878 'hyperpolymath/cicd-suite@main': @@ -150,9 +150,9 @@ dependencies: commit: 'sha1-c1a34884054fabf0e9de81dbf68f4ba7874e85f1' owner_id: 6759885 repo_id: 1275650185 - 'hyperpolymath/smtp-notify-action@v0.3.0': - ref: 'v0.3.0' - commit: 'sha1-22e7bdb322c430c1d0dac6b3bb307f4bb139d0be' + 'hyperpolymath/smtp-notify-action@v0.5.0': + ref: 'v0.5.0' + commit: 'sha1-c1c9fa07992a02c1fd3d67a0dc1b08cccb852aef' owner_id: 6759885 repo_id: 1352485172 'hyperpolymath/standards@8f2ee50841e216cd8c192eeb68953118190f105c': From d80bb1c8d3e856526ee2761185f0ff4739b0116f Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 14 Oct 2026 09:59:56 +0000 Subject: [PATCH 6/6] fix(ci): defer actions.lock verification to governance in the workflow linter The copied "Verify immutable action lockfile" step pinned its own gh-actions-lock v0.1.6 binary. v0.1.6 cannot read lockfile v0.0.3, which every current `gh actions-lock` writes, so the step failed whenever a current tool refreshed the lock (proof-burrower#111/#112). It also kept a second version pin that drifts from the estate's. Governance already verifies the lock through standards scripts/update-actions-lock.sh. That is one tested implementation, with one pin, and it accepts reusable-workflow coverage. The step is removed and a comment points at the gate. No `uses:` changes, so actions.lock is untouched. Owner decision 2026-10-14: drop the lock step from copied linters; the estate moves to gh-actions-lock v0.2.0 in hyperpolymath/standards#1250. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_019a95kk88TZ1iegsBK3kox3 --- .github/workflows/workflow-linter.yml | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/.github/workflows/workflow-linter.yml b/.github/workflows/workflow-linter.yml index 3531ce2..16e343f 100644 --- a/.github/workflows/workflow-linter.yml +++ b/.github/workflows/workflow-linter.yml @@ -66,14 +66,11 @@ jobs: fi echo "All workflows have permissions declared" - - name: Verify immutable action lockfile with the authoritative tool - env: - GH_TOKEN: ${{ github.token }} - run: | - curl -fsSL --retry 3 -o "$RUNNER_TEMP/gh-actions-lock" https://github.com/github/gh-actions-lock/releases/download/v0.1.6/linux-amd64 - echo "4181ec1da5408b34b9a542a7ee5c6ce3a4d6ac815c7d0206a00ceca8a817f4e3 $RUNNER_TEMP/gh-actions-lock" | sha256sum --check - chmod u+x "$RUNNER_TEMP/gh-actions-lock" - "$RUNNER_TEMP/gh-actions-lock" --rescan --no-fix + # actions.lock is verified by governance's lockfile check (standards + # scripts/update-actions-lock.sh): one tested implementation, one + # gh-actions-lock pin, and it accepts reusable-workflow coverage. The step + # that stood here pinned its own v0.1.6 binary, which cannot read + # lockfile v0.0.3, so it failed whenever a current tool wrote the lock. - name: Check for Duplicate Workflows run: |