@nurix/etna 0.19.65 → 0.19.67

package/data/harnesses/apollo/skills/documentation/templates/memory-main.md

@@ -1,25 +0,0 @@
-# Scaffold: docs/memory/main.md
-
-Baseline scaffold — created if missing (the `maintenance` agent's baseline calls this). Target file: `docs/memory/main.md`.
-
-```
----
-type: project-memory
-owner: main-agent
-description: Project-wide patterns and conventions confirmed in this codebase. Project facts only — user-centric facts go in ~/.claude/.
----
-
-# Main Agent — Project Memory
-
-Append entries below, oldest at bottom. Format:
-
-## YYYY-MM-DD — {topic}
-
-{1-3 line fact, with file paths or references where relevant}
-
----
-
-## {today} — Baseline
-
-Memory file initialized during documentation baseline (structure v{harness-version} — read from `.claude/harness.json` / `docs/structure.md` frontmatter; never hardcode a literal version).
-```

package/data/harnesses/apollo/skills/documentation/templates/migration-runbook.md

@@ -1,34 +0,0 @@
-# Migration Runbook (docs/history/migrations/YYYY-MM-DD-{slug}.md)
-
-Record. Use for: a **one-shot** migration, upgrade, or data operation — authored before execution, executed once, then outcome-stamped and frozen. Supporting scripts live beside it in a same-named folder when needed (`YYYY-MM-DD-{slug}/`).
-
-Required: **Goal**, **Steps**, **Verification**, and — after execution — the **Outcome** stamp. Optional: Preconditions, Rollback.
-
-```
-# Migration: {Title}
-
-**Goal:** What this migration accomplishes and why it runs now, one or two lines.
-**Executes against:** {environment / database / system}
-
-## Preconditions
-
-- Backups taken, feature flags set, access confirmed — exact checks
-
-## Steps
-
-1. One action per step, exact command in a code block
-2. Note expected output where it disambiguates success from failure
-
-## Verification
-
-- The observable end state that confirms success — exact check commands
-
-## Rollback
-
-- How to undo, and the point of no return
-
-## Outcome
-
-<!-- Stamped once, immediately after execution; the file freezes with it. -->
-**Executed:** YYYY-MM-DD — {result: clean | issues encountered + how resolved | aborted + why}
-```

package/data/harnesses/apollo/skills/documentation/templates/non-goals.md

@@ -1,11 +0,0 @@
-# Non-Goals (docs/architecture/non-goals.md)
-
-Truth document. Use for: what the system deliberately does **not** do. A non-goal is a decision, not an omission — each entry carries the why and what would reopen it. Readers (and agents) use this to stop re-proposing settled exclusions.
-
-```
-# Non-Goals
-
-Things this system deliberately does not do. Each is a decision — don't re-propose one without new information of the kind its "revisit if" names.
-
-- **{Non-goal}** — {why it's excluded}. Revisit if: {the trigger that would reopen it}.
-```

package/data/harnesses/apollo/skills/documentation/templates/operations-procedure.md

@@ -1,36 +0,0 @@
-# Operations Procedure (docs/operations/{procedure}.md)
-
-Truth document. Use for: any **recurring** procedure — setup, development, deployment, maintenance. A procedure is consulted mid-task, not read: exact commands, copy-paste runnable, no narrative. Updated in place whenever the workflow changes.
-
-A **one-shot** procedure (a migration, an upgrade, an incident response executed once) is not an operations doc — it is a **Migration Runbook** (record, below). The test: will someone run this again next month? Yes → operations. No → runbook.
-
-Required: **Goal**, **Steps**, **Verification**. Optional: Preconditions, Troubleshooting, Rollback — include only when they carry real content.
-
-If a procedure is a deterministic command list run frequently, script it and have the doc point at the script — a doc should carry judgment (when, why, what to check), not replace automation.
-
-```
-# {Procedure Name}
-
-**Goal:** What this procedure accomplishes, one line.
-
-## Preconditions
-
-- Access, tools, or state required before starting — exact versions, env vars, credentials location
-
-## Steps
-
-1. One action per step, exact command in a code block
-2. Note expected output where it disambiguates success from failure
-
-## Verification
-
-- The observable end state that confirms it worked — exact check commands, not "it should work now"
-
-## Troubleshooting
-
-- Symptom → cause → fix (append entries as failures are root-caused)
-
-## Rollback
-
-- How to undo, and when undo stops being possible
-```

package/data/harnesses/apollo/skills/documentation/templates/plan.md

@@ -1,88 +0,0 @@
-# Plan (docs/history/plans/YYYY-MM-DD-feature-name.md)
-
-Record. Use for: every implementation plan. Plans are created here directly with `Status: Draft`; after approval the plan gates (`boundary`, then `testing` plan-gate mode) run against the still-`Draft` file, the status flips to `Status: In Progress` at the first implementation step, and the file freezes at `Status: Complete` or `Status: Abandoned`. Once frozen, never edit — write a new dated plan if scope changes. The plan records the journey; the truth it implemented lives on in the feature doc and any AD it touched.
-
-The `boundary` skill parses the **Proposed Changes** sections to check boundary impact before execution, and the `testing` skill (plan-gate mode) writes a **Test Obligations** section into the plan at the same gate. Keep that structure stable — section headings and bullet shape are load-bearing for the parsers, and the Test Obligations table is the ledger the verification gate discharges before the plan may reach `Status: Complete`.
-
-**Doc Obligations is the one ledger the plan's author writes.** Deriving tests from behavior is judgment, which is why `testing` owns that section and it is marked never-hand-author; resolving Proposed Changes' file paths to the feature docs that own them is a **lookup** against the ownership index already injected at session start. Different work, different rule — fill it yourself, while the touch list is fresh.
-
-The **`Gates:`** line is machine-read: the compliance hook greps exactly the forms below, and implementation edits are blocked while a segment reads `pending`. Each gate skill rewrites only its own segment when it runs — `boundary` to `Boundary: passed YYYY-MM-DD` or `Boundary: blocked YYYY-MM-DD`; `testing` (plan-gate mode) to `Test-plan: written YYYY-MM-DD (N rows)` — the segment label stays `Test-plan`, greppable. The author writes `Docs: mapped YYYY-MM-DD (N docs)` when the Doc Obligations table is filled. Never hand-edit the line to skip a gate.
-
-```
-# {Feature Name}
-
-**Status:** Draft | In Progress | Complete | Abandoned
-**Gates:** Boundary: pending · Test-plan: pending · Docs: pending
-**Spec:** [docs/features/{feature}.md](../../features/{feature}.md)   <!-- one line per feature doc this plan implements against; a plan spanning three features names three -->
-**Started:** YYYY-MM-DD
-**Completed:** YYYY-MM-DD   <!-- fill when status flips to Complete -->
-
-## Background
-
-Why this work is happening *now*. Link to the spec for *what* we're building; this section is the motivation and the trigger. One paragraph.
-
-## Proposed Changes
-
-### New Files
-
-- `src/path/new-file.js` — purpose
-
-### Modified Files
-
-- `src/path/existing.js` — what changes and why
-
-### New Entities / State
-
-- `entities.foo` — new Redux slice / DB table / persisted shape
-- Persisted state addition: `state.bar.baz` (default `null` for existing users on rehydrate)
-
-### API Changes
-
-- `POST /api/foo` — new route, request `{...}`, response `{status, data}`
-- `PUT /api/bar` — request shape changes; see Migration
-
-### Cross-Module Contracts Affected
-
-- List which cross-cutting contracts this plan affects (db schema, wire envelope, auth, events, env/config, …)
-- "None" is a valid answer and means the `boundary` check will pass cleanly
-
-## Doc Obligations
-
-<!-- One row per feature doc whose `owns:` globs intersect the Proposed Changes above — resolve
-     them against the injected ownership index. Hand-authored: this is a lookup, not research.
-     Amendable while the plan is open; discharged at Completion. -->
-
-| Doc | Claim that changes | `owns:` still accurate? |
-| --- | --- | --- |
-| `docs/features/{feature}.md` | what it says today that this plan makes false | yes / no — new paths to add |
-
-**"None" is valid** — a plan touching only unowned paths owes no doc update, and says so explicitly. It is not a free pass: `boundary` builds its own touch list from the same Proposed Changes and reports docs this table missed.
-
-## Implementation Steps
-
-1. Concrete, ordered, testable
-2. Each step ends with something verifiable
-3. ...
-
-## Test Obligations
-
-<!-- Written by the `testing` skill (plan-gate mode) at the plan gate (after `boundary`). One row per
-     promised behavior: layer · target file · oracle · fixtures. Amendable while the
-     plan is open; discharged at the verification gate. Do not hand-author. -->
-
-## Done Criteria
-
-- [ ] Implementation complete
-- [ ] Verification gate passed — every Test Obligations row discharged (satisfied / owes nothing / blocked → backlog), gate run date and results noted here
-- [ ] Every Doc Obligations row discharged — **updated** / **owes nothing** (with the reason) / **blocked** (→ backlog item, so the debt outlives the frozen plan)
-- [ ] Changelog entry created in `docs/history/changelog/`, carrying the gate's results
-- [ ] Plan marked `Status: Complete`, **Completed:** date filled
-
-## Open Questions
-
-- Question — who decides, by when
-
-## Risks
-
-- Risk — likelihood / impact / mitigation
-```

package/data/harnesses/apollo/skills/documentation/templates/protected-files.md

@@ -1,37 +0,0 @@
-# Protected Files
-
-Truth document. Use for: documenting critical files that need approval before modification.
-
-This doc answers *what is protected and why breaking it hurts* — nothing more. Don't duplicate function-level detail here (signatures, inputs/outputs): it drifts from both the code and the owning feature doc. The owning feature doc is the canonical reference for how the code works; link to it.
-
-```
-# Protected Files
-
-Critical files requiring approval before modification.
-
-## File List
-
-# Category 1 - Description
-path/to/critical/file1.js
-path/to/critical/file2.js
-
-# Category 2 - Description
-path/to/another/file.js
-
-## Risk Summary
-
-| Category   | Risk if Broken  |
-|------------|-----------------|
-| Category 1 | Specific impact |
-| Category 2 | Specific impact |
-
-## Why Protected
-
-### Category 1: [Name]
-
-**Purpose:** What these files do, one or two lines
-**Owning doc:** [docs/features/{feature}.md] — canonical reference for how this code works
-**Invariants:**
-- The behavior that must not break, stated as a constraint (not a function tour)
-- Important point 2
-```

package/data/harnesses/apollo/skills/documentation/templates/root-readme.md

@@ -1,104 +0,0 @@
-# Project Root README
-
-Truth document. Use for: the human-facing entry point at the repository root (`/README.md`) — what visitors and new contributors land on. Distinct from `docs/README.md` (the agent/doc index — see **docs/README.md (Documentation Root)** above). The two coexist; don't merge them.
-
-### Strategy
-
-The root README answers, in order:
-
-1. **What is this?** — one to two sentences, no marketing claims
-2. **What do I get if I install it?** — capability families
-3. **What's it built on?** — terse stack list with versions
-4. **How do I run it?** — the three or four scripts that matter
-5. **How is it laid out?** — directory tree, one-liner per significant folder
-6. **How do I extend it?** — numbered contribution checklist
-7. **What state is it in?** — pre-publish, beta, stable, internal
-
-Skip any section that doesn't apply. Don't pad to fill the template.
-
-### Writing rules
-
-- **Sentence-case headings.** "Getting started", not "Getting Started".
-- **Concrete over abstract.** Real versions, real paths, real commands. No "leverages cutting-edge…".
-- **The tagline answers "what is this?"** — not "why is it great?". Two sentences max.
-- **Tables for enumeration** (routes, commands, endpoints). **Bullets for families and categories.**
-- **Directory tree as a code block**, not a nested markdown list.
-- **Numbered checklist** for "how to add a thing" — readers should be able to follow it top-to-bottom without re-reading.
-- **Point to `docs/` for depth.** The root README links into deep docs; it doesn't host them.
-- **Detect the package manager from the lockfile** (`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, otherwise npm) and write commands accordingly. Don't hardcode `npm` if the repo uses pnpm.
-
-### Template
-
-```markdown
-# {package-name}
-
-{One- to two-sentence positioning. What it is and what scope it covers. No superlatives, no value claims.}
-
-## What's in the box
-
-- **{Family 1}** — {what's in it; a few specific items, comma-listed.}
-- **{Family 2}** — {what's in it.}
-- **{Family 3}** — {what's in it.}
-
-The full surface lives in [`{path/to/public-index}`]({path/to/public-index}). ← optional pointer for libraries
-
-## Stack
-
-- {Framework} {version} · {Language} {version}
-- {Build tool} {version}
-- {Other load-bearing deps}
-
-## Getting started
-
-\`\`\`bash
-{pm} install
-{pm} run dev        # what it does (port, URL)
-{pm} run build      # what it does
-{pm} run preview    # what it does (omit if not applicable)
-\`\`\`
-
-{Optional one-liner about first-run behavior — e.g., "Dev server lands on /playground."}
-
-## {Runtime entry point} ← optional; e.g., "The playground", "CLI", "API endpoints"
-
-{Brief description of the dev/runtime surface.}
-
-| {Thing}              | {What it shows / does} |
-| -------------------- | ---------------------- |
-| `{route or command}` | {description}          |
-
-## Layout
-
-\`\`\`
-src/
-├── {entry-file}        # {purpose}
-├── {folder}/           # {purpose}
-│   └── ...
-└── {folder}/           # {purpose}
-\`\`\`
-
-## Adding a {primary unit}
-
-1. {Drop the source under the right family/folder.}
-2. {Re-export from the public surface.}
-3. {Wire into the playground / example app / test harness so reviewers can see it render.}
-4. {Document any divergence from upstream in `docs/{...}`.}
-
-## Styling ← optional; replace with whichever cross-cutting concern matters most
-
-{Configuration notes that affect every consumer — design tokens, conventions, opt-outs.}
-
-## Status
-
-{Pre-publish, beta, stable, internal-only. State the stability tier per surface — which APIs are contracts and which are experimental — so readers know what can be relied on.}
-
-## License
-
-{License name — scope. e.g., "UNLICENSED — internal use only", "MIT".}
-```
-
-### Baseline scaffolding behavior
-
-The baseline audit **does** scaffold the project root README when missing. The risk this template guards against — template-shaped placeholders that look abandoned — is mitigated by the writing rules above: fill every section with concrete details from the repo (real package manager from the lockfile, real scripts, real layout, real status). Skip sections that genuinely don't apply rather than leaving stubs.
-
-**Never overwrite an existing root README** during a baseline. If one is present — even sparse or outdated — leave it untouched. Treat updates to a pre-existing root README as a separate, explicit request.

package/data/harnesses/apollo/skills/documentation/templates/security-overview.md

@@ -1,27 +0,0 @@
-# Security Overview (docs/architecture/security.md)
-
-Truth document. Use for: the single place the system's security posture is stated — assets, trust boundaries, controls, and accepted risks. Controls link to the code that implements them; this doc asserts, the code proves.
-
-Required: **Trust boundaries**, **Controls**. Optional: Assets, Accepted risks.
-
-```
-# Security Overview
-
-## Assets
-
-- {What's worth protecting — data classes, credentials, tenant isolation}
-
-## Trust boundaries
-
-- {Boundary} — {what crosses it, and what checks the crossing} 
-
-## Controls
-
-| Control | Protects against | Implemented in |
-| ------- | ---------------- | -------------- |
-| {control} | {threat} | `{file/module}` |
-
-## Accepted risks
-
-- {Risk knowingly carried} — accepted because {reason}; owner: {who}. Revisit if: {trigger}.
-```

package/data/harnesses/apollo/skills/documentation/templates/structure.md

@@ -1,65 +0,0 @@
-# docs/structure.md (Authority Map)
-
-Truth document. Use for: defining which folder owns which topic and how docs are maintained.
-
-```
----
-harness-version: 1.0.0
----
-
-# Documentation Structure
-
-> This file is the entry point for understanding the docs folder.
-> `harness-version` above is the repo's single baseline/version sentinel — the `maintenance` agent (baseline mode) owns it and stamps the installed harness version (semver) on every reconcile.
-
-## Authority Map
-
-Each topic has one canonical location. Read from here, not from plans or changelogs.
-
-| Topic | Authority | Key Files |
-| ----- | --------- | --------- |
-| Code-path ownership (path → doc + module) | feature `owns:` frontmatter | the generated ownership index |
-| System overview | `docs/architecture/` | system-design.md |
-| Steering (domain model, glossary, non-goals) | `docs/architecture/` | domain-model.md, glossary.md, non-goals.md |
-| Architecture decisions (ADs) | `docs/architecture/decisions/` | AD-NNN-*.md |
-| API surface | `docs/architecture/` | api.md |
-| Security | `docs/architecture/` | security.md |
-| Feature behavior | `docs/features/` | {key files} |
-| Setup & development | `docs/operations/` | {key files} |
-| Environment / config surface | `docs/operations/` | environment.md |
-| Testing strategy | `docs/tests/` | strategy.md |
-| Historical plans | `docs/history/plans/` | YYYY-MM-DD-name.md |
-| Change records | `docs/history/changelog/` | `YYYY-MM-DD-{three-words}.md` — one per unit of work, written at commit time |
-| Migration runbooks | `docs/history/migrations/` | YYYY-MM-DD-name.md |
-| Deep-research artifacts | `docs/history/research/{topic}/` | README.md + findings.md + sources.md |
-| Brainstorm design records | `docs/research/{topic}-brainstorm/` (active; legacy `-brainstorming/`) → `docs/history/brainstorms/{topic}/` (harvested; user deletes or commits) | thesis.md + forks.md + ledger.md + state.md |
-| Backlog | `docs/history/` | backlog.md |
-
-## The Two Natures
-
-Every doc is a **truth document** (states current absolutes, topic-named, updated in place) or a **record** (dated account of activity, frozen or append-only). `architecture/`, `features/`, `operations/`, `tests/` hold truth; `history/`, `research/`, `memory/` hold records.
-
-- Truth documents are rewritten in place when reality changes — the change-story goes to a changelog entry, never into the truth doc's body.
-- Records freeze: plans at `Complete`/`Abandoned`, changelog entries and migration runbooks once written/executed. A scope change is a new dated record that links back.
-- Feature docs are the living reference for implemented features; an AD is the living truth for one decision subject, with its dated journey confined to its Decision Changelog tail.
-
-## Folder Rules
-
-- `docs/features/`: Living reference for implemented features. Each feature doc **carries** the `owns:` / `module:` / `keywords:` / `status:` frontmatter — `owns:` declares the code-path globs it owns (the only ownership key), `module:` is an optional bounded-context label, `keywords:` are discovery terms, `status:` is `active`/`draft`/`deprecated`. The SessionStart hook unions every feature's `owns:` globs into the injected ownership index.
-- `docs/architecture/`: The truth layer for system-wide shape: overview, domain model, glossary, non-goals, API surface, security, and `decisions/` (ADs — one per subject, updated in place, journey in each AD's Decision Changelog). Update when cross-cutting reality changes.
-- `docs/operations/`: How-to procedures for setup, development, and deployment, plus the environment registry. Update when workflows change. One-shot migrations do NOT live here — they are records (`docs/history/migrations/`).
-- `docs/tests/`: Testing strategy and test docs. Present when the repo has a test posture worth documenting.
-- `docs/history/plans/`: Records. Must have `Status:` field. Never modify after completion.
-- `docs/history/changelog/`: Records. One entry per unit of work (`YYYY-MM-DD-{three-words}.md`), written by whoever does the work and frozen inside the commit it describes. Entries carry the refinement context a diff cannot show — the ask in the user's words, iterations and rejections, skill survived/overridden verdicts, discoveries, pins. Format is the `documentation` skill's `templates/changelog-entry.md`; trigger and lifecycle are the `changelog` rule; distillation is the `retro` agent. Immutability begins at commit — a draft in the working tree is mutable until then, never after. Every entry appends a row to `docs/history/CHANGELOG.md`.
-- `docs/history/migrations/`: Records. One-shot migration/upgrade runbooks — authored before execution, outcome-stamped and frozen after.
-- `docs/history/research/{topic}/`: Deep-research artifacts — the dumped output of a research pass, one folder per topic (conventionally `README.md` synthesis + `findings.md` verified claims & citations + `sources.md`). A point-in-time, cited record — **not** a living authority doc: it owns no code (no `owns:` frontmatter) and is never edited to "stay current." A spec/plan links to it for grounding; a new question gets a new topic folder.
-- `docs/research/{topic}-brainstorm/` → `docs/history/brainstorms/{topic}/`: Brainstorm design records — the Brainstorming-Mode session for a topic (working surface `thesis.md` + `forks.md` + `ledger.md` + `state.md` + `basis/` + `fragments/`, plus an untracked `ops/` capture layer deleted at stop), written by the `brainstorm` skill and its twin agent. An active session lives under `docs/research/` (legacy folders carry the older `-brainstorming/` suffix); on a **passed harvest** it **moves** to `docs/history/brainstorms/` — the completion marker — and the **user decides whether the moved folder is deleted or committed** as provenance. Each of the two folders carries a `Readme.md` index (the skill reads it at start instead of scanning). Author-created (never scaffolded empty), one folder per design conversation. Owns no code (no `owns:` frontmatter); the harvest routes its conclusions into `architecture/`/`features/`/`history/`. (Distinct from `docs/history/research/{topic}/` above — that is a frozen deep-research record, not a brainstorm session.)
-- `docs/history/backlog.md`: Tracked work items. Append new items under appropriate priority.
-
-## Health Log
-
-<!-- Updated by maintenance agent — the sanctioned dated tail in this truth doc (SKILL.md § The Two Natures names the two bridges) -->
-| Date | Review Summary |
-| ---- | -------------- |
-| {today} | Initial baseline — v{harness-version} structure established |
-```

package/data/harnesses/apollo/skills/documentation/templates/system-overview.md

@@ -1,32 +0,0 @@
-# System Overview (docs/architecture/system-design.md)
-
-Truth document. Use for: the bird's-eye view — what the system is, its subsystems, and how they connect. The first doc a new reader opens after the README; austere and short (two screens max). Depth lives in feature docs — this doc maps, it doesn't explain.
-
-Required: **What this is**, **Subsystem map**. Optional: Key flows, Where the truth lives.
-
-```
-# System Overview
-
-## What this is
-
-{Two or three sentences: what the system does, for whom, in what environment it runs.}
-
-## Subsystem map
-
-┌──────────┐     ┌──────────┐     ┌──────────┐
-│ Frontend │────▶│   API    │────▶│    DB    │
-└──────────┘     └──────────┘     └──────────┘
-{One box per subsystem; label the arrows with the contract that crosses them.}
-
-- **{Subsystem}** — one line: what it owns. → [owning doc](../features/{feature}.md)
-
-## Key flows
-
-{At most two or three ASCII flow diagrams for the flows everything else hangs off — request lifecycle, auth, the core domain operation.}
-
-## Where the truth lives
-
-| Area | Canonical doc |
-| ---- | ------------- |
-| {area} | [{doc}](path) |
-```

package/data/harnesses/apollo/skills/documentation/templates/testing-strategy.md

@@ -1,29 +0,0 @@
-# Testing Strategy (docs/tests/strategy.md)
-
-Truth document. Use for: the repo's test posture — what is tested at which level, how to run it, and what is deliberately untested. The framework choices come from the harness testing rule; this doc records how *this repo* applies them.
-
-Required: **Levels**, **Running**. Optional: Deliberately untested, Adding a test.
-
-```
-# Testing Strategy
-
-## Levels
-
-| Layer | Runner | Lives in | Covers |
-| ----- | ------ | -------- | ------ |
-| Unit / integration | {runner} | `tests/` | {what} |
-| E2E | {runner} | `e2e/` | {what} |
-
-## Running
-
-- `{pm} test` — the whole unit suite (CI gate)
-- `{pm} run test:e2e` — {when to run}
-
-## Deliberately untested
-
-- {Area} — {why, and what verifies it instead (typecheck, boot check, manual journey)}
-
-## Adding a test
-
-1. {Where the file goes, what it's named, where fixtures live}
-```

package/data/harnesses/apollo/skills/schema-design/SKILL.md

@@ -1,141 +0,0 @@
----
-name: schema-design
-description: "Use when designing or altering a relational schema — a new table, column, index, junction, migration, or seed — or reviewing one. Owns the design doctrine: what earns a table, where a fact lives (state column vs. sequence log vs. audit log), scope columns over parallel tables, junction = M:N only, FK policy including append-only tables, uniqueness with nullable columns, vocabulary tables, copying rows between scopes. Naming and column types stay in the `database.md` rule. Triggers on 'new table', 'schema', 'migration', 'add a column', 'junction table', 'foreign key', 'audit log', 'versioning'."
----
-
-# Schema Design — the doctrine
-
-You decide **what earns a table and where a fact lives** — for every Nurix relational schema, engine-agnostic (written for SQLite / Cloudflare D1 + Drizzle; a Postgres project keeps the same names and semantics with native types). Naming, the `id`/`slug`/`label` vocabulary, and column types are the `database.md` rule and are never restated here — this skill owns the design arguments consulted at schema-change time.
-
-Apply the sections below to the change in hand; when reviewing, report violations with the section that names them.
-
-## What earns a table
-
-A table is the most expensive home for data — a migration to change its shape, a join to read, a mirror to keep in sync. Default to **not** a table — a concept earns one only with at least one property in the left column.
-
-| A table is earned by…                                                      | Lacking all of these, the data belongs in…              |
-| -------------------------------------------------------------------------- | ------------------------------------------------------- |
-| identity minted at **runtime** — a session, an upload                      | —                                                       |
-| variation **per tenant / user** — a workspace's theme                      | —                                                       |
-| **independent addressing** — queried, indexed, or FK'd in isolation        | a **JSON column** on its parent row                     |
-| **concurrency-safe** writes — racing writers must not clobber a shared blob | —                                                       |
-| a **DB-enforced invariant** — immutability trigger, unique, atomic boundary | —                                                       |
-| dev-authored, published on deploy, identical for every tenant — plan tiers | **config / a constants file**, validated at build       |
-| exactly recomputable from other rows — a tenant's usage total              | a **cache** (KV / edge), recomputed on demand           |
-| process state dead once the request completes — a retry count             | a **log or workflow engine**, never the domain DB       |
-| owned by another system-of-record — the payment processor's invoice        | a **reference column** — store the id, not the data     |
-
-Each right-column route is one test: process state — would a product feature break if this vanished the instant the request finished?; derived output — exactly recomputable from other rows + code?; un-addressed detail — is the row ever `SELECT`ed / `JOIN`ed / FK'd alone?; another system's record — does a specialized service (chat, telemetry, object store) already own it?
-
-- **Static vocabulary or a fixed graph → config, not a table** — HTTP status labels, a fixed onboarding funnel. Surface it in code as a constant/type; reifying it into tables plus a seed makes the file and the tables a two-copy sync problem. The refined boundary is § Vocabulary / lookup tables.
-- **History → one immutable log + a mutable head.** Never shatter versioning into per-entity `*_revisions` / `*_revision_sections` tables — snapshot the coherent set into one append-only versions table; current state is a projection of the newest entry. A table that is just "old rows of another table" collapses into the snapshot.
-- **A surviving table names the invariant it buys** — content-addressed immutable rows buy reproducibility, a monotonic sequence buys ordering/sync, an atomic write boundary buys multi-row atomicity. Drop the requirement and the table drops with it.
-
-Table count tracks **requirements, not domain richness** — a rich domain is not entitled to a table per noun.
-
-## State, rules, and history
-
-**One fact has one home, chosen by what kind of fact it is.** Confusing these produces the most common redundant table in a schema — a queue whose rows restate state the entity already carries.
-
-| The fact | Home | Example |
-| --- | --- | --- |
-| What the entity **is now** | a **column on the entity's own row** | `documents.state = 'blocked'` |
-| What may be **done** about that state | **code** — the transition map, the UI's affordances | which inputs unblock a document |
-| What **was done**, and by whom | the **append-only audit log** | an `audit_log` row: `document.override_applied` |
-| What a consumer must **replay in order** | the **sequence log** | an `app_events` row keyed `(app_id, sequence)` |
-
-- **State becomes a column the moment anything selects on it.** `WHERE state = 'blocked'` takes an index; `WHERE json_extract(metadata, '$.state') = 'blocked'` scans the table and is invisible to every schema check. JSON keeps only what § What earns a table leaves it — detail nothing addresses alone.
-- **A pending-work table mirroring row state is the anti-pattern** — `*_actions`, `*_inbox`, `*_flags`. The tell: resolving one of its rows also updates the entity, so two rows answer one question and are free to disagree. The *open question* is a column beside the state (at most one per row ⇒ a column, § A junction spells many-to-many); the *answer given* is an audit-log row.
-- **Legal transitions live in code, never as rows** — a `status_transitions` table is a state machine the database cannot enforce and the code must re-implement anyway to use.
-
-**The two logs are not substitutes**, and no one table serves both:
-
-| | Sequence log | Audit log |
-| --- | --- | --- |
-| Answers | what happened here, **in order** | who did what, **and whether it succeeded** |
-| Ordinal | a **gapless per-entity `sequence`**, allocated from a counter | none — nothing replays it |
-| Scope | one entity, always | any — **including none**: a sign-up predates every tenant |
-| Records | only what **happened** | **attempts too** — `denied`, `failure` |
-| Read by | cursors replaying forward | investigations, at any age |
-
-The bottom two rows are why neither can hold the other's rows: an event at a scope with no entity has no sequence to take, and a refused attempt in a replay stream would have consumers apply something that never happened.
-
-### The audit log's own shape
-
-**An audit log outlives every row it names, so it stores what it needs to stay readable without them.** Both consequences are missing from most first drafts:
-
-- **Denormalize the display at write time** — `actor_label`, `target_label` beside `actor_id` / `target_id`. Ids alone leave the log intact but unreadable once the person or record is deleted, which is the one thing it exists to survive.
-- **Record the attempt, not the success** — `outcome` (`success | failure | denied`) plus a `reason`. Refused sign-ins and permission denials are most of what anyone opens an audit log for; without the column they cannot be written at all.
-- **Keep the columns product-neutral** — `actor_*` · `action` · `outcome` · `target_*` · `scope_path` · `channel` · `source_ip` · `correlation_id` · `changes_json` serve any domain. Per-level tenancy columns tie the log to today's model; a materialized `scope_path` (`workspace:abc/app:def`) makes "everything under this tenant" one prefix scan and survives a new level appearing — at the price of enforcing the hierarchy in code rather than a `CHECK`.
-
-## Scope, not parallel tables
-
-One entity that exists at several scopes is **one table with a nullable scope column** — never one table per scope, and never one table shared across entity families.
-
-- **A table shared by several families carries the union of their columns** — one `settings` table for users, apps, and workspaces. Almost nothing can be `NOT NULL`, the payload lands in JSON beyond every constraint, index, and FK, and a new family widens a table other features already depend on. One table per family.
-- **Two tables declared to have "the same columns" are two schemas maintained by hand** — the drift is silent, surfacing as an incomplete copy, never as an error. Collapse them and discriminate by column.
-- **The scope column is the discriminator** (`app_id IS NULL` = parent scope, set = child scope). Copying a scope is then `INSERT … SELECT` over one table with one column rewritten, so source and target cannot disagree about shape.
-- **A nullable owner column is how a row exists before its owner does** — a pending enrolment or unclaimed record is creatable before the owner is known, which is what lets a `pending_*` / `*_requests` table collapse into the real one.
-- **A reserved row can own the shipped defaults.** A fixed-id "system" parent makes the defaults and a tenant's copy the same kind of row, through the same code. It must then be excluded from every tenant-scoped query — state that invariant where the id is defined.
-
-## Copying rows between scopes
-
-- **A copied junction row is already correct with no remapping** — its endpoints are `slug` references (§ Keys & the shared vocabulary), and a slug means the same thing in every scope. Rewriting ids through a source→copy map is the most error-prone step in a multi-level copy, and a partial failure leaves wiring pointed into another scope rather than raising.
-- **Provenance is a soft reference — no FK.** `source_id` must outlive its referent; an FK would either block the source's deletion or erase the lineage.
-- **Store the source's version at copy time** — `version` + `source_version` make "is an upgrade available" a comparison of two stored values, not a content diff.
-- **A copy is a row, never a live read.** Nothing at the child scope reads the parent's row at runtime; propagation happens only through an explicit re-copy, so a local edit is never silently overwritten.
-
-## A junction spells many-to-many — nothing else
-
-**A `_map` table is the schema's notation for M:N. Using it for 1:M is a category error** — the junction's own uniqueness admits many parents per child, so the "one parent" rule stops being enforced the moment it is written this way. Cardinality decides between the only two shapes:
-
-| Relationship | Shape |
-| --- | --- |
-| **1:M** — the child has exactly one parent | a **reference column on the child** (`agents.routing_slug`), plus an index |
-| **M:N** — both sides have many | a **`<a>_<b>_map` junction** with a composite unique |
-
-- **The test is one question about the child**: can this row ever belong to two parents at once? No ⇒ column. A junction "in case it becomes M:N later" ships the unenforced model today to buy a migration you may never run.
-- **A junction for a 1:M also** makes the association a row that can go missing independently of the child — a child can exist correctly while its wiring does not — and forces a join onto the most common read in the system.
-- **A junction carrying only its two endpoints and timestamps is the tell** — a real M:N junction usually earns its own columns (a role, an order, a status); one that never does is a 1:M waiting to be collapsed into a column.
-- **Collapsing deletes a copy step** — the association travels inside the row it belongs to: no second pass to remap, no copy landing with its wiring half-applied.
-- **A pair already recorded elsewhere needs no table at all.** If an append-only log stores `(parent, child)` on every write, the association table is `SELECT DISTINCT` over that log — a cache free to disagree with the log it derives from (§ What earns a table).
-
-## Foreign keys into and out of append-only tables
-
-**An append-only table can afford no `ON DELETE` action at all, so its references to mutable tables are soft — no FK.** Every option is closed to it:
-
-| Action | Why it fails on an append-only table |
-| --- | --- |
-| `SET NULL` | It is an **UPDATE**. An append-only trigger aborts it, so the parent's deletion fails — with an error naming the trigger, not the constraint. |
-| `CASCADE` | Deletes history to delete a person. The log exists precisely to outlive its subjects. |
-| `NO ACTION` | Makes anyone who ever appeared in the log undeletable — the hub defect above. |
-
-- **`SET NULL` is the trap** — it reads like a safe relaxation of `NO ACTION` and passes review as one.
-- **Record the actor as a plain column** — the same soft-reference treatment provenance gets (`source_id`, `thread_id`). The log keeps naming who acted after the account is gone, which is what an audit trail is for.
-- **`CASCADE` from the append-only side's own parent is still fine** — a cascade is a DELETE, so a `BEFORE UPDATE` trigger never sees it: an App's log dying with the App is legitimate, distinct from erasing a log to delete a person.
-- **State the exemption where it exists.** A catalog whose rows must not disappear under a referencing row (a service definition, a vocabulary) keeps `NO ACTION` deliberately — that guarantee is worth one line saying so.
-
-## Uniqueness with a nullable column
-
-**`UNIQUE (a, b)` does not constrain rows where `b` is `NULL`** — SQL treats every `NULL` as distinct, so a composite unique over a nullable discriminator silently permits exactly the duplicates it was introduced to keep apart. Write one partial index per scope instead:
-
-```sql
-CREATE UNIQUE INDEX <t>_parent_slug_unique ON <t> (parent_id, slug) WHERE child_id IS NULL;
-CREATE UNIQUE INDEX <t>_child_slug_unique  ON <t> (child_id, slug)  WHERE child_id IS NOT NULL;
-```
-
-**Prove a uniqueness claim by inserting the duplicate it forbids** — a schema review cannot tell a firing index from a silent one by reading.
-
-## Vocabulary / lookup tables
-
-A controlled vocabulary earns a **table** only when a user row FKs into it and reads its `label` / `description` at runtime — a service catalog rendered in a picker; static dev-authored config nobody references by FK stays **config** (§ What earns a table) — a `doc_type` value list. Enumerable is not tabular, and a `type`-style column validated against the constants file beats an FK to a seeded mirror. An earned table has a fixed shape: `id` (UUID) · `slug` (UNIQUE) · `label` · optional `description` · `status` · timestamps.
-
-- **Seeds are generated, never hand-written** — the source of truth is a CSV or a shared package; a generator emits the `*.seed.sql` with UUIDv5 ids and an idempotent `ON CONFLICT(slug)` upsert that preserves live counts / admin-tuned columns. ❌ Hand-editing seed SQL — regenerate it.
-
-## Run
-
-1. **Route every new fact through § What earns a table** — default to *not* a table; name the left-column property that earns one, or the right-column home it takes instead.
-2. **Classify every fact by § State, rules, and history** — now-state → entity column; rules → code; what-was-done → audit log; replayable → sequence log.
-3. **Check cardinality before any junction** (§ A junction spells many-to-many) and every FK's `ON DELETE` (§ Keys, § Append-only).
-4. **Prove uniqueness claims by inserting the forbidden duplicate** — a schema review cannot tell a firing index from a silent one by reading.
-5. **Report as a findings list** — one line per violation: the section, the table/column, the fix.