@nurix/etna 0.20.46 → 0.20.48

package/data/harnesses/code/hooks/lib/protection-gate.mjs

@@ -0,0 +1,208 @@
+// harness/code/hooks/lib/protection-gate.mjs — the Protection walls: frozen records and protected files,
+// on the file tools and on the shell write screen. The one module the fail-closed `protection.mjs`
+// loads, so its import graph stays narrow (frozen, repo, session-log, walls, graph, node built-ins): a
+// partial mount missing a compliance-only module cannot crash the hook that blocks on a crash.
+// `protectionVerdict` is the predicate and writes nothing; `protectionGate` adds the logged deny.
+// Compliance runs the same predicate first and defers when `protectionHandled` (docs/harness/code/hooks.md).
+
+import fs from "node:fs";
+import path from "node:path";
+import { frozenStatusAtHead } from "./frozen.mjs";
+import { readSafe, relIfInside, commandRoot, backtickTokens, docsRoot, resolveProjectDir } from "./repo.mjs";
+import { appendEvent } from "./session-log.mjs";
+import { wallEnabled } from "./walls.mjs";
+import { readGraph } from "./graph.mjs";
+
+// The per-call ceiling of one git call, and the default when a caller carries no deadline.
+const GIT_TIMEOUT_MS = 5000;
+
+// Milliseconds a git call may take: the time left before `deadlineAt`, capped at GIT_TIMEOUT_MS.
+function budgetMs(deadlineAt) {
+  if (!Number.isFinite(deadlineAt)) return GIT_TIMEOUT_MS;
+  return Math.max(0, Math.min(GIT_TIMEOUT_MS, Math.floor(deadlineAt - Date.now())));
+}
+
+export function decision(permissionDecision, reason) {
+  return {
+    hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision, permissionDecisionReason: reason },
+  };
+}
+
+// A deny is also an event in the session gate log — the record that makes going silent after a
+// block impossible. The log is a dated per-session record (never drained; bookkeeping stays a
+// queue); the Stop and commit walls block on `denied` lines with no later `resolved` pair.
+export function deny(projectDir, sessionId, gate, target, reason) {
+  appendEvent(projectDir, sessionId, "denied", gate, target);
+  return decision("deny", reason);
+}
+
+// --- the build graph's switch ------------------------------------------------------------
+// A run handed a build graph (docs/harness/code/build-graph.md) may declare `mode.walls`, an
+// allowlist over lib/walls.mjs. Every wall it does not name is off for that session — because
+// the compliance set assumes a session that can dispatch a bookkeeper and a user who can answer
+// an ask, and a generation box has neither: its walls would be unresolvable blocks, not guard
+// rails. No graph, or a graph with no `mode` block, leaves every wall exactly as it was. With no graph
+// declaring one, an exit set (docs/harness/code/exit-check.md) may carry the same block.
+// Read here rather than through lib/graph-store.mjs and lib/exit-store.mjs, which import the state
+// module; the reading is theirs (`wallsAllowlist`, `exitWallsAllowlist`), field for field.
+function graphWalls(projectDir) {
+  let text;
+  try {
+    text = fs.readFileSync(path.join(projectDir, ".claude", "state", "graph.json"), "utf8");
+  } catch (e) {
+    return null; // absent — dormancy
+  }
+  const parsed = readGraph(text, projectDir);
+  if (!parsed.ok || !parsed.graph.mode) return null; // a refused graph never switches a wall off
+  return parsed.graph.mode.walls;
+}
+
+function exitWalls(projectDir) {
+  try {
+    const set = JSON.parse(fs.readFileSync(path.join(projectDir, ".claude", "state", "exit.json"), "utf8"));
+    const attempts = set?.attempts;
+    const isExitSet = set && set.v === 1 && Array.isArray(set.owed) && Number.isInteger(attempts?.used) && Number.isInteger(attempts?.max);
+    return isExitSet && Array.isArray(set?.mode?.walls) ? set.mode.walls : null;
+  } catch (e) {
+    return null; // absent or unreadable — no allowlist
+  }
+}
+
+// Keyed by projectDir, so one importer serving two repositories never reads the other's switch.
+const allowlistCache = new Map();
+export function wallOn(projectDir, name) {
+  if (!allowlistCache.has(projectDir)) {
+    let allowlist;
+    try {
+      allowlist = graphWalls(projectDir) ?? exitWalls(projectDir);
+    } catch (e) {
+      allowlist = null; // a broken graph never switches a wall off
+    }
+    allowlistCache.set(projectDir, allowlist);
+  }
+  return wallEnabled(allowlistCache.get(projectDir), name);
+}
+
+// The protected-list reader: AGENTS.md, the list itself, and every backticked path in
+// <docs>/operations/protected-files.md. Read once per projectDir per process.
+const protectedCache = new Map();
+export function protectedPaths(projectDir) {
+  if (protectedCache.has(projectDir)) return protectedCache.get(projectDir);
+  const root = docsRoot(projectDir);
+  const text = readSafe(path.join(projectDir, root, "operations", "protected-files.md"));
+  const list = ["AGENTS.md", `${root}/operations/protected-files.md`, ...backtickTokens(text)];
+  protectedCache.set(projectDir, list);
+  return list;
+}
+
+// A file write arriving by shell hits the same wall the Edit tool does. Only tokens in a
+// WRITING position count — redirect targets, `tee`/`mv`/`cp` destinations, and any path on an
+// in-place editor line (`sed -i`, `perl -i`) — so reading a frozen record into a pipe stays
+// legal. A token that isn't an existing repo path falls through frozenStatus/protected as a
+// no-op, which keeps sed expressions and flags harmless without shell-parsing them.
+export function bashWriteTargets(command) {
+  const targets = [];
+  let m;
+  const redirect = />{1,2}\s*([^\s;|&<>]+)/g;
+  while ((m = redirect.exec(command))) targets.push(m[1]);
+  const tee = /\btee\s+(?:-\S+\s+)*([^\s;|&<>]+)/g;
+  while ((m = tee.exec(command))) targets.push(m[1]);
+  const moveCopy = /\b(?:mv|cp)\s+(?:-\S+\s+)*\S+\s+([^\s;|&<>]+)/g;
+  while ((m = moveCopy.exec(command))) targets.push(m[1]);
+  if (/\b(?:sed|perl)\s+(?:-\S*\s+)*-\S*i/.test(command) || /\bsed\s+--in-place\b/.test(command)) {
+    for (const t of command.split(/[\s"']+/)) {
+      if (t && !t.startsWith("-") && /[/.]/.test(t)) targets.push(t);
+    }
+  }
+  return targets;
+}
+
+// The two walls on one repo-relative path. frozenStatusAtHead, not frozenStatus: a record frozen
+// only in the WORKTREE is a freeze born in the current edit — a plan legitimately flipping to
+// Complete — and denying that walls the completion ceremony itself. A spent budget reads as not
+// frozen: a timeout is never a gate. Returns { wall, rel, message, projectDir } or null.
+export function pathVerdict(projectDir, rel, { deadlineAt, shell = false } = {}) {
+  if (wallOn(projectDir, "frozen-record")) {
+    const timeoutMs = budgetMs(deadlineAt);
+    const frozen = timeoutMs > 0 ? frozenStatusAtHead(projectDir, rel, { timeoutMs }) : { frozen: false };
+    if (frozen.frozen) {
+      return {
+        wall: "frozen-record",
+        rel,
+        projectDir,
+        message: shell
+          ? `BLOCKED — frozen record. \`${rel}\` is committed history and is never edited (${frozen.reason}) — a shell write is still a write. A correction is a new dated entry that links back.`
+          : `BLOCKED — frozen record. \`${rel}\` is committed history and is never edited (${frozen.reason}). A correction is a new dated entry that links back.`,
+      };
+    }
+  }
+  if (wallOn(projectDir, "protected-file") && protectedPaths(projectDir).includes(rel)) {
+    return {
+      wall: "protected-file",
+      rel,
+      projectDir,
+      message: shell
+        ? `BLOCKED — protected file. \`${rel}\` is on the protected list — a shell write is still a write.`
+        : `BLOCKED — protected file. \`${rel}\` is on the protected list.`,
+    };
+  }
+  return null;
+}
+
+// The two walls on every write target of a shell command run in `root`; the first denial wins.
+export function shellVerdict(root, command, { deadlineAt } = {}) {
+  for (const target of bashWriteTargets(command || "")) {
+    const rel = relIfInside(root, target);
+    if (!rel) continue;
+    const verdict = pathVerdict(root, rel, { deadlineAt, shell: true });
+    if (verdict) return verdict;
+  }
+  return null;
+}
+
+// The predicate over a PreToolUse payload: { wall, rel, message, projectDir } or null. Writes nothing.
+// A Bash command is judged in the repo it acts on (lib/repo.mjs#commandRoot).
+export function protectionVerdict(projectDir, payload, { deadlineAt } = {}) {
+  const input = (payload && payload.tool_input) || {};
+  if (payload && payload.tool_name === "Bash") {
+    if (!input.command) return null;
+    const timeoutMs = budgetMs(deadlineAt);
+    const root = timeoutMs > 0 ? commandRoot(projectDir, payload, input.command, { timeoutMs }) : projectDir;
+    return shellVerdict(root, input.command, { deadlineAt });
+  }
+  const rel = relIfInside(projectDir, input.file_path);
+  return rel ? pathVerdict(projectDir, rel, { deadlineAt }) : null;
+}
+
+// The predicate with the logged deny: the hook output object, or null.
+export function protectionGate(projectDir, payload, { deadlineAt } = {}) {
+  const verdict = protectionVerdict(projectDir, payload, { deadlineAt });
+  if (!verdict) return null;
+  return deny(verdict.projectDir, payload.session_id, verdict.wall, verdict.rel, verdict.message);
+}
+
+// The dispatcher protection.mjs calls.
+export function protectionPreToolUse(payload, { deadlineAt } = {}) {
+  if (!payload || payload.hook_event_name !== "PreToolUse") return null;
+  return protectionGate(resolveProjectDir(payload), payload, { deadlineAt });
+}
+
+// True when the project's committed .claude/settings.json registers a PreToolUse handler whose
+// command names .claude/hooks/protection.mjs, and that file exists. A mount rewrites .claude/hooks/**
+// without touching the settings, so either half can be missing; compliance holds both walls then.
+export function protectionHandled(projectDir) {
+  if (!fs.existsSync(path.join(projectDir, ".claude", "hooks", "protection.mjs"))) return false;
+  let settings;
+  try {
+    settings = JSON.parse(fs.readFileSync(path.join(projectDir, ".claude", "settings.json"), "utf8"));
+  } catch (e) {
+    return false;
+  }
+  const groups = settings?.hooks?.PreToolUse;
+  if (!Array.isArray(groups)) return false;
+  return groups.some(
+    (group) =>
+      Array.isArray(group?.hooks) &&
+      group.hooks.some((handler) => typeof handler?.command === "string" && handler.command.includes(".claude/hooks/protection.mjs"))
+  );
+}

package/data/harnesses/code/hooks/lib/records-door.mjs

@@ -1,12 +1,12 @@
 // harness/code/hooks/lib/records-door.mjs — the hooks' side of the records door. A hook never holds a
-// credential: it hands rows to `nustack records emit`, which climbs the door's rungs, and when the tool
-// is absent or its call fails it appends them to .claude/state/records/<kind>.jsonl, where the next
-// session finds them. Never throws. Fuller account: docs/harness/code/hooks.md § lib/records-door.mjs.
+// credential: it hands rows to `nustack records emit` as a bare JSON array on stdin, and the CLI climbs
+// the door's rungs. There is no fallback file: with the tool absent or its call failing, the caller
+// keeps the rows and offers them again (lib/backlog-detector.mjs). Never throws.
+// Fuller account: docs/harness/code/hooks.md § lib/records-door.mjs.
 
 import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
-import { stateDir } from "./state.mjs";
 
 // The first executable named `name` on the PATH, or null.
 export function onPath(name, pathEnv = process.env.PATH || "") {
@@ -22,33 +22,24 @@ export function onPath(name, pathEnv = process.env.PATH || "") {
   return null;
 }
 
-function appendLocal(projectDir, kind, rows) {
-  const dir = path.join(stateDir(projectDir), "records");
-  fs.mkdirSync(dir, { recursive: true });
-  const at = new Date().toISOString();
-  fs.appendFileSync(path.join(dir, `${kind}.jsonl`), rows.map((row) => JSON.stringify({ kind, row, at }) + "\n").join(""));
-}
-
-// Emits rows of one kind: through `nustack records emit --kind <kind> --json` when the tool is on the
-// PATH and answers 0, else to the rung-4 file. Returns "door" or "file" (or "none" when nothing landed).
+// Emits rows of one kind through `nustack records emit --kind <kind> --json`, the rows as a bare array
+// on stdin — the shape every published CLI's parseRows accepts. Returns "door" (exit 0), "absent" (no
+// `nustack` on the PATH), "failed" (a non-zero exit, a spawn error or a timeout) or "none" (no rows).
 export function emitRecord(kind, rows, { projectDir, env = process.env, timeoutMs = 5000 } = {}) {
   const list = (Array.isArray(rows) ? rows : [rows]).filter(Boolean);
   if (list.length === 0) return "none";
   const binary = onPath("nustack", env.PATH || "");
-  if (binary) {
+  if (!binary) return "absent";
+  try {
     const res = spawnSync(binary, ["records", "emit", "--kind", kind, "--json"], {
       cwd: projectDir,
-      input: JSON.stringify({ kind, rows: list }),
+      input: JSON.stringify(list),
       encoding: "utf8",
       env,
       timeout: timeoutMs,
     });
-    if (!res.error && res.status === 0) return "door";
-  }
-  try {
-    appendLocal(projectDir, kind, list);
-    return "file";
+    return !res.error && res.status === 0 ? "door" : "failed";
   } catch (e) {
-    return "none";
+    return "failed";
   }
 }

package/data/harnesses/code/hooks/lib/repo.mjs

@@ -1,11 +1,36 @@
-// harness/code/hooks/lib/repo.mjs — the shared floor every hook module stands on: safe reads,
-// path normalization, git, session ids, and the one definition of "source file". Each of these
-// existed as 2–5 diverging private copies before being hoisted here.
+// harness/code/hooks/lib/repo.mjs — the shared floor every hook module stands on: stdin, the project
+// root, the state folder, safe reads, path normalization, git, session ids, and the one definition of
+// "source file". Each of these existed as 2–5 diverging private copies before being hoisted here. It
+// imports nothing but node built-ins, which keeps the Protection hook's import graph narrow.
 
 import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 
+// Read all of stdin synchronously; returns "" if nothing is piped.
+export 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.
+export function resolveProjectDir(payload) {
+  return process.env.CLAUDE_PROJECT_DIR || (payload && payload.cwd) || process.cwd();
+}
+
+// Ensure .claude/state/ exists and is self-ignoring (a `*` .gitignore inside it),
+// so consumers never see machine-local state as untracked noise. Returns the dir.
+export function stateDir(projectDir) {
+  const dir = path.join(projectDir, ".claude", "state");
+  fs.mkdirSync(dir, { recursive: true });
+  const ignore = path.join(dir, ".gitignore");
+  if (!fs.existsSync(ignore)) fs.writeFileSync(ignore, "*\n");
+  return dir;
+}
+
 export function readSafe(file) {
   try {
     return fs.readFileSync(file, "utf8");
@@ -44,8 +69,8 @@ export function relIfInside(projectDir, filePath) {
   return rel.split(path.sep).join("/");
 }
 
-export function git(cwd, args) {
-  const res = spawnSync("git", args, { cwd, encoding: "utf8", timeout: 5000 });
+export function git(cwd, args, { timeoutMs = 5000 } = {}) {
+  const res = spawnSync("git", args, { cwd, encoding: "utf8", timeout: timeoutMs });
   return res.status === 0 ? (res.stdout || "").trim() : null;
 }
 
@@ -75,7 +100,8 @@ export function backtickTokens(text) {
 // A candidate is normalized to its git toplevel so a subdirectory cwd still resolves to the
 // repo root. Claim and release both route here — two private copies of this rule once
 // disagreed, and the divergence leaked stale claims.
-export function commandRoot(projectDir, payload, command) {
+// `timeoutMs` bounds the toplevel lookup, for a caller spending a wall-clock budget.
+export function commandRoot(projectDir, payload, command, { timeoutMs = 5000 } = {}) {
   const cdMatch = /(?:^|\n|&&|;)\s*cd\s+"?([^"\s;&]+)"?/.exec(command || "");
   for (const candidate of [cdMatch && cdMatch[1], payload && payload.cwd]) {
     if (!candidate || !path.isAbsolute(candidate)) continue;
@@ -84,7 +110,7 @@ export function commandRoot(projectDir, payload, command) {
     } catch (e) {
       continue;
     }
-    return git(candidate, ["rev-parse", "--show-toplevel"]) || candidate;
+    return git(candidate, ["rev-parse", "--show-toplevel"], { timeoutMs }) || candidate;
   }
   return projectDir;
 }

package/data/harnesses/code/hooks/lib/session-log.mjs

@@ -9,8 +9,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import { stateDir } from "./state.mjs";
-import { sid8 } from "./repo.mjs";
+import { stateDir, sid8 } from "./repo.mjs";
 
 export function sessionLogPath(projectDir, sessionId) {
   const dir = path.join(stateDir(projectDir), "sessions");

package/data/harnesses/code/hooks/lib/state.mjs

@@ -17,7 +17,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { globToRegExp } from "./ownership.mjs";
-import { docsRoot } from "./repo.mjs";
+import { docsRoot, stateDir } from "./repo.mjs";
 
 // Relative to the docs root (lib/repo.mjs#docsRoot) — never a bare "docs/..." literal.
 export const QUEUE_PATH = ["operations", "bookkeeping.md"];
@@ -326,15 +326,9 @@ export function waiverCovers(rows, kind, subject, today) {
   return unexpiredWaivers(rows, kind, today).some((w) => w.body.includes(`\`${subject}\``));
 }
 
-// Ensure .claude/state/ exists and is self-ignoring (a `*` .gitignore inside it),
-// so consumers never see machine-local state as untracked noise. Returns the dir.
-export function stateDir(projectDir) {
-  const dir = path.join(projectDir, ".claude", "state");
-  fs.mkdirSync(dir, { recursive: true });
-  const ignore = path.join(dir, ".gitignore");
-  if (!fs.existsSync(ignore)) fs.writeFileSync(ignore, "*\n");
-  return dir;
-}
+// stateDir lives in lib/repo.mjs, so the Protection hook's narrow import graph reaches it without
+// this module; it is re-exported here for every existing importer.
+export { stateDir };
 
 // The build graph's two machine-local files. Named here so every reader — the walker's adapters,
 // the compliance gates, a composer writing a graph before any session has run — spells them once.

package/data/harnesses/code/hooks/lib/walls.mjs

@@ -6,7 +6,7 @@
 // the two sets agree, so a rename fails there rather than in a generation box at 3am.
 //
 // The first ten are PreToolUse gate ids as recorded in the session log; the last four name Stop
-// sub-walls that had no id at all until `mode.walls` needed to talk about them.
+// sub-walls that had no id at all until `mode.walls` needed to talk about them; the last is an ask.
 export const WALLS = [
   "frozen-record",
   "protected-file",
@@ -22,6 +22,7 @@ export const WALLS = [
   "open-denials",
   "ledger",
   "changelog-entry",
+  "new-standard-doc",
 ];
 
 // The build graph's own denials are deliberately absent: they are not skippable, because they

package/data/harnesses/code/hooks/protection.mjs

@@ -0,0 +1,53 @@
+// harness/code/hooks/protection.mjs — the Protection hook: the fail-closed PreToolUse entry over
+// lib/protection-gate.mjs. It denies an edit or a shell write to a frozen record or a protected file,
+// and it is the one hook registered with `onFailure: "block"`: an exception in the gate, or a module
+// that cannot load, exits 1 after a line in .claude/state/hook-failures.log, and Claude Code then
+// blocks the call. A timeout is never a gate: every git call spends one wall-clock budget, a spent
+// budget allows, and a backstop timer exits 0 at the deadline if an asynchronous wait outlives it.
+// A repository with no git, no protected list or no docs root is no failure: nothing is frozen or
+// protected there. Fuller account: docs/harness/code/hooks.md.
+
+import fs from "node:fs";
+import path from "node:path";
+
+// The wall-clock budget, under the handler's 10 s timeout so process start fits in the gap.
+const PROTECTION_DEADLINE_MS = 7000;
+
+const deadlineAt = Date.now() + PROTECTION_DEADLINE_MS;
+setTimeout(() => process.exit(0), PROTECTION_DEADLINE_MS).unref();
+
+async function main() {
+  const { protectionPreToolUse } = await import("./lib/protection-gate.mjs");
+  let raw = "";
+  try {
+    raw = fs.readFileSync(0, "utf8");
+  } catch (e) {
+    raw = "";
+  }
+  let payload = {};
+  try {
+    payload = raw ? JSON.parse(raw) : {};
+  } catch (e) {
+    payload = {}; // no payload names nothing to protect
+  }
+  const out = protectionPreToolUse(payload, { deadlineAt });
+  if (out) process.stdout.write(JSON.stringify(out));
+}
+
+let code = 0;
+try {
+  await main();
+} catch (e) {
+  // Fail closed: a Protection wall that cannot run must not let the write through.
+  code = 1;
+  try {
+    const dir = path.join(process.env.CLAUDE_PROJECT_DIR || process.cwd(), ".claude", "state");
+    fs.mkdirSync(dir, { recursive: true });
+    fs.appendFileSync(path.join(dir, "hook-failures.log"), `${new Date().toISOString()} protection.mjs ${e?.message || e}\n`);
+  } catch (e2) {
+    /* nowhere to write — the exit status still blocks */
+  }
+  process.stderr.write(`protection.mjs failed closed: ${e?.message || e}\n`);
+} finally {
+  process.exit(code);
+}

package/data/harnesses/code/skills/documentation/SKILL.md

@@ -20,7 +20,7 @@ This skill writes one document at a time: the genre registry says what kind of d
 ## Writing one document
 
 1. **Find the genre.** Match the request against § Routing, then read that genre's registry row: nature, `type:`, location, required keys, required sections. No row fits ⇒ `references/untemplated.md`.
-2. **Find the existing document.** If a document on the topic already exists, extend it; a second document on one topic is drift. If the file is a frozen record (a plan at `Complete` or `Abandoned`, a committed changelog entry, an executed runbook), never edit it: write a new dated record that links back.
+2. **Find the existing document.** If a document on the topic already exists, extend it; a second document on one topic is drift. A new doctrine or playbook document also waits for the user's approval (§ Doctrine and playbooks). If the file is a frozen record (a plan at `Complete` or `Abandoned`, a committed changelog entry, an executed runbook), never edit it: write a new dated record that links back.
 3. **Earn it, and route a set.** A new truth document that states rules (doctrine, a system, an architecture decision) first lists the decisions only it would own, each checked against the documents that exist; under about six, its rules go to their homes and the document is not written. More than one sibling document, or any doctrine document, follows `references/document-sets.md` from here: a term table and a rule ledger before prose, rendered from the ledger, one cold read.
 4. **Place and name it** at the registry's location. `docs/structure.md` is the placement authority for anything the registry leaves open.
 5. **Write it from the template, then run its genre procedure.** A template's procedure section binds that genre only: doctrine's is the reason check (`templates/doctrine.md` § Reason check). Keep the template's section names exactly; omit optional sections with nothing real to say. Write the body from the outside in (style guide § Shape), every heading and bold label a noun phrase, every sentence after a label third person, one rule per sentence in the term engineers use (style guide § Sentences, § Vocabulary). In a truth document, every sentence is present tense (§ The three natures). Every line owns a decision: before stating a rule, search the neighbours for it, and cite the one found rather than restating it (style guide § Net-net).
@@ -41,6 +41,15 @@ Some genres carry steps beyond writing from the template. Each procedure lives i
 
 A genre with no row here has no procedure beyond its template.
 
+## Doctrine and playbooks
+
+Two genres are standards rather than accounts of one repository: a doctrine document settles one concern every product handles, and a playbook settles one interface or workflow shape every product builds. Both are read by the next product as much as by this one, so four rules bind them beyond their templates:
+
+- **General form:** each reads correctly copied verbatim into another product's repository. It names nothing only its own repository has: the product, its domain entities, its vendors and stack, its people, its own documents by path. An example uses an object every product has, and the repository's own values stay in its feature documents, which name the standard in their Scope.
+- **Extend first:** before a new document is proposed, the existing set is read (`grep -m1 '^description:' docs/architecture/{doctrine,playbooks}/*.md`), and content whose subject one of them already covers lands there as a section, a principle or a row.
+- **New only on a clear distinction:** a new document is written only for a concern or a shape none of the existing ones owns, with decisions of its own (the template's earn-it test).
+- **Never without approval:** an agent never creates a doctrine or playbook document on its own initiative, a baseline and a harvest included. It names the proposed document, the existing documents it was checked against and the distinction between them, then waits for the user's yes in chat. An unattended session files the request as a stop. An edit to an existing document follows the normal loop.
+
 ## The three natures
 
 Every document is exactly one of three things, and the registry names which for every genre. Decide before writing a word: every other rule follows from the split.
@@ -105,6 +114,7 @@ A document names the objects it designs in `objects:`, and a source file names t
 | Document a feature's data flow or state | The feature doc's Flows (behaviour) and Promises (guarantees); a persisted shape belongs in the API reference (style guide § State at persistence points); component and transient state are not documented |
 | Document a workspace package | [`templates/package.md`](templates/package.md), the residual owner of `packages/{name}/**` |
 | Document one concern the platform handles everywhere (authentication, storage, the API protocol) | [`templates/doctrine.md`](templates/doctrine.md): design and principles in general form, no mechanism, no project link, owns no code; written through [`references/document-sets.md`](references/document-sets.md) |
+| Document one interface or workflow shape every product builds (the shell, a settings area, analytics pages, a record's lifecycle) | [`templates/playbook.md`](templates/playbook.md): the shape and its rules in general form, owns no code; created only with the user's approval (§ Doctrine and playbooks) |
 | Write or rework several sibling documents at once (a doctrine folder, a family of features) | [`references/document-sets.md`](references/document-sets.md): usefulness test, term table, rule ledger, render, one cold read |
 | Document one system spanning packages | [`templates/system.md`](templates/system.md): one machine end to end, never a giant feature doc |
 | Record or revise an architecture decision | [`templates/architecture-decision.md`](templates/architecture-decision.md): one AD per subject, revised in place |

package/data/harnesses/code/skills/documentation/references/style-guide.md

@@ -28,7 +28,8 @@ Every genre takes the same shape (principle 2) and the same labels (principle 5)
 
 | Genre | Nature | Deepest layer | Excluded |
 | --- | --- | --- | --- |
-| Doctrine (`docs/architecture/common/`) | Truth | The decisions behind each part and the reasons for them | Any mechanism. A doctrine document describes no code |
+| Doctrine (`docs/architecture/doctrine/`) | Truth | The decisions behind each part and the reasons for them | Any mechanism. A doctrine document describes no code |
+| Playbook (`docs/architecture/playbooks/`) | Truth | What a person sees and does in the shape, part by part: its arrangement, each part's behaviour, its states and promises | Any one product's values: its labels, routes, limits and timings, which are its feature documents'. Any mechanism |
 | System (`docs/architecture/systems/`) | Truth | The machine's behaviour across packages: the order it runs in, sequence and state diagrams at role level, the invariant at each place where parts meet, what re-drives a stall. No single file shows a cross-package flow, so this layer earns its place | Per-function steps, tables and columns, routes |
 | Package (`docs/architecture/packages/`) | Truth | The public contract a consumer touches: commands and their flags, exports, what is installed and where. For a CLI the flags *are* the promise | Internal layout, the build's steps, which file holds what |
 | Feature (`docs/features/`) | Truth | The behaviour a person meets, in full: each state the surface can be in, each edge case, what a rejection tells them, the wording where the wording is promised. This genre runs deepest toward its end, in Promises, because a promise is checked by a person or a test and the code cannot state it as intent | Columns, routes, guards, functions, files |

package/data/harnesses/code/skills/documentation/scripts/doc-lint.mjs

@@ -255,7 +255,7 @@ function lintFile(path, findings) {
         if (/^[a-z]+:\/\//.test(target) || SCAFFOLD.test(target)) continue;
         // The repo-root README routes by intent (templates/root-readme.md): its Map names owning package and system
         // docs, its Destinations rows name procedures and rules. Individual feature docs stay off it — the ownership index finds them.
-        if (isRootReadme && /(^|\/)docs\/(architecture\/(packages|systems|common)\/|operations\/)[^/]+\.md$|(^|\/)\.claude\/rules\/[^/]+\.md$/.test(target)) continue;
+        if (isRootReadme && /(^|\/)docs\/(architecture\/(packages|systems|doctrine|playbooks)\/|operations\/)[^/]+\.md$|(^|\/)\.claude\/rules\/[^/]+\.md$/.test(target)) continue;
         if (isRootReadme && /(^|\/)docs\/features\/[^/]+\.md$/.test(target)) { findings.push({ path, n, severity: 'warn', id: 'root-readme-feature-link', message: `root README links an individual feature doc (\`${target}\`) — point at docs/features/ and let the ownership index find it`, excerpt: line.trim().slice(0, 90) }); continue; }
         findings.push({ path, n, severity: 'block', id: 'index-lists-files', message: `index links an individual document (\`${target}\`) — name the folder and how its files are named; \`ls\` is the roster`, excerpt: line.trim().slice(0, 90) });
       }
@@ -382,7 +382,7 @@ function lintFile(path, findings) {
   // A heading or a bold bullet label names; it never says. A label with a finite verb drags in a tense,
   // a person and a voice ("What was decided", "You already belong to…"), so a label opening with a
   // wh-word or a personal pronoun, or ending in a full stop, is a clause (style-guide § Labels).
-  const isLabelledDoc = isOwningDoc || (scope === 'truth' && !isFolderIndex && /(^|\/)docs\/architecture\/common\/[^/]+\.md$/.test(path));
+  const isLabelledDoc = isOwningDoc || (scope === 'truth' && !isFolderIndex && /(^|\/)docs\/architecture\/(doctrine|playbooks)\/[^/]+\.md$/.test(path));
   if (isLabelledDoc && !disabled.has('clause-label')) {
     const CLAUSE = /^(how|what|why|where|when|who|which|whose|you|your|we|our|i|it)\b|\b(you|your)\b|\.$/i;
     for (const { n, line } of lines) {
@@ -413,7 +413,7 @@ function lintFile(path, findings) {
 
 // A doctrine folder is read as a set: its documents cite each other's principles by number and must not restate each
 // other (templates/doctrine.md, references/document-sets.md), so these checks read the siblings beside the linted file.
-const DOCTRINE_LOCATION = /(^|\/)docs\/architecture\/common\/[^/]+\.md$/;
+const DOCTRINE_LOCATION = /(^|\/)docs\/architecture\/doctrine\/[^/]+\.md$/;
 // A doctrine document closes on Terms and Related documents; an older one on "For the agent". The body ends at the first.
 const DOCTRINE_CLOSING = /^##\s+(For the agent|Terms|Related documents)\s*$/;
 // The words a doctrine document replaces with the term engineers use (references/style-guide.md § Vocabulary).

package/data/harnesses/code/skills/documentation/templates/Readme.md

@@ -17,7 +17,8 @@ Every fact about a genre lives in one row of the table below: its template, its
 | Feature | [feature.md](feature.md) | truth | `feature` | `docs/features/{feature}.md` | `type` `description` `status` `objects` | Scope · Promises · For the agent |
 | Package | [package.md](package.md) | truth | `package` | `docs/architecture/packages/{package}.md` | `type` `description` `status` `objects` | Scope · Ownership · Usage · Promises · For the agent |
 | System | [system.md](system.md) | truth | `system` | `docs/architecture/systems/{system}.md` | `type` `description` `status` `objects` | Scope · Flow · Promises · For the agent |
-| Doctrine | [doctrine.md](doctrine.md) | truth | `doctrine` | `docs/architecture/common/{concern}.md` | `type` `description` `status` `objects` | Principles · Terms · Related documents |
+| Doctrine | [doctrine.md](doctrine.md) | truth | `doctrine` | `docs/architecture/doctrine/{concern}.md` | `type` `description` `status` `objects` | Principles · Terms · Related documents |
+| Playbook | [playbook.md](playbook.md) | truth | `playbook` | `docs/architecture/playbooks/{subject}.md` | `type` `description` `status` `objects` | Purpose · Related documents |
 | Architecture decision | [architecture-decision.md](architecture-decision.md) | truth | `architecture-decision` | `docs/architecture/decisions/AD-NNN-{subject}.md` | `type` `title` `description` `status` `last-updated` | Decision · Context · Consequences |
 | UX behavior | [ux-behavior.md](ux-behavior.md) | truth | `ux` | `docs/features/{surface}-ux.md` | `type` `description` `status` `objects` | Purpose · Anatomy · States · Affordances · Promises · Transitions |
 | System overview | [system-overview.md](system-overview.md) | truth | `system-overview` | `docs/architecture/system-design.md` | `type` `description` | — |
@@ -25,7 +26,7 @@ Every fact about a genre lives in one row of the table below: its template, its
 | Glossary | [glossary.md](glossary.md) | truth | `glossary` | `docs/architecture/glossary.md` | `type` `description` | — |
 | Non-goals | [non-goals.md](non-goals.md) | truth | `non-goals` | `docs/architecture/non-goals.md` | `type` `description` | — |
 | Security overview | [security-overview.md](security-overview.md) | truth | `security-overview` | `docs/architecture/security.md` | `type` `description` | — |
-| Testing strategy | [testing-strategy.md](testing-strategy.md) | truth | `testing-strategy` | `docs/architecture/common/testing.md` | `type` `description` | — |
+| Testing strategy | [testing-strategy.md](testing-strategy.md) | truth | `testing-strategy` | `docs/architecture/doctrine/testing.md` | `type` `description` | — |
 | API reference | [api-reference.md](api-reference.md) | truth | `api-reference` | `docs/architecture/api.md` | `type` `description` | — |
 | Environment registry | [environment-registry.md](environment-registry.md) | truth | `environment-registry` | `docs/operations/environment.md` | `type` `description` | — |
 | Behavioral checklist | [behavioral-checklist.md](behavioral-checklist.md) | truth | `checklist` | `docs/tests/{feature}.md` | `type` `description` `verifies` | — |

package/data/harnesses/code/skills/documentation/templates/doctrine.md

@@ -1,4 +1,4 @@
-# Doctrine documentation (docs/architecture/common/{concern}.md)
+# Doctrine documentation (docs/architecture/doctrine/{concern}.md)
 
 Truth document. Use for **one concern the platform handles everywhere**: authentication, authorization, storage, the API protocol, credentials, telemetry. One file per concern, named for the concern. A doctrine document speaks for no code: no source header names it, and it carries no `owns:`. The surfaces bound by it are the documents that design or touch the objects it governs, computed through those objects, and each names it in its Scope.
 

package/data/harnesses/code/skills/documentation/templates/playbook.md

@@ -0,0 +1,63 @@
+# Playbook documentation (docs/architecture/playbooks/{subject}.md)
+
+Truth document. Use for **one interface or workflow shape every product builds**: the shell, a settings area, analytics pages, a record's lifecycle, the interaction patterns, automated agents. One file per shape, named for it. A playbook speaks for no code: no source header names it, and it carries no `owns:`. The product's own feature documents hold its instance of the shape, and each names the playbook in its Scope.
+
+**A playbook states the shape, never one product's instance of it.** It says what the parts are, how they are arranged, how each behaves and what the shape promises, so a new instance is new content poured into a known shape rather than a new layout. A product's own values (its labels, routes, limits, timings, the wording of its copy) belong to its feature document. A playbook explains no mechanism, for the reasons a doctrine document explains none (`templates/doctrine.md`).
+
+**Doctrine or playbook.** A doctrine document settles the decisions of one concern every product handles, such as how authorization works. A playbook settles what a person sees and does in one recurring shape, such as how a settings page is laid out. A playbook cites the doctrine its shape rests on, and never restates it.
+
+**A playbook is written in general form, never linked to the project that holds it.** It reads correctly when copied verbatim into any other product's repository, under the same rule a doctrine document keeps (`templates/doctrine.md`). Where the shape needs a word for the product's own record, the Purpose introduces a generic one once ("the subject: the record a report is read per, such as a job in a hiring product") and the body uses it throughout. Its links reach only sibling playbooks, doctrine documents and published standards.
+
+**Earn the document, and ask before writing it.** List the rules only this playbook would own, each checked against the playbooks and doctrine that exist. Fewer than about six owned rules means the shape is a section of a neighbour, not a document. A new playbook is created only with the user's approval (SKILL.md § Doctrine and playbooks).
+
+**Required:**
+
+- the frontmatter
+- **Purpose:** what the shape is for, what it is not for, and the generic words it introduces
+- **Related documents**
+
+**Optional, each only with something real to say:**
+
+- **Anatomy:** an ASCII diagram of the arrangement with each region labelled, then one bullet per region
+- **One section per part** that carries rules of its own, named for the part ("Roster", "Readiness", "Side peek")
+- **States:** one table — State · Entered when · The person sees · Can do
+- **Affordances:** what a person can do, one bullet per verb
+- **Principles:** numbered, each a noun-phrase label and its rule
+- **Promises:** what the shape guarantees, grouped under `###` headings where there are several kinds
+- **Transitions:** what moves the shape between its states, and who moves it
+
+Sections run Purpose first and Related documents last; the rest follow the order above. Each is named for its concept, never for its layer. Expect one hundred to two hundred lines.
+
+```yaml
+---
+type: playbook                                   # required tooling key
+description: "{at most 300 characters: the shape this playbook settles, and that a product's own instance is its feature doc}" # required
+status: active                                   # required — active | draft
+objects: [rail, command palette, account menu]   # required — the parts this playbook shapes, by their graph names
+---
+```
+
+```
+# {Shape} playbook
+
+## Purpose
+
+{What the shape is for and what it is not for, in two or three sentences. The generic words it introduces, each in one bullet.}
+
+## Anatomy
+
+{An ASCII diagram, then one bullet per labelled region.}
+
+## {Part}
+
+- **{Rule label}:** {the rule, in general form}
+
+## Principles
+
+1. **{Label}:** {the rule}. {Its reason, as a separate sentence.}
+
+## Related documents
+
+- [{Sibling playbook}]({file}.md): {what it settles beside this one}
+- [{Doctrine}](../doctrine/{concern}.md): {the decision this shape rests on}
+```

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

@@ -130,7 +130,7 @@ The rest of this page is for the team and for coding agents working in this repo
 
 The baseline **does** scaffold `/README.md` when it is missing, and it fills each section from the repo:
 
-- **Identity, Capabilities, Deployment:** from the product charter and vision documents under `docs/architecture/common/` (what the product is, the core loop, who it is for), the package manifests (what publishes where), and the deploy config (addresses). Written in a user's terms; where the charter is missing, the baseline writes Identity only and raises a `note:` row for the rest.
+- **Identity, Capabilities, Deployment:** from the product charter and vision documents under `docs/architecture/doctrine/` (what the product is, the core loop, who it is for), the package manifests (what publishes where), and the deploy config (addresses). Written in a user's terms; where the charter is missing, the baseline writes Identity only and raises a `note:` row for the rest.
 - **The main path:** from the system overview.
 - **Map:** from the workspace globs and the ownership index.
 - **Rules:** from `docs/operations/protected-files.md` and the architecture doctrine.