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

package/skills/adia-ui-ops/references/audit-patterns/format-hygiene.md

@@ -1,217 +0,0 @@
----
-date: 2026-04-27
-coverage: canonical
-peers:
-  - coverage-gaps.md
-  - staleness-tooling.md
-  - entry-file-coverage.md
-  - pointer-validation.md
-  - orphan-detection.md
-  - stale-content.md
-  - memory-fragmentation.md
-  - ../doc-types/adr-pattern.md
-  - ../doc-types/postmortem-pattern.md
-  - ../recipes/self-healing-hooks.md
-  - ../guidance/context-budget.md
-primary_sources:
-  - https://adr.github.io/ — ADR `Status:` field convention
-  - https://github.com/joelparkerhenderson/architecture-decision-record
-  - https://sre.google/sre-book/postmortem-culture/ — Postmortem severity + duration metadata
-  - https://djw.fyi/portfolio/preventing-drift/ — Daryl White, "Avoiding the Silent Stale Doc Problem"
-  - https://keepachangelog.com/ — Keep a Changelog format
-status: research-verified
----
-
-# Format hygiene (delivers Promise 3, "less-prone-to-staleness")
-
-> **The premise.** Staleness is invisible without dates. Ownership is invisible without owners. A doc that doesn't *say* when it was last reviewed cannot be flagged as stale by any automated audit — it's not that the audit is wrong, it's that the doc has refused to answer the question. Format hygiene is the precondition for every staleness check downstream.
-
-## Form vs. content
-
-This is a **form check**, not a **content check**:
-
-| Form check (this file) | Content check (elsewhere) |
-|---|---|
-| Does the file have a `date:` field? | Is the date recent? → `stale-content.md` |
-| Does the ADR have a `Status:` field? | Is the status accurate? → manual review |
-| Does AGENTS.md have a `_Last reviewed:_` line? | Is AGENTS.md telling the truth? → `redundancy-detection.md` |
-
-Form is mechanizable; content mostly is not. **Enforce form first** — without it, the staleness tooling in `staleness-tooling.md` runs blind.
-
-## Why this is Promise 3's home
-
-Promise 3 depends on *visibility* of staleness:
-
-```
-date frontmatter → mtime threshold → audit flags stale → human reviews → re-dates or archives
-```
-
-Break the first link (no date), break the chain. `git log -1 --format=%cs` is a noisy fallback — a typo fix on a 3-year-old doc looks "fresh." The `_Last reviewed:_` line is the explicit affirmation that someone *reread* the doc.
-
-## The five hygiene checks
-
-| # | Check | Where it applies | Severity |
-|---|---|---|---|
-| 1 | Doc has `date:` YAML frontmatter OR `_Last reviewed:_` line | All canonical docs | High |
-| 2 | Doc has YAML frontmatter at all | Canonical reference docs (skills-style) | Medium |
-| 3 | AGENTS.md has `_Last reviewed:_` or version line | AGENTS.md, CLAUDE.md (if fat) | High |
-| 4 | ADR has `Status:` field | `.brain/adrs/*.md` | High |
-| 5 | Postmortem has `severity:` and `duration:` | `.brain/postmortems/*.md` | High |
-
-Ownership (`_Owner:_` or `owner:`) is a sixth concern — emit as Medium where missing; small repos can accept "team that owns the parent directory."
-
-## Check 1 — every canonical doc is dated
-
-Two acceptable forms; either passes. **Form A — YAML frontmatter** (`date: 2026-04-27`). **Form B — inline reviewed-line** (`_Last reviewed: 2026-04-27 by @kimba_`).
-
-### Detection
-
-```bash
-# A doc is "dated" if it has either form. Otherwise emit finding.
-check_dated() {
-  local f="$1"
-  # Form A: YAML date: field within first frontmatter block
-  if head -20 "$f" | awk '/^---$/{i++; if(i==2) exit} i==1' | grep -qE '^date:\s*[0-9]{4}-[0-9]{2}-[0-9]{2}'; then
-    return 0
-  fi
-  # Form B: _Last reviewed:_ line anywhere in the file
-  if grep -qE '_Last reviewed:_?\s*[0-9]{4}-[0-9]{2}-[0-9]{2}' "$f"; then
-    return 0
-  fi
-  return 1
-}
-
-for f in AGENTS.md CLAUDE.md README.md CHANGELOG.md \
-         $(find .brain docs -name '*.md' -not -path '.brain/archive/*' -not -path 'docs/archive/*' 2>/dev/null); do
-  [ -f "$f" ] && [ ! -L "$f" ] || continue
-  if ! check_dated "$f"; then
-    echo "UNDATED: $f"
-  fi
-done
-```
-
-CHANGELOG.md is special — it's append-only and dates live per-entry. The check passes if *any* entry has a date heading like `## [1.2.3] - 2026-04-27`.
-
-## Check 2 — canonical reference docs have YAML frontmatter
-
-For reference material in `.brain/` (not narrative READMEs in `docs/`), missing frontmatter is a smell. The ops-repo convention mirrors this skills library: `date`, `coverage`, `peers`, `primary_sources`, `status`.
-
-### Detection
-
-```bash
-# A doc has frontmatter if line 1 is exactly `---`.
-for f in $(find .brain docs -name '*.md' -not -path '.brain/archive/*' -not -path 'docs/archive/*' 2>/dev/null); do
-  [ -f "$f" ] || continue
-  if [ "$(head -1 "$f")" != "---" ]; then
-    echo "NO-FRONTMATTER: $f"
-  fi
-done
-```
-
-Medium severity — narrative docs legitimately don't need frontmatter. Reference docs and ADRs/postmortems definitely should.
-
-## Check 3 — AGENTS.md has `_Last reviewed:_` or version line
-
-AGENTS.md is loaded every session; if it can't be cheaply freshness-checked, the staleness story collapses for the most-loaded file in the repo.
-
-### Detection
-
-```bash
-for f in AGENTS.md CLAUDE.md; do
-  [ -f "$f" ] && [ ! -L "$f" ] || continue
-  # Skip thin pointers (≤15 lines)
-  [ "$(wc -l < "$f")" -le 15 ] && continue
-  # Require either a Last-reviewed line or a Version line
-  if ! grep -qE '_Last reviewed:_?\s*[0-9]{4}-[0-9]{2}-[0-9]{2}|^Version:\s*[0-9]+\.[0-9]+' "$f"; then
-    echo "NO-REVIEW-LINE: $f"
-  fi
-done
-```
-
-A version line (`Version: 2026.04`) is acceptable — calendar-versioning AGENTS.md is valid for repos that re-cut docs per release.
-
-## Check 4 — every ADR has a `Status:` field
-
-Per [adr.github.io](https://adr.github.io/), an ADR without `Status:` is uninterpretable — readers can't tell if it's `proposed`, `accepted`, `deprecated`, or `superseded`. See `../doc-types/adr-pattern.md`.
-
-### Detection
-
-```bash
-# Status field can be in frontmatter (status:) OR in body (## Status: accepted).
-for f in $(find .brain/adrs docs/adrs docs/adr docs/decisions -name '*.md' 2>/dev/null); do
-  [ -f "$f" ] || continue
-  # README/index files are not ADRs
-  case "$(basename "$f")" in README.md|index.md|INDEX.md) continue ;; esac
-  if ! grep -qE '^status:\s+(proposed|accepted|deprecated|superseded|rejected)|^##\s+Status' "$f"; then
-    echo "ADR-NO-STATUS: $f"
-  fi
-done
-```
-
-Accept `proposed | accepted | deprecated | superseded | rejected` (case-insensitive). Custom workflows pass with a warning.
-
-## Check 5 — every postmortem has `severity:` and `duration:`
-
-Per Google's [SRE Book postmortem culture](https://sre.google/sre-book/postmortem-culture/) and `../doc-types/postmortem-pattern.md`, a postmortem without severity + duration is *narrative* — it can't be aggregated ("incidents per quarter at SEV-1" needs these).
-
-### Detection
-
-```bash
-for f in $(find .brain/postmortems docs/postmortems docs/incidents -name '*.md' 2>/dev/null); do
-  [ -f "$f" ] || continue
-  case "$(basename "$f")" in README.md|index.md|INDEX.md|TEMPLATE.md) continue ;; esac
-  has_sev=false; has_dur=false
-  grep -qE '^severity:\s*(SEV-?[0-9]|P[0-9]|critical|high|medium|low)' "$f" && has_sev=true
-  grep -qE '^duration:\s+' "$f" && has_dur=true
-  [ "$has_sev" = false ] && echo "POSTMORTEM-NO-SEVERITY: $f"
-  [ "$has_dur" = false ] && echo "POSTMORTEM-NO-DURATION: $f"
-done
-```
-
-`status:` (resolved / ongoing / blocked) and `date:` fall under Check 1 and Check 2 above.
-
-## Output shape (the gap-report row)
-
-```markdown
-- **NO-REVIEW-LINE — `AGENTS.md`** (severity: high)
-  - 187 lines of fat instructions, no `_Last reviewed:_` and no `Version:` line.
-  - **Promise 3 impact:** the most-loaded file in the repo is invisible to the audit.
-  - **Recommendation:** add `_Last reviewed: 2026-04-27 by @kimba_` near the top.
-
-- **ADR-NO-STATUS — `.brain/adrs/0007-pick-postgres.md`** (severity: high)
-  - **Recommendation:** add `Status: accepted` (or `superseded by 0014`). See `../doc-types/adr-pattern.md`.
-
-- **POSTMORTEM-NO-SEVERITY — `.brain/postmortems/2026-03-15-checkout-outage.md`** (severity: high)
-  - **Recommendation:** add `severity: SEV-2` and `duration: 47 minutes`.
-```
-
-## Severity rubric (consolidated)
-
-| Finding | Severity | Why |
-|---|---|---|
-| AGENTS.md / CLAUDE.md (fat) without `_Last reviewed:_` | High | Most-loaded file invisible to staleness tooling |
-| ADR without `Status:` | High | ADR uninterpretable; readers can't tell what's current |
-| Postmortem without `severity:` | High | Cannot aggregate; loses analytical value |
-| Postmortem without `duration:` | High | Same as above |
-| Canonical reference doc without `date:` or `_Last reviewed:_` | High | Invisible to staleness tooling |
-| Reference doc in `.brain/` without YAML frontmatter | Medium | Convention drift; advisory for narrative docs |
-| Doc without `_Owner:_` or implicit team owner | Medium | Ownership gap; advisory |
-
-## What this pattern is NOT for
-
-- **Content correctness** — `severity: SEV-2` passes hygiene even if the real severity was SEV-1. Content question.
-- **Schema validation** — shape only; a typed-skill schema validator is a different tool.
-- **Markdown structure** — heading levels, list indentation live in `markdownlint`, called from `staleness-tooling.md`.
-
-## Cross-references
-
-- Coverage gaps (does the file even exist?): `coverage-gaps.md`
-- Stale content (is the date recent enough?): `stale-content.md`, `staleness-tooling.md`
-- Entry-file shape (AGENTS.md sectional checks): `entry-file-coverage.md`
-- Pointer validation (do referenced files resolve?): `pointer-validation.md`
-- Orphan detection (is this file linked from anywhere?): `orphan-detection.md`
-- Memory fragmentation (are ADRs scattered across folders?): `memory-fragmentation.md`
-- ADR template: `../doc-types/adr-pattern.md`
-- Postmortem template: `../doc-types/postmortem-pattern.md`
-- Self-healing hook (run on commit): `../recipes/self-healing-hooks.md`
-- Context budget (AGENTS.md shape rules): `../guidance/context-budget.md`

package/skills/adia-ui-ops/references/audit-patterns/lockstep-versioning.md

@@ -1,113 +0,0 @@
-# Lockstep versioning (Promise-4 trip-wire for monorepos)
-
-**Added:** 2026-05-02 after the AdiaUI repo's caret-on-0.0.x lock-in
-postmortem (`a2ui-mcp@0.1.3 → corpus@0.0.6` shipped silently for ~4
-days).
-
-## The drift class
-
-Monorepos with multiple published packages accumulate one of two
-versioning failure modes:
-
-1. **Independent versions diverge silently.** Internal-dep ranges
-   like `^0.0.x` lock to exact versions under npm pre-1.0 semver
-   (`^0.0.6 = exactly 0.0.6`). Consumers track stale bundled
-   versions while developers see `main`.
-2. **Coordinated cuts have high friction.** Every change to any
-   package requires bumping all packages, regenerating lockfiles,
-   re-tagging, re-publishing. Operators skip the coordination → drift.
-
-Both modes produce shipping bugs that are invisible until a consumer
-reports it (or, in the AdiaUI case, until a manual code review
-catches it).
-
-## Detection (Promise-4 trip-wire)
-
-The trip-wire is a CI gate that runs on every PR. Three checks:
-
-1. **Version match:** all published packages share one version.
-2. **Caret-trap:** no `@<scope>/*` dep range matches `^0\.0\.\d+`.
-3. **Range alignment:** every internal `@<scope>/*` range is `^X.Y.0`
-   matching the lockstep version.
-
-Example implementation (AdiaUI repo,
-`scripts/release/check-lockstep.mjs`):
-
-```js
-const PACKAGES = [
-  "packages/a2ui/compose/package.json",
-  "packages/a2ui/corpus/package.json",
-  // ... 8 total
-];
-const ADIA_DEP_RE = /^@adia-ai\//;
-const CARET_0_0_X_RE = /^\^0\.0\.\d+$/;
-const VALID_CARET_RE = /^\^(\d+)\.(\d+)\.0$/;
-
-// Read all 9 package.jsons. Compare versions; flag mismatches.
-// For each @adia-ai/* dep across all 9: flag if ^0.0.x; flag if ranges differ.
-```
-
-Wire to CI:
-
-```yaml
-# .github/workflows/docs-lint.yml (or sibling workflow)
-lockstep-versioning:
-  name: Lockstep version coherence
-  runs-on: ubuntu-latest
-  steps:
-    - uses: actions/checkout@v4
-    - uses: actions/setup-node@v4
-    - run: node scripts/release/check-lockstep.mjs
-```
-
-The `--fix` mode rewrites mismatched ranges to the highest version
-observed. Used during a coordinated cut to sync the rest of the tree.
-
-## When to install
-
-Install when the monorepo has **2+ published packages** AND at least
-one package has internal-dep ranges to siblings. The catastrophic
-failure mode is `^0.0.x` ranges + a popular consumer-facing package;
-the gate prevents both from coexisting.
-
-The convention to write down (in the project's spec / docs):
-
-- All N published packages share one version `X.Y.0` with Y≥1.
-- Every internal dep range is `^X.Y.0` matching the lockstep version.
-- Cuts are atomic: bumping one bumps all N.
-- The CI gate fails any PR that misaligns.
-
-For AdiaUI's specific implementation (the worked example), see the
-consuming repo's `docs/specs/package-architecture.md` § 15 (versioning policy).
-
-## Prevention (post-publish admin)
-
-Once the gate is installed and passing, the post-publish admin:
-
-1. **Flip from `continue-on-error: true` to blocking.** Most cuts are
-   added with the gate advisory (because the cut PR itself can't pass
-   the gate — it's installing the gate against a misaligned repo).
-   After the cut succeeds, flip to blocking.
-2. **Add the gate to** `.brain/findings/INDEX.md` Graduations.
-3. **Cross-reference the postmortem** if the gate was prompted by an
-   incident.
-
-## Anti-patterns
-
-- **Don't make the gate optional.** A `continue-on-error: true` gate
-  is invisible to operators; the value is in the block.
-- **Don't try to make the policy "just for some packages."** The
-  caret-trap is a class — once you have the gate, sweep it across all
-  internal deps. Partial enforcement is worse than no enforcement
-  (operators trust the gate; misalignment in non-gated packages
-  becomes a different shipping bug class).
-- **Don't accept `^0.0.x` ranges with comments saying "we know."**
-  Comments don't enforce; the gate does.
-
-## Related
-
-- See [`feedback_npm_caret_on_0_0_x.md`](`~/.claude/projects/<repo>/memory/`) —
-  the user-memory entry (now flagged as superseded by the policy).
-- See `.brain/postmortems/2026-05-02-corpus-caret-lock.md` — the
-  postmortem that drove the gate's authoring.
-- See `lockstep-release` skill — the procedural counterpart for cuts.

package/skills/adia-ui-ops/references/audit-patterns/memory-fragmentation.md

@@ -1,180 +0,0 @@
----
-date: 2026-04-27
-coverage: canonical
-peers:
-  - orphan-detection.md
-  - stale-content.md
-  - entry-file-coverage.md
-  - ../recipes/continuous-learning-loop.md
-  - ../doc-types/adr-pattern.md
-  - ../doc-types/postmortem-pattern.md
-primary_sources:
-  - https://adr.github.io — ADR conventions; canonical folder layout
-  - https://sre.google/workbook/postmortem-culture/ — Google SRE postmortem culture
-  - Michael Nygard, "Documenting Architecture Decisions" (cognitect.com/blog/2011/11/15)
-  - https://learn.microsoft.com/en-us/azure/well-architected/architect-role/architecture-decision-record
-status: research-verified
----
-
-# Memory-fragmentation detection (delivers Promise 5, "continuously-learning")
-
-> **The premise.** A repo's memory primitives — ADRs, post-mortems, decision logs, RFCs — only compound if they live in **one canonical place per kind** and are reachable from AGENTS.md. When decisions live in PR descriptions, post-mortems live in Slack, and runbooks live in Notion, the agent (and every new human) starts from zero on every session. This audit detects the fragmentation and points at the consolidation recipe.
-
-## Where this fits
-
-`../recipes/continuous-learning-loop.md` describes the *flow* — how decisions and incidents become persistent memory. `../doc-types/adr-pattern.md` and `../doc-types/postmortem-pattern.md` describe the *artifacts*. This file is the *audit*: how to detect that the flow is broken or the artifacts are scattered.
-
-## Four signals of memory fragmentation
-
-| # | Signal | What it looks like | Severity |
-|---|---|---|---|
-| 1 | **No `.brain/adrs/` folder despite architectural-shape commits** | `git log --grep='migrate\|switch from\|adopt'` returns 20 hits; `.brain/adrs/` doesn't exist | High |
-| 2 | **No `.brain/postmortems/` despite incident-shape commits** | `git log --grep='hotfix\|revert\|incident\|outage'` returns matches; `.brain/postmortems/` empty | High |
-| 3 | **Decision/RFC/ADR text scattered outside the canonical folders** | `grep -ri 'decision\|ADR\|RFC' docs/` finds matches in random `docs/notes-*.md` files, not `.brain/adrs/` | Medium |
-| 4 | **AGENTS.md missing a "Memory primitives" section** | Agent doesn't know to consult ADRs / post-mortems / runbooks | **Critical** (closes-the-loop check) |
-
-Signal 4 is the most damaging. A repo can have an exemplary `.brain/adrs/` folder with 40 decisions, and if AGENTS.md doesn't tell the agent to *read it*, the artifacts are dead weight on disk.
-
-## The bash check
-
-```bash
-#!/usr/bin/env bash
-# scripts/check-memory-fragmentation.sh
-set -euo pipefail
-fail=0
-
-# Signal 1: ADR folder vs architectural-commit volume.
-arch=$(git log --since='2 years ago' \
-       --grep='migrate\|switch\|adopt\|introduce\|deprecate\|replace.*with' \
-       --oneline 2>/dev/null | wc -l | tr -d ' ')
-if [ ! -d .brain/adrs ] && [ ! -d docs/adrs ] && [ ! -d docs/architecture/decisions ] && [ ! -d adrs ]; then
-    [ "$arch" -gt 5 ] && { echo "FRAGMENT-NO-ADR-FOLDER: $arch arch-shape commits in 2y; no .brain/adrs/."; fail=1; }
-else
-    n=$(find .brain/adrs docs/adrs docs/architecture/decisions adrs -name '*.md' \
-        -not -name 'README.md' -not -name 'INDEX.md' 2>/dev/null | wc -l | tr -d ' ')
-    yrs=$(( ($(date +%s) - $(git log --reverse --format=%ct | head -1)) / 31536000 ))
-    [ "$yrs" -lt 1 ] && yrs=1
-    [ "$n" -lt "$yrs" ] && echo "FRAGMENT-SPARSE-ADRS: $n ADRs for ${yrs}y repo (expected >=$yrs)."
-fi
-
-# Signal 2: postmortems vs incident-shape commits.
-inc=$(git log --grep='hotfix\|revert\|incident\|outage\|rollback\|emergency' \
-      --oneline 2>/dev/null | wc -l | tr -d ' ')
-if [ ! -d .brain/postmortems ] && [ ! -d docs/postmortems ] && [ ! -d docs/incidents ] && [ ! -d docs/post-mortems ]; then
-    [ "$inc" -gt 3 ] && { echo "FRAGMENT-NO-POSTMORTEM-FOLDER: $inc incident-shape commits; none filed."; fail=1; }
-fi
-
-# Signal 3: decision/RFC/postmortem text outside canonical folders.
-canonical_re='\.brain/(adrs|postmortems|architecture)/|docs/(adrs|architecture/decisions|postmortems|incidents|post-mortems)/'
-find .brain docs -type f -name '*.md' -not -path '.brain/archive/*' -not -path 'docs/archive/*' | while read -r f; do
-    echo "$f" | grep -qE "$canonical_re" && continue
-    case "$(basename "$f")" in README.md|INDEX.md) continue ;; esac
-    if grep -qE '^## (Status|Decision|Consequences)' "$f" 2>/dev/null \
-       || grep -qiE '\b(post-?mortem|RFC[- ]?[0-9]|architecture decision record)\b' "$f"; then
-        echo "FRAGMENT-MISPLACED: $f is decision/postmortem/RFC-shaped but outside canonical folders."
-    fi
-done
-
-# Signal 4: AGENTS.md "Memory primitives" section (hard fail).
-c=AGENTS.md; [ ! -f "$c" ] && [ -f CLAUDE.md ] && c=CLAUDE.md
-if [ -f "$c" ] && [ ! -L "$c" ]; then
-    grep -qiE '^## *(memory primitives|memory|where to find|key documents)' "$c" \
-        || { echo "FRAGMENT-NO-MEMORY-SECTION: $c lacks a Memory primitives section."; fail=1; }
-fi
-exit $fail
-```
-
-Heuristics are conservative — most findings are advisory. Only signal 4 is gated as a hard finding because it always indicates a closed-loop break.
-
-## What each signal recommends
-
-### Signal 1 — no `.brain/adrs/` despite architectural commits
-
-**Recommendation.** Bootstrap the folder with `recipes/adr-introduction.md` (planned per the INDEX). The first ADR (`0001-record-architecture-decisions.md`) is the meta-decision: "we will record architectural decisions". Then back-fill 3-5 of the most-impactful past architectural changes as historical ADRs.
-
-### Signal 2 — incidents without post-mortems
-
-**Recommendation.** Create `.brain/postmortems/` (or `docs/incidents/`). For commits matching the incident heuristic (`hotfix`, `revert`, `outage`), do *not* try to retroactively reconstruct post-mortems for events the team didn't review. Instead: install the convention going forward, and as the next SEV-1 / SEV-2 happens, run the post-mortem flow per `../doc-types/postmortem-pattern.md`.
-
-### Signal 3 — misplaced decision/RFC/postmortem text
-
-**Recommendation.** Move the file. The audit emits a `git mv` suggestion:
-
-```bash
-# For each FRAGMENT-MISPLACED file, the recommendation is:
-git mv docs/notes-on-postgres-decision.md .brain/adrs/0014-use-postgres-not-mysql.md
-# Then re-number to fit the existing sequence; update any inbound links.
-```
-
-Re-numbering is mandatory if the canonical folder uses sequential numbering. The audit does not auto-rename — too easy to break links — but it lists all candidates so the consolidation can be batched in one PR.
-
-### Signal 4 — no Memory primitives section in AGENTS.md
-
-**Recommendation.** Add the section using the template from `../recipes/continuous-learning-loop.md`:
-
-```markdown
-## Memory primitives
-
-- **Before architectural changes**, read `.brain/adrs/` newest-first. If your
-  proposed change conflicts with an `Accepted` ADR, write a new ADR
-  superseding it; don't silently override.
-
-- **When debugging a production issue**, search `.brain/postmortems/` for
-  prior occurrences. Many "new" bugs are repeats.
-
-- **When you make a mistake the user has to correct**, ask: "Should I add
-  this to AGENTS.md so I don't repeat it?" Most of the time the answer is
-  yes. Add a one-line correction with a dated parenthetical.
-
-- **When a runbook is needed for a recurring operation**, file it in
-  `.brain/runbooks/` rather than embedding it in AGENTS.md.
-```
-
-This is the single highest-leverage edit in any audit — without it, Promise 5 isn't being delivered no matter how many ADRs the repo has.
-
-## Out-of-repo memory (the harder problem)
-
-A category of fragmentation the bash check can't detect: decisions and post-mortems that live *outside* the repo entirely — in Slack threads, Notion pages, Confluence, Linear comments, Google Docs, meeting notes, individual engineers' brains.
-
-The audit can't grep these. What it *can* do is emit an advisory finding:
-
-```text
-ADVISORY: Repo has 47 PRs in 12 months that mention "RFC", "decision", or "design doc"
-in their description but no ADRs were written. Consider whether decisions are
-being captured durably, or only in transient PR descriptions.
-```
-
-```bash
-# Heuristic for the advisory
-gh pr list --state merged --limit 200 --search "RFC OR decision OR \"design doc\"" \
-    --json number,title --jq '. | length' 2>/dev/null
-```
-
-The fix is cultural, not mechanical: the team agrees that "decision in a PR description" → "ADR in `.brain/adrs/`" before merge. The PR template change is in `../recipes/continuous-learning-loop.md` (Flow 2).
-
-## Severity rubric
-
-| Finding | Severity | Why |
-|---|---|---|
-| AGENTS.md missing Memory primitives section | **Critical** | Closes-loop check; artifacts on disk are dead weight without it |
-| `.brain/adrs/` missing AND repo has architectural-shape commits | High | Decisions are evaporating into PR descriptions |
-| `.brain/postmortems/` missing AND repo has incident-shape commits | High | Lessons aren't compounding |
-| Decision-shaped content outside canonical folders | Medium | Discoverability breaks; agent won't find it |
-| Sparse ADRs (<1 per year of repo age) for repos >2 years old | Medium | Likely under-capture; advisory |
-| Out-of-repo memory (Slack/Notion) | Advisory | Cultural fix; audit emits a recommendation, not a hard finding |
-
-## What this pattern is NOT for
-
-- **Detecting whether individual ADRs are well-written** — that's a content-quality check, not a fragmentation check. See `../doc-types/adr-pattern.md` for the format rubric.
-- **Detecting stale ADRs** — ADRs are immutable; "stale" doesn't apply. An ADR replaced by a newer one is `Superseded`, not `stale`. The audit explicitly excludes `.brain/adrs/` from `stale-content.md`'s heuristic 1.
-- **Detecting that a post-mortem is blameless** — the convention is in `../doc-types/postmortem-pattern.md`; the audit doesn't enforce it because language analysis is unreliable.
-- **Runbooks** — `.brain/runbooks/` is mentioned in the Memory primitives template but isn't its own audit category yet (could be added in v0.3.0).
-
-## Cross-references
-
-- Continuous-learning loop (the flow this audit verifies): `../recipes/continuous-learning-loop.md`
-- ADR pattern (the canonical artifact format): `../doc-types/adr-pattern.md`
-- Post-mortem pattern (the other canonical artifact format): `../doc-types/postmortem-pattern.md`
-- Orphan detection (sibling — finds unreachable docs, here we find scattered ones): `orphan-detection.md`
-- Stale-content (sibling Promise 3 audit): `stale-content.md`
-- Entry-file coverage (precondition — AGENTS.md exists to host Memory primitives section): `entry-file-coverage.md`