@spec-engine/spec-engine 0.8.0 → 0.9.0

package/dist/impl.js

@@ -20,7 +20,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@spec-engine/spec-engine",
-    version: "0.8.0",
+    version: "0.9.0",
     description: "Cross-repo spec engine \u2014 durable requirements with permanent IDs, bound to code via @spec tags, checked in CI. Ships the spec CLI, the local coverage webapp (spec serve), and offline docs (spec docs).",
     license: "MIT",
     type: "module",
@@ -73,6 +73,31 @@ var init_package = __esm(() => {
   };
 });
 
+// src/stdout.ts
+import { format } from "util";
+function isEpipe(e) {
+  return typeof e === "object" && e !== null && "code" in e && (e.code === "EPIPE" || e.code === "ERR_STREAM_DESTROYED");
+}
+function routeStdout() {
+  process.stdout.on("error", (e) => {
+    if (!isEpipe(e))
+      throw e;
+  });
+  console.log = (...args) => {
+    const text = `${format(...args)}
+`;
+    lastWrite = new Promise((written) => process.stdout.write(text, () => written()));
+  };
+}
+async function exit(code) {
+  await lastWrite;
+  process.exit(code);
+}
+var lastWrite;
+var init_stdout = __esm(() => {
+  lastWrite = Promise.resolve();
+});
+
 // ../shared/src/diagnostics.ts
 var DiagnosticCode, NotASpecPlatformError, InvalidDomainFilesError;
 var init_diagnostics = __esm(() => {
@@ -84,15 +109,13 @@ var init_diagnostics = __esm(() => {
     SUPERSEDED_REFERENCED: "SUPERSEDED_REFERENCED",
     DEPRECATED_REFERENCED: "DEPRECATED_REFERENCED",
     STATEMENT_GRAMMAR: "STATEMENT_GRAMMAR",
+    STATEMENT_RULES: "STATEMENT_RULES",
     DRAFT_REFERENCED: "DRAFT_REFERENCED",
     GLOSSARY_DRIFT: "GLOSSARY_DRIFT",
     ORPHAN_REQ: "ORPHAN_REQ",
     UNVERIFIED_REQ: "UNVERIFIED_REQ",
     DRIFT: "DRIFT",
     NO_SPEC_CONFIG: "NO_SPEC_CONFIG",
-    BROKEN_FILE_REF: "BROKEN_FILE_REF",
-    UNIMPLEMENTED_IN_FILE: "UNIMPLEMENTED_IN_FILE",
-    UNVERIFIED_IN_FILE: "UNVERIFIED_IN_FILE",
     BROKEN_RELATES: "BROKEN_RELATES",
     RELATES_SUPERSEDED: "RELATES_SUPERSEDED",
     CYCLIC_SUPERSEDE: "CYCLIC_SUPERSEDE",
@@ -100,6 +123,7 @@ var init_diagnostics = __esm(() => {
     UNKNOWN_ROLE: "UNKNOWN_ROLE",
     UNSOURCED_CHANGE: "UNSOURCED_CHANGE",
     INVALID_DOMAIN_FILE: "INVALID_DOMAIN_FILE",
+    MIGRATION_PENDING: "MIGRATION_PENDING",
     UNPROVEN_REQ: "UNPROVEN_REQ",
     PROOFS_UNCONFIRMED: "PROOFS_UNCONFIRMED",
     REQUIREMENT_REMOVED: "REQUIREMENT_REMOVED",
@@ -214,8 +238,6 @@ function orderDomain(d) {
       supersedes: r.supersedes ?? null,
       supersededBy: r.supersededBy ?? null,
       relates: r.relates,
-      livesIn: r.livesIn,
-      verifiedIn: r.verifiedIn,
       issues: r.issues.map((iss) => ({ role: iss.role, id: iss.id })),
       changedAtVersion: r.changedAtVersion,
       supersededAtVersion: r.supersededAtVersion,
@@ -262,6 +284,10 @@ function preserveShape(raw, rawDomain, domain) {
   const next = orderDomain(domain);
   patchFields(raw, before, next);
   const rawEntries = raw.requirements;
+  for (const entry of rawEntries) {
+    for (const key of LEGACY_ENTRY_KEYS)
+      delete entry[key];
+  }
   const byId = new Map;
   rawDomain.requirements.forEach((r, i) => {
     byId.set(r.id, [...byId.get(r.id) ?? [], i]);
@@ -332,7 +358,7 @@ async function validateAndWrite(path, domain, sourceFile) {
   await Bun.write(path, serialized);
   return { ok: true };
 }
-var ID_RE, KEY_RE, SpecIssueSchema, SpecCiteSchema, SpecRequirementSchema, SpecDomainSchema, sameValue = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+var ID_RE, KEY_RE, SpecIssueSchema, SpecCiteSchema, LEGACY_ENTRY_KEYS, SpecRequirementSchema, SpecDomainSchema, sameValue = (a, b) => JSON.stringify(a) === JSON.stringify(b);
 var init_domain = __esm(() => {
   init_diagnostics();
   ID_RE = /^[A-Z][A-Z0-9]*-\d+$/;
@@ -345,6 +371,7 @@ var init_domain = __esm(() => {
     term: z.string(),
     pinned: z.number().int()
   }).strict();
+  LEGACY_ENTRY_KEYS = ["livesIn", "verifiedIn"];
   SpecRequirementSchema = z.object({
     id: z.string().regex(ID_RE),
     status: z.string().min(1),
@@ -353,8 +380,8 @@ var init_domain = __esm(() => {
     supersedes: z.string().nullable().optional(),
     supersededBy: z.string().nullable().optional(),
     relates: z.array(z.string()).optional().default([]),
-    livesIn: z.array(z.string()).optional().default([]),
-    verifiedIn: z.array(z.string()).optional().default([]),
+    livesIn: z.unknown().optional(),
+    verifiedIn: z.unknown().optional(),
     issues: z.array(SpecIssueSchema).optional().default([]),
     changedAtVersion: z.number().int().optional(),
     supersededAtVersion: z.number().int().optional(),
@@ -363,7 +390,7 @@ var init_domain = __esm(() => {
     aliases: z.array(z.string()).optional().default([]),
     cites: z.array(SpecCiteSchema).optional().default([]),
     section: z.string().nullable().optional()
-  }).strict();
+  }).strict().transform(({ livesIn: _l, verifiedIn: _v, ...entry }) => entry);
   SpecDomainSchema = z.object({
     key: z.string().regex(KEY_RE),
     owner: z.string().nullable().optional(),
@@ -376,6 +403,159 @@ var init_domain = __esm(() => {
   }).strict();
 });
 
+// ../shared/src/statementRules.ts
+function jargonPatterns(words) {
+  if (words.length === 0)
+    return [];
+  return [new RegExp(`\\b(?:${words.map(escapeRegExp).join("|")})\\b`, "i")];
+}
+function withoutExemptNames(statement, names) {
+  let out = statement;
+  for (const name of names) {
+    const tail = name.endsWith("/") ? "[^\\s`]*" : "(?![\\w-])";
+    out = out.replace(new RegExp(`(?<![\\w.-])${escapeRegExp(name)}${tail}`, "g"), "X");
+  }
+  return out;
+}
+function sentenceDetail(statement) {
+  if (/[\r\n]/.test(statement))
+    return "contains a line break";
+  const prose = statement.replace(QUOTED, "Q").replace(NON_TERMINAL, "N");
+  const terminals = prose.match(TERMINAL)?.length ?? 0;
+  if (terminals === 1 && /[.?!]$/.test(prose.trimEnd()))
+    return null;
+  return `${terminals} sentence terminators; exactly one, at the end`;
+}
+function hitsDetail(text, patterns) {
+  const hits = patterns.map((pattern) => text.match(pattern)?.[0]).filter((hit) => hit !== undefined);
+  return hits.length > 0 ? hits.map((hit) => `"${hit}"`).join(", ") : null;
+}
+function statementFindings(statement, config = {}) {
+  const maxLength = config.maxLength ?? DEFAULT_MAX_STATEMENT_LENGTH;
+  const details = {
+    "one-sentence": sentenceDetail(statement),
+    length: statement.length > maxLength ? `${statement.length} characters; at most ${maxLength}` : null,
+    "no-file-path": hitsDetail(withoutExemptNames(statement, config.exemptNames ?? []), FILE_PATH),
+    "no-test-narration": null,
+    "no-toolchain-layout": null,
+    "no-history": null,
+    "no-jargon": hitsDetail(statement, jargonPatterns(config.jargon ?? DEFAULT_JARGON)),
+    "no-tool-statement": hitsDetail(statement, TOOL_STATEMENT)
+  };
+  for (const { rule, patterns } of FIXED_RULES)
+    details[rule] = hitsDetail(statement, patterns);
+  const findings = [];
+  for (const rule of STATEMENT_RULES) {
+    const detail = details[rule];
+    if (detail !== null && config.severity?.[rule] !== "off") {
+      findings.push({ rule, detail, reason: STATEMENT_RULE_REASONS[rule] });
+    }
+  }
+  return findings;
+}
+function formatStatementFinding(f) {
+  return `${f.rule}: ${f.detail} \u2014 ${f.reason}`;
+}
+var RULE_ZERO = "A requirement is one rule of the product's behavior, stated from the user's point of view.", STATEMENT_RULES, DEFAULT_MAX_STATEMENT_LENGTH = 280, DEFAULT_JARGON, STATEMENT_RULE_REASONS, EXT = "ts|tsx|js|mjs|json|yml|yaml|sql|md|toml|css|astro|sh", FILE_PATH, FIXED_RULES, TOOL_STATEMENT, escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), QUOTED, NON_TERMINAL, TERMINAL;
+var init_statementRules = __esm(() => {
+  STATEMENT_RULES = [
+    "one-sentence",
+    "length",
+    "no-file-path",
+    "no-test-narration",
+    "no-toolchain-layout",
+    "no-history",
+    "no-jargon",
+    "no-tool-statement"
+  ];
+  DEFAULT_JARGON = [
+    "seam",
+    "seams",
+    "rung",
+    "rungs",
+    "residue",
+    "matrix entry",
+    "stage runner",
+    "the stage"
+  ];
+  STATEMENT_RULE_REASONS = {
+    "one-sentence": "a statement is one testable sentence",
+    length: "a sentence a reader holds at once",
+    "no-file-path": "which file holds what is layout, not behaviour",
+    "no-test-narration": "how a test is written is not what the product does",
+    "no-toolchain-layout": "how CI and tooling are arranged is not a product behaviour",
+    "no-history": "a statement says what holds now, not how it got there",
+    "no-jargon": "a reader without the codebase cannot parse project jargon",
+    "no-tool-statement": "naming the tool in use is a decision record, not a requirement"
+  };
+  FILE_PATH = [
+    /(?<![\w/@-])(?:apps|packages|tooling|modules|spec-engine|\.github)\/[\w.@/-]*/i,
+    /`(?![@/<])(?![^`\s]*:\/\/)(?![^`\s./]*\/[^`\s./]*`)[^`\s]*\/[^`\s]*`/,
+    new RegExp(`\\b(?!(?:next|node|postgres)\\.js\\b|auth\\.md\\b)[\\w-]+(?:\\.[\\w-]+)*\\.(?:${EXT})\\b`, "i")
+  ];
+  FIXED_RULES = [
+    {
+      rule: "no-test-narration",
+      patterns: [
+        /\b(?:describe|it|test)\(/,
+        /\.(?:test|spec)\./i,
+        /\btest files?\b/i,
+        /\bthe tests?\b/i,
+        /\bvitest\b/i,
+        /\bplaywright\b/i,
+        /\bfixtures?\b(?! (?:accounts?|seed))/i,
+        /\bplanted\b/i
+      ]
+    },
+    {
+      rule: "no-toolchain-layout",
+      patterns: [
+        /\bworkflows?\b/i,
+        /\b(?:test|full|CI|job|build|RLS|per-table) matrix\b|\bmatrix (?:entry|entries|job)\b/i,
+        /\brunners?\b/i,
+        /\bGitHub Actions\b/i,
+        /\bci\.yml\b/i,
+        /(?<!`)\bpnpm\s/i,
+        /\bturbo\b/i,
+        /\bbiome\b/i,
+        /\bdrizzle-kit\b/i,
+        /\btsx\s/i,
+        /\bbun\s/i,
+        /\bShellCheck\b/i,
+        /\bcoverage thresholds?\b/i,
+        /`(?:pnpm )?ci:/i,
+        /@spec(?![\w-])/i,
+        /\btag(?:ged)? in\b/i
+      ]
+    },
+    {
+      rule: "no-history",
+      patterns: [
+        /\bamended\b/i,
+        /\bsupersed\w*(?: by)? `?[A-Z][A-Z0-9]*-\d/,
+        /\breplaced by\b|\breplace[sd] `?(?:ADR-|[A-Z][A-Z0-9]*-\d)/i,
+        /\bpreviously\b/i,
+        /\bformerly\b/i,
+        /\bused to\b/i,
+        /\bsince `?\d/i,
+        /\bmigration \d/i,
+        /\b0\d{3}_/,
+        /\bPORT-T/,
+        /\bADR-/
+      ]
+    }
+  ];
+  TOOL_STATEMENT = [
+    /\bwe use\b/i,
+    /\bis used for\b/i,
+    /\bis the tool\b/i,
+    /\bis pinned (?:to|at) (?:`?[\w@./-]+`? )?v?\d/i
+  ];
+  QUOTED = /`[^`]*`|"[^"]*"|\u201C[^\u201D]*\u201D/g;
+  NON_TERMINAL = /\b(?:e\.g|i\.e|etc|vs|cf)\.|\d+(?:\.\d+)+/gi;
+  TERMINAL = /[.?!](?=\s|$)/g;
+});
+
 // ../shared/src/checkConfig.ts
 import { z as z2 } from "zod";
 function parseCheckConfigText(text, sourceFile) {
@@ -393,10 +573,11 @@ function parseCheckConfigText(text, sourceFile) {
   const path = issue && issue.path.length > 0 ? issue.path.join(".") : "(root)";
   return { ok: false, detail: `${sourceFile}: ${path}: ${issue?.message ?? "invalid"}` };
 }
-var CODES, matchEntry, SeverityRuleSchema, CheckConfigSchema;
+var CODES, matchEntry, SeverityRuleSchema, StatementRulesConfigSchema, CheckConfigSchema;
 var init_checkConfig = __esm(() => {
   init_diagnostics();
   init_domain();
+  init_statementRules();
   CODES = Object.values(DiagnosticCode);
   matchEntry = z2.string().refine((s) => KEY_RE.test(s) || ID_RE.test(s), "must be a domain key or a requirement id");
   SeverityRuleSchema = z2.object({
@@ -404,7 +585,16 @@ var init_checkConfig = __esm(() => {
     severity: z2.enum(["error", "warning", "off"]),
     match: z2.array(matchEntry).optional()
   }).strict();
-  CheckConfigSchema = z2.object({ severity: z2.array(SeverityRuleSchema) }).strict();
+  StatementRulesConfigSchema = z2.object({
+    maxLength: z2.number().int().positive().optional(),
+    jargon: z2.array(z2.string().min(1)).optional(),
+    exemptNames: z2.array(z2.string().min(1)).optional(),
+    severity: z2.partialRecord(z2.enum(STATEMENT_RULES), z2.enum(["error", "warning", "off"])).optional()
+  }).strict();
+  CheckConfigSchema = z2.object({
+    severity: z2.array(SeverityRuleSchema).default([]),
+    statementRules: StatementRulesConfigSchema.optional()
+  }).strict();
 });
 
 // ../shared/src/config.ts
@@ -844,6 +1034,7 @@ var init_src = __esm(() => {
   init_net();
   init_propagation();
   init_schema();
+  init_statementRules();
   init_storage();
 });
 
@@ -1113,9 +1304,6 @@ function isPathIgnored(path, extra = []) {
 function isHiddenEntry(name) {
   return name.startsWith(".") && name !== ".github";
 }
-function isHiddenPath(rel) {
-  return rel.split("/").some(isHiddenEntry);
-}
 async function walkInto(rootDir, relDir, keep, extraIgnore, out) {
   const absDir = relDir ? join2(rootDir, relDir) : rootDir;
   let entries;
@@ -2193,33 +2381,9 @@ class SqliteStorage {
     if (files.length > FILES_MAX) {
       throw new Error(`resolveByFiles: too many files (max ${FILES_MAX} per call; got ${files.length})`);
     }
-    const queryFiles = this.#expandSelfMemberFiles(files);
-    if (queryFiles.length > 32000) {
-      throw new Error(`resolveByFiles: expanded bind count ${queryFiles.length} would exceed ` + "SQLITE_MAX_VARIABLE_NUMBER (32766); lower FILES_MAX");
-    }
-    const placeholders = queryFiles.map(() => "?").join(",");
+    const placeholders = files.map(() => "?").join(",");
     const sql = RESOLVE_BY_FILES_SQL_PREFIX + placeholders + RESOLVE_BY_FILES_SQL_SUFFIX;
-    return this.#db.query(sql).all(...queryFiles);
-  }
-  #selfMemberName() {
-    const canonical = this.getRepo("spec-engine");
-    if (!canonical)
-      return null;
-    const platformRoot = dirname2(canonical.path);
-    const row = this.#db.query("SELECT name FROM repos WHERE name != 'spec-engine' AND path = $path").get({ path: platformRoot });
-    return row?.name ?? null;
-  }
-  #expandSelfMemberFiles(files) {
-    const self = this.#selfMemberName();
-    if (!self)
-      return files;
-    const prefix = `${self}/`;
-    const expanded = [...files];
-    for (const f of files) {
-      if (!f.startsWith(prefix))
-        expanded.push(prefix + f);
-    }
-    return expanded;
+    return this.#db.query(sql).all(...files);
   }
   withWriteTx(fn) {
     const wrapped = this.#db.transaction((arg) => fn(arg));
@@ -2685,24 +2849,8 @@ function repoExtraIgnore(member) {
   const repoIgnore = (member.ignore ?? []).map((e) => e.endsWith("/") ? e : `${e}/`);
   return [...member.selfMember ? ["spec-engine/"] : [], ...repoIgnore];
 }
-function scannedTagFile(members, platformDir, platformRel) {
-  const abs = resolve3(platformDir, platformRel);
-  let owner = null;
-  for (const member2 of members) {
-    const rel2 = relative(member2.path, abs).split(sep2).join("/");
-    if (rel2 === "" || rel2 === ".." || rel2.startsWith("../") || isAbsolute(rel2))
-      continue;
-    if (owner === null || member2.path.length > owner.member.path.length)
-      owner = { member: member2, rel: rel2 };
-  }
-  if (owner === null)
-    return null;
-  const { member, rel } = owner;
-  if (isHiddenPath(rel) || isPathIgnored(rel, repoExtraIgnore(member)))
-    return null;
-  if (!isTagSource(rel) && !isDocSource(rel))
-    return null;
-  return `${member.name}/${rel}`;
+function tagFile(member, rel) {
+  return member.selfMember ? rel : `${member.name}/${rel}`;
 }
 async function scanMemberCode(member, extraIgnore) {
   const hitsOut = [];
@@ -2710,7 +2858,7 @@ async function scanMemberCode(member, extraIgnore) {
   for (const rel of codePaths) {
     const absPath = join4(member.path, rel);
     const text = await Bun.file(absPath).text();
-    const platformRelative = `${member.name}/${rel}`;
+    const platformRelative = tagFile(member, rel);
     const hits = scanTagsInFile(member.name, platformRelative, text);
     for (const h of hits)
       hitsOut.push(h);
@@ -2724,7 +2872,7 @@ async function scanMemberDocs(member, extraIgnore) {
   for (const rel of docPaths) {
     const absPath = join4(member.path, rel);
     const text = await Bun.file(absPath).text();
-    const platformRelative = `${member.name}/${rel}`;
+    const platformRelative = tagFile(member, rel);
     const { tags, mentions } = scanDocFile(member.name, platformRelative, text);
     for (const t of tags)
       tagsOut.push(t);
@@ -2915,6 +3063,944 @@ var init_pipeline = __esm(() => {
   init_discover();
 });
 
+// ../../.claude/skills/req-author/SKILL.md
+var SKILL_default = `---
+name: req-author
+description: Turn a rough brief or ticket into Spec Engine requirements \u2014 draft them in the fixed EARS shape, tie every draft to the exact words it came from, present the batch for human approval, and only then mint via the real \`spec\` CLI.
+---
+
+# req-author
+
+> A requirement is one rule of the product's behavior, stated from the user's point of view.
+
+The full requirement authoring standard is the "Requirement authoring
+standard" section of the agent reference
+(\`packages/site/src/content/docs/agent-reference.md\`); this skill applies it.
+
+This skill drives the real \`spec\` CLI (\`spec req\`, \`spec query\`,
+\`spec domain list\`) and never reimplements minting. It is the front half of
+the lifecycle: brief in, approved requirements out; the route \u2192 tag \u2192 check
+loop consumes what it produces.
+
+**Two non-negotiable rules:**
+
+1. **Never write without approval.** Draft, self-check, present the batch \u2014
+   then STOP. No \`spec req\` runs until the human explicitly approves.
+2. **Every draft quotes its source.** Each drafted requirement carries the
+   exact phrase from the brief it derives from, verbatim. A requirement you
+   cannot anchor to the author's words is labeled **inferred** so the human
+   can accept or reject the inference knowingly. This exists because
+   agent-drafted requirements have shipped that the product owner could not
+   trace back to anything they said.
+
+## Procedure
+
+1. **Read the brief.** A ticket is temporary work; the requirements outlive
+   it. One brief usually splits into several requirements \u2014 one per behavior,
+   never one per ticket.
+
+2. **Draft each requirement in the fixed shape.** Every statement uses one of
+   the five EARS shapes (the word "shall" separates who acts from the
+   observable result):
+
+   | Situation | Shape |
+   |---|---|
+   | Always true | The \`<system>\` shall \`<result>\` |
+   | Triggered by an event | When \`<trigger>\`, the \`<system>\` shall \`<result>\` |
+   | Only in a certain state | While \`<state>\`, the \`<system>\` shall \`<result>\` |
+   | Handling something going wrong | If \`<failure>\`, then the \`<system>\` shall \`<result>\` |
+   | Only when a feature is present | Where \`<feature>\`, the \`<system>\` shall \`<result>\` |
+
+   Example: "When an unknown requirement id is passed, spec resolve shall
+   print [] and exit 0." If a draft fits no row, you have not yet decided
+   what triggers the behavior or what observably happens \u2014 decide, or mark
+   the draft as a question for the human.
+
+   One promise per statement: a result chaining two behaviors with \`and\` is
+   two drafts. Prefer \`When\`, \`If \u2026 then\`, and the bare \`shall\` form; \`While\`
+   and \`Where\` only when a state or feature gates the behavior. Rationale
+   belongs in the why, never in the statement.
+
+   The statement rules are checked the same way: one sentence ending in a
+   period, at most 280 characters, and no repository file or folder, test
+   mechanics, CI or tooling layout, history, project jargon, or tool choice.
+   \`spec req\` refuses a draft that breaks one; \`spec lint <KEY-NNN> .\` lists
+   the findings for an existing requirement.
+
+3. **Write a why that names what breaks.** The \`why\` answers "what goes wrong
+   if this stops being true" \u2014 never a restatement of the statement in
+   different words.
+
+4. **Place and dedup.** \`spec domain list --json\` shows every domain's
+   charter; put each requirement in the domain whose promise it protects (not
+   where the code file sits). Then \`spec query "<phrase>" . --json\` \u2014 if a
+   close requirement already exists, propose amending or relating it instead
+   of a new id.
+
+5. **Present the batch and STOP.** For each candidate show: the domain, the
+   statement, the why, and the **source quote** (or the
+   \`inferred\` label). Write nothing until the human approves. This gate is
+   mandatory.
+
+6. **On approval, mint via the real CLI:**
+
+   \`\`\`
+   spec req <domain> --text "<statement>" --why "<what breaks>"
+   \`\`\`
+
+   (or the equivalent \`spec mcp\` tools). \`spec req\` validates through the one
+   shared schema \u2014 in a domain that declares the ears grammar it also checks
+   the statement shape at write time, and with \`--json\` it returns the parsed
+   clauses.
+
+7. **Record the ticket as provenance only.** The originating ticket id is
+   history, never a requirement id and never a code \`@spec\` tag.
+
+8. **Verify.** \`spec index . && spec check . --ci\` (exit 0) and
+   \`spec guard .\` (no loss) before the change ships.
+
+## Invocation note
+
+The repo's \`.mcp.json\` registers the local \`spec mcp\` server (stdio,
+loopback), so the tools and the \`author_requirements\` prompt are callable
+natively from the harness. From a source checkout the server runs as
+\`bun packages/engine/src/cli.ts mcp .\`; a compiled \`spec\` binary on PATH runs
+as \`spec mcp .\`.
+`;
+var init_SKILL = () => {};
+
+// ../site/src/content/docs/agent-reference.md
+var agent_reference_default = `---
+title: Agent Reference
+description: The model, the authoring standard, and the exact contract of the spec CLI, for coding agents and the people who direct them
+---
+
+The reference for a coding agent working in a repository that uses Spec Engine. It has three parts: the model and the working loop, the standard every requirement is written against, and the exact contract of every \`spec\` command.
+
+## What Spec Engine is
+
+Spec Engine helps developers, product teams, and agents write better specs and keep them current, so the software changes accurately.
+
+It works with four things:
+
+| Noun | What it is | Where it lives | Authored or derived |
+| --- | --- | --- | --- |
+| Domain | A named subject area of requirements with an UPPERCASE key (\`BILLING\`), an owner, and a charter that says what belongs in it | \`spec-engine/<KEY>/SPEC.json\`, one file per domain | Authored |
+| Requirement | One durable rule of the product's behavior, addressed by a permanent id \`KEY-NNN\` (\`BILLING-009\`), with a statement, a why, and a status | An entry in its domain's \`SPEC.json\` | Authored |
+| Tag | A comment \`@spec KEY-NNN\` that binds a line of code or a test to a requirement | Source and test files, in comments | Authored in code |
+| Index | A SQLite database of every domain, requirement, and tag, which the read and check commands query | \`.spec-engine/index.sqlite\` at the platform root | Derived |
+
+- The \`SPEC.json\` files are the only authored truth about what the product promises. Write them through the \`spec\` commands. An id is never reused or renumbered: a changed promise is superseded by a new id, and an ended one is deprecated.
+- Tags in code are the only truth about where a requirement is implemented and where it is verified. A tag in implementation code implements; a tag in a test file verifies. The kind comes from the file path, never from the tag text.
+- The index is derived and disposable. Every command rebuilds it from the \`SPEC.json\` files and the tags, and deleting \`.spec-engine/\` is always safe.
+- Requirements are not tickets. One ticket usually becomes several requirements. A ticket id is provenance only: it goes in \`--issue\`, never in a requirement id or a tag.
+
+## The loop
+
+\`\`\`shell
+spec query "renewal charge" . --json         # 1. route: requirements on the topic
+spec resolve src/billing/renew.ts . --json   #    or the ones tagged in a file
+# 2. implement the change
+# 3. tag the function that produces the behavior and the test that proves it
+spec check . --ci --json                     # 4. exit 1: fix before the PR
+spec guard . --json                          # 5. exit 1: the change loses a requirement
+\`\`\`
+
+When \`spec guard\` blocks, relay its \`\uD83D\uDED1 spec-guard:\` block verbatim to the user. Then either \`spec supersede\` the requirement with a successor or get the user's explicit decision to \`spec deprecate\` it. Never delete a requirement to make the gate pass.
+
+## What to tag
+
+\`\`\`ts
+export function renew() { /* \u2026 */ }     // @spec BILLING-009
+it("charges current price", () => {})   // @spec BILLING-009 unit
+\`\`\`
+
+- A tag binds the one function that produces the behavior and the one test that proves it.
+- Helpers, glue code, and configuration carry no tag.
+- If you cannot name the behavior a line produces, do not tag it.
+- A test tag may end with a level: \`unit\`, \`integration\`, or \`e2e\`.
+
+## In CI
+
+\`\`\`shell
+spec check . --ci --base "$(git merge-base HEAD origin/main)"
+\`\`\`
+
+Without \`--base\`, \`check\` diffs against \`HEAD\`, which in a CI checkout already holds the change, so the removal and loss checks find nothing to report.
+
+## Requirement authoring standard
+
+<!-- @spec CHRT-024 -->
+
+The rules every new requirement is written against. The statement shapes and the statement rules are also checked at write time and by \`spec check\`.
+
+0. **A requirement is one rule of the product's behavior, stated from the user's point of view.** The statement rules below are the mechanical half of this rule: \`spec req\`, \`amend\`, \`supersede\`, \`move\`, and \`accept\` refuse a statement that breaks one, \`spec check\` reports an Active statement that breaks one as \`STATEMENT_RULES\`, and \`spec lint\` lists every finding. The judgment half stays with the author.
+1. **One behavior per requirement.** A ticket usually splits into several requirements. Never mint one requirement per ticket.
+2. **Write the statement in a fixed shape.** Pick the sentence shape that matches the situation. The word "shall" separates who acts from the observable result:
+
+   | Situation | Shape | Example |
+   | --- | --- | --- |
+   | Always true | The \`<system>\` shall \`<result>\` | The spec CLI shall write JSON output to stdout only. |
+   | Triggered by an event | When \`<trigger>\`, the \`<system>\` shall \`<result>\` | When an unknown requirement id is passed, spec resolve shall print \`[]\` and exit 0. |
+   | Only in a certain state | While \`<state>\`, the \`<system>\` shall \`<result>\` | While the index file is missing, read commands shall rebuild it before answering. |
+   | Handling something going wrong | If \`<failure>\`, then the \`<system>\` shall \`<result>\` | If the results file cannot be parsed, then spec check shall report the file and exit 2. |
+   | Only when a feature is present | Where \`<feature>\`, the \`<system>\` shall \`<result>\` | Where a member config lists ignore directories, the scanner shall skip them. |
+
+   A statement that fits no row has not yet decided what triggers the behavior or what observably happens.
+
+   A statement may end with a trailing \`so <observable consequence>\` clause ("\u2026shall report NO_SPEC_CONFIG at warning severity, so a lone warning never fails the gate") when the consequence is itself observable. The reason the behavior exists belongs in the why, never in the statement.
+
+   One promise per statement. A result that chains two behaviors with \`and\`, or that sets two severities, is two requirements: a single test must be able to prove the whole statement. Prefer \`When\`, \`If \u2026 then\`, and the bare \`shall\` form. Use \`While\` and \`Where\` only when a state or a feature is what gates the behavior.
+3. **It must make sense on its own.** A reader who sees only this one statement, in search results or a report, understands it. A statement that says "the normalization" or "that prefix" without naming the subject fails.
+4. **Describe what it does, not how.** Say what a user or calling agent observes. If renaming an internal function would make the statement wrong, it is written at the wrong level.
+5. **No expiration dates.** No "currently", no "the new behavior", no references to things that were removed.
+6. **The why states what breaks.** Answer "what goes wrong if this stops being true". Never restate the requirement in other words.
+7. **Three link types, three jobs.** Tests prove it. Code implements it. Tickets are only history: never an id, never proof.
+8. **File it where the promise lives, and search first.** Pick the domain whose charter covers the behavior, and run \`spec query\` before minting. If something close exists, amend it instead.
+
+### Requirement id format
+
+<!-- @spec CHRT-023 -->
+
+- Ids are \`KEY-NNN\`: the domain key, a hyphen, and a three-digit zero-padded number (\`BILLING-010\`).
+- Ids are permanent. A requirement is superseded or deprecated, never renumbered and never deleted.
+
+### The one-promise lint
+
+A domain envelope may declare \`grammar: "ears"\` with \`grammarSeverity: "warning" | "error"\` (default warning). Set both with \`spec domain grammar <KEY>\`, never by hand. In such a domain a statement must fit one of the five shapes, and a statement that fits a shape still fails when:
+
+| Rule | Fails | Passes |
+| --- | --- | --- |
+| Semicolon clause | \`; \` anywhere after the first \`shall\` | \`When a; b holds, X shall \u2026\` |
+| Second subject | \`, and <subject> shall\` after the first \`shall\` | \`X shall A, and shall B\` |
+| Rationale | \`because\`, \`so that\`, \`in order to\` anywhere | a trailing \`, so <observable consequence>\` |
+
+- \`spec check\` reports a nonconforming Active or Draft statement as \`STATEMENT_GRAMMAR\` at the declared severity, one row per statement, the detail naming the first failed shape or rule.
+- \`spec req\`, \`amend\`, \`supersede\`, and \`move\` judge new text at write time: they warn and write under warning, and refuse (exit 2) under error.
+- The lint is a pattern, not a reading: a statement that passes can still chain two behaviors, and the reviewer still owns that call.
+- The TERM domain is exempt.
+
+### The statement rules
+
+Every domain is judged by these rules, whatever its grammar. \`spec req\`, \`amend\`, \`supersede\`, \`move\` (with new text), and \`accept\` refuse a statement that breaks a rule graded \`error\` (the default): exit 2, one \`<rule>: <detail> \u2014 <reason>\` line per finding, rule 0 last. A rule graded \`warning\` writes the statement and prints the same finding lines on stderr. There is no override flag; the \`statementRules\` block of \`check.json\` grades a rule, tunes it, or turns it off. \`spec check\` reports an Active statement that breaks one as \`STATEMENT_RULES\`, one row per rule per statement. The TERM domain is never judged.
+
+| Rule | Reports | Printed reason |
+| --- | --- | --- |
+| \`one-sentence\` | more than one sentence, no closing period, or a line break | a statement is one testable sentence |
+| \`length\` | over \`maxLength\` characters (280 by default) | a sentence a reader holds at once |
+| \`no-file-path\` | a repository path or file name | which file holds what is layout, not behaviour |
+| \`no-test-narration\` | how a test is written | how a test is written is not what the product does |
+| \`no-toolchain-layout\` | CI or tooling layout | how CI and tooling are arranged is not a product behaviour |
+| \`no-history\` | how the requirement changed | a statement says what holds now, not how it got there |
+| \`no-jargon\` | a word from the jargon list | a reader without the codebase cannot parse project jargon |
+| \`no-tool-statement\` | which tool is in use | naming the tool in use is a decision record, not a requirement |
+
+## Authoring requirements (brief \u2192 mint)
+
+<!-- @spec AUTHOR-013 -->
+
+<!-- @spec AUTHOR-012 -->
+
+The procedure for turning a brief or ticket into requirements. Each draft is written to the requirement authoring standard above.
+
+1. **Split the brief.** One requirement per behavior, never one per ticket.
+2. **Place each.** \`spec domain list --json\` prints every charter. File the requirement where the promise lives.
+3. **Dedup.** \`spec query "<phrase>" . --json\` before minting. Overlap means \`spec amend\` or relate the existing requirement.
+4. **Draft to the standard.** Every draft quotes the phrase of the brief it derives from.
+5. **Mint.** \`spec req <domain> --text "<statement>" --why "<what breaks>" [--issue <ticket>]\`.
+6. **Provenance, not identity.** The ticket goes in \`--issue\`, never in an id or a tag.
+7. **Verify.** \`spec index . && spec check . --ci\` (exit 0) and \`spec guard .\` before the PR.
+
+## Command reference
+
+### Invocation
+
+\`\`\`shell
+spec <command> [...]                            # after: bun add -g @spec-engine/spec-engine
+bunx @spec-engine/spec-engine <command> [...]   # without a global install (requires Bun)
+\`\`\`
+
+- Almost every command takes an optional trailing \`platformDir\` positional (default: cwd). The platform dir is the directory that contains \`spec-engine/\`.
+- Every command is non-interactive when stdin is not a TTY.
+- \`--json\` goes to **stdout only**. Guidance, warnings, and diagnostics chrome go to **stderr**. Parse stdout, surface stderr.
+
+### Platforms, members, and pins
+
+- A platform is the directory holding \`spec-engine/\`. When declared, its platform file \`platform-map.json\` is \`{ name, members, ignore }\`.
+- A member is a repository named in that file, carrying a \`{ platform, member }\` marker. A monorepo's coverage columns are its workspace packages, named by path (\`packages/engine\`). A lone repository with no platform file is one column or its packages. A monorepo's files outside every package are one more column, named by the member or, for a lone monorepo, the directory.
+- \`spec-engine.member.json\` adds one fact: the member's pin, \`spec-engine@N\`. \`spec init <name>\` declares and pins in one step.
+- A requirement domain's version is derived from its supersede history. The platform version is the max domain version. Drift compares a member's pin against each referenced requirement's \`changed_at_version\`. A stray \`spec-engine.platform.json\` is ignored with a warning.
+- A member's \`dependsOn\` (the platform's own package names in its manifest) orders \`spec propagation\`: providers before consumers.
+
+### Tags
+
+- The tag is \`@spec KEY-NNN\`, optionally followed by a level token \`unit\` | \`integration\` | \`e2e\` on a test tag. Never write "implements" or "verifies" in the tag.
+- The scanner reads \`.ts\`, \`.tsx\`, \`.js\`, \`.jsx\`, \`.mjs\`, \`.sh\`, \`.lua\`, \`.luau\`, \`.go\`, \`.rs\`, \`.tf\`, \`.toml\`, \`.sql\`, \`.css\`, \`.yml\`, \`.yaml\`, and \`.astro\` files, any file named \`Dockerfile\` or \`Dockerfile.<suffix>\`, and \`.md\` documents, whose tags document.
+- The tag regex ignores the comment leader, so \`--\`, \`//\`, \`#\`, \`<!-- -->\`, and \`/* \u2026 */\` all work.
+- Dot-prefixed directories are skipped except \`.github/\`. \`fixtures/\` directories are ignored everywhere.
+- A tag in implementation code implements; a tag in a test path verifies. A test path contains \`.test.\`, \`.spec.\`, \`__tests__/\`, \`/tests/\`, \`/e2e/\`, or \`.e2e.\`, or ends in \`_test.go\`, \`_test.rs\`, \`_spec.lua\`, or \`_test.lua\`, or lives under \`spec/\` (busted).
+- Rust tests inline under \`#[cfg(test)]\` sit in the implementation file and count as implements; put a verifying tag in \`tests/\` or a \`*_test.rs\` file.
+
+### Exit code contract
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success. Empty results are success (\`[]\` on stdout, guidance on stderr). |
+| 1 | Data-level failure: \`check\` found an error-severity diagnostic; \`guard\` found a loss; \`gate\` failed; \`index\` crashed mid-build. |
+| 2 | Usage/environment error: bad args, not a Spec Engine platform (no \`spec-engine/\`), path-containment violation, invalid \`--limit\`/\`--port\`, FTS5 syntax error. |
+
+Branch on exit codes, not on output text.
+
+### Commands
+
+| Command | Synopsis | \`--json\` | Exits |
+| --- | --- | --- | --- |
+| \`spec index [platformDir]\` | Build or refresh the derived index | yes (IndexResult) | 0 / 1 / 2 |
+| \`spec check [platformDir] [--ci]\` | Integrity + coverage + drift diagnostics | yes (array) | 0 / 1 / 2 |
+| \`spec guard [platformDir] [--against <ref>]\` | Block a change about to lose a requirement, its last implementation, or its last test | yes (array) | 0 / 1 / 2 |
+| \`spec map [platformDir]\` | Requirement \xD7 repo coverage matrix | yes (array) | 0 / 2 |
+| \`spec get <KEY-NNN> [platformDir]\` | One requirement's full record and its tag sites; unknown id is \`[]\` | yes (object, or \`[]\`) | 0 / 2 |
+| \`spec list [platformDir] [--domain KEY] [--status S]\` | Every requirement record in (key, seq) order, history included | yes (array) | 0 / 2 |
+| \`spec query <text> [platformDir]\` | Full-text retrieval over requirements | yes (array) | 0 / 2 |
+| \`spec relations [platformDir]\` | Mermaid graph of \`relates\` links | yes (array) | 0 / 2 |
+| \`spec provenance [issueId] [platformDir]\` | Per-requirement provenance matrix | yes (array) | 0 / 2 |
+| \`spec resolve <files\u2026> [platformDir]\` | Requirements tagged in the given files | yes (array) | 0 / 2 |
+| \`spec propagation <KEY-NNN> [platformDir]\` | Per-repo migrated/drifted state for a superseded requirement | yes (array) | 0 / 2 |
+| \`spec gate <repo> <KEY-NNN> [platformDir]\` | Approval gate: pass iff Active and the pin covers it | yes (object) | 0 / 1 / 2 |
+| \`spec init [repo]\` | Declare a member through platform-map and write its \`spec-engine.member.json\` pin | yes (object) | 0 / 2 |
+| \`spec domain new <KEY>\` / \`spec domain list\` / \`spec domain grammar <KEY>\` | Scaffold / list \`spec-engine/<KEY>/SPEC.json\` / set its statement grammar and severity | \`list\`: yes (array); \`grammar\`: yes (object) | 0 / 2 |
+| \`spec migrate [platformDir]\` | Strip the retired \`livesIn\` and \`verifiedIn\` fields from every \`SPEC.json\` (idempotent) | yes (object) | 0 / 2 |
+| \`spec req <domain-prefix> [platformDir]\` | Piped: next unused id. \`--text\`: author non-interactively | yes (object) | 0 / 2 |
+| \`spec term \u2026\` | Author, list, revise, and confirm glossary terms | yes | 0 / 2 |
+| \`spec glossary [platformDir]\` | Generate \`GLOSSARY.md\` from the TERM store; \`--migrate\`, \`--check\` | yes (object) | 0 / 1 / 2 |
+| \`spec deprecate <KEY-NNN> --reason "\u2026" [platformDir]\` | End an Active/Draft requirement with a recorded reason | yes (object) | 0 / 2 |
+| \`spec supersede <KEY-NNN> [platformDir]\` | Flip to superseded, mint the successor, retag every site to it | yes (object) | 0 / 2 |
+| \`spec move <KEY-NNN> <NEW-DOMAIN> [platformDir]\` | Cross-domain supersede | yes (object) | 0 / 2 |
+| \`spec amend <KEY-NNN> [platformDir]\` | Revise an unshipped entry in place | yes (object) | 0 / 2 |
+| \`spec accept <KEY-NNN> [platformDir]\` | Promote a Draft requirement to Active | yes (object) | 0 / 2 |
+| \`spec lint [KEY \\| KEY-NNN] [platformDir] [--all]\` | Every statement-rule finding for the platform, a domain, or a requirement | yes (array) | 0 / 1 / 2 |
+| \`spec serve [platformDir] [--port N] [--host IP]\` | Local webapp + \`/api/*\` over the index | n/a (HTTP) | 0 / 1 / 2 |
+| \`spec docs [--port N]\` | Serve the bundled docs site offline | n/a (HTTP) | 0 / 1 / 2 |
+| \`spec mcp [platformDir]\` | MCP server over stdio | n/a (JSON-RPC) | 0 / 2 |
+
+Common flags on the index-touching commands (\`index\`, \`check\`, \`map\`, \`get\`, \`list\`, \`query\`, \`relations\`, \`resolve\`, \`propagation\`, \`provenance\`, \`gate\`, \`serve\`):
+
+| Flag | Effect |
+| --- | --- |
+| \`--out <path>\` | Index DB path override. Must resolve inside \`platformDir\` (exit 2 otherwise). |
+| \`--no-prompt\` | Suppress the member-onboarding prompt. |
+| \`--json\` | Machine output (all except \`serve\`). |
+| \`--fresh\` | Read commands only: delete the DB plus WAL/SHM and reindex before answering. |
+
+\`init\`, \`domain list\`, \`req\` register \`--json\` only. \`domain new\` registers none.
+
+**Index freshness.** Read commands (\`map\`, \`get\`, \`list\`, \`query\`, \`relations\`, \`resolve\`, \`propagation\`, \`provenance\`) build the index when it is missing and otherwise trust it. A warm index older than a changed \`SPEC.json\` produces a stderr warning. Tag-only code edits are not detected. \`gate\` always rebuilds cold, and so does \`check --ci\`. After editing specs or tags, pass \`--fresh\`.
+
+### spec index
+
+Build or refresh the derived index.
+
+\`--json\`: \`{ build_id, repos, domains, requirements, tags, diagnostics }\`.
+
+Exit: 0 built / 1 an invalid SPEC.json refused the build, or the build crashed / 2 not a platform or bad args.
+
+- \`build_id\` is deterministic for identical inputs (cold-rebuild equivalence).
+- A \`SPEC.json\` that is not JSON or fails the shared schema refuses the whole build, and the index on disk is left as it was. Every file is parsed first, so one run reports every invalid file. Under \`--json\` stdout holds only the \`INVALID_DOMAIN_FILE\` rows in the \`spec check --json\` row shape; text mode prints only those rows on stderr. Every other index-building command prints only the same rows and exits 1 (\`check\`, \`gate\`, \`guard\`, \`serve\`, and the read commands); a lifecycle command that reindexes for its retag (\`supersede\`, \`amend\`, \`deprecate\`, \`move\`, \`term confirm\`) exits 2 after its write.
+- Also writes \`.spec-engine/doctor.md\`, a list of doc lines that mention a requirement id without an explicit \`<!-- @spec ID -->\` binding.
+
+### spec check
+
+Integrity, coverage, drift, and governance diagnostics.
+
+| Flag | Effect |
+| --- | --- |
+| \`--ci\` | Delete the DB first. Correctness never trusts a warm index. |
+| \`--results <junit.xml>\` | The trusted-red gate: a verifying tag counts only when its test passed. Path resolves inside \`platformDir\`. |
+| \`--base <ref>\` | Diff the requirement set against a git ref (deletion and status-flip governance). |
+| \`--approved-by <list>\` | Approver set for the status-flip check. |
+| \`--require-owner-approval\` | Escalate \`UNAPPROVED_STATUS_FLIP\` from warning to error. |
+| \`--unsourced-change\` | Also warn on superseded requirements with no \`supersedes-via\` issue. |
+
+\`--json\` rows: \`{ code, severity, repo, source_file, line, req_id, detail }\`, nullable except \`code\`, \`severity\`, \`detail\`, sorted deterministically.
+
+Exit: 0 clean or warnings only / 1 any error-severity row / 2 usage.
+
+<!-- @spec CHCK-053 -->
+
+Codes, in \`DiagnosticCode\` order:
+
+| Code | Severity | Condition |
+| --- | --- | --- |
+| \`DUP_ID\` | error | The same requirement id appears twice |
+| \`BROKEN_SUPERSEDE\` | error | A \`supersededBy\` names a missing id, or a \`supersedes\` names a missing id or the entry itself |
+| \`BAD_STATUS\` | error | An entry status outside \`active\` / \`draft\` / \`superseded\` / \`deprecated\` |
+| \`DANGLING_TAG\` | error | A tag references no requirement |
+| \`SUPERSEDED_REFERENCED\` | error | Code still tags a superseded requirement (retag to the successor) |
+| \`DEPRECATED_REFERENCED\` | error | Code still tags a deprecated requirement |
+| \`STATEMENT_GRAMMAR\` | per domain, default warning | A statement fails its domain's declared grammar |
+| \`STATEMENT_RULES\` | error; per rule from \`statementRules.severity\` | An Active statement breaks a statement rule: one row per rule per statement, the detail \`<rule>: <detail> \u2014 <reason>\` |
+| \`DRAFT_REFERENCED\` | error on a verifying tag, warning on an implementing or documenting tag | A tag references a Draft requirement |
+| \`GLOSSARY_DRIFT\` | warning | The committed glossary differs from the one generated from the term store |
+| \`ORPHAN_REQ\` | error | An Active requirement has no implementing tag |
+| \`UNVERIFIED_REQ\` | warning | An Active requirement is implemented but has no verifying tag |
+| \`DRIFT\` | error | A member is pinned behind the version at which a requirement it references changed |
+| \`NO_SPEC_CONFIG\` | warning | A declared member is present on disk with no \`spec-engine.member.json\` |
+| \`BROKEN_RELATES\` | warning | A \`relates\` entry names a nonexistent requirement |
+| \`RELATES_SUPERSEDED\` | warning | A \`relates\` entry names a superseded requirement |
+| \`CYCLIC_SUPERSEDE\` | error | A circular supersession chain |
+| \`SELF_RELATES\` | warning | A \`relates\` entry names its own requirement (dropped, but surfaced) |
+| \`UNKNOWN_ROLE\` | warning | An \`issues\` entry uses a role outside \`created\` / \`supersedes-via\` / \`amends-via\` (surfaced and dropped, never stored) |
+| \`UNSOURCED_CHANGE\` | warning, only with \`--unsourced-change\` | A superseded requirement carries no \`supersedes-via\` issue |
+| \`INVALID_DOMAIN_FILE\` | error | A \`SPEC.json\` is not JSON or fails the shared schema; one row per failing field |
+| \`MIGRATION_PENDING\` | warning | A \`SPEC.json\` still carries the retired \`livesIn\` or \`verifiedIn\` fields; run \`spec migrate\` |
+| \`UNPROVEN_REQ\` | error, only with \`--results\` | An Active requirement has verifying tags but no passing correlated test |
+| \`PROOFS_UNCONFIRMED\` | warning, only without \`--results\` | The proof gate fell back to presence-only mode |
+| \`REQUIREMENT_REMOVED\` | error | An Active requirement present at the base ref is gone with no same-change supersession |
+| \`IMPL_LOST\` | error, when a base ref resolves | The change removes the last implementing tag of a surviving Active requirement |
+| \`VERIFY_LOST\` | warning, when a base ref resolves | The change removes the last verifying tag of a surviving Active requirement |
+| \`SPEC_FILE_DELETED\` | error, when a base ref resolves | A \`SPEC.json\` present at the base ref is gone |
+| \`UNAPPROVED_STATUS_FLIP\` | warning; error with \`--require-owner-approval\` | A flip to superseded or deprecated whose CODEOWNERS domain owner is absent from \`--approved-by\` |
+| \`PARTIAL_PROPAGATION\` | error, needs \`--base\` and \`--results\` | A changed requirement where some bound tests pass and some fail |
+| \`MALFORMED_FILE\` | platform-map's severity: error, or warning for a manifest | A platform file, a package or workspace manifest, or platform-map's per-user file failed to parse or validate |
+| \`MEMBER_MISSING\` | warning | A declared member is not on this machine; it is not scanned |
+| \`MARKER_MISSING\` | warning | A declared member has no marker |
+| \`MARKER_MISMATCH\` | error | A member's marker names a different platform |
+| \`UNLISTED_REPO\` | warning (platform-map info, promoted) | A repository in the platform folder is not a member; its tags are not scanned |
+| \`PLATFORM_NOT_LOCATED\` | warning | A marker names a platform this machine cannot find |
+| \`UNDECLARED_PLATFORM\` | warning (platform-map info, promoted) | A folder of repositories with no platform file; nothing in it is a member |
+| \`SCAN_TRUNCATED\` | warning | A workspace walk hit its depth or entry cap |
+| \`UNDEFINED_TERM\` | error | A \`cites\` entry resolves to no glossary term |
+| \`ORPHAN_TERM\` | warning | An Active term that nothing cites |
+| \`TERM_DRIFT\` | warning | A citation's pin is behind the term's current version |
+| \`SUPERSEDED_TERM_REFERENCED\` | error | A citation names a superseded term |
+
+The four TERM codes are the last four rows. Only \`error\` rows drive exit 1.
+
+The eight codes before them are platform-map's, surfaced with the platform-map code: every platform-map error and warning keeps its severity; \`UNLISTED_REPO\` and \`UNDECLARED_PLATFORM\` are promoted from info to warning because they mean a repository's tags are not scanned; \`UNMATCHED_PATTERN\` and \`AMBIGUOUS_ECOSYSTEM\` are not surfaced. \`repo\` is the diagnostic's subject when it names a member; \`source_file\` is the subject. \`NO_SPEC_CONFIG\` stays Spec Engine's own code: a declared member present on disk with no \`spec-engine.member.json\`.
+
+- Deletion detection runs by default: with no \`--base\`, the working tree is diffed against \`HEAD\` whenever git resolves. An Active requirement absent from the tree without a same-change supersession is \`REQUIREMENT_REMOVED\`. History (superseded and deprecated entries) may never be deleted. Outside git the check stays quiet.
+- Without \`--results\`, \`check\` emits \`PROOFS_UNCONFIRMED\` and skips proof enforcement. The results file is never hashed into \`build_id\`. Generate it with the test runner's JUnit reporter, for example \`bun test --reporter=junit --reporter-outfile=.spec-engine/results.xml\`.
+- Term citations: \`UNDEFINED_TERM\`, \`SUPERSEDED_TERM_REFERENCED\`, and \`TERM_DRIFT\` clear with \`spec term confirm\`.
+- Losses: whenever a base ref resolves (\`--base\`, else \`HEAD\`), \`check\` reports the \`IMPL_LOST\`, \`VERIFY_LOST\`, and \`SPEC_FILE_DELETED\` rows \`spec guard\` would report against that ref. Guard's \`REQUIREMENT_REMOVED\` rows are dropped; the removal check already reports that id.
+- Under \`--ci\` with no \`--base\`, a working tree whose tracked files equal \`HEAD\` makes every loss check pass vacuously, so \`check\` warns on stderr with the line to run instead: \`spec check . --ci --base "$(git merge-base HEAD origin/<default>)"\`. The exit code and stdout are unchanged. <!-- @spec GUARD-031 -->
+- Coverage counts only Active requirements: \`ORPHAN_REQ\` and \`UNVERIFIED_REQ\` fire for Active entries only. <!-- @spec CHCK-032 -->
+
+#### check.json
+
+\`spec-engine/check.json\` regrades diagnostics. Absent means no rules.
+
+\`\`\`json
+{ "severity": [
+  { "code": "UNVERIFIED_REQ", "severity": "error" },
+  { "code": "UNVERIFIED_REQ", "severity": "warning", "match": ["LEGACY", "BILLING-004"] }
+] }
+\`\`\`
+
+- \`code\` is any diagnostic code; \`severity\` is \`error\`, \`warning\`, or \`off\`.
+- \`match\` lists domain keys and requirement ids. A scoped rule applies only to rows whose \`req_id\` is listed or carries a listed key.
+- The most specific rule wins: an id match, then a domain match, then an unscoped rule. Among equals, the later rule wins.
+- \`off\` drops the row from every output.
+- Grading runs inside the operation, so the CLI, \`spec_check\`, and every other surface agree, and exit 1 follows the graded severities.
+- A file that fails the schema (unknown code or key, a bad severity, a malformed match entry) exits 2 with \`spec-engine/check.json: <path>: <reason>\`.
+
+\`statementRules\` configures the statement rules on every surface: the write-time refusal, \`STATEMENT_RULES\`, and \`spec lint\`.
+
+\`\`\`json
+{ "severity": [],
+  "statementRules": {
+    "maxLength": 280,
+    "jargon": ["seam", "rung"],
+    "exemptNames": ["SPEC.json", "spec-engine/"],
+    "severity": { "no-jargon": "off", "length": "error" }
+} }
+\`\`\`
+
+- \`maxLength\` defaults to 280. \`jargon\` replaces the default list (\`seam\`, \`seams\`, \`rung\`, \`rungs\`, \`residue\`, \`matrix entry\`, \`stage runner\`, \`the stage\`).
+- \`exemptNames\` are product names \`no-file-path\` never reports. A name ending in \`/\` exempts every path under it.
+- \`severity\` maps a rule to \`error\`, \`warning\`, or \`off\`. A rule with no entry is \`error\`. \`error\` refuses the write and grades the \`STATEMENT_RULES\` row error; \`warning\` writes, prints the finding on stderr, and grades the row warning; \`off\` turns the rule off everywhere. The \`severity\` array regrades by code after it.
+- The rules: \`one-sentence\`, \`length\`, \`no-file-path\`, \`no-test-narration\`, \`no-toolchain-layout\`, \`no-history\`, \`no-jargon\`, \`no-tool-statement\`. Unknown keys exit 2.
+
+### spec guard
+
+The pre-commit loss gate. Diffs the requirement derivation at \`--against <ref>\` (default \`HEAD\`) against the working tree, scoped to the files in \`git diff\`. Rebuilds the worktree index cold every run.
+
+\`--json\` rows: \`{ kind, req_id, file, line, detail }\`, sorted by \`(req_id, kind, file, line)\`. \`kind\` is one of \`REQUIREMENT_REMOVED\`, \`IMPL_LOST\`, \`VERIFY_LOST\`, \`SPEC_FILE_DELETED\` (\`req_id\` null).
+
+Exit: 0 clean / 1 any loss / 2 usage.
+
+- A loss is suppressed only by ending the requirement in the same change: supersede it (either direction) or \`spec deprecate\` it. There is no override comment.
+- A non-git tree, a repo with no \`HEAD\`, or an unknown ref prints \`NOT_A_GIT_REPO\` to stderr and exits 0.
+- A ref that begins with \`-\` or holds a character outside \`A-Z a-z 0-9 . _ / -\` is refused before git runs: \`guard\` treats it as an unknown ref, and \`check --base\` exits 2.
+- Text mode prints a \`\uD83D\uDED1 spec-guard:\` block per requirement, written in the second person. Relay it verbatim to the user before proceeding.
+
+### spec map
+
+\`--json\` rows keyed \`(req_id, repo)\`: \`{ req_id, domain_key, req_status, req_spec_version, req_changed_at_version, repo, repo_pin, implemented: 0|1, verified: 0|1, test_levels }\`. Text mode renders \`src\`, \`test\`, \`src+test\`, \`\u2014\`.
+
+Exit: 0 / 2.
+
+### spec get
+
+One requirement's full record from the derived index, with the code sites its tags name. Tags are the only record of where a requirement is implemented and verified.
+
+\`--json\`: the \`Requirement\` row \`{ id, key, seq, status, superseded_by, text, why, source_file, line, spec_version, changed_at_version, superseded_at_version }\` plus \`implemented_in: [{ repo, file, line, kind }]\` (implementing and documenting tags) and \`verified_in: [{ repo, file, line, level }]\` (verifying tags), each sorted by (repo, file, line). The same object is served by \`GET /api/requirements/:id\` and \`spec_get\`, and shown on the webapp \`/requirements/:id\` page. Text mode is a one-row table (\`ID STATUS KEY SEQ CHANGED_AT TEXT\`) followed by an \`implemented in:\` and a \`verified in:\` list of \`file:line\`.
+
+Exit: 0 / 2. An unknown id prints \`[]\` on stdout, guidance on stderr, and exits 0. A malformed id exits 2.
+
+### spec list
+
+Every requirement record in (key, seq) order. Unlike \`query\`, superseded and deprecated rows are included and nothing is ranked.
+
+| Flag | Effect |
+| --- | --- |
+| \`--domain KEY\` | Only that domain (case-insensitive key). |
+| \`--status S\` | Only that status: \`active\`, \`draft\`, \`superseded\`, \`deprecated\`. Any other word exits 2. |
+
+\`--json\`: an array of \`Requirement\` rows, the same rows \`GET /api/requirements\` serves. Text mode is the \`ID STATUS KEY SEQ CHANGED_AT TEXT\` table.
+
+Exit: 0 / 2. An empty result is \`[]\` under \`--json\`, guidance on stderr in text mode, exit 0.
+
+### spec query
+
+FTS5 \`MATCH\` syntax. \`--limit N\` (default 10, max 1000).
+
+Exit: 0 / 2 (bare \`AND\` or \`OR\` is an FTS5 grammar error).
+
+- Wrap multi-word phrases in double quotes inside the shell-quoted arg.
+- Results rank ascending (best first). Superseded requirements are excluded.
+- Glossary term definitions ride the same index. A matching term appears in a separate Terms group in text mode, discriminated by \`key\` under \`--json\`.
+
+### spec relations
+
+Text mode: mermaid \`graph LR\`, one node per requirement in a \`relates\` field, one undirected deduped edge per pair. \`--json\` rows: \`{ from_id, to_id, source_file, line }\`, sorted by (from, to).
+
+Exit: 0 / 2. Empty graph is \`[]\` and exit 0.
+
+### spec provenance
+
+Per requirement: the creating issue, the revising issues (\`supersedes-via\`, \`amends-via\`), the backing tests, and the \`source_file:line\` pointer.
+
+| Flag | Effect |
+| --- | --- |
+| \`[issueId]\` positional | Display-only reverse filter. Never a join key. |
+| \`--resolve-issues\` | Overlay tracker title/status/URL. Needs \`SPEC_TRACKER_TOKEN\`; degrades to bare ids without it. |
+
+\`--json\` rows: \`{ req_id, role, issue_id, source_file, line, req_status, implemented, verified, test_levels }\`, sorted on the full composite key.
+
+Exit: 0 / 2. Empty matrix is \`[]\` and exit 0.
+
+### spec resolve
+
+Accepts multiple positionals, comma-split inside one positional, and absolute paths under the platform dir.
+
+| Flag | Effect |
+| --- | --- |
+| \`--req KEY-NNN\` | Reverse query: every tag site for that requirement. Takes no file positionals. |
+
+\`--json\` rows (\`--req\`): \`{ req_id, repo, file, line, kind, level }\` sorted by (repo, file, line). \`kind\` is \`implements\`, \`verifies\`, or \`documents\`.
+
+Exit: 0 / 2. Empty result is \`[]\` and exit 0. Unknown id under \`--req\` is \`[]\`.
+
+Path rules. \`tags.file\` is platform-relative: \`<member>/<path>\` for a file inside a declared member or a workspace package, and the bare \`<path>\` for a file a lone repository owns itself (its directory-named or \`root\` column). The key never carries the checkout's folder name.
+
+- Multi-repo platform: pass \`<repo>/<path>\`, e.g. \`spec resolve api/src/renew.ts .\`
+- Single repo: pass the path from the platform root, e.g. \`spec resolve src/orders.ts .\` or \`spec resolve .github/workflows/ci.yml .\`
+- Absolute paths are normalized against \`platformDir\`. A path outside it exits 2.
+
+### spec propagation
+
+One row per member repo: \`{ repo, state, via_req_id, drifted }\`. \`state\` is one of \`MIGRATED_VERIFIED\`, \`MIGRATED_UNVERIFIED\`, \`ON_PREDECESSOR\`, \`ON_OTHER_DOMAIN_REQ\`, \`NO_DOMAIN_REFERENCE\`.
+
+Rows are in dependency order: a member comes after every member it depends on, read from platform-map's \`dependsOn\` (the platform's own package names in a member's manifest), and members at the same depth come by name. The same order is served by \`/api/propagation/:id\`, \`spec_propagation\`, and the webapp's \`/propagation/:id\` page. A platform with no in-platform dependencies lists members by name.
+
+Exit: 0 / 2.
+
+### spec gate
+
+\`--json\`: \`{ pass, reason, repo, req_id, detail, status, changed_at_version, pinned_spec_version }\`. \`reason\` is one of \`PASS\`, \`NOT_FOUND\`, \`DRAFT\`, \`SUPERSEDED\`, \`DEPRECATED\`, \`VERSION_PIN\`, decided in that order. Pin equality passes.
+
+Exit: 0 pass / 1 fail / 2 unknown repo name or bad args.
+
+### spec init
+
+Declares a member through platform-map and writes \`spec-engine.member.json\`.
+
+| Flag | Effect |
+| --- | --- |
+| \`--specs spec-engine@N\` | Override the pin. |
+| \`--force\` | Rewrite an existing config, preserving \`ignore\`. Any other key refuses, as does a malformed \`ignore\`. |
+| \`--platform <dir>\` | The platform root, for a declared member checked out outside the platform folder. Its location is recorded in platform-map's per-user file first. |
+
+\`--json\`: \`{ action: "wrote", path, pin, source, declared, linked, agent_surface }\`, \`{ action: "already-configured", path, pin, extra_fields, declared, linked, agent_surface }\`, or, on a platform directory, \`{ action: "surface-only", agent_surface }\`. \`declared\` lists the platform-map files written (the platform file, the marker), empty when the member was already declared; \`linked\` is the per-user file written under \`--platform\`, else null; \`agent_surface\` lists the agent-surface files written or changed, \`[]\` on a re-run.
+
+Exit: 0 wrote or already configured / 2. Branch on \`action\`, not the exit code.
+
+- Where the target sits decides what is written:
+  - a repository directly under a platform folder (a directory holding \`spec-engine/\`) that the platform file does not list is declared: a \`platform-map.json\` platform file entry at the root (the file is created when absent) and a \`{ platform, member }\` marker in the repository, then the pin. platform-map declares only a directory with a \`.git\` entry or a \`package.json\`; a plain folder is refused with exit 2;
+  - a declared member only gets the pin (a missing marker is written back);
+  - a workspace package of a monorepo gets a nested pin and no declaration; a repository inside a lone monorepo that is not a workspace package is refused;
+  - a directory under no platform gets the \`spec-engine@1\` fallback pin;
+  - a platform directory (holding \`spec-engine/\`) gets the agent surface and no pin.
+- Every action then installs the agent surface into the repository (the member; the monorepo root for a workspace package), bundled in the npm package under \`dist/agent/\`. Hints for anything left alone go to stderr.
+  - \`AGENTS.md\`: the agent reference between a \`spec-engine:agent-reference:begin\` and a \`spec-engine:agent-reference:end\` HTML comment marker, appended or created, replaced in place when the markers exist; text outside them is never touched. A \`CLAUDE.md\` that does not mention \`AGENTS.md\` gets a hint only.
+  - \`.claude/skills/req-author/\`: written when absent; a differing copy is replaced only under \`--force\`.
+  - \`.mcp.json\`: a \`spec\` server entry (\`spec mcp <platform>\`) merged in; other keys and an existing \`spec\` entry are kept.
+  - \`pre-commit\`: \`spec guard <platform>\`, written to \`.githooks/\` or else \`.git/hooks/\` when no hook exists there; an existing hook gets a hint.
+  - With no platform located, the MCP entry and the hook are skipped.
+- The platform root is platform-map's \`locate()\`: the nearest \`platform-map.json\` or \`.git\` boundary, a marker resolved through the parent directory or the per-user file; the parent directory when it holds \`spec-engine/\`. A \`.git\` boundary between the target and an outer \`spec-engine/\` hides that platform.
+- Default pin: \`--specs\`, else the derived platform version, else \`spec-engine@1\` with a printed note.
+- A resolved path with a \`spec-engine\` segment is refused, except on the engine's own checkout (root package named \`@spec-engine/spec-engine\`), where only the path below the platform root is judged.
+- \`ignore: ["dir", \u2026]\` excludes repo-relative directory prefixes from that repo's scans: \`vendor\` hides \`vendor/x.ts\` but not \`src/vendor/x.ts\`. A monorepo root column excludes its workspace package paths the same way. A monorepo's columns are its workspace manifest's packages.
+
+### spec domain
+
+\`spec domain new <KEY>\` scaffolds \`spec-engine/<KEY>/SPEC.json\`. \`spec domain list\` prints one key per line; \`--json\` prints a sorted array of \`{ key, scope }\` (scope is the charter sentence or null), read from the filesystem.
+
+\`spec domain grammar <KEY> [platformDir] [--grammar ears|freeform] [--severity warning|error]\` sets the envelope's \`grammar\` and/or \`grammarSeverity\` through the validating write path; every other field is written back as read. \`--json\` prints \`{ key, grammar, grammar_severity, file }\` (an unset field is null). An unknown domain, neither flag, or a value outside the enums exits 2. CLI only: no MCP tool or HTTP route.
+
+\`\`\`shell
+spec domain grammar CHCK --severity error
+\`\`\`
+
+Exit: 0 / 2.
+
+### spec migrate
+
+Rewrites every \`SPEC.json\` that still carries the retired \`livesIn\` or \`verifiedIn\` fields through the write seam, which drops them. A file without them is not touched, so a second run writes nothing. Until a file is migrated, the fields are read and ignored, and the next write of a file drops them.
+
+\`--json\`: \`{ files }\`, the platform-relative paths rewritten.
+
+Exit: 0 / 2.
+
+### spec req
+
+| Mode | Behavior |
+| --- | --- |
+| stdin not a TTY, no \`--text\` | Print the bare next unused id (e.g. \`BILLING-010\`), exit 0. No prompts, no writes. |
+| \`--json\`, no \`--text\` | Print \`{ domain, next_id }\`. Same zero-write contract, even on a TTY. |
+| \`--text "<statement>"\` | Append an Active entry with zero prompts. \`--why\`, \`--relates\`, \`--issue <ticket>\` fill the other fields and error without \`--text\`. \`--relates\` repeats and comma-separates. |
+| \`--draft\` | Author the entry as Draft (with \`--text\`, or on a TTY). Off a TTY without \`--text\` it exits 2. |
+| TTY, no flags | Interactive authoring. |
+
+\`--json\` with \`--text\`: \`{ id, file }\`, plus \`clauses: { pattern, condition, system, response }\` when the statement parses as EARS.
+
+Exit: 0 / 2 (ambiguous prefix, unknown domain, grammar refusal, statement-rule refusal).
+
+- The domain prefix is case-insensitive: \`bil\` resolves to \`BILLING\`.
+- The resolved domain's charter is echoed to stderr on every authoring path.
+- Unresolvable \`@<path>\` refs warn on stderr and never block.
+
+### spec term
+
+A term is a requirement row in the reserved \`TERM\` domain: definition in \`statement\`, headword in \`term\`, synonyms in \`aliases\`.
+
+| Form | Effect |
+| --- | --- |
+| \`spec term "<name>" --def "<definition>" [--aliases a,b] [--section s]\` | Append a \`TERM-NNN\`. \`--json\`: \`{ id, file }\`. |
+| \`spec term\` with no \`--def\` | Pure id query, mirrors \`spec req\`: bare next \`TERM\` id, or \`{ domain, next_id }\`. |
+| \`spec term list\` | \`id  name  status\` per line, or \`[{ id, term, status }]\`. Reads the filesystem. |
+| \`spec term revise <TERM-NNN> --def "\u2026"\` | Rewrite the definition in place and bump the TERM envelope's \`specVersion\`. \`--no-bump\` opts out. \`--json\`: \`{ id, file, spec_version }\`. |
+| \`spec term confirm <KEY-NNN> <TERM-NNN>\` | Re-pin a citation to the term's current version (clears \`TERM_DRIFT\`); re-point to the successor when the term is superseded (clears \`SUPERSEDED_TERM_REFERENCED\`). \`--json\`: \`{ req_id, term_id, pinned, file }\`. |
+
+\`spec supersede TERM-NNN\` and \`spec amend TERM-NNN --term/--aliases\` work on term ids as on requirements.
+
+Exit: 0 / 2.
+
+### spec glossary
+
+| Form | Effect |
+| --- | --- |
+| \`spec glossary\` | Overwrite \`GLOSSARY.md\` from the TERM store. Byte-stable: fixed header, terms in id order, \`## {section}\` once per change, one \`- **{term}** \u2014 {statement}\` bullet each. |
+| \`--migrate\` | One-time parse of an existing \`GLOSSARY.md\` into \`TERM-001..N\`. Skips when the TERM domain already has entries. |
+| \`--check\` | Regenerate into a buffer and diff against the committed file. Exit 1 on drift. |
+
+\`--json\`: \`{ generated }\`, \`{ migrated }\`, or \`{ ok }\`.
+
+Exit: 0 / 1 (\`--check\` drift) / 2.
+
+### spec deprecate
+
+Marks an Active/Draft requirement \`deprecated\`, records \`--reason\` on the entry, and removes every \`@spec\` tag of the id from the code. A line that holds only the tag (and its comment leader) is deleted; on a line with other text, only the tag and its level token go. Text mode prints the removed sites.
+
+\`--json\`: \`{ id, file, reason, removed: [{ req_id, repo, file, line, kind, level }] }\`, the sites as they stood before the removal.
+
+Tag sites come from the freshly built index, so \`fixtures/\` and dot-prefixed directories are never touched. Each rewritten line keeps its comment leader, level token, and line ending, and no other line changes. Running the command again finds no sites.
+
+Exit: 0 / 2.
+
+### spec supersede
+
+Requires an Active target. Flips it to \`superseded by NEW\`, mints the successor in the domain file that holds the target, reindexes fresh, and rewrites every \`@spec OLD\` tag in the code to \`@spec NEW\`, keeping the level token and the rest of the line. Text mode prints the rewritten sites. Tag sites come from the freshly built index, so \`fixtures/\` and dot-prefixed directories are never touched. Each rewritten line keeps its comment leader, level token, and line ending, and no other line changes. Running the command again finds no sites.
+
+The successor copies the predecessor's \`why\`, \`relates\`, \`cites\`, \`aliases\`, \`term\`, and \`section\` unless a flag overrides the field. Its \`issues\` hold only the \`created\` row from \`--issue\`.
+
+| Flag | Effect |
+| --- | --- |
+| \`--text\` | The successor statement. Required when not a TTY. |
+| \`--why\`, \`--relates\` | Successor fields. Default to copies of the predecessor's. \`--relates\` repeats or comma-separates and replaces the whole list; an empty value clears it. |
+| \`--issue <ticket>\` | Recorded as \`supersedes-via\` on the predecessor and \`created\` on the successor. |
+| \`--no-bump\` | TERM domain only: keep the authored \`specVersion\`. No-op elsewhere. |
+
+\`--json\`: \`{ old_id, new_id, file, spec_version, retagged: [{ req_id, repo, file, line, kind, level }] }\`, the rewritten sites (\`req_id\` is the old id). On a requirement domain \`spec_version\` is the derived domain version after the supersession, and the same number is stamped as the predecessor's \`supersededAtVersion\`.
+
+Exit: 0 / 2. All guards run before the first byte is written.
+
+### spec move
+
+Cross-domain supersede. Mints the successor as the next id in \`<NEW-DOMAIN>\` (which must exist), copies \`statement\`, \`why\`, \`relates\`, \`cites\`, \`aliases\`, \`term\`, and \`section\` (\`--text\` and \`--why\` override), flips the source to superseded with a cross-domain \`supersededBy\`, and rewrites every tag of the source to the successor as \`spec supersede\` does. The successor carries no \`issues\`.
+
+\`--json\`: \`{ old_id, new_id, from_file, to_file, source_spec_version, target_spec_version, retagged: [...] }\`.
+
+Exit: 0 / 2 (non-Active source, or the target is the source's own domain).
+
+- Both envelopes validate before either is written.
+- The source version advances; the target version is unchanged.
+
+### spec amend
+
+Revise an Active or Draft entry in place. Same id, no version change.
+
+| Flag | Effect |
+| --- | --- |
+| \`--text\`, \`--why\`, \`--relates\` | Field to change. At least one flag is required. Untouched fields stay byte-identical. \`--relates\` repeats or comma-separates and replaces the whole list (the \`--aliases\` idiom); an empty value clears it. |
+| \`--issue <ticket>\` | Append \`amends-via\` provenance. |
+| \`--term\`, \`--aliases\` | TERM ids only. |
+
+\`--json\`: \`{ id, file, fields_changed }\`.
+
+A released requirement is an Active entry present in its domain file at the newest \`v*\` tag merged into HEAD. Its promise does not change in place: a \`--text\`, \`--why\`, \`--term\`, or \`--aliases\` amend refuses with exit 2, naming the tag. Two paths stay open: \`spec supersede\` changes the promise, and an amend of only \`--relates\` or \`--issue\` writes in place. With no \`v*\` tag merged into HEAD, or outside git, every entry is unreleased. A Draft entry always amends.
+
+Exit: 0 / 2 (superseded or deprecated target; a released entry's promise fields).
+
+### spec accept
+
+Promotes a Draft requirement to Active. Every other field stays byte-identical and the domain version does not move. Reword a draft with \`spec amend\` first; end one with \`spec deprecate\`.
+
+\`--json\`: \`{ id, file }\`.
+
+Exit: 0 / 2 (the target is not Draft: nothing is written).
+
+- A Draft never raises \`ORPHAN_REQ\` or \`UNVERIFIED_REQ\` and is not counted in the coverage report. A code tag on one is \`DRAFT_REFERENCED\` (warning).
+
+### spec lint
+
+Every statement-rule finding. Reads \`SPEC.json\` directly, not the index.
+
+| Form | Scope |
+| --- | --- |
+| \`spec lint [platformDir]\` | the platform |
+| \`spec lint <KEY> [platformDir]\` | one domain |
+| \`spec lint <KEY-NNN> [platformDir]\` | one requirement |
+| \`--all\` | Draft requirements as well as Active ones |
+
+Text mode prints \`<id> <rule>: <detail> \u2014 <reason>\` per finding on stdout, then rule 0 on stderr. \`--json\` prints a sorted array of \`{ req_id, rule, detail, reason, source_file, line }\`. The TERM domain is never judged. A lone positional that holds \`spec-engine/\` is the platform dir. CLI only: no MCP tool or HTTP route.
+
+Exit: 0 clean / 1 any finding / 2 usage, unknown domain or id, or a bad \`check.json\`.
+
+### spec serve
+
+Binds one address: \`127.0.0.1\`, or \`--host <ip>\` (a literal loopback, RFC 1918, or \`100.64/10\` address only; anything else exits 2). \`--port 0\` (default) picks a free port. \`--probe\` boots on loopback, fetches \`/\`, and exits 0 or 1. The startup line, \`/api/platform\` (\`name\`), and every page's title and sidebar name the platform (platform file \`name\`, else the directory name), never a path; \`spec mcp\` logs the same name on stderr.
+
+A non-loopback \`--host\` is LAN mode: stdout prints \`http://<ip>:<port>/?token=\u2026\`; every request needs that token (the query parameter is exchanged for an \`HttpOnly; SameSite=Strict\` cookie, then a 302 drops it), else 401. A \`Host\` other than loopback or the bound address is 403. Read-only unless \`--allow-writes\`: non-GET requests, \`/provenance\`, and \`/api/provenance?resolve=1\` answer 403. \`--token\` / \`SPEC_SERVE_TOKEN\` pin the token (\u2265 16 of \`A-Z a-z 0-9 _ -\`); otherwise it is 256 random bits.
+
+When the reindex after a write refuses on an invalid \`SPEC.json\` elsewhere on the platform, the route answers 422 \`{ error: "invalid_domain_file", diagnostics: [...] }\`, the rows in the \`check --json\` shape (the CLI exits 2 with the same rows).
+
+Always-on routes: \`/\`, \`/requirements[/:id]\`, \`/propagation/:id\`, \`/api/coverage\`, \`/api/report\`, \`/api/repos\`, \`/api/platform\`, \`/api/requirements[/:id]\`, \`/api/propagation/:id\`, \`/api/resolve?files=\u2026\`.
+
+Flag-gated, 404 until enabled. \`SPEC_FLAGS\` is comma-separated; unknown keys are ignored.
+
+| \`SPEC_FLAGS\` key | Routes |
+| --- | --- |
+| \`query\` | \`/query\`, \`/api/query?q=&limit=\` |
+| \`relations\` | \`/relations\`, \`/api/relations[?format=mermaid]\` |
+| \`provenance\` | \`/provenance\`, \`/api/provenance[?resolve=1]\`, \`/api/provenance/by-issue?issue=\` |
+| \`editor\` | \`/editor\`, \`POST\` and \`PUT /api/requirements\`, \`POST /api/requirements/:id/supersede\`, \`POST /api/requirements/:id/move\`, \`POST /api/requirements/:id/deprecate\`, \`POST /api/requirements/:id/accept\` |
+| \`glossary\`, \`logs\` | Placeholder pages |
+
+Exit: 0 / 1 / 2.
+
+### spec docs
+
+Serves the prebuilt docs site on \`127.0.0.1\`, fully offline.
+
+- Takes no platform dir. Registers none of \`--json\`, \`--out\`, \`--no-prompt\`.
+- The npm artifact ships the site at \`dist/docs/\`. A source checkout serves \`packages/site/dist\`; run \`bun run build:site\` first, else exit 2.
+- \`--probe\` mirrors \`serve --probe\`.
+
+Exit: 0 / 1 / 2.
+
+### spec mcp
+
+MCP server over stdio. Register it as \`{ "command": "spec", "args": ["mcp", "<platformDir>"] }\`.
+
+| Tool | Returns |
+| --- | --- |
+| \`spec_query\` | FTS hits, the \`spec query --json\` shape |
+| \`spec_resolve\` | files \u2192 requirements |
+| \`spec_req_tags\` | requirement \u2192 tag sites |
+| \`spec_coverage_report\` | per-domain rollup \`{ domain, active, implemented, verified, orphans, unverified }\` |
+| \`spec_check\` | diagnostic rows |
+| \`spec_propagation\` | per-repo migration state |
+| \`spec_next_id\` | \`{ domain, next_id }\`, nothing written |
+| \`spec_get\` | one \`Requirement\` row with \`implemented_in\` and \`verified_in\`, or \`[]\` for an unknown id; the \`spec get --json\` shape |
+| \`spec_list\` | \`Requirement\` rows in (key, seq) order, \`domain\` and \`status\` filters; the \`spec list --json\` shape |
+| \`spec_supersede\` | \`{ old_id, new_id, file, spec_version, retagged }\`, the \`spec supersede --json\` shape; optional \`why\`, \`relates\`, \`issue\` arguments |
+| \`spec_deprecate\` | \`{ id, file, reason, removed }\`, the \`spec deprecate --json\` shape |
+| \`spec_accept\` | \`{ id, file }\`, the \`spec accept --json\` shape |
+| \`spec_req\` | \`{ id, file, clauses? }\`, the \`spec req --text --json\` shape; \`domain\` (key or prefix) and \`text\` required, optional \`why\`, \`relates\`, \`issue\`, \`draft\` |
+| \`spec_amend\` | \`{ id, file, fields_changed }\`, the \`spec amend --json\` shape; \`id\` required, optional \`text\`, \`why\`, \`relates\`, \`issue\` |
+| \`spec_move\` | \`{ old_id, new_id, from_file, to_file, source_spec_version, target_spec_version, retagged }\`, the \`spec move --json\` shape; \`id\` and \`newDomain\` required, optional \`text\`, \`why\` |
+
+Every tool call reindexes fresh. stdout is the protocol channel; chrome goes to stderr. One prompt, \`author_requirements\` (\`brief\` required, \`domain\` optional), returns a static authoring playbook with the brief and the domain's charter substituted. The engine runs no model.
+
+Exit: 0 / 2.
+
+### Gotchas
+
+- **\`fixtures/\` is globally ignored by the tag scanner.** Tags under any \`fixtures/\` folder are test data, not coverage claims.
+- **The index owns nothing.** Never edit \`.spec-engine/index.sqlite\`. Edit the \`SPEC.json\` source and re-run \`spec index\`.
+- **\`storage_unavailable\` / \`SQLITE_IOERR*\` means your environment.** The index runs in WAL mode and needs real file locks. A sandboxed process gets \`SQLITE_IOERR_VNODE\`; re-run unsandboxed or grant write and lock access to \`<platformDir>/.spec-engine/\`. \`SQLITE_BUSY\` means another \`spec\` process holds the index.
+- **Empty is not an error.** Read commands exit 0 with \`[]\` and guidance on stderr.
+- **Determinism is contractual.** JSON outputs are sorted and byte-stable.
+- A directory passed as the last positional is \`platformDir\` only if it contains \`spec-engine/\`. Otherwise it is treated as a file, with a warning.
+`;
+var init_agent_reference = () => {};
+
+// src/operations/agentSurface.ts
+import { existsSync as existsSync3, mkdirSync as mkdirSync2, readFileSync, writeFileSync } from "fs";
+import { dirname as dirname4, join as join5, relative as relative2 } from "path";
+function mcpTemplate(platformArg) {
+  const body = { mcpServers: { spec: { command: "spec", args: ["mcp", platformArg] } } };
+  return `${JSON.stringify(body, null, 2)}
+`;
+}
+function shellArg(arg) {
+  return /^[\w./-]+$/.test(arg) ? arg : `'${arg.replaceAll("'", "'\\''")}'`;
+}
+function writeIfChanged(path, content, out) {
+  if (existsSync3(path) && readFileSync(path, "utf8") === content)
+    return;
+  mkdirSync2(dirname4(path), { recursive: true });
+  writeFileSync(path, content);
+  out.written.push(path);
+}
+function writeReferenceBlock(dir, out) {
+  const path = join5(dir, "AGENTS.md");
+  const block = `${AGENT_BLOCK_BEGIN}
+${AGENT_REFERENCE.trimEnd()}
+${AGENT_BLOCK_END}`;
+  const text = existsSync3(path) ? readFileSync(path, "utf8") : "";
+  const begin = text.indexOf(AGENT_BLOCK_BEGIN);
+  const end = text.indexOf(AGENT_BLOCK_END, begin);
+  let next;
+  if (begin !== -1 && end !== -1) {
+    next = text.slice(0, begin) + block + text.slice(end + AGENT_BLOCK_END.length);
+  } else if (begin !== -1 || text.includes(AGENT_BLOCK_END)) {
+    out.hints.push(`${path} holds only one agent-reference marker; restore the pair to let spec init refresh the block`);
+    return;
+  } else {
+    const gap = text === "" ? "" : text.endsWith(`
+`) ? `
+` : `
+
+`;
+    next = `${text}${gap}${block}
+`;
+  }
+  writeIfChanged(path, next, out);
+  const claude = join5(dir, "CLAUDE.md");
+  if (existsSync3(claude) && !readFileSync(claude, "utf8").includes("AGENTS.md")) {
+    out.hints.push(`${claude} does not reference AGENTS.md; add the line @AGENTS.md so Claude Code loads the spec reference`);
+  }
+}
+function writeSkill(dir, force, out) {
+  for (const [rel, content] of Object.entries(SKILL_FILES)) {
+    const path = join5(dir, ".claude", "skills", rel);
+    if (existsSync3(path) && !force && readFileSync(path, "utf8") !== content) {
+      out.hints.push(`${path} differs from the bundled skill; re-run with --force to replace it`);
+      continue;
+    }
+    writeIfChanged(path, content, out);
+  }
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function writeMcpEntry(dir, platformArg, out) {
+  const path = join5(dir, ".mcp.json");
+  const entry = { command: "spec", args: ["mcp", platformArg] };
+  const wanted = `add to its mcpServers: "spec": ${JSON.stringify(entry)}`;
+  if (!existsSync3(path)) {
+    writeIfChanged(path, mcpTemplate(platformArg), out);
+    return;
+  }
+  let config2;
+  try {
+    config2 = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    out.hints.push(`${path} is not valid JSON; left unchanged. ${wanted}`);
+    return;
+  }
+  if (!isRecord(config2) || config2.mcpServers !== undefined && !isRecord(config2.mcpServers)) {
+    out.hints.push(`${path} is not an MCP server config object; left unchanged. ${wanted}`);
+    return;
+  }
+  const servers = config2.mcpServers ?? {};
+  if (servers.spec !== undefined) {
+    if (JSON.stringify(servers.spec) !== JSON.stringify(entry)) {
+      out.hints.push(`${path} already has a spec server entry; left unchanged. Expected ${wanted}`);
+    }
+    return;
+  }
+  config2.mcpServers = { ...servers, spec: entry };
+  writeIfChanged(path, `${JSON.stringify(config2, null, 2)}
+`, out);
+}
+function writeHook(dir, platformArg, out) {
+  const command = `spec guard ${shellArg(platformArg)}`;
+  const hooksDir = [join5(dir, ".githooks"), join5(dir, ".git", "hooks")].find(isExistingDir);
+  if (hooksDir === undefined) {
+    out.hints.push(`${dir} has no hooks directory; add a pre-commit hook that runs: ${command}`);
+    return;
+  }
+  const path = join5(hooksDir, "pre-commit");
+  if (existsSync3(path)) {
+    if (!readFileSync(path, "utf8").includes(command)) {
+      out.hints.push(`${path} already exists; left unchanged. Add this line to it: ${command}`);
+    }
+    return;
+  }
+  writeFileSync(path, PRE_COMMIT.replace("spec guard .", command), { mode: 493 });
+  out.written.push(path);
+  if (hooksDir.endsWith(".githooks")) {
+    out.hints.push(`git runs ${path} only after: git config core.hooksPath .githooks`);
+  }
+}
+function writeAgentSurface(input) {
+  const out = { written: [], hints: [] };
+  writeReferenceBlock(input.dir, out);
+  writeSkill(input.dir, input.force, out);
+  if (input.platformDir === null) {
+    out.hints.push("no platform was located, so the MCP server and the pre-commit hook were skipped; re-run spec init once the repository belongs to a platform");
+    return out;
+  }
+  const platformArg = relative2(input.dir, input.platformDir) || ".";
+  writeMcpEntry(input.dir, platformArg, out);
+  writeHook(input.dir, platformArg, out);
+  return out;
+}
+var AGENT_BLOCK_BEGIN = "<!-- spec-engine:agent-reference:begin -->", AGENT_BLOCK_END = "<!-- spec-engine:agent-reference:end -->", AGENT_REFERENCE, SKILL_FILES, PRE_COMMIT = `#!/bin/sh
+spec guard .
+exit $?
+`;
+var init_agentSurface = __esm(() => {
+  init_SKILL();
+  init_agent_reference();
+  init_constants();
+  AGENT_REFERENCE = agent_reference_default.replace(/^---\n[\s\S]*?\n---\n+/, "").replace(/^<!-- @spec [A-Z][A-Z0-9]*-\d+ -->\n\n?/gm, "").replace(/ <!-- @spec [A-Z][A-Z0-9]*-\d+ -->/g, "");
+  SKILL_FILES = { "req-author/SKILL.md": SKILL_default };
+});
+
 // src/operations/_result.ts
 function fail(reason, detail, extra = {}) {
   const out = { ok: false, reason, detail };
@@ -2936,8 +4022,8 @@ var init__result = __esm(() => {
 });
 
 // src/operations/init.ts
-import { existsSync as existsSync3, realpathSync, statSync as statSync2 } from "fs";
-import { basename as basename3, join as join5, relative as relative2, resolve as resolve4, sep as sep3 } from "path";
+import { existsSync as existsSync4, realpathSync, statSync as statSync2 } from "fs";
+import { basename as basename3, join as join6, relative as relative3, resolve as resolve4, sep as sep3 } from "path";
 import {
   applyInit,
   applyLink,
@@ -2971,7 +4057,7 @@ function canonicalize(repoDir) {
 function judgeSpecTree(repoDir, canonical, root) {
   if (!hasSpecEngineSegment(canonical))
     return { ok: true };
-  const judged = root !== null && isEnginePlatform(root, ENGINE_PACKAGE_NAME) ? relative2(root, canonical) : canonical;
+  const judged = root !== null && isEnginePlatform(root, ENGINE_PACKAGE_NAME) ? relative3(root, canonical) : canonical;
   if (hasSpecEngineSegment(judged)) {
     return fail("usage", `${repoDir} resolves to ${canonical}, which is inside a spec-engine/ tree \u2014 refusing to scaffold there.`);
   }
@@ -3019,7 +4105,7 @@ function place(repoDir, canonical) {
   return fail("usage", `${canonical} is neither a declared member nor a workspace package of the platform at ${root}`);
 }
 function link(canonical, platformRoot) {
-  if (!existsSync3(join5(canonical, PLATFORM_MAP_FILENAME))) {
+  if (!existsSync4(join6(canonical, PLATFORM_MAP_FILENAME))) {
     return fail("usage", `${canonical} carries no platform-map.json marker, so it is not a declared member; declare it from the platform folder with \`spec init <name>\``);
   }
   const plan = planLink(canonical, { root: resolve4(platformRoot) });
@@ -3034,7 +4120,7 @@ async function resolveMemberPin(input) {
   if (!canon.ok)
     return canon;
   const { canonical } = canon;
-  if (isExistingDir(join5(canonical, CANONICAL_SPECS_DIR))) {
+  if (isExistingDir(join6(canonical, CANONICAL_SPECS_DIR))) {
     return fail("usage", `${canonical} is a platform dir (contains spec-engine/) \u2014 pass a member subdir or cd into one`);
   }
   let linked = null;
@@ -3084,7 +4170,7 @@ function planDeclare(platformDir, name) {
   }
   const candidate = plan.candidates.find((c) => c.name === name);
   if (candidate === undefined) {
-    return fail("usage", `${join5(platformDir, name)} has no .git entry or package.json, so platform-map cannot declare it as a member`);
+    return fail("usage", `${join6(platformDir, name)} has no .git entry or package.json, so platform-map cannot declare it as a member`);
   }
   if (candidate.marker !== undefined && candidate.marker !== plan.platformName) {
     return fail("conflict", `${name} carries a platform-map.json marker for platform "${candidate.marker}", not "${plan.platformName}"`);
@@ -3127,8 +4213,8 @@ async function write(configPath, specs, ignore) {
 }
 async function writeMemberConfig(input) {
   const { canonical, pin } = input;
-  const configPath = join5(canonical, MEMBER_CONFIG_FILENAME);
-  if (!existsSync3(configPath)) {
+  const configPath = join6(canonical, MEMBER_CONFIG_FILENAME);
+  if (!existsSync4(configPath)) {
     await write(configPath, pin, input.ignore);
     return { ok: true, action: "wrote", path: configPath, pin };
   }
@@ -3251,16 +4337,16 @@ function renderDiagnostics(rows, mode) {
 }
 
 // src/operations/_index.ts
-import { existsSync as existsSync4, mkdirSync as mkdirSync2, readdirSync, statSync as statSync3 } from "fs";
-import { dirname as dirname4, join as join6 } from "path";
+import { existsSync as existsSync5, mkdirSync as mkdirSync3, readdirSync, statSync as statSync3 } from "fs";
+import { dirname as dirname5, join as join7 } from "path";
 async function withIndex(opts, fn) {
   const { platformDir, build } = opts;
   const dbPath = opts.dbPath ?? defaultIndexPath(platformDir);
   assertSpecPlatform(platformDir);
-  mkdirSync2(dirname4(dbPath), { recursive: true });
+  mkdirSync3(dirname5(dbPath), { recursive: true });
   if (build === "fresh" || build === "reset")
     coldResetDb(dbPath);
-  const wasMissing = !existsSync4(dbPath);
+  const wasMissing = !existsSync5(dbPath);
   const storage2 = openStorage(dbPath);
   try {
     const warnings = [];
@@ -3281,12 +4367,12 @@ async function withIndex(opts, fn) {
 function staleIndexWarning(platformDir, dbPath) {
   try {
     const dbMtime = statSync3(dbPath).mtimeMs;
-    const specsDir = join6(platformDir, CANONICAL_SPECS_DIR);
+    const specsDir = join7(platformDir, CANONICAL_SPECS_DIR);
     for (const entry of readdirSync(specsDir, { withFileTypes: true })) {
       if (!entry.isDirectory())
         continue;
-      const specPath = join6(specsDir, entry.name, SPEC_FILENAME);
-      if (!existsSync4(specPath))
+      const specPath = join7(specsDir, entry.name, SPEC_FILENAME);
+      if (!existsSync5(specPath))
         continue;
       if (statSync3(specPath).mtimeMs > dbMtime) {
         return `spec: warning \u2014 ${CANONICAL_SPECS_DIR}/${entry.name}/${SPEC_FILENAME} changed after the index was built; results may be stale. Pass --fresh to rebuild.`;
@@ -3348,14 +4434,14 @@ function handleNotAPlatform(e) {
   }
   throw e;
 }
-function handleInvalidDomainFiles(e, json, code = EXIT.FAILURE) {
+async function handleInvalidDomainFiles(e, json, code = EXIT.FAILURE) {
   if (!(e instanceof InvalidDomainFilesError))
     return;
   if (json)
     console.log(renderDiagnostics(e.diagnostics, "json"));
   else
     console.error(renderDiagnostics(e.diagnostics, "text"));
-  process.exit(code);
+  await exit(code);
 }
 function cliFreshTags(platformDir) {
   const fresh = coldFreshTags(platformDir);
@@ -3363,7 +4449,7 @@ function cliFreshTags(platformDir) {
     try {
       return await fresh(reqId);
     } catch (e) {
-      handleInvalidDomainFiles(e, false, EXIT.USAGE);
+      await handleInvalidDomainFiles(e, false, EXIT.USAGE);
       throw e;
     }
   };
@@ -3379,7 +4465,7 @@ function printWarnings(cmdName, warnings) {
   for (const w of warnings ?? []) {
     if (w.kind === "ref")
       console.error(`spec req: warning \u2014 ${w.text}`);
-    else if (w.kind === "grammar")
+    else if (w.kind === "grammar" || w.kind === "statement")
       console.error(`${cmdName}: ${w.text}`);
     else
       console.error(w.text);
@@ -3405,7 +4491,7 @@ async function withReadStorage(opts, fn) {
     });
   } catch (e) {
     handleStorageUnavailable(e, dbPath);
-    handleInvalidDomainFiles(e, json);
+    await handleInvalidDomainFiles(e, json);
     handleNotAPlatform(e);
   }
 }
@@ -3414,6 +4500,7 @@ var init__shared = __esm(() => {
   init_constants();
   init_discover();
   init__index();
+  init_stdout();
   init_errors();
   init_sqlite();
 });
@@ -3424,7 +4511,7 @@ __export(exports_init, {
   runInit: () => runInit,
   initCommand: () => initCommand
 });
-import { resolve as resolve5 } from "path";
+import { dirname as dirname6, join as join8, resolve as resolve5 } from "path";
 import { defineCommand } from "citty";
 function errMessage2(err) {
   return err instanceof Error ? err.message : String(err);
@@ -3456,19 +4543,54 @@ function sourceText(result, json) {
   }
   return "fallback @1";
 }
+function printSurface(surface, json) {
+  for (const hint of surface.hints)
+    console.error(`spec init: ${hint}`);
+  if (json)
+    return;
+  for (const file of surface.written)
+    console.log(`  agent surface: ${file}`);
+}
+function surfaceFor(result, force) {
+  const { placement } = result;
+  return writeAgentSurface({
+    dir: placement.kind === "package" ? placement.platformDir : dirname6(result.path),
+    platformDir: placement.kind === "loose" ? null : placement.platformDir,
+    force
+  });
+}
+function isPlatformDir(dir) {
+  try {
+    return isExistingDir(join8(dir, CANONICAL_SPECS_DIR));
+  } catch {
+    return false;
+  }
+}
+function initPlatformDir(dir, force, json) {
+  const surface = writeAgentSurface({ dir, platformDir: dir, force });
+  if (json) {
+    console.log(JSON.stringify({ action: "surface-only", agent_surface: surface.written }));
+  } else {
+    console.log(`spec init: ${dir} is a platform directory; wrote no member config`);
+  }
+  printSurface(surface, json);
+}
 async function runInit(args) {
   const json = Boolean(args.json);
+  const force = Boolean(args.force);
   const override = typeof args.specs === "string" ? validateOverride(args.specs) : undefined;
   const result = await initMember({
     repoDir: resolveRepoArg(args.repo),
     override,
     platformRoot: typeof args.platform === "string" ? args.platform : undefined,
-    force: Boolean(args.force)
+    force
   });
   if (!result.ok)
     exitOnFailure("spec init", result);
   const source = sourceText(result, json);
   const { declared, linked } = result;
+  const surface = surfaceFor(result, force);
+  const agent_surface = surface.written;
   if (result.action === "already-configured") {
     if (json) {
       console.log(JSON.stringify({
@@ -3477,8 +4599,10 @@ async function runInit(args) {
         pin: result.pin,
         extra_fields: result.extraFields,
         declared,
-        linked
+        linked,
+        agent_surface
       }));
+      printSurface(surface, json);
       return;
     }
     console.log("spec init: already configured");
@@ -3491,6 +4615,7 @@ async function runInit(args) {
       console.log(`  declared: ${file}`);
     if (linked !== null)
       console.log(`  linked: ${linked}`);
+    printSurface(surface, json);
     return;
   }
   if (json) {
@@ -3500,8 +4625,10 @@ async function runInit(args) {
       pin: result.pin,
       source,
       declared,
-      linked
+      linked,
+      agent_surface
     }));
+    printSurface(surface, json);
     return;
   }
   console.log(`spec init: wrote ${result.path}`);
@@ -3511,17 +4638,19 @@ async function runInit(args) {
     console.log(`  declared: ${file}`);
   if (linked !== null)
     console.log(`  linked: ${linked}`);
+  printSurface(surface, json);
 }
 var initCommand;
 var init_init2 = __esm(() => {
   init_src();
   init_constants();
+  init_agentSurface();
   init_init();
   init__shared();
   initCommand = defineCommand({
     meta: {
       name: "init",
-      description: "Declare a member repo and scaffold its spec-engine.member.json"
+      description: "Declare a member repo, scaffold its spec-engine.member.json, and install the agent surface"
     },
     args: {
       repo: {
@@ -3539,7 +4668,7 @@ var init_init2 = __esm(() => {
       },
       force: {
         type: "boolean",
-        description: "Overwrite an existing spec-engine.member.json (refuses if existing has extra keys)."
+        description: "Overwrite an existing spec-engine.member.json (refuses if existing has extra keys) and a differing req-author skill."
       },
       json: {
         type: "boolean",
@@ -3547,7 +4676,11 @@ var init_init2 = __esm(() => {
       }
     },
     async run({ args }) {
-      await runInit(args);
+      const repoDir = resolveRepoArg(args.repo);
+      if (isPlatformDir(repoDir))
+        initPlatformDir(repoDir, Boolean(args.force), Boolean(args.json));
+      else
+        await runInit(args);
     }
   });
 });
@@ -3612,7 +4745,7 @@ function listFlag(rawArgs, name, parsed) {
   }
   return raw.flatMap((v) => v.split(",")).map((v) => v.trim()).filter((v) => v !== "");
 }
-var platformDirArg, outArg, jsonArg, freshArg, noPromptArg, livesArg, testsArg, relatesArg;
+var platformDirArg, outArg, jsonArg, freshArg, noPromptArg, relatesArg;
 var init__args = __esm(() => {
   init_constants();
   platformDirArg = {
@@ -3633,14 +4766,6 @@ var init__args = __esm(() => {
     type: "boolean",
     description: "Suppress the interactive onboarding prompt for siblings missing spec-engine.member.json (they surface as NO_SPEC_CONFIG warnings)"
   };
-  livesArg = {
-    type: "string",
-    description: "Lives in (livesIn) paths: repeat the flag or comma-separate; an empty value clears the list"
-  };
-  testsArg = {
-    type: "string",
-    description: "Verified in (verifiedIn) test paths: repeat the flag or comma-separate; an empty value clears the list"
-  };
   relatesArg = {
     type: "string",
     description: "Related requirement ids (relates): repeat the flag or comma-separate; an empty value clears the list"
@@ -3652,8 +4777,8 @@ var exports_commands = {};
 __export(exports_commands, {
   indexCommand: () => indexCommand
 });
-import { mkdirSync as mkdirSync3 } from "fs";
-import { dirname as dirname5 } from "path";
+import { mkdirSync as mkdirSync4 } from "fs";
+import { dirname as dirname7 } from "path";
 import { defineCommand as defineCommand2 } from "citty";
 var indexCommand;
 var init_commands = __esm(() => {
@@ -3700,7 +4825,7 @@ var init_commands = __esm(() => {
       let storage2;
       try {
         assertSpecPlatform(platformDir);
-        mkdirSync3(dirname5(dbPath), { recursive: true });
+        mkdirSync4(dirname7(dbPath), { recursive: true });
         storage2 = openStorage(dbPath);
         const result = await runIndex({ platformDir, storage: storage2 });
         if (args.json) {
@@ -3719,7 +4844,7 @@ var init_commands = __esm(() => {
           console.error(formatNotASpecPlatform(err.platformDir));
           process.exit(EXIT.USAGE);
         }
-        handleInvalidDomainFiles(err, !!args.json);
+        await handleInvalidDomainFiles(err, !!args.json);
         console.error("spec index FAILED:", err);
         process.exit(EXIT.FAILURE);
       } finally {
@@ -3729,6 +4854,87 @@ var init_commands = __esm(() => {
   });
 });
 
+// src/base/gitBase.ts
+function gitEnv() {
+  return Object.fromEntries(Object.entries(process.env).filter(([k]) => !k.startsWith("GIT_") || k.startsWith("GIT_CONFIG")));
+}
+function isSafeRef(ref) {
+  return /^[A-Za-z0-9._/][A-Za-z0-9._/-]*$/.test(ref);
+}
+function gitRepoPrefix(platformDir) {
+  const proc = Bun.spawnSync(["git", "rev-parse", "--show-prefix"], {
+    cwd: platformDir,
+    env: gitEnv()
+  });
+  if (proc.exitCode !== 0)
+    return "";
+  return proc.stdout.toString().trim();
+}
+function gitRefResolves(platformDir, ref) {
+  if (!isSafeRef(ref))
+    return false;
+  const proc = Bun.spawnSync(["git", "rev-parse", "--verify", "--quiet", `${ref}^{commit}`], {
+    cwd: platformDir,
+    env: gitEnv()
+  });
+  return proc.exitCode === 0;
+}
+function gitShow(platformDir, ref, relPath) {
+  if (!isSafeRef(ref))
+    return null;
+  const full = `${gitRepoPrefix(platformDir)}${relPath}`;
+  const proc = Bun.spawnSync(["git", "show", `${ref}:${full}`], {
+    cwd: platformDir,
+    env: gitEnv()
+  });
+  if (proc.exitCode !== 0)
+    return null;
+  return proc.stdout.toString();
+}
+function gitLsTree(platformDir, ref, dir) {
+  if (!isSafeRef(ref))
+    return [];
+  const prefix = gitRepoPrefix(platformDir);
+  const proc = Bun.spawnSync(["git", "ls-tree", "-r", "--name-only", ref, "--", `${prefix}${dir}`], { cwd: platformDir, env: gitEnv() });
+  if (proc.exitCode !== 0)
+    return [];
+  return proc.stdout.toString().split(`
+`).map((l) => l.trim()).filter((l) => l.length > 0).map((l) => prefix.length > 0 && l.startsWith(prefix) ? l.slice(prefix.length) : l);
+}
+function gitTreeMatchesHead(platformDir) {
+  return Bun.spawnSync(["git", "diff", "--quiet", "HEAD", "--", ".", ":!.spec-engine"], {
+    cwd: platformDir
+  }).exitCode === 0;
+}
+function gitDiffNameStatus(platformDir, ref) {
+  if (!isSafeRef(ref))
+    return [];
+  const proc = Bun.spawnSync(["git", "diff", "--name-status", "--no-renames", "--relative", ref, "--"], { cwd: platformDir, env: gitEnv() });
+  if (proc.exitCode !== 0)
+    return [];
+  const rows = [];
+  for (const line of proc.stdout.toString().split(`
+`)) {
+    if (line.length === 0)
+      continue;
+    const parts = line.split("\t");
+    const status = (parts[0] ?? "").trim().toUpperCase();
+    const path = (parts[parts.length - 1] ?? "").trim();
+    if (status.length === 0 || path.length === 0)
+      continue;
+    rows.push({ status, path });
+  }
+  return rows;
+}
+function newestReleaseTag(platformDir) {
+  const proc = Bun.spawnSync(["git", "tag", "--list", "v*", "--merged", "HEAD", "--sort=-v:refname"], { cwd: platformDir, env: gitEnv() });
+  if (proc.exitCode !== 0)
+    return null;
+  const tag = proc.stdout.toString().split(`
+`)[0]?.trim() ?? "";
+  return tag !== "" && isSafeRef(tag) ? tag : null;
+}
+
 // src/check/proven.ts
 function normalizeToSegments(path) {
   const out = [];
@@ -3852,74 +5058,6 @@ var init_proven = __esm(() => {
   init_src();
 });
 
-// src/base/gitBase.ts
-function isSafeRef(ref) {
-  return /^[A-Za-z0-9._/][A-Za-z0-9._/-]*$/.test(ref);
-}
-function gitRepoPrefix(platformDir) {
-  const proc = Bun.spawnSync(["git", "rev-parse", "--show-prefix"], { cwd: platformDir });
-  if (proc.exitCode !== 0)
-    return "";
-  return proc.stdout.toString().trim();
-}
-function gitRefResolves(platformDir, ref) {
-  if (!isSafeRef(ref))
-    return false;
-  const proc = Bun.spawnSync(["git", "rev-parse", "--verify", "--quiet", `${ref}^{commit}`], {
-    cwd: platformDir
-  });
-  return proc.exitCode === 0;
-}
-function gitShow(platformDir, ref, relPath) {
-  if (!isSafeRef(ref))
-    return null;
-  const full = `${gitRepoPrefix(platformDir)}${relPath}`;
-  const proc = Bun.spawnSync(["git", "show", `${ref}:${full}`], { cwd: platformDir });
-  if (proc.exitCode !== 0)
-    return null;
-  return proc.stdout.toString();
-}
-function gitLsTree(platformDir, ref, dir) {
-  if (!isSafeRef(ref))
-    return [];
-  const prefix = gitRepoPrefix(platformDir);
-  const proc = Bun.spawnSync(["git", "ls-tree", "-r", "--name-only", ref, "--", `${prefix}${dir}`], { cwd: platformDir });
-  if (proc.exitCode !== 0)
-    return [];
-  return proc.stdout.toString().split(`
-`).map((l) => l.trim()).filter((l) => l.length > 0).map((l) => prefix.length > 0 && l.startsWith(prefix) ? l.slice(prefix.length) : l);
-}
-function gitDiffNameStatus(platformDir, ref) {
-  if (!isSafeRef(ref))
-    return [];
-  const proc = Bun.spawnSync(["git", "diff", "--name-status", "--no-renames", "--relative", ref, "--"], {
-    cwd: platformDir
-  });
-  if (proc.exitCode !== 0)
-    return [];
-  const rows = [];
-  for (const line of proc.stdout.toString().split(`
-`)) {
-    if (line.length === 0)
-      continue;
-    const parts = line.split("\t");
-    const status = (parts[0] ?? "").trim().toUpperCase();
-    const path = (parts[parts.length - 1] ?? "").trim();
-    if (status.length === 0 || path.length === 0)
-      continue;
-    rows.push({ status, path });
-  }
-  return rows;
-}
-function newestReleaseTag(platformDir) {
-  const proc = Bun.spawnSync(["git", "tag", "--list", "v*", "--merged", "HEAD", "--sort=-v:refname"], { cwd: platformDir });
-  if (proc.exitCode !== 0)
-    return null;
-  const tag = proc.stdout.toString().split(`
-`)[0]?.trim() ?? "";
-  return tag !== "" && isSafeRef(tag) ? tag : null;
-}
-
 // src/check/codeowners.ts
 function parseCodeowners(text) {
   const rules = [];
@@ -3997,18 +5135,18 @@ function matchesSegment(pat, seg) {
 }
 
 // src/authoring/domains.ts
-import { existsSync as existsSync5, readdirSync as readdirSync2 } from "fs";
-import { join as join7 } from "path";
+import { existsSync as existsSync6, readdirSync as readdirSync2 } from "fs";
+import { join as join9 } from "path";
 function normalizeDomainKey(raw) {
   return raw.toUpperCase().replace(/\s+/g, "");
 }
 function listDomainKeys(platformDir) {
-  const specsDir = join7(platformDir, "spec-engine");
-  return readdirSync2(specsDir, { withFileTypes: true }).filter((e) => e.isDirectory() && existsSync5(join7(specsDir, e.name, "SPEC.json"))).map((e) => e.name).sort();
+  const specsDir = join9(platformDir, "spec-engine");
+  return readdirSync2(specsDir, { withFileTypes: true }).filter((e) => e.isDirectory() && existsSync6(join9(specsDir, e.name, "SPEC.json"))).map((e) => e.name).sort();
 }
 async function domainScope(platformDir, key) {
   const { abs: jsonPath, rel: relFile } = specPaths(platformDir, key);
-  if (!existsSync5(jsonPath))
+  if (!existsSync6(jsonPath))
     return null;
   let text;
   try {
@@ -4049,166 +5187,28 @@ function requirementsOf(text, sourceFile) {
 }
 async function headMaxSeq(platformDir, key) {
   try {
-    const proc = Bun.spawn(["git", "-C", join7(platformDir, "spec-engine", key), "show", "HEAD:./SPEC.json"], { stdout: "pipe", stderr: "ignore" });
+    const proc = Bun.spawn(["git", "-C", join9(platformDir, "spec-engine", key), "show", "HEAD:./SPEC.json"], { stdout: "pipe", stderr: "ignore", env: gitEnv() });
     const text = await new Response(proc.stdout).text();
     if (await proc.exited !== 0)
-      return 0;
-    return maxSeqOf(requirementsOf(text, specPaths(platformDir, key).rel));
-  } catch {
-    return 0;
-  }
-}
-async function nextRequirementId(platformDir, key) {
-  const { abs: jsonPath, rel: relFile } = specPaths(platformDir, key);
-  if (!existsSync5(jsonPath))
-    return `${key}-001`;
-  const requirements = requirementsOf(await Bun.file(jsonPath).text(), relFile);
-  const maxSeq = Math.max(maxSeqOf(requirements), await headMaxSeq(platformDir, key));
-  const next = String(maxSeq + 1).padStart(3, "0");
-  return `${key}-${next}`;
-}
-var init_domains = __esm(() => {
-  init_src();
-  init_constants();
-  init_src();
-});
-
-// src/authoring/filerefs.ts
-import { existsSync as existsSync6 } from "fs";
-import { resolve as resolve7 } from "path";
-function extractRefsFromText(s) {
-  const out = [];
-  for (const m of s.matchAll(FILE_REF_RE)) {
-    const candidate = (m[1] ?? "").replace(/\.+$/, "");
-    if (candidate.includes("/"))
-      out.push(candidate);
-  }
-  return out;
-}
-function resolveFileRef(platformDir, ref) {
-  const root = resolve7(platformDir);
-  const abs = resolve7(root, ref);
-  if (!(abs === root || abs.startsWith(`${root}/`)))
-    return false;
-  return existsSync6(abs);
-}
-var FILE_REF_RE;
-var init_filerefs = __esm(() => {
-  FILE_REF_RE = /(?<![^\s])@([A-Za-z0-9_][A-Za-z0-9_\-./]*)/g;
-});
-
-// src/check/filerefs.ts
-function locateInDomain(raw, sourceFile, requirements, statuses) {
-  const out = [];
-  const rawLines = raw.split(`
-`);
-  let lineCursor = 0;
-  for (const req of requirements) {
-    const found = findRequirementIdLine(rawLines, req.id, lineCursor);
-    if (found >= 0)
-      lineCursor = found + 1;
-    if (statuses.has(req.status.toLowerCase())) {
-      out.push({ sourceFile, line: found >= 0 ? found + 1 : 0, req });
-    }
-  }
-  return out;
-}
-async function locatedEntries(platformDir, statuses) {
-  const out = [];
-  for (const key of listDomainKeys(platformDir)) {
-    const { abs, rel } = specPaths(platformDir, key);
-    let raw;
-    try {
-      raw = await Bun.file(abs).text();
-    } catch {
-      continue;
-    }
-    const parsed = parseDomainText(raw, rel);
-    if (parsed.ok)
-      out.push(...locateInDomain(raw, rel, parsed.data.requirements, statuses));
-  }
-  return out;
-}
-function sortRows(rows) {
-  return rows.sort((a, b) => (a.source_file ?? "").localeCompare(b.source_file ?? "") || (a.line ?? 0) - (b.line ?? 0) || (a.req_id ?? "").localeCompare(b.req_id ?? "") || a.code.localeCompare(b.code) || a.detail.localeCompare(b.detail));
-}
-function row(at, code, severity, detail) {
-  return {
-    code,
-    severity,
-    repo: null,
-    source_file: at.sourceFile,
-    line: at.line,
-    req_id: at.req.id,
-    detail
-  };
-}
-async function brokenFileRefDiagnostics(platformDir) {
-  const rows = [];
-  for (const at of await locatedEntries(platformDir, FILE_REF_STATUSES)) {
-    for (const [field, entries] of [
-      ["livesIn", at.req.livesIn],
-      ["verifiedIn", at.req.verifiedIn]
-    ]) {
-      for (const entry of entries) {
-        const ref = refOf(entry);
-        if (ref.length === 0 || resolveFileRef(platformDir, ref))
-          continue;
-        rows.push(row(at, DiagnosticCode.BROKEN_FILE_REF, "error", `${field} entry ${entry} does not resolve to a file under the platform root`));
-      }
-    }
-  }
-  return sortRows(rows);
-}
-function tagKeys(tags, kinds) {
-  return new Set(tags.filter((t) => kinds.includes(t.kind)).map((t) => `${t.req_id}	${t.file}`));
-}
-function inFileRows(platformDir, members, at, check) {
-  const rows = [];
-  for (const entry of at.req[check.field]) {
-    const ref = refOf(entry);
-    if (ref.length === 0 || !resolveFileRef(platformDir, ref))
-      continue;
-    const file = scannedTagFile(members, platformDir, ref);
-    if (file === null || check.keys.has(`${at.req.id}	${file}`))
-      continue;
-    rows.push(row(at, check.code, "warning", `${check.field} entry ${entry} holds no ${check.missing} tag for ${at.req.id}`));
+      return 0;
+    return maxSeqOf(requirementsOf(text, specPaths(platformDir, key).rel));
+  } catch {
+    return 0;
   }
-  return rows;
 }
-async function inFileTagDiagnostics(platformDir, tags) {
-  const { members } = await discoverRepos(platformDir, { quiet: true });
-  const checks = [
-    {
-      field: "livesIn",
-      code: DiagnosticCode.UNIMPLEMENTED_IN_FILE,
-      keys: tagKeys(tags, ["implements", "documents"]),
-      missing: "implementing or documenting"
-    },
-    {
-      field: "verifiedIn",
-      code: DiagnosticCode.UNVERIFIED_IN_FILE,
-      keys: tagKeys(tags, ["verifies"]),
-      missing: "verifying"
-    }
-  ];
-  const rows = [];
-  for (const at of await locatedEntries(platformDir, IN_FILE_STATUSES)) {
-    for (const check of checks)
-      rows.push(...inFileRows(platformDir, members, at, check));
-  }
-  return sortRows(rows);
+async function nextRequirementId(platformDir, key) {
+  const { abs: jsonPath, rel: relFile } = specPaths(platformDir, key);
+  if (!existsSync6(jsonPath))
+    return `${key}-001`;
+  const requirements = requirementsOf(await Bun.file(jsonPath).text(), relFile);
+  const maxSeq = Math.max(maxSeqOf(requirements), await headMaxSeq(platformDir, key));
+  const next = String(maxSeq + 1).padStart(3, "0");
+  return `${key}-${next}`;
 }
-var FILE_REF_STATUSES, IN_FILE_STATUSES, refOf = (entry) => entry.startsWith("@") ? entry.slice(1) : entry;
-var init_filerefs2 = __esm(() => {
+var init_domains = __esm(() => {
   init_src();
-  init_domains();
-  init_filerefs();
   init_constants();
-  init_discover();
-  init_pipeline();
-  FILE_REF_STATUSES = new Set(["active", "draft"]);
-  IN_FILE_STATUSES = new Set(["active"]);
+  init_src();
 });
 
 // src/check/grammar.ts
@@ -4341,20 +5341,20 @@ var init_removed = __esm(() => {
 });
 
 // src/check/severity.ts
-import { existsSync as existsSync7, readFileSync } from "fs";
-import { join as join8 } from "path";
+import { existsSync as existsSync7, readFileSync as readFileSync2 } from "fs";
+import { join as join10 } from "path";
 function readCheckConfig(platformDir) {
-  const path = join8(platformDir, CHECK_CONFIG_REL);
+  const path = join10(platformDir, CHECK_CONFIG_REL);
   if (!existsSync7(path))
     return { ok: true, config: { severity: [] } };
-  return parseCheckConfigText(readFileSync(path, "utf-8"), CHECK_CONFIG_REL);
+  return parseCheckConfigText(readFileSync2(path, "utf-8"), CHECK_CONFIG_REL);
 }
-function specificity(rule, row2) {
-  if (rule.code !== row2.code)
+function specificity(rule, row) {
+  if (rule.code !== row.code)
     return Specificity.none;
   if (rule.match === undefined)
     return Specificity.code;
-  const id = row2.req_id;
+  const id = row.req_id;
   if (id === null)
     return Specificity.none;
   if (rule.match.includes(id))
@@ -4364,20 +5364,20 @@ function specificity(rule, row2) {
 }
 function applySeverity(rows, rules) {
   const out = [];
-  for (const row2 of rows) {
+  for (const row of rows) {
     let best;
     let bestScore = Specificity.none;
     for (const rule of rules) {
-      const score = specificity(rule, row2);
+      const score = specificity(rule, row);
       if (score !== Specificity.none && score >= bestScore) {
         best = rule;
         bestScore = score;
       }
     }
     if (best === undefined)
-      out.push(row2);
+      out.push(row);
     else if (best.severity !== "off")
-      out.push({ ...row2, severity: best.severity });
+      out.push({ ...row, severity: best.severity });
   }
   return out;
 }
@@ -4424,6 +5424,60 @@ var init_sqlDiagnostics = __esm(() => {
   ]);
 });
 
+// src/check/statementRules.ts
+async function domainRows(platformDir, key, config2, scope) {
+  const { abs, rel } = specPaths(platformDir, key);
+  const raw = await Bun.file(abs).text().catch(() => null);
+  if (raw === null)
+    return [];
+  const parsed = parseDomainText(raw, rel);
+  if (!parsed.ok)
+    return [];
+  const rawLines = raw.split(`
+`);
+  const rows = [];
+  let lineCursor = 0;
+  for (const req of parsed.data.requirements) {
+    const found = findRequirementIdLine(rawLines, req.id, lineCursor);
+    if (found >= 0)
+      lineCursor = found + 1;
+    if (scope.id !== undefined && req.id !== scope.id)
+      continue;
+    if (!scope.statuses.has(req.status.toLowerCase()))
+      continue;
+    for (const f of statementFindings(req.statement, config2)) {
+      rows.push({ req_id: req.id, ...f, source_file: rel, line: found >= 0 ? found + 1 : 0 });
+    }
+  }
+  return rows;
+}
+async function statementRuleRows(platformDir, config2, scope) {
+  const rows = [];
+  for (const key of scope.keys ?? listDomainKeys(platformDir)) {
+    if (key !== "TERM")
+      rows.push(...await domainRows(platformDir, key, config2, scope));
+  }
+  rows.sort((a, b) => a.source_file.localeCompare(b.source_file) || a.line - b.line || a.req_id.localeCompare(b.req_id));
+  return rows;
+}
+async function statementRulesDiagnostics(platformDir, config2) {
+  const rows = await statementRuleRows(platformDir, config2, { statuses: new Set(["active"]) });
+  return rows.map((r) => ({
+    code: DiagnosticCode.STATEMENT_RULES,
+    severity: config2?.severity?.[r.rule] === "warning" ? "warning" : "error",
+    repo: null,
+    source_file: r.source_file,
+    line: r.line,
+    req_id: r.req_id,
+    detail: formatStatementFinding(r)
+  }));
+}
+var init_statementRules2 = __esm(() => {
+  init_src();
+  init_domains();
+  init_constants();
+});
+
 // src/check/statusflip.ts
 function normalizeHandle(h) {
   return (h.startsWith("@") ? h.slice(1) : h).toLowerCase();
@@ -4895,8 +5949,6 @@ function successorEntry(id, pred, fields) {
     supersedes: null,
     supersededBy: null,
     relates: fields.relates,
-    livesIn: fields.livesIn,
-    verifiedIn: fields.verifiedIn,
     issues: fields.issue ? [{ role: "created", id: fields.issue }] : [],
     aliases: [...pred.aliases],
     cites: pred.cites.map((c) => ({ ...c }))
@@ -4914,6 +5966,30 @@ var init__envelope = __esm(() => {
   init__result();
 });
 
+// src/authoring/filerefs.ts
+import { existsSync as existsSync9 } from "fs";
+import { resolve as resolve7 } from "path";
+function extractRefsFromText(s) {
+  const out = [];
+  for (const m of s.matchAll(FILE_REF_RE)) {
+    const candidate = (m[1] ?? "").replace(/\.+$/, "");
+    if (candidate.includes("/"))
+      out.push(candidate);
+  }
+  return out;
+}
+function resolveFileRef(platformDir, ref) {
+  const root = resolve7(platformDir);
+  const abs = resolve7(root, ref);
+  if (!(abs === root || abs.startsWith(`${root}/`)))
+    return false;
+  return existsSync9(abs);
+}
+var FILE_REF_RE;
+var init_filerefs = __esm(() => {
+  FILE_REF_RE = /(?<![^\s])@([A-Za-z0-9_][A-Za-z0-9_\-./]*)/g;
+});
+
 // src/authoring/grammar.ts
 async function grammarConfig(platformDir, key) {
   const freeform = { grammar: "freeform", severity: "warning" };
@@ -4962,8 +6038,35 @@ var init_grammar2 = __esm(() => {
   init_constants();
 });
 
+// src/authoring/statementRules.ts
+function statementRulesVerdict(platformDir, key, statement) {
+  if (key === "TERM" || statement.trim() === "")
+    return { refusal: null, warnings: [] };
+  const config2 = readCheckConfig(platformDir);
+  if (!config2.ok)
+    return { refusal: config2.detail, warnings: [] };
+  const rules = config2.config.statementRules;
+  const findings = statementFindings(statement, rules);
+  const errors = findings.filter((f) => (rules?.severity?.[f.rule] ?? "error") === "error");
+  if (errors.length > 0) {
+    return { refusal: [...errors.map(formatStatementFinding), RULE_ZERO].join(`
+`), warnings: [] };
+  }
+  return {
+    refusal: null,
+    warnings: findings.map((f) => ({
+      kind: "statement",
+      text: `warning \u2014 ${formatStatementFinding(f)}`
+    }))
+  };
+}
+var init_statementRules3 = __esm(() => {
+  init_src();
+  init_severity();
+});
+
 // src/operations/mint.ts
-import { existsSync as existsSync9 } from "fs";
+import { existsSync as existsSync10 } from "fs";
 function unresolvableRefWarnings(platformDir, fieldValues) {
   const out = [];
   for (const value of fieldValues) {
@@ -4978,15 +6081,10 @@ function unresolvableRefWarnings(platformDir, fieldValues) {
 async function mint(input) {
   const { platformDir, key } = input;
   const { abs: specPath, rel: relFile } = specPaths(platformDir, key);
-  if (!existsSync9(specPath)) {
+  if (!existsSync10(specPath)) {
     return fail("not_found", `no domain ${key} (expected ${relFile} under ${platformDir})`);
   }
-  const warnings = unresolvableRefWarnings(platformDir, [
-    input.statement,
-    input.why,
-    ...input.livesIn,
-    ...input.verifiedIn ?? []
-  ]);
+  const warnings = unresolvableRefWarnings(platformDir, [input.statement, input.why]);
   const verdict = await judgeStatementGrammar(platformDir, key, input.statement);
   if (!verdict.ok) {
     if (verdict.severity === "error") {
@@ -4994,6 +6092,10 @@ async function mint(input) {
     }
     warnings.push({ kind: "grammar", text: grammarWarningText("", verdict).slice(2) });
   }
+  const rules = statementRulesVerdict(platformDir, key, input.statement);
+  if (rules.refusal !== null)
+    return fail("usage", rules.refusal, { warnings });
+  warnings.push(...rules.warnings);
   const file = await readEnvelope(platformDir, key);
   if (!file.ok) {
     return fail(file.reason, file.detail, { diagnostics: file.diagnostics, warnings });
@@ -5008,8 +6110,6 @@ async function mint(input) {
     supersedes: null,
     supersededBy: null,
     relates: splitList(input.relates ?? []),
-    livesIn: input.livesIn,
-    verifiedIn: input.verifiedIn ?? [],
     issues: input.issue ? [{ role: "created", id: input.issue }] : [],
     aliases: [],
     cites: input.cites ?? []
@@ -5031,6 +6131,7 @@ var init_mint = __esm(() => {
   init_domains();
   init_filerefs();
   init_grammar2();
+  init_statementRules3();
   init_constants();
   init__envelope();
   init__result();
@@ -5066,8 +6167,6 @@ async function mintTerm(input) {
     supersedes: null,
     supersededBy: null,
     relates: [],
-    livesIn: [],
-    verifiedIn: [],
     issues: [],
     aliases: input.aliases,
     cites: [],
@@ -5168,8 +6267,8 @@ var init_term = __esm(() => {
 });
 
 // src/operations/glossary.ts
-import { existsSync as existsSync10, readFileSync as readFileSync2 } from "fs";
-import { join as join9 } from "path";
+import { existsSync as existsSync11, readFileSync as readFileSync3 } from "fs";
+import { join as join11 } from "path";
 function parseGlossary(md) {
   const terms = [];
   let section = null;
@@ -5221,15 +6320,15 @@ function generateGlossary(terms) {
 }
 function readStoreTerms(platformDir) {
   const { abs: specPath, rel: relFile } = specPaths(platformDir, TERM_KEY);
-  if (!existsSync10(specPath))
+  if (!existsSync11(specPath))
     return [];
-  const parsed = parseDomainText(readFileSync2(specPath, "utf8"), relFile);
+  const parsed = parseDomainText(readFileSync3(specPath, "utf8"), relFile);
   if (!parsed.ok)
     return [];
   return parsed.data.requirements.filter((r) => r.status.toLowerCase() === "active").sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0).map((r) => ({ term: r.term ?? "", statement: r.statement, section: r.section ?? null }));
 }
 function glossaryPath(platformDir) {
-  return join9(platformDir, "GLOSSARY.md");
+  return join11(platformDir, "GLOSSARY.md");
 }
 async function migrateGlossary(platformDir) {
   const store = await termStore(platformDir);
@@ -5240,10 +6339,10 @@ async function migrateGlossary(platformDir) {
     return { ok: true, skipped: true, existing: domain2.requirements.length };
   }
   const gPath = glossaryPath(platformDir);
-  if (!existsSync10(gPath)) {
+  if (!existsSync11(gPath)) {
     return fail("not_found", `no GLOSSARY.md to migrate (expected ${gPath})`);
   }
-  const parsed = parseGlossary(readFileSync2(gPath, "utf8"));
+  const parsed = parseGlossary(readFileSync3(gPath, "utf8"));
   domain2.requirements = parsed.map((t, i) => ({
     id: `${TERM_KEY}-${String(i + 1).padStart(3, "0")}`,
     status: "active",
@@ -5253,8 +6352,6 @@ async function migrateGlossary(platformDir) {
     supersedes: null,
     supersededBy: null,
     relates: [],
-    livesIn: [],
-    verifiedIn: [],
     issues: [],
     aliases: [],
     cites: [],
@@ -5281,10 +6378,10 @@ function glossaryDriftDiagnostic(platformDir) {
   if (terms.length === 0)
     return null;
   const gPath = glossaryPath(platformDir);
-  if (!existsSync10(gPath))
+  if (!existsSync11(gPath))
     return null;
   const generated = generateGlossary(terms);
-  const committed = readFileSync2(gPath, "utf8");
+  const committed = readFileSync3(gPath, "utf8");
   if (generated === committed)
     return null;
   return {
@@ -5300,7 +6397,7 @@ function glossaryDriftDiagnostic(platformDir) {
 function checkGlossary(platformDir) {
   const generated = generateGlossary(readStoreTerms(platformDir));
   const gPath = glossaryPath(platformDir);
-  const committed = existsSync10(gPath) ? readFileSync2(gPath, "utf8") : "";
+  const committed = existsSync11(gPath) ? readFileSync3(gPath, "utf8") : "";
   return { ok: true, clean: generated === committed };
 }
 var GLOSSARY_INTRO = `Canonical names for Spec Engine concepts. When prose, code comments, diagnostics, or
@@ -5314,7 +6411,7 @@ var init_glossary = __esm(() => {
 });
 
 // src/guard/collect.ts
-import { join as join10 } from "path";
+import { join as join12 } from "path";
 function isIgnored(path) {
   return isPathIgnored(path);
 }
@@ -5362,7 +6459,7 @@ async function collectWorktreeReqs(canonicalDir) {
   const activeIds = new Set;
   const supersedesTargets = new Set;
   for (const rel of await findDomainJsonFiles(canonicalDir)) {
-    const text = await Bun.file(join10(canonicalDir, rel)).text();
+    const text = await Bun.file(join12(canonicalDir, rel)).text();
     for (const r of parseReqs(text)) {
       ids.add(r.id);
       if (r.status.toLowerCase() === "active")
@@ -5390,7 +6487,7 @@ async function collectFacts(platformDir, ref, storage2) {
   const deletedSpecFiles = changed.filter((e) => e.status === "D" && isSpecFile(e.path)).map((e) => e.path);
   const base = collectBaseReqs(platformDir, ref, specPaths2);
   const baseTags = collectBaseTags(platformDir, ref, codePaths);
-  const worktree = await collectWorktreeReqs(join10(platformDir, CANONICAL_SPECS_DIR));
+  const worktree = await collectWorktreeReqs(join12(platformDir, CANONICAL_SPECS_DIR));
   const counts = tallyWorktreeTags(storage2);
   return {
     baseReqs: base.reqs,
@@ -5507,14 +6604,63 @@ var init_guard = __esm(() => {
   init_collect();
 });
 
+// src/operations/migrate.ts
+async function migrationPendingDiagnostics(platformDir) {
+  const rows = [];
+  for (const key of listDomainKeys(platformDir)) {
+    const { abs, rel } = specPaths(platformDir, key);
+    const raw = await Bun.file(abs).text().catch(() => "");
+    if (!LEGACY_KEY_RE.test(raw))
+      continue;
+    rows.push({
+      code: DiagnosticCode.MIGRATION_PENDING,
+      severity: "warning",
+      repo: null,
+      source_file: rel,
+      line: null,
+      req_id: null,
+      detail: `${rel} still carries the retired livesIn or verifiedIn fields; run spec migrate to strip them`
+    });
+  }
+  return rows;
+}
+async function migrate(platformDir) {
+  const files = [];
+  for (const key of listDomainKeys(platformDir)) {
+    const file = await readEnvelope(platformDir, key);
+    if (!file.ok)
+      return file;
+    if (!LEGACY_KEY_RE.test(await Bun.file(file.specPath).text()))
+      continue;
+    const res = await validateAndWrite(file.specPath, file.domain, file.relFile);
+    if (!res.ok) {
+      return fail("invalid_domain_file", res.diagnostics.map((d) => d.detail).join(`
+`), {
+        diagnostics: res.diagnostics
+      });
+    }
+    files.push(file.relFile);
+  }
+  return { ok: true, files };
+}
+var LEGACY_KEY_RE;
+var init_migrate = __esm(() => {
+  init_src();
+  init_domains();
+  init_constants();
+  init__envelope();
+  init__result();
+  LEGACY_KEY_RE = /(?<!\\)"(?:livesIn|verifiedIn)"\s*:/;
+});
+
 // src/operations/check.ts
-import { existsSync as existsSync11, readFileSync as readFileSync3 } from "fs";
-import { join as join11 } from "path";
+import { existsSync as existsSync12, readFileSync as readFileSync4 } from "fs";
+import { join as join13 } from "path";
 function readCodeownersText(platformDir) {
-  const path = join11(platformDir, ".github", "CODEOWNERS");
-  if (!existsSync11(path))
+  const path = join13(platformDir, ".github", "CODEOWNERS");
+  if (!existsSync12(path))
     return null;
-  return readFileSync3(path, "utf-8");
+  return readFileSync4(path, "utf-8");
 }
 function domainReqsFromText(text, platformRel) {
   const validated = parseDomainText(text, platformRel);
@@ -5527,7 +6673,7 @@ async function collectChangeReqs(canonicalDir) {
   const relPathById = new Map;
   for (const rel of await findDomainJsonFiles(canonicalDir)) {
     const platformRel = `${CANONICAL_SPECS_DIR}/${rel}`;
-    const text = await Bun.file(join11(canonicalDir, rel)).text();
+    const text = await Bun.file(join13(canonicalDir, rel)).text();
     const parsed = domainReqsFromText(text, platformRel);
     for (const r of parsed.reqs) {
       reqs.push(r);
@@ -5568,7 +6714,7 @@ async function ingestResults(storage2, resultsPath, diagnostics2) {
 }
 async function governanceGate(input, ref, diagnostics2, results) {
   const { platformDir } = input;
-  const change = await collectChangeReqs(join11(platformDir, CANONICAL_SPECS_DIR));
+  const change = await collectChangeReqs(join13(platformDir, CANONICAL_SPECS_DIR));
   const base = collectBaseReqs2(platformDir, ref, diagnostics2);
   diagnostics2.push(...requirementRemoved(base.reqs, change.reqs, (id) => base.relPathById.get(id) ?? null));
   const codeowners = parseCodeowners(readCodeownersText(platformDir) ?? "");
@@ -5611,9 +6757,9 @@ async function check(input, storage2) {
     diagnostics2.push(...unsourcedChanges(superseded, storage2.listProvenance()));
   }
   diagnostics2.push(...await statementGrammarDiagnostics(platformDir));
-  diagnostics2.push(...await brokenFileRefDiagnostics(platformDir));
-  diagnostics2.push(...await inFileTagDiagnostics(platformDir, storage2.listTags()));
+  diagnostics2.push(...await statementRulesDiagnostics(platformDir, checkConfig2.config.statementRules));
   diagnostics2.push(...await supersedesPointerDiagnostics(platformDir));
+  diagnostics2.push(...await migrationPendingDiagnostics(platformDir));
   const glossaryDrift = glossaryDriftDiagnostic(platformDir);
   if (glossaryDrift !== null)
     diagnostics2.push(glossaryDrift);
@@ -5622,7 +6768,7 @@ async function check(input, storage2) {
     await governanceGate(input, input.base, diagnostics2, results);
     diagnostics2.push(...await lossDiagnostics(storage2, platformDir, input.base));
   } else if (gitRefResolves(platformDir, "HEAD")) {
-    const change = await collectChangeReqs(join11(platformDir, CANONICAL_SPECS_DIR));
+    const change = await collectChangeReqs(join13(platformDir, CANONICAL_SPECS_DIR));
     const baseParseSink = [];
     const base = collectBaseReqs2(platformDir, "HEAD", baseParseSink);
     diagnostics2.push(...requirementRemoved(base.reqs, change.reqs, (id) => base.relPathById.get(id) ?? null));
@@ -5640,13 +6786,13 @@ async function check(input, storage2) {
 var LOSS_SEVERITY;
 var init_check = __esm(() => {
   init_src();
-  init_filerefs2();
   init_grammar();
   init_propagation_teeth();
   init_proven();
   init_removed();
   init_severity();
   init_sqlDiagnostics();
+  init_statementRules2();
   init_statusflip();
   init_supersedes();
   init_unsourced();
@@ -5657,6 +6803,7 @@ var init_check = __esm(() => {
   init__result();
   init_glossary();
   init_guard();
+  init_migrate();
   LOSS_SEVERITY = {
     IMPL_LOST: "error",
     SPEC_FILE_DELETED: "error",
@@ -5667,7 +6814,8 @@ var init_check = __esm(() => {
 // src/commands/check.ts
 var exports_check = {};
 __export(exports_check, {
-  checkCommand: () => checkCommand
+  checkCommand: () => checkCommand,
+  CI_BASE_WARNING: () => CI_BASE_WARNING
 });
 import { resolve as resolve8 } from "path";
 import { defineCommand as defineCommand3 } from "citty";
@@ -5690,7 +6838,7 @@ function exitAfterCrash(e) {
   console.error(`spec check: crashed: ${msg}`);
   process.exit(EXIT.USAGE);
 }
-var checkCommand;
+var CI_BASE_WARNING = 'spec check --ci: losses not checked, the working tree equals HEAD. In CI run: spec check . --ci --base "$(git merge-base HEAD origin/<default>)"', checkCommand;
 var init_check2 = __esm(() => {
   init_src();
   init_proven();
@@ -5699,6 +6847,7 @@ var init_check2 = __esm(() => {
   init_prompt();
   init__index();
   init_check();
+  init_stdout();
   init__args();
   init__shared();
   checkCommand = defineCommand3({
@@ -5772,13 +6921,16 @@ var init_check2 = __esm(() => {
           return result;
         });
       } catch (e) {
-        handleInvalidDomainFiles(e, jsonMode);
+        await handleInvalidDomainFiles(e, jsonMode);
         exitAfterCrash(e);
       }
       if (outcome === undefined) {
         process.exit(EXIT.USAGE);
         return;
       }
+      if (args.ci && !args.base && gitTreeMatchesHead(platformDir)) {
+        console.error(CI_BASE_WARNING);
+      }
       const diagnostics2 = [...outcome.diagnostics];
       if (outcome.proofsUnconfirmed) {
         if (jsonMode) {
@@ -5790,14 +6942,14 @@ var init_check2 = __esm(() => {
       console.log(renderDiagnostics(diagnostics2, jsonMode ? "json" : "text"));
       if (!jsonMode)
         console.log(`build_id: ${outcome.buildId}`);
-      process.exit(outcome.failing ? EXIT.FAILURE : EXIT.OK);
+      await exit(outcome.failing ? EXIT.FAILURE : EXIT.OK);
     }
   });
 });
 
 // src/operations/domain.ts
-import { existsSync as existsSync12, mkdirSync as mkdirSync4 } from "fs";
-import { dirname as dirname6, join as join12, resolve as resolve9 } from "path";
+import { existsSync as existsSync13, mkdirSync as mkdirSync5 } from "fs";
+import { dirname as dirname8, join as join14, resolve as resolve9 } from "path";
 function definedFields(options) {
   const out = {};
   if (options.scope !== undefined)
@@ -5817,12 +6969,12 @@ async function newDomain(platformDir, key, options = {}) {
   if (!(resolvedDest === resolvedRoot || resolvedDest.startsWith(`${resolvedRoot}/`))) {
     return fail("usage", `refusing to write outside platformDir (${resolvedDest})`);
   }
-  if (existsSync12(dest))
+  if (existsSync13(dest))
     return fail("conflict", `refusing to overwrite ${dest}`);
-  if (existsSync12(join12(dirname6(dest), "SPEC.md"))) {
+  if (existsSync13(join14(dirname8(dest), "SPEC.md"))) {
     return fail("conflict", `refusing to create ${dest}: domain ${key} already exists as spec-engine/${key}/SPEC.md ` + "\u2014 migrate the SPEC.md first (a fresh empty SPEC.json would shadow it on the next index)");
   }
-  mkdirSync4(dirname6(dest), { recursive: true });
+  mkdirSync5(dirname8(dest), { recursive: true });
   const envelope = { ...scaffoldDomainObject(key, localToday()), ...definedFields(options) };
   const res = await validateAndWrite(dest, envelope, relFile);
   if (!res.ok) {
@@ -6040,12 +7192,12 @@ function sortMatrix(rows) {
     return a.repo.localeCompare(b.repo);
   });
 }
-function cellStatus(row2) {
-  if (row2.implemented === 1 && row2.verified === 1)
+function cellStatus(row) {
+  if (row.implemented === 1 && row.verified === 1)
     return "src+test";
-  if (row2.implemented === 1)
+  if (row.implemented === 1)
     return "src";
-  if (row2.verified === 1)
+  if (row.verified === 1)
     return "test";
   return EMPTY_CELL;
 }
@@ -6058,18 +7210,18 @@ function renderMatrix(rows, mode) {
     return "";
   const repos = Array.from(new Set(sorted.map((r) => r.repo))).sort((a, b) => a.localeCompare(b));
   const byReq = new Map;
-  for (const row2 of sorted) {
-    let entry = byReq.get(row2.req_id);
+  for (const row of sorted) {
+    let entry = byReq.get(row.req_id);
     if (!entry) {
       entry = {
-        domain_key: row2.domain_key,
-        req_id: row2.req_id,
-        req_status: row2.req_status,
+        domain_key: row.domain_key,
+        req_id: row.req_id,
+        req_status: row.req_status,
         cells: new Map
       };
-      byReq.set(row2.req_id, entry);
+      byReq.set(row.req_id, entry);
     }
-    entry.cells.set(row2.repo, cellStatus(row2));
+    entry.cells.set(row.repo, cellStatus(row));
   }
   const header = ["DOMAIN", "REQUIREMENT", "STATUS", ...repos];
   const lines = [header];
@@ -6077,8 +7229,8 @@ function renderMatrix(rows, mode) {
     const cells = repos.map((r) => entry.cells.get(r) ?? EMPTY_CELL);
     lines.push([entry.domain_key, entry.req_id, entry.req_status, ...cells]);
   }
-  const widths = header.map((_, col) => Math.max(...lines.map((row2) => row2[col]?.length ?? 0)));
-  return lines.map((row2) => row2.map((c, i) => c.padEnd(widths[i] ?? 0)).join("  ")).join(`
+  const widths = header.map((_, col) => Math.max(...lines.map((row) => row[col]?.length ?? 0)));
+  return lines.map((row) => row.map((c, i) => c.padEnd(widths[i] ?? 0)).join("  ")).join(`
 `);
 }
 var EMPTY_CELL = "\u2014";
@@ -6214,12 +7366,19 @@ var init_map = __esm(() => {
 
 // src/operations/records.ts
 function getRecord(storage2, id) {
-  const row2 = storage2.getRequirement(id);
-  return {
-    ok: true,
-    row: row2,
-    platformEmpty: row2 === null && storage2.listRequirements().length === 0
-  };
+  const req = storage2.getRequirement(id);
+  if (req === null) {
+    return { ok: true, row: null, platformEmpty: storage2.listRequirements().length === 0 };
+  }
+  const implemented_in = [];
+  const verified_in = [];
+  for (const { repo, file, line, kind, level } of storage2.listTags({ req_id: id })) {
+    if (kind === "verifies")
+      verified_in.push({ repo, file, line, level: level ?? null });
+    else
+      implemented_in.push({ repo, file, line, kind });
+  }
+  return { ok: true, row: { ...req, implemented_in, verified_in }, platformEmpty: false };
 }
 function listRecords(storage2, filter = {}) {
   const rows = storage2.listRequirements(filter);
@@ -6255,8 +7414,18 @@ function renderRecords(rows, mode) {
     lines.push([r.id, r.status, r.key, String(r.seq), String(r.changed_at_version), r.text]);
   }
   const fixed = HEADER.length - 1;
-  const widths = HEADER.slice(0, fixed).map((_, col) => Math.max(...lines.map((row2) => row2[col]?.length ?? 0)));
-  return lines.map((row2) => row2.map((cell, i) => i < fixed ? cell.padEnd(widths[i] ?? 0) : cell).join("  ").trimEnd()).join(`
+  const widths = HEADER.slice(0, fixed).map((_, col) => Math.max(...lines.map((row) => row[col]?.length ?? 0)));
+  return lines.map((row) => row.map((cell, i) => i < fixed ? cell.padEnd(widths[i] ?? 0) : cell).join("  ").trimEnd()).join(`
+`);
+}
+function renderRecord(record) {
+  const sites = (label, list) => list.length === 0 ? [`${label}: none`] : [`${label}:`, ...list.map((s) => `  ${s.file}:${s.line}`)];
+  return [
+    renderRecords([record], "text"),
+    "",
+    ...sites("implemented in", record.implemented_in),
+    ...sites("verified in", record.verified_in)
+  ].join(`
 `);
 }
 var HEADER;
@@ -6283,7 +7452,7 @@ var init_get = __esm(() => {
   getCommand = defineCommand6({
     meta: {
       name: "get",
-      description: "Print one requirement's full record (id, status, key, seq, versions, statement) from the derived index."
+      description: "Print one requirement's full record (id, status, key, seq, versions, statement) and the file:line of every tag that implements or verifies it, from the derived index."
     },
     args: {
       reqId: {
@@ -6320,7 +7489,7 @@ var init_get = __esm(() => {
           console.log("[]");
           return;
         }
-        console.log(args.json ? JSON.stringify(result.row) : renderRecords([result.row], "text"));
+        console.log(args.json ? JSON.stringify(result.row) : renderRecord(result.row));
       });
     }
   });
@@ -6408,11 +7577,11 @@ function renderPropagation(rows, mode) {
     return "";
   const header = ["REPO", "STATE", "VIA", "DRIFT?"];
   const lines = [header];
-  for (const row2 of rows) {
-    lines.push([row2.repo, row2.state, row2.via_req_id ?? EMPTY_CELL2, row2.drifted ? "yes" : "no"]);
+  for (const row of rows) {
+    lines.push([row.repo, row.state, row.via_req_id ?? EMPTY_CELL2, row.drifted ? "yes" : "no"]);
   }
-  const widths = header.map((_, col) => Math.max(...lines.map((row2) => row2[col]?.length ?? 0)));
-  return lines.map((row2) => row2.map((c, i) => c.padEnd(widths[i] ?? 0)).join("  ")).join(`
+  const widths = header.map((_, col) => Math.max(...lines.map((row) => row[col]?.length ?? 0)));
+  return lines.map((row) => row.map((c, i) => c.padEnd(widths[i] ?? 0)).join("  ")).join(`
 `);
 }
 var EMPTY_CELL2 = "\u2014";
@@ -6486,8 +7655,8 @@ function excerptOf(raw) {
 }
 function renderTable(header, rows) {
   const lines = [header, ...rows];
-  const widths = header.map((_, col) => Math.max(...lines.map((row2) => row2[col]?.length ?? 0)));
-  return lines.map((row2) => row2.map((c, i) => c.padEnd(widths[i] ?? 0)).join("  ")).join(`
+  const widths = header.map((_, col) => Math.max(...lines.map((row) => row[col]?.length ?? 0)));
+  return lines.map((row) => row.map((c, i) => c.padEnd(widths[i] ?? 0)).join("  ")).join(`
 `);
 }
 function renderQuery(hits, mode) {
@@ -6742,17 +7911,17 @@ function compareReqIds2(a, b) {
 function sortProvenance(rows) {
   return [...rows].sort((a, b) => compareReqIds2(a.req_id, b.req_id) || a.role.localeCompare(b.role) || a.issue_id.localeCompare(b.issue_id) || a.source_file.localeCompare(b.source_file) || a.line - b.line);
 }
-function backingTests(row2) {
+function backingTests(row) {
   let base;
-  if (row2.implemented === 1 && row2.verified === 1)
+  if (row.implemented === 1 && row.verified === 1)
     base = "src+test";
-  else if (row2.implemented === 1)
+  else if (row.implemented === 1)
     base = "src";
-  else if (row2.verified === 1)
+  else if (row.verified === 1)
     base = "test";
   else
     base = "\u2014";
-  return row2.test_levels ? `${base} (${row2.test_levels})` : base;
+  return row.test_levels ? `${base} (${row.test_levels})` : base;
 }
 function renderProvenance(rows, mode) {
   const sorted = sortProvenance(rows);
@@ -6762,12 +7931,12 @@ function renderProvenance(rows, mode) {
   if (sorted.length === 0)
     return "";
   const byReq = new Map;
-  for (const row2 of sorted) {
-    const bucket = byReq.get(row2.req_id);
+  for (const row of sorted) {
+    const bucket = byReq.get(row.req_id);
     if (bucket)
-      bucket.push(row2);
+      bucket.push(row);
     else
-      byReq.set(row2.req_id, [row2]);
+      byReq.set(row.req_id, [row]);
   }
   const lines = [];
   for (const [reqId, links] of byReq) {
@@ -6782,8 +7951,8 @@ function renderProvenance(rows, mode) {
   return lines.join(`
 `);
 }
-function decorateRow(row2, resolved) {
-  const prefix = `  ${row2.role}  ${row2.issue_id}  ${row2.source_file}:${row2.line}`;
+function decorateRow(row, resolved) {
+  const prefix = `  ${row.role}  ${row.issue_id}  ${row.source_file}:${row.line}`;
   if (resolved?.ok && resolved.title && resolved.url) {
     const staleMark = resolved.stale ? " (cached \u2014 refresh failed)" : "";
     return `${prefix}  ${resolved.title} [${resolved.status ?? ""}] ${resolved.url}${staleMark}`;
@@ -6807,12 +7976,12 @@ function renderProvenanceDecorated(rows, resolved, mode) {
   if (sorted.length === 0)
     return "";
   const byReq = new Map;
-  for (const row2 of sorted) {
-    const bucket = byReq.get(row2.req_id);
+  for (const row of sorted) {
+    const bucket = byReq.get(row.req_id);
     if (bucket)
-      bucket.push(row2);
+      bucket.push(row);
     else
-      byReq.set(row2.req_id, [row2]);
+      byReq.set(row.req_id, [row]);
   }
   const lines = [];
   for (const [reqId, links] of byReq) {
@@ -6833,8 +8002,8 @@ var TOKEN_HINT = "set SPEC_TRACKER_TOKEN to resolve issue titles";
 var init_adapter = () => {};
 
 // ../tracker/src/cache.ts
-import { mkdirSync as mkdirSync5 } from "fs";
-import { dirname as dirname7, join as join13 } from "path";
+import { mkdirSync as mkdirSync6 } from "fs";
+import { dirname as dirname9, join as join15 } from "path";
 function isFresh(entry, now, ttlMs = CACHE_TTL_MS) {
   const t = Date.parse(entry.fetched_at);
   if (Number.isNaN(t))
@@ -6848,7 +8017,7 @@ function isValidEntry(e) {
   return typeof r.title === "string" && typeof r.status === "string" && typeof r.url === "string" && typeof r.fetched_at === "string";
 }
 function sidecarPath(platformDir) {
-  return join13(platformDir, ".spec-engine", SIDECAR_FILE);
+  return join15(platformDir, ".spec-engine", SIDECAR_FILE);
 }
 async function readCache(platformDir) {
   try {
@@ -6872,7 +8041,7 @@ async function readCache(platformDir) {
 async function writeCache(platformDir, cache) {
   try {
     const path = sidecarPath(platformDir);
-    mkdirSync5(dirname7(path), { recursive: true });
+    mkdirSync6(dirname9(path), { recursive: true });
     await Bun.write(path, `${JSON.stringify(cache, null, 2)}
 `);
     return true;
@@ -7178,8 +8347,6 @@ async function mintFromFlags(platformDir, key, textFlag, args, rawArgs) {
   await mintAndReport(platformDir, key, {
     statement,
     why: (args.why ?? "").trim(),
-    livesIn: listFlag(rawArgs, "lives", args.lives) ?? [],
-    verifiedIn: listFlag(rawArgs, "tests", args.tests) ?? [],
     relates: listFlag(rawArgs, "relates", args.relates) ?? [],
     issue: (args.issue ?? "").trim() || undefined,
     status: statusOf(args),
@@ -7199,11 +8366,9 @@ async function mintInteractively(platformDir, key, id, status) {
     return;
   }
   const why = (await askLine("Why it matters: ")).trim();
-  const livesIn = listFlag([], "lives", await askLine("Lives in: ")) ?? [];
   await mintAndReport(platformDir, key, {
     statement: requirement,
     why,
-    livesIn,
     issue: undefined,
     status,
     json: false
@@ -7258,8 +8423,6 @@ var init_req = __esm(() => {
       description: "Non-interactive authoring: the Requirement field. When set, the entry appends with zero prompts."
     },
     why: { type: "string", description: "Why it matters field (only with --text)" },
-    lives: livesArg,
-    tests: testsArg,
     relates: relatesArg,
     issue: {
       type: "string",
@@ -7293,9 +8456,9 @@ var init_req = __esm(() => {
         await mintFromFlags(platformDir, key, textFlag, args, rawArgs);
         return;
       }
-      const hasFieldFlags = typeof args.why === "string" || typeof args.lives === "string" || typeof args.tests === "string" || typeof args.relates === "string" || typeof args.issue === "string";
+      const hasFieldFlags = typeof args.why === "string" || typeof args.relates === "string" || typeof args.issue === "string";
       if (hasFieldFlags) {
-        console.error("spec req: --why/--lives/--tests/--relates/--issue require --text (the Requirement field is mandatory)");
+        console.error("spec req: --why/--relates/--issue require --text (the Requirement field is mandatory)");
         process.exit(EXIT.USAGE);
         return;
       }
@@ -7383,8 +8546,8 @@ async function listTermsCommand(platformDirRaw, json) {
     console.log(JSON.stringify(result.rows));
     return;
   }
-  for (const row2 of result.rows) {
-    console.log(`${row2.id}  ${row2.term}  ${row2.status}`);
+  for (const row of result.rows) {
+    console.log(`${row.id}  ${row.term}  ${row.status}`);
   }
 }
 async function reviseTermCommand(opts) {
@@ -7431,8 +8594,8 @@ async function confirmTermCommand(opts) {
     exitOnFailure("spec term confirm", result);
   await withIndex({ platformDir, build: "fresh" }, () => {
     return;
-  }).catch((e) => {
-    handleInvalidDomainFiles(e, false, EXIT.USAGE);
+  }).catch(async (e) => {
+    await handleInvalidDomainFiles(e, false, EXIT.USAGE);
     throw e;
   });
   const { pinned, file } = result;
@@ -7615,7 +8778,7 @@ function resolvePlatform2(platformDirRaw) {
   }
   return platformDir;
 }
-async function migrate(platformDir, json) {
+async function migrate2(platformDir, json) {
   const result = await migrateGlossary(platformDir);
   if (!result.ok)
     exitOnFailure("spec glossary", result);
@@ -7639,7 +8802,7 @@ async function generate(platformDir, json) {
   else
     console.log(`generated GLOSSARY.md from ${result.generated} terms`);
 }
-function check2(platformDir, json) {
+async function check2(platformDir, json) {
   if (checkGlossary(platformDir).clean) {
     if (json)
       console.log(JSON.stringify({ ok: true }));
@@ -7651,13 +8814,14 @@ function check2(platformDir, json) {
   console.error("run `spec glossary .` to regenerate the human view from the store");
   if (json)
     console.log(JSON.stringify({ ok: false }));
-  process.exit(EXIT.FAILURE);
+  await exit(EXIT.FAILURE);
 }
 var glossaryCommand;
 var init_glossary2 = __esm(() => {
   init_constants();
   init_discover();
   init_glossary();
+  init_stdout();
   init__args();
   init__shared();
   glossaryCommand = defineCommand14({
@@ -7681,15 +8845,69 @@ var init_glossary2 = __esm(() => {
       const platformDir = resolvePlatform2(args.platformDir);
       const json = Boolean(args.json);
       if (args.migrate)
-        await migrate(platformDir, json);
+        await migrate2(platformDir, json);
       else if (args.check)
-        check2(platformDir, json);
+        await check2(platformDir, json);
       else
         await generate(platformDir, json);
     }
   });
 });
 
+// src/operations/_retag.ts
+import { readFileSync as readFileSync5, writeFileSync as writeFileSync2 } from "fs";
+import { join as join16 } from "path";
+function retagLine(line, oldId, newId, doc) {
+  const cr = line.endsWith("\r") ? "\r" : "";
+  const body = cr ? line.slice(0, -1) : line;
+  const re = doc ? DOC_BINDING_RE : SPEC_TAG_RE;
+  if (newId !== null) {
+    return body.replace(re, (m, id) => id === oldId ? m.replace(id, newId) : m) + cr;
+  }
+  const stripped = body.replace(new RegExp(`\\s*(?:${re.source})`, "g"), (m, id, level) => {
+    if (id !== oldId)
+      return m;
+    return typeof level === "string" && !LEVELS.has(level) ? m.slice(m.search(TRAILING_WORD)) : "";
+  });
+  if (stripped === body)
+    return line;
+  const rest = stripped.replace(EMPTY_COMMENT_TAIL, "");
+  const residue = rest.trim();
+  return residue === "" || residue === "*" ? null : rest + cr;
+}
+async function applyRetag(platformDir, oldId, newId, freshTags) {
+  const sites = toReqTagRows(await freshTags(oldId));
+  const byFile = new Map;
+  for (const site of sites) {
+    const entry = byFile.get(site.file) ?? { doc: site.kind === "documents", lines: new Set };
+    entry.lines.add(site.line);
+    byFile.set(site.file, entry);
+  }
+  for (const [file, { doc, lines }] of byFile) {
+    const abs = join16(platformDir, file);
+    const out = [];
+    readFileSync5(abs, "utf8").split(`
+`).forEach((line, i) => {
+      const next = lines.has(i + 1) ? retagLine(line, oldId, newId, doc) : line;
+      if (next !== null)
+        out.push(next);
+    });
+    writeFileSync2(abs, out.join(`
+`));
+  }
+  if (sites.length > 0)
+    await freshTags(oldId);
+  return sites;
+}
+var EMPTY_COMMENT_TAIL, TRAILING_WORD;
+var init__retag = __esm(() => {
+  init_docs();
+  init_tags();
+  init_reads2();
+  EMPTY_COMMENT_TAIL = /\s*(?:\/\/|#|--|\/\*+\s*\*+\/|<!--\s*-->)\s*$/;
+  TRAILING_WORD = /\s+[a-z][a-z0-9]*$/;
+});
+
 // src/operations/supersede.ts
 async function supersedeTarget(platformDir, id) {
   const located = await locateEntry(platformDir, id);
@@ -7708,8 +8926,6 @@ async function supersedeTarget(platformDir, id) {
 function successorFields(input, req) {
   return {
     why: (input.why ?? req.why ?? "").trim(),
-    livesIn: input.livesIn ?? [...req.livesIn],
-    verifiedIn: input.verifiedIn ?? [...req.verifiedIn],
     relates: input.relates === undefined ? [...req.relates] : splitList(input.relates)
   };
 }
@@ -7754,15 +8970,17 @@ async function supersede(input, freshTags) {
     }
     warnings.push({ kind: "grammar", text: grammarWarningText("", verdict).slice(2) });
   }
-  const { why, livesIn, verifiedIn, relates } = successorFields(input, req);
-  warnings.push(...unresolvableRefWarnings(platformDir, [input.statement, why, ...livesIn, ...verifiedIn]));
+  const rules = statementRulesVerdict(platformDir, key, input.statement);
+  if (rules.refusal !== null)
+    return fail("usage", rules.refusal);
+  warnings.push(...rules.warnings);
+  const { why, relates } = successorFields(input, req);
+  warnings.push(...unresolvableRefWarnings(platformDir, [input.statement, why]));
   const newId = await nextRequirementId(platformDir, key);
   const issue = input.issue?.trim() || undefined;
   const successor = successorEntry(newId, req, {
     statement: input.statement,
     why,
-    livesIn,
-    verifiedIn,
     relates,
     issue
   });
@@ -7779,18 +8997,19 @@ async function supersede(input, freshTags) {
       warnings
     });
   }
-  const retag = toReqTagRows(await freshTags(id));
-  return { ok: true, oldId: id, newId, file: relFile, specVersion, retag, warnings };
+  const retagged = await applyRetag(platformDir, id, newId, freshTags);
+  return { ok: true, oldId: id, newId, file: relFile, specVersion, retagged, warnings };
 }
 var init_supersede = __esm(() => {
   init_src();
   init_domains();
   init_grammar2();
+  init_statementRules3();
   init_domainJson();
   init__envelope();
   init__result();
+  init__retag();
   init_mint();
-  init_reads2();
 });
 
 // src/resolve/format.ts
@@ -7806,14 +9025,14 @@ function renderResolve(rows, mode) {
     return "";
   const header = ["REQ_ID", "STATUS", "TEXT"];
   const lines = [header];
-  for (const row2 of sorted) {
-    const raw = row2.text ?? "";
+  for (const row of sorted) {
+    const raw = row.text ?? "";
     const truncated = raw.length > TEXT_MAX ? raw.slice(0, TEXT_MAX) + ELLIPSIS2 : raw;
     const text = truncated.replace(/\s+/g, " ").trim();
-    lines.push([row2.id, row2.status, text || EMPTY_CELL4]);
+    lines.push([row.id, row.status, text || EMPTY_CELL4]);
   }
-  const widths = header.map((_, col) => Math.max(...lines.map((row2) => row2[col]?.length ?? 0)));
-  return lines.map((row2) => row2.map((c, i) => c.padEnd(widths[i] ?? 0)).join("  ")).join(`
+  const widths = header.map((_, col) => Math.max(...lines.map((row) => row[col]?.length ?? 0)));
+  return lines.map((row) => row.map((c, i) => c.padEnd(widths[i] ?? 0)).join("  ")).join(`
 `);
 }
 function sortReqTags(rows) {
@@ -7828,8 +9047,8 @@ function renderReqTags(rows, mode) {
     return "";
   const header = ["REPO", "FILE", "LINE", "KIND", "LEVEL"];
   const lines = [header];
-  for (const row2 of sorted) {
-    lines.push([row2.repo, row2.file, String(row2.line), row2.kind, row2.level ?? EMPTY_CELL4]);
+  for (const row of sorted) {
+    lines.push([row.repo, row.file, String(row.line), row.kind, row.level ?? EMPTY_CELL4]);
   }
   const widths = header.map((_, col) => Math.max(...lines.map((l) => (l[col] ?? "").length)));
   return lines.map((l) => l.map((cell, col) => cell.padEnd(widths[col])).join("  ").trimEnd()).join(`
@@ -7873,12 +9092,6 @@ function inputFromArgs(args, rawArgs, platformDir, id, statement) {
   const input = { platformDir, id, statement, noBump: Boolean(args.noBump) };
   if (typeof args.why === "string")
     input.why = args.why;
-  const livesIn = listFlag(rawArgs, "lives", args.lives);
-  if (livesIn !== undefined)
-    input.livesIn = livesIn;
-  const verifiedIn = listFlag(rawArgs, "tests", args.tests);
-  if (verifiedIn !== undefined)
-    input.verifiedIn = verifiedIn;
   const relates = listFlag(rawArgs, "relates", args.relates);
   if (relates !== undefined)
     input.relates = relates;
@@ -7915,14 +9128,6 @@ var init_supersede2 = __esm(() => {
       type: "string",
       description: "Successor's Why it matters (default: copied from the old entry)"
     },
-    lives: {
-      type: "string",
-      description: "Successor's Lives in: repeat or comma-separate; empty clears (default: copied from the old entry)"
-    },
-    tests: {
-      type: "string",
-      description: "Successor's Verified in (verifiedIn): repeat or comma-separate; empty clears (default: copied from the old entry)"
-    },
     relates: {
       type: "string",
       description: "Successor's related ids: repeat or comma-separate; empty clears (default: copied from the old entry)"
@@ -7945,13 +9150,13 @@ var init_supersede2 = __esm(() => {
     },
     json: {
       type: "boolean",
-      description: "Emit { old_id, new_id, file, spec_version, retag } as JSON instead of the text summary"
+      description: "Emit { old_id, new_id, file, spec_version, retagged } as JSON instead of the text summary"
     }
   };
   supersedeCommand = defineCommand15({
     meta: {
       name: "supersede",
-      description: "Supersede a shipped requirement: flip it to superseded, mint the successor, bump specVersion, and emit the retag worklist."
+      description: "Supersede a shipped requirement: flip it to superseded, mint the successor, bump specVersion, and retag every site of it to the successor."
     },
     args: supersedeArgs,
     async run({ args, rawArgs }) {
@@ -7971,21 +9176,18 @@ var init_supersede2 = __esm(() => {
       if (!result.ok)
         exitOnFailure("spec supersede", result);
       printWarnings("spec supersede", result.warnings);
-      const { newId, file, specVersion, retag } = result;
+      const { newId, file, specVersion, retagged } = result;
       if (args.json) {
-        console.log(JSON.stringify({ old_id: id, new_id: newId, file, spec_version: specVersion, retag }));
+        console.log(JSON.stringify({ old_id: id, new_id: newId, file, spec_version: specVersion, retagged }));
       } else {
         console.log(`superseded ${id} \u2192 ${newId} in ${file}`);
         if (specVersion !== null)
           console.log(`specVersion bumped to ${specVersion}`);
-        if (retag.length > 0) {
-          console.log(`retag ${retag.length} site(s) from ${id} to ${newId}:`);
-          console.log(renderReqTags(retag, "text"));
+        if (retagged.length > 0) {
+          console.log(`retagged ${retagged.length} site(s) from ${id} to ${newId}:`);
+          console.log(renderReqTags(retagged, "text"));
         }
       }
-      if (retag.length > 0) {
-        console.error(`note: spec check will report SUPERSEDED_REFERENCED at each remaining ${id} tag until the sites are retagged to ${newId}`);
-      }
     }
   });
 });
@@ -8014,14 +9216,14 @@ async function deprecate(input, freshTags) {
       diagnostics: res.diagnostics
     });
   }
-  const sites = toReqTagRows(await freshTags(id));
-  return { ok: true, id, file: relFile, reason, sites };
+  const removed = await applyRetag(platformDir, id, null, freshTags);
+  return { ok: true, id, file: relFile, reason, removed };
 }
 var init_deprecate = __esm(() => {
   init_src();
   init__envelope();
   init__result();
-  init_reads2();
+  init__retag();
 });
 
 // src/commands/deprecate.ts
@@ -8056,7 +9258,7 @@ var init_deprecate2 = __esm(() => {
       },
       json: {
         type: "boolean",
-        description: "Print { id, file, reason, sites } instead of text"
+        description: "Print { id, file, reason, removed } instead of text"
       }
     },
     async run({ args }) {
@@ -8079,15 +9281,15 @@ var init_deprecate2 = __esm(() => {
       const result = await deprecate({ platformDir, id, reason }, cliFreshTags(platformDir));
       if (!result.ok)
         exitOnFailure("spec deprecate", result);
-      const { file, sites } = result;
+      const { file, removed } = result;
       if (args.json) {
-        console.log(JSON.stringify({ id, file, reason, sites }));
+        console.log(JSON.stringify({ id, file, reason, removed }));
         return;
       }
       console.log(`deprecated ${id} in ${file} \u2014 reason recorded`);
-      if (sites.length > 0) {
-        console.error(`${sites.length} code tag(s) still bind ${id} \u2014 remove or retag them (spec check reports each as DEPRECATED_REFERENCED):`);
-        console.error(renderReqTags(sites, "text"));
+      if (removed.length > 0) {
+        console.log(`removed ${removed.length} tag(s) of ${id}:`);
+        console.log(renderReqTags(removed, "text"));
       }
     }
   });
@@ -8115,8 +9317,6 @@ function successorFields2(input, req) {
   return {
     statement: (input.statement ?? req.statement).trim(),
     why: (input.why ?? req.why ?? "").trim(),
-    livesIn: input.livesIn ?? [...req.livesIn],
-    verifiedIn: input.verifiedIn ?? [...req.verifiedIn],
     relates: [...req.relates]
   };
 }
@@ -8160,13 +9360,12 @@ async function move(input, freshTags) {
       }
       warnings.push({ kind: "grammar", text: grammarWarningText("", verdict).slice(2) });
     }
+    const rules = statementRulesVerdict(platformDir, targetKey, fields.statement);
+    if (rules.refusal !== null)
+      return fail("usage", rules.refusal);
+    warnings.push(...rules.warnings);
   }
-  warnings.push(...unresolvableRefWarnings(platformDir, [
-    fields.statement,
-    fields.why,
-    ...fields.livesIn,
-    ...fields.verifiedIn
-  ]));
+  warnings.push(...unresolvableRefWarnings(platformDir, [fields.statement, fields.why]));
   const newId = await nextRequirementId(platformDir, targetKey);
   const sourceCurrent = source.domain.specVersion ?? 1;
   req.status = "superseded";
@@ -8186,7 +9385,7 @@ async function move(input, freshTags) {
   }
   await validateAndWrite(target.specPath, target.domain, target.relFile);
   await validateAndWrite(source.specPath, source.domain, source.relFile);
-  const retag = toReqTagRows(await freshTags(id));
+  const retagged = await applyRetag(platformDir, id, newId, freshTags);
   return {
     ok: true,
     oldId: id,
@@ -8195,7 +9394,7 @@ async function move(input, freshTags) {
     toFile: target.relFile,
     sourceSpecVersion,
     targetSpecVersion,
-    retag,
+    retagged,
     warnings
   };
 }
@@ -8203,11 +9402,12 @@ var init_move = __esm(() => {
   init_src();
   init_domains();
   init_grammar2();
+  init_statementRules3();
   init_domainJson();
   init__envelope();
   init__result();
+  init__retag();
   init_mint();
-  init_reads2();
 });
 
 // src/commands/move.ts
@@ -8216,18 +9416,12 @@ __export(exports_move, {
   moveCommand: () => moveCommand
 });
 import { defineCommand as defineCommand17 } from "citty";
-function inputFromArgs2(args, rawArgs, platformDir, id, targetKey) {
+function inputFromArgs2(args, platformDir, id, targetKey) {
   const input = { platformDir, id, targetKey, noBump: Boolean(args.noBump) };
   if (typeof args.text === "string")
     input.statement = args.text;
   if (typeof args.why === "string")
     input.why = args.why;
-  const livesIn = listFlag(rawArgs, "lives", args.lives);
-  if (livesIn !== undefined)
-    input.livesIn = livesIn;
-  const verifiedIn = listFlag(rawArgs, "tests", args.tests);
-  if (verifiedIn !== undefined)
-    input.verifiedIn = verifiedIn;
   return input;
 }
 var moveArgs, moveCommand;
@@ -8259,30 +9453,22 @@ var init_move2 = __esm(() => {
       type: "string",
       description: "Rewrite the successor's Why (default: copied from the source)"
     },
-    lives: {
-      type: "string",
-      description: "Rewrite the successor's Lives in: repeat or comma-separate; empty clears (default: copied from the source)"
-    },
-    tests: {
-      type: "string",
-      description: "Rewrite the successor's Verified in (verifiedIn): repeat or comma-separate; empty clears (default: copied from the source)"
-    },
     noBump: {
       type: "boolean",
       description: "Do not bump either envelope's specVersion"
     },
     json: {
       type: "boolean",
-      description: "Emit { old_id, new_id, from_file, to_file, source_spec_version, target_spec_version, retag } as JSON"
+      description: "Emit { old_id, new_id, from_file, to_file, source_spec_version, target_spec_version, retagged } as JSON"
     }
   };
   moveCommand = defineCommand17({
     meta: {
       name: "move",
-      description: "Move a requirement to another domain: mint the successor in <NEW-DOMAIN> carrying the source's fields, mark the source superseded, bump both specVersions, and emit the retag worklist."
+      description: "Move a requirement to another domain: mint the successor in <NEW-DOMAIN> carrying the source's fields, mark the source superseded, bump both specVersions, and retag every site of it to the successor."
     },
     args: moveArgs,
-    async run({ args, rawArgs }) {
+    async run({ args }) {
       const id = args.id;
       const rawTargetKey = args.newDomain;
       const platformDir = resolvePlatformDir(args);
@@ -8300,11 +9486,11 @@ var init_move2 = __esm(() => {
       } catch (e) {
         handleNotAPlatform(e);
       }
-      const result = await move(inputFromArgs2(args, rawArgs, platformDir, id, targetKey), cliFreshTags(platformDir));
+      const result = await move(inputFromArgs2(args, platformDir, id, targetKey), cliFreshTags(platformDir));
       if (!result.ok)
         exitOnFailure("spec move", result);
       printWarnings("spec move", result.warnings);
-      const { newId, fromFile, toFile, sourceSpecVersion, targetSpecVersion, retag } = result;
+      const { newId, fromFile, toFile, sourceSpecVersion, targetSpecVersion, retagged } = result;
       const sourceKey = id.slice(0, id.indexOf("-"));
       if (args.json) {
         console.log(JSON.stringify({
@@ -8314,21 +9500,18 @@ var init_move2 = __esm(() => {
           to_file: toFile,
           source_spec_version: sourceSpecVersion,
           target_spec_version: targetSpecVersion,
-          retag
+          retagged
         }));
       } else {
         console.log(`moved ${id} \u2192 ${newId} (${sourceKey} \u2192 ${targetKey})`);
         if (sourceSpecVersion !== null || targetSpecVersion !== null) {
           console.log(`specVersion: ${sourceKey}\u2192${sourceSpecVersion}, ${targetKey}\u2192${targetSpecVersion}`);
         }
-        if (retag.length > 0) {
-          console.log(`retag ${retag.length} site(s) from ${id} to ${newId}:`);
-          console.log(renderReqTags(retag, "text"));
+        if (retagged.length > 0) {
+          console.log(`retagged ${retagged.length} site(s) from ${id} to ${newId}:`);
+          console.log(renderReqTags(retagged, "text"));
         }
       }
-      if (retag.length > 0) {
-        console.error(`note: spec check will report SUPERSEDED_REFERENCED at each remaining ${id} tag until the sites are retagged to ${newId}`);
-      }
     }
   });
 });
@@ -8357,7 +9540,7 @@ function gateRejection(platformDir, relFile, req, fields) {
   const tag = releaseHolding(platformDir, relFile, id);
   if (tag === null)
     return null;
-  return fail("conflict", `${id} is released in ${tag} \u2014 its promise is immutable. ` + `Run \`spec supersede ${id}\` to change the statement or why; ` + "pass only --lives, --tests, or --relates to amend its metadata in place.");
+  return fail("conflict", `${id} is released in ${tag} \u2014 its promise is immutable. ` + `Run \`spec supersede ${id}\` to change the statement or why; ` + "pass only --relates or --issue to amend its metadata in place.");
 }
 function applyFields(req, fields) {
   const fieldsChanged = [];
@@ -8372,16 +9555,6 @@ function applyFields(req, fields) {
     fieldsChanged.push("why");
     refValues.push(fields.why ?? "");
   }
-  if (fields.livesIn !== undefined) {
-    req.livesIn = fields.livesIn;
-    fieldsChanged.push("lives");
-    refValues.push(...fields.livesIn);
-  }
-  if (fields.verifiedIn !== undefined) {
-    req.verifiedIn = fields.verifiedIn;
-    fieldsChanged.push("tests");
-    refValues.push(...fields.verifiedIn);
-  }
   if (fields.relates !== undefined) {
     req.relates = splitList(fields.relates);
     fieldsChanged.push("relates");
@@ -8419,6 +9592,10 @@ async function amend(input) {
       }
       warnings.push({ kind: "grammar", text: grammarWarningText("", verdict).slice(2) });
     }
+    const rules = statementRulesVerdict(platformDir, key, fields.statement);
+    if (rules.refusal !== null)
+      return fail("usage", rules.refusal);
+    warnings.push(...rules.warnings);
   }
   const { fieldsChanged, refValues } = applyFields(req, fields);
   warnings.push(...unresolvableRefWarnings(platformDir, refValues));
@@ -8437,6 +9614,7 @@ var PROMISE_FIELDS;
 var init_amend = __esm(() => {
   init_src();
   init_grammar2();
+  init_statementRules3();
   init__envelope();
   init__result();
   init_mint();
@@ -8451,9 +9629,9 @@ __export(exports_amend, {
 import { defineCommand as defineCommand18 } from "citty";
 function assertAmendFlags(args) {
   const hasIssue = args.issue !== undefined && args.issue.trim() !== "";
-  const hasField = args.text !== undefined || args.why !== undefined || args.lives !== undefined || args.tests !== undefined || args.relates !== undefined || args.term !== undefined || args.aliases !== undefined;
+  const hasField = args.text !== undefined || args.why !== undefined || args.relates !== undefined || args.term !== undefined || args.aliases !== undefined;
   if (!hasField && !hasIssue) {
-    console.error("spec amend: nothing to amend \u2014 pass at least one of --text / --why / --lives / --tests / --relates / --term / --aliases");
+    console.error("spec amend: nothing to amend \u2014 pass at least one of --text / --why / --relates / --term / --aliases");
     process.exit(EXIT.USAGE);
   }
   if (args.text !== undefined && args.text.trim() === "") {
@@ -8477,12 +9655,6 @@ function fieldsFromArgs(args, rawArgs) {
     const v = args.why.trim();
     fields.why = v === "" ? null : v;
   }
-  const livesIn = listFlag(rawArgs, "lives", args.lives);
-  if (livesIn !== undefined)
-    fields.livesIn = livesIn;
-  const verifiedIn = listFlag(rawArgs, "tests", args.tests);
-  if (verifiedIn !== undefined)
-    fields.verifiedIn = verifiedIn;
   const relates = listFlag(rawArgs, "relates", args.relates);
   if (relates !== undefined)
     fields.relates = relates;
@@ -8511,8 +9683,6 @@ var init_amend2 = __esm(() => {
     platformDir: platformDirArg,
     text: { type: "string", description: "New Requirement (statement) field value" },
     why: { type: "string", description: "New Why it matters field value" },
-    lives: livesArg,
-    tests: testsArg,
     relates: relatesArg,
     issue: {
       type: "string",
@@ -8528,7 +9698,7 @@ var init_amend2 = __esm(() => {
   amendCommand = defineCommand18({
     meta: {
       name: "amend",
-      description: "Revise a requirement's fields in place (same id, no version bump). A released requirement's statement and why are superseded instead; --lives, --tests, and --relates still amend."
+      description: "Revise a requirement's fields in place (same id, no version bump). A released requirement's statement and why are superseded instead; --relates and --issue still amend."
     },
     args: amendArgs,
     async run({ args, rawArgs }) {
@@ -8568,6 +9738,9 @@ async function accept(input) {
   if (req.status.toLowerCase() !== "draft") {
     return fail("conflict", `${id} is ${displayStatus(req.status)} \u2014 only a Draft entry accepts`);
   }
+  const rules = statementRulesVerdict(platformDir, located.key, req.statement);
+  if (rules.refusal !== null)
+    return fail("usage", rules.refusal);
   req.status = "active";
   domain2.updated = localToday();
   const res = await validateAndWrite(specPath, domain2, relFile);
@@ -8577,10 +9750,11 @@ async function accept(input) {
       diagnostics: res.diagnostics
     });
   }
-  return { ok: true, id, file: relFile };
+  return { ok: true, id, file: relFile, warnings: rules.warnings };
 }
 var init_accept = __esm(() => {
   init_src();
+  init_statementRules3();
   init__envelope();
   init__result();
 });
@@ -8629,6 +9803,7 @@ var init_accept2 = __esm(() => {
       const result = await accept({ platformDir, id });
       if (!result.ok)
         exitOnFailure("spec accept", result);
+      printWarnings("spec accept", result.warnings);
       if (args.json) {
         console.log(JSON.stringify({ id, file: result.file }));
         return;
@@ -8638,6 +9813,158 @@ var init_accept2 = __esm(() => {
   });
 });
 
+// src/operations/lint.ts
+import { existsSync as existsSync14 } from "fs";
+async function lint2(input) {
+  const { platformDir, target } = input;
+  const config2 = readCheckConfig(platformDir);
+  if (!config2.ok)
+    return fail("usage", config2.detail);
+  const statuses = new Set(input.all ? ["active", "draft"] : ["active"]);
+  let keys;
+  let id;
+  if (target !== undefined && ID_RE.test(target)) {
+    const located = await locateEntry(platformDir, target);
+    if (!located.ok)
+      return located;
+    keys = [located.key];
+    id = target;
+  } else if (target !== undefined && KEY_RE.test(target)) {
+    const { abs, rel } = specPaths(platformDir, target);
+    if (!existsSync14(abs))
+      return fail("not_found", `no domain ${target} (expected ${rel})`);
+    keys = [target];
+  } else if (target !== undefined) {
+    return fail("usage", `${target} is neither a domain key nor a requirement id`);
+  }
+  const findings = await statementRuleRows(platformDir, config2.config.statementRules, {
+    keys,
+    id,
+    statuses
+  });
+  return { ok: true, findings };
+}
+var init_lint = __esm(() => {
+  init_src();
+  init_severity();
+  init_statementRules2();
+  init_constants();
+  init__envelope();
+  init__result();
+});
+
+// src/commands/lint.ts
+var exports_lint = {};
+__export(exports_lint, {
+  lintCommand: () => lintCommand
+});
+import { existsSync as existsSync15 } from "fs";
+import { join as join17, resolve as resolve13 } from "path";
+import { defineCommand as defineCommand20 } from "citty";
+function splitPositionals(args) {
+  const { target, platformDir } = args;
+  if (target !== undefined && platformDir === undefined && existsSync15(join17(resolve13(target), CANONICAL_SPECS_DIR))) {
+    return { target: undefined, platformDir: resolve13(target) };
+  }
+  return { target, platformDir: resolvePlatformDir({ platformDir }) };
+}
+var lintCommand;
+var init_lint2 = __esm(() => {
+  init_src();
+  init_constants();
+  init_discover();
+  init_lint();
+  init_stdout();
+  init__args();
+  init__shared();
+  lintCommand = defineCommand20({
+    meta: {
+      name: "lint",
+      description: "Print every statement-rule finding for the platform, one domain (KEY), or one requirement (KEY-NNN); exit 1 on any"
+    },
+    args: {
+      target: {
+        type: "positional",
+        required: false,
+        description: "Domain key or requirement id (default: the whole platform)"
+      },
+      platformDir: platformDirArg,
+      all: { type: "boolean", description: "Judge Draft requirements as well as Active ones" },
+      json: jsonArg
+    },
+    async run({ args }) {
+      const { target, platformDir } = splitPositionals(args);
+      try {
+        assertSpecPlatform(platformDir);
+      } catch (e) {
+        handleNotAPlatform(e);
+      }
+      const result = await lint2({ platformDir, target, all: !!args.all });
+      if (!result.ok)
+        exitOnFailure("spec lint", result);
+      if (args.json) {
+        console.log(JSON.stringify(result.findings.map(({ req_id, rule, detail, reason, source_file, line }) => ({
+          req_id,
+          rule,
+          detail,
+          reason,
+          source_file,
+          line
+        }))));
+      } else {
+        for (const f of result.findings)
+          console.log(`${f.req_id} ${formatStatementFinding(f)}`);
+        if (result.findings.length > 0)
+          console.error(RULE_ZERO);
+      }
+      await exit(result.findings.length > 0 ? EXIT.FAILURE : EXIT.OK);
+    }
+  });
+});
+
+// src/commands/migrate.ts
+var exports_migrate = {};
+__export(exports_migrate, {
+  migrateCommand: () => migrateCommand
+});
+import { defineCommand as defineCommand21 } from "citty";
+var migrateCommand;
+var init_migrate2 = __esm(() => {
+  init_discover();
+  init_migrate();
+  init__args();
+  init__shared();
+  migrateCommand = defineCommand21({
+    meta: {
+      name: "migrate",
+      description: "Remove the retired livesIn and verifiedIn fields from every SPEC.json, rewriting only the files that carry one"
+    },
+    args: {
+      platformDir: platformDirArg,
+      json: jsonArg
+    },
+    async run({ args }) {
+      const platformDir = resolvePlatformDir(args);
+      try {
+        assertSpecPlatform(platformDir);
+      } catch (e) {
+        handleNotAPlatform(e);
+      }
+      const result = await migrate(platformDir);
+      if (!result.ok)
+        exitOnFailure("spec migrate", result);
+      if (args.json) {
+        console.log(JSON.stringify({ files: result.files }));
+        return;
+      }
+      if (result.files.length === 0)
+        console.error("spec migrate: nothing to migrate");
+      for (const f of result.files)
+        console.log(`migrated ${f}`);
+    }
+  });
+});
+
 // src/server/authorPrompt.ts
 function renderAuthorPrompt(opts) {
   const charterBlock = opts.charter ? `
@@ -8647,6 +9974,8 @@ Domain charter (scope): ${opts.charter}
 Target domain: ${opts.domain} (no charter/scope recorded \u2014 check placement carefully)
 ` : "\nNo target domain given \u2014 determine placement from `spec domain list`.\n";
   return [
+    RULE_ZERO,
+    "",
     "You are authoring Spec Engine requirements from a brief. Follow this playbook exactly.",
     charterBlock,
     "Brief:",
@@ -8656,14 +9985,17 @@ Target domain: ${opts.domain} (no charter/scope recorded \u2014 check placement
     "1. One requirement per behavior \u2014 never one per ticket; a brief fans out into several.",
     "2. Placement: the domain whose promise the requirement protects (see the charter above); run `spec query <text>` first \u2014 if a close requirement exists, amend or relate it instead of minting.",
     '3. Draft each statement in one of the five EARS shapes ("shall" separates who acts from the observable result): `The <system> shall <result>` / `When <trigger>, the <system> shall <result>` / `While <state>, \u2026` / `If <failure>, then \u2026` / `Where <feature>, \u2026`. Example: "When an unknown id is passed, spec resolve shall print [] and exit 0."',
-    "4. Self-check: the statement makes sense read alone; it describes what the system does, not how the code does it; no expiration dates ('currently', removed things); the why names what breaks if the promise stops holding \u2014 never a restatement.",
+    "4. Self-check: the statement is one sentence of at most 280 characters that names no repository file or folder, test mechanics, CI or tooling layout, history, project jargon, or the tool in use (spec req refuses it otherwise; `spec lint` lists the findings); it makes sense read alone; it describes what the system does, not how the code does it; no expiration dates ('currently', removed things); the why names what breaks if the promise stops holding \u2014 never a restatement.",
     "5. Tie each draft to its source: quote the exact phrase of the brief it derives from; label anything you inferred as inferred.",
     "6. Present the full batch (statement, why, placement, source quote) for approval BEFORE writing.",
-    '7. Mint each approved requirement: `spec req <domain> --text "\u2026" --why "\u2026" --lives "\u2026"`.',
+    '7. Mint each approved requirement: `spec req <domain> --text "\u2026" --why "\u2026"`.',
     "8. The originating ticket is provenance only \u2014 never a requirement id, never a code tag."
   ].join(`
 `);
 }
+var init_authorPrompt = __esm(() => {
+  init_src();
+});
 
 // src/server/mcp.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -8680,10 +10012,6 @@ function amendFieldsOf(args) {
     fields.statement = args.text;
   if (args.why !== undefined)
     fields.why = args.why || null;
-  if (args.lives !== undefined)
-    fields.livesIn = args.lives;
-  if (args.verified_in !== undefined)
-    fields.verifiedIn = args.verified_in;
   if (args.relates !== undefined)
     fields.relates = args.relates;
   if (args.issue)
@@ -8713,7 +10041,7 @@ function buildMcpServer(platformDir) {
   }, async ({ files }) => fresh((s) => jsonResult(resolveFiles(s, files).rows)));
   server.registerTool("spec_req_tags", {
     title: "Requirement \u2192 tag sites (reverse query)",
-    description: "Every code/test/doc site tagging the given requirement, across all repos \u2014 impact analysis and retag worklists.",
+    description: "Every code/test/doc site tagging the given requirement, across all repos \u2014 impact analysis.",
     inputSchema: { req_id: z4.string().describe("Requirement id (KEY-NNN)") }
   }, async ({ req_id }) => {
     if (!ID_RE.test(req_id)) {
@@ -8754,15 +10082,15 @@ function buildMcpServer(platformDir) {
   });
   server.registerTool("spec_get", {
     title: "One requirement's full record",
-    description: "The full record for one requirement id: status, key, seq, statement, why, versions, and source location. An unknown id returns [] (the `spec get --json` shape).",
+    description: "The full record for one requirement id: status, key, seq, statement, why, versions, source location, and the implemented_in and verified_in tag sites. An unknown id returns [] (the `spec get --json` shape).",
     inputSchema: { req_id: z4.string().describe("Requirement id (KEY-NNN)") }
   }, async ({ req_id }) => {
     if (!ID_RE.test(req_id)) {
       return errorResult(`req_id must be a requirement id (KEY-NNN); got ${req_id}`);
     }
     return fresh((s) => {
-      const { row: row2 } = getRecord(s, req_id);
-      return jsonResult(row2 ?? []);
+      const { row } = getRecord(s, req_id);
+      return jsonResult(row ?? []);
     });
   });
   server.registerTool("spec_list", {
@@ -8787,17 +10115,15 @@ function buildMcpServer(platformDir) {
   });
   server.registerTool("spec_supersede", {
     title: "Supersede a shipped requirement",
-    description: "Flip an Active requirement to superseded, mint its successor in the same domain, and return the retag worklist (the tag sites spec check reports as SUPERSEDED_REFERENCED until retagged). The same JSON as `spec supersede --json`.",
+    description: "Flip an Active requirement to superseded, mint its successor in the same domain, rewrite every tag of the predecessor to the successor, and return the rewritten sites. The same JSON as `spec supersede --json`.",
     inputSchema: {
       req_id: z4.string().describe("The Active requirement id to supersede (KEY-NNN)"),
       statement: z4.string().min(1).describe("The successor's statement"),
       why: z4.string().optional().describe("Successor's why (default: copied from the predecessor)"),
-      lives_in: z4.array(z4.string()).optional().describe("Successor's livesIn paths (default: copied from the predecessor)"),
-      verified_in: z4.array(z4.string()).optional().describe("Successor's verifiedIn paths (default: copied from the predecessor)"),
       relates: z4.array(z4.string()).optional().describe("Successor's related ids, each comma-split; an empty list clears (default: copied from the predecessor)"),
       issue: z4.string().optional().describe("Ticket recorded as supersedes-via on the predecessor and created on the successor")
     }
-  }, async ({ req_id, statement, why, lives_in, verified_in, relates, issue }) => {
+  }, async ({ req_id, statement, why, relates, issue }) => {
     if (!ID_RE.test(req_id)) {
       return errorResult(`req_id must be a requirement id (KEY-NNN); got ${req_id}`);
     }
@@ -8806,8 +10132,6 @@ function buildMcpServer(platformDir) {
       id: req_id,
       statement,
       why,
-      livesIn: lives_in,
-      verifiedIn: verified_in,
       relates,
       issue
     }, coldFreshTags(platformDir));
@@ -8820,12 +10144,12 @@ function buildMcpServer(platformDir) {
       new_id: r.newId,
       file: r.file,
       spec_version: r.specVersion,
-      retag: r.retag
+      retagged: r.retagged
     });
   });
   server.registerTool("spec_deprecate", {
     title: "Deprecate a requirement",
-    description: "Mark an Active or Draft requirement deprecated with a recorded reason and return the code tags still bound to it (each a DEPRECATED_REFERENCED error in spec check until removed). The same JSON as `spec deprecate --json`.",
+    description: "Mark an Active or Draft requirement deprecated with a recorded reason, remove every tag of it from the code, and return the removed sites. The same JSON as `spec deprecate --json`.",
     inputSchema: {
       req_id: z4.string().describe("The requirement id to deprecate (KEY-NNN)"),
       reason: z4.string().min(1).describe("Why the requirement ended; the durable record")
@@ -8838,7 +10162,7 @@ function buildMcpServer(platformDir) {
     if (trimmed === "")
       return errorResult("reason must be non-empty");
     const r = await deprecate({ platformDir, id: req_id, reason: trimmed }, coldFreshTags(platformDir));
-    return r.ok ? jsonResult({ id: r.id, file: r.file, reason: r.reason, sites: r.sites }) : errorResult(r.detail);
+    return r.ok ? jsonResult({ id: r.id, file: r.file, reason: r.reason, removed: r.removed }) : errorResult(r.detail);
   });
   server.registerTool("spec_accept", {
     title: "Accept a draft requirement",
@@ -8851,7 +10175,11 @@ function buildMcpServer(platformDir) {
       return errorResult(`req_id must be a requirement id (KEY-NNN); got ${req_id}`);
     }
     const r = await accept({ platformDir, id: req_id });
-    return r.ok ? jsonResult({ id: r.id, file: r.file }) : errorResult(r.detail);
+    if (!r.ok)
+      return errorResult(r.detail);
+    for (const w of r.warnings)
+      console.error(`spec_accept: ${w.text}`);
+    return jsonResult({ id: r.id, file: r.file });
   });
   server.registerTool("spec_req", {
     title: "Author a requirement",
@@ -8860,13 +10188,11 @@ function buildMcpServer(platformDir) {
       domain: z4.string().min(1).describe("Domain key or unique case-insensitive prefix"),
       text: z4.string().trim().min(1).describe("The requirement statement"),
       why: z4.string().trim().default("").describe("What breaks without it"),
-      lives: z4.array(z4.string()).default([]).describe("livesIn paths"),
-      verified_in: z4.array(z4.string()).default([]).describe("verifiedIn test paths"),
       relates: z4.array(z4.string()).default([]).describe("Related requirement ids, each comma-split"),
       issue: z4.string().trim().optional().describe("Originating ticket, recorded as created"),
       draft: z4.boolean().default(false).describe("Author as Draft instead of Active")
     }
-  }, async ({ domain: domain2, text, why, lives, verified_in, relates, issue, draft }) => {
+  }, async ({ domain: domain2, text, why, relates, issue, draft }) => {
     const allocated = await nextId(platformDir, domain2);
     if (!allocated.ok)
       return errorResult(allocated.detail);
@@ -8875,8 +10201,6 @@ function buildMcpServer(platformDir) {
       key: allocated.key,
       statement: text,
       why,
-      livesIn: lives,
-      verifiedIn: verified_in,
       relates,
       issue: issue || undefined,
       status: draft ? "draft" : "active"
@@ -8894,17 +10218,15 @@ function buildMcpServer(platformDir) {
       id: z4.string().describe("The requirement id to amend (KEY-NNN)"),
       text: z4.string().trim().min(1).optional().describe("New statement"),
       why: z4.string().trim().optional().describe("New why; empty clears it"),
-      lives: z4.array(z4.string()).optional().describe("Replacement livesIn list; empty clears"),
-      verified_in: z4.array(z4.string()).optional().describe("Replacement verifiedIn list; empty clears"),
       relates: z4.array(z4.string()).optional().describe("Replacement related ids, each comma-split; empty clears"),
       issue: z4.string().trim().optional().describe("Ticket recorded as amends-via")
     }
-  }, async ({ id, text, why, lives, verified_in, relates, issue }) => {
+  }, async ({ id, text, why, relates, issue }) => {
     if (!ID_RE.test(id))
       return errorResult(`id must be a requirement id (KEY-NNN); got ${id}`);
-    const fields = amendFieldsOf({ text, why, lives, verified_in, relates, issue });
+    const fields = amendFieldsOf({ text, why, relates, issue });
     if (Object.keys(fields).length === 0) {
-      return errorResult("nothing to amend \u2014 pass at least one of text, why, lives, verified_in, relates");
+      return errorResult("nothing to amend \u2014 pass at least one of text, why, relates, issue");
     }
     const r = await amend({ platformDir, id, fields });
     if (!r.ok)
@@ -8915,16 +10237,14 @@ function buildMcpServer(platformDir) {
   });
   server.registerTool("spec_move", {
     title: "Move a requirement to another domain",
-    description: "Mint the successor in newDomain carrying the source's fields, mark the source superseded, and return the retag worklist. The same JSON as `spec move --json`.",
+    description: "Mint the successor in newDomain carrying the source's fields, mark the source superseded, rewrite every tag of the source to the successor, and return the rewritten sites. The same JSON as `spec move --json`.",
     inputSchema: {
       id: z4.string().describe("The Active requirement id to move (KEY-NNN)"),
       newDomain: z4.string().min(1).describe("The existing target domain key"),
       text: z4.string().optional().describe("Successor statement (default: copied)"),
-      why: z4.string().optional().describe("Successor why (default: copied)"),
-      lives: z4.array(z4.string()).optional().describe("Successor livesIn list; empty clears (default: copied)"),
-      verified_in: z4.array(z4.string()).optional().describe("Successor verifiedIn list; empty clears (default: copied)")
+      why: z4.string().optional().describe("Successor why (default: copied)")
     }
-  }, async ({ id, newDomain: newDomain2, text, why, lives, verified_in }) => {
+  }, async ({ id, newDomain: newDomain2, text, why }) => {
     if (!ID_RE.test(id))
       return errorResult(`id must be a requirement id (KEY-NNN); got ${id}`);
     const targetKey = normalizeDomainKey(newDomain2);
@@ -8935,9 +10255,7 @@ function buildMcpServer(platformDir) {
       id,
       targetKey,
       statement: text,
-      why,
-      livesIn: lives,
-      verifiedIn: verified_in
+      why
     }, coldFreshTags(platformDir));
     if (!r.ok)
       return errorResult(r.detail);
@@ -8950,7 +10268,7 @@ function buildMcpServer(platformDir) {
       to_file: r.toFile,
       source_spec_version: r.sourceSpecVersion,
       target_spec_version: r.targetSpecVersion,
-      retag: r.retag
+      retagged: r.retagged
     });
   });
   server.registerPrompt("author_requirements", {
@@ -8999,6 +10317,7 @@ var init_mcp = __esm(() => {
   init_records();
   init_supersede();
   init_grammar3();
+  init_authorPrompt();
 });
 
 // src/commands/mcp.ts
@@ -9007,14 +10326,14 @@ __export(exports_mcp, {
   mcpCommand: () => mcpCommand
 });
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { defineCommand as defineCommand20 } from "citty";
+import { defineCommand as defineCommand22 } from "citty";
 var mcpCommand;
 var init_mcp2 = __esm(() => {
   init_discover();
   init_mcp();
   init__args();
   init__shared();
-  mcpCommand = defineCommand20({
+  mcpCommand = defineCommand22({
     meta: {
       name: "mcp",
       description: "Serve Spec Engine as an MCP (Model Context Protocol) server over stdio \u2014 agent-native query/resolve/check/report tools."
@@ -9042,8 +10361,8 @@ __export(exports_resolve, {
   resolveCommand: () => resolveCommand
 });
 import { statSync as statSync5 } from "fs";
-import { join as join14, relative as relative3, resolve as resolve13, sep as sep4 } from "path";
-import { defineCommand as defineCommand21 } from "citty";
+import { join as join18, relative as relative4, resolve as resolve14, sep as sep4 } from "path";
+import { defineCommand as defineCommand23 } from "citty";
 function classifyArg(a) {
   if (a.startsWith("--")) {
     const eq = a.indexOf("=");
@@ -9078,10 +10397,10 @@ function splitFilesAndPlatformDir(positionals, fallbackPlatformDir) {
   let lastIsPlatformDir = false;
   let lastIsDirWithoutSpecEngine = false;
   try {
-    const resolved = resolve13(last);
+    const resolved = resolve14(last);
     if (statSync5(resolved).isDirectory()) {
       try {
-        if (statSync5(join14(resolved, "spec-engine")).isDirectory()) {
+        if (statSync5(join18(resolved, "spec-engine")).isDirectory()) {
           lastIsPlatformDir = true;
         } else {
           lastIsDirWithoutSpecEngine = true;
@@ -9168,7 +10487,7 @@ async function dispatchReverseQuery(reqArg, resolved, args) {
   }
   await runReverseQuery({
     reqId: reqArg,
-    platformDir: resolve13(lone ?? process.cwd()),
+    platformDir: resolve14(lone ?? process.cwd()),
     outArg: args.out,
     json: Boolean(args.json),
     fresh: Boolean(args.fresh),
@@ -9178,7 +10497,7 @@ async function dispatchReverseQuery(reqArg, resolved, args) {
 function normalizeFileInputs(files, platformDir) {
   const normalized = [];
   for (const input of files) {
-    const rel = relative3(platformDir, resolve13(platformDir, input));
+    const rel = relative4(platformDir, resolve14(platformDir, input));
     const segments = rel.split(sep4);
     if (rel === "" || rel === "." || segments[0] === "..") {
       console.error(`spec resolve: file path must be inside platformDir: ${input}`);
@@ -9229,7 +10548,7 @@ var init_resolve2 = __esm(() => {
       description: "Suppress interactive onboarding prompt for siblings missing spec-engine.member.json (defaults to NO_SPEC_CONFIG warning)"
     }
   };
-  resolveCommand = defineCommand21({
+  resolveCommand = defineCommand23({
     meta: {
       name: "resolve",
       description: "Return the requirements tagged in the given files. Accepts multiple positional file paths (e.g. `spec resolve api/src/renew.ts api/src/charge.ts`) and a comma-split fallback inside a single positional (`spec resolve a.ts,b.ts`). Paths may be platform-relative or absolute under the platform tree."
@@ -9253,7 +10572,7 @@ var init_resolve2 = __esm(() => {
         process.exit(EXIT.USAGE);
         return;
       }
-      const platformDir = resolve13(resolved.platformDir ?? process.cwd());
+      const platformDir = resolve14(resolved.platformDir ?? process.cwd());
       const outArg2 = args.out;
       const dbPath = resolveDbPath(platformDir, outArg2);
       if (outArg2)
@@ -9392,10 +10711,10 @@ var exports_gate = {};
 __export(exports_gate, {
   gateCommand: () => gateCommand
 });
-import { existsSync as existsSync13 } from "fs";
-import { join as join15 } from "path";
-import { defineCommand as defineCommand22 } from "citty";
-function isEpipe(e) {
+import { existsSync as existsSync16 } from "fs";
+import { join as join19 } from "path";
+import { defineCommand as defineCommand24 } from "citty";
+function isEpipe2(e) {
   if (e === null || typeof e !== "object" || !("code" in e))
     return false;
   const code = e.code;
@@ -9405,7 +10724,7 @@ function writeStdoutTolerant(line) {
   try {
     console.log(line);
   } catch (writeErr) {
-    if (!isEpipe(writeErr))
+    if (!isEpipe2(writeErr))
       throw writeErr;
   }
 }
@@ -9417,7 +10736,7 @@ function resolveGateArgs(args) {
     process.exit(EXIT.USAGE);
   }
   const platformDir = resolvePlatformDir(args);
-  if (!existsSync13(join15(platformDir, "spec-engine"))) {
+  if (!existsSync16(join19(platformDir, "spec-engine"))) {
     console.error(formatNotASpecPlatform(platformDir));
     process.exit(EXIT.USAGE);
   }
@@ -9430,6 +10749,7 @@ var init_gate2 = __esm(() => {
   init_prompt();
   init__index();
   init_gate();
+  init_stdout();
   init__args();
   init__shared();
   gateArgs = {
@@ -9457,7 +10777,7 @@ var init_gate2 = __esm(() => {
       description: "Suppress interactive onboarding prompt for siblings missing spec-engine.member.json (defaults to NO_SPEC_CONFIG warning)"
     }
   };
-  gateCommand = defineCommand22({
+  gateCommand = defineCommand24({
     meta: {
       name: "gate",
       description: "Rung-3 approval primitive: passes iff <reqId> is Active and <repo>'s pinned spec_version covers its changed_at_version. Exits 0 PASS / 1 any gate failure / 2 crash or bad args."
@@ -9490,7 +10810,7 @@ var init_gate2 = __esm(() => {
             writeStdoutTolerant(`build_id: ${gated.buildId}`);
         }
       } catch (e) {
-        handleInvalidDomainFiles(e, Boolean(args.json));
+        await handleInvalidDomainFiles(e, Boolean(args.json));
         const msg = e instanceof Error ? e.message : String(e);
         console.error(`spec gate: crashed: ${msg}`);
         process.exit(EXIT.USAGE);
@@ -9500,7 +10820,7 @@ var init_gate2 = __esm(() => {
         process.exit(EXIT.USAGE);
         return;
       }
-      process.exit(gated.outcome.pass ? EXIT.OK : EXIT.FAILURE);
+      await exit(gated.outcome.pass ? EXIT.OK : EXIT.FAILURE);
     }
   });
 });
@@ -9581,14 +10901,15 @@ var exports_guard = {};
 __export(exports_guard, {
   guardCommand: () => guardCommand
 });
-import { defineCommand as defineCommand23 } from "citty";
+import { defineCommand as defineCommand25 } from "citty";
 var guardCommand;
 var init_guard2 = __esm(() => {
   init_constants();
   init_guard();
+  init_stdout();
   init__args();
   init__shared();
-  guardCommand = defineCommand23({
+  guardCommand = defineCommand25({
     meta: {
       name: "guard",
       description: "Loss detection: diff the requirement derivation at a git ref (default HEAD) against the working tree and block requirements about to be steamrolled."
@@ -9611,14 +10932,14 @@ var init_guard2 = __esm(() => {
       if (!gitRefResolves(platformDir, ref)) {
         console.error(`spec guard: NOT_A_GIT_REPO \u2014 ref '${ref}' does not resolve in ${platformDir} ` + "(not a git repo, a fresh repo with no commit, or an unfetched/misspelled ref); " + "skipping loss detection");
         console.log(jsonMode ? "[]" : `\u2713 spec guard: no requirements about to be lost (non-git context)`);
-        process.exit(EXIT.OK);
+        await exit(EXIT.OK);
       }
       let losses = [];
       await withReadStorage({ platformDir, dbPath: defaultIndexPath(platformDir), fresh: true, json: jsonMode }, async (storage2) => {
         losses = (await guard(storage2, platformDir, ref)).losses;
       });
       console.log(renderGuard(losses, jsonMode ? "json" : "text", ref));
-      process.exit(losses.length > 0 ? EXIT.FAILURE : EXIT.OK);
+      await exit(losses.length > 0 ? EXIT.FAILURE : EXIT.OK);
     }
   });
 });
@@ -11220,9 +12541,9 @@ function requirementStatusBadge(status) {
   const variant = status === "Active" ? "active" : status === "Superseded" ? "superseded" : status === "Draft" ? "draft" : "retired";
   return badge(variant, STATUS_LABEL[status]);
 }
-function propagationStateBadge(row2) {
+function propagationStateBadge(row) {
   let variant;
-  switch (row2.state) {
+  switch (row.state) {
     case "MIGRATED_VERIFIED":
       variant = "verified";
       break;
@@ -11235,7 +12556,7 @@ function propagationStateBadge(row2) {
     default:
       variant = "unbound";
   }
-  return badge(variant, row2.state);
+  return badge(variant, row.state);
 }
 function coverageGlyph(impl, verif) {
   const [variant, char, title] = impl && verif ? ["both", "\u2713", "src + test"] : impl ? ["impl", "S", "src only"] : verif ? ["test", "T", "test only"] : ["none", "", "none"];
@@ -11369,18 +12690,18 @@ import { html as html4, raw as raw3 } from "hono/html";
 function pivot(rows) {
   const repos = [...new Set(rows.map((r) => r.repo))].sort();
   const byDomain = new Map;
-  for (const row2 of rows) {
-    let dom = byDomain.get(row2.domain_key);
+  for (const row of rows) {
+    let dom = byDomain.get(row.domain_key);
     if (!dom) {
       dom = new Map;
-      byDomain.set(row2.domain_key, dom);
+      byDomain.set(row.domain_key, dom);
     }
-    let req = dom.get(row2.req_id);
+    let req = dom.get(row.req_id);
     if (!req) {
-      req = { id: row2.req_id, status: row2.req_status, cells: new Map };
-      dom.set(row2.req_id, req);
+      req = { id: row.req_id, status: row.req_status, cells: new Map };
+      dom.set(row.req_id, req);
     }
-    req.cells.set(row2.repo, { impl: row2.implemented, verif: row2.verified });
+    req.cells.set(row.repo, { impl: row.implemented, verif: row.verified });
   }
   const domains = [...byDomain.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([key, reqMap]) => ({
     key,
@@ -11627,14 +12948,6 @@ function mountEditor(app, bindHost = DEFAULT_BIND_HOST) {
             Why (optional)
             <textarea name="why" rows="2"></textarea>
           </label>
-          <label>
-            Lives in (optional, single path)
-            <input type="text" name="livesIn" placeholder="path/to/impl.ts" />
-          </label>
-          <label>
-            Verified in (optional, single path)
-            <input type="text" name="verifiedIn" placeholder="path/to/impl.test.ts" />
-          </label>
           <label>
             Relates to (optional, comma-separated ids)
             <input type="text" name="relates" placeholder="BILLING-001, BILLING-002" />
@@ -11672,8 +12985,6 @@ function mountEditor(app, bindHost = DEFAULT_BIND_HOST) {
     const form = await c.req.parseBody();
     const statement = field(form, "statement");
     const why = field(form, "why");
-    const livesIn = field(form, "livesIn");
-    const verifiedIn = field(form, "verifiedIn");
     const relates = field(form, "relates");
     const payload = {
       key: field(form, "key"),
@@ -11681,10 +12992,6 @@ function mountEditor(app, bindHost = DEFAULT_BIND_HOST) {
     };
     if (why.length > 0)
       payload.why = why;
-    if (livesIn.length > 0)
-      payload.livesIn = livesIn;
-    if (verifiedIn.length > 0)
-      payload.verifiedIn = verifiedIn;
     if (relates.length > 0)
       payload.relates = relates;
     const res = await app.request("/api/requirements", {
@@ -12001,15 +13308,15 @@ var init_relations2 = __esm(() => {
 import { html as html10, raw as raw9 } from "hono/html";
 function coverageRollups(coverage) {
   const cov = new Map;
-  for (const row2 of coverage) {
-    if (row2.req_status !== "Active")
+  for (const row of coverage) {
+    if (row.req_status !== "Active")
       continue;
-    const c = cov.get(row2.req_id) ?? { impl: 0, verif: 0 };
-    if (row2.implemented)
+    const c = cov.get(row.req_id) ?? { impl: 0, verif: 0 };
+    if (row.implemented)
       c.impl += 1;
-    if (row2.verified)
+    if (row.verified)
       c.verif += 1;
-    cov.set(row2.req_id, c);
+    cov.set(row.req_id, c);
   }
   return cov;
 }
@@ -12253,6 +13560,9 @@ function mountRequirements(app) {
 </html>`);
     }
     const r = await res.json();
+    const sites = (list) => list.length === 0 ? "\u2014" : html10`<ul>
+            ${list.map((s) => html10`<li><code>${s.file}:${s.line}</code></li>`)}
+          </ul>`;
     const body = html10`
       ${navBar("requirements")}
       <div class="eyebrow">/ Requirement</div>
@@ -12272,6 +13582,8 @@ function mountRequirements(app) {
         <dt>line</dt><dd>${r.line}</dd>
         <dt>text</dt><dd>${r.text}</dd>
         <dt>why</dt><dd>${r.why ?? "\u2014"}</dd>
+        <dt>implemented_in</dt><dd>${sites(r.implemented_in)}</dd>
+        <dt>verified_in</dt><dd>${sites(r.verified_in)}</dd>
       </dl>
     `;
     return c.html(html10`<!doctype html>
@@ -12356,15 +13668,15 @@ function mountSetup(app) {
     const memberCount = members.length;
     const note = readingNote(mode, memberCount);
     const boundByRepo = new Map;
-    for (const row2 of cov) {
-      if (!row2.implemented)
+    for (const row of cov) {
+      if (!row.implemented)
         continue;
-      let set = boundByRepo.get(row2.repo);
+      let set = boundByRepo.get(row.repo);
       if (!set) {
         set = new Set;
-        boundByRepo.set(row2.repo, set);
+        boundByRepo.set(row.repo, set);
       }
-      set.add(row2.req_id);
+      set.add(row.req_id);
     }
     const body = html11`
       ${navBar("setup")}
@@ -12601,8 +13913,6 @@ function mintFieldsFromBody(body) {
   return {
     statement: typeof body.statement === "string" ? body.statement : "",
     why: typeof body.why === "string" ? body.why : "",
-    livesIn: toStringList(body.livesIn),
-    verifiedIn: toStringList(body.verifiedIn),
     relates: toStringList(body.relates),
     issue: typeof body.issue === "string" && body.issue.trim() !== "" ? body.issue.trim() : undefined,
     status: body.status === "draft" ? "draft" : "active"
@@ -12611,8 +13921,6 @@ function mintFieldsFromBody(body) {
 function successorFieldsFromBody(body) {
   return {
     why: typeof body.why === "string" ? body.why : undefined,
-    livesIn: "livesIn" in body ? toStringList(body.livesIn) : undefined,
-    verifiedIn: "verifiedIn" in body ? toStringList(body.verifiedIn) : undefined,
     relates: "relates" in body ? toStringList(body.relates) : undefined,
     issue: typeof body.issue === "string" && body.issue.trim() !== "" ? body.issue.trim() : undefined
   };
@@ -12623,10 +13931,6 @@ function amendFieldsFromBody(body) {
     fields.statement = body.statement;
   if ("why" in body)
     fields.why = typeof body.why === "string" ? body.why : null;
-  if ("livesIn" in body)
-    fields.livesIn = toStringList(body.livesIn);
-  if ("verifiedIn" in body)
-    fields.verifiedIn = toStringList(body.verifiedIn);
   if ("relates" in body)
     fields.relates = toStringList(body.relates);
   return Object.keys(fields).length === 0 ? null : fields;
@@ -12688,8 +13992,8 @@ function mountApi(app, storage2, platformDir = process.cwd(), bindHost = DEFAULT
   }));
   app.get("/api/requirements/:id", guarded((c) => {
     const id = c.req.param("id") ?? "";
-    const { row: row2 } = getRecord(storage2, id);
-    return row2 ? c.json(row2) : c.json({ error: "not found" }, 404);
+    const { row } = getRecord(storage2, id);
+    return row ? c.json(row) : c.json({ error: "not found" }, 404);
   }));
   app.post("/api/requirements", guarded(async function createRequirement(c) {
     if (!featureEnabled("editor")) {
@@ -12735,7 +14039,7 @@ function mountApi(app, storage2, platformDir = process.cwd(), bindHost = DEFAULT
     return withWriteLock(async () => {
       const fields = amendFieldsFromBody(body);
       if (fields === null) {
-        return c.json({ error: "nothing to amend \u2014 provide statement, why, livesIn, verifiedIn, or relates" }, 400);
+        return c.json({ error: "nothing to amend \u2014 provide statement, why, or relates" }, 400);
       }
       const r = await amend({ platformDir, id, fields });
       if (!r.ok)
@@ -12777,7 +14081,7 @@ function mountApi(app, storage2, platformDir = process.cwd(), bindHost = DEFAULT
         new_id: r.newId,
         file: r.file,
         spec_version: r.specVersion,
-        retag: r.retag
+        retagged: r.retagged
       }, 201);
     });
   }));
@@ -12807,9 +14111,7 @@ function mountApi(app, storage2, platformDir = process.cwd(), bindHost = DEFAULT
         id,
         targetKey,
         statement: typeof body.text === "string" ? body.text : undefined,
-        why: typeof body.why === "string" ? body.why : undefined,
-        livesIn: "lives" in body ? toStringList(body.lives) : undefined,
-        verifiedIn: "verifiedIn" in body ? toStringList(body.verifiedIn) : undefined
+        why: typeof body.why === "string" ? body.why : undefined
       }, async (reqId) => {
         await runIndex({ platformDir, storage: storage2 });
         return storage2.listTags({ req_id: reqId });
@@ -12824,7 +14126,7 @@ function mountApi(app, storage2, platformDir = process.cwd(), bindHost = DEFAULT
         to_file: r.toFile,
         source_spec_version: r.sourceSpecVersion,
         target_spec_version: r.targetSpecVersion,
-        retag: r.retag
+        retagged: r.retagged
       }, 201);
     });
   }));
@@ -12855,7 +14157,7 @@ function mountApi(app, storage2, platformDir = process.cwd(), bindHost = DEFAULT
       });
       if (!r.ok)
         return failureResponse(c, r);
-      return c.json({ ok: true, id: r.id, file: r.file, reason: r.reason, sites: r.sites }, 200);
+      return c.json({ ok: true, id: r.id, file: r.file, reason: r.reason, removed: r.removed }, 200);
     });
   }));
   app.post("/api/requirements/:id/accept", guarded(async function acceptRequirement(c) {
@@ -12901,12 +14203,12 @@ function mountApi(app, storage2, platformDir = process.cwd(), bindHost = DEFAULT
     if (!featureEnabled("relations")) {
       return c.json({ error: featureDisabledMessage("relations") }, 404);
     }
-    const format = c.req.query("format");
-    if (format !== undefined && format !== "mermaid") {
+    const format2 = c.req.query("format");
+    if (format2 !== undefined && format2 !== "mermaid") {
       return c.json({ error: 'format must be "mermaid" when provided' }, 400);
     }
     const rows = relations(storage2).rows;
-    if (format === "mermaid") {
+    if (format2 === "mermaid") {
       return c.text(renderRelations(rows, "mermaid"));
     }
     return c.json(sortRelations(rows));
@@ -13097,9 +14399,9 @@ __export(exports_serve, {
   resolveBind: () => resolveBind,
   composeServeApp: () => composeServeApp
 });
-import { existsSync as existsSync14, mkdirSync as mkdirSync6 } from "fs";
-import { dirname as dirname8 } from "path";
-import { defineCommand as defineCommand24 } from "citty";
+import { existsSync as existsSync17, mkdirSync as mkdirSync7 } from "fs";
+import { dirname as dirname10 } from "path";
+import { defineCommand as defineCommand26 } from "citty";
 import { Hono as Hono2 } from "hono";
 function composeServeApp(storage2, platformDir = process.cwd(), bindHost = DEFAULT_BIND_HOST) {
   const app = new Hono2;
@@ -13161,7 +14463,7 @@ async function runProbe() {
   }
   console.log("serve --probe OK");
   server.stop();
-  process.exit(EXIT.OK);
+  await exit(EXIT.OK);
 }
 var serveCommand;
 var init_serve = __esm(() => {
@@ -13173,10 +14475,11 @@ var init_serve = __esm(() => {
   init_prompt();
   init_api();
   init_lan();
+  init_stdout();
   init_sqlite();
   init__args();
   init__shared();
-  serveCommand = defineCommand24({
+  serveCommand = defineCommand26({
     meta: {
       name: "serve",
       description: "Run the local webapp. Binds 127.0.0.1 on --port, or one private --host address behind an access token. --probe is the asset-embedding smoke."
@@ -13248,8 +14551,8 @@ var init_serve = __esm(() => {
           noPrompt: args.noPrompt
         }
       });
-      mkdirSync6(dirname8(dbPath), { recursive: true });
-      const needsIndex = !existsSync14(dbPath);
+      mkdirSync7(dirname10(dbPath), { recursive: true });
+      const needsIndex = !existsSync17(dbPath);
       let storage2;
       try {
         storage2 = openStorage(dbPath);
@@ -13270,7 +14573,7 @@ var init_serve = __esm(() => {
         });
       } catch (err) {
         storage2.close();
-        handleInvalidDomainFiles(err, false);
+        await handleInvalidDomainFiles(err, false);
         handleStorageUnavailable(err, dbPath);
         console.error(`spec serve: failed to start on ${urlHost(host, port)}:`, err);
         process.exit(EXIT.FAILURE);
@@ -13297,13 +14600,13 @@ __export(exports_docs, {
   docsCommand: () => docsCommand,
   createDocsFetchHandler: () => createDocsFetchHandler
 });
-import { existsSync as existsSync15, statSync as statSync6 } from "fs";
-import { join as join16, normalize, sep as sep5 } from "path";
+import { existsSync as existsSync18, statSync as statSync6 } from "fs";
+import { join as join20, normalize, sep as sep5 } from "path";
 import { fileURLToPath } from "url";
-import { defineCommand as defineCommand25 } from "citty";
+import { defineCommand as defineCommand27 } from "citty";
 function resolveDocsRootFrom(candidates) {
   for (const candidate of candidates) {
-    if (existsSync15(join16(candidate, "index.html")))
+    if (existsSync18(join20(candidate, "index.html")))
       return candidate;
   }
   return null;
@@ -13327,17 +14630,17 @@ function createDocsFetchHandler(root) {
     if (pathname.includes("\x00")) {
       return new Response("Bad request", { status: 400 });
     }
-    const target = normalize(join16(normalRoot, pathname));
+    const target = normalize(join20(normalRoot, pathname));
     if (target !== normalRoot && !target.startsWith(rootPrefix)) {
       return new Response("Not found", { status: 404 });
     }
-    for (const candidate of [target, join16(target, "index.html"), `${target}.html`]) {
-      if (existsSync15(candidate) && statSync6(candidate).isFile()) {
+    for (const candidate of [target, join20(target, "index.html"), `${target}.html`]) {
+      if (existsSync18(candidate) && statSync6(candidate).isFile()) {
         return new Response(Bun.file(candidate));
       }
     }
-    const notFoundPage = join16(normalRoot, "404.html");
-    if (existsSync15(notFoundPage)) {
+    const notFoundPage = join20(normalRoot, "404.html");
+    if (existsSync18(notFoundPage)) {
       return new Response(Bun.file(notFoundPage), { status: 404 });
     }
     return new Response("Not found", { status: 404 });
@@ -13369,7 +14672,7 @@ async function runProbe2(root) {
   }
   console.log("docs --probe OK");
   server.stop();
-  process.exit(EXIT.OK);
+  await exit(EXIT.OK);
 }
 function exitNoDocsRoot() {
   console.error("spec docs: no built documentation found. From a checkout run `bun run build:site` " + "(writes packages/site/dist); the published npm package ships it at dist/docs.");
@@ -13378,7 +14681,8 @@ function exitNoDocsRoot() {
 var docsCommand;
 var init_docs2 = __esm(() => {
   init_constants();
-  docsCommand = defineCommand25({
+  init_stdout();
+  docsCommand = defineCommand27({
     meta: {
       name: "docs",
       description: "Serve the bundled documentation site offline. Binds 127.0.0.1 on --port (loopback only \u2014 no --host). --probe is the boot-and-fetch smoke."
@@ -13439,10 +14743,10 @@ __export(exports___smoke, {
   schemaSmokeCommand: () => schemaSmokeCommand,
   schemaMismatchSmokeCommand: () => schemaMismatchSmokeCommand
 });
-import { defineCommand as defineCommand26 } from "citty";
+import { defineCommand as defineCommand28 } from "citty";
 var schemaSmokeCommand, schemaMismatchSmokeCommand;
 var init___smoke = __esm(() => {
-  schemaSmokeCommand = defineCommand26({
+  schemaSmokeCommand = defineCommand28({
     meta: {
       name: "__schema-smoke",
       description: "(hidden CI) open a fresh DB, exec DDL, assert the schema shape",
@@ -13485,7 +14789,7 @@ var init___smoke = __esm(() => {
       console.log("__schema-smoke OK");
     }
   });
-  schemaMismatchSmokeCommand = defineCommand26({
+  schemaMismatchSmokeCommand = defineCommand28({
     meta: {
       name: "__schema-mismatch-smoke",
       description: "(hidden CI) corrupt _schema_version, re-open, assert silent rebuild",
@@ -13511,8 +14815,10 @@ var init___smoke = __esm(() => {
 
 // src/cli.ts
 init_package();
-import { defineCommand as defineCommand27, runMain, showUsage } from "citty";
-var main = defineCommand27({
+init_stdout();
+import { defineCommand as defineCommand29, runMain, showUsage } from "citty";
+routeStdout();
+var main = defineCommand29({
   meta: {
     name: "spec",
     version: package_default.version,
@@ -13538,6 +14844,8 @@ var main = defineCommand27({
     move: () => Promise.resolve().then(() => (init_move2(), exports_move)).then((m) => m.moveCommand),
     amend: () => Promise.resolve().then(() => (init_amend2(), exports_amend)).then((m) => m.amendCommand),
     accept: () => Promise.resolve().then(() => (init_accept2(), exports_accept)).then((m) => m.acceptCommand),
+    lint: () => Promise.resolve().then(() => (init_lint2(), exports_lint)).then((m) => m.lintCommand),
+    migrate: () => Promise.resolve().then(() => (init_migrate2(), exports_migrate)).then((m) => m.migrateCommand),
     mcp: () => Promise.resolve().then(() => (init_mcp2(), exports_mcp)).then((m) => m.mcpCommand),
     resolve: () => Promise.resolve().then(() => (init_resolve2(), exports_resolve)).then((m) => m.resolveCommand),
     gate: () => Promise.resolve().then(() => (init_gate2(), exports_gate)).then((m) => m.gateCommand),