From 97a034d91fe59d0bd42bde8a687e7f370dd61553 Mon Sep 17 00:00:00 2001 From: Aaron Stainback Date: Fri, 1 May 2026 21:16:52 -0400 Subject: [PATCH 1/2] tools(hygiene): exclude docs/lost-substrate/** from orphan-role-ref lint MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `docs/lost-substrate/**` is by definition a history-surface (incident artifacts + dated inventory ledgers from the 2026-04-29 corruption-triage). Persona names + dated attribution are explicitly ALLOWED there per Otto-279 history-surface carve-out. Adding to the lint's history-surface exclusion list closes two false-positive findings the initial implementation flagged (docs/lost-substrate/artifacts/2026-04-29-corruption/triage- report.md lines 10 + 55). Smoke-test confirms: full-repo audit drops from 16 findings to 14 (the two lost-substrate findings are now correctly suppressed). The remaining 14 are real findings in tools/ + tests/ surfaces; cleanup deferred to follow-up PRs (most are in audit-agencysignature-* / validate-agencysignature-* tools that reference the originating-ferry purpose; some are clear "Per Aaron 2026-MM-DD" violations on tool comments). Note on test-fixture-strings: tests/Tests.FSharp/Algebra/ Veridicality.Tests.fs:12 contains the string `"repo/amara/ ferry-10"` as a TEST FIXTURE (sourceID under test, not a substrate-attribution claim). The lint's regex matches the literal token; a parser-aware refinement that distinguishes string literals from comment/doc context would suppress this. Deferred to a follow-up — current lint catches the case at write-time which is a tractable signal even with the noise. Composes with PR #1187 (initial lint). --- tools/hygiene/audit-orphan-role-refs.sh | 3 +++ 1 file changed, 3 insertions(+) diff --git a/tools/hygiene/audit-orphan-role-refs.sh b/tools/hygiene/audit-orphan-role-refs.sh index cf15584f6d..344b1b1378 100755 --- a/tools/hygiene/audit-orphan-role-refs.sh +++ b/tools/hygiene/audit-orphan-role-refs.sh @@ -57,6 +57,8 @@ # 2026-04-29 call; see file's classification block) # - docs/backlog/** (per-row history of backlog filings; # authors, dated lineage, persona names allowed) +# - docs/lost-substrate/** (incident artifacts + dated +# inventory ledgers — by definition history-surface) # - docs/CURRENT-ROUND.md (round-history equivalent) # - docs/amara-full-conversation/** (verbatim archived # conversation — bootstrap-attempt-1 lineage) @@ -131,6 +133,7 @@ is_history_surface() { docs/pr-discussions/* | \ docs/active-trajectory.md | \ docs/backlog/* | \ + docs/lost-substrate/* | \ docs/CURRENT-ROUND.md | \ docs/amara-full-conversation/* | \ .git/* | \ From 22c8e13a37604cc83cf466b05639dbf77e03bd0d Mon Sep 17 00:00:00 2001 From: Aaron Stainback Date: Fri, 1 May 2026 21:24:49 -0400 Subject: [PATCH 2/2] docs(audit-orphan): explicit doctrine-extension note per PR #1193 review Copilot P1 finding on PR #1193: header claimed Otto-279 carve-out is defined by docs/AGENT-BEST-PRACTICES.md, but that doc's closed list does NOT yet include docs/lost-substrate/**. Without an explicit reconciliation note, future readers see policy/tool drift between the doc and the script. Resolution: amended the script's comment block to make the doctrine-extension explicit. Three buckets now distinguished: - Canonical (in AGENT-BEST-PRACTICES.md closed list) - Tool-extended (lost-substrate; pending doctrine update to add it to the canonical list) - Always-skip (non-substrate paths) Plus a "Doctrine-extension follow-up" note: when AGENT-BEST- PRACTICES.md's Otto-279 closed list next gets edited, fold lost-substrate into the canonical list and remove the tool-extended note here. The doc remains the source of truth for the categorical rule; this script encodes the operational implementation. Behavior unchanged. Comment-only edit. --- tools/hygiene/audit-orphan-role-refs.sh | 25 ++++++++++++++++++++++--- 1 file changed, 22 insertions(+), 3 deletions(-) diff --git a/tools/hygiene/audit-orphan-role-refs.sh b/tools/hygiene/audit-orphan-role-refs.sh index 344b1b1378..7ad62cafef 100755 --- a/tools/hygiene/audit-orphan-role-refs.sh +++ b/tools/hygiene/audit-orphan-role-refs.sh @@ -44,7 +44,12 @@ # - root *.md (README, AGENTS, GOVERNANCE, CLAUDE.md, etc.) — # these are current-state surfaces per Otto-279 # -# Exclude (history surfaces — per Otto-279): +# Exclude (history surfaces — per Otto-279 carve-out at +# docs/AGENT-BEST-PRACTICES.md, plus this script's pragmatic +# extensions for surfaces NOT yet listed in the canonical +# closed list but which are by-definition history surfaces): +# +# Canonical (in AGENT-BEST-PRACTICES.md closed list): # - memory/** # - docs/research/** # - docs/aurora/** @@ -57,13 +62,27 @@ # 2026-04-29 call; see file's classification block) # - docs/backlog/** (per-row history of backlog filings; # authors, dated lineage, persona names allowed) -# - docs/lost-substrate/** (incident artifacts + dated -# inventory ledgers — by definition history-surface) # - docs/CURRENT-ROUND.md (round-history equivalent) # - docs/amara-full-conversation/** (verbatim archived # conversation — bootstrap-attempt-1 lineage) +# +# Tool-extended (this script's additions, pending a doctrine +# update that adds them to the canonical list — see +# "Doctrine-extension follow-up" below): +# - docs/lost-substrate/** (incident artifacts + dated +# inventory ledgers from corruption-triage events; by +# definition history-surface) +# +# Always-skip (non-substrate paths): # - .git/**, node_modules/**, third_party/** # +# Doctrine-extension follow-up: when the AGENT-BEST-PRACTICES.md +# Otto-279 closed list next gets edited, fold docs/lost-substrate/** +# into the canonical list and remove the tool-extended note here. +# Until that happens the lint extends the doc; the doc remains the +# source of truth for the categorical rule, this script encodes the +# operational implementation. +# # Output shape: # file:line:column: : #