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

package/skills/adia-ui-ops/references/guidance/reliability-dial.md

@@ -0,0 +1,186 @@
+---
+date: 2026-04-27
+coverage: canonical
+peers:
+  - llm-doc-writing.md
+  - context-budget.md
+  - ../recipes/self-healing-hooks.md
+  - ../recipes/recommend-then-validate.md
+primary_sources:
+  - Steve Yegge, "Welcome to Gas City" — https://steve-yegge.medium.com/welcome-to-gas-city-57f564bb3607
+  - https://code.claude.com/docs/en/best-practices
+status: research-verified
+---
+
+# Reliability dial (configurable strictness)
+
+> _"Reliability, friends, is a dial. You choose where to set it. More rounds of review, more backstops, more guardrails… you can get agentic workers to be as reliable as you need."_
+> — Steve Yegge, "Welcome to Gas City"
+
+## What this delivers
+
+Yegge's load-bearing insight: trying to set one absolute level of strictness for every repo is wrong. A solo side project and a regulated production codebase need different friction. `ops-repo` exposes a single explicit knob — **strictness** — and routes every trip-wire's threshold through it.
+
+Three positions:
+
+| Position | Posture | When to use |
+|---|---|---|
+| **`lax`** | Discoverable but never blocks | Side projects, prototypes, exploration phases |
+| **`normal`** | Default. Pre-commit warns/fails on critical | Most production repos |
+| **`strict`** | Every promise's trip-wire must pass; multi-agent review required for any apply-mode fix | Regulated codebases, monorepos with many contributors, repos where doc breakage is costly |
+
+Explicit knob beats implicit severity rubric: the team picks its dial position once, in `.brain/config.toml`, and every check derives from there.
+
+## The config file
+
+`.brain/config.toml` at repo root:
+
+```toml
+[ops-repo]
+strictness = "normal"  # lax | normal | strict
+version = "1.1"
+
+# Optional per-trip-wire overrides
+[ops-repo.overrides]
+entry_file_max_lines = 200       # default for "normal"; "strict" = 150
+orphan_grace_days = 30           # default for "normal"; "strict" = 7
+doc_age_threshold_days = 365     # default for "normal"; "strict" = 180
+```
+
+For Node projects, equivalent block in `package.json`:
+
+```json
+{
+  "ops-repo": { "strictness": "normal" }
+}
+```
+
+For Python projects, `pyproject.toml`:
+
+```toml
+[tool.ops-repo]
+strictness = "normal"
+```
+
+## What each position does
+
+| Trip-wire | `lax` | `normal` | `strict` |
+|---|---|---|---|
+| **Entry-file length** | Warn >250 lines | Warn >150, fail pre-commit >200 | Fail pre-commit >150 |
+| **AGENTS.md/CLAUDE.md drift** | Warn | Fail pre-commit | Require symlink (`ln -s AGENTS.md CLAUDE.md`) |
+| **Broken intra-repo links** | Report only | Fail PR | Fail pre-commit |
+| **Broken external links** (lychee) | Report weekly | Fail PR | Fail PR + fail pre-commit |
+| **Doc frontmatter dates** | Suggest | Require on new docs | Require on all docs; review every 365d |
+| **Orphan grace period** | 90 days | 30 days | 7 days |
+| **AGENTS.md "Memory primitives" section** | Recommend | Require | Require + fail audit if missing |
+| **`.brain/adrs/` for repos > 1 year old** | Recommend | Recommend (medium severity) | Required (high severity) |
+| **Apply-mode fixes** | Single agent | Single agent | Recommend agent + validate agent (see `../recipes/recommend-then-validate.md`) |
+| **Auto-archive PR** | Manual review | Manual review | Multi-agent review |
+
+## Choosing your position
+
+The dial is **not a quality scale**. `lax` isn't bad and `strict` isn't good. They're matched to *cost of failure*.
+
+```
+                cost of doc breakage to your team
+   low ←───────────────────────────────────────→ high
+
+   lax        normal                           strict
+   │           │                                 │
+solo prototype  most production repos      monorepo, regulated,
+                                           high-stakes shared codebase
+```
+
+If `strict` causes more friction than it prevents, you're at the wrong position. Try `normal` first.
+
+## Git sync (where the brain lives)
+
+By default, `.brain/` is committed to git — the brain *is* shared across the team. But not every team wants this. Solo developers, research notebooks, individual scratch repos, or teams that sync memory through a non-git mechanism (internal wiki, S3, Notion) may prefer to keep `.brain/` local.
+
+Two modes:
+
+| Mode | What gets committed | Promise 5 (continuously-learning) | When to use |
+|---|---|---|---|
+| **`shared`** (default) | `.brain/{adrs,postmortems,runbooks,archive,architecture,audit-history,changesets,config.toml}` (`cache/` + `cold-start/working/` always gitignored) | Applies to the team — artifacts compound across contributors | Most repos with >1 contributor |
+| **`local-only`** | Nothing in `.brain/` is committed; entire `.brain/` is gitignored | Applies to **your local clone only** — your individual brain compounds; the team's doesn't | Solo, prototypes, or repos where memory syncs via a non-git system |
+
+Configure in `.brain/config.toml`:
+
+```toml
+[ops-repo.git-sync]
+mode = "shared"   # shared | local-only
+```
+
+Default is `shared` — when omitted, behavior is identical to v1.5.0.
+
+### What `local-only` changes
+
+When `mode = "local-only"`:
+
+- `.gitignore` should include `.brain/` at the top (greenfield adds this automatically when configured).
+- Every contributor maintains their own `.brain/`. Your ADRs are not your teammate's ADRs.
+- The **auto-archive PR workflow is disabled** (no PRs because nothing is tracked).
+- The audit-history-ledger remains useful as a *local* diagnostic but is not a SOC2-grade shared trail.
+- The `concurrent-learnings-merge.md` recipe is irrelevant (no shared brain to merge into).
+- The `cold-start-harvest.md` recipe is irrelevant (no shared brain to import into).
+- Promise 5 still applies — but to *you*, not the team.
+
+Switching `local-only` → `shared` later: remove `.brain/` from `.gitignore`, set `mode = "shared"`, then `git add .brain/` to stage what you've accumulated. The reverse direction (`shared` → `local-only`) requires deciding what to do with already-committed artifacts (typically: leave them committed for history; new artifacts go local).
+
+### Granular per-subdir sync (advanced)
+
+Some teams want finer control — e.g., share ADRs but keep `audit-history/` local-only (less PR noise; the SOC2 trail kept on a separate machine):
+
+```toml
+[ops-repo.git-sync]
+mode = "shared"
+
+[ops-repo.git-sync.committed]
+adrs = true
+postmortems = true
+runbooks = true
+archive = true
+architecture = true
+changesets = true
+config = true            # config.toml itself
+audit-history = false    # opt out of committing audit-history; stays local
+```
+
+Defaults match the `shared` mode table above. The audit warns if a subdir is gitignored when the chosen mode says it should be committed (or vice versa).
+
+### Why this is separate from strictness
+
+Strictness controls *how loud* the audit/hooks are. Git-sync controls *where the brain lives*. The two are orthogonal:
+
+- A **`local-only` + `strict`** brain is fine — you take your own notes very seriously.
+- A **`shared` + `lax`** brain is fine — the team gathers but doesn't enforce.
+- A **`shared` + `strict`** brain is the regulated-codebase posture (the original v1.1 default).
+- A **`local-only` + `lax`** brain is the personal-scratch posture.
+
+## How the audit honors the dial
+
+When the audit runs, it loads `.brain/config.toml` and threshold-routes every check. Findings include the dial position they were evaluated against:
+
+```markdown
+- **DRIFT — CLAUDE.md vs AGENTS.md** (severity: critical, evaluated at strictness=strict)
+  - At `lax`: would have been a warning.
+  - At `normal`: would have failed pre-commit.
+  - At `strict`: requires symlink. Recommended fix: `ln -s AGENTS.md CLAUDE.md`.
+```
+
+This makes the dial *visible*, not just operative — when a finding fires, the team can see whether re-tuning the dial is the right answer or fixing the issue is.
+
+## Anti-patterns
+
+- **Setting `strict` and ignoring half the trip-wires.** Inconsistent. Either commit to the position or move to `normal`.
+- **Setting `lax` permanently as a way to silence findings.** That defeats the purpose. Lax is for prototypes; if a real repo lives at `lax` for a year, escalate.
+- **Per-file overrides everywhere.** Override sparingly. The defaults exist because they're empirically reasonable; per-file exceptions become drift over time.
+- **Changing the dial mid-PR to make a check pass.** The dial belongs to the team and the repo, not to a single change.
+
+## Cross-references
+
+- The trip-wires themselves: `../recipes/self-healing-hooks.md`
+- Recommend-then-validate (the multi-agent pattern `strict` requires): `../recipes/recommend-then-validate.md`
+- Token-budget defaults (entry-file lengths): `context-budget.md`
+- LLM-doc-writing (content quality): `llm-doc-writing.md`
+- Audit history (where the dial position is recorded per run): `../audit-patterns/audit-history-ledger.md`

package/skills/adia-ui-ops/references/recipes/adr-introduction.md

@@ -0,0 +1,211 @@
+---
+date: 2026-04-27
+coverage: canonical
+peers:
+  - greenfield-setup.md
+  - memory-organization.md
+  - audit-existing-repo.md
+  - continuous-learning-loop.md
+  - ../doc-types/adr-pattern.md
+primary_sources:
+  - https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions
+  - https://adr.github.io/madr/
+  - https://github.com/joelparkerhenderson/architecture-decision-record
+  - https://github.com/npryce/adr-tools
+status: research-verified
+---
+
+# Recipe: introduce ADRs to an established repo (delivers Promise 5)
+
+> **The premise.** A repo without ADRs has scattered architectural memory — decisions live in PR descriptions, Slack archives, code comments, and senior engineers' heads. The "continuously-learning" promise is broken until the repo has a place to land decisions *at decision time*. This recipe creates that place and seeds it just enough that the practice survives.
+
+## What this recipe is *not*
+
+- **Not** a backfill-everything-ever campaign. Reconstructing 10 years of decisions almost never finishes.
+- **Not** a bureaucratic gate. Most PRs aren't architectural; most don't need ADRs.
+- **Not** a tooling adoption. `adr-tools` (Pryce) is optional and lightly maintained as of April 2026. `mkdir .brain/adrs/` is enough to start.
+
+## What this recipe *is*
+
+A 60-minute setup that (1) creates `.brain/adrs/` with an index and the bootstrap ADR; (2) backfills 3-5 *load-bearing* historical decisions; (3) wires the AGENTS.md `Memory primitives` section; (4) adds the architectural-impact checkbox to the PR template; (5) briefs the team in one paragraph.
+
+## Step 1 — Create the ADR home + index
+
+```bash
+mkdir -p docs/adrs
+
+cat > .brain/adrs/README.md <<'EOF'
+# Architecture Decision Records
+
+This folder captures architectural decisions. Each ADR is dated, numbered,
+and immutable — decisions don't get edited; they get superseded.
+
+Format: MADR 4.0.0 (https://adr.github.io/madr/) for new ADRs.
+Read newest-first. See `../../AGENTS.md` "Memory primitives" for when
+to consult.
+
+## Index
+
+| # | Title | Status | Date |
+|---|---|---|---|
+| 0001 | Record architecture decisions | Accepted | 2026-04-27 |
+
+_Last reviewed: 2026-04-27_
+EOF
+```
+
+## Step 2 — Bootstrap ADR 0001
+
+Use the Nygard format ([cognitect.com 2011](https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions)) for the bootstrap; canonical templates in `../doc-types/adr-pattern.md`. The bootstrap ADR records the decision to *use ADRs* — without it, future contributors don't know whether the practice is required.
+
+Save as `.brain/adrs/0001-record-architecture-decisions.md` (full content in `greenfield-setup.md`). Update the README index.
+
+## Step 3 — Backfill 3-5 load-bearing historical ADRs
+
+This is where teams either succeed or burn out. **Do not try to backfill every past decision.** Pick the 3-5 commitments that (a) are still live, (b) get questioned by new contributors, (c) would change the agent's behavior if it knew them.
+
+### How to find them — git archaeology in 20 minutes
+
+```bash
+# 1. Framework / library / runtime introductions
+git log --diff-filter=A --name-only --pretty=format:'%h %ad %s' --date=short \
+    -- 'package.json' 'Gemfile' 'requirements.txt' 'go.mod' 'Cargo.toml' \
+       'pyproject.toml' '*.csproj' 'pom.xml' 'mix.exs' | head -50
+
+# 2. DB-related decisions
+git log --all --oneline --grep -E -i 'postgres|mysql|mongo|redis|sqlite|dynamo' | head -30
+
+# 3. Deployment platform decisions
+git log --all --oneline --grep -E -i 'deploy|kubernetes|cloud-run|fly|render|vercel|heroku' | head -30
+
+# 4. Auth / security decisions
+git log --all --oneline --grep -E -i 'auth|jwt|session|oauth|saml' | head -20
+```
+
+Triangulate with the team: "What three things do people ask about most often?"
+
+### Typical high-value backfill candidates
+
+| ADR # | Decision shape | Why it earns its place |
+|---|---|---|
+| 0002 | Framework choice (e.g., Next.js over Remix) | Agent reaches for wrong framework conventions otherwise |
+| 0003 | Database choice (e.g., Postgres over MySQL) | Affects schema design, query patterns |
+| 0004 | Deployment platform (e.g., Cloud Run, not k8s) | Affects observability, CI, ops |
+| 0005 | Auth provider (e.g., Auth0 over rolling our own) | Affects security model, user model |
+| 0006 | Module boundaries (e.g., monorepo, not split repos) | Affects refactor blast radius |
+
+### Backfill ADR template
+
+Backfill ADRs **explicitly mark themselves as backfilled**. The team didn't go through the ADR process at the time — that's fine, just be honest.
+
+```markdown
+# 2. Use Postgres over MySQL
+
+Date: 2026-04-27 (decision made: 2024-03-12; backfilled retroactively)
+
+## Status
+Accepted
+
+## Context
+[Reconstructed from git log + PR #142 + memory of who was around. Some
+of the original constraint analysis is unrecoverable; this ADR captures
+the load-bearing context.]
+
+In Q1 2024, we needed a relational database for the user-account service.
+Drivers: JSONB for flexible user-profile fields, mature partitioning for
+the multi-tenant rollout, team familiarity (3 of 5 had Postgres experience).
+
+## Decision
+Postgres 15. Hosted on RDS in us-east-1.
+
+## Consequences
+- Locked into Postgres dialect (we use JSONB ops + LATERAL joins).
+- Migrating later requires schema rewrite + data backfill.
+- Connection pool management is a known op concern (see
+  `.brain/postmortems/2026-04-12-checkout-outage.md`).
+```
+
+The "(decision made: ... ; backfilled retroactively)" tag is critical — tells the next reader the ADR isn't reconstructing perfect history, just the load-bearing summary.
+
+**Stop at 3-5.** A 6th tempting backfill is usually scope creep. Add to the backlog and let it appear when someone next touches the relevant area.
+
+## Step 4 — Wire AGENTS.md Memory primitives
+
+If AGENTS.md doesn't have a `Memory primitives` section, add one. If it does, add the ADR pointer:
+
+```markdown
+## Where to find things
+(...)
+- **Architecture Decision Records:** `.brain/adrs/` (index: `.brain/adrs/README.md`)
+
+## Memory primitives
+- **Before architectural decisions**, read `.brain/adrs/` newest-first.
+  If your proposed change conflicts with an `Accepted` ADR, write a new
+  ADR superseding it; don't silently override.
+```
+
+Without this section, the ADRs exist but the agent doesn't know to read them — single most-common loop break (see `continuous-learning-loop.md`).
+
+## Step 5 — Update the PR template
+
+Add the architectural-impact checkbox to `.github/pull_request_template.md`:
+
+```markdown
+## 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]
+```
+
+Optionally add the auto-detection CI workflow from `continuous-learning-loop.md` that warns when architectural files change without an accompanying ADR.
+
+## Step 6 — Brief the team
+
+One paragraph. Post in #engineering:
+
+> We've added `.brain/adrs/` for architectural decisions. New decisions
+> that change framework / DB / deployment / auth / module boundaries
+> get an ADR alongside the PR. The PR template has a checkbox to remind.
+> We've backfilled 5 historical ones (Postgres, Cloud Run, Next.js,
+> Auth0, monorepo). Format is MADR 4.0.0 — see `.brain/adrs/README.md`.
+> AGENTS.md now points to this folder so LLM agents read it before
+> architectural changes.
+
+Don't send a 500-word memo — short, factual, links.
+
+## Verification checklist
+
+- [ ] `.brain/adrs/` exists with `README.md` index
+- [ ] `0001-record-architecture-decisions.md` is `Accepted`
+- [ ] 3-5 backfill ADRs landed, each marked retroactive in the date line
+- [ ] AGENTS.md `Where to find things` references `.brain/adrs/`
+- [ ] AGENTS.md `Memory primitives` instructs newest-first reading
+- [ ] `.github/pull_request_template.md` has architectural-impact checkbox
+- [ ] Team brief sent
+
+## When to choose Nygard vs MADR vs Y-statements
+
+| Format | When to use |
+|---|---|
+| **Nygard** (Title / Date / Status / Context / Decision / Consequences) | Small teams, fast cadence, straightforward decisions |
+| **MADR 4.0.0** (adds Deciders / Considered Options / Decision Drivers) | Larger teams, audit-trail matters, multi-option |
+| **Y-statements** (Zimmermann SATURN 2012) | One-line reversible choices; or summary atop a longer ADR |
+
+The audit treats all three as valid; `../doc-types/adr-pattern.md` covers detection.
+
+## Common mistakes
+
+- **Backfilling everything.** Past 5 ADRs you're doing archaeology, not setup.
+- **No bootstrap ADR.** Without `0001`, future contributors don't know whether ADRs are mandatory.
+- **Backfill ADRs that pretend they were written contemporaneously.** Reads as historical revisionism.
+- **Adding ADRs but not the AGENTS.md pointer.** Corpus exists; agent doesn't read it.
+- **PR template without the checkbox.** New decisions don't get captured.
+
+## Cross-references
+
+- ADR pattern (templates, anti-patterns, audit checks): `../doc-types/adr-pattern.md`
+- Memory organization (where ADRs sit relative to runbooks/postmortems): `memory-organization.md`
+- Greenfield setup (the day-one version): `greenfield-setup.md`
+- Continuous-learning loop (the system this plugs into): `continuous-learning-loop.md`
+- AGENTS.md Memory primitives section: `../standards/agents-md-spec.md`

package/skills/adia-ui-ops/references/recipes/audit-existing-repo.md

@@ -0,0 +1,234 @@
+---
+date: 2026-04-27
+coverage: canonical
+peers:
+  - greenfield-setup.md
+  - adr-introduction.md
+  - memory-organization.md
+primary_sources:
+  - SKILL.md (this skill's own audit categories)
+status: needs-research-enhancement
+---
+
+# Recipe: audit an existing repo
+
+> **The end-to-end procedure** for running `ops-repo` against a real repo and producing an actionable gap report. Includes the v1.5 `.brain/` layout migration recipe.
+
+## Inputs
+
+- A path to a git repo (working tree)
+- Optional: severity threshold (`critical` / `high` / `medium` / `low`) — default `medium`
+- Optional: write-mode flag (`recommend-only` / `apply-fixes`) — default `recommend-only`
+
+## Outputs
+
+- `stale-docs-audit.md` (or stdout) with the gap report
+- (If `apply-fixes`) edits to `AGENTS.md`, `CLAUDE.md`, etc., or new files in `.brain/`
+
+## The 7-step procedure
+
+### Step 1 — Discovery
+
+Enumerate everything that matters:
+
+```bash
+# Entry-file candidates at root
+ls -la AGENTS.md CLAUDE.md README.md CONTRIBUTING.md SECURITY.md \
+       .cursorrules .windsurfrules .aider.conf.yml 2>/dev/null
+
+# Cursor newer-style rules folder
+ls -la .cursor/rules/ 2>/dev/null
+
+# Continue config
+ls -la .continue/ 2>/dev/null
+
+# GitHub Copilot instructions
+ls -la .github/copilot-instructions.md 2>/dev/null
+
+# Brain artifacts (v1.5 layout) + legacy docs/ tree
+find .brain docs -type f -name '*.md' 2>/dev/null
+find . -maxdepth 2 \( -name 'CHANGELOG*.md' -o -name 'ARCHITECTURE.md' -o -name 'PLAN.md' -o -name 'ROADMAP.md' \) 2>/dev/null
+```
+
+Build two sets:
+- **EntryFiles**: files found at the root that are entry candidates
+- **DocFiles**: files found anywhere under `.brain/` or `docs/`, plus well-known top-level docs (CHANGELOG.md, ARCHITECTURE.md, PLAN.md, ROADMAP.md)
+
+**Git-sync mode detection.** Check `.gitignore`. If `.brain/` (the directory itself, not just `.brain/cache/` or `.brain/cold-start/`) appears in `.gitignore`, the repo is in `local-only` mode (per `../guidance/reliability-dial.md` § Git sync). The audit still runs against the working tree, but Promise 5 findings apply to the local clone only — multi-contributor recipes (`concurrent-learnings-merge.md`, `cold-start-harvest.md`) and the auto-archive PR workflow are moot in this mode and should be skipped.
+
+### Step 2 — Pointer trace
+
+For each file in `EntryFiles`, parse it as Markdown and extract every relative-path link or backtick-quoted path. Build a set:
+
+- **PointedTo**: union of all paths referenced from any entry file
+
+Cross-check against `DocFiles`:
+
+- **PointedTo ∩ DocFiles** — files reachable from entry. ✅
+- **PointedTo \ DocFiles** — referenced but missing. ❌ *Broken pointer.*
+- **DocFiles \ PointedTo** — exist but unreachable. 🟡 *Orphan.*
+
+### Step 3 — Canonical determination
+
+Decide which entry file is *canonical* (the one that should hold instructions; others should redirect to it).
+
+Decision tree:
+
+```
+Is AGENTS.md present and ≥30 lines?
+  YES → AGENTS.md is canonical.
+  NO  → Is exactly one fat (≥30 lines) entry file present?
+          YES → Recommend renaming it to AGENTS.md.
+          NO  → Are multiple fat files present?
+                  YES → DRIFT. Recommend consolidation.
+                  NO  → No canonical file. CRITICAL gap.
+```
+
+### Step 4 — Thin-pointer compliance
+
+For every entry file that is NOT canonical, verify it's a thin pointer:
+
+- Length ≤ 15 lines
+- References the canonical file by name
+- No substantive instructions of its own
+
+Findings:
+- **Fat non-canonical** → drift risk → recommend converting to pointer.
+- **Wrong target** → e.g. CLAUDE.md exists, points at `AGENTS.md`, but AGENTS.md doesn't exist → broken redirect.
+
+### Step 5 — Memory-primitive check
+
+For each of the standard memory homes, check existence and pointer-from-AGENTS.md:
+
+| Home | Required? | If missing |
+|---|---|---|
+| `.brain/adrs/` (or legacy `docs/adrs/`) | Recommended | "No ADR home — recommend introducing them. See `recipes/adr-introduction.md`." |
+| `.brain/decisions/` | Optional | If absent and no ADRs either, both flagged. |
+| `.brain/postmortems/` (or legacy `docs/postmortems/` / `docs/incidents/`) | Optional | Flag only if repo has had production incidents (heuristic: search for `incident`, `outage`, `post-mortem` in commit log). |
+| `CHANGELOG.md` | Strongly recommended | Flag as gap if missing. |
+| `.brain/runbooks/` (or legacy `docs/runbooks/`) | Optional | Flag if production-facing repo. |
+
+### Step 6 — Staleness probe
+
+For each file in `DocFiles`:
+
+- **Last modified** > 6 months ago AND **no `_Last reviewed:_` line** → flag as needs-review.
+- File contains references to symbols/files that no longer exist in the repo → flag as broken-reference.
+- File contains commands that fail dry-run (e.g., `npm install` but project is pnpm) → flag as command-stale. (Best-effort; may require running commands.)
+
+### Step 7 — Synthesize the gap report
+
+Write `stale-docs-audit.md` with sections:
+
+```markdown
+# Stale-docs audit — <repo name>
+
+_Generated: 2026-04-27_
+
+## Summary
+
+- **Critical**: 1 finding
+- **High**: 3 findings
+- **Medium**: 7 findings
+- **Low**: 4 findings
+
+## Critical
+
+### MISSING — AGENTS.md
+[detail per the entry-file-coverage.md output shape]
+
+## High
+
+### DRIFT — CLAUDE.md vs .cursorrules
+[detail]
+
+### NO ADR HOME
+The repo has architectural decisions scattered across PR descriptions and code
+comments but no `.brain/adrs/`. Recommend introducing ADRs.
+
+[continue per severity]
+
+## Recommended fixes (ordered)
+
+1. Rename `CLAUDE.md` → `AGENTS.md`; create thin `CLAUDE.md` redirect.
+2. Create `.brain/adrs/` with `0001-record-architecture-decisions.md`.
+3. Add "Where to find things" and "Memory primitives" sections to AGENTS.md.
+4. Update `.cursorrules` to be a thin pointer.
+5. Resolve drift between CLAUDE.md and .cursorrules: pnpm vs npm.
+
+## Suggested edits (when in apply-fixes mode)
+
+[concrete diffs — not applied without explicit user confirmation]
+```
+
+## Migration: legacy `docs/` layout → `.brain/`
+
+If the audit finds memory artifacts in `docs/{adrs,postmortems,runbooks,archive,architecture}/` (the pre-v1.5 layout), the recommended migration is one git move that preserves history:
+
+```bash
+mkdir -p .brain
+
+# Move each memory primitive that exists. Skip silently if absent.
+[ -d docs/adrs ]         && git mv docs/adrs         .brain/adrs
+[ -d docs/postmortems ]  && git mv docs/postmortems  .brain/postmortems
+# Or if the repo used the docs/incidents alias:
+[ -d docs/incidents ] && [ ! -d .brain/postmortems ] && git mv docs/incidents .brain/postmortems
+[ -d docs/runbooks ]     && git mv docs/runbooks     .brain/runbooks
+[ -d docs/archive ]      && git mv docs/archive      .brain/archive
+[ -d docs/architecture ] && git mv docs/architecture .brain/architecture
+[ -d docs/ops-repo/audit-history ] && git mv docs/ops-repo/audit-history .brain/audit-history
+
+# Config + transient state homes
+[ -f .ops-repo.toml ] && git mv .ops-repo.toml .brain/config.toml
+[ -d .ops-repo/changesets ] && git mv .ops-repo/changesets .brain/changesets
+
+git commit -m "chore: migrate memory layer to .brain/ (ops-repo v1.5)"
+```
+
+After the move, also update:
+
+- **`AGENTS.md`** — every "Where to find things" pointer (`docs/adrs/` → `.brain/adrs/`, etc.)
+- **`.gitignore`** — add `.brain/cache/` and `.brain/cold-start/working/` (transient state)
+- **`.github/workflows/`** — rename `repo-fixer-*.yml` → `repo-brain-*.yml` if hooks were installed pre-v1.3
+- **Workflow path filters / lychee globs** — add `'.brain/**/*.md'` next to `'docs/**/*.md'` (verbatim recipes in `self-healing-hooks.md`)
+
+The audit recognizes either layout — **migration is opt-in for v1.5**, not enforced. Repos that prefer the established `docs/{adrs,...}/` convention can stay there; the audit's checks adapt. Greenfield setup defaults to `.brain/`.
+
+**What stays at the repo root regardless of layout:**
+
+- `AGENTS.md`, `CLAUDE.md`
+- `README.md`, `CONTRIBUTING.md`, `SECURITY.md`, `CODE_OF_CONDUCT.md`
+- `ARCHITECTURE.md` (matklad pattern)
+- `CHANGELOG.md`
+- `PLAN.md`, `ROADMAP.md` (if used)
+
+## Apply-fixes mode safety rules
+
+When `apply-fixes` is on:
+
+1. **Never delete a file** without showing the user and asking.
+2. **Never overwrite a file >50 lines** without showing a diff and asking.
+3. **Always commit each fix as a separate commit** with a clear message — this is reversible.
+4. **Never rewrite git history.**
+5. If asked to delete an orphaned doc, prefer **moving to `.brain/archive/`** with a date suffix over outright deletion.
+
+## Common findings on real repos
+
+From running this audit across real-world projects, the most frequent gaps:
+
+1. **No AGENTS.md, fat CLAUDE.md** — repo predates the standard or only used Claude Code.
+2. **No "Where to find things" section** — naked entry; agent has nothing to navigate.
+3. **CLAUDE.md and .cursorrules drifted** — duplicate maintenance burden, rarely consistent.
+4. **No ADR home** — decisions scattered across PRs.
+5. **Stale build commands** — entry file says `npm` but repo migrated to pnpm/bun.
+6. **Orphaned `docs/old-plan.md`** — never cleaned up after being superseded.
+7. **Undated `ARCHITECTURE.md`** — no way to know if it's current.
+8. **Pre-v1.5 `docs/` layout** — opportunity to migrate to `.brain/` (see § Migration above).
+
+## Cross-references
+
+- Entry-file checks: `../audit-patterns/entry-file-coverage.md`
+- Pointer validation: `../audit-patterns/pointer-validation.md`
+- Orphan detection: `../audit-patterns/orphan-detection.md`
+- Greenfield setup: `greenfield-setup.md`
+- Adding ADRs to existing repo: `adr-introduction.md`