@nurix/etna 0.15.7 → 0.16.0

package/data/harnesses/code-fable/hooks/session-reflect.js

@@ -0,0 +1,283 @@
+// plugins/code/hooks/session-reflect.js — SessionEnd hook: reflect the session into durable lessons (headless haiku pass) appended to the actor's memory inbox.
+
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { execFileSync, spawn } = require("child_process");
+const { redact } = require("./lib/redact.js");
+
+// A session below all three thresholds carries no lesson worth a model call.
+const MIN_TURNS = 8;
+const MAX_MESSAGE_CHARS = 1500;
+const MAX_DIGEST_CHARS = 80000;
+const MAX_LESSONS = 6;
+
+// Read all of stdin synchronously; returns "" if nothing is piped.
+function readStdin() {
+  try {
+    return fs.readFileSync(0, "utf8");
+  } catch (e) {
+    return "";
+  }
+}
+
+// Resolve the project root: CLAUDE_PROJECT_DIR env, else payload cwd, else process cwd.
+function resolveProjectDir(payload) {
+  return process.env.CLAUDE_PROJECT_DIR || (payload && payload.cwd) || process.cwd();
+}
+
+// Run a git command in projectDir; returns trimmed stdout or fallback on any error.
+function git(projectDir, args, fallback) {
+  try {
+    return execFileSync("git", ["-C", projectDir, ...args], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim() || fallback;
+  } catch (e) {
+    return fallback;
+  }
+}
+
+// Slug a raw actor name into kebab-case ASCII.
+function slugActor(name) {
+  return String(name || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+// Determine the actor: git user.name (slugged) → $USER → "agent".
+function resolveActor(projectDir) {
+  const fromGit = slugActor(git(projectDir, ["config", "user.name"], ""));
+  if (fromGit) return fromGit;
+  const fromEnv = slugActor(process.env.USER || "");
+  if (fromEnv) return fromEnv;
+  return "agent";
+}
+
+// Truncate a single line to n chars with an ellipsis marker.
+function clip(text, n) {
+  const clean = String(text || "").replace(/\s+/g, " ").trim();
+  return clean.length > n ? clean.slice(0, n) + "…" : clean;
+}
+
+// Extract plain text from a message whose content is a string or content-block array.
+function extractText(msg) {
+  if (!msg || !msg.content) return "";
+  if (typeof msg.content === "string") return msg.content;
+  if (Array.isArray(msg.content)) {
+    return msg.content
+      .filter((b) => b && b.type === "text" && typeof b.text === "string")
+      .map((b) => b.text)
+      .join(" ");
+  }
+  return "";
+}
+
+// Strip harness-injected wrappers so only what the user actually typed survives.
+function stripInjected(text) {
+  return String(text || "")
+    .replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, "")
+    .replace(/<(local-command-caveat|local-command-stdout|local-command-stderr|command-name|command-message|command-args|command-contents)>[\s\S]*?<\/\1>/g, "")
+    .trim();
+}
+
+// Scan an assistant message's tool_use blocks for edited files and git commits.
+function collectToolUse(msg, summary) {
+  if (!msg || !Array.isArray(msg.content)) return;
+  for (const block of msg.content) {
+    if (!block || block.type !== "tool_use") continue;
+    const name = block.name || "";
+    const input = block.input || {};
+    if (/^(Edit|Write|MultiEdit|NotebookEdit)$/.test(name) && input.file_path) {
+      summary.files.add(input.file_path);
+    }
+    if (name === "Bash" && typeof input.command === "string" && /\bgit\s+commit\b/.test(input.command)) {
+      summary.sawCommit = true;
+    }
+  }
+}
+
+// Walk the JSONL transcript once: turn/edit/commit counts plus a USER/ASSISTANT text digest.
+function digestTranscript(transcriptPath) {
+  const out = { turns: 0, files: new Set(), sawCommit: false, lines: [] };
+  if (!transcriptPath || !fs.existsSync(transcriptPath)) return out;
+  for (const line of fs.readFileSync(transcriptPath, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    let row;
+    try {
+      row = JSON.parse(line);
+    } catch (e) {
+      continue;
+    }
+    if (row.isSidechain) continue;
+    const msg = row && row.message ? row.message : row;
+    const role = (msg && msg.role) || row.type;
+    if (role === "user") {
+      const text = stripInjected(extractText(msg));
+      if (!text || text.startsWith("Caveat: The messages below")) continue;
+      out.lines.push("USER: " + clip(text, MAX_MESSAGE_CHARS));
+    } else if (role === "assistant") {
+      out.turns += 1;
+      collectToolUse(msg, out);
+      const text = extractText(msg);
+      if (text) out.lines.push("ASSISTANT: " + clip(text, MAX_MESSAGE_CHARS));
+    }
+  }
+  return out;
+}
+
+// Compute the per-actor inbox file path.
+function inboxPath(projectDir, actor) {
+  const dir = path.join(projectDir, "docs", "memory", "inbox");
+  return { dir, file: path.join(dir, `${actor}.md`) };
+}
+
+// True when this session already wrote an inbox entry (SessionEnd re-fires on resume).
+function alreadyReflected(file, sessionId) {
+  try {
+    return Boolean(sessionId) && fs.existsSync(file) && fs.readFileSync(file, "utf8").includes(`session ${sessionId}`);
+  } catch (e) {
+    return false;
+  }
+}
+
+// Build the inbox file header block.
+function inboxHeader(actor) {
+  return `# Memory inbox — ${actor}\nSession lessons awaiting distillation — appended by the session-reflect hook, consumed by \`distiller facts\`.\n`;
+}
+
+// The full output contract sits AFTER the transcript — with it only up front, the model
+// continues the conversation in the transcript instead of reflecting on it.
+const PROMPT_HEADER = [
+  "You are a memory reflector. Below is the transcript of a FINISHED coding session,",
+  "delimited by <transcript> tags. Do not reply to it or continue it — you will be asked",
+  "to extract durable lessons from it after the closing tag.",
+  "",
+  "<transcript>",
+  "",
+].join("\n");
+
+const PROMPT_FOOTER = [
+  "",
+  "</transcript>",
+  "",
+  "The session above is over. Extract ONLY durable lessons a future session in this",
+  "repository would benefit from knowing:",
+  "- corrections or preferences the user stated",
+  "- failures whose root cause was found, with the fix",
+  "- decisions made, with their rationale",
+  "- discovered constraints or non-obvious facts about the project or its tooling",
+  "Rules:",
+  "- Most sessions contain none. If nothing qualifies, output exactly: NONE",
+  `- Otherwise output at most ${MAX_LESSONS} bullets and nothing else — no preamble, no headers.`,
+  '- Each bullet starts with "- [project]" (true of this repo or its tooling) or "- [user]" (true of this user).',
+  "- Each bullet is one complete, self-contained sentence with names and identifiers spelled out.",
+  "- Routine work (commits made, files edited, tasks completed) is NOT a lesson. Never include secrets.",
+].join("\n");
+
+// Hook mode: stash the payload and hand off to a detached worker so session exit is never delayed.
+function hook() {
+  const raw = readStdin();
+  let payload = {};
+  try {
+    payload = raw ? JSON.parse(raw) : {};
+  } catch (e) {
+    payload = {};
+  }
+  if (!payload.transcript_path) return;
+
+  const stash = {
+    projectDir: resolveProjectDir(payload),
+    transcriptPath: payload.transcript_path,
+    sessionId: payload.session_id || "",
+  };
+  const stashFile = path.join(os.tmpdir(), `etna-reflect-${stash.sessionId || process.pid}.json`);
+  fs.writeFileSync(stashFile, JSON.stringify(stash), "utf8");
+  spawn(process.execPath, [__filename, "--worker", stashFile], { detached: true, stdio: "ignore" }).unref();
+}
+
+// Worker mode: filter, digest, run the reflection model, append surviving lessons to the inbox.
+function worker(stashFile) {
+  let stash;
+  try {
+    stash = JSON.parse(fs.readFileSync(stashFile, "utf8"));
+  } finally {
+    try {
+      fs.rmSync(stashFile, { force: true });
+    } catch (e) {
+      // Stale stash files are harmless.
+    }
+  }
+
+  const { projectDir, transcriptPath, sessionId } = stash;
+  const digest = digestTranscript(transcriptPath);
+  if (digest.turns < MIN_TURNS && digest.files.size === 0 && !digest.sawCommit) return;
+
+  const actor = resolveActor(projectDir);
+  const { dir, file } = inboxPath(projectDir, actor);
+  if (alreadyReflected(file, sessionId)) return;
+
+  let text = redact(digest.lines.join("\n"));
+  if (text.length > MAX_DIGEST_CHARS) {
+    text = text.slice(0, 8000) + "\n[... middle of session elided ...]\n" + text.slice(-(MAX_DIGEST_CHARS - 8000));
+  }
+
+  const output = execFileSync("claude", ["-p", "--model", "haiku"], {
+    input: PROMPT_HEADER + text + PROMPT_FOOTER,
+    encoding: "utf8",
+    cwd: os.tmpdir(),
+    env: Object.assign({}, process.env, { ETNA_REFLECT: "1" }),
+    timeout: 240000,
+    maxBuffer: 4 * 1024 * 1024,
+    stdio: ["pipe", "pipe", "ignore"],
+  });
+
+  const lessons = output
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => /^- \[(project|user)\]\s+\S/.test(l))
+    .slice(0, MAX_LESSONS)
+    .map((l) => redact(l));
+  if (!lessons.length) return;
+
+  const repo = path.basename(projectDir);
+  const branch = git(projectDir, ["rev-parse", "--abbrev-ref", "HEAD"], "-");
+  const now = new Date();
+  const pad = (n) => String(n).padStart(2, "0");
+  const stamp = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())} ${pad(now.getHours())}:${pad(now.getMinutes())}`;
+
+  fs.mkdirSync(dir, { recursive: true });
+  if (alreadyReflected(file, sessionId)) return;
+  const exists = fs.existsSync(file);
+  const block =
+    (exists ? "\n" : inboxHeader(actor) + "\n") +
+    `## ${stamp} · session ${sessionId || "unknown"} · ${repo}@${branch}\n` +
+    lessons.join("\n") +
+    "\n";
+  fs.appendFileSync(file, block, "utf8");
+}
+
+function main() {
+  if (process.env.ETNA_REFLECT) return;
+  const workerIdx = process.argv.indexOf("--worker");
+  if (workerIdx !== -1) {
+    worker(process.argv[workerIdx + 1]);
+  } else {
+    hook();
+  }
+}
+
+try {
+  main();
+} catch (e) {
+  try {
+    process.stderr.write(`session-reflect hook: ${e && e.message ? e.message : e}\n`);
+  } catch (e2) {
+    // Nothing more we can do.
+  }
+} finally {
+  process.exit(0);
+}

package/data/harnesses/code-fable/rules/general.md

@@ -0,0 +1,96 @@
+---
+applyTo: "**"
+---
+
+# Technology Choices & Standards
+
+Opinionated technology stack and implementation standards.
+
+## Environment & Versions
+
+### Runtime Versions
+
+- **Node.js:** 22 LTS (latest)
+- **Package manager:** project-determined — detect from lockfile (`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `package-lock.json` → npm). Use the matching command in scripts; don't hardcode a specific manager.
+- **PostgreSQL:** 17
+- **Redis:** 7.x (latest)
+
+### Recommended Packages
+
+No alternatives. No explanations for obvious choices. Just use these.
+
+| 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          | fetch                   |
+| date-fns                 | ^4.1.0    | Date formatting        | moment, dayjs           |
+| @dnd-kit/core            | ^6.3.1    | Drag and drop          | react-beautiful-dnd     |
+| 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                   | ^5.1.6    | ID generation          | uuid                    |
+| express                  | ^5.2.1    | HTTP server            | fastify, koa            |
+| prisma                   | ^7.2.0    | Database ORM           | sequelize, typeorm      |
+| @prisma/client           | ^7.2.0    | Database queries       | -                       |
+| 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                    | ^3.22.0   | Syntax highlighting    | prism, highlight.js     |
+| lucide-react             | ^0.562.0  | Icons                  | react-icons, heroicons  |
+| @pdfme/generator         | ^5.5.8    | 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              |
+| socket.io-client         | ^4.7.0    | WebSocket client       | native WebSocket, ws    |
+| react-markdown           | ^10.1.0   | Markdown rendering     | marked, markdown-it     |
+| 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                 |
+
+---
+
+## Express 5.x Setup
+
+```javascript
+app.use(cors({ origin: process.env.FRONTEND_URL }));
+app.use(compression());
+app.use(express.json({ limit: "10mb" }));
+app.use(rateLimit({ windowMs: 15 * 60 * 1000, max: 100 }));
+```
+
+- Middleware order: body parsers, custom middleware, routes, error handlers
+- Use Express Router for modular routes
+- Centralized error handler as last middleware
+- Use middleware for auth
+
+---
+
+## API Response Format
+
+```json
+{
+    "status": 1,
+    "message": "Message sent successfully",
+    "data": { "delivered": [{ "user@example.com": 2 }] }
+}
+```
+
+**Error:**
+
+```json
+{
+    "status": 0,
+    "message": "Error description",
+    "data": null
+}
+```
+
+HTTP codes: `200`, `201` (created), `400`, `401` (not authenticated), `403` (not authorized), `404`, `500`

package/data/harnesses/code-fable/rules/nomenclature.md

@@ -0,0 +1,34 @@
+---
+applyTo: "**"
+---
+
+# Nomenclature Guidelines
+
+## Naming Guidelines
+
+- Use descriptive names that reveal intent, purpose, and usage
+- Names should explain why something exists and how it's used
+- Favor clarity over brevity
+- Maintain consistency within the codebase
+- Avoid abbreviations unless they're universally understood
+
+## Naming Styles
+
+- Variables : Use nouns or noun phrases. Examples: `userData`, `firstName`, `paymentStatus`, `configOptions`
+- Functions & Methods : Use verbs or verb phrases that describe the action. Examples: `calculateTotal`, `getUserInfo`, `validateInput`, `sendNotification`
+- Boolean Variables : Prefix with is**, has**, can**, or should**. Examples: `isValid`, `hasPermission`, `canEdit`, `shouldRefresh`
+- Arrays : Use plural nouns. Examples: `users`, `productList`, `errorMessages`, `activeConnections`
+- Classes & Components : Use singular nouns or noun phrases. Examples: `RequestHandler`, `UserProfile`, `PaymentProcessor`, `DataValidator`
+- Constants : Use uppercase with meaningful names. Examples: `DEFAULT_TIMEOUT`, `API_BASE_URL`, `MAX_RETRY_COUNT`, `COLOR_PRIMARY`
+- Event Handlers : Use Prefix with handle or on. Examples: `handleSubmit`, `onUserLogin`, `handleInputChange`, `onPageLoad`
+- Interfaces & Types : Use Consider prefixing with I for interfaces (if preferred). Examples: `IUserData`, `IConfigOptions`, `AuthResponse`, `RequestParams`
+- Promises & Async Functions : Use Consider using future tense or suffixes like Async. Examples: `fetchUserData`, `getUserProfileAsync`, `loadConfigAsync`, `processPayment`
+- File & Folder Structure : Use lowercase with descriptive names. Group by feature or function type. Example: `auth/login_service.js`
+
+## Casing Styles
+
+- camelCase : Used in Variables, function names, method names, property names. Examples: `userData`, `calculateTotal`, `firstName`, `isValidEmail`
+- PascalCase : Used in Class names, component names, type definitions. Examples: `UserProfile`, `DataService`, `AuthProvider`, `RequestHandler`
+- snake_case : Used in File names, folder names. Examples: `user_service`, `api_utils`, `auth_middleware`, `data_models`
+- UPPER_SNAKE_CASE : Used in Constants, environment variables. Examples: `MAX_RETRY_COUNT`, `API_KEY`, `DEFAULT_TIMEOUT`, `COLOR_PRIMARY`
+- kebab-case : Used in URLs, CSS class names, HTML IDs. Examples: `nav-container`, `user-profile`, `button-primary`, `form-wrapper`

package/data/harnesses/code-fable/skills/boundary/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: boundary
+description: The single home for a repo's typed application boundaries — the cross-cutting contracts (db-schema, wire envelope, store shape, auth, tenancy, event schemas, edge bindings, …) where editing one module silently breaks another. One skill, four modes — `generate` (baseline all boundaries from the detected stack + IA), `create` (add/update one boundary), `check` (pre-implementation: does this plan touch a boundary? severity-ranked impact), `init` (reconcile: ensure files exist, scan live code for violations + drift, backfill new catalog types). All four read one shared knowledge root, `references/boundary-taxonomy.md`, so they can never drift apart. Triggers on "application boundary", "baseline boundaries", "map boundaries", "generate boundaries", "create a boundary", "introspect", "check this plan", "impact analysis", "what could break", "scan for boundary violations", "boundary drift", "/boundary".
+---
+
+# Application Boundary Skill
+
+The one place a repo's **typed application boundaries** are produced, checked, and
+maintained. A boundary is a horizontal cross-cutting contract — an *edge* between
+modules, layers, services, or deploy units — where editing one side silently
+breaks another. They live as one file per boundary in `docs/boundaries/`.
+
+This skill merges what used to be three components — `boundary-mapper` (produce),
+`introspect` (pre-impl check), `contract-monitor` (post-impl scan) — into one
+skill with four modes. The reason they're one skill: **all four share a single
+knowledge root** — [`references/boundary-taxonomy.md`](references/boundary-taxonomy.md),
+the exhaustive catalog of *what an application boundary is* and *which kinds
+exist* (≈170 types across persistence, wire/API, frontend, auth/tenancy,
+async/messaging, config/build, runtime/infra). Three separate components meant
+three copies of that mental model that drifted apart. One skill, one catalog,
+zero drift.
+
+> **Read [`references/boundary-taxonomy.md`](references/boundary-taxonomy.md)
+> first, in every mode.** It carries the boundary-file anatomy, the
+> `point`-vs-`transcribe` doc-mode, the technology/domain split, the per-type
+> severities, and the safe-change checklists. This SKILL.md only orchestrates the
+> four verbs over that knowledge.
+
+---
+
+## Picking a mode
+
+| You want to… | Mode | Old component |
+|---|---|---|
+| Baseline a repo — generate every boundary that exists from the stack + IA | **`generate`** | boundary-mapper (baseline) |
+| Add or update **one** boundary file | **`create`** | boundary-mapper (create/update) |
+| Before coding: does this **plan** touch a boundary? Severity-ranked impact | **`check`** | introspect |
+| Reconcile: do files exist? scan **live code** for violations + drift; backfill new catalog types | **`init`** | contract-monitor + drift + catalog-sync |
+
+If the user's intent is ambiguous, ask which mode. `generate` and `create` are the
+same writer at different scope (`generate` = `create` over every detected
+boundary).
+
+## Execution model — pure skill
+
+This skill runs **in the main session** — no standing sub-agents. `check` and
+`create` are light and always run inline. `generate` and `init` sweep the
+codebase; run that sweep inline too. **Only** for an unusually large repo (where
+an inline full-codebase sweep would blow the context budget) may you dispatch a
+**one-shot scan worker** sub-agent that reads this same taxonomy reference and
+returns structured findings — the knowledge still lives in exactly one place.
+Default to inline; reach for a worker only when the repo's size forces it.
+
+## Before any mode
+
+1. Read [`references/boundary-taxonomy.md`](references/boundary-taxonomy.md) — the
+   boundary types, doc-modes, default severities, and safe-change checklists for
+   the stack you're about to touch.
+2. If `docs/memory/boundary.md` exists, read it for project-specific
+   boundary exceptions, known violations the user chose not to fix, where the IA
+   model actually lives, and stack quirks that change a doc-mode.
+3. If `docs/routing.md` exists, read it for module-ownership context.
+
+---
+
+## Mode: `generate` (baseline)
+
+No `docs/boundaries/` yet (or a from-scratch re-baseline). Detect the stack + IA,
+instantiate one file per boundary that actually exists.
+
+1. **Detect the stack** — read `package.json` (deps), the lockfile, and skim the
+   source tree. Map detected technologies to their boundary types via the
+   taxonomy. (Detect the package manager from the lockfile; don't assume.)
+2. **Detect the information architecture** — read `docs/architecture/`
+   (domain-model, ADRs), doctrine in any `docs/modules/*/pillars/`, and the
+   entity/contract definitions (a `@org/contracts` package, `schema.ts`,
+   `models.py`). The IA entity model is the flagship `domain` boundary
+   (`information-architecture`).
+3. **For each boundary the repo exhibits**, write one file to `docs/boundaries/`
+   using the boundary-file anatomy. Decide `point` vs `transcribe` per the
+   taxonomy: `point` boundaries get a `file:line` pointer + invariants +
+   checklist (never a transcribed copy — it rots); `transcribe` boundaries (the
+   composed store tree, the response envelope, the IA topology, tenancy) get the
+   contract canonically in the file.
+   - **Greenfield branch — contract decided, no code yet.** If the repo is
+     pre-code (ADRs/domain-model decide the contract but the source module isn't
+     scaffolded), a `point` boundary has no `file:line` to mirror. Don't skip it
+     and don't fabricate a pointer — per the taxonomy's *Greenfield / pre-code
+     boundaries*, emit it as **conventions-with-planned-pointer**: record the
+     decided conventions inline, carry a `planned <path>` pointer, mark it `point*`
+     (a pre-code `transcribe` source is `transcribe*`), and make the last
+     safe-change item "replace the planned pointer with the real `file:line` once
+     code lands." Link any item that hinges on an unresolved decision to its
+     open-question/ADR.
+4. **Set severity** from the taxonomy default, adjusted by the concrete repo +
+   project memory. Severity is load-bearing — it drives `check` review depth and
+   `init` scan priority.
+5. **Name the bounding code units** (paths / package names) in every `Bounds`
+   line. The distinct vertices named across all `Bounds` lines are the
+   **module-discovery feed** `harness-manager` reads to propose modules — name
+   them precisely.
+6. **Write `docs/boundaries/README.md`** as the index per the taxonomy's index
+   spec: a table with a **Doc-mode column**
+   (`| Boundary | Type | Severity | Doc-mode | Bounds (summary) |`), then the
+   standing blocks — **Active technology packs**, **Folds applied** (which catalog
+   types collapsed into which file — surface the per-entry fold-notes as a ledger),
+   and **Skipped** (types omitted + one-line reason each). Add the `point*`/`transcribe*`
+   footnote if any boundary is pre-code.
+7. **Don't invent boundaries the repo doesn't have.** Only instantiate types the
+   detected stack/IA actually exhibits; `log()` what you skipped and why.
+
+Write only under `docs/boundaries/` and `docs/memory/boundary.md`.
+Read-only on production code.
+
+## Mode: `create` (targeted)
+
+Add or update a single boundary file (e.g. a new contract surfaced by `check`, or
+a boundary the author asks for by name).
+
+1. Identify the boundary type from the taxonomy; confirm the repo exhibits it.
+2. Write/update the one file with the full anatomy (Bounds, Shape, Invariants,
+   Blast radius, Safe-change checklist), `point` or `transcribe` per the taxonomy.
+3. Update `docs/boundaries/README.md` (add/refresh the index row).
+4. For an **update** that fixes drift (the `maintenance` agent flags a boundary
+   file drifted from its source): re-read the source, refresh the `Shape` pointer
+   or transcription, leave invariants/checklist intact unless they changed.
+
+## Mode: `check` (pre-implementation)
+
+Read-only. Intersect a plan's proposed changes with the documented boundaries and
+surface cascading risk *before* coding. (This is the old `introspect`.)
+
+**Inputs.** Plan path (user-provided; else newest in `docs/history/plans/`). Every
+file in `docs/boundaries/` is mandatory input — if the folder is missing/empty,
+stop and tell the user to run `generate` first. Source files read on demand to
+verify — never guess from plan text alone.
+
+1. **Load.** Resolve + read the plan; confirm it has a `Status:` (warn if
+   `Complete`/`Abandoned`). Read every boundary file; parse the
+   `[BOUNDARY: type · severity]` header + Bounds / Shape / Invariants / Blast
+   radius / Safe-change checklist. Severity sets review depth.
+2. **Parse proposed changes.** The plan template's **Proposed Changes**
+   subsections are load-bearing: New Files / Modified Files (check against the
+   modules each boundary **Bounds** and any `Shape` `file:line`) · New Entities /
+   State (vs `information-architecture` + `db-schema`) · API Changes (vs
+   `wire-response-envelope` / `rest-endpoint-shape` / `graphql-schema`) ·
+   Cross-Module Contracts Affected (the author's own admission — start there,
+   then verify). Note any missing subsection.
+3. **Analyze each boundary × change pair** for: **Bounds overlap** (touches a
+   bounded module or a `Shape` pointer), **Invariant overlap** (introduces a
+   shape the invariants prohibit — raw literal where a shared constant is
+   required, entity type not in the canonical array, persisted field without
+   fallback), **Shape overlap** (modifies the canonical Shape). Read the actual
+   source to verify any plausible intersection.
+4. **Assign severity.** Anchor to the boundary's own severity (the floor),
+   adjust by the concrete change. Critical = silent data loss / corrupted
+   persistence / broken cross-entity refs; High = stale state / broken lookups /
+   schema selectors without fallbacks; Medium = likely-to-drift string-coupling;
+   Low = code smell.
+5. **Report** (in chat — never written to disk):
+
+   ```
+   # Application Boundary — check — {plan filename}
+
+   Plan: {path}
+   Boundaries: {N} files evaluated
+   Intersections: {N} ({critical}/{high}/{medium}/{low})
+
+   ## Violations
+   | # | Boundary | Risk | Severity | Plan step |
+
+   ## Suggested Plan Additions
+   - Violation #1 → add step X to Implementation Steps / Done Criteria …
+
+   ## Missing Subsections
+   ## New Cross-Module Contracts Detected
+   {describe the proposed boundary (type, Bounds, Shape, suggested severity) and
+    recommend running `create` to formalize it — do not write the file from check}
+   ```
+
+The severity-ranked table is the load-bearing output. Suggestions are advisory —
+the user folds them back into the plan; **`check` never edits the plan or code.**
+
+## Mode: `init` (reconcile — ensure, scan, backfill)
+
+Ensure boundaries are initialized and current. Three jobs in one pass:
+
+1. **Ensure exist.** If `docs/boundaries/` is missing/empty → this is really a
+   baseline; run `generate` instead and stop.
+2. **Scan live code for violations** (the old `contract-monitor`). For each
+   boundary file, parse its header + invariants, then scan the codebase for
+   violations of *that* boundary. Categories: **unregistered entity types**
+   (strings used as entity-type ids not in the canonical array) · **string-coupled
+   constants** (raw literals where a shared constant import is required) ·
+   **cross-entity references without propagation** (storing entity A's
+   slug/name/id by value in B with no documented propagation) · **schema
+   mismatches** (selectors hitting persisted fields without a fallback default) ·
+   **undocumented endpoints** (routes with no feature-doc / `api` boundary entry).
+   Verify by reading actual source — never guess.
+3. **Detect drift + backfill the catalog.** (a) Flag any boundary file whose
+   `Shape` has drifted from its source (refresh it via `create`/update). (b)
+   Compare the taxonomy's boundary *types* against what the repo now exhibits —
+   if the repo gained a technology (or the catalog gained a type) that the repo
+   exhibits but `docs/boundaries/` lacks, surface it and offer to `generate` that
+   one boundary.
+
+**Act on violations.** Mechanical fix (missing constant import, missing fallback,
+missing canonical-array entry) → fix directly with an Edit. Design-decision fix
+(new entity-type registration, new propagation mechanism, schema migration) →
+append to `docs/history/backlog.md` as P0/P1 with the specific boundary + bounded
+modules. Pre-existing exception (in `docs/memory/boundary.md`) → skip
+silently.
+
+**Report** a table `| # | Boundary | Violation | Location | Action taken |`, then
+update `docs/memory/boundary.md` with scan date, per-boundary
+violation counts, items fixed / backlogged, new exceptions, and any
+newly-exhibited boundary types backfilled.
+
+---
+
+## Rules
+
+- **One knowledge root.** Every mode reads `references/boundary-taxonomy.md`.
+  Extend the catalog there, never inline a divergent copy in a mode.
+- **`check` is read-only** — never edits the plan, source, boundaries, or memory.
+  The other modes write only under `docs/boundaries/`,
+  `docs/memory/boundary.md`, and (for `init` mechanical fixes) the
+  specific violating source line. Never touch frozen records
+  (`docs/history/plans/`, `docs/history/changelog/`) or feature docs.
+- **Verify against source.** Never report a violation or intersection from text
+  alone — read the files the plan/boundary names.
+- **One file per boundary.** Don't bundle unrelated boundaries.
+- **Severity is load-bearing.** It feeds `check` review depth + `init` priority.
+  Default from the taxonomy; adjust from the repo + memory.
+- **Name the bounding code units** in every `Bounds` line — they're the
+  module-discovery feed `harness-manager` reads. A workspace is *not* a module.
+- **Don't invent boundaries the repo doesn't have.** Only instantiate exhibited
+  types; `log()` skips. **A clean report is valid** — empty violations/intersections
+  means say so, don't pad.
+- **Docs never outrank code.** For `point` boundaries, mirror with `file:line`;
+  don't fork the shape. `file:line` stays primary for point-mode boundaries; an
+  `anchors:` query (see the documentation skill's frontmatter reference) MAY
+  supplement it for refactor-resilience — optional and additive, it re-resolves
+  the shape when the line moves, never replaces the pointer.
+- **Be specific** — file paths, line numbers, boundary names, the exact violating
+  string or code shape.
+
+## Strategy memory
+
+After a run you may append to `docs/memory/boundary.md` (git-tracked):
+project-specific boundary exceptions, where the IA model actually lives in this
+repo, stack quirks that change a doc-mode, recurring drift/violation zones,
+historical violation counts. Never user preferences (those are `~/.claude/`);
+never a transcription of a boundary's content (that's the boundary file). Date
+each entry `## YYYY-MM-DD — {topic}`.
+
+## Output locations
+
+- `generate`/`create`/`init` write boundary files to `docs/boundaries/` + the
+  index `docs/boundaries/README.md`; memory to `docs/memory/boundary.md`.
+- `check` returns its report in chat — never written to disk; the user folds
+  insights back into the plan.