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

package/skills/adia-ui-ops/references/recipes/harvest-repo-brain.md

@@ -1,169 +0,0 @@
----
-date: 2026-04-29
-coverage: canonical
-peers:
-  - import-repo-brain-harvest.md
-  - cold-start-harvest.md
-  - continuous-learning-loop.md
-  - ../audit-patterns/audit-history-ledger.md
-status: research-verified
----
-
-# Harvest ops-repo (export findings + sync to agent memory + update harness)
-
-> **The premise.** The `.brain/` tree is the repo's long-term memory; agent memory at `~/.claude/projects/<repo>/memory/` is the per-conversation working memory; `AGENTS.md` / `.claude/settings.json` is the harness that decides what gets loaded when. **`harvest ops-repo`** runs all three in one pass: ingests every finding the brain has accumulated, lifts the durable ones into agent memory, and (optionally) updates the harness so the next session loads them.
-
-This recipe is invoked by phrases like:
-- "harvest ops-repo"
-- "use ops-repo to harvest"
-- "sync brain to agent memory"
-- "promote findings to memory"
-- "harvest brain matter"
-
-It has two output paths the user picks between (or runs both):
-
-- **Local sync** — write to `~/.claude/projects/<repo>/memory/`. The next session in *this* repo starts richer. Default.
-- **Portable export** — write a bundle to `/tmp/brain-export-<repo>-<date>/`. Another repo's `ops-repo` can `import` it. Opt-in.
-
-## What gets harvested
-
-Source-of-truth inventory:
-
-| Source | Memory destination | Disposition rule |
-|---|---|---|
-| `.brain/adrs/*.md` (status: `accepted` or `superseded`) | `project_<topic>.md` | One memory per ADR. The decision + rationale → body. Skip `proposed` / `rejected`. |
-| `.brain/postmortems/*.md` (the lessons section) | `feedback_<lesson_slug>.md` | One memory per *lesson bullet*, not per postmortem. Each lesson gets `**Why:**` + `**How to apply:**`. |
-| `docs/conventions/*.md` (rule paragraphs) | `feedback_<rule_slug>.md` | Extract individual rules; body points back at the convention file for full text. |
-| `.brain/findings/INDEX.md` (OPEN entries with severity ≥ medium) | (audit-input only — not promoted) | Findings are working state, not durable canon. They feed the harness-update step instead. |
-| `.brain/audit-history/*.json` (recent trip-wire results) | (audit-input only) | Used to detect harness gaps, not promoted as memories. |
-| External URLs cited 2+ times across the brain | `reference_<topic>.md` | One-liner + URL. |
-| Journal sections cited 3+ times from ADRs/postmortems/conventions | `feedback_<topic>.md` | Citation count is the promotion gate; below threshold stays in the journal. |
-| Operator-profile facts in `AGENTS.md` (role, expertise, tooling) | `user_<aspect>.md` | Only if AGENTS.md states them explicitly. |
-
-## What does NOT get harvested
-
-- Per-day journal entries (high-volume, mostly already distilled into ADRs / postmortems / conventions).
-- ADRs with status `proposed` / `rejected` (working memory, not durable).
-- Boilerplate convention prose (rules > 30 lines stay in the convention file; the memory is a *pointer*).
-- Anything matching the secret-pattern redactor (same list as `audit-history-ledger.md` privacy section).
-
-## Procedure
-
-The agent runs through these steps. User-confirmation gates are marked **[gate]**.
-
-1. **Resolve the agent-memory directory.** It's `~/.claude/projects/<encoded-repo-path>/memory/`. The encoding replaces `/` with `-` and prefixes `-`. Confirm by inspecting an existing file there if uncertain.
-
-2. **Inventory existing memory.** Read `MEMORY.md` and list the directory. Build a map of `existing_name → file` so the harvest can update in place rather than create duplicates.
-
-3. **Walk ADRs.** For each `.brain/adrs/NNNN-*.md` with `status: accepted` or `superseded`:
-   - Title → `name` field
-   - Frontmatter summary or first paragraph → `description` field (one-liner)
-   - Decision + rationale → body, structured as `**Why:** … **How to apply:** …`
-   - If a matching memory exists → diff and update; else → create
-
-4. **Walk postmortems.** For each `.brain/postmortems/YYYY-MM-DD-*.md`:
-   - Find the *Lessons* / *Memory* / *Memories captured* section
-   - Each bulleted lesson → its own `feedback_*.md` (don't bundle)
-   - Postmortem title → `description` hook
-   - Lesson rule → body lead, then `**Why:**` (the incident), `**How to apply:**` (when to invoke)
-
-5. **Walk conventions.** For each `docs/conventions/*.md`:
-   - Extract individual rules (`## ` headings or numbered list items)
-   - One `feedback_*` per rule
-   - Body: rule + `**Why:** ... **How to apply:** see docs/conventions/<file>.md` for full text
-
-6. **Walk external references.** Grep for `https://` URLs that recur 2+ times in `.brain/`:
-   ```bash
-   grep -rhoE 'https?://[^ )"]+' .brain/adrs .brain/postmortems docs/conventions | \
-     sort | uniq -c | sort -rn | awk '$1 >= 2'
-   ```
-   - Each → one `reference_*.md` (one-liner + URL)
-
-7. **Promote frequent journal sections.** Citation count:
-   ```bash
-   grep -rhoE 'journal/.*§\s*[0-9]+' .brain/ docs/conventions/ | \
-     sort | uniq -c | sort -rn | awk '$1 >= 3'
-   ```
-   - For each, read the journal section, distill to a rule, write `feedback_*`
-
-8. **Audit the harness.** Read `.claude/settings.json` (project) and `~/.claude/settings.json` (user). Check for:
-   - **Hooks gap:** if a finding mentions "should run X before commit" 3+ times in `.brain/audit-history/`, propose a `pre-commit` hook
-   - **Permission gap:** if commands in `.brain/runbooks/` aren't in `permissions.allow`, propose adding them
-   - **Memory ceiling:** if `MEMORY.md` after harvest exceeds 200 lines, propose pruning the lowest-value entries (lowest description quality, oldest by file mtime)
-
-9. **[gate] Diff-and-confirm.** Show the user a 5-line preview per memory candidate (name, description, type, body lead, action: create/update/skip). For harness changes, show the proposed `settings.json` diff. Default interactive; allow `--yes` for bulk seeding.
-
-10. **Apply approved changes.** Write memory files; update `MEMORY.md` index; apply settings.json diff if approved.
-
-11. **Optional portable export.** If the user requested a portable bundle (or invoked `harvest ops-repo --export`):
-    - Build `/tmp/brain-export-<repo>-<date>/` with manifest.json + adrs/ + postmortems/ + conventions-portable/ + findings-schema.json + audit-history-schema.json + config.toml.example + agents-template.md
-    - Manifest schema, sanity gates (no absolute paths, no secrets, ≤5MB), and bundle README — see [`import-repo-brain-harvest.md`](./import-repo-brain-harvest.md) for the receiving-side contract
-
-12. **Report.** Print a summary:
-    ```
-    Harvested 14 memory files from .brain/ + docs/conventions/:
-      ✓ 8 project_  (from 10 ADRs — 2 already in memory, updated in place)
-      ✓ 4 feedback_ (from 1 postmortem + 3 conventions)
-      ✓ 2 reference_ (from external URLs cited 2+ times)
-      ✓ 0 user_     (AGENTS.md doesn't state operator profile)
-
-    Harness updates applied:
-      ✓ pre-commit hook for "verify journal-date" (cited 3× in audit-history)
-      ✓ permissions.allow += ["Bash(npm run verify:*)"]
-      MEMORY.md: 18 → 32 lines (well under 200 ceiling).
-
-    Portable bundle: not requested. Re-run with --export to produce one.
-    ```
-
-## Memory-file format reminder
-
-Each memory file is its own markdown with frontmatter:
-
-```markdown
----
-name: {{short title}}
-description: {{one-line description used to decide relevance in future conversations}}
-type: {{user | feedback | project | reference}}
----
-
-{{body — for feedback/project, structure as: rule/fact, then **Why:** and **How to apply:** lines}}
-```
-
-`MEMORY.md` index is a flat list, one line per entry, < 200 lines:
-
-```markdown
-- [Title](file.md) — one-line hook
-```
-
-## Sanity checks
-
-Before write, every candidate must pass:
-
-- [ ] Body ≤ 30 lines (long content stays in `.brain/` / `docs/`; memory points to it)
-- [ ] `description` is meaningful (no "TODO", no placeholder)
-- [ ] `type` is one of `user` / `feedback` / `project` / `reference` (no inventions)
-- [ ] No file path under `/Users/`, `/home/`, `C:\`
-- [ ] No content matching `sk_live_`, `ghp_`, `aws_secret_access_key`, `BEGIN PRIVATE KEY`, `Authorization: Bearer`
-- [ ] No filename collision (existing entries get *updated*, not duplicated)
-
-If the portable bundle path is selected, the bundle ALSO must pass:
-
-- [ ] Manifest.json parses + every disposition claim has a matching file
-- [ ] No absolute user paths
-- [ ] Bundle size < 5 MB
-- [ ] No file references hostnames matching `*.internal`, `*.corp`, IPv4 addresses, or `localhost`-anchored URLs
-
-## Cadence
-
-- **At repo onboarding** — first run seeds the agent's memory with the existing canon. Most-impactful single invocation.
-- **Per quarter** — sweep recent ADRs / postmortems / conventions for promotions.
-- **On-demand after a postmortem lands** — promote the lesson immediately so the next session catches it.
-- **NOT weekly cron** — memory churn confuses the agent more than it helps.
-
-## See also
-
-- [`import-repo-brain-harvest.md`](./import-repo-brain-harvest.md) — the receiving-side recipe (consumes a portable bundle, syncs to agent memory)
-- [`continuous-learning-loop.md`](./continuous-learning-loop.md) — the broader Anthropic-iterate pattern this skill instantiates
-- [`cold-start-harvest.md`](./cold-start-harvest.md) — the inverse flow (importing buried learnings *into* the brain layout for the first time)
-- [`../audit-patterns/audit-history-ledger.md`](../audit-patterns/audit-history-ledger.md) — privacy / redaction reference for the bundle export
-- The auto-memory section of the parent repo's `AGENTS.md` — canonical description of the memory system (types, filename conventions)

package/skills/adia-ui-ops/references/recipes/import-repo-brain-harvest.md

@@ -1,153 +0,0 @@
----
-date: 2026-04-29
-coverage: canonical
-peers:
-  - harvest-repo-brain.md
-  - cold-start-harvest.md
-  - continuous-learning-loop.md
-status: research-verified
----
-
-# Import ops-repo harvest (consume a portable bundle into this brain)
-
-> **The premise.** Some other repo ran `harvest ops-repo --export` and produced a portable bundle. **`import ops-repo harvest`** ingests that bundle into *this* repo's `.brain/` tree, then syncs the new content into the agent's memory at `~/.claude/projects/<this-repo>/memory/` so the next session catches everything immediately.
-
-This recipe is invoked by phrases like:
-- "import ops-repo harvest"
-- "use ops-repo to import"
-- "ingest brain bundle"
-- "import bundle from <path>"
-- "merge another repo's brain into this one"
-
-The inverse of [`harvest-repo-brain.md`](./harvest-repo-brain.md). One produces; the other consumes. Together they let institutional memory move between repos without touching source code.
-
-## What gets imported
-
-The bundle's `manifest.json` declares disposition per artifact. The importer respects it:
-
-| Bundle artifact | Target | Collision rule |
-|---|---|---|
-| `bundle/adrs/NNNN-*.md` | `.brain/adrs/` | Renumber on collision (next free `NNNN`); preserve original number in body as `Originally: 0007 (source-repo)` |
-| `bundle/postmortems/YYYY-MM-DD-*.md` | `.brain/postmortems/` | Date prefix is unique enough; on exact-match append `-imported` to filename |
-| `bundle/postmortems/_TEMPLATE.md` | `.brain/postmortems/_TEMPLATE.md` | If absent in target, install. If present, diff and prompt — don't auto-overwrite |
-| `bundle/runbooks-portable/*.md` | `.brain/runbooks/` | Same diff-and-prompt rule |
-| `bundle/conventions-portable/*.md` | `docs/conventions/` | Same — never auto-overwrite |
-| `bundle/findings-schema.json` | (use to validate `.brain/findings/INDEX.md`) | If target has no `INDEX.md`, install one with the imported schema |
-| `bundle/audit-history-schema.json` | (use to validate `.brain/audit-history/`) | First imported audit lands in the same shape as the source |
-| `bundle/config.toml.example` | `.brain/config.toml` | If target has no config, install with imported defaults; otherwise diff-and-prompt |
-| `bundle/agents-template.md` | (use to verify target `AGENTS.md` has parallel sections) | Read-only — informs the gap report |
-
-## What does NOT get imported
-
-- Source files, configs, package files (the bundle should never include these; if it does, refuse to import)
-- Anything in `bundle/audit-history/` content — only the *schema*. Each repo's audit ledger is its own.
-- Anything matching the secret-pattern redactor (defense in depth — the source should have stripped these, but verify)
-
-## Procedure
-
-User-confirmation gates marked **[gate]**.
-
-1. **[gate] Locate the bundle.** Default path: `../brain-export-*-*/`. The user can pass an explicit path. If multiple bundles match, prompt for selection.
-
-2. **Validate the bundle.**
-   - `manifest.json` parses
-   - Every `disposition: "portable"` claim has a corresponding file
-   - Bundle size < 5 MB (refuse to import larger — likely contains junk)
-   - No file matches secret patterns (refuse on hit)
-   - No absolute user paths in any text file (warn-and-strip)
-
-3. **Detect target's brain layout.**
-   - `.brain/` exists? Use it.
-   - Only legacy `docs/{adrs,postmortems,...}/` exists? Recommend running base `ops-repo` to migrate to `.brain/` first; abort import unless user forces.
-   - Neither exists? Recommend `greenfield-setup.md`; abort.
-
-4. **Plan the merges.** For each bundle artifact, compute:
-   - Target path
-   - Collision: none / rename / diff-and-prompt
-   - Renumber map (for ADRs)
-
-5. **[gate] Show the merge plan.** Render as a table; let the user veto per-row. Default interactive; allow `--yes` for bulk import.
-
-6. **Apply the plan.**
-   - Copy ADRs (with renumbering as planned)
-   - Copy postmortems (with `-imported` suffix on date collisions)
-   - Diff-prompt each runbook and convention; user picks accept / reject / merge-manually
-   - Install schemas + config.toml if absent
-
-7. **Update local INDEX files.**
-   - `.brain/adrs/README.md` (if present): refresh the index to include imported ADRs with a `(imported from <source-repo>)` annotation
-   - `.brain/postmortems/INDEX.md`: same
-   - `.brain/findings/INDEX.md`: keep target's findings, but add an "Imported from <source>" section if the source had `## Graduations` content worth preserving
-
-8. **Run a fresh audit.** Invoke the parent `ops-repo` audit on the freshly-imported state. The ledger entry will record the import as the audit's source event.
-
-9. **Sync to agent memory.** Pipeline: the imported ADRs / postmortems / conventions feed the harvest pass from [`harvest-repo-brain.md`](./harvest-repo-brain.md). User can opt out (`--no-memory-sync`) but default is to run it — the import is most useful when it propagates all the way to the agent's working memory.
-
-10. **Sync the harness if recommended.** Re-run the harness audit step from `harvest-repo-brain.md`: any pre-commit hooks the source had that aren't installed locally, propose them; any `permissions.allow` entries the source needed for its runbooks, propose them.
-
-11. **[gate] Approve harness changes.** Settings updates always require explicit confirmation — even with `--yes`.
-
-12. **Report.** Print a summary:
-    ```
-    Imported brain-export-source-repo-2026-04-29/ (manifest v1.0, 412 KB):
-      ✓ 7 ADRs copied (5 renumbered to 0011-0017; 2 already present, skipped)
-      ✓ 1 postmortem copied
-      ✓ _TEMPLATE.md updated (your version was older, accepted import)
-      ✓ 2 runbooks (1 accepted, 1 rejected — bumped to /tmp/ for review)
-      ✓ 3 conventions (3 accepted)
-      ✓ Schemas installed (findings-schema, audit-history-schema)
-
-    Memory sync (via harvest-repo-brain pipeline):
-      ✓ 7 project_  (from imported ADRs)
-      ✓ 4 feedback_ (from imported postmortem + 3 conventions)
-      MEMORY.md: 32 → 43 lines.
-
-    Harness recommendations:
-      ✓ pre-commit hook for "verify journal-date" (proposed; user approved)
-      ✓ permissions.allow += ["Bash(npm run verify:*)"] (proposed; user approved)
-
-    Audit run:
-      ✓ Trip-wires green; ledger entry written to .brain/audit-history/2026-04-29-import-source.json
-    ```
-
-## Sanity checks
-
-Refuse to import if any of these fail:
-
-- [ ] Bundle's `manifest.json` is missing or invalid
-- [ ] Bundle contains files outside the declared dispositions
-- [ ] Bundle contains absolute user paths or matches secret patterns (defense in depth)
-- [ ] Bundle size > 5 MB
-- [ ] Target has uncommitted changes in `.brain/` (require clean tree to make rollback safe)
-- [ ] Target's git branch isn't main / a dedicated import branch (refuse to import on a release branch)
-
-Always require **explicit user confirmation** for:
-
-- Overwriting existing ADR / postmortem / convention content (default: skip on collision)
-- Settings.json modifications (default: prompt)
-- Adding pre-commit hooks (default: prompt — hooks are powerful)
-- Auto-syncing to agent memory (default: prompt; opt-out flag)
-
-## Rollback
-
-The import never touches anything outside `.brain/` + `docs/conventions/` + `~/.claude/projects/<repo>/memory/` + `.claude/settings.json`. To roll back:
-
-```bash
-git checkout -- .brain/ docs/conventions/ .claude/settings.json
-# memory files are user-scope; restore from a backup if needed
-```
-
-The audit-history ledger entry that records the import is **not** rolled back — it's append-only. The next audit will show the import was reverted; that's the audit trail working as intended.
-
-## When to NOT import
-
-- Two repos with truly divergent architectures (a Vue 3 SaaS vs an Elixir CLI). The ADRs won't translate; the postmortems won't translate; you'll spend more time triaging than the import saves.
-- The source bundle is older than 90 days. Brain matter ages — better to ask the source repo to re-harvest fresh.
-- The target repo is mid-incident. Import lands cleanly only against a steady-state target.
-
-## See also
-
-- [`harvest-repo-brain.md`](./harvest-repo-brain.md) — the producing-side recipe; this is its inverse
-- [`cold-start-harvest.md`](./cold-start-harvest.md) — different flow (extracts buried learnings from an existing repo's scattered docs into the brain layout for the first time)
-- [`continuous-learning-loop.md`](./continuous-learning-loop.md) — the broader iterate pattern import-then-audit instantiates
-- [`../audit-patterns/audit-history-ledger.md`](../audit-patterns/audit-history-ledger.md) — privacy redactor reference (defense-in-depth on the import)

package/skills/adia-ui-ops/references/recipes/memory-organization.md

@@ -1,182 +0,0 @@
----
-date: 2026-04-27
-coverage: canonical
-peers:
-  - greenfield-setup.md
-  - adr-introduction.md
-  - audit-existing-repo.md
-  - continuous-learning-loop.md
-  - ../doc-types/adr-pattern.md
-  - ../doc-types/postmortem-pattern.md
-  - ../doc-types/decisions-log.md
-primary_sources:
-  - https://adr.github.io/madr/
-  - https://sre.google/workbook/postmortem-culture/
-  - https://learn.microsoft.com/en-us/azure/well-architected/architect-role/architecture-decision-record
-  - https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions
-status: research-verified
----
-
-# Recipe: organize ADRs, postmortems, runbooks, and decision logs (delivers Promise 5)
-
-> **The premise.** Memory primitives only compound if they have *one* obvious home each. The most common organizational failure is not absence — it's split-brain: `.brain/adrs/` AND `docs/decisions/`, both half-populated, both authoritative-looking. The agent loads both, gets contradictions, and learns nothing. This recipe makes the layout decisive.
-
-## The four memory primitives
-
-| Primitive | What it captures | Storage | Lifecycle |
-|---|---|---|---|
-| **ADR** | A specific architectural commitment | `.brain/adrs/NNNN-*.md` | Proposed → Accepted → (Superseded) |
-| **Postmortem** | An incident retrospective | `.brain/postmortems/YYYY-MM-DD-*.md` | Drafted → Resolved (mostly immutable) |
-| **Runbook** | A repeatable operational procedure | `.brain/runbooks/<verb-noun>.md` | Living; revised in place |
-| **Decision log entry** (looser) | A non-architectural commitment too small for an ADR | `docs/decisions/YYYY-MM-DD-*.md` (optional) | Living, dated, lighter-weight |
-
-Plus two adjacent (not memory but co-located):
-
-| Document | Storage | Why it's not memory |
-|---|---|---|
-| **Architecture overview** | `docs/ARCHITECTURE.md` (or `.brain/architecture/`) | Describes current state, not decision history |
-| **Spec / RFC / pre-decision draft** | `docs/drafts/` or `docs/rfcs/` | Pre-decision; converts to ADR when accepted |
-
-## The decision tree (which folder does this go in?)
-
-| If you can say... | It belongs in... |
-|---|---|
-| "We decided to use X instead of Y" (architectural) | `.brain/adrs/` |
-| "We picked library X over Y" (small, reversible) | `docs/decisions/` (optional) |
-| "On April 12, the checkout broke because..." | `.brain/postmortems/` |
-| "To roll out a new region, run these 8 steps" | `.brain/runbooks/` |
-| "The system has these services and they talk like..." | `docs/ARCHITECTURE.md` |
-| "Here's what we're considering for next quarter" | `docs/drafts/` or `docs/rfcs/` |
-
-If the team can describe each new doc in one sentence, the right folder usually pops out.
-
-## Should I have `.brain/adrs/` AND `docs/decisions/`?
-
-**Most teams: no.** Pick one. ADRs cover both architectural and non-architectural decisions just fine — especially since MADR 4.0.0 (Sept 2024) explicitly broadens scope to non-architectural by renaming the *A* to *Any*.
-
-**Some teams: yes.** When ADRs feel too heavy for routine choices ("we picked Vitest over Jest"), a lighter `docs/decisions/` folder reduces activation energy. Trade-off: now you have two places to look. Document the split in `.brain/adrs/README.md`:
-
-```markdown
-# Decision logs
-
-This repo splits decisions into two folders by weight:
-- `.brain/adrs/` — architectural commitments (MADR format, full context).
-- `docs/decisions/` — lighter-weight (one-paragraph, dated).
-
-When in doubt, prefer ADR.
-```
-
-The audit checks both layouts and flags neither as wrong — only flags when both exist *without* a documented split rationale. See `../doc-types/decisions-log.md`.
-
-## Where do design docs go?
-
-A "design doc" is usually one of:
-
-| Doc actually is... | Goes in... |
-|---|---|
-| A pre-decision proposal under discussion | `docs/drafts/` (delete after decided) or `docs/rfcs/` (keep with `Status:`) |
-| The decision itself, after it's made | `.brain/adrs/NNNN-*.md` |
-| The current architecture | `docs/ARCHITECTURE.md` |
-| A spec for a feature being built | `docs/specs/` |
-
-The most common confusion: someone writes a "design doc", the team accepts it, and it sits there forever as both pre-decision artifact and post-decision record. Resolve by moving the *decision* into an ADR (which references the design doc), and archiving the original.
-
-## When is something a runbook vs a doc?
-
-| If a person needs to follow steps to *do* something | Runbook |
-|---|---|
-| If a person needs to *understand* something | Architecture / README / docs |
-
-Tells: imperative voice + numbered steps → runbook. Declarative voice + continuous prose → docs. Filename: `<verb>-<noun>.md` (`deploy-staging.md`, `rotate-secrets.md`, `roll-back.md`). Time-stamped runbooks are a smell — runbooks are living; postmortems handle "things that happened on a date".
-
-## File-naming conventions
-
-| Folder | Convention | Why |
-|---|---|---|
-| `.brain/adrs/` | `NNNN-kebab-case-title.md` (4-digit, sequential) | Numbered for sequence; immutable after Accepted |
-| `.brain/postmortems/` | `YYYY-MM-DD-incident-name.md` | Sorts chronologically; date is the unique identifier |
-| `docs/decisions/` | `YYYY-MM-DD-decision-name.md` | Sorts chronologically; small enough that numbering is overkill |
-| `.brain/runbooks/` | `<verb>-<noun>.md` | No date — runbooks are living |
-| `.brain/architecture/` | `<topic>.md` (kebab-case) | Topical, not temporal |
-| `docs/drafts/` | freeform | Not yet committed |
-| `.brain/archive/` | `original-name-YYYY-MM-DD.md` | Provenance preserved for moved-orphans |
-
-## Index files (`README.md` in each folder)
-
-Every memory folder gets a `README.md` index:
-
-```markdown
-# Architecture Decision Records
-
-(...one-paragraph orientation...)
-
-## Index
-
-| # | Title | Status | Date |
-|---|---|---|---|
-| 0001 | Record architecture decisions | Accepted | 2026-04-27 |
-| 0002 | Use Postgres over MySQL | Accepted | 2026-04-27 |
-
-_Last reviewed: 2026-04-27_
-```
-
-Postmortems use a similar table sorted newest-first. Runbooks use a flat list grouped by area (deployment / observability / security / data). Auto-generation tools (`adr-log`) work but are optional — hand-curated tables stay accurate longer than people fear.
-
-## Lifecycle: Proposed → Accepted → Superseded
-
-ADR statuses are load-bearing:
-
-- **Proposed** — under discussion. Audit flags Proposed >30 days (probably abandoned).
-- **Accepted** — committed. Immutable; only edited for typos, never substance.
-- **Rejected** — considered and chosen against. Recorded so it doesn't get re-proposed without context.
-- **Deprecated** — no longer active but not yet replaced.
-- **Superseded by ADR-NNNN** — replaced by a newer decision. Both ADRs stay; the older one stays in place with the supersession note.
-
-Postmortems: Drafted → Resolved. After Resolved, edits are limited to typos. Runbooks: continuously edited; `_Last reviewed:_` line is the freshness signal.
-
-## How AGENTS.md exposes all of this
-
-The `Where to find things` section enumerates the homes:
-
-```markdown
-## Where to find things
-- **Architecture:** `docs/ARCHITECTURE.md`
-- **Architecture Decision Records:** `.brain/adrs/` (index: `.brain/adrs/README.md`)
-- **Decision log (lighter-weight):** `docs/decisions/` (only if your team uses both)
-- **Post-mortems:** `.brain/postmortems/` (index: `.brain/postmortems/README.md`)
-- **Runbooks:** `.brain/runbooks/` (index: `.brain/runbooks/README.md`)
-- **Drafts / RFCs:** `docs/drafts/` (pre-decision; do not treat as committed)
-```
-
-The `Memory primitives` section instructs *when* to read each:
-
-```markdown
-## Memory primitives
-- **Before architectural decisions**, read `.brain/adrs/` newest-first.
-- **When debugging production issues**, search `.brain/postmortems/`.
-- **When running operational procedures**, look in `.brain/runbooks/`
-  before improvising. If missing, write the runbook *while* doing it.
-- **Drafts in `docs/drafts/` are not commitments** — do not implement
-  them as if they were ADRs.
-```
-
-This closes the continuous-learning loop — see `continuous-learning-loop.md`.
-
-## Common organizational anti-patterns
-
-- **`.brain/adrs/` and `docs/decisions/` both half-populated, no documented split.** Pick one or document the split.
-- **Postmortems in `docs/traces/`.** "Traces" reads as observability traces (OpenTelemetry / Jaeger). Use `.brain/postmortems/` or `docs/incidents/`.
-- **Runbooks under date-prefix names.** Runbooks are living; date-prefixes lie.
-- **Design docs that became ADRs without archiving the originals.** Two sources of truth on the same decision.
-- **No index files.** Folder is technically populated but undiscoverable without `ls`.
-- **Postmortems in private docs (Notion, Confluence).** Unreachable from the agent; aggressively link from AGENTS.md.
-
-## Cross-references
-
-- ADR pattern: `../doc-types/adr-pattern.md`
-- Postmortem pattern: `../doc-types/postmortem-pattern.md`
-- Decision log: `../doc-types/decisions-log.md`
-- Greenfield setup (creates this layout day one): `greenfield-setup.md`
-- ADR introduction (retrofit): `adr-introduction.md`
-- Continuous-learning loop: `continuous-learning-loop.md`
-- AGENTS.md Memory primitives section: `../standards/agents-md-spec.md`