Guidance unification: one canonical home per fact, a measured loader story, and a gate that keeps it true

.claude/commands/deslop-reborn.md

@@ -21,8 +21,8 @@ crate and skip the selection cascade in §1 — but still run the §1 Reborn/leg
 a legitimate Reborn target. Otherwise pick one per §1.
 
 ## 0. Environment & state
-- **Reborn-only.** All work targets the Reborn stack in `crates/` (root CLAUDE.md, "Where to Build
-  — the Reborn stack in `crates/`"). The v1 `src/` monolith and its legacy enclave
+- **Reborn-only.** All work targets the Reborn stack in `crates/` (root AGENTS.md, "Purpose and
+  precedence"). The v1 `src/` monolith and its legacy enclave
   (`ironclaw_engine`, `ironclaw_tui`, `ironclaw_gateway`, `ironclaw_oauth`) have all been removed,
   so every crate under `crates/` that the workspace builds is a legitimate target. Two caveats you can check in the root `Cargo.toml`: `tools/ironclaw_silk_decoder`
   is in `exclude`, so workspace-wide `cargo` commands never see it; and a crate with no consumers
@@ -85,7 +85,7 @@ If **every** Reborn crate is ledger-recorded or PR-held, this is a **no-de-slop
   **smallest self-contained slice** (one module / one invariant / one test gap) and record the rest in
   the ledger for the next iteration. Never open a sprawling multi-thousand-line refactor PR. Prefer
   **deleting** complexity over accreting layers.
-- **Privacy & logging doctrine (root CLAUDE.md — hard blockers).**
+- **Privacy & logging doctrine (root AGENTS.md security invariants + the REPL rule in root CLAUDE.md — hard blockers).**
   - **Never add a log line that prints a prompt, completion, key material, decrypted content, secret,
     or raw bytes** — log ids/counts/sizes/durations/error-types only. Treat any such existing line you
     find as a finding and fix it.
@@ -96,7 +96,7 @@ If **every** Reborn crate is ledger-recorded or PR-held, this is a **no-de-slop
     most valuable data in the system. Never strip, truncate, or delete them from the database; a
     "simplification" that drops retained LLM data is a blocker, not a fix. In-memory caches may be
     evicted; the database is the source of truth.
-- **Production-code conventions (root CLAUDE.md).** No `.unwrap()`/`.expect()` outside `#[cfg(test)]`;
+- **Production-code conventions (root AGENTS.md).** No `.unwrap()`/`.expect()` outside `#[cfg(test)]`;
   errors via `thiserror` with context; `crate::` imports (not `super::`) in non-test code; multi-line
   prompt templates live in `prompts/*.md` loaded via `include_str!()`, never inline Rust constants. A
   de-slop that *introduces* any of these is a self-inflicted finding — reject it (§6 guard).

.claude/rules/database.md

@@ -11,7 +11,7 @@ New persistence uses the `RootFilesystem` mount catalog. Consumers receive a
 `ScopedFilesystem` and typed domain wrappers; they do not choose backends or
 maintain parallel backend-dispatch traits.
 
-Read `crates/substrates/ironclaw_filesystem/CLAUDE.md` and the owning domain contract before
+Read `crates/substrates/ironclaw_filesystem/CONTRACT.md` and the owning domain contract before
 changing storage. Re-verify the core surface with:
 
 ```bash

.claude/rules/type-placement.md

@@ -91,14 +91,14 @@ Resolution order for an existing mirror:
    boundary and MUST stay manual so new sensitive fields do not auto-flow.
 4. `pub use` is legitimate only at an architecture-mandated contract facade;
    never use it as a path-preservation shim or dependency dodge.
-   This is the same exception CLAUDE.md's "no `pub use` re-exports unless
-   exposing to downstream consumers" already draws.
+   This is the same exception the root AGENTS.md's "no `pub use` re-exports
+   unless exposing to downstream consumers" already draws.
 
 ## Relocating a shared module — update imports, don't leave a re-export
 
 When a type or module used by several crates has to move to a lower crate so
 they can all reach it (the canonical case: a pure primitive shared across
-layers moves into `ironclaw_common`, and CLAUDE.md already permits *depending on
+layers moves into `ironclaw_common`, and the root AGENTS.md already permits *depending on
 `common`* from anywhere), **move it and update every consumer's import to the
 new path**. Do NOT leave a `pub use old_path::* ` shim in the original crate to
 preserve `old_crate::thing` call sites — that shim is exactly the

.claude/rules/types.md

@@ -41,7 +41,7 @@ turned each into a compile error.
 
 ## Extension/Auth identity invariant
 
-See `CLAUDE.md` → "Extension/Auth Invariants" for routing rules. The
+See `AGENTS.md` → "Extension/Auth Invariants" for routing rules. The
 types live in `crates/contracts/ironclaw_common/src/identity.rs`:
 
 - [`CredentialName`] — backend secret identity (e.g.

.claude/skills/architecture-video/SKILL.md

@@ -20,13 +20,13 @@ Generates and maintains the animated architecture overview video in `docs/intern
 
 Read these files to understand the current system architecture:
 
-- `CLAUDE.md` — top-level project structure, module specs, key traits, principles
+- `AGENTS.md` — top-level commands, invariants, tree map, module specs table
 - `crates/Architecture.md` — **the Reborn stack thesis and component map (the current architecture; lead the video with this)**
 - `crates/AGENTS.md` — the Reborn crate routing map
-- `crates/domains/ironclaw_llm/CLAUDE.md` — canonical LLM provider architecture
-- `src/db/CLAUDE.md` — database dual-backend architecture
-- `src/tools/README.md` — v1 tool system architecture
-- `src/workspace/README.md` — v1 workspace/memory architecture
+- `crates/domains/ironclaw_llm/CONTRACT.md` — canonical LLM provider architecture
+- `crates/substrates/ironclaw_filesystem/CONTRACT.md` — storage fabric / dual-backend architecture
+- `crates/extensions/AGENTS.md` — the installable-package family: extension packages, tool surfaces, lifecycle host (successor of the v1 tool system)
+- `crates/domains/ironclaw_memory/README.md` — the memory contract and conformance seam (successor of the v1 workspace/memory system)
 
 ### 2. Read current video scenes
 

.github/workflows/code_style.yml

@@ -40,6 +40,7 @@ jobs:
     runs-on: ubuntu-latest
     outputs:
       has_code: ${{ steps.non_pr.outputs.has_code || steps.diff.outputs.has_code }}
+      has_guidance: ${{ steps.non_pr.outputs.has_guidance || steps.diff.outputs.has_guidance }}
       has_docs: ${{ steps.non_pr.outputs.has_docs || steps.diff.outputs.has_docs }}
       has_reborn_cli: ${{ steps.non_pr.outputs.has_reborn_cli || steps.diff.outputs.has_reborn_cli }}
       has_clippy: ${{ steps.non_pr.outputs.has_clippy || steps.diff.outputs.has_clippy }}
@@ -50,6 +51,7 @@ jobs:
         if: github.event_name == 'push'
         run: |
           echo "has_code=true" >> "$GITHUB_OUTPUT"
+          echo "has_guidance=true" >> "$GITHUB_OUTPUT"
           echo "has_docs=true" >> "$GITHUB_OUTPUT"
           echo "has_reborn_cli=true" >> "$GITHUB_OUTPUT"
           echo "has_clippy=true" >> "$GITHUB_OUTPUT"
@@ -87,6 +89,26 @@ jobs:
             echo "No code changes — style checks will be skipped"
           fi
 
+          # The guidance gate (scripts/ci/check-guidance.py, run inside
+          # fast-checks) scans surfaces the code filter above deliberately
+          # leaves out: `.claude/` rules and skills (whose frontmatter
+          # `paths:` triggers it verifies), the root AGENTS.md/CLAUDE.md pair
+          # (reference seed + alias site), and `docs/` (the reference-target
+          # space guidance most often cites — a rename there must dangle
+          # references loudly, not merge green). Without this output a PR
+          # editing only `.claude/rules/` would skip the exact
+          # never-firing-trigger class the gate exists to catch (#7306
+          # review). `has_code` keeps its meaning — ws12_workflow_contracts.py
+          # pins docs/ and openwiki/ OUT of it — so this OR-s into
+          # fast-checks' condition only; the clippy and JS lanes stay
+          # code-scoped. openwiki/ stays out here too: it is generated by its
+          # own workflow and is not a check-guidance scan surface.
+          if printf '%s\n' "$CHANGED_FILES" | grep -Eq '^(\.claude/|AGENTS\.md$|CLAUDE\.md$|docs/)'; then
+            echo "has_guidance=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "has_guidance=false" >> "$GITHUB_OUTPUT"
+          fi
+
           # docs/ is deliberately NOT in the has_code scope above, so a
           # docs-only PR skips every Rust lane — the publication-boundary gate
           # needs its own trigger. The gate's own files are in scope so the
@@ -126,7 +148,10 @@ jobs:
   fast-checks:
     name: Fast deterministic checks
     needs: changes
-    if: needs.changes.outputs.has_code == 'true'
+    # `has_guidance` OR-s in the guidance surfaces (.claude/, root
+    # AGENTS.md/CLAUDE.md, docs/) so check-guidance.py runs for the files it
+    # governs; every other lane keys on `has_code` alone.
+    if: needs.changes.outputs.has_code == 'true' || needs.changes.outputs.has_guidance == 'true'
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
@@ -178,6 +203,7 @@ jobs:
           python3 scripts/ci/test_ws12_suite_shards.py
           python3 scripts/ci/test_ws12_workflow_contracts.py
           python3 scripts/ci/test-check-target-tree.py
+          python3 scripts/ci/test-check-guidance.py
           scripts/ci/test-hermetic-test-process.sh
           scripts/ci/test-reborn-docker-entrypoint.sh
           # #7144: this 204-test module had never been run by any lane, so five
@@ -208,6 +234,13 @@ jobs:
       # compares `cargo metadata` against the documented tree itself.
       - name: Check the crate tree matches PROPOSAL §5
         run: python3 scripts/ci/check-target-tree.py
+      # The guidance half of the same claim: every repo path the agent docs
+      # reference must be tracked, every `.claude/rules` `paths:` trigger must
+      # match at least one tracked file (a glob that matches nothing is a rule
+      # that never fires), and every crate must appear in its family's
+      # AGENTS.md crate table with a README.md (guidance-conventions.md).
+      - name: Check guidance references the tracked tree
+        run: python3 scripts/ci/check-guidance.py
       - name: Check composition mass budget
         run: bash scripts/ci/check-composition-budget.sh
       - name: Self-test the composition budget gate
@@ -543,6 +576,16 @@ jobs:
             exit 1
           fi
 
+          # Same reason as the docs gate above: a guidance-only PR has
+          # has_code=false, so fast-checks (which carries check-guidance.py)
+          # must be judged before the early exit or the gate would run and
+          # never be able to block — the inert-guard shape this whole change
+          # exists to remove.
+          if [[ "${{ needs.changes.outputs.has_guidance }}" == "true" && "${{ needs.fast-checks.result }}" != "success" ]]; then
+            echo "fast-checks failed: ${{ needs.fast-checks.result }}"
+            exit 1
+          fi
+
           if [[ "${{ needs.changes.outputs.has_code }}" == "false" ]]; then
             if [[ "${{ needs.changes.outputs.has_reborn_cli }}" == "true" && "${{ needs.reborn-cli-smoke.result }}" != "success" ]]; then
               echo "Reborn CLI smoke failed: ${{ needs.reborn-cli-smoke.result }}"