@nurix/etna 0.1.2 → 0.2.0

package/README.md

@@ -1,13 +1,6 @@
 # @nurix/etna
 
-CLI to bootstrap a project with a Nurix harness. Produces the same on-disk state as running
-
-```
-/plugin marketplace add nurixlabs/skills
-/plugin install nurix-harness@nurixlabs
-```
-
-inside Claude Code, plus drops the harness's `CLAUDE.md` at the project root. See [`../../harness/README.md`](../../harness/README.md) for what a harness is and why the install model is designed this way.
+CLI to bootstrap a project with a Nurix harness. Copies the harness's `CLAUDE.md`, skills, agents, rules, and scripts into the project so they live with the code — version-controllable, editable per project, and visible without leaving the repo.
 
 ## Usage
 
@@ -17,46 +10,60 @@ From the root of the project you want to bootstrap:
 npx @nurix/etna nurix-harness
 ```
 
-After this completes, three things have changed on disk:
+After this completes:
 
 ```
 your-project/
-├── CLAUDE.md                          ← bundled in this package; the harness's policy
+├── CLAUDE.md             ← harness policy (backup of any existing file is kept)
 └── .claude/
-    └── settings.json                  ← enabledPlugins["nurix-harness@nurixlabs"] = true
-
-~/.claude/settings.json                ← extraKnownMarketplaces["nurixlabs"] registered
+    ├── skills/           ← documentation, introspect, workflow-mapper
+    ├── agents/           ← spec-mode, maintenance, contract-monitor, …
+    ├── rules/            ← general.md, nomenclature.md
+    └── scripts/          ← build-ownership-index.sh, check-doc-drift.sh
 ```
 
-That's the entire footprint. Open Claude Code in the project; on next session start it resolves `nurix-harness@nurixlabs`, clones `nurixlabs/skills` into `~/.claude/plugins/marketplaces/`, fills the plugin cache at `~/.claude/plugins/cache/nurixlabs/nurix-harness/<version>/`, and loads the plugin. The CLI does not touch any of those Claude Code internals itself — that's deliberate (see [Installation goals](../../harness/README.md#installation-goals)).
+That's the entire footprint. Nothing is written outside the project. No marketplace registration, no `enabledPlugins` entry, no global cache dependency — Claude Code picks up project-scoped agents/skills/rules/scripts on its next session start.
 
-If Claude Code is already running, run `/reload-plugins`.
+Re-run `npx @nurix/etna nurix-harness` anytime to refresh the harness content with what the latest published package ships. Existing same-named files are overwritten; files you've added that aren't part of the harness are left alone. The previous `CLAUDE.md` is backed up to `CLAUDE.md.bak.<ISO-timestamp>`.
+
+## Migrating from 0.1.x
+
+`0.1.x` registered the harness as a Claude Code plugin via the `nurixlabs/skills` marketplace. `0.2.0` switches to direct file installation. When you re-run `etna` on a project that has a `0.1.x` install, the CLI removes the stale `enabledPlugins["<plugin>@nurixlabs"]` entry from `<project>/.claude/settings.json` so Claude Code doesn't double-load the same content from the global plugin cache.
+
+The `nurixlabs` marketplace entry in `~/.claude/settings.json` is harmless to leave (it doesn't load anything by itself) — remove it manually if you want.
 
 ## Available harnesses
 
 Listed by `npx @nurix/etna` (no args) using the bundled `data/harness-index.json`.
 
-| Plugin name | Harness folder in etna | What it ships |
+| Plugin name | Source in etna | What it ships |
 |---|---|---|
-| `nurix-harness` | [`harness/code/`](../../harness/code/) | The canonical v7 harness — governance agents, baseline workflow skills, ownership/drift scripts |
+| `nurix-harness` | [`plugins/nurix-harness.md`](../../plugins/nurix-harness.md) → top-level catalogs | Governance agents, baseline workflow skills, ownership/drift scripts |
+| `kb-agi` | [`plugins/kb-agi.md`](../../plugins/kb-agi.md) → top-level catalogs | Knowledge-vault scaffolding |
 
 ## How it works
 
-1. Looks up `<plugin-name>` in the bundled `data/harness-index.json` to find the matching harness folder and the marketplace metadata.
-2. Copies the bundled `data/harnesses/<harness-folder>/CLAUDE.md` to `./CLAUDE.md` (backing up any existing one to `CLAUDE.md.bak.<ISO-timestamp>`).
-3. Adds the marketplace entry to `~/.claude/settings.json` under `extraKnownMarketplaces`.
-4. Adds `<plugin-name>@<marketplace>: true` to `./.claude/settings.json` under `enabledPlugins`.
+Each harness has a folder under `etna/harness/<name>/` with:
+- `CLAUDE.md` — the project-root policy file
+- `index.md` — symlinked to `../../plugins/<plugin>.md` (the manifest)
 
-No GitHub fetch. No `.claude/plugins/<name>/` folder. Claude Code's plugin resolver handles all of that on next launch.
+The plugin manifest's YAML frontmatter declares which top-level `agents/`, `skills/`, `rules/`, and `scripts/` belong to that plugin:
 
-## Why two sources
+```yaml
+---
+name: nurix-harness
+skills: [documentation, introspect, workflow-mapper]
+agents: [spec-mode, maintenance, contract-monitor, …]
+scripts: [build-ownership-index, check-doc-drift]
+rules: [general, nomenclature]
+---
+```
 
-- **Plugin content** lives in the marketplace (`nurixlabs/skills`) and is fetched by Claude Code at session start — always the latest CI-published version.
-- **`CLAUDE.md`** is bundled in this npm package, versioned with the package. A plugin cannot ship a project-root `CLAUDE.md` (Claude Code's plugin spec doesn't support it), so the CLI ships that half itself. Harness policy changes warrant a package version bump.
+`scripts/build-data.js` (run by `prepack`) resolves each manifest against the catalogs and bundles the result into `data/harnesses/<folder>/`. The installer (`bin/etna.js`) reads from that bundle at install time. No GitHub fetch at runtime — the published npm package contains everything.
 
 ## Building / contributing
 
-`data/` is generated. Don't edit by hand. To regenerate after touching anything under `etna/harness/`:
+`data/` is generated. Don't edit by hand. To regenerate after editing the etna catalogs or manifests:
 
 ```sh
 cd packages/cli
@@ -67,4 +74,4 @@ npm run build:data
 
 ## Publishing
 
-CI auto-publishes on push to `dev` when `packages/cli/**` or `harness/**` change — see [`.github/workflows/publish-etna-to-npm.yml`](../../.github/workflows/publish-etna-to-npm.yml). The `publishConfig.access` is `restricted` so the scoped package is private by default.
+CI auto-publishes on push to `dev` when `packages/cli/**` or `harness/**` change — see [`.github/workflows/publish-etna-to-npm.yml`](../../.github/workflows/publish-etna-to-npm.yml). The `publishConfig.access` is `restricted` so the scoped package is private by default. The `NPM_PUBLISH_TOKEN` GitHub Actions secret must be a granular access token with **Bypass 2FA** enabled — classic automation tokens are rejected by the npmjs.com 2FA policy on the `nurix-tools` account.

package/bin/etna.js

@@ -1,12 +1,22 @@
 #!/usr/bin/env node
 // packages/cli/bin/etna.js
-// `npx @nurix/etna <plugin-name>` — bootstrap a Nurix harness in the current directory.
-// Produces the same on-disk state as running `/plugin marketplace add <repo>` followed by
-// `/plugin install <plugin>@<marketplace>` inside Claude Code, plus drops the harness's
-// CLAUDE.md at the project root. Claude Code's plugin resolver fills the cache on next launch.
-
-import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, copyFileSync, lstatSync } from 'node:fs';
-import { homedir } from 'node:os';
+// `npx @nurix/etna <plugin-name>` — copy a Nurix harness into the current
+// directory. Drops the harness's CLAUDE.md at the project root and copies its
+// skills, agents, rules, and scripts into <project>/.claude/. No marketplace,
+// no plugin enablement — files live in the project, version-controlled and
+// editable per project. Re-run `etna` to refresh.
+
+import {
+    existsSync,
+    mkdirSync,
+    readFileSync,
+    writeFileSync,
+    renameSync,
+    copyFileSync,
+    cpSync,
+    readdirSync,
+    lstatSync,
+} from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -14,17 +24,18 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkgRoot = resolve(__dirname, '..');
 const dataDir = join(pkgRoot, 'data');
 
+// Subfolders bundled inside each harness payload that map 1:1 onto
+// <project>/.claude/<name>/. Order matches Claude Code's own folder layout.
+const PLUGIN_SUBDIRS = ['skills', 'agents', 'rules', 'scripts'];
+
 function usage() {
     const idx = loadHarnessIndex();
     console.log(`\nUsage: npx @nurix/etna <plugin-name>\n`);
     const names = Object.keys(idx.plugins);
     if (names.length) {
-        console.log(`Available harnesses (plugin → marketplace):`);
-        for (const name of names) {
-            console.log(`  ${name.padEnd(20)} → ${idx.marketplace.name}`);
-        }
+        console.log(`Available harnesses:`);
+        for (const name of names) console.log(`  ${name}`);
     }
-    console.log(`\nMarketplace: ${idx.marketplace.source.repo} (github)`);
     console.log();
 }
 
@@ -41,6 +52,14 @@ function die(msg, code = 1) {
     process.exit(code);
 }
 
+function isSymlink(path) {
+    try {
+        return lstatSync(path).isSymbolicLink();
+    } catch {
+        return false;
+    }
+}
+
 // Move <path> to <path>.bak.<timestamp> if it exists. Returns the backup path, or null.
 function backupIfExists(path) {
     if (!existsSync(path) && !isSymlink(path)) return null;
@@ -50,14 +69,6 @@ function backupIfExists(path) {
     return backup;
 }
 
-function isSymlink(path) {
-    try {
-        return lstatSync(path).isSymbolicLink();
-    } catch {
-        return false;
-    }
-}
-
 function readJson(path) {
     if (!existsSync(path)) return {};
     try {
@@ -73,27 +84,44 @@ function writeJson(path, value) {
     writeFileSync(path, JSON.stringify(value, null, 2) + '\n');
 }
 
-// Register the marketplace in ~/.claude/settings.json (extraKnownMarketplaces).
-// Mirrors what `/plugin marketplace add <owner>/<repo>` writes.
-function registerMarketplace(marketplace) {
-    const path = join(homedir(), '.claude', 'settings.json');
-    const settings = readJson(path);
-    settings.extraKnownMarketplaces = settings.extraKnownMarketplaces || {};
-    settings.extraKnownMarketplaces[marketplace.name] = { source: marketplace.source };
-    writeJson(path, settings);
-    return path;
+// Copy the harness's bundled .claude/<subdir>/ contents into <project>/.claude/<subdir>/,
+// merging with whatever's already there. Existing same-named entries are overwritten so
+// re-running `etna` always refreshes harness-provided content. Returns count copied.
+function copyHarnessSubdir(bundledSubdir, projectSubdir) {
+    if (!existsSync(bundledSubdir)) return 0;
+    mkdirSync(projectSubdir, { recursive: true });
+    let copied = 0;
+    for (const entry of readdirSync(bundledSubdir, { withFileTypes: true })) {
+        const src = join(bundledSubdir, entry.name);
+        const dest = join(projectSubdir, entry.name);
+        cpSync(src, dest, { recursive: true, force: true });
+        copied += 1;
+    }
+    return copied;
 }
 
-// Add `<plugin>@<marketplace>: true` to <target>/.claude/settings.json under enabledPlugins.
-// Mirrors what `/plugin install <plugin>@<marketplace>` writes at project scope.
-function enablePlugin(targetDir, pluginName, marketplaceName) {
-    const path = join(targetDir, '.claude', 'settings.json');
-    const settings = readJson(path);
-    settings.enabledPlugins = settings.enabledPlugins || {};
-    const key = `${pluginName}@${marketplaceName}`;
-    settings.enabledPlugins[key] = true;
-    writeJson(path, settings);
-    return { path, key };
+// Clean up any leftover marketplace/enabledPlugins entries from a previous 0.1.x
+// install. After 0.2.0 we don't use the marketplace flow at all — leaving stale
+// entries causes Claude Code to also resolve the plugin from the global cache,
+// double-loading the same skills under a different namespace.
+function migrateFromPluginInstall(targetDir, pluginName) {
+    const removed = [];
+    const projectSettingsPath = join(targetDir, '.claude', 'settings.json');
+    if (existsSync(projectSettingsPath)) {
+        const s = readJson(projectSettingsPath);
+        if (s.enabledPlugins) {
+            const keys = Object.keys(s.enabledPlugins).filter((k) =>
+                k.startsWith(`${pluginName}@`),
+            );
+            for (const k of keys) {
+                delete s.enabledPlugins[k];
+                removed.push(`enabledPlugins["${k}"] in ${projectSettingsPath}`);
+            }
+            if (Object.keys(s.enabledPlugins).length === 0) delete s.enabledPlugins;
+            writeJson(projectSettingsPath, s);
+        }
+    }
+    return removed;
 }
 
 async function main(args) {
@@ -111,34 +139,36 @@ async function main(args) {
         );
     }
 
-    const bundledClaude = join(dataDir, 'harnesses', harnessFolder, 'CLAUDE.md');
-    if (!existsSync(bundledClaude)) {
+    const bundledHarnessDir = join(dataDir, 'harnesses', harnessFolder);
+    const bundledClaudeMd = join(bundledHarnessDir, 'CLAUDE.md');
+    if (!existsSync(bundledClaudeMd)) {
         die(`Bundled CLAUDE.md missing for harness '${harnessFolder}'. Rebuild package data.`);
     }
 
     const targetDir = process.cwd();
     const claudeMdDest = join(targetDir, 'CLAUDE.md');
-    const marketplace = idx.marketplace;
-    const fqKey = `${pluginName}@${marketplace.name}`;
 
-    console.log(`\nInstalling ${fqKey} into ${targetDir}`);
+    console.log(`\nInstalling ${pluginName} into ${targetDir}`);
 
     const claudeBackup = backupIfExists(claudeMdDest);
     if (claudeBackup) console.log(`  backed up existing CLAUDE.md → ${claudeBackup}`);
 
-    copyFileSync(bundledClaude, claudeMdDest);
+    copyFileSync(bundledClaudeMd, claudeMdDest);
     console.log(`  installed CLAUDE.md → ${claudeMdDest}`);
 
-    const marketplacePath = registerMarketplace(marketplace);
-    console.log(`  registered marketplace '${marketplace.name}' → ${marketplacePath}`);
+    for (const sub of PLUGIN_SUBDIRS) {
+        const count = copyHarnessSubdir(
+            join(bundledHarnessDir, sub),
+            join(targetDir, '.claude', sub),
+        );
+        if (count > 0) console.log(`  copied ${count} ${sub} → ${targetDir}/.claude/${sub}/`);
+    }
 
-    const { path: enablePath } = enablePlugin(targetDir, pluginName, marketplace.name);
-    console.log(`  enabled '${fqKey}' → ${enablePath}`);
+    const migrated = migrateFromPluginInstall(targetDir, pluginName);
+    for (const entry of migrated) console.log(`  removed stale ${entry}`);
 
     console.log(`\nDone. Open Claude Code in ${targetDir}.`);
-    console.log(
-        `It will fetch ${marketplace.source.repo}, install ${pluginName}, and load it on next session start.\n`,
-    );
+    console.log(`Re-run \`npx @nurix/etna ${pluginName}\` anytime to refresh harness content.\n`);
 }
 
 main(process.argv.slice(2)).catch((e) => {

package/data/harness-index.json

@@ -1,12 +1,6 @@
 {
-    "marketplace": {
-        "name": "nurixlabs",
-        "source": {
-            "source": "github",
-            "repo": "nurixlabs/skills"
-        }
-    },
     "plugins": {
-        "nurix-harness": "code"
+        "nurix-harness": "code",
+        "kb-agi": "kb-agi"
     }
 }

package/data/harnesses/code/CLAUDE.md

@@ -73,6 +73,13 @@ Feature docs in `docs/features/` must include YAML frontmatter with `owns`, `tou
 
 The spec-mode agent checks for ownership conflicts during research. If conflicts are found, address them in the spec before proceeding.
 
+### Architecture Decisions (ADRs)
+
+Record an ADR when a decision (a) changes how state, dependencies, or boundaries are organized, (b) has a rejected alternative worth remembering, and (c) could plausibly be re-litigated. Default: don't write one. Style preferences, local refactors, and obvious-from-code choices don't qualify.
+
+- File: `docs/architecture/adr/NNNN-kebab-case.md` (4-digit sequential number). Frozen once written — supersede via a new ADR, never edit.
+- Invoke the `documentation` skill with "record an ADR" or "architecture decision".
+
 ---
 
 ## Agents
@@ -88,7 +95,7 @@ Seven sub-agents and three skills are defined under `.claude/`. Reach for them b
 | `dep-health` | Agent | Dependency supply-chain audit | "audit dependencies", "check CVEs", "dep health" |
 | `git-history` | Agent | Classify recent commits into a velocity/severity CSV | "classify commits", "commit history report" |
 | `change-review` | Agent | Velocity heatmap, risk zones (high churn + low coverage) | "where is risk accumulating", "velocity report" |
-| `documentation` | Skill | Baseline audit, scaffolding, templates | "baseline docs", "create docs", "audit docs" |
+| `documentation` | Skill | Baseline audit, scaffolding, templates, ADRs, guardrails | "baseline docs", "create docs", "audit docs", "record an ADR", "architecture decision", "create guardrails" |
 | `workflow-mapper` | Skill | Discover and diagram codebase workflows | "map workflows", "trace flows" |
 | `introspect` | Skill | Pre-implementation impact analysis against guardrails | "introspect this plan", "impact analysis" |
 
@@ -140,20 +147,22 @@ Unless explicitly requested:
 
 The six procedural folders below are fixed. Domain folders live as subfolders inside these — `docs/architecture/core/` for core module internals, `docs/features/{feature}/` for deep features. Discovery flows through **[`docs/routing.md`](docs/routing.md)** when present.
 
-| Folder               | Purpose                                                | Mutability            |
-| -------------------- | ------------------------------------------------------ | --------------------- |
-| `docs/architecture/` | System-wide patterns, technical decisions, API specs   | Living                |
-| `docs/features/`     | How implemented features work today                    | Living                |
-| `docs/operations/`   | Setup, development, deployment                         | Living                |
-| `docs/history/`      | Plans, changelogs, backlog                             | Frozen or append-only |
-| `docs/memory/`       | Project knowledge + agent state                        | Living                |
-| `docs/tests/`        | Test plans and automation                              | Living                |
+| Folder                   | Purpose                                                  | Mutability            |
+| ------------------------ | -------------------------------------------------------- | --------------------- |
+| `docs/architecture/`     | System-wide patterns, technical decisions, API specs     | Living                |
+| `docs/architecture/adr/` | Architecture Decision Records — numbered, one per file   | Frozen (supersede)    |
+| `docs/features/`         | How implemented features work today                      | Living                |
+| `docs/operations/`       | Setup, development, deployment                           | Living                |
+| `docs/history/`          | Plans, changelogs, backlog                               | Frozen or append-only |
+| `docs/memory/`           | Project knowledge + agent state                          | Living                |
+| `docs/tests/`            | Test plans and automation                                | Living                |
 
 ### Naming & Lifecycle
 
 - Features: `kebab-case.md` — living reference, status `Active`
 - Plans: `YYYY-MM-DD-kebab-case.md` — frozen after `Complete` or `Abandoned`
 - Changelogs: `YYYY-MM-DD-kebab-case.md` — append-only
+- ADRs: `NNNN-kebab-case.md` (4-digit zero-padded number, sequential) — frozen; supersede via a new ADR
 - Memory: `{agent-name}.md` — agent-maintained
 
 ### Documentation Maintenance

package/data/harnesses/code/agents/change-review.md

@@ -0,0 +1,80 @@
+---
+name: change-review
+description: Velocity analysis — produces commit heatmap, risk-zone identification (high churn + low guardrail coverage), stabilization signals, team distribution. Consumes `git-history`'s CSV output rather than reanalyzing commits. Use when planning where to invest in better guardrails or rules.
+tools: Read, Glob, Grep, Bash
+model: inherit
+---
+
+# Change-Review Agent
+
+You analyze code-change velocity over time to identify risk zones. Where `git-history` classifies *what* changed (module, impact, severity), you ask *where is change accelerating or decelerating* — and whether guardrail coverage matches the risk.
+
+You answer: "where should the tech lead invest in better guardrails or rules next?"
+
+## Before Starting
+
+1. If `./docs/memory/change-review.md` exists, read it for historical velocity snapshots, prior risk-zone flags, and known concentration risks.
+2. If `./docs/memory/git-history.md` or a recent CSV from the git-history agent exists, prefer it as input — don't re-classify commits. If no recent run exists, ask the user to run `git-history` first or fall back to a direct `git log` analysis.
+3. Read `./docs/operations/guardrails.md` if it exists. Risk-zone scoring is "high churn + low guardrail coverage" — without guardrails, you can only produce a heatmap, not risk zones.
+4. Read `./docs/OWNERSHIP_INDEX.md` if it exists, to map churn to owning feature docs.
+
+## Step 1: Velocity Heatmap
+
+Compute commits-per-module over rolling windows:
+
+- **1 week** — what's hot right now
+- **1 month** — current rhythm
+- **3 months** — quarter-level pattern
+
+Aggregate by top-level module (`src/{module}/`). Report:
+
+| Module | Commits 1w | Commits 1m | Commits 3m | Trend |
+|--------|-----------:|-----------:|-----------:|-------|
+
+Trend column: ↑ rising, ↓ falling, → steady, ↑↑ sharply rising, ↓↓ sharply falling.
+
+## Step 2: Risk Zones
+
+For each module with high churn (top quartile in 1m window), check guardrail coverage:
+
+- Does `docs/operations/guardrails.md` mention this module?
+- Is the module's `owns` doc up to date? (cross-reference with maintenance agent's last drift check if available)
+- Does the module appear in `docs/routing.md`?
+
+Flag risk zones: high churn × low coverage. These are where silent breakage is most likely.
+
+## Step 3: Stabilization Signals
+
+Identify modules where 1-week and 1-month velocity are both decreasing. Candidates for reducing review overhead — fewer guardrails needed where churn is dropping.
+
+## Step 4: Team Distribution
+
+Per module, list which authors made the most commits in the 3-month window. Surface concentration risks:
+
+- One author > 70% of commits in a critical module → bus-factor flag
+- One author owns all changes touching a guardrail → review-coverage flag
+
+## Step 5: Report & Track
+
+### Report format
+
+- **Velocity heatmap** (table above)
+- **Risk zones**: top 5 high-churn / low-coverage modules with specific guardrails to consider adding
+- **Stabilization signals**: modules where review overhead can decrease
+- **Concentration risks**: bus-factor and review-coverage flags
+- **Recommendations**: prioritized list — typically "add guardrail for X", "update routing.md to cover Y", "spread reviews of Z across more authors"
+
+### Update tracking
+
+1. Write snapshot to `docs/memory/change-review.md` with date and all four sections above
+2. Append items to `docs/history/backlog.md`:
+   - `- **[P1]** No guardrail coverage for high-churn module \`src/{name}/\` — discovered by change-review`
+3. Report summary to the user
+
+## Rules
+
+- Prefer git-history's CSV as input; only fall back to direct `git log` analysis if no recent CSV exists
+- Read-only for source code
+- May write to `docs/memory/change-review.md` and `docs/history/backlog.md`
+- Risk-zone identification requires guardrails — if `guardrails.md` doesn't exist, produce heatmap only and tell the user that risk-zone scoring needs documented guardrails
+- A clean report (no risk zones) is valid for a low-churn, well-covered project

package/data/harnesses/code/agents/contract-monitor.md

@@ -0,0 +1,65 @@
+---
+name: contract-monitor
+description: Post-implementation contract auditor. Scans the live codebase for violations of cross-module contracts documented in `docs/operations/guardrails.md` — unregistered entity types, string-coupled constants, cross-entity references without propagation, schema mismatches, undocumented endpoints. Run on request after significant merges. Pairs with the `introspect` skill (which runs pre-implementation).
+tools: Read, Glob, Grep, Edit, Write, Bash
+model: inherit
+---
+
+# Contract Monitor
+
+You scan the codebase for cross-module contract violations. Where the `introspect` skill checks _before_ implementation (against a plan), you check _after_ — against the live codebase. On a team with multiple developers making concurrent changes, contract violations emerge from the interaction of individually-correct changes; no single plan introspection can catch these.
+
+## Before Starting
+
+1. Read `./docs/operations/guardrails.md` — this is your source of truth for which contracts exist. If it doesn't exist, stop and tell the user a guardrails doc is required.
+2. If `./docs/memory/contract-monitor.md` exists, read it for known exceptions, historical violation counts, and patterns the user has chosen not to fix.
+3. If `./docs/routing.md` exists, read it for module ownership context.
+
+## Scan
+
+For each guardrail section in `guardrails.md`:
+
+1. Parse the section — extract contract name, canonical source location, consumer paths, violation description, checklist (if any)
+2. Scan the codebase for violations of that specific contract. Categories to check:
+   - **Unregistered entity types** — strings used as entity-type identifiers that aren't in the canonical array
+   - **String-coupled constants** — raw string literals used where shared constant imports are required
+   - **Cross-entity references without propagation** — storing entity A's slug/name/id by value in entity B without documented propagation
+   - **Schema mismatches** — selectors accessing persisted fields without fallback defaults
+   - **Undocumented API endpoints** — routes in code with no corresponding feature doc or guardrail entry
+3. Verify by reading actual source files — never guess.
+
+## Act
+
+For each violation:
+
+- **Mechanical fix** (missing constant import, missing fallback default, missing entry in canonical array) → fix it directly with an Edit
+- **Design-decision fix** (new entity type registration, new cross-entity propagation mechanism, schema migration) → append to `docs/history/backlog.md` as P0 or P1 with the specific guardrail and consumer paths
+- **Pre-existing exception** (recorded in `docs/memory/contract-monitor.md`) → skip silently; don't re-flag
+
+## Report
+
+Present a structured report:
+
+| # | Guardrail | Violation | Location | Action taken |
+|---|-----------|-----------|----------|--------------|
+
+Then update `docs/memory/contract-monitor.md` with:
+- Scan date
+- Violation counts per guardrail
+- Items fixed mechanically (with file paths)
+- Items backlogged (with P-level and rationale)
+- New exceptions added (if any)
+
+## Optional: extend guardrails
+
+If you discover patterns in code that should be guardrails but aren't yet documented:
+
+1. Surface the candidate guardrail to the user with a draft entry
+2. Wait for approval before writing to `guardrails.md` — never add a guardrail unilaterally
+
+## Rules
+
+- Never delete feature docs or modify frozen records (`docs/history/plans/`, `docs/history/changelog/`)
+- Be specific: include file paths, line numbers, and the exact violating string
+- Respect known-exceptions in `docs/memory/contract-monitor.md`
+- A clean report is valid — do not invent violations