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

package/skills/adia-ui-ops/references/genres/prose-and-writing.md

@@ -1,149 +0,0 @@
----
-date: 2026-04-27
-coverage: extended
-peers:
-  - ../recipes/greenfield-setup.md
-  - ../recipes/memory-organization.md
-  - ../doc-types/adr-pattern.md
-  - ../doc-types/postmortem-pattern.md
-primary_sources:
-  - https://diataxis.fr/
-  - https://www.amwa.org/page/style_guides
-  - https://en.wikipedia.org/wiki/Series_bible
-  - https://github.com/errata-ai/vale
-status: research-verified
----
-
-# Genre: prose and writing
-
-> **Premise.** ops-repo was designed for code repositories, but five of the six promises (less-wasteful, token-and-context-optimized, less-prone-to-staleness, self-healing partial, continuously-learning) translate cleanly to prose, fiction, journalism, and documentation projects. The skill works — with a vocabulary swap and one fewer trip-wire.
-
-_Last reviewed: 2026-04-27_
-
-## Where it fits
-
-| Genre | Fit | Why |
-|---|---|---|
-| Technical documentation | Excellent | Drift-vs-code is the same concern; ADRs map 1:1 to documentation decisions |
-| Long-form non-fiction (book) | Excellent | Voice EDRs, source-of-fact registries, revision retrospectives all matter |
-| Long-form fiction (novel/series) | Excellent | "Series bible" is exactly the brain metaphor; EDRs become world-building decisions |
-| Academic / research writing | Strong | Citation-stale (papers retracted, replaced) is the same as live-link-stale-content |
-| Journalism / essays | Partial | Revision retrospectives become "what I'd revise"; EDRs less natural for one-off pieces |
-| Screenplay / playwriting | Partial | Character-bible decisions are EDR-shaped; but writers' rooms don't usually want the process ceremony |
-| Marketing / SEO copy | Low | Optimization is dominated by A/B testing; not a docs problem |
-| Poetry | Poor | Wrong tool. Voice is not decomposable into decision records. |
-
-## Vocabulary translation
-
-| ops-repo (code) | Prose equivalent |
-|---|---|
-| `AGENTS.md` | `STYLE.md` or `VOICE.md` (the canonical style/voice guide) |
-| ADR (Architecture Decision Record) | EDR (Editorial Decision Record) — voice/POV/structure decisions |
-| Postmortem | Revision retrospective — "what broke in this draft" |
-| Runbook | Process ritual — "how I plan a chapter," "submission checklist" |
-| Architecture overview | Series bible / world bible (fiction) or content map (docs) |
-| Trip-wire | Editorial gate (e.g., "no draft published without sensitivity check") |
-| Audit | Manuscript health check |
-| Browserslist baseline | House-style baseline (AP, Chicago, NYT, brand-specific) |
-
-## Folder layout (prose adaptation)
-
-```
-.brain/
-├── config.toml
-├── edrs/                  # editorial decision records (was adrs/)
-│   ├── 0001-pov-third-limited.md
-│   ├── 0002-no-second-person.md
-│   └── 0003-style-guide-AP-not-Chicago.md
-├── retrospectives/        # was postmortems/
-│   ├── draft-1-feedback-synthesis.md
-│   └── reader-survey-q1.md
-├── rituals/               # was runbooks/
-│   ├── chapter-planning.md
-│   └── pre-submission-checklist.md
-├── bible/                 # was architecture/
-│   ├── characters.md
-│   ├── world.md
-│   └── timeline.md
-├── archive/               # superseded EDRs, abandoned drafts (not deleted)
-└── audit-history/         # manuscript-health JSON ledgers
-```
-
-The dotfile prefix is *more* useful for prose than for code: drafts live at the repo root or in `chapters/` / `posts/`, and `.brain/` is structurally clearly the "out of band" memory layer that humans curate but don't read every day.
-
-## Promise-by-promise applicability
-
-| Promise | Applies to prose? | How |
-|---|---|---|
-| 1. Less-wasteful | Yes | Style-guide drift detection (one canonical, no duplicated style rules across files) |
-| 2. Token-and-context-optimized | Yes | Prose has the same agent-context-window problem; STYLE.md ≤200 lines |
-| 3. Less-prone-to-staleness | Yes | Citation rot, character-name conflicts across drafts, world-bible vs current-draft drift |
-| 4. Self-healing | Partial | Pre-commit hooks for spelling/style work (Vale, markdownlint); but most prose tooling is editor-internal not git-hook-internal |
-| 5. Continuously-learning | Yes | Voice/POV decisions accumulate; series spans years; humans curate the editorial log |
-| Reliability dial | Yes | A novelist working alone uses `lax`; a magazine staff with multiple writers uses `strict` |
-
-## What translates as-is
-
-- `../standards/agents-md-spec.md` — replace `AGENTS.md` → `STYLE.md`; the 8-section skeleton works (Project overview = book/series overview, Build/test/run = build commands for the manuscript build, Conventions = style rules, etc.)
-- `../audit-patterns/orphan-detection.md` — orphan files in `.brain/` not reachable from STYLE.md
-- `../audit-patterns/redundancy-detection.md` — same style rule repeated in two files
-- `../audit-patterns/format-hygiene.md` — every EDR has a date and status
-- `../audit-patterns/staleness-tooling.md` — Vale, lychee work for prose too (Vale is *primarily* a prose tool)
-- `../audit-patterns/token-waste-detection.md` — STYLE.md bloat is the same problem
-- `../recipes/self-healing-hooks.md` — Vale + spell + style-rule hooks instead of code linters
-- `../recipes/audit-existing-repo.md` — survey an existing manuscript repo
-- `../recipes/cold-start-harvest.md` — same procedure for an old manuscript with style notes scattered everywhere
-- `../guidance/context-budget.md` — same math; agent context is finite
-- `../guidance/reliability-dial.md` — strictness picker
-
-## What needs translation
-
-- `../doc-types/adr-pattern.md` → EDR pattern. Change the `## Status` allowed values to `Drafted | Adopted | Superseded | Abandoned`. Keep the Y-statement / MADR templates.
-- `../doc-types/postmortem-pattern.md` → revision retrospective. Replace "incident timeline" with "draft timeline"; keep "blameless" and "what we'd do differently."
-- `../doc-types/architecture-md.md` → series bible. matklad's pattern translates: "what is where in this story-world."
-- `../doc-types/decisions-log.md` → editorial decision log.
-
-## What doesn't apply
-
-- `../standards/cross-tool-matrix.md` — Cursor/Codex/Devin don't have prose equivalents. Use Claude/ChatGPT/Cursor-for-prose; one entry file (STYLE.md) plus one tool-specific pointer is enough.
-- `../audit-patterns/entry-file-coverage.md` — partial. Fewer entry-file conventions in prose; just STYLE.md.
-- `../audit-patterns/memory-fragmentation.md` — partial. Less likely to fragment when one author works alone.
-
-## When NOT to use ops-repo for prose
-
-- Single short essay or a one-week project. Overhead exceeds benefit.
-- Pure ideation / brainstorming. Premature structuring kills exploration.
-- Marketing copy where the "right answer" comes from A/B tests, not editorial decisions.
-- Poetry. Voice is not decomposable into decision records.
-
-## Examples in the wild
-
-- **Fiction series bibles** — Brandon Sanderson's wikis, the WGA "showrunner bible" pattern — these are exactly `architecture-md.md` content, just predating the convention.
-- **House style guides** — Chicago, AP, NYT, The Economist — these are STYLE.md / EDR collections.
-- **Diátaxis / Divio documentation framework** — already practices most of ops-repo's promises; this skill names what's already happening in well-run docs orgs.
-
-## Greenfield prose setup (analogue of `recipes/greenfield-setup.md`)
-
-Drop these files at the repo root of a manuscript or docs repo:
-
-```
-STYLE.md                                       # canonical style/voice guide (≤200 lines)
-.brain/
-├── config.toml
-├── edrs/0001-record-editorial-decisions.md   # bootstrap EDR
-├── retrospectives/.gitkeep
-├── rituals/.gitkeep
-├── bible/.gitkeep
-└── archive/.gitkeep
-.github/pull_request_template.md               # "Editorial impact" checkbox
-```
-
-The 5 promises ship from day one. EDR 0001 records the decision to use EDRs, exactly mirroring ADR 0001 in the code-greenfield recipe.
-
-## Cross-references
-
-- AGENTS.md spec (the analogue of STYLE.md): `../standards/agents-md-spec.md`
-- Greenfield setup (procedural): `../recipes/greenfield-setup.md`
-- Memory organization (folder layout rationale): `../recipes/memory-organization.md`
-- ADR pattern (the EDR template): `../doc-types/adr-pattern.md`
-- Reliability dial: `../guidance/reliability-dial.md`

package/skills/adia-ui-ops/references/guidance/context-budget.md

@@ -1,137 +0,0 @@
----
-date: 2026-04-27
-coverage: canonical
-peers:
-  - llm-doc-writing.md
-  - ../audit-patterns/token-waste-detection.md
-  - ../standards/agents-md-spec.md
-primary_sources:
-  - https://code.claude.com/docs/en/best-practices — Anthropic's CLAUDE.md guidance
-  - https://docs.anthropic.com/en/docs/about-claude/models — Claude model context windows
-  - https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/
-status: research-verified
----
-
-# Context budget (delivers Promise 2)
-
-> **The premise.** Every token in AGENTS.md / CLAUDE.md / loaded docs is a token *not* available for the actual code being worked on. "Token-and-context-optimized" means treating the agent's context window as a budget — and refusing to spend it on prose that could be a link.
-
-## The math
-
-Claude model context windows (April 2026):
-
-| Model | Context window |
-|---|---|
-| Claude Opus 4.7 | **1M tokens** (1,000,000) |
-| Claude Sonnet 4.6 | 200K tokens |
-| Claude Haiku 4.5 | 200K tokens |
-
-That sounds like a lot. It isn't — once you load:
-
-- AGENTS.md / CLAUDE.md (load every session — Anthropic loads CLAUDE.md automatically)
-- The files the agent is editing (often 3-10 files, 200-2000 lines each)
-- The files the agent is *reading* to make decisions (10-50 files easily)
-- Tool-call results (test output, lint errors, build logs)
-- The conversation transcript itself (can grow to 30K+ tokens in long sessions)
-
-A naked 800-line AGENTS.md costs **~10K tokens** — 5% of Sonnet's window, just for the entry file. If `ARCHITECTURE.md` is 1500 lines and gets loaded too, that's another 18K. Now you've spent 14% of the window on metadata before doing any work.
-
-The Opus 4.7 1M window changes the math but not the principle. **Token economy is good engineering regardless of window size** — bigger window means tokens are cheaper, not free.
-
-## Anthropic's load-bearing rule
-
-> Keep CLAUDE.md under ~200 lines. Instruction quality decreases as count increases.
->
-> — [Anthropic Claude Code best practices](https://code.claude.com/docs/en/best-practices)
-
-The **same ergonomic ceiling applies to AGENTS.md.** This isn't an arbitrary number — it's where empirical observation says adherence drops. Long files are skimmed, ignored, or contradicted by their own later sections.
-
-GitHub's [analysis of 2,500+ AGENTS.md files](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/) confirms this — the most-effective files cluster around 50-150 lines.
-
-## Layered docs (the navigability principle)
-
-The ceiling forces a structural choice: **detail goes into linked subfolders, not into the entry file**.
-
-```
-AGENTS.md  (~150 lines: agent persona, build/test/run, conventions, trust
-            boundaries, where-to-find-things, memory primitives)
-   ↓ links to
-ARCHITECTURE.md  (~500 lines: system overview, component map,
-                  data-flow diagrams, deployment topology)
-   ↓ links to
-.brain/adrs/0001-*.md  (each ADR ~100 lines: one decision in depth)
-.brain/postmortems/2026-04-*.md  (each ~150 lines: one incident)
-.brain/runbooks/*.md  (each ~100 lines: one procedure)
-```
-
-The agent loads AGENTS.md every session (~150 lines, ~2K tokens). It loads ARCHITECTURE.md *only when needed* (~7K tokens). It loads a specific ADR *only when about to make a related decision* (~1K tokens).
-
-**Total cost in the common case: 2K tokens. Total cost when deeply needed: ~10K tokens.** Compare to a flat 800-line AGENTS.md (10K every session, even when not relevant).
-
-## The budget breakdown for a healthy repo
-
-A target shape:
-
-| Surface | Line ceiling | Token cost (approx) | When loaded |
-|---|---|---|---|
-| AGENTS.md | 200 | 2-3K | Every session |
-| CLAUDE.md | 15 (thin pointer or symlink) | 0-200 | Every session (Claude Code) |
-| README.md | 200-300 | 3-5K | Sometimes (human-facing) |
-| ARCHITECTURE.md | 500 | 6-8K | When agent needs system overview |
-| .brain/PLAN.md | 200 | 2-3K | When agent needs current priorities |
-| .brain/adrs/<one>.md | 100-200 | 1-3K each | When agent makes architectural decisions |
-| .brain/postmortems/<one>.md | 100-200 | 1-3K each | When agent debugs production issues |
-| .brain/runbooks/<one>.md | 100-200 | 1-3K each | When agent runs operational procedures |
-| `CHANGELOG.md` | (any) | varies | When agent needs version history |
-
-The rule of thumb: **anything an agent needs *every session* must be tiny; everything else can be large but must be reachable on demand**.
-
-## What violates the budget (the trip-wires)
-
-The token-waste-detection audit (Promise 2) flags these specifically:
-
-1. **AGENTS.md or CLAUDE.md > 200 lines** — hard cap.
-2. **AGENTS.md or CLAUDE.md > 150 lines** — warning (approaching cap).
-3. **A `.brain/` file > 500 lines that isn't in `.brain/adrs/`, `.brain/postmortems/`, or `.brain/architecture/`** — likely a place where one big doc should be a folder of smaller ones.
-4. **Repeated content** — the same command listed in AGENTS.md, README.md, AND CONTRIBUTING.md. Pick one canonical, link from the others.
-5. **Verbose prose where bullets would work** — 8 paragraphs explaining what could be a 3-bullet checklist.
-6. **Generated content checked in** — TypeDoc / JSDoc / API reference generated docs that should be regenerated, not committed.
-
-## What does NOT violate the budget
-
-- **Long ADRs** — an ADR should be as long as the decision warrants. Some are 30 lines; some are 300. Don't compress for compression's sake.
-- **Long post-mortems** — same: an incident with a complex root cause needs depth.
-- **CHANGELOG.md** — append-only history, expected to grow without bound. Agents rarely load all of it.
-- **Long ARCHITECTURE.md** — within reason; if it gets >1500 lines, split into `.brain/architecture/`.
-
-## How to reduce a bloated AGENTS.md (the recipe)
-
-Bloated AGENTS.md is the most common failure. Recipe to compress:
-
-1. **Strip "we use TypeScript" lines.** If `tsconfig.json` is present, the agent already knows.
-2. **Strip personal preferences.** Move to `CLAUDE.local.md` (gitignored) or `~/.claude/CLAUDE.md` (user-global).
-3. **Strip TODOs / WIP notes.** Move to `.brain/PLAN.md` and link.
-4. **Strip long history / motivation.** Move to `README.md` or `ARCHITECTURE.md`.
-5. **Compress prose to bullets.** "Run tests with Vitest, our preferred test runner" → "Tests: Vitest".
-6. **Replace inline detail with a link.** "Our deployment uses Cloud Run with the following 14 steps..." → "Deployment: see `.brain/runbooks/deploy.md`".
-7. **Audit for self-contradictions.** A file that contradicts itself is worse than incomplete.
-8. **Re-read the file as if you were the agent.** Anything that doesn't change behavior gets cut.
-
-A 600-line AGENTS.md typically reduces to 120-150 lines without losing instructional value.
-
-## The Anthropic feedback loop applied to context budget
-
-When AGENTS.md grows past 200 lines, two patterns work:
-
-**Pattern A — extract to a linked file.** A "Conventions" section growing past 30 lines becomes `.brain/CONVENTIONS.md` linked from AGENTS.md. The link is permanent; the file can grow.
-
-**Pattern B — ask Claude to compress.** "AGENTS.md is 280 lines. Compress to 180 while preserving all instructional content. Move detail to linked subfolders if needed." This is the inverse of the iterate-pattern: instead of *adding* corrections, *delete* what no longer earns its tokens.
-
-Run pattern B quarterly. The audit can prompt this with a finding: `WARN: AGENTS.md is 240 lines. Run quarterly compression pass.`
-
-## Cross-references
-
-- LLM-doc-writing (companion guidance on content quality): `llm-doc-writing.md`
-- Token-waste detection (the audit pattern that catches violations): `../audit-patterns/token-waste-detection.md`
-- AGENTS.md spec: `../standards/agents-md-spec.md`
-- Self-healing hooks (the pre-commit length check): `../recipes/self-healing-hooks.md`

package/skills/adia-ui-ops/references/guidance/llm-doc-writing.md

@@ -1,116 +0,0 @@
----
-date: 2026-04-27
-coverage: extended
-peers:
-  - ../standards/agents-md-spec.md
-  - ../standards/claude-md-convention.md
-primary_sources:
-  - https://code.claude.com/docs/en/best-practices — Anthropic Claude Code best practices
-  - https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/ — empirical study of 2,500+ AGENTS.md files
-  - https://www.humanlayer.dev/blog/writing-a-good-claude-md
-status: research-verified
----
-
-# Writing AGENTS.md / CLAUDE.md content well
-
-> **The empirical case for short, specific, navigable.** Not a style guide — a set of load-bearing constraints distilled from Anthropic's own best practices and GitHub's analysis of 2,500+ AGENTS.md files in the wild.
-
-## Length
-
-**Anthropic's own guidance for CLAUDE.md is "under ~200 lines."** The same ergonomic ceiling applies to AGENTS.md — instruction quality drops as count rises. Long files are skimmed, ignored, or contradicted by their own later sections.
-
-If you have more than 200 lines of relevant content, push detail into linked subfolders (`ARCHITECTURE.md`, `.brain/adrs/`, `.brain/runbooks/`). The entry file should *navigate to* depth, not *contain* depth.
-
-## What to include (per GitHub's 2,500-repo study)
-
-The most-effective AGENTS.md files share these sections:
-
-1. **Project overview** — one paragraph, what + who + why.
-2. **Build / test / run commands** — exact shell commands, no prose. Wrong commands are worse than missing commands.
-3. **Coding conventions** — short bullets. Style, types, formatting.
-4. **Trust boundaries** — what to modify, what not to. Critical for preventing destructive edits.
-5. **Where to find things** — pointers to subfolders. The skill's load-bearing recommendation.
-6. **Memory primitives** — when to read ADRs, when to check post-mortems.
-
-Sections that don't help LLM agents (move elsewhere):
-
-- Long history / motivation / vision (move to `README.md` or `ARCHITECTURE.md`).
-- Detailed architecture diagrams (move to `ARCHITECTURE.md`; reference from AGENTS.md).
-- Personal preferences (move to `CLAUDE.local.md` or `~/.claude/CLAUDE.md`, gitignored).
-
-## What to delete
-
-Per Anthropic's best-practices doc and HumanLayer's writeup:
-
-- **Delete instructions Claude already follows correctly without being told.** "Use TypeScript" in a TS-only repo is noise.
-- **Delete instructions that contradict each other.** Diff your own AGENTS.md for self-contradictions.
-- **Delete TODOs, comments, work-in-progress notes.** Use `.brain/PLAN.md` instead.
-- **Delete commands that fail.** A wrong `npm test` is worse than no `npm test`.
-
-## Iteration pattern
-
-Anthropic recommends treating AGENTS.md as **live, not frozen**: when the agent makes a mistake, ask it to add a correction to AGENTS.md itself. Over a few weeks the file converges on what's load-bearing.
-
-Don't write AGENTS.md from scratch in one session — author the skeleton, then iterate by **deleting** as Claude proves it doesn't need a given line.
-
-## Hooks > advisory text (where possible)
-
-Per Anthropic: prefer **hooks** for deterministic behavior, not AGENTS.md text. A hook always executes; advisory text is suggestion.
-
-Examples:
-- "Run `pnpm typecheck` before committing" → write a `pre-commit` hook in `.husky/pre-commit`.
-- "Don't edit `db/migrations/`" → enforce via CODEOWNERS or branch protection, not AGENTS.md prose.
-
-AGENTS.md should explain *why* and reference the hook; the hook does the work.
-
-## The "agent persona + boundaries + commands" pattern
-
-GitHub's empirical study found this three-part shape works well:
-
-```markdown
-# AGENTS.md
-
-## You are
-A senior Rust engineer working on a high-throughput web service.
-Prioritize correctness over cleverness.
-
-## Boundaries
-- DO NOT: modify `migrations/`, generated code under `gen/`, `Cargo.lock`
-- DO: write tests for every public function; run `cargo fmt` and `cargo clippy` before committing
-- ASK: before changing anything in `crates/core/`
-
-## Commands
-build:  `cargo build --release`
-test:   `cargo test --workspace`
-lint:   `cargo clippy --all-targets -- -D warnings`
-fmt:    `cargo fmt --all -- --check`
-run:    `cargo run --bin server`
-
-## Where to find things
-- Architecture overview: `ARCHITECTURE.md`
-- ADRs: `.brain/adrs/`
-- Postmortems: `.brain/postmortems/`
-- Runbooks: `.brain/runbooks/`
-- Active plan: `.brain/PLAN.md`
-
-_Last reviewed: 2026-04-27_
-```
-
-50-60 lines. Sufficient for most repos.
-
-## Anti-patterns (what shows up in stale AGENTS.md / CLAUDE.md)
-
-1. **The 800-line dump.** Nobody reads it; the agent doesn't either.
-2. **The "we use TypeScript" file.** Noise — it's already in `tsconfig.json`.
-3. **Stale build commands.** Repo migrated to pnpm a year ago; AGENTS.md still says `npm`. The audit catches this by comparing to the lockfile.
-4. **The duplicated CLAUDE.md.** AGENTS.md and CLAUDE.md both fat, drifted apart.
-5. **No "Where to find things."** Naked entry; agent has nothing to navigate to.
-6. **Personal preferences in the committed file.** "I like 2-space indents" → move to `CLAUDE.local.md` (gitignored).
-7. **TODOs that never got done.** "// TODO: document the auth flow" sitting in AGENTS.md for a year.
-
-## Cross-references
-
-- AGENTS.md spec: `../standards/agents-md-spec.md`
-- CLAUDE.md as thin pointer / symlink: `../standards/claude-md-convention.md`
-- Audit checks: `../audit-patterns/entry-file-coverage.md`
-- Staleness detection tooling: `../audit-patterns/staleness-tooling.md`

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

@@ -1,186 +0,0 @@
----
-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`