@nurix/etna 0.19.55 → 0.19.56

package/data/harness-index.json

@@ -1,5 +1,5 @@
 {
-    "fingerprint": "79c4b33f5911",
+    "fingerprint": "e7493c40d358",
     "harnesses": {
         "apollo": {
             "plugin": "apollo",

package/data/harnesses/apollo/CLAUDE.md

@@ -8,13 +8,13 @@ How AI coding agents — any vendor, any runtime — work on this project. Rules
 
 **Baseline first**: if `docs/structure.md` lacks a `harness-version` frontmatter marker, or it is behind the `version` in `.claude/harness.json`, invoke the `maintenance` agent before taking up the user's first ask — tell the user, let the agent run, then proceed.
 
-Invoke the `maintenance` agent whenever the docs look like they need it — not just at first setup: a missing `docs/structure.md` (the repo isn't reconciled — baseline before applying anything below), a `harness-version` marker behind the installed version, docs contradicting code, unowned source paths, or drift noticed while working. Never reconcile these by hand — the agent auto-selects its mode (baseline when the marker is missing or behind, coherence audit otherwise) and hands back; if it returns a follow-up (typically the module proposal), re-invoke it to finish. Each component's internals live in the component, not here.
+Invoke the `maintenance` agent when a mechanical condition holds: `docs/structure.md` is missing (the repo isn't reconciled — baseline first), the `harness-version` marker is behind the installed version, a doc contradicts code being touched, or source paths are unowned — not on prose that merely looks stale. Structural reconciliation is never done by hand — the agent auto-selects its mode (baseline when the marker is missing or behind, coherence audit otherwise) and hands back; if it returns a follow-up (typically the module proposal), re-invoke it to finish. Single-glob or single-line doc corrections are done inline, per § Documentation. Each component's internals live in the component, not here.
 
 ---
 
 ## Getting Started
 
-- Read **[`docs/structure.md`](docs/structure.md)** for the documentation map and folder authority (architecture, features, operations)
+- Consult **[`docs/structure.md`](docs/structure.md)** when adding or moving a doc — it is the authority on placement
 - Read **[`docs/memory/`](docs/memory/)** for agent memory files (one per agent)
 - Prefer `docs/` over `README.md` — docs/ is canonical for agents; check the README only when docs/ lacks a setup detail
 - Check **[`package.json`](package.json)** for available scripts. Detect the package manager from the lockfile — see `.claude/rules/general.md`; don't hardcode one.
@@ -33,9 +33,11 @@ Three peer modes, then a verification gate and a Completion step — enter where
 
 > Brainstorm entry needs a **basis** — a reference document or a one-shot brain dump; drip-sized asks (a bug fix, one button) are too small and get redirected. A **pillar** is a recorded strategic principle from a past brainstorm: in-progress sessions live under `docs/research/`, harvested ones under `docs/history/brainstorms/`, harvested doctrine under `docs/architecture/`. The LLD is the feature doc itself — `docs/features/{feature}.md`, design intent first, extended in place at Completion.
 
+> **The lightweight lane:** a change touching one module, no cross-module contract surface, and under about a day's work skips the modes above entirely — the ad-hoc regime of `.claude/rules/testing.md` applies: make the change, pay its test immediately if it alters promised behavior, cover it with a changelog row.
+
 **On Plan Completion:**
 
-1. **The verification gate passes first** — user-triggered: when implementation completes, report it and offer the gate; never run it unbidden. It requires the plan's Test Obligations ledger to exist (proof the plan gates ran) and discharges every row, driving the real surface before pinning tests — `.claude/rules/verification.md`. A plan with outstanding obligations stays open, whatever the code does.
+1. **The verification gate passes first** — user-triggered: when implementation completes, report it and offer the gate; never run it unbidden. It requires the plan's Test Obligations ledger to exist (proof the plan gates ran) and discharges every row, driving the real surface before pinning tests — `.claude/rules/testing.md`. A plan with outstanding obligations stays open, whatever the code does.
 2. Freeze the plan — `Status: Complete`, fill the Completed date. The file is now frozen.
 3. Flip the feature LLD to `status: active`; extend it in place with the how-it-works sections; confirm its `owns:` globs against the actual code.
 4. Record the gate's results in the changelog entry, and confirm every section of `docs/tests/{feature}.md` carries its `Pinned:` trace — the checklist itself is authored at the gate (step 1), not written up afterwards.
@@ -67,20 +69,15 @@ Boundaries are **diagnosed, not documented** — the `boundary` skill derives th
 
 ### Test obligations — specify before implementing
 
-**After `boundary` passes and its amendments are folded, invoke the `test-plan` skill** — same plan gate, ordered second. It derives the tests the plan owes from its Proposed Changes and the owning LLD, and writes the **Test Obligations** ledger into the plan (one row per promised behavior: layer · target file · oracle · fixtures). It writes no test files — the ledger is what the verification gate discharges, and because it lives in the plan file it survives dispatch to an executor that sees only the plan. On a boundary **BLOCK** it does not run — re-plan first. Layer rules and the e2e altitude gate live in the skill.
+**After `boundary` passes and its amendments are folded, invoke the `testing` skill (plan-gate mode)** — same plan gate, ordered second. It derives the tests the plan owes from its Proposed Changes and the owning LLD, and writes the **Test Obligations** ledger into the plan (one row per promised behavior: layer · target file · oracle · fixtures). It writes no test files — the ledger is what the verification gate discharges, and because it lives in the plan file it survives dispatch to an executor that sees only the plan. On a boundary **BLOCK** it does not run — re-plan first. Layer rules and the e2e altitude gate live in the skill.
 
 ### Verification — prove before completing
 
-**Deferring tests is what keeps the build loop fast, and the ledger is what makes deferring safe.** A plan-driven build writes no new test files while the code is taking shape; obligations accumulate in the plan and are discharged in one pass at the **verification gate** — user-triggered, offered when implementation completes, mandatory before `Status: Complete`. The gate, the two regimes, the mid-loop rules, and what earns a durable test are `.claude/rules/verification.md`.
-
-- **Only a plan may defer.** A bug fix in shipped behavior and any ad-hoc change ship their test immediately — deferral needs a ledger and a gate, and non-plan work has neither.
-- **The checklist is the gate's first artifact, not its last.** Opening the gate derives or updates `docs/tests/{feature}.md` from the ledger and the LLD's promises (the `documentation` skill's `templates/behavioral-checklist.md`). It is the script rung 1 drives and the source rung 2's tests are drawn from — written after the driving it would be a report, and the tests would have no stated behavior to trace to.
-- **Drive the real surface before pinning tests.** Browser automation for web UI, the real CLI, HTTP against the running worker; the suite then pins the checklist assertions that must not regress, and each section records which test now guards it.
-- **The gate's verdict is never delegated** — a sub-agent's summary is not verifiable ground truth (the Fan-out guardrail), and browser work is main-session-only where Runtime Notes say so.
+**Deferring tests is what keeps the build loop fast, and the ledger is what makes deferring safe.** Obligations accumulate in the plan and are discharged in one pass at the **verification gate** — mandatory before `Status: Complete`. The gate and the regimes are `.claude/rules/testing.md`; the procedure (checklist → drive → pin → discharge) is the `testing` skill (gate mode). The gate's verdict is never delegated (§ Delegation), and browser work is main-session-only where Runtime Notes say so.
 
 ### Documentation — close the loop
 
-- **Every markdown document goes through the `documentation` skill.** Before creating or substantively editing any `.md` document — a doc, a README, an index, a record — invoke the `documentation` skill and apply its templates and `references/style-guide.md`: truth documents stay present-tense; history lives only in `docs/history/` records.
+- **Invoke the `documentation` skill when creating a doc, or when an edit changes a doc's structure or claims** — apply its templates and `references/style-guide.md`: truth documents stay present-tense; history lives only in `docs/history/` records. Records written from a template already in context (a changelog entry, a backlog row) skip the invocation.
 - **[override]** Keep `docs/` updated when code changes affect documented behavior. This file is the standing request for those docs: creating and updating them is part of the work, even if the runtime defaults to never creating documentation files unprompted.
 - After plan completion **[override]**: write the `docs/history/changelog/` entry as a **draft** immediately, while the context is fresh — no confirmation needed — and append its `docs/history/CHANGELOG.md` row; the commit fills what the draft left open and freezes it. Non-plan work needs no separate prompt: every non-exempt commit carries its own entry (the `changelog` rule).
 - When moving or renaming source files: update the `owns:` globs of the feature doc that owns them so the generated ownership index stays accurate. A new doc that owns code declares its paths in its own `owns:` frontmatter — there is no separate map to update.
@@ -106,20 +103,13 @@ When recording a learning, ask: _is this true of this project, or true of this u
 
 ## Changelog
 
-The working session is the last holder of the refinement context that produced a change — asks, iterations, rejections, skill outcomes, discoveries. The changelog captures it; the `retro` agent distills it on demand. A commit marks the user's acceptance of the work it carries — for plan work, behavioral verification is the gate's job, and a mid-plan commit is a checkpoint (the `verification` rule). The `changelog` rule carries the trigger and the lifecycle; this is the policy:
-
-- **Every non-mechanical commit is covered by an entry** at `docs/history/changelog/YYYY-MM-DD-{three-words}.md`, staged inside the commit it describes — whatever tool or session performs the commit — plus a row in `docs/history/CHANGELOG.md`. Format, required fields, and the closed exemption list are the `documentation` skill's `templates/changelog-entry.md`; the failure fields (rejected attempts, overridden skill output) and verbatim taste quotes are required, not optional — the entry's value concentrates there.
-- **An entry may exist before its commit.** A plan reaching `Status: Complete` writes its entry as a **draft** immediately, while the context is fresh; the commit fills what the draft left open. **Immutability begins at commit, not creation** — a draft is mutable, a committed entry never is, and a correction is a new entry that links back. Doc-health passes skip the genre.
-- **A commit is the smallest unit an entry may describe**; above that the mapping is judgment. Work exceeding a draft's scope gets a *second* entry rather than stretching the first.
-- **Distillation is the `retro` agent** — run on demand (before a brainstorm or LLD, before a new project, after a refinement arc), it converts accumulated entries into a typed punch list (doc content, doc structure, skill evolution, pins, harness rules), appends actionable items to the backlog, and proposes only — application runs through the normal documentation loop.
-
-**One-shot migrations are a different genre.** Work that runs **once** against a live system — a data backfill, a schema cutover, a dependency or harness upgrade rolled across repos — is a **migration runbook** at `docs/history/migrations/YYYY-MM-DD-{slug}.md` (template: the `documentation` skill's `templates/migration-runbook.md`), authored **before** execution and outcome-stamped after. A changelog entry says what changed in the repo; a runbook says what was executed against the world and how to verify or undo it. A repeatable procedure is neither — that is `docs/operations/`. When a runbook defers targets, it records **why** and the **trigger to re-evaluate them**, so the next run re-checks rather than inheriting the skip.
+The working session is the last holder of the refinement context that produced a change — asks, iterations, rejections, discoveries; the changelog captures it, and the `retro` agent distills it on demand into doc, skill, and pin feedback. When an entry is owed, its lifecycle, its granularity, and the migration-runbook genre are the `changelog` rule; format and required fields are the `documentation` skill's `templates/changelog-entry.md`. A plan reaching `Status: Complete` writes its entry as a **draft** immediately, while the context is fresh; **immutability begins at commit, not creation** — a committed entry is never edited, a correction is a new entry that links back.
 
 ---
 
 ## Out-of-Scope Discovery
 
-When a plan's implementation surfaces work that is important but outside the plan's scope and is not being done now (a pre-existing bug being fixed on the spot is the bug-fix regime — the `verification` rule — not a backlog item):
+When a plan's implementation surfaces work that is important but outside the plan's scope and is not being done now (a pre-existing bug being fixed on the spot is the bug-fix regime — the `testing` rule — not a backlog item):
 
 - Append it to `docs/history/backlog.md` under the appropriate priority (P0-P3)
 - Format: `- **[P1]** Description — discovered by [plan-name or agent-name]`
@@ -127,22 +117,31 @@ When a plan's implementation surfaces work that is important but outside the pla
 
 ---
 
+## Delegation
+
+The single policy for sub-agent dispatch — when to fan out, at what tier, and how far to trust the result. Component-internal dispatch mechanics (the foreman loop, the brainstorm twin, batch classification) stay in their components and defer here for anything this section covers. No dispatch mechanism ⇒ inline.
+
+- **Delegate to keep bulk out of the main context.** Wide file reads, sweeps, broad research, audits, fixture prep — work whose raw tool output the main session doesn't need — defaults to a sub-agent: output a sub-agent reads dies with it, while output read inline is re-read and re-billed on every later turn. The hand-off is self-contained (the sub-agent sees none of the conversation), so it must still cost less than the work; run independent delegations in parallel.
+- **Small or judgment work stays inline.** A task finishable in a handful of tool calls is faster done than briefed. **Never delegate judgment by reflex** — a second opinion is for a high-stakes call or an explicit request.
+- **A delegated result is a report, not verifiable ground truth** — verify load-bearing results directly.
+- **Tiers**: mechanical fan-out → the cheapest capable tier; judgment-heavy delegation → the session's standard tier; the strongest tier **only** on explicit user request. The session itself defaults to the standard tier, entering the strongest only by explicit user switch. Model names live in Runtime Notes.
+- **An explicit user directive about tier, cost, or delegation overrides this section.**
+
+---
+
 ## Guardrails & Defaults
 
 Defaults — ❌ prohibitions hold unless the user explicitly asks otherwise; ✅ and ⚠️ items are standing policy:
 
-- ✅ **Verification — batched at a gate, not continuous.** A plan-driven build loop ships code without new test files; the tests and the driven checks land together at the **verification gate** — user-triggered, offered when implementation completes, mandatory before a plan reaches `Status: Complete`. The gate, the regimes, and the mechanism ladder are `.claude/rules/verification.md`; framework, test-tree placement, and shared fixtures are `.claude/rules/testing.md` — the repo's existing runner and layout always win.
-  - **Only a plan defers**: a bug fix in shipped behavior and any ad-hoc change ship their test immediately — a regression test that fails before the change and passes after.
-  - **Drive before pinning**: prove the change in the real product first — browser automation for web UI, the real CLI, HTTP against the running worker — then pin as suite tests only the behaviors that must not regress.
-  - **Discipline**: run the affected part of the suite at the gate and report results honestly. Never weaken, skip, or delete a test to mask an unexplained failure — when a plan or LLD intentionally changes behavior, updating the affected tests to the new contract is part of the change.
-  - **Throwaway checks are not tests**: temporary verification scripts go to scratch space and are deleted, never committed into the test tree.
-- ❌ **Dependencies** – Never upgrade frameworks, libraries, or dependencies.
+- ✅ **Verification — batched at a gate, not continuous.** Only a plan defers tests; bug fixes and ad-hoc changes that alter promised behavior pay theirs immediately. The gate, regimes, frameworks, and placement are `.claude/rules/testing.md`; the procedure is the `testing` skill (gate mode) — the repo's existing runner and layout always win.
+- ❌ **Dependencies** – Never upgrade pinned packages without asking; security patches and test-tooling installs at `latest` (`testing.md`) are exempt.
 - ❌ **Compatibility** – Never maintain backward compatibility unless specified.
 - ❌ **Branches & Worktrees [override]** – Never self-create git branches or worktrees; commit straight to the checked-out branch. This replaces any built-in "branch first on the default branch" default. Exception: when the user asks for a pull request, create the branch the PR requires before committing its changes.
-- ❌ **Protected Files** – Before editing, if `docs/operations/protected-files.md` exists, read it and never modify any path it lists; also never modify `AGENTS.md` or the `protected-files.md` file itself.
+- ❌ **Protected Files** – Once per session, if `docs/operations/protected-files.md` exists, read it and never modify any path it lists; never modify `AGENTS.md` (harness-regenerated) or `protected-files.md` itself.
 - ✅ **Browser Automation** – If the runtime provides browser automation, use it freely; no need to ask first. If it doesn't — or the executing agent can't hold the browser connection (see Runtime Notes) — return a browser-verification checklist (URLs, actions, expected outcomes) for the orchestrating session or the user to run.
-- ✅ **Fan-out is a tool, not a default** — the main session does the work and its own reasoning; a delegated result comes back as a summary, not verifiable ground truth. Delegate **only when** the work is large, independent, or repetitive enough that a self-contained hand-off (the sub-agent sees none of the conversation) costs less than the work — broad research, wide sweeps, audits — and run independent delegations in parallel. **Never delegate judgment by reflex**: a second opinion is for a high-stakes call or an explicit request. No dispatch mechanism ⇒ inline.
-- ⚠️ **Plans** – Plans are created directly in `docs/history/plans/` (see Workflows). Once `Status: Complete` or `Status: Abandoned`, the file is frozen — never edited. Abandoning a plan whose code was committed first converts its undischarged Test Obligations into backlog items (the `verification` rule). If scope changes after completion, write a new dated plan that links back to the old one.
+- ✅ **Bookkeeping** — hooks silently append doc-debt rows to `docs/operations/bookkeeping.md`; the commit hook blocks while unresolved rows remain — dispatch the `bookkeeper` agent to drain the queue.
+- ✅ **Delegation** — when to fan out, tiers, and trust are § Delegation.
+- ⚠️ **Plans** – Plans are created directly in `docs/history/plans/` (see Workflows). Once `Status: Complete` or `Status: Abandoned`, the file is frozen — never edited. Abandoning a plan whose code was committed first converts its undischarged Test Obligations into backlog items (the `testing` rule). If scope changes after completion, write a new dated plan that links back to the old one.
 - ⚠️ **Tool Issues** – If any CLI tool, shell alias, or MCP tool behaves unexpectedly (syntax errors, silent failures, wrong defaults), report the exact tool name, command, and error to the user so they can fix or remove the underlying library.
 
 ---
@@ -158,5 +157,5 @@ Defaults — ❌ prohibitions hold unless the user explicitly asks otherwise;
 
 Everything above is runtime-neutral. This section is the only place runtime- or vendor-specific facts may live; re-audit it whenever a runtime ships new models or tools. Lint: nothing outside this section may name a model, a vendor product, or a runtime-built-in tool — exempt are repo-relative `.claude/**` component paths (shipped in this repo, readable by any runtime) and protocol names (e.g. MCP).
 
-- **Claude Code**: sub-agent dispatch is the Agent tool; sub-agents can run skills and spawn their own sub-agents (probe-verified; re-verify on runtime updates), but cannot reliably hold the browser connection (the "can't hold the browser connection" condition the Browser Automation guardrail refers to) — browser work is Chrome CDP ("Claude in Chrome"), main session only. The user-level memory store is `~/.claude/` (auto-memory under `~/.claude/projects/...`). The ownership index and skill/agent descriptions are injected at session start; skills are invoked as slash commands (e.g. `/brainstorm start`). Dispatch tiers: mechanical fan-out runs on the cheapest capable tier; a user-requested second opinion takes the strongest — pick by capability at dispatch, since model names go stale.
+- **Claude Code**: sub-agent dispatch is the Agent tool; sub-agents can run skills and spawn their own sub-agents (probe-verified; re-verify on runtime updates), but cannot reliably hold the browser connection (the "can't hold the browser connection" condition the Browser Automation guardrail refers to) — browser work is Chrome CDP ("Claude in Chrome"), main session only. The user-level memory store is `~/.claude/` (auto-memory under `~/.claude/projects/...`). The ownership index and skill/agent descriptions are injected at session start; skills are invoked as slash commands (e.g. `/brainstorm start`). Dispatch tiers (§ Delegation): the standard tier is Opus-class and is the session default; mechanical fan-out runs on the cheapest capable tier (Sonnet-class); the strongest tier (Fable-class) only on explicit user switch or request — pick by capability at dispatch, since model names go stale.
 - **Runtimes without native component support** (AGENTS.md readers, etc.): read `.claude/agents/<name>.md` and each skill's `.claude/skills/<name>/SKILL.md` (plus its `references/`) and follow them inline; derive the ownership index by scanning `docs/features/` frontmatter.

package/data/harnesses/apollo/harness.json

@@ -15,5 +15,5 @@
     "docs/memory/main.md",
     ".mcp.json"
   ],
-  "digest": "6c5d5cfe5a12"
+  "digest": "47955a71244a"
 }

package/data/harnesses/apollo/hooks/approved-packages.md

@@ -0,0 +1,42 @@
+# Approved Packages
+
+Read by the PreToolUse install gate (`compliance.mjs`) — an off-table install is denied. Not model-loaded; the policy line lives in `.claude/rules/general.md`. The table changes only by explicit user decision.
+
+| Package | Version | Use | Don't use |
+| --- | --- | --- | --- |
+| `react` | ^19.2.3 | UI components | — |
+| `vite` | ^8.0.0 | Build tool, dev server | `webpack`, CRA |
+| `tailwindcss` | ^4.1.18 | Styling | `styled-components` |
+| `@vitejs/plugin-react-swc` | ^4.2.2 | JSX compilation | `@vitejs/plugin-react` |
+| `react-router-dom` | ^7.11.0 | Routing | — |
+| `@reduxjs/toolkit` | ^2.11.2 | State management | `zustand`, `jotai` |
+| `react-redux` | ^9.2.0 | Redux React bindings | — |
+| `axios` | ^1.13.2 | HTTP requests in browser/Node code | `fetch` in browser code — Workers and edge runtimes use native `fetch`, which is correct there |
+| `@microsoft/fetch-event-source` | ^2.0.1 | SSE over POST — streaming agent output | hand-rolled `getReader()` loops, `EventSource` |
+| `date-fns` | ^4.1.0 | Date formatting | `moment`, `dayjs` |
+| `@dnd-kit/core` | ^6.3.1 | Drag and drop | `react-beautiful-dnd` |
+| `@xyflow/react` | ^12.11.0 | Node-based flow charts | `reactflow`, `react-flow-renderer` |
+| `motion` | ^12.23.26 | Animations | `react-spring` |
+| `sonner` | ^2.0.7 | Toast notifications | `react-toastify` |
+| `react-window` | ^2.2.3 | List virtualization | `react-virtualized` |
+| `nanoid` | ^6.0.0 | ID generation | `uuid` — exempt: UUIDv5/v7 database ids per `database.md` |
+| `express` | ^5.2.1 | HTTP server | `fastify`, `koa` |
+| `drizzle-orm` | ^0.45.2 | Database ORM | `prisma`, `sequelize`, `typeorm` |
+| `drizzle-kit` | ^0.31.10 | Schema tooling | — |
+| `zod` | ^4.2.1 | Schema validation | `yup`, `joi` |
+| `jose` | ^6.1.3 | JWT handling | `jsonwebtoken` |
+| `microdiff` | ^1.5.0 | JSON object diffing | `deep-diff`, `just-diff` |
+| `react18-json-view` | ^0.2.9 | JSON tree view | `react-json-view` |
+| `@tiptap/react` | ^3.11.1 | Rich text editor | `slate`, `quill`, `draft-js` |
+| `shiki` | ^4.3.1 | Syntax highlighting | `prism`, `highlight.js` |
+| `lucide-react` | ^1.26.0 | Icons | `react-icons`, `heroicons` |
+| `@pdfme/generator` | ^6.1.12 | PDF generation | `jspdf`, `pdfkit` |
+| `cmdk` | ^1.1.1 | Command palette | `kbar`, `ninja-keys` |
+| `@monaco-editor/react` | ^4.7.0 | Code editor | `codemirror`, `ace` |
+| `localforage` | ^1.10.0 | Client-side storage | `idb`, `dexie` |
+| `react-markdown` | ^10.1.0 | Markdown rendering | `marked`, `markdown-it` |
+| `remark-gfm` | ^4.0.1 | GFM (tables, tasklists) | `remark-github`, custom |
+| `fast-deep-equal` | ^3.1.3 | Deep equality checks | `lodash.isEqual` |
+| `@ngneat/falso` | latest | Fake data generation | `@faker-js/faker`, `chance` |
+| `pino` | ^10.1.0 | Logging | `winston` |
+

package/data/harnesses/apollo/hooks/compliance.mjs

@@ -107,14 +107,14 @@ function fileGate(projectDir, rel, toolName) {
       if (!plan.hasLedger) {
         return decision(
           "deny",
-          `BLOCKED — plan gate. \`${plan.file}\` has no \`## Test Obligations\` section. Run the \`test-plan\` skill; its ledger is what the verification gate discharges.`
+          `BLOCKED — plan gate. \`${plan.file}\` has no \`## Test Obligations\` section. Run the \`testing\` skill (plan-gate mode); its ledger is what the verification gate discharges.`
         );
       }
     }
   }
 
   // Writing a test file is never an interruption. Deferring tests to the verification gate stays
-  // doctrine (`verification.md` § During the loop), but it needs no gate here: what the ledger
+  // doctrine (`testing.md` § During the loop), but it needs no gate here: what the ledger
   // actually guarantees is enforced at both ends already — a plan may not take implementation
   // edits until its `## Test Obligations` section exists (above), and it may not reach
   // `Status: Complete` until the gate discharges every row (the Stop gate). Policing the *moment*
@@ -169,11 +169,16 @@ function commitGate(projectDir) {
   return null;
 }
 
-// Package names approved anywhere in the rules (general.md table + testing.md's frameworks).
+// Package names approved in .claude/hooks/approved-packages.md (plus testing.md frameworks and general.md).
 function approvedPackages(projectDir) {
   const names = new Set();
-  for (const rule of ["general.md", "testing.md"]) {
-    const text = readSafe(path.join(projectDir, ".claude", "rules", rule));
+  const sources = [
+    path.join(projectDir, ".claude", "hooks", "approved-packages.md"),
+    path.join(projectDir, ".claude", "rules", "general.md"),
+    path.join(projectDir, ".claude", "rules", "testing.md"),
+  ];
+  for (const src of sources) {
+    const text = readSafe(src);
     for (const m of text.matchAll(/`(@?[a-z0-9][\w./-]*)`/g)) names.add(m[1]);
   }
   return names;
@@ -191,7 +196,7 @@ function packageGate(projectDir, command) {
     if (!approved.has(pkg)) {
       return decision(
         "deny",
-        `BLOCKED — package table. \`${pkg}\` is not in the approved table (.claude/rules/general.md; test packages: .claude/rules/testing.md). The table changes only by explicit user decision.`
+        `BLOCKED — package table. \`${pkg}\` is not in the approved table (.claude/hooks/approved-packages.md; test packages: .claude/rules/testing.md). The table changes only by explicit user decision.`
       );
     }
   }

package/data/harnesses/apollo/rules/changelog.md

@@ -8,7 +8,9 @@ Every unit of work leaves one record — `docs/history/changelog/YYYY-MM-DD-{thr
 | --- | --- |
 | A plan reaches `Status: Complete` | A draft entry for that plan, linked to it — written now, while the session still holds the context |
 | The user asks for a changelog | The entry for the work in hand. No commit required |
-| A commit is made | Every non-exempt commit is covered by an entry — the `commit` skill writes or completes it |
+| A commit is made | Every non-exempt commit is covered by an entry — the `commit` skill writes or completes it (no `commit` skill in the runtime ⇒ write the entry from the `documentation` skill's `templates/changelog-entry.md` and stage it with the commit) |
+
+An entry is owed only by work that changes promised behavior or takes a design decision; mechanical and cosmetic commits — a typo, a copy tweak, a config value, a log line — take only their `docs/history/CHANGELOG.md` row, no entry file. The failure fields (`Ask:`, `Skills:`, `Pin:`) are required only when non-none.
 
 ## Lifecycle
 
@@ -17,3 +19,7 @@ Draft (created before its commit exists) → complete (missing fields filled fro
 ## Granularity
 
 A commit is the smallest unit an entry may describe; above that the mapping is judgment — four commits may be four entries or one, whichever reads better as history. An entry spanning several commits rides in the **last** of them, naming the predecessors in `Commits:`. When work exceeds what a draft describes, write a second entry rather than stretching the draft — the first stays an honest account of the plan.
+
+## Migrations are a different genre
+
+**One-shot migrations are a different genre.** Work that runs **once** against a live system — a data backfill, a schema cutover, a dependency or harness upgrade rolled across repos — is a **migration runbook** at `docs/history/migrations/YYYY-MM-DD-{slug}.md` (template: the `documentation` skill's `templates/migration-runbook.md`), authored **before** execution and outcome-stamped after. A changelog entry says what changed in the repo; a runbook says what was executed against the world and how to verify or undo it. A repeatable procedure is neither — that is `docs/operations/`. When a runbook defers targets, it records **why** and the **trigger to re-evaluate them**, so the next run re-checks rather than inheriting the skip.

package/data/harnesses/apollo/rules/cloudflare.md

@@ -0,0 +1,167 @@
+# Cloudflare Worker
+
+Conventions for Cloudflare Workers — `wrangler.jsonc` setup, vars and secrets, and code shape (dispatch, errors, modules, WebSockets). Schema design doctrine is the `schema-design` skill.
+
+## 1. Project & wrangler.jsonc Setup
+
+### 1.1 Wrangler version
+
+- Use Wrangler **v4** — v3's bundled config schema is missing newer keys (e.g. `secrets_store_secrets`), so editors flag valid config as invalid.
+- **No `package.json`** (dep-free worker): use `npx wrangler@4` in every command and doc — the `@4` is the pin. Don't create a `package.json` just to record it.
+- **`package.json` exists**: pin wrangler to the exact version tested against (not `^4.0.0`), reinstall, and verify with `wrangler deploy --dry-run` before pushing.
+
+### 1.2 Config format
+
+- Use `wrangler.jsonc` (not `wrangler.toml`).
+- Include `"$schema": "node_modules/wrangler/config-schema.json"` so the editor validates against the exact installed wrangler version.
+
+### 1.3 Comments in jsonc
+
+None by default. Keep a comment only when it captures a non-obvious **WHY** — a hidden constraint, workaround, or account-specific quirk. Never narrate what a key already says.
+
+### 1.4 workers.dev URLs
+
+- Set `"workers_dev": false` once a custom domain is wired up, so the custom domain is the only entry point.
+- Pair with a `routes` entry using `custom_domain: true` so Cloudflare manages the DNS record and cert.
+
+### 1.5 Observability
+
+Default block for every Worker:
+
+```jsonc
+"observability": {
+    "logs": {
+        "enabled": false,
+        "invocation_logs": true
+    }
+}
+```
+
+`enabled: false` avoids per-log billing; `invocation_logs: true` keeps the cheap per-request audit trail. **Bootstrap override:** a new Worker (especially cron-only) runs with `enabled: true` until a few real runs look clean — with logs off, `console.log` is visible only live via `npx wrangler tail` and nothing persists after a failed run. Flip back once stable.
+
+### 1.6 Project structure & dependencies
+
+- Main entry file: `index.ts`. Reusable helpers: `helper.ts`.
+- TypeScript under `strict: true` — wrangler bundles it natively, no separate build step; a minimal `tsconfig.json` ships even in dep-free Workers.
+- Don't run `npm run build` or `npm run deploy` in examples.
+- **`package.json` / `package-lock.json` are opt-in, not default.** Create them only when code under `src/` imports an npm package at runtime — a Worker on built-in Web/Workers APIs alone needs no manifest; run wrangler, linters, and one-offs via `npx <tool>`. Add both files the moment the first real dep lands. `node_modules/` stays in `.gitignore` either way.
+
+### 1.7 Environment & configuration
+
+- Use the deployed Cloudflare URL in docs/tests, not `localhost`.
+- Prefer SQLite-based Durable Objects over in-memory-only designs; add classes under `migrations.new_sqlite_classes`.
+
+### 1.8 Cloudflare Secrets Store
+
+Use when the user mentions it. Use the same `binding` name as the `secret_name`.
+
+```jsonc
+"secrets_store_secrets": [
+    { "binding": "CLICKUP_KEY", "store_id": "792206780c0c46e8ba8ade3f21b44eac", "secret_name": "CLICKUP_KEY" }
+]
+```
+
+Access in code: `await env.CLICKUP_KEY.get()`.
+
+### 1.9 Naming
+
+- Repo/dir: `cf-<name>` (e.g. `cf-extract-design`).
+- Worker name: `<name>` — repo name minus the `cf-` prefix.
+- R2 bucket, D1 database, and KV namespace names: equal to the worker name. One name, one resource set.
+
+### 1.10 Vars & secrets
+
+**Non-secret vars live in the `vars` block in `wrangler.jsonc`** — checked in, one source of truth. Vars are configuration, not runtime state; do not move them to the dashboard. A single-tenant application Worker (one deployment — e.g. Apollo) declares them at the top level; a multi-tenant Worker declares per-tenant vars under each `env.<tenant>` block (§11).
+
+**Secrets never touch git.** Local dev: a gitignored `.dev.vars` (`KEY=VALUE` dotenv, auto-loaded by `wrangler dev`) with a committed `.dev.vars.example` listing the keys and placeholder values. Production: `wrangler secret put <NAME>`, a gitignored `.secrets` file pushed with `wrangler secret bulk .secrets` (or shipped with a deploy via `wrangler deploy --secrets-file .secrets`), or the Secrets Store (§1.8). Never log or echo a secret value.
+
+**No `keep_vars`.** Leave it unset (default `false`) — each deploy reconciles vars to exactly what the config declares. `keep_vars` only guards plaintext vars set out-of-band in the dashboard; it never touches secrets — `wrangler secret put` secrets survive every deploy regardless. Only the multi-tenant pattern sets `keep_vars: true` (§11).
+
+**Never name a deployed-value file `.env` or `.env.<anything>`** — `wrangler dev` auto-loads a root `.env` as local dev vars, so a prod-valued `.env` silently becomes the local environment on a fresh clone or in CI. Committed `*.example` files carry keys with placeholder values only.
+
+`.gitignore`: `.dev.vars`, `.secrets`, `.secrets.*`, `.env`, `.env.*`
+
+## 2. Code & Helpers
+
+- Use `generateUuidV7()` in `helper.ts` for IDs (time-sortable UUIDv7).
+- Only `await` what's needed (e.g. `request.json()`, `do.fetch(...)`).
+
+## 3. fetch() Structure
+
+`validateRequest()` first, then `switch (path)` for dispatch. Single `try/catch` wrapping the entire handler. No if-chains, no regex in fetch.
+
+```js
+export default {
+  async fetch(request, env, ctx) {
+    try {
+      const route = validateRequest(request);
+      switch (route.path) {
+        case "monitors":
+          return await handleMonitors({ ...route, env, ctx });
+        default:
+          throw { code: 404, message: "Route not found" };
+      }
+    } catch (error) {
+      console.error("Unhandled error in fetch()", error);
+      return createErrorResponse(
+        error.message || "Internal server error",
+        error.code || 500,
+      );
+    }
+  },
+};
+```
+
+No nested `try/catch` except around WebSocket `send`/`close` (see §9).
+
+## 4. validateRequest()
+
+Lives in `helper.ts`. Parses the URL in one place and returns `{ path, method, query, resourceId, subPath }`; throws `{ code: 400 }` when a path requires a resource ID and none is present.
+
+## 5. Validation
+
+Fail fast with thrown `{ code, message }` (`400` bad input, `401` missing/invalid auth). Validate required fields explicitly — no optional chaining for required fields.
+
+## 6. Errors & Responses
+
+- Throw structured errors: `{ code, message }`. Always `console.error()` with context (path, user, etc.). No empty catch blocks.
+- Response envelope `{ status: 1|0, message, data }` — the shared cross-service contract.
+- `createResponse(data, message, code)` in `helper.ts` bakes CORS in, returns a null body for 204/304, and uses proper HTTP codes; `createErrorResponse(message, code)` delegates to it.
+- CORS is passive: a `CORS_HEADERS` const in `helper.ts`, spread into `createResponse()` — no explicit OPTIONS handler, no wrapper functions. Origin-restricted CORS builds the headers from an allowlist (plus `localhost` in dev), still inside `createResponse()`.
+
+## 7. Handler Signatures
+
+Single destructured object — never positional args. Compose by spreading route with env/ctx: `handleGetStats({ request, env, resourceId })`, not `handleGetStats(request, id, env)`.
+
+## 8. Module Structure
+
+Feature-based folders with `handle.ts` + `helper.ts` pairs. `index.ts` only does dispatch.
+
+| Path | Role |
+| --- | --- |
+| `src/index.ts` | Entry point — dispatch only |
+| `src/helper.ts` | Shared CORS, responses, validation, utilities |
+| `src/database.ts` | Shared D1 queries |
+| `src/<feature>/handle.ts` | Route handlers |
+| `src/<feature>/helper.ts` | Feature-specific helpers & DB ops |
+
+## 9. WebSockets
+
+Standard `WebSocketPair` handshake (`server.accept()`, return 101 with `webSocket: client`). Check `readyState === WebSocket.OPEN` before sending. The only acceptable nested `try/catch`: wrap `send`; in its catch, `close(1011)` inside a bare inner try, then evict the session.
+
+## 10. D1 Schema
+
+Follows the shared database naming and column-type vocabulary; what earns a table and the rest of the design doctrine is the `schema-design` skill.
+
+## 11. Multi-tenant Workers (native environments)
+
+Rare — only when **one Worker codebase ships as several independent tenants** (separate Workers, domains, and data stores from a single `src/`, e.g. `~/dev/auth` → `auth-nuplay`, `auth-nustack`). Use **native wrangler environments**, never one Worker that switches tenant at runtime. For a single-tenant application Worker, §1.10 applies and this section does not.
+
+- **One config, `env.<tenant>` blocks.** The top-level block is **local dev** (`wrangler dev`): a `*-dev` name and placeholder D1/KV ids, simulated locally. Each `env.<tenant>` block is **one production tenant**; deploy it with `wrangler deploy --env <tenant>`.
+- **Named environments never inherit** `vars` / `d1_databases` / `kv_namespaces` / `routes` / `secrets_store_secrets` / `assets` from the top level — **each `env.<tenant>` declares them in full**. Dropping a binding from an env block disables that capability for that one tenant.
+- **Per-tenant non-secret vars live in `env.<tenant>.vars`** — still checked in; one file holds every tenant's config side by side.
+- **Local-dev vars** come from a gitignored `.vars.local`, injected as `--var` by the dev script (the top-level block carries no in-config `vars`).
+- **Per-tenant secrets, never in git** — `wrangler secret put <NAME> --env <tenant>`, or a gitignored per-tenant `.secrets` (e.g. `worker/tenants/<tenant>/.secrets`) pushed with `wrangler secret bulk --env <tenant>`, plus a committed `.secrets.example`. Secrets Store bindings are declared inside each env block.
+- **`keep_vars: true`** (top level) keeps a per-tenant deploy **additive**: tenants inject their non-secret vars via `--var` (or the dashboard), and without it a deploy would wipe them. On secrets it changes nothing (§1.10).
+
+`.gitignore`: `.vars.local`, `.secrets`, `.secrets.*`, `.env`, `.env.*`

package/data/harnesses/apollo/rules/database.md

@@ -1,84 +1,6 @@
 # Database
 
-Fixed conventions for relational schemas in **every** Nurix project — what earns a table, where a fact lives once it does, the key vocabulary, foreign-key doctrine, naming, and column types. A cross-project consistency rule: **one concept, one name, everywhere**. General code naming (variables, files, casing) is [`nomenclature.md`](nomenclature.md); this rule owns the database.
-
-Written for SQLite / Cloudflare D1 + Drizzle (the concrete types below). The names and key vocabulary are engine-agnostic — a Postgres project keeps the same column names and semantics with native types (`uuid`, `timestamptz`, `boolean`).
-
-## 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.
+Naming and the fixed column vocabulary for relational schemas in **every** Nurix project — one concept, one name, everywhere. Written for SQLite / Cloudflare D1 + Drizzle; a Postgres project keeps the same column names and semantics with native types (`uuid`, `timestamptz`, `boolean`). **Design doctrine — what earns a table, state vs. logs, junctions, FK policy, uniqueness traps — is the `schema-design` skill; consult it before any schema change.**
 
 ## Keys & the shared vocabulary
 
@@ -96,36 +18,6 @@ Reference columns name what they point at: `<entity>_id` for a UUID-PK reference
 
 **Every inbound FK to a hub table declares a deliberate `ON DELETE`.** A hub (`users`, `devices`, anything several modules point at) collects edges from teams that never meet, and a single `NO ACTION` among them turns deleting the parent into a constraint error naming neither table. Decide per edge: the child dies with the row (`CASCADE`) or survives it (`SET NULL`, which needs a nullable column) — `NO ACTION` on a hub is a deferred outage, not a default.
 
-## 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.
-
 ## Naming
 
 - **Tables** — `snake_case`, plural noun for what they hold (`users`, `apps`, `devices`).
@@ -134,25 +26,9 @@ Reference columns name what they point at: `<entity>_id` for a UUID-PK reference
 - **Indexes** — `<table>_<col(s)>_idx`; unique `<table>_<col(s)>_unique`; a junction's composite unique reads `<table>_<colA>_<colB>_unique` (`app_user_map_app_user_unique`).
 - **Drizzle mirror** — the exported object is the camelCase table name (`app_user_map` → `appUserMap`); column props are the camelCase of the column (`created_at` → `createdAt`). The `sqliteTable("…")` string and every index name must match the DDL (`init.sql`) exactly — the schema-parity boundary.
 
-## 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.
-
 ## Column types (SQLite / D1)
 
 - **Timestamps** — `created_at` + `updated_at`, both `TEXT NOT NULL DEFAULT (datetime('now'))`, on **every** table — except append-only logs, which carry only `created_at`.
 - **Booleans** — `INTEGER` (Drizzle `integer(…, { mode: "boolean" })`); the `is_*` / `has_*` names are § Naming.
 - **JSON** — `TEXT` (Drizzle `text(…, { mode: "json" })`).
 
-## 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.