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

package/skills/adia-ui-ops/references/audit-cadence.md

@@ -1,263 +0,0 @@
-# Audit cadence — the 3-phase invocation contract
-
-> **Owner: `adia-ui-ops` mode 5** (cold-start triage entry).
-> Absorbed verbatim from the retired standalone `ops-repo` skill (v1.8.0,
-> 2026-05-22) — `§Invocation`, `§The five promises`, `§Verification`,
-> `§Audit categories`, `§What this skill (does NOT) produces`, `§The
-> opinionated stance`, `§Quick reference`, `§Invariants`. Only the framing
-> wrapper changed; the content body is identical.
-
-Turn any repo into a **brain** for LLM coding agents — a less-wasteful,
-token-and-context-optimized, less-prone-to-staleness, self-healing,
-continuously-learning **memory layer** for the agents that work in it.
-
-> **What "brain" means here — and what it doesn't.** The repo doesn't
-> think. **You + your agents + the structured artifacts** form a
-> cognitive system; this audit layer is the *artifact layer* of that
-> system, not the cognition. Agents stay deterministic. Humans curate.
-> Trip-wires enforce structure. The artifacts compound. (Per Steve
-> Yegge, ["Welcome to Gas City"](https://steve-yegge.medium.com/welcome-to-gas-city-57f564bb3607)
-> — the v1.1 reframe.)
->
-> Concretely: working memory = entry files (AGENTS.md / CLAUDE.md).
-> Long-term memory = ADRs (episodic decisions) + post-mortems
-> (procedural lessons) + CHANGELOG (autobiographical timeline).
-> Autobiographical introspection = `.brain/audit-history/`. Autonomic
-> functions = pre-commit hooks + scheduled CI. Habit formation = the
-> Anthropic iterate pattern. The repo gets *richer* over time as humans
-> deposit and curate; the agents read what's there.
-
-## Invocation (the 3-phase contract)
-
-### Step 1 — Ingest
-
-| Surface prompt | Watch for | Likely actual question |
-|---|---|---|
-| "Audit my docs" | Code docs vs LLM-agent docs | "Are my agent-readable docs in good shape?" |
-| "Stale README" | One file vs whole surface | "Is my doc surface coherent?" |
-| "Set up AGENTS.md" | Greenfield vs migration | "Do I have agent-rules already, and how do I consolidate?" |
-| "Add ADRs" | Pattern vs immediate need | "Where should ADRs live and what should AGENTS.md say?" |
-| "Set up .brain folder" / "migrate to .brain" | Greenfield vs migration | "Initialize the v1.5 layout, or migrate from `docs/`?" |
-
-### Step 2 — Decompose
-
-Every audit decomposes into the same six sub-tasks:
-
-1. **Discovery** — what entry files, `.brain/`, and `docs/` folders exist?
-2. **Pointer trace** — what does each entry file reference; does that target exist?
-3. **Orphan detection** — what files exist in `.brain/` or `docs/` that are never referenced?
-4. **Staleness probe** — what content is dated and obviously stale?
-5. **Memory check** — do ADRs, postmortems, runbooks have homes (`.brain/` or legacy `docs/`)?
-6. **Synthesis** — severity-ranked gap report + proposed fixes.
-
-### Step 3 — Route
-
-| You're doing… | Go to |
-|---|---|
-| Verifying AGENTS.md format | `standards/agents-md-spec.md` |
-| Setting up CLAUDE.md as pointer / symlink | `standards/claude-md-convention.md` |
-| Cross-tool compatibility matrix | `standards/cross-tool-matrix.md` |
-| README/CONTRIBUTING/SECURITY conventions | `standards/readme-conventions.md` |
-| Writing AGENTS.md *content* well | `guidance/llm-doc-writing.md` |
-| Authoring an ADR | `doc-types/adr-pattern.md` |
-| Decision-log shape (collection of ADRs) | `doc-types/decisions-log.md` |
-| `PLAN.md` / `ROADMAP.md` shape | `doc-types/plan-roadmap.md` |
-| `CHANGELOG.md` best practices | `doc-types/changelog.md` |
-| `ARCHITECTURE.md` template | `doc-types/architecture-md.md` |
-| Postmortem template (Google SRE / Atlassian) | `doc-types/postmortem-pattern.md` |
-| Running a full audit (incl. `.brain/` migration) | `recipes/audit-existing-repo.md` |
-| Greenfield setup (`.brain/` defaults) | `recipes/greenfield-setup.md` |
-| Adding ADRs to an established repo | `recipes/adr-introduction.md` |
-| Organizing memory primitives | `recipes/memory-organization.md` |
-| **Self-healing hooks** (Promise 4) | `recipes/self-healing-hooks.md` |
-| **Continuously-learning loop** (Promise 5) | `recipes/continuous-learning-loop.md` |
-| **Findings-index readout** — close the read side of the audit ledger (Promise 5) | `recipes/findings-index-readout.md` |
-| **Skill stewardship loop** — procedural-memory analog of audit-and-iterate (Promise 5) | `recipes/skill-stewardship-loop.md` |
-| **Harvest ops-repo** — lift findings into agent memory + portable bundle | `recipes/harvest-repo-brain.md` |
-| **Import ops-repo harvest** — consume a portable bundle into this repo | `recipes/import-repo-brain-harvest.md` |
-| **Lockstep versioning** — multi-package monorepos pre-1.0 caret-lock trap (Promises 4, 5) | `audit-patterns/lockstep-versioning.md` |
-| **Archive-link sweep** — depth-aware path rewrites after cross-tree moves (Promises 1, 3) | `audit-patterns/archive-link-sweep.md` |
-| **Changelog `[Unreleased]` bloat** — periodic clear after release (Promises 1, 3) | `audit-patterns/changelog-unreleased-bloat.md` |
-| **Spec dating** — backfill missing `date:` / `_Last reviewed:_` (Promise 3) | `audit-patterns/spec-dating-sweep.md` |
-| **Browser-bundle `node:*` imports** — top-level static `import 'node:*'` in browser-reachable modules (Promises 3, 4) | `audit-patterns/browser-bundle-node-imports.md` |
-| **Context budget** (Promise 2) | `guidance/context-budget.md` |
-| **Redundancy detection** (Promise 1) | `audit-patterns/redundancy-detection.md` |
-| **Token-waste detection** (Promise 2) | `audit-patterns/token-waste-detection.md` |
-| Tooling for staleness (lychee, Vale, markdownlint, LLM-on-diff) | `audit-patterns/staleness-tooling.md` |
-| **Reliability dial** + git-sync — `.brain/config.toml` strictness AND `shared`/`local-only` mode | `guidance/reliability-dial.md` |
-| **Recommend-then-validate** — two-agent fix pattern | `recipes/recommend-then-validate.md` |
-| **Audit history ledger** — persistent queryable record | `audit-patterns/audit-history-ledger.md` |
-| **External-reference verification** — WebFetch URL probe | `recipes/external-reference-verification.md` |
-| **Concurrent learnings merge** — multi-contributor sync | `recipes/concurrent-learnings-merge.md` |
-| **Cold-start harvest** — importing existing learnings | `recipes/cold-start-harvest.md` |
-| **Prose / writing genre** — non-code domains | `genres/prose-and-writing.md` |
-
-## The five promises (and how each is delivered)
-
-The audit makes specific promises about the repo it leaves behind. Each
-promise is delivered by a concrete audit, edit, hook, or workflow — not
-by good intentions. If a promise isn't backed by a verifiable mechanism,
-it's broken.
-
-| # | Promise | What it means concretely | Delivery mechanism | Reference |
-|---|---|---|---|---|
-| 1 | **Less-wasteful** | No orphans. No drift between CLAUDE.md and AGENTS.md. No duplicate prose. Every doc has a reason to exist. | Orphan detection + redundancy detection + drift consolidation + archive-not-delete | `audit-patterns/orphan-detection.md`, `audit-patterns/redundancy-detection.md` |
-| 2 | **Token-and-context-optimized** | Agents read the minimum needed. Entry files under ~200 lines (Anthropic). Detail lives in linked subfolders. Structure lets agents pull only the slice they need. | <200-line ceiling on entry files; pointer-based navigation; layered docs (entry → ARCHITECTURE → ADRs deep); token-waste detection | `guidance/context-budget.md`, `guidance/llm-doc-writing.md`, `audit-patterns/token-waste-detection.md` |
-| 3 | **Less-prone-to-staleness** | Staleness is *visible* (frontmatter dates, "Last reviewed:" lines), *detectable* (lychee, git-mtime, LLM-on-diff), and *gated* (CI fails on broken links / stale content) | Dated frontmatter required; lychee link checks; git-mtime heuristic; LLM-on-diff PR gate | `audit-patterns/staleness-tooling.md`, `audit-patterns/stale-content.md` |
-| 4 | **Self-healing** | The repo fixes itself in CI, not in occasional human-driven audits. Drift between CLAUDE.md and AGENTS.md fails pre-commit. Broken links fail PRs. Orphans get auto-archived after a grace period. | Pre-commit hooks; GitHub Actions (weekly audit + PR-time drift check); apply-fixes mode; auto-archive workflow | `recipes/self-healing-hooks.md` |
-| 5 | **Continuously-learning indefinitely** | The *artifacts compound, not the agents.* Agents stay deterministic; humans curate; the trip-wires enforce structure. Both **declarative memory** (entry files, ADRs, postmortems, audit ledgers, findings index) and **procedural memory** (skills under `.claude/skills/`) compound — mistakes become AGENTS.md corrections, decisions become ADRs, incidents become post-mortems, recurring procedures become skills. | Anthropic iterate pattern; ADR-on-architectural-change flow; postmortem-on-incident flow; audit history ledger; findings-index readout; skill-stewardship loop with four scripts (check-skill-frontmatter, audit-skills, draft-skill, iterate-skill) | `recipes/continuous-learning-loop.md`, `recipes/findings-index-readout.md`, `recipes/skill-stewardship-loop.md`, `audit-patterns/audit-history-ledger.md` |
-
-> **The check:** every audit pass produces a gap report mapped to these
-> promises. If the repo can't pass *all five* promise-checks at the
-> chosen severity threshold, the skill flags exactly which promises
-> aren't being delivered and recommends the specific mechanism to install.
-
-## Verification — how to confirm a promise is delivered
-
-Each promise has a **trip-wire**: a concrete check that fails when the
-promise breaks. Without trip-wires, "self-healing" is just a marketing
-claim.
-
-| Promise | Trip-wire (the check that catches breakage) | Where it runs |
-|---|---|---|
-| Less-wasteful | (a) `orphan-detection` finds zero unreferenced files in `.brain/` and `docs/` (archived ones live in `.brain/archive/`). (b) MD5(CLAUDE.md) ≠ MD5(AGENTS.md) only if symlink/thin-pointer. | Pre-commit hook + weekly CI |
-| Token-optimized | `wc -l AGENTS.md CLAUDE.md` < 200 each (warn at 150). Token-waste detection across `.brain/` + `docs/` finds zero >500-line files that aren't ADRs/postmortems. | Pre-commit hook |
-| Stale-resistant | `lychee` exits clean. Every file in `.brain/` and `docs/` has a `date:` frontmatter or `_Last reviewed:_` line within 365 days. | PR CI + scheduled CI |
-| Self-healing | The hooks above are wired into `.husky/` or `.git/hooks/` AND `.github/workflows/`. Audit verifies their **presence**. A repo with no hooks is not self-healing — it just happens to be clean today. | Audit checks for hook existence |
-| Continuously-learning | (a) `.brain/adrs/` and `.brain/postmortems/` (or legacy `docs/` equivalents) exist; both have ≥1 entry from the last 90 days OR an explicit "no architectural changes / no incidents in window" note. (b) `.agents/skills/` or `.claude/skills/` exists; `audit-skills` runs clean (no errors); skill frontmatter passes `check-skill-frontmatter`. | Quarterly review + skill audit |
-
-> **The canonical model (background).** **`AGENTS.md`** is the standard
-> entry file for LLM coding agents — emerged August 2025, stewarded by
-> the **Agentic AI Foundation (AAIF) under the Linux Foundation** since
-> December 2025, adopted by 60,000+ open-source projects. `CLAUDE.md`,
-> `.cursor/rules/*.mdc`, `.windsurfrules`, `.github/copilot-instructions.md`
-> should be **thin pointers to `AGENTS.md`**.
->
-> **Important caveat.** As of April 2026 **Claude Code does not read
-> `AGENTS.md` natively** ([issue #31005](https://github.com/anthropics/claude-code/issues/31005)).
-> The two clean workarounds are: (a) symlink `ln -s AGENTS.md CLAUDE.md`,
-> or (b) keep a thin `CLAUDE.md` that says "instructions live in AGENTS.md."
-
-## What this audit produces
-
-- A **gap report** (`stale-docs-audit.md`) with severity-ranked findings:
-  missing entry files, broken pointers, orphaned docs, missing memory
-  primitives, stale content.
-- **Specific fixes**: edits to `AGENTS.md` / `CLAUDE.md` / other entry
-  files; new files to seed (`.brain/adrs/0001-*.md`, etc.); removals of
-  stale duplicates.
-- An **opinion** on memory organization: where ADRs live, where decision
-  logs live, where traces live, and how the entry file points to each.
-
-## What this audit does NOT do
-
-- Does not write feature documentation. Looks at the *meta-shape* of the
-  docs surface.
-- Does not enforce a content style guide. Match the project's voice.
-- Does not run code or modify behavior. Doc-only.
-
-## The opinionated stance
-
-1. **AGENTS.md is canonical.** One file, top-level. Spec home:
-   [agents.md](https://agents.md). Format is **deliberately light** —
-   no required fields, "just standard Markdown."
-2. **CLAUDE.md is a thin pointer or symlink.** A 3-5 line redirect, or
-   `ln -s AGENTS.md CLAUDE.md`. Same shape for `.cursor/rules/*.mdc`,
-   `.windsurfrules`, `.github/copilot-instructions.md`. Avoid maintaining
-   N divergent copies.
-3. **Entry files explicitly point to subfolders.** A naked `AGENTS.md`
-   is incomplete — it must say "for architecture decisions, read
-   `.brain/adrs/`", "for the roadmap, read `PLAN.md`", "for change
-   history, read `CHANGELOG.md`."
-4. **Memory primitives have homes.** ADRs in `.brain/adrs/` (numbered,
-   dated, status). **Postmortems in `.brain/postmortems/`** (Google SRE
-   blameless format). Runbooks in `.brain/runbooks/`. Each gets a
-   pointer from `AGENTS.md`. Greenfield repos default to `.brain/`
-   (since v1.5); existing repos with `docs/{adrs,postmortems,...}/` are
-   recognized by the audit and may migrate via
-   `recipes/audit-existing-repo.md` `Migration` section.
-5. **Every doc is dated.** YAML frontmatter `date:` or
-   `_Last reviewed: YYYY-MM-DD_`. Staleness must be visible.
-6. **Orphans are a smell.** Files in `.brain/` or `./docs/` that no
-   entry file references are either (a) missing from the index or (b)
-   abandoned and should be archived.
-7. **Keep AGENTS.md / CLAUDE.md short.** Anthropic's guidance: "under
-   ~200 lines"; instruction quality drops as count rises.
-
-## Audit categories
-
-| Category | What it checks | Reference |
-|---|---|---|
-| **Entry-file coverage** | Does `AGENTS.md` exist? Does `CLAUDE.md` point to it? Are other agent-rules files thin pointers? | `audit-patterns/entry-file-coverage.md` |
-| **Pointer integrity** | Do entry files reference real subfolders? Are intra-repo links resolving? | `audit-patterns/pointer-validation.md` |
-| **Orphan detection** | Files in `.brain/` or `./docs/` not referenced by any entry file | `audit-patterns/orphan-detection.md` |
-| **Staleness** | Dates older than threshold; references to renamed/removed code; broken intra-repo links | `audit-patterns/stale-content.md` |
-| **Memory fragmentation** | No `.brain/adrs/`; ADRs in random places; decisions mixed with code comments | `audit-patterns/memory-fragmentation.md` |
-| **Coverage gaps** | Missing canonical files (`README.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, `ARCHITECTURE.md`) | `audit-patterns/coverage-gaps.md` |
-| **Format hygiene** | Undated docs, no frontmatter, no ownership, no version info | `audit-patterns/format-hygiene.md` |
-| **Skill stewardship** | Skills (`.agents/skills/*` or `.claude/skills/*`) — frontmatter present, descriptions 60-1024 chars; six-signal audit (procedure recurrence, graduations without skills, memory citations, stale refs, churn divergence, description similarity); reference scripts: `audit-skills`, `check-skill-frontmatter`, `draft-skill`, `iterate-skill`. | `recipes/skill-stewardship-loop.md` |
-| **Lockstep versioning** | Multi-package monorepos pre-1.0: caret-lock trap (`^0.0.x` resolves to exact version); coordinated bumps + CI gate | `audit-patterns/lockstep-versioning.md` |
-| **Archive-link sweep** | After cross-tree doc moves (e.g. `docs/X.md` → `.brain/archive/Y.md`), every linker needs depth-aware path rewrite | `audit-patterns/archive-link-sweep.md` |
-| **Changelog `[Unreleased]` bloat** | After a release cut, `[Unreleased]` blocks accumulate stale promoted-content; periodic clear | `audit-patterns/changelog-unreleased-bloat.md` |
-| **Spec dating** | Specs without `date:` frontmatter or `_Last reviewed:_` line are invisible to staleness detection | `audit-patterns/spec-dating-sweep.md` |
-| **Browser-bundle `node:*` imports** | Modules reachable from browser bundles must guard `node:*` imports (top-level static imports throw via Vite's externalization stub) | `audit-patterns/browser-bundle-node-imports.md` |
-
-## Quick reference — the canonical doc surface (v1.5 layout)
-
-| Path | Purpose | Entry-file should point to it? |
-|---|---|---|
-| `AGENTS.md` | THE entry file for LLM agents | n/a — itself the entry |
-| `CLAUDE.md` | Thin pointer or `ln -s AGENTS.md` | n/a — derivative |
-| `.cursor/rules/*.mdc` | Cursor's newer rules dir | n/a — Cursor reads AGENTS.md too |
-| `.windsurfrules` | Windsurf (Cognition-owned). Reads AGENTS.md too | n/a — derivative |
-| `.github/copilot-instructions.md` | GitHub Copilot. Also reads AGENTS.md/CLAUDE.md/GEMINI.md | n/a — derivative |
-| `.aider.conf.yml` + `CONVENTIONS.md` | Aider | n/a |
-| `.continue/` rules | Continue.dev | n/a |
-| `README.md` | Human + LLM landing | YES |
-| `PLAN.md` | Active work plan (repo root) | YES if exists |
-| `ROADMAP.md` | Future-looking (repo root) | YES if exists |
-| `CHANGELOG.md` | Released change history | YES |
-| `ARCHITECTURE.md` | System overview (matklad pattern; repo root) | YES if exists |
-| `CONTRIBUTING.md` | Contributor guide | YES if exists |
-| `SECURITY.md` | Security disclosure | YES if exists |
-| `.brain/adrs/` | Numbered ADRs (the *canonical* "Architecture Decision Log") | YES |
-| `.brain/postmortems/` | Blameless incident write-ups (Google SRE / Atlassian) | YES if exists |
-| `.brain/runbooks/` | Operational procedures | YES if exists |
-| `.brain/archive/` | Superseded/abandoned docs (auto-archived after 30-day grace) | n/a |
-| `.brain/architecture/` | Diagrams + extended docs (short overview is `ARCHITECTURE.md` at root) | YES if exists |
-| `.brain/audit-history/` | JSON audit ledger (queryable, SOC2-friendly) | n/a |
-| `.brain/changesets/` | AGENTS.md changesets staging (multi-contributor; consolidated at merge) | n/a |
-| `.brain/cache/` | WebFetch cache for external-ref-verification (gitignored) | n/a |
-| `.brain/cold-start/` | Harvest-session working state (gitignored) | n/a |
-| `.brain/config.toml` | Repo-brain strictness configuration (lax/normal/strict) | n/a |
-
-> **Legacy `docs/` layout supported.** Repos pre-dating v1.5 may have
-> `docs/adrs/`, `docs/postmortems/`, `docs/runbooks/`, `docs/archive/`,
-> `docs/architecture/`. The audit recognizes both. Migration to `.brain/`
-> is opt-in via one `git mv` (recipe in `recipes/audit-existing-repo.md`
-> `Migration` section).
-
-## Invariants
-
-1. **AGENTS.md is canonical.** All other entry files are thin pointers,
-   not divergent copies.
-2. **Entry files explicitly point to subfolders.** A naked AGENTS.md is
-   incomplete.
-3. **Every doc is dated.** Frontmatter `date:` or `_Last reviewed:_` line.
-4. **Memory primitives have homes (v1.5 layout).** ADRs in `.brain/adrs/`,
-   postmortems in `.brain/postmortems/`, runbooks in `.brain/runbooks/`,
-   archive in `.brain/archive/`. Audit recognizes legacy
-   `docs/{adrs,postmortems,...}/` and nudges toward migration.
-5. **Orphans are findings, not noise.** Every orphan gets a recommendation.
-6. **No destructive deletion without confirmation.** The audit recommends;
-   the user decides.
-7. **Cross-tool compatibility over single-tool optimization.**
-8. **Procedural memory is co-equal with declarative.** Skills under
-   `.agents/skills/` (or `.claude/skills/` where `.agents/` is not
-   present) are part of the brain — audited, dated, frontmatter-checked.
-   `audit-skills` runs alongside the doc audit; `iterate-skill --update`
-   is the procedural analog of intra-repo link rewrites.
-9. **Flow operations are conversational, not commands.** "Harvest
-   ops-repo" / "import ops-repo harvest" invoke the bridge recipes;
-   never become standalone skills (they compose primitives this skill
-   already owns).

package/skills/adia-ui-ops/references/audit-patterns/archive-link-sweep.md

@@ -1,96 +0,0 @@
-# Archive-link sweep (per-file relative-path rewrites)
-
-**Added:** 2026-05-02 after the lockstep cut's plan archival surfaced
-5 broken intra-repo links — each with a different relative-path
-depth.
-
-## The drift class
-
-When a doc moves via `git mv` from one tree location to another
-(typically `docs/plans/X.md` → `.brain/archive/YYYY-Q/PLAN-X.md`),
-intra-repo links from other files break. **Each linking file has a
-*different* relative-path depth** — sed alone can't fix them in one
-pass.
-
-Example drift surface (from the 2026-05-02 plan archival):
-
-| Linking file | Old → new |
-|---|---|
-| `CHANGELOG.md` (root) | `./docs/plans/X.md` → `./.brain/archive/YYYY-Q/PLAN-X.md` |
-| `ROADMAP.md` (root) | same |
-| `docs/conventions/Y.md` | `../plans/X.md` → `../../.brain/archive/YYYY-Q/PLAN-X.md` |
-| `docs/journal/YYYY/MM/Z.md` | `../../../plans/X.md` → `../../../../.brain/archive/YYYY-Q/PLAN-X.md` |
-| `packages/<pkg>/CHANGELOG.md` | `../../../docs/plans/X.md` → `../../../.brain/archive/YYYY-Q/PLAN-X.md` |
-
-5 files, 4 different relative-path patterns. A `sed -i 's|docs/plans/X|.brain/archive/Y/PLAN-X|g'` doesn't work — the prefix segments differ.
-
-## Detection
-
-```bash
-node scripts/check-links.mjs --all 2>&1 | head -20
-```
-
-Look for "resolves to: <path> (not found)" entries.
-
-## Fix recipe (Python with explicit per-file tuples)
-
-```python
-import pathlib
-
-ROOT = pathlib.Path("/path/to/repo")
-
-# Each tuple: (linking_file, old_fragment, new_fragment)
-EDITS = [
-    (ROOT / "CHANGELOG.md",
-     "./docs/plans/X.md",
-     "./.brain/archive/2026-Q2/PLAN-X.md"),
-    (ROOT / "ROADMAP.md",
-     "./docs/plans/X.md",
-     "./.brain/archive/2026-Q2/PLAN-X.md"),
-    (ROOT / "docs/conventions/Y.md",
-     "../plans/X.md",
-     "../../.brain/archive/2026-Q2/PLAN-X.md"),
-    (ROOT / "docs/journal/2026/05/Z.md",
-     "../../../plans/X.md",
-     "../../../../.brain/archive/2026-Q2/PLAN-X.md"),
-    (ROOT / "packages/foo/CHANGELOG.md",
-     "../../../docs/plans/X.md",
-     "../../../.brain/archive/2026-Q2/PLAN-X.md"),
-]
-
-for path, old, new in EDITS:
-    text = path.read_text()
-    if old in text:
-        path.write_text(text.replace(old, new))
-        print(f"  ✓ {path.relative_to(ROOT)}")
-    else:
-        print(f"  ✗ {path.relative_to(ROOT)} — old fragment not found")
-```
-
-After running, verify:
-
-```bash
-node scripts/check-links.mjs --all
-```
-
-Expected: zero broken intra-repo links.
-
-## Prevention
-
-This is mechanical drift — there's no preventing it without making
-all references absolute. Two practical mitigations:
-
-1. **Pre-commit hook** runs `check-links.mjs` on every staged
-   markdown change. The hook would catch the move + link rot in the
-   same commit.
-2. **The `stale-audit` skill** includes this check as part of its
-   7-check post-release sweep.
-
-## Related
-
-- See [`feedback_relative_path_after_archive.md`](`~/.claude/projects/<repo>/memory/`) — the user-memory entry capturing the lesson.
-- Sibling concern to `feedback_directory_rename_outbound_refs` (which
-  is about renames, not archive moves) and `feedback_git_mv_audit_imports`
-  (which is about code imports inside moved files, not links from
-  elsewhere TO the moved file).
-- `stale-audit` skill check #4.

package/skills/adia-ui-ops/references/audit-patterns/audit-history-ledger.md

@@ -1,162 +0,0 @@
----
-date: 2026-04-27
-coverage: canonical
-peers:
-  - ../recipes/self-healing-hooks.md
-  - ../recipes/continuous-learning-loop.md
-  - ../recipes/recommend-then-validate.md
-  - ../guidance/reliability-dial.md
-primary_sources:
-  - Steve Yegge, "Welcome to Gas City" — versioned action ledger pattern
-  - https://www.dolthub.com/ — Dolt git-versioned database (Yegge's reference implementation)
-status: research-verified
----
-
-# Audit history ledger (the persistent record of every fix)
-
-> _"Every agent action recorded in both a database and version history… Your SOC2 story, sitting right there in the database, already written."_
-> — Steve Yegge, "Welcome to Gas City"
-
-## What this delivers
-
-Every audit run produces a queryable, versioned artifact. The repo *itself* becomes its own audit log of how it was fixed over time. This compounds **Promise 5 (continuously-learning)** — the artifacts that accumulate aren't just ADRs and post-mortems, but also a structured record of how the doc surface evolved.
-
-Falls out as a free benefit: SOC2 / compliance / "show me what changed in the last quarter" queries become trivial.
-
-## The ledger structure
-
-```
-.brain/
-├── audit-history/
-│   ├── 2026-04-27.json
-│   ├── 2026-05-04.json
-│   ├── 2026-05-11.json
-│   └── ...
-├── README.md           # generated index, sorted newest-first
-└── trends.md           # quarterly summary (optional)
-```
-
-One file per audit run, named `YYYY-MM-DD.json` (or `YYYY-MM-DD-HHMM.json` if multiple per day). **Append-only — never modified after the run completes** (immutable, like ADRs and post-mortems).
-
-## The schema
-
-```json
-{
-  "$schema": "https://ops-repo.dev/schemas/audit-history.v1.json",
-  "audit_id": "2026-04-27T13:42:00Z",
-  "repo": "github.com/example/example",
-  "commit": "abc123def456",
-  "strictness": "normal",
-  "skill_version": "1.1.0",
-  "promises_evaluated": [1, 2, 3, 4, 5],
-  "findings": [
-    {
-      "id": "DRIFT-CLAUDE-AGENTS",
-      "promise": 1,
-      "severity": "critical",
-      "category": "redundancy",
-      "file": "CLAUDE.md",
-      "message": "CLAUDE.md (240 lines) and AGENTS.md (180 lines) have substantively divergent content."
-    },
-    {
-      "id": "STALE-2026-04-15",
-      "promise": 3,
-      "severity": "medium",
-      "category": "staleness",
-      "file": "docs/old-plan.md",
-      "message": "Last modified 2024-09-12 (583 days ago); no '_Last reviewed:_' line."
-    }
-  ],
-  "fixes_proposed": 12,
-  "fixes_applied": 8,
-  "fixes_vetoed": 4,
-  "veto_reasons": [
-    {"fix_id": "delete-orphan-1", "rule": "delete-always-vetoed"},
-    {"fix_id": "edit-agents-md", "rule": "would-exceed-200-lines"}
-  ],
-  "trip_wires": {
-    "lychee": "pass",
-    "entry_file_length": "pass",
-    "agents_claude_drift": "fail",
-    "doc_dates": "pass",
-    "orphan_count": 4
-  }
-}
-```
-
-The schema is intentionally simple — no nested objects beyond two levels, no free-text bodies. The whole file should fit in <2KB for a typical run.
-
-## Why JSON, not Markdown
-
-- **Queryable.** `jq '.findings[] | select(.severity=="critical")' audit-history/*.json` answers compliance questions in seconds.
-- **Diff-friendly.** Git diff highlights actual content changes, not prose reflow.
-- **Schema-validatable.** The `$schema` URL anchors the format; CI can reject malformed entries.
-- **Token-cheap.** A structured record consumes a fraction of the tokens Markdown narration would.
-
-For human readers, the generated `audit-history/README.md` summarizes:
-
-```markdown
-# Audit history
-
-| Date | Strictness | Findings | Critical | Fixes applied |
-|---|---|---|---|---|
-| [2026-05-11](2026-05-11.json) | normal | 8 | 0 | 4 |
-| [2026-05-04](2026-05-04.json) | normal | 11 | 1 | 6 |
-| [2026-04-27](2026-04-27.json) | normal | 23 | 2 | 8 |
-
-_Trend: critical findings down 100% over 14 days. Total findings down 65%._
-```
-
-Generated weekly by the scheduled CI workflow.
-
-## How it integrates with the other promises
-
-| Promise | What the ledger adds |
-|---|---|
-| 1. Less-wasteful | Trend data shows whether redundancy is increasing or decreasing |
-| 2. Token-optimized | Tracks entry-file line counts over time |
-| 3. Less-stale | Tracks % of docs with valid `date:` frontmatter over time |
-| 4. Self-healing | Records which trip-wires fired and which hooks caught them |
-| 5. Continuously-learning | The ledger *is* part of the institutional memory; not just curated artifacts but the operational record |
-
-## Privacy considerations
-
-Some teams will not want every audit run committed to a public repo:
-
-- **Public repos:** Either commit the ledger (most useful) or `.gitignore` it (preserves history locally only).
-- **Private repos:** Always commit; this is where compliance value compounds.
-- **Sensitive findings:** Never put PII or secrets in audit messages. The schema's `message` field should describe categories, not content (✅ "broken link in marketing copy"; ❌ "broken link to https://internal.example.com/finance/q4-revenue.pdf").
-
-The audit emits warnings if any finding message contains URL fragments matching common secret patterns (API keys, tokens, internal hostnames).
-
-## Closing the read side — `.brain/findings/INDEX.md`
-
-The ledger is *write-rich, read-poor*. Every audit emits structured findings, but nothing surfaces them — a future session would have to `cat` every JSON to know what's still open. The read-side closure is a generated `.brain/findings/INDEX.md` that folds every `findings[]` entry across the ledger into one sortable view, plus a hand-curated `## Graduations` table tracking finding-to-permanent-infrastructure pairs.
-
-Recipe: [`../recipes/findings-index-readout.md`](../recipes/findings-index-readout.md). Wire it into the same harvest cron that writes the ledger; the index regenerates on every run, the ledger stays append-only.
-
-This is the load-bearing closure for *capture-without-action* drift — an audit ledger that nobody reads might as well not exist.
-
-## Compliance / SOC2 framing (the free benefit)
-
-Auditors increasingly ask:
-- "Show me changes to documented procedures."
-- "Demonstrate the last review of [X]."
-- "Provide a record of how doc-quality issues were detected and resolved."
-
-The audit history ledger answers all three trivially. It's not a *replacement* for compliance docs, but it materially reduces the "gather evidence" cost.
-
-## Anti-patterns
-
-- **Manually editing past audit-history files.** Defeats the immutability invariant. Like editing accepted ADRs.
-- **Letting the ledger grow without index/trend files.** A flat folder of 200 JSON files is unreadable. The README.md and trends.md surface what's worth seeing.
-- **Storing findings *content* (the actual broken link, the actual stale text)** rather than findings *categories*. Privacy hazard.
-- **Including the ledger in token budget calculations.** It's not loaded by agents in normal sessions; it's an out-of-band artifact.
-- **Running the audit so often the ledger fills with noise** — once-weekly is the sweet spot for most repos. Daily is overkill outside high-velocity production.
-
-## Cross-references
-
-- Self-healing hooks (where the audit runs): `../recipes/self-healing-hooks.md`
-- Continuously-learning loop (the broader context): `../recipes/continuous-learning-loop.md`
-- Recommend-then-validate (which writes vetoes into the ledger): `../recipes/recommend-then-validate.md`
-- Reliability dial (recorded with each audit run): `../guidance/reliability-dial.md`