diff --git a/tools/hygiene/audit-orphan-role-refs.sh b/tools/hygiene/audit-orphan-role-refs.sh index cf15584f6d..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/** @@ -60,8 +65,24 @@ # - 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: : # @@ -131,6 +152,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/* | \