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

package/skills/adia-ui-ops/references/recipes/external-reference-verification.md

@@ -1,158 +0,0 @@
----
-date: 2026-04-27
-coverage: canonical
-peers:
-  - ../audit-patterns/stale-content.md
-  - ../audit-patterns/staleness-tooling.md
-  - recommend-then-validate.md
-  - ../audit-patterns/audit-history-ledger.md
-primary_sources:
-  - https://github.com/karpathy/autoresearch — autonomous propose-evaluate-iterate (spirit-source)
-  - https://github.com/lycheeverse/lychee — link checker (the *liveness* check this recipe complements)
-status: research-verified
----
-
-# External-reference verification (WebFetch-powered)
-
-> _"You're not touching any of the Python files like you normally would as a researcher. Instead, you are programming the `program.md` Markdown files that provide context to the AI agents."_
-> — Andrej Karpathy, [autoresearch](https://github.com/karpathy/autoresearch)
-
-The premise: **`lychee` tells you a link is broken; it doesn't tell you the live link points to outdated content.** External-reference verification fetches the current state of cited URLs, library docs, and spec pages, compares to what the doc claims, and proposes specific corrections.
-
-This recipe imports autoresearch's *spirit* (focused research question → fetch → evaluate → propose) into repo-fixer, scoped to the one place where its loop genuinely fits: external-reference verification.
-
-## What it catches that other staleness tools miss
-
-| Tool | Catches | Doesn't catch |
-|---|---|---|
-| `lychee` | Dead links (404s, timeouts) | Live links pointing to outdated content |
-| Git-mtime heuristic | Old files | New files with stale facts |
-| LLM-on-diff | Code-doc drift in *this* repo | External-world drift |
-| **External-ref verification** | "AGENTS.md cites Promise.try as Stage 3; MDN now shows Stage 4 shipped" | (this — the gap the others leave) |
-
-Examples of what it catches:
-
-- "Use Node 18+" — Node 24 has been LTS for a year
-- "ES2022 features" — should be ES2025 now
-- "GitHub Copilot doesn't read AGENTS.md" — it does (since 2025-08-28)
-- Cited library version that's three majors behind
-- TC39 proposal Stage that's advanced
-- WCAG / ARIA spec citation pointing at a superseded version
-
-## The loop (autoresearch DNA)
-
-```
-1. SCAN
-   - Audit emits STALE-EXTERNAL-REF findings (per audit-patterns/stale-content.md)
-   - Each finding: { file, line, cited_url, current_claim }
-
-2. FETCH    ← the autoresearch step
-   - For each finding, WebFetch the cited URL or canonical doc
-   - Extract the current state (version, status, behavior)
-   - Cap fetches per audit run (default: 30) to bound cost
-
-3. COMPARE
-   - ALIGNED: doc matches reality → no fix
-   - STALE: doc disagrees with reality → propose fix
-   - AMBIGUOUS: can't tell → flag for manual review
-
-4. PROPOSE
-   - Build a specific edit including:
-     - File + line
-     - Original text
-     - Replacement text
-     - Source URL + fetch date
-
-5. VALIDATE (per recommend-then-validate.md)
-   - Dry-run the edit against trip-wires
-   - Verify the source URL is not on a deny-list
-
-6. PR
-   - Opens with verified corrections
-   - Each correction cites the source URL it was verified against
-```
-
-## Sample finding → fix output
-
-```markdown
-## STALE-EXTERNAL-REF (severity: medium)
-
-**File:** docs/POLYFILLS.md:47
-**Cited URL:** https://github.com/tc39/proposal-promise-try
-**Current claim in doc:** "Promise.try is at Stage 3"
-**Verified state (fetched 2026-04-27):** "Stage 4, shipping in Chrome 128 / Safari 18.2 / Firefox 134"
-
-**Proposed correction:**
-- Line 47: replace "Stage 3" with "Stage 4 (shipping Chrome 128 / Safari 18.2 /
-  Firefox 134, per [tc39/proposal-promise-try](https://github.com/tc39/proposal-promise-try)
-  accessed 2026-04-27)"
-
-**Validator check:** PASS (no broken links introduced; no entry-file length impact)
-```
-
-## Configuration
-
-`.brain/config.toml`:
-
-```toml
-[ops-repo.external-ref-verification]
-enabled = false                   # default: opt-in
-max_fetches_per_run = 30          # cost ceiling
-fetch_timeout_seconds = 15
-cache_days = 7                    # share fetches across same-week audits
-deny_list = ["pastebin.com", "*.s3.amazonaws.com/private-*"]
-allow_list_only = false
-allowed_domains = []              # used only when allow_list_only=true
-```
-
-Disabled by default — fetching costs money and time, and most repos don't need verification on every audit. Enable for repos with substantive external-reference surface (API integrations, browser-support tables, framework-version docs, language-spec citations).
-
-## How autoresearch DNA maps in (and where it stops)
-
-Autoresearch is **overnight hill-climbing on a single file with a single metric**, fully unattended. This recipe is **a focused research probe per finding**, bounded and reviewed:
-
-| Autoresearch | This recipe |
-|---|---|
-| Iterates over `train.py` | Iterates over external-ref findings |
-| Metric: `val_bpb` | Metric: cited claim matches fetched reality (yes/no/ambiguous) |
-| Search through candidates | One probe per finding (no candidate search) |
-| Overnight unattended | Single CI run, human-reviewed PR |
-| Hill-climbing | Direct lookup |
-
-We import the *spirit* — autonomous propose-evaluate within a budget, with WebFetch as the eval mechanism. We don't import the loop shape. Yegge-aligned shepherding stays intact.
-
-## When to use it
-
-- Docs that cite external APIs, frameworks, libraries, or specs (e.g., `ref-polyfills`-style reference repos)
-- Quarterly cadence is enough for most teams (scheduled GitHub Action, not every PR)
-- Useful for "stop external-world rot" — the audit history ledger then shows trend data on how often external refs go stale
-
-## When NOT to use it
-
-- **Internal-only repos** with no external citations
-- **Cost-sensitive contexts** where 30 fetches per audit is a meaningful expense
-- **Heavy-fetch repos** where the cap would miss most references — split into per-doc audits instead
-- **Privacy-sensitive content** where fetching cited URLs leaks repo-internal information
-
-## Privacy & cost considerations
-
-- Don't fetch URLs from `.brain/postmortems/` (may contain incident-specific URLs that shouldn't leave the network)
-- Don't fetch URLs matching common internal-hostname patterns
-- Cap default at 30 fetches/run; tune via `max_fetches_per_run`
-- Cache aggressively — same URL, same week, same result (the 15-minute WebFetch cache is too short for multi-doc audits; recipe layer adds a 7-day cache by default)
-
-## Anti-patterns
-
-- **Fetching URLs without rate limiting.** Respect retry-after headers and the deny list.
-- **Trusting the fetch blindly.** Fetched pages can themselves be stale (caching, mirrors). Pair with frontmatter dates on the citation.
-- **Including fetched content verbatim in the PR.** Cite + summarize; don't dump pages of HTML.
-- **Running on every PR.** Quarterly or weekly is usually right; the audit history ledger surfaces the trend.
-- **Verifying without recording the fetch date.** Without a date, the corrected claim is itself unverifiable a year from now.
-
-## Cross-references
-
-- Stale-content audit pattern (the input): `../audit-patterns/stale-content.md`
-- Recommend-then-validate (consumer pattern): `recommend-then-validate.md`
-- Staleness tooling (lychee, Vale, markdownlint): `../audit-patterns/staleness-tooling.md`
-- Audit history ledger (where verified-fix metadata lands): `../audit-patterns/audit-history-ledger.md`
-- Reliability dial (where the fetch budget gets tuned per strictness): `../guidance/reliability-dial.md`

package/skills/adia-ui-ops/references/recipes/findings-index-readout.md

@@ -1,126 +0,0 @@
----
-date: 2026-04-29
-coverage: canonical
-peers:
-  - ../audit-patterns/audit-history-ledger.md
-  - continuous-learning-loop.md
-  - ../doc-types/postmortem-pattern.md
-status: practice-verified
----
-
-# Findings index — closing the read side of the audit ledger
-
-> **The premise.** The audit ledger (`.brain/audit-history/*.json`) is *write-rich, read-poor*. Audits accumulate findings with severity codes (F-W1, F-S4, etc.) but nothing surfaces them — there's no list view, no "open findings" surface, no way to ask "what's still on the action surface?" without `cat`-ing every JSON file.
->
-> The read-side closure is a single generated Markdown file at `.brain/findings/INDEX.md` that folds every `findings[]` entry across the audit history into one sortable table. Plus a hand-curated `## Graduations` section that tracks finding-to-permanent-infrastructure pairs.
-
-## What this delivers
-
-A repo with a healthy audit-history ledger but no findings index has *capture without action*. Audits keep noting "F-S4 high — render-method drift in stepper.js" — and unless you happen to be reading that specific JSON, you'll never see it again. A future audit re-emits the same finding type from a different commit; the pattern doesn't surface; nothing graduates.
-
-The findings-index closes that loop:
-
-1. **Surface OPEN findings.** Anything `fix_applied: false` rises to the top of the index. The first thing a new agent in the repo can do is grep `OPEN` in `.brain/findings/INDEX.md` and pick from the action surface.
-2. **Track graduations.** When a recurring finding-type prompts permanent infrastructure (a trip-wire, a generator, a convention), that pairing is recorded in the `## Graduations` section. The index becomes the institutional memory of *which findings became rules*.
-3. **Auto-close findings.** When a later audit emits `F-X-resolved`, the original `F-X` auto-promotes from OPEN to CLOSED-LATER. The ledger stays append-only; the index reflects the latest truth.
-4. **Refresh on the harvest cron.** Same cadence as the audit-history workflow. No new infrastructure, no second cron, just one extra script step.
-
-## The minimum viable shape
-
-```
-.brain/
-├── audit-history/        # write side (per audit JSON)
-│   ├── 2026-04-27.json
-│   ├── 2026-04-28.json
-│   └── 2026-04-29-002.json
-└── findings/
-    └── INDEX.md          # read side (regenerated)
-```
-
-`INDEX.md` is a single file. It is **not** an index in the README sense (one row per audit) — it's an aggregate of all `findings[]` entries across all audits, sorted by status × severity × id.
-
-## Status taxonomy
-
-Each finding falls into one of six bins. Sort the table by this order — the action surface always sits at the top.
-
-| Status | Rule | Read |
-|---|---|---|
-| `OPEN` | `fix_applied === false` | Action surface — pick from the top. |
-| `DONE-WITH-FOLLOWUP` | `fix_applied === true && follow_up exists` | Fix landed; the audit flagged a follow-up that hasn't been addressed. |
-| `DONE` | `fix_applied === true && no follow_up` | Fixed in the same session as the audit; no follow-up flagged. |
-| `CLOSED-EARLIER` | `id` ends with `-resolved` | Re-check confirming an earlier OPEN has since been addressed. |
-| `CLOSED-LATER` | original was OPEN/DONE-WITH-FOLLOWUP **and** a `<id>-resolved` exists in a later audit | Auto-promoted; original retains its position in the audit JSON, but the index reflects the latest state. |
-| `INFO-ONLY` | `fix_applied === null` | Positive observations (trip-wires passing, healthy cadence, etc.). Recorded for ledger continuity. |
-
-Within each status, sort by severity: `high > warn > drift-resolved > info > info-positive > nit`. Then by `id` alphabetical.
-
-## The Graduations section
-
-The hand-curated `## Graduations` table is the load-bearing innovation. It records, in plain text, the pairs:
-
-```markdown
-## Graduations
-
-| Finding | Permanent fix |
-|---|---|
-| [F-N1](../audit-history/2026-04-29-003.json) | Pre-commit Check 3 — journal-date sanity (commit `342ba89c`) |
-| [F-W1](../audit-history/2026-04-29-002.json) | `docs/journal/2026/04/INDEX.md` (commit `35146f9d`) |
-| [F-A1](../audit-history/2026-04-29.json) | Daily build-log harvest cron firing |
-```
-
-This is the read-side answer to *"what do we do with findings beyond fixing them once?"* When the same finding-type recurs (today's F-S4 echoes last week's F-S2), the graduation table tells you: "we already know this class is recurring — it's earned a trip-wire."
-
-**Pre-seed the table on first generation; preserve it across regenerations.** The table is the memory; the rest of the index is the rendering.
-
-## The generator script (~280 lines)
-
-The reference implementation is a Node script that:
-
-1. Reads every `.brain/audit-history/*.json`.
-2. Tracks `audit_id` separately from filename (mismatches happen — one repo had `2026-04-29.json` containing `audit_id: "2026-04-29-001"`).
-3. Flattens all `findings[]` entries with their parent audit reference.
-4. Auto-promotes OPEN/DONE-WITH-FOLLOWUP to CLOSED-LATER when a `<id>-resolved` exists in a later audit.
-5. Sorts by status × severity × id.
-6. Preserves the existing `## Graduations` section if it exists; pre-seeds a stub on first run.
-7. Writes `.brain/findings/INDEX.md`.
-
-The script is mechanical (no LLM calls). Cheap enough to run on every cron firing.
-
-**Concrete reference**: [`scripts/build/findings-index.mjs`](https://github.com/adiahealth/gen-ui-kit/blob/main/scripts/build/findings-index.mjs) in the chat-ui repo (~280 lines). It's the canonical implementation that the chat-ui repo wires into its daily build-log workflow.
-
-## Wiring into the harvest cron
-
-Add one step to the daily harvest workflow, after the harvester:
-
-```yaml
-# After the harvester step:
-- name: Refresh findings index
-  run: node scripts/build/findings-index.mjs
-```
-
-Cheap (just JSON reads + a markdown write); always runs so the index reflects whatever `.brain/audit-history/` currently holds, even on runs where the harvester itself skipped (no material delta).
-
-The PR-creator step that already bundles audit-history changes will pick up `.brain/findings/INDEX.md` automatically.
-
-## When a finding "graduates"
-
-Three signals that a finding-type is ready to graduate from "fixed once" to "permanent infrastructure":
-
-1. **Recurrence.** The same finding-type appears in 2+ audits across different commits. Today's F-S4 echoes a prior F-S2; the pattern is real, not a one-off.
-2. **Mechanical verifiability.** The rule the finding implies can be checked by a script (link checker, grep, AST walk) — not "use good judgment."
-3. **Clear failure mode.** The cost of *not* graduating is concrete (a future incident, a daily noise source, a recurring doc-drift class).
-
-Graduations don't require ceremony. When you ship the trip-wire, edit the `## Graduations` table to record the pair: `<finding-id>` → `<permanent fix + commit SHA>`. That's the institutional record.
-
-## Anti-patterns to avoid
-
-1. **Don't make the index `cat`-able from individual audits.** The point is *aggregation*. If the index just lists audits with their findings nested, you've reproduced the read problem.
-2. **Don't auto-curate Graduations.** The pairing of "this finding" → "this trip-wire" requires human judgment. Pre-seed and preserve; never overwrite.
-3. **Don't drop INFO-ONLY findings.** Positive observations (trip-wires passing, healthy cadence) are the *evidence* that the system is working. Hiding them makes the index look like a problem list, when much of the value is the green count.
-4. **Don't replace the audit JSONs.** The index is a *view*. The JSONs remain the source of truth — append-only, immutable, schema-validated.
-
-## Related
-
-- [`audit-patterns/audit-history-ledger.md`](../audit-patterns/audit-history-ledger.md) — the write-side ledger this recipe reads from.
-- [`recipes/continuous-learning-loop.md`](continuous-learning-loop.md) — the broader Promise 5 pattern; this recipe is one specific closure.
-- [`doc-types/postmortem-pattern.md`](../doc-types/postmortem-pattern.md) — postmortems are the *narrative* counterpart; the findings-index is the *structured* counterpart.

package/skills/adia-ui-ops/references/recipes/greenfield-setup.md

@@ -1,252 +0,0 @@
----
-date: 2026-04-27
-coverage: canonical
-peers:
-  - audit-existing-repo.md
-  - adr-introduction.md
-  - memory-organization.md
-  - self-healing-hooks.md
-  - continuous-learning-loop.md
-primary_sources:
-  - https://agents.md
-  - https://github.com/typicode/husky
-  - https://pre-commit.com/
-  - https://adr.github.io/madr/
-  - https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions
-  - https://code.claude.com/docs/en/best-practices
-status: research-verified
----
-
-# Recipe: greenfield setup (delivers all 5 promises from day one)
-
-> **The premise.** A new repo has no legacy debt — no fat CLAUDE.md, no orphan docs, no scattered decisions. This is the *only* moment the repo can ship with all five promises pre-installed. Skip this and you'll be doing `audit-existing-repo.md` in six months.
->
-> **Not a new repo?** If your repo is older than ~3 months and has any documentation at all, use `cold-start-harvest.md` instead. That recipe handles the inventory + triage + supersede pattern this one skips.
->
-> **Existing `docs/` layout?** If you already have `docs/adrs/`, `docs/postmortems/`, etc., the v1.5 `.brain/` layout is opt-in — both are recognized by the audit. The migration is one `git mv` documented in `audit-existing-repo.md` § Migration.
-
-## What this recipe delivers
-
-| Promise | Delivered by |
-|---|---|
-| 1. Less-wasteful | One canonical entry file, thin pointers, no duplicated commands |
-| 2. Token-and-context-optimized | AGENTS.md ≤150 lines from day one; layered docs |
-| 3. Less-prone-to-staleness | `_Last reviewed:_` lines, frontmatter dates, lychee CI |
-| 4. Self-healing | Pre-commit hooks + PR-time CI + scheduled weekly audit |
-| 5. Continuously-learning | ADR `0001` bootstrap, PR template architectural-impact checkbox, Memory primitives section |
-
-## Step 1 — `AGENTS.md` skeleton (Promise 1, 2)
-
-Use the recommended structure from `../standards/agents-md-spec.md`. Drop in the 8-section skeleton, customize what's true for the repo, target **80-120 lines**:
-
-```markdown
-# AGENTS.md
-
-This file gives instructions to LLM coding agents (Codex, Devin, Cursor,
-Windsurf, Copilot, Aider, Continue, Jules, Junie — and Claude Code via
-symlink/pointer) working in this repo.
-
-_Last reviewed: 2026-04-27_
-
-## Project overview          (one paragraph)
-## Build / test / run        (commands)
-## Conventions               (bullet list)
-## Trust boundaries          (DO NOT modify / DO modify)
-## Where to find things      (pointers to .brain/)
-## Memory primitives         (when to read ADRs / postmortems)
-```
-
-Verify with `wc -l AGENTS.md`. The pre-commit hook from Step 5 will fail it past 200.
-
-## Step 2 — `CLAUDE.md` as symlink (Promise 1)
-
-Claude Code does not read AGENTS.md natively as of April 2026 (issue [#31005](https://github.com/anthropics/claude-code/issues/31005)). Symlink is cleanest:
-
-```bash
-ln -s AGENTS.md CLAUDE.md
-git add CLAUDE.md
-```
-
-Windows + WSL teams often hit symlink-in-git issues — fall back to the thin-pointer alternative from `../standards/claude-md-convention.md`. Either is fine; never have both files fat.
-
-## Step 3 — `.brain/` directory tree + `.gitignore` (Promise 2, 5)
-
-```bash
-mkdir -p .brain/{adrs,postmortems,runbooks,archive,architecture}
-touch .brain/{adrs,postmortems,runbooks,archive,architecture}/.gitkeep
-```
-
-Add an index `README.md` in each memory home (~10-20 lines each, `_Last reviewed:_` stamped). See `memory-organization.md` for the rationale on which folders go where and what each index file contains.
-
-Then add transient-state homes to `.gitignore`. `.brain/cache/` is the WebFetch cache populated by external-reference verification. `.brain/cold-start/working/` is the harvest-session scratch space. The persistent state (`adrs/`, `postmortems/`, `runbooks/`, `archive/`, `architecture/`, `audit-history/`, `changesets/`, `config.toml`) gets committed.
-
-```bash
-cat >> .gitignore << 'EOF'
-
-# ops-repo transient state
-.brain/cache/
-.brain/cold-start/working/
-EOF
-```
-
-> **Want `.brain/` entirely local?** Set `mode = "local-only"` in `.brain/config.toml` and gitignore the whole `.brain/` directory (instead of just the cache/cold-start subdirs). See `../guidance/reliability-dial.md` § Git sync. Promise 5 then applies to your local clone only — multi-contributor recipes and the auto-archive PR workflow become moot.
-
-## Step 4 — Bootstrap ADR `0001` (Promise 5)
-
-The first ADR records the decision to use ADRs. Without it, the practice itself isn't decided. Use the Nygard format ([cognitect.com 2011](https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions)); template in `../doc-types/adr-pattern.md`:
-
-```markdown
-# 1. Record architecture decisions
-
-Date: 2026-04-27
-
-## Status
-Accepted
-
-## Context
-We need to record architectural decisions made on this project so future
-contributors (human and LLM agent) can understand why the codebase looks
-the way it does.
-
-## Decision
-We will use Architecture Decision Records as described by Michael Nygard.
-ADRs live in `.brain/adrs/` as `NNNN-kebab-case-title.md` with a `Status:`
-field. The collection is the decision log.
-
-## Consequences
-- Architectural decisions are captured at decision time, not retroactively.
-- New contributors read `.brain/adrs/` newest-first to understand commitments.
-- Decisions become harder to silently override — supersession requires a new ADR.
-```
-
-Save as `.brain/adrs/0001-record-architecture-decisions.md`. Update `.brain/adrs/README.md`.
-
-## Step 5 — Pre-commit hooks + CI (Promise 3, 4)
-
-Install the full stack from `self-healing-hooks.md`:
-
-```bash
-cp ~/.repo-brain-templates/.pre-commit-config.yaml .
-mkdir -p scripts && cp ~/.repo-brain-templates/scripts/*.sh scripts/
-chmod +x scripts/*.sh
-
-pip install pre-commit && pre-commit install
-
-mkdir -p .github/workflows
-cp ~/.repo-brain-templates/.github/workflows/*.yml .github/workflows/
-```
-
-Five files land: `.pre-commit-config.yaml`, `scripts/check-agents-claude-drift.sh`, `scripts/check-doc-dates.sh`, `.github/workflows/repo-brain-pr.yml`, `.github/workflows/repo-brain-weekly.yml`. The verbatim contents are in `self-healing-hooks.md`.
-
-Citations: [pre-commit.com](https://pre-commit.com/), [Husky](https://github.com/typicode/husky) (Node monocultures), [Lychee](https://github.com/lycheeverse/lychee-action).
-
-## Step 6 — PR template (Promise 5)
-
-The architectural-impact checkbox closes the continuous-learning loop. Drop in `.github/pull_request_template.md`:
-
-```markdown
-## What
-[summary]
-
-## Why
-[motivation]
-
-## Architectural impact
-- [ ] No architectural change (no ADR needed)
-- [ ] Architectural change — ADR added at: `.brain/adrs/NNNN-*.md`
-- [ ] Architectural change — ADR exemption granted by: [name]
-      Reason: [why no ADR]
-
-## Docs touched
-- [ ] AGENTS.md updated if conventions / commands changed
-- [ ] ADR added if architectural commitment made
-- [ ] Runbook added if new ops procedure introduced
-```
-
-See `continuous-learning-loop.md` for the auto-detection workflow that warns when architectural files change without an accompanying ADR.
-
-## Step 7 — `_Last reviewed:_` lines (Promise 3)
-
-Every doc gets a date — YAML frontmatter `date:` or inline `_Last reviewed: YYYY-MM-DD_`. The greenfield seed:
-
-```bash
-TODAY=$(date +%F)
-for f in AGENTS.md README.md CONTRIBUTING.md SECURITY.md .brain/**/*.md; do
-    [ -f "$f" ] || continue
-    grep -q "_Last reviewed:" "$f" || \
-        printf "\n_Last reviewed: %s_\n" "$TODAY" >> "$f"
-done
-```
-
-The pre-commit hook from Step 5 enforces this on future edits.
-
-## Step 8 — `.brain/config.toml` (optional: tune the strictness dial)
-
-The hooks installed in Step 5 default to `strictness = "normal"`. To tune up or down, drop a `.brain/config.toml`:
-
-```toml
-[ops-repo]
-strictness = "normal"  # lax | normal | strict
-version = "1.1"
-```
-
-- **`lax`** — side projects, prototypes (warnings, no blocking)
-- **`normal`** — most production repos (default)
-- **`strict`** — regulated codebases, monorepos (every trip-wire blocks; multi-agent review for apply-mode fixes)
-
-See `../guidance/reliability-dial.md` for what each position changes per trip-wire. Skip this step entirely to use `normal` defaults — `.brain/config.toml` is an override, not a requirement.
-
-## Step 9 — Verification checklist
-
-- [ ] `AGENTS.md` exists, ≤150 lines, has all 8 sections
-- [ ] `CLAUDE.md` is a symlink to `AGENTS.md` OR a ≤15-line pointer
-- [ ] `.brain/{adrs,postmortems,runbooks,archive,architecture}/` exist with README index files
-- [ ] `.brain/adrs/0001-record-architecture-decisions.md` is `Accepted`
-- [ ] `.gitignore` excludes `.brain/cache/` and `.brain/cold-start/working/`
-- [ ] `.pre-commit-config.yaml` present; `pre-commit install` ran
-- [ ] `scripts/check-*.sh` present and executable
-- [ ] `.github/workflows/repo-brain-{pr,weekly}.yml` present
-- [ ] `.github/pull_request_template.md` has architectural-impact checkbox
-- [ ] Every `.md` has `_Last reviewed:_` or YAML `date:`
-- [ ] `README.md` references `AGENTS.md` once (no duplicated build commands; see `../standards/readme-conventions.md`)
-- [ ] (Optional) `.brain/config.toml` present if non-default strictness desired
-- [ ] `pre-commit run --all-files` passes
-
-12 boxes ticked → all 5 promises ship from day one.
-
-## First commit message
-
-```
-chore: bootstrap repo-brain-compliant doc surface
-
-- AGENTS.md (canonical), CLAUDE.md → symlink
-- .brain/{adrs,postmortems,runbooks,archive,architecture}/
-- .gitignore for .brain/cache/, .brain/cold-start/working/
-- ADR 0001 — Record architecture decisions
-- pre-commit hooks (drift, length, doc-date)
-- CI (PR-time link-check + weekly audit)
-- PR template with architectural-impact checkbox
-
-Delivers all 5 ops-repo promises from day one.
-```
-
-## Common greenfield mistakes
-
-- **Setting up `CLAUDE.md` as canonical.** Works for Claude Code only; other agents (Codex, Cursor, Devin, Copilot) ignore it. Always make AGENTS.md canonical.
-- **Skipping ADR 0001.** Without the bootstrap, the next contributor wonders if ADRs are required.
-- **Pre-commit installed but not run.** `pre-commit install` writes `.git/hooks/pre-commit`; clones don't pick it up. Document the install in `CONTRIBUTING.md`.
-- **Lychee with `fail: false` on PR.** Defeats the gate. `fail: true` on PR; `fail: false` only in scheduled audits.
-- **Stamping `_Last reviewed:_` programmatically and never touching it again.** The date should be re-stamped on real edits, not just the seed.
-- **Committing `.brain/cache/` or `.brain/cold-start/working/`.** Transient state belongs in `.gitignore`.
-
-## Cross-references
-
-- AGENTS.md spec (the skeleton's source): `../standards/agents-md-spec.md`
-- CLAUDE.md convention: `../standards/claude-md-convention.md`
-- README/CONTRIBUTING/SECURITY conventions: `../standards/readme-conventions.md`
-- ADR pattern: `../doc-types/adr-pattern.md`
-- Self-healing hooks (Step 5 detail): `self-healing-hooks.md`
-- Continuous-learning loop (Step 6 detail): `continuous-learning-loop.md`
-- Memory organization (folder layout rationale): `memory-organization.md`
-- Token-budget rationale for length caps: `../guidance/context-budget.md`
-- Migration recipe for existing `docs/` layouts: `audit-existing-repo.md` § Migration