@adia-ai/adia-ui-forge 0.1.3 → 0.8.1

package/skills/adia-ui-ops/references/audit-patterns/orphan-detection.md

@@ -1,202 +0,0 @@
----
-date: 2026-04-27
-coverage: canonical
-peers:
-  - pointer-validation.md
-  - redundancy-detection.md
-  - token-waste-detection.md
-  - entry-file-coverage.md
-  - ../recipes/self-healing-hooks.md
-primary_sources:
-  - https://en.wikipedia.org/wiki/Reachability — graph reachability (the formal model behind orphan detection)
-  - https://github.com/lycheeverse/lychee — secondary; lychee's `--reachable` mode does similar accounting
-  - https://djw.fyi/portfolio/preventing-drift/ — Daryl White on doc archival flows
-status: research-verified
----
-
-# Orphan detection (delivers Promise 1, "less-wasteful")
-
-> **The premise.** A doc no one references is a doc no one reads — but it still costs tokens when a globbed `.brain/**/*.md` or `docs/**/*.md` load picks it up, still costs trust when a future reader finds it and can't tell whether it's current, and still drifts because no PR ever touches it. Orphans are the silent compounding cost of an unmaintained doc tree.
-
-## The graph model
-
-Treat the repo as a directed graph:
-
-- **Nodes:** every Markdown file under `.brain/**` and `docs/**` plus the top-level entries (`AGENTS.md`, `CLAUDE.md`, `README.md`, `CONTRIBUTING.md`, etc.).
-- **Edges:** every relative-path link from one node to another (extracted by the same grammar `pointer-validation.md` uses).
-- **Roots:** `AGENTS.md` is the canonical root. `CLAUDE.md` (when fat), `README.md`, and `CONTRIBUTING.md` are secondary roots.
-- **Orphan:** any node in `.brain/**` or `docs/**` that is **not reachable** from any root.
-
-Reachability is transitive — if `AGENTS.md` links `ARCHITECTURE.md` and `ARCHITECTURE.md` links `docs/services/auth.md`, then `auth.md` is reachable.
-
-## What this pattern catches
-
-| # | Class | Example | Severity |
-|---|---|---|---|
-| 1 | **Orphaned active doc** | `docs/setup-2024.md` not referenced; still describes current behavior | Medium |
-| 2 | **Orphaned stale doc** | `docs/old-redis-setup.md` not referenced AND last touched 18 months ago | Medium |
-| 3 | **Orphaned generated content** | `docs/api/Foo.md` from a typedoc dump nobody linked | Low (fix is `.gitignore`, not archive — see `redundancy-detection.md`) |
-| 4 | **Orphan with inbound link from outside `docs/`** | `docs/onboarding.md` linked from a `package.json` script comment but not from any doc | Low (advisory — re-link from AGENTS.md) |
-
-## The bash check
-
-Two-pass set-difference: build the set of *files in `.brain/` + `docs/`*, build the set of *files referenced from a root or its transitive closure*, diff.
-
-```bash
-#!/usr/bin/env bash
-# scripts/find-orphan-docs.sh — find .brain/*.md and docs/*.md unreachable from any root.
-set -euo pipefail
-
-all_docs=$(find .brain docs -type f -name '*.md' 2>/dev/null | sort -u)
-
-roots=()
-for r in AGENTS.md CLAUDE.md README.md CONTRIBUTING.md \
-         .cursorrules .windsurfrules \
-         .github/copilot-instructions.md .github/pull_request_template.md \
-         .brain/README.md .brain/INDEX.md docs/README.md docs/INDEX.md; do
-    [ -f "$r" ] && roots+=("$r")
-done
-
-# Extract resolved relative-path link targets from a Markdown file.
-extract_links() {
-    local src_dir; src_dir=$(dirname "$1")
-    grep -oE '\]\([^)]+\)' "$1" \
-      | sed -E 's/^\]\(//; s/\)$//; s/[[:space:]]+["\x27].*$//; s/#.*$//' \
-      | while read -r path; do
-            case "$path" in ''|http://*|https://*|mailto:*|file://*) continue ;; esac
-            if [ -d "$src_dir/$path" ]; then
-                find "$src_dir/$path" -maxdepth 1 -name '*.md' 2>/dev/null
-            else
-                python3 -c "import os,sys; print(os.path.normpath('$src_dir/$path'))"
-            fi
-        done
-}
-
-# Transitive closure: BFS from roots.
-declare -A reachable
-queue=("${roots[@]}")
-while [ "${#queue[@]}" -gt 0 ]; do
-    src="${queue[0]}"; queue=("${queue[@]:1}")
-    [ -n "${reachable[$src]:-}" ] && continue
-    reachable[$src]=1
-    [ -f "$src" ] || continue
-    while read -r t; do [ -f "$t" ] && queue+=("$t"); done < <(extract_links "$src")
-done
-
-for f in $all_docs; do
-    [ -z "${reachable[$f]:-}" ] && \
-        echo "ORPHAN: $f (last modified: $(git log -1 --format=%cs -- "$f"))"
-done
-```
-
-Notes: `python3` only normalizes paths (swap for `realpath --relative-to=.` if unavailable). Reference-style links (`[text][ref]`) aren't parsed — use `lychee --include-paths` if needed.
-
-## What to do with each orphan (the three-way choice)
-
-For every `ORPHAN: <file>` finding, the audit recommends one of three actions. **Always via PR**, never silently:
-
-### (a) Re-link — orphan is still relevant
-
-The doc is current but unpointed. Add a link from AGENTS.md's "Where to find things" or the area `docs/<area>/README.md`:
-
-```markdown
-# AGENTS.md (excerpt)
-
-## Where to find things
-
-- **Architecture:** `.brain/architecture/`
-- **ADRs:** `.brain/adrs/`
-- **Onboarding:** `docs/onboarding.md`   <-- newly re-linked
-- **Post-mortems:** `.brain/postmortems/`
-```
-
-### (b) Archive — orphan is obsolete-but-historic
-
-Cutting loses institutional memory; keeping in place invites confusion. Move to `.brain/archive/`:
-
-```bash
-git mv docs/old-redis-setup.md .brain/archive/old-redis-setup.md
-git commit -m 'docs: archive old-redis-setup.md (orphan, obsolete since 2025-10 Redis -> Memorystore migration)'
-```
-
-The `.brain/archive/` folder gets its own `README.md` listing what's in there and why it's archived. The audit *excludes* `.brain/archive/**` from the orphan scan (everything in there is intentionally orphaned).
-
-### (c) Delete — if the orphan adds no value
-
-Truly obsolete content with no historical interest. **In a PR**, never silently:
-
-```bash
-git rm docs/notes-from-old-design-meeting.md
-git commit -m 'docs: remove obsolete design-meeting notes (orphan, no longer relevant)'
-```
-
-The PR description must say *why* — so a future reader who finds the deletion in `git log` understands the rationale.
-
-## The 30-day grace period
-
-Per `../recipes/self-healing-hooks.md`, the auto-archive workflow does *not* archive on the first scan after a doc goes orphaned. The grace period is **30 days** of being orphaned-and-untouched before auto-archive proposes a PR.
-
-Reasons: (1) a PR in flight may temporarily orphan a doc while a link is being moved; (2) a planned re-link may be queued; (3) genuine forgotten orphans accumulate dust within 30 days regardless. The audit *report* always lists current orphans; the *auto-archive workflow* applies the 30-day floor before acting.
-
-## Always-referencing files (avoid false positives)
-
-Some files act as *indices* — they enumerate every file in a folder, so every file in that folder is reachable by virtue of the index existing. Treat these as ALWAYS_REFERENCING in the orphan-scan reachability graph:
-
-| File | What it indexes |
-|---|---|
-| `.brain/adrs/README.md` | every ADR (`0001-*.md` … `NNNN-*.md`) |
-| `.brain/postmortems/README.md` | every postmortem |
-| `.brain/runbooks/README.md` | every runbook |
-| `docs/specs/INDEX.md` | every spec |
-| `docs/journal/README.md` | every dated journal entry |
-
-Without them in the entry-file set, every ADR / postmortem / runbook / spec / journal entry shows up as an orphan — a false-positive cluster that drowns the real findings. Observed in the wild on 2026-04-29: an audit pass flagged seven ADRs as orphans because the orphan-scan didn't include `.brain/adrs/README.md` as a referencer. Adding it resolved all seven.
-
-The rule is index-shaped: any folder with a `README.md` whose body is a *table* listing the folder's files counts as a referencer. Apply this in the entry-file set:
-
-```bash
-ENTRY_FILES=(
-  "AGENTS.md" "CLAUDE.md" "README.md" "PLAN.md" "ROADMAP.md"
-  ".brain/adrs/README.md"          # ← add these
-  ".brain/postmortems/README.md"
-  ".brain/runbooks/README.md"
-  "docs/specs/INDEX.md"
-  "docs/journal/README.md"
-)
-```
-
-## Excluding intentional orphans
-
-Some docs are intentionally orphaned. Mark them so the audit doesn't keep flagging:
-
-| Convention | What it does |
-|---|---|
-| Place file under `.brain/archive/**` | Excluded from orphan scan |
-| Add YAML frontmatter `orphan: intentional` | Excluded from orphan scan |
-| Add file to `.brain/ignore` (one path per line) | Excluded from orphan scan |
-
-The skill recommends `.brain/archive/` as the default — it's the most discoverable. Frontmatter and ignorefile are escape hatches.
-
-## Severity rubric
-
-| Finding | Severity | Why |
-|---|---|---|
-| Orphaned doc that contradicts AGENTS.md (stale active content) | High | Causes drift if anyone finds and follows it |
-| Orphaned active doc (matches code/AGENTS.md but unlinked) | Medium | Useful content, agent never finds it |
-| Orphaned stale doc (>6mo old, no `_Last reviewed:_`) | Medium | Obsolete; archive candidate |
-| Orphaned generated content (typedoc/sphinx/etc.) | Low | Fix is `.gitignore`, not archive — see `redundancy-detection.md` |
-| Orphaned doc with inbound link from non-doc source (script comment, code) | Low | Re-link from AGENTS.md and move on |
-
-## What this pattern is NOT for
-
-- **Files outside `.brain/` and `docs/`** — orphan-detection scope is `.brain/**` and `docs/**`. Top-level files (`LICENSE`, `package.json`) aren't candidates.
-- **Code files** — dead-code detection is a separate problem. This audit is about *documentation*.
-- **Folders with no `.md`** — assets-only folders (`docs/images/`) don't get scanned. They're referenced from inside `.md` files via `![alt](images/foo.png)`, which is a `pointer-validation.md` concern.
-
-## Cross-references
-
-- Pointer validation (the inverse — links that don't resolve): `pointer-validation.md`
-- Redundancy detection (sibling Promise 1 audit): `redundancy-detection.md`
-- Token-waste detection (orphans contribute to glob-load tax): `token-waste-detection.md`
-- Entry-file coverage (the precondition — roots exist): `entry-file-coverage.md`
-- Auto-archive workflow + 30-day grace: `../recipes/self-healing-hooks.md`

package/skills/adia-ui-ops/references/audit-patterns/pointer-validation.md

@@ -1,180 +0,0 @@
----
-date: 2026-04-27
-coverage: canonical
-peers:
-  - orphan-detection.md
-  - stale-content.md
-  - staleness-tooling.md
-  - entry-file-coverage.md
-  - ../recipes/self-healing-hooks.md
-primary_sources:
-  - https://github.com/lycheeverse/lychee — fast Markdown/HTML link checker (Rust)
-  - https://daringfireball.net/projects/markdown/syntax#link — original Markdown link syntax (Gruber)
-  - https://spec.commonmark.org/0.31.2/#links — CommonMark 0.31.2 link grammar
-status: research-verified
----
-
-# Pointer validation (delivers Promise 1, "less-wasteful" + Promise 3, "less-prone-to-staleness")
-
-> **The premise.** A pointer that doesn't resolve is worse than no pointer. The agent follows the link, hits a 404, and either gives up (silent failure) or hallucinates (loud failure). This audit catches every relative-path reference in the repo's instruction graph and verifies it lands on a real file before the agent ever has to.
-
-## What this pattern catches
-
-Five classes of broken pointer:
-
-| # | Class | Example | Severity |
-|---|---|---|---|
-| 1 | **Pointer to a renamed/moved file** | AGENTS.md says `docs/architecture.md`; file was moved to `.brain/architecture/overview.md` six months ago | High |
-| 2 | **Pointer to a never-existed file** | Author typo: `.brain/runbooks/databse.md` (missing the `a`) | High |
-| 3 | **Pointer to a folder without an index** | AGENTS.md says `.brain/adrs/`; folder exists but no `README.md` to land on | Medium |
-| 4 | **Pointer from canonical file to missing file** | AGENTS.md links `[Memory primitives](docs/memory.md)`; that file is gone | **Critical** |
-| 5 | **Repo-root file using `docs/`-relative paths** | `PLAN.md` at repo root has `[spec](./specs/foo.md)`; resolves to `./specs/foo.md` (404), should be `./docs/specs/foo.md` | **Critical** |
-
-Class 4 is the load-bearing case: the canonical entry file is the agent's single source of truth, and a broken link from it is a broken promise to every agent on every session.
-
-Class 5 is a particularly nasty failure mode that surfaces when a doc gets moved between directories without its links being rewritten. **Watch for it** when `PLAN.md` / `ROADMAP.md` / `CHANGELOG.md` move from `docs/` to repo root (or vice versa), or when `docs/foo/bar.md` is hoisted to `docs/bar.md`. The check below catches it because relative-path resolution starts from the source file's directory — but human reviewers miss it constantly because the *display text* often shows the correct path while the link itself is wrong:
-
-```markdown
-[`docs/specs/genui-multiturn.md`](./specs/genui-multiturn.md)
-                                    ↑ broken — file is at root, not docs/
-```
-
-Observed in the wild on 2026-04-29: 25+ broken intra-repo links across `PLAN.md` + `ROADMAP.md` after the files were moved from `docs/` to repo root. Display text was correct on every link; targets all wrong.
-
-## Scope: what files we validate pointers from
-
-| File | Why |
-|---|---|
-| `AGENTS.md` | Canonical entry; every link must resolve |
-| `CLAUDE.md` (when fat) | Same as AGENTS.md while it's still fat; once thin-pointered the only link is to AGENTS.md |
-| `README.md` | Human + agent landing |
-| `CONTRIBUTING.md` | Often points at `docs/dev-setup.md` etc. |
-| `.brain/**/*.md`, `docs/**/*.md` | Doc-to-doc links must resolve too |
-| `.cursor/rules/*.mdc`, `.windsurfrules`, `.github/copilot-instructions.md` | If fat, validate; if thin pointers to AGENTS.md, only the one link to validate |
-| `.github/pull_request_template.md` | Often points at ADR conventions / contribution guides |
-
-Validate **relative paths only**. External URLs are `lychee`'s job — see `staleness-tooling.md` for the tool wiring. `lychee` will *also* check intra-repo paths, but the skill implements its own check so the audit can run offline and produce structured findings independent of `lychee` being installed.
-
-## The bash check (intra-repo links)
-
-The link-extraction grammar (CommonMark 0.31.2 §6.3) is `[text](target)` with optional title. We capture `target` and check it.
-
-```bash
-#!/usr/bin/env bash
-# scripts/check-pointers.sh
-# Validate every relative-path link in entry + docs files.
-set -euo pipefail
-
-# Files we extract pointers from.
-candidates=(
-    AGENTS.md CLAUDE.md README.md CONTRIBUTING.md
-    .cursorrules .windsurfrules
-    .github/copilot-instructions.md
-    .github/pull_request_template.md
-)
-for f in .brain/**/*.md .brain/*.md docs/**/*.md docs/*.md .cursor/rules/*.mdc 2>/dev/null; do
-    [ -f "$f" ] && candidates+=("$f")
-done
-
-fail=0
-for src in "${candidates[@]}"; do
-    [ -f "$src" ] || continue
-    # Extract the (target) of every Markdown link, drop quoted titles.
-    grep -oE '\]\([^)]+\)' "$src" \
-        | sed -E 's/^\]\(//; s/\)$//; s/[[:space:]]+["\x27].*$//' \
-        | sort -u \
-        | while read -r target; do
-            # Skip empty, anchors-only, mailto:, and absolute URLs.
-            case "$target" in
-                ''|'#'*|mailto:*|http://*|https://*|ftp://*|file://*) continue ;;
-            esac
-            # Strip fragment (#section) before resolving.
-            path="${target%%#*}"
-            [ -z "$path" ] && continue
-            # Resolve relative to the source file's directory.
-            src_dir=$(dirname "$src")
-            resolved="$src_dir/$path"
-            # Folder pointer? Accept if folder exists and has a README.md or any *.md.
-            if [ -d "$resolved" ]; then
-                if [ -f "$resolved/README.md" ] || ls "$resolved"/*.md >/dev/null 2>&1; then
-                    continue
-                fi
-                echo "EMPTY-FOLDER-POINTER: $src -> $target (folder exists but no .md inside)"
-                fail=1
-                continue
-            fi
-            # File pointer.
-            if [ ! -f "$resolved" ]; then
-                echo "BROKEN-POINTER: $src -> $target (resolved: $resolved)"
-                fail=1
-            fi
-        done
-done
-exit $fail
-```
-
-Dedupe is done by `sort -u` per file — the same target referenced 5 times in one file emits only one finding.
-
-## The dedupe step (why it matters for the report)
-
-A 200-line AGENTS.md often references `.brain/adrs/` 4-6 times (Where-to-find-things, Memory-primitives, Conventions, etc.). Without dedupe, a single broken folder produces a 6-line report. Dedupe per-source-file before reporting; the same target broken from multiple files is genuinely worth multiple findings (it tells you *where* to fix).
-
-## Folder-pointer special case
-
-A pointer like `.brain/adrs/` is not a file — it's a folder. The check passes if:
-
-1. The folder exists, AND
-2. The folder has a `README.md`, OR
-3. The folder contains at least one `.md` file (so the agent can list and pick).
-
-A folder with `.png` and `.svg` only is not a valid landing target for a doc pointer. Flag it with `EMPTY-FOLDER-POINTER`.
-
-## External link validation (out of scope for this check)
-
-External URLs (`https://...`) are validated by `lychee` per `staleness-tooling.md`. Reasons we keep them separate:
-
-- External checks need network; intra-repo checks must run offline.
-- External links rate-limit; intra-repo links are free.
-- External links are validated weekly (cron) per `../recipes/self-healing-hooks.md`; intra-repo links are validated on every commit.
-
-If you want a one-shot "all links" pass, run both sequentially:
-
-```bash
-bash scripts/check-pointers.sh   # intra-repo, fast, offline
-lychee --no-progress '.brain/**/*.md' 'docs/**/*.md' '*.md'   # external + intra-repo, network-bound
-```
-
-The intra-repo check is allowed to be redundant with `lychee --offline`; what it adds is structured output the audit pipeline can ingest without parsing `lychee` JSON.
-
-## Severity rubric
-
-| Finding | Severity | Why |
-|---|---|---|
-| Broken pointer **from AGENTS.md** to a canonical file (`.brain/adrs/`, `.brain/postmortems/`, `.brain/architecture/`) | **Critical** | Agent's primary memory map is wrong; trust collapses |
-| Broken pointer from any other entry file (`CLAUDE.md`, `README.md`, `.cursor/rules/`) | High | Agent following that tool will hit 404 |
-| Broken doc-to-doc pointer in `.brain/**` or `docs/**` | High | Reachable but breaks navigation graph |
-| Empty-folder pointer (`.brain/runbooks/` exists, no `.md` inside) | Medium | Agent lands but finds nothing actionable |
-| Pointer with stale fragment (`docs/foo.md#old-section` where the file exists but the anchor doesn't) | Low | File loads, agent skim-reads; advisory |
-
-The fragment check (`#section-name` resolves to a real heading slug) is supported by `lychee --include-fragments` and is the cleanest way to catch class 5. Don't reimplement slug-generation in bash; pay the lychee dependency.
-
-## What this pattern is NOT for
-
-- **External links** — `staleness-tooling.md`'s `lychee` integration owns those.
-- **Symbol references inside prose** — "the `FooHandler` class" is a *content* claim, not a pointer; it's covered by `stale-content.md`.
-- **Image / asset paths** — same machinery works (`![alt](path/to/img.png)`), but assets are usually checked-in alongside the doc, so failures are rare. The check above will catch them anyway.
-- **Reference-style links** (`[text][ref]` with `[ref]: target` later in the file) — the bash above doesn't parse them. CommonMark §6.3.2. If your repo uses them, swap to a Python parser (`markdown-it-py`) or run `lychee --offline` which handles them natively.
-
-## How AGENTS.md's pointers become self-healing
-
-The pre-commit hook in `../recipes/self-healing-hooks.md` runs this check on every commit that touches `AGENTS.md`, `CLAUDE.md`, `README.md`, `CONTRIBUTING.md`, or any file under `.brain/**` or `docs/**`. A broken pointer fails the commit — the author is forced to fix it locally. This is the cheapest place to catch it; by the time it reaches CI, the author has already context-switched.
-
-The weekly cron (`repo-brain-weekly.yml`) re-runs the check across the whole repo (in case a PR touched a target without touching the source pointing at it — the canonical "rename without re-link" case).
-
-## Cross-references
-
-- Orphan detection (the inverse — files no one points at): `orphan-detection.md`
-- Stale content (symbol-level rot): `stale-content.md`
-- External link checking: `staleness-tooling.md`
-- Entry-file coverage (the precondition — entry files exist): `entry-file-coverage.md`
-- Self-healing hooks (where the check runs automatically): `../recipes/self-healing-hooks.md`

package/skills/adia-ui-ops/references/audit-patterns/redundancy-detection.md

@@ -1,210 +0,0 @@
----
-date: 2026-04-27
-coverage: canonical
-peers:
-  - orphan-detection.md
-  - token-waste-detection.md
-  - ../standards/claude-md-convention.md
-  - ../recipes/self-healing-hooks.md
-primary_sources:
-  - https://github.com/anthropics/claude-code/issues/31005
-status: research-verified
----
-
-# Redundancy detection (delivers Promise 1, "less-wasteful")
-
-> **The premise.** Redundancy is waste *and* drift waiting to happen. Two files saying "use pnpm" will, eventually, disagree — one will say `pnpm`, the other will say `npm` after a sloppy edit. The audit's job is to detect redundancy *before* it drifts.
-
-## What this pattern catches
-
-Five classes of redundancy:
-
-| Class | Example | Severity |
-|---|---|---|
-| **Drift between entry files** | CLAUDE.md and AGENTS.md both fat with substantively different content | Critical |
-| **Repeated commands** | Build commands listed in AGENTS.md, README.md, AND CONTRIBUTING.md | Medium |
-| **Repeated facts** | "We use Postgres" stated in AGENTS.md, ARCHITECTURE.md, AND README.md | Low |
-| **Verbose-vs-tabular duplication** | Same conventions written as prose AND as a table later in the same file | Low |
-| **Generated content checked in alongside source** | API reference markdown alongside the docstrings it was generated from | Medium |
-
-## Drift between entry files (the critical case)
-
-This is the audit's single most-important check. Claude Code reads CLAUDE.md, every other agent reads AGENTS.md natively (per `cross-tool-matrix.md`). When the two files contain different instructions, the team has two failure modes simultaneously:
-
-1. **Claude Code follows out-of-date rules** (because CLAUDE.md is stale).
-2. **Cursor/Codex/Devin follow out-of-date rules** (because AGENTS.md is stale).
-
-The fix is the canonical model from this skill: AGENTS.md fat, CLAUDE.md as symlink or thin pointer.
-
-### Detection logic
-
-```bash
-# Pseudocode for the drift check
-if [ ! -f AGENTS.md ] || [ ! -f CLAUDE.md ]; then
-    # No drift possible
-    exit 0
-fi
-
-if [ -L CLAUDE.md ] && [ "$(readlink CLAUDE.md)" = "AGENTS.md" ]; then
-    # Symlink → identical content
-    exit 0
-fi
-
-claude_lines=$(wc -l < CLAUDE.md)
-if [ "$claude_lines" -le 15 ] && grep -qi 'AGENTS.md' CLAUDE.md; then
-    # Thin pointer → no fat content to drift
-    exit 0
-fi
-
-# Both fat → drift risk; emit finding
-echo "DRIFT — CLAUDE.md ($claude_lines lines) vs AGENTS.md ($(wc -l <AGENTS.md) lines)"
-echo "  Diff highlights:"
-diff <(grep -v '^$' CLAUDE.md) <(grep -v '^$' AGENTS.md) | head -20
-```
-
-The full hook is in `../recipes/self-healing-hooks.md`.
-
-### Recipe to fix
-
-```bash
-# Pick AGENTS.md as canonical (recommended).
-# Move CLAUDE.md content into AGENTS.md, deduplicating.
-# Then:
-
-# Option A: symlink (cleanest)
-rm CLAUDE.md
-ln -s AGENTS.md CLAUDE.md
-git add CLAUDE.md
-git commit -m 'docs: CLAUDE.md → symlink to AGENTS.md (eliminate drift)'
-
-# Option B: thin pointer (works on Windows, no symlink quirks)
-cat > CLAUDE.md <<'EOF'
-# CLAUDE.md
-
-This repo's instructions for LLM coding agents live in [`AGENTS.md`](./AGENTS.md).
-Please read that file. The contents apply identically to Claude Code.
-
-_Last reviewed: 2026-04-27_
-EOF
-git add CLAUDE.md
-git commit -m 'docs: CLAUDE.md → thin pointer to AGENTS.md'
-```
-
-## Repeated commands
-
-A common pattern: build/test/run commands appear in AGENTS.md, README.md, and CONTRIBUTING.md. Each is true at the moment of writing; one will eventually drift.
-
-### Detection
-
-```bash
-# Heuristic: extract code-fenced shell blocks from each file, hash them, find duplicates.
-for f in AGENTS.md README.md CONTRIBUTING.md .brain/**/*.md docs/**/*.md; do
-    [ -f "$f" ] || continue
-    awk '/^```(bash|sh|shell)/,/^```$/' "$f" | sha256sum | awk -v f="$f" '{print f, $1}'
-done | sort -k2 | awk '{
-    if ($2 == prev_hash) print "DUPLICATE: " prev_file " <-> " $1;
-    prev_file = $1; prev_hash = $2
-}'
-```
-
-Tighter heuristic: parse out individual commands (lines starting with `$ ` or matching `pnpm|npm|yarn|cargo|go run`) and find which appear in multiple files.
-
-### Fix recipe
-
-Pick a canonical home (AGENTS.md is typical). Other files reference it:
-
-```markdown
-# README.md (excerpt)
-
-## Build / test / run
-
-See [`AGENTS.md`](./AGENTS.md) for build, test, and run commands.
-```
-
-```markdown
-# CONTRIBUTING.md (excerpt)
-
-## Local setup
-
-For build / test / run commands, see [`AGENTS.md`](./AGENTS.md). For
-contribution conventions, continue below.
-```
-
-The agent reads AGENTS.md every session anyway, so this isn't a navigation cost.
-
-## Repeated facts
-
-Lower severity: same fact ("we use Postgres") appears in 3 places. The fact rarely changes, so drift risk is low — but tokens are wasted on each load.
-
-### Detection
-
-This is hard to automate well — paraphrased duplicates evade hashing. Practical approach: look for *named entities* (technology names, version numbers, named services) that appear in multiple top-level docs, and surface as "consider consolidating."
-
-```bash
-# Heuristic: find tech names that appear in 3+ entry-level docs
-grep -l -i -E '\b(postgres|mysql|redis|kafka|s3|aws|gcp|azure)\b' \
-    AGENTS.md README.md CONTRIBUTING.md ARCHITECTURE.md 2>/dev/null \
-    | sort | uniq -c | sort -rn | awk '$1 >= 3 { print "POSSIBLE-REDUNDANCY: " $2 }'
-```
-
-Treat as advisory; humans decide whether to consolidate.
-
-## Verbose-vs-tabular duplication within one file
-
-A surprisingly common pattern: AGENTS.md says
-
-> "We use TypeScript with strict mode enabled. Our test runner is Vitest. We use Conventional Commits for commit messages. ESLint is configured for our coding style."
-
-...and then *also* has:
-
-```markdown
-| Tool | Choice |
-|---|---|
-| Language | TypeScript (strict) |
-| Tests | Vitest |
-| Commits | Conventional |
-| Linting | ESLint |
-```
-
-Both communicate the same facts. Cut the prose, keep the table — bullets/tables are denser and the agent prefers them.
-
-### Detection
-
-Hard. Practical heuristic: flag files with both `^>` blockquotes longer than 100 chars AND a Markdown table covering similar content. Manual review.
-
-## Generated content checked in
-
-If the project generates API reference markdown (TypeDoc, sphinx, mkdocs-jsdoc, rustdoc → md, etc.), don't check in the output:
-
-```
-# .gitignore (excerpt)
-docs/api/                       # generated by `pnpm docs:generate`
-docs/typedoc/                   # generated by TypeDoc
-```
-
-The audit signal: many `.md` files in `docs/api/` or `docs/typedoc/` that look auto-generated (template-driven structure, very uniform front-matter, mass-modified in single commits). These get loaded as orphan candidates by the orphan-detection pass — but the right fix is `.gitignore`, not archive.
-
-## Severity rubric
-
-| Finding | Severity | Why |
-|---|---|---|
-| AGENTS.md / CLAUDE.md drift (both fat, divergent) | Critical | Causes Claude Code and other agents to follow different rules |
-| Repeated build commands across 3+ files | Medium | High drift risk over time |
-| Repeated facts (named entities) across 3+ docs | Low | Drift risk lower; tokens wasted |
-| Verbose+tabular duplication in same file | Low | Internal redundancy; advisory |
-| Generated content checked in | Medium | Bloats repo, confuses orphan detection |
-
-## What this pattern is NOT for
-
-- **Repeated *links*** are good. Linking to AGENTS.md from README.md is fine — it's *not* duplicating content, it's pointing to it.
-- **Repeated section headers** (every ADR has a "Status:" section) are not redundancy — they're structural convention.
-- **Repeated examples** in docs (e.g., the same `pnpm install` shown in a setup walkthrough) are not redundancy if each appears in a different procedural context.
-
-## Cross-references
-
-- Orphan detection (sibling Promise 1 audit): `orphan-detection.md`
-- Token-waste detection (sibling Promise 2 audit): `token-waste-detection.md`
-- CLAUDE.md thin-pointer recipe: `../standards/claude-md-convention.md`
-- Self-healing hooks (where the drift trip-wire lives): `../recipes/self-healing-hooks.md`
-- Concurrent learnings merge (uses this trip-wire as the post-merge backstop): `../recipes/concurrent-learnings-merge.md`
-- Cold-start harvest (uses this trip-wire to detect imported conflicts in phase 5): `../recipes/cold-start-harvest.md`