@spec-engine/spec-engine 0.1.1 → 0.2.0

package/dist/impl.js

@@ -35,6 +35,10 @@ var init_diagnostics = __esm(() => {
     BAD_STATUS: "BAD_STATUS",
     DANGLING_TAG: "DANGLING_TAG",
     SUPERSEDED_REFERENCED: "SUPERSEDED_REFERENCED",
+    DEPRECATED_REFERENCED: "DEPRECATED_REFERENCED",
+    STATEMENT_GRAMMAR: "STATEMENT_GRAMMAR",
+    DRAFT_REFERENCED: "DRAFT_REFERENCED",
+    GLOSSARY_DRIFT: "GLOSSARY_DRIFT",
     ORPHAN_REQ: "ORPHAN_REQ",
     UNVERIFIED_REQ: "UNVERIFIED_REQ",
     DRIFT: "DRIFT",
@@ -103,6 +107,8 @@ function orderDomain(d) {
     specVersion: d.specVersion,
     updated: d.updated,
     scope: d.scope ?? null,
+    grammar: d.grammar,
+    grammarSeverity: d.grammarSeverity,
     requirements: d.requirements.map((r) => ({
       id: r.id,
       status: r.status,
@@ -115,6 +121,7 @@ function orderDomain(d) {
       issues: r.issues.map((iss) => ({ role: iss.role, id: iss.id })),
       changedAtVersion: r.changedAtVersion,
       supersededAtVersion: r.supersededAtVersion,
+      deprecatedReason: r.deprecatedReason,
       term: r.term,
       aliases: r.aliases,
       cites: r.cites.map((c) => ({ term: c.term, pinned: c.pinned })),
@@ -157,6 +164,7 @@ var init_domain = __esm(() => {
     issues: z2.array(SpecIssueSchema).optional().default([]),
     changedAtVersion: z2.number().int().optional(),
     supersededAtVersion: z2.number().int().optional(),
+    deprecatedReason: z2.string().optional(),
     term: z2.string().optional(),
     aliases: z2.array(z2.string()).optional().default([]),
     cites: z2.array(SpecCiteSchema).optional().default([]),
@@ -168,9 +176,109 @@ var init_domain = __esm(() => {
     specVersion: z2.number().int().positive().optional(),
     updated: z2.string(),
     scope: z2.string().nullable().optional(),
+    grammar: z2.enum(["ears", "freeform"]).optional(),
+    grammarSeverity: z2.enum(["warning", "error"]).optional(),
     requirements: z2.array(SpecRequirementSchema)
   }).strict();
 });
+
+// ../shared/src/ears.ts
+function reject(problem) {
+  return { ok: false, problem, expected: EARS_EXPECTED };
+}
+function parseEarsStatement(raw) {
+  const statement = raw.trim();
+  if (statement === "")
+    return reject("the statement is empty");
+  if (!/\bshall\b/.test(statement)) {
+    return reject('missing the word "shall" \u2014 it separates who acts from the observable result (e.g. "spec check shall exit 1")');
+  }
+  for (const { keyword, pattern, re } of CONDITIONAL) {
+    if (!statement.startsWith(`${keyword} `))
+      continue;
+    const m2 = statement.match(re);
+    if (m2) {
+      const [, condition, system, response] = m2;
+      return {
+        ok: true,
+        clauses: {
+          pattern,
+          condition: condition.trim(),
+          system: system.trim().replace(/^the\s+/i, ""),
+          response: response.trim()
+        }
+      };
+    }
+    if (keyword === "If" && !/,\s*then\s/.test(statement)) {
+      return reject('starts with "If" but has no ", then" \u2014 the failure clause never hands over to the system');
+    }
+    return reject(`starts with "${keyword}" but the condition clause never ends \u2014 add a comma before naming the system that acts`);
+  }
+  const m = statement.match(ALWAYS_RE);
+  if (m) {
+    const [, system, response] = m;
+    if (/,/.test(system)) {
+      return reject('the clause before "shall" contains a comma but starts with no condition keyword (When/While/If/Where) \u2014 either drop the comma or lead with the condition');
+    }
+    return {
+      ok: true,
+      clauses: {
+        pattern: "always",
+        condition: null,
+        system: system.trim().replace(/^the\s+/i, ""),
+        response: response.trim()
+      }
+    };
+  }
+  return reject('nothing follows "shall" \u2014 the observable result is missing');
+}
+var EARS_EXPECTED, CONDITIONAL, ALWAYS_RE;
+var init_ears = __esm(() => {
+  EARS_EXPECTED = [
+    'When <trigger>, the <system> shall <result> \u2014 e.g. "When an unknown id is passed, spec resolve shall print [] and exit 0."',
+    "While <state>, the <system> shall <result>",
+    "If <failure>, then the <system> shall <result>",
+    "Where <feature>, the <system> shall <result>",
+    "The <system> shall <result>"
+  ].join(`
+  `);
+  CONDITIONAL = [
+    { keyword: "When", pattern: "when", re: /^When\s+(.+?),\s*(.+?)\s+shall\s+(.+)$/s },
+    { keyword: "While", pattern: "while", re: /^While\s+(.+?),\s*(.+?)\s+shall\s+(.+)$/s },
+    { keyword: "If", pattern: "if", re: /^If\s+(.+?),\s*then\s+(.+?)\s+shall\s+(.+)$/s },
+    { keyword: "Where", pattern: "where", re: /^Where\s+(.+?),\s*(.+?)\s+shall\s+(.+)$/s }
+  ];
+  ALWAYS_RE = /^(.+?)\s+shall\s+(.+)$/s;
+});
+
+// ../shared/src/flags.ts
+function parseFlags(value) {
+  const enabled = new Set;
+  for (const rawKey of (value ?? "").split(",")) {
+    const key = rawKey.trim().toLowerCase();
+    if (FEATURE_KEYS.includes(key))
+      enabled.add(key);
+  }
+  return enabled;
+}
+function featureEnabled(key) {
+  return parseFlags(process.env.SPEC_FLAGS).has(key);
+}
+function featureDisabledMessage(key) {
+  return `${FEATURES[key].label} is not enabled (coming soon). To try it locally, run with SPEC_FLAGS=${key}.`;
+}
+var FEATURES, FEATURE_KEYS;
+var init_flags = __esm(() => {
+  FEATURES = {
+    glossary: { label: "Glossary" },
+    relations: { label: "Relations" },
+    provenance: { label: "Provenance" },
+    query: { label: "Query" },
+    editor: { label: "Editor" },
+    logs: { label: "Logs" }
+  };
+  FEATURE_KEYS = Object.keys(FEATURES);
+});
 // ../shared/src/net.ts
 function isLoopbackHostname(hostname) {
   return LOOPBACK_HOSTNAMES.has(hostname);
@@ -340,7 +448,7 @@ CREATE INDEX IF NOT EXISTS idx_term_citations_term ON term_citations(term_id);
 -- Invariant #4). source_file + line locate the authored **Issues:** field line.
 -- Exactly ONE index, on req_id (SC3) \u2014 never on issue_id, which would read as
 -- treating the opaque payload as a lookup key (PROV-02, grep-fenced in Plan 04).
--- @spec PROV-001
+-- @spec PROV-004
 CREATE TABLE IF NOT EXISTS provenance (
   id            INTEGER PRIMARY KEY AUTOINCREMENT,
   req_id        TEXT NOT NULL,
@@ -398,6 +506,7 @@ LEFT JOIN tags t
 -- cell. The Q4 ORPHAN_REQ / Q5 UNVERIFIED_REQ queries (sqlite.ts) carry the
 -- SAME literal exclusion so a term never fires a coverage ERROR. The match is
 -- the exact literal 'TERM' \u2014 never a real domain key.
+-- @spec SCHM-017
 WHERE r.key != 'TERM'
 GROUP BY r.id, repos.name;
 
@@ -424,7 +533,7 @@ WHERE r.changed_at_version > repos.pinned_spec_version;
 -- the Wave-D diagnostics. term.key='TERM' keeps the VIEW scoped to the reserved
 -- glossary domain. Present-and-empty until Wave C populates term_citations; the
 -- diagnostic (TERM_DRIFT) reads it in Wave E.
--- @spec CHCK-005
+-- @spec CHCK-018
 CREATE VIEW IF NOT EXISTS term_drift AS
 SELECT
   tc.req_id                  AS req_id,
@@ -510,7 +619,7 @@ var init_schema = __esm(() => {
 // ../shared/src/storage.ts
 var REQUIREMENT_STATUSES;
 var init_storage = __esm(() => {
-  REQUIREMENT_STATUSES = ["Active", "Superseded", "Draft", "Retired"];
+  REQUIREMENT_STATUSES = ["Active", "Superseded", "Draft", "Deprecated"];
 });
 
 // ../shared/src/index.ts
@@ -518,6 +627,8 @@ var init_src = __esm(() => {
   init_config();
   init_diagnostics();
   init_domain();
+  init_ears();
+  init_flags();
   init_net();
   init_propagation();
   init_schema();
@@ -772,7 +883,8 @@ var init_domainJson = __esm(() => {
     active: "Active",
     draft: "Draft",
     superseded: "Superseded",
-    retired: "Retired"
+    deprecated: "Deprecated",
+    retired: "Deprecated"
   });
   VALID_ROLES = new Set(["created", "supersedes-via", "amends-via"]);
 });
@@ -1292,6 +1404,8 @@ class SqliteStorage {
     for (const sql of [
       Q1_DANGLING_TAG_SQL,
       Q2_SUPERSEDED_REFERENCED_SQL,
+      Q2B_DEPRECATED_REFERENCED_SQL,
+      Q2D_DRAFT_REFERENCED_SQL,
       Q3_DRIFT_SQL,
       Q4_ORPHAN_REQ_SQL,
       Q5_UNVERIFIED_REQ_SQL,
@@ -1651,6 +1765,34 @@ FROM tags t
 JOIN requirements r ON r.id = t.req_id
 WHERE r.status = 'Superseded'
 ORDER BY t.repo, t.file, t.line
+`, Q2B_DEPRECATED_REFERENCED_SQL = `
+SELECT
+  'DEPRECATED_REFERENCED'                                     AS code,
+  t.repo                                                      AS repo,
+  t.file                                                      AS source_file,
+  t.line                                                      AS line,
+  t.req_id                                                    AS req_id,
+  ('Tag references deprecated requirement ' || t.req_id ||
+    ' \u2014 it is end-of-life with no successor')                 AS detail,
+  'error'                                                     AS severity
+FROM tags t
+JOIN requirements r ON r.id = t.req_id
+WHERE r.status = 'Deprecated'
+ORDER BY t.repo, t.file, t.line
+`, Q2D_DRAFT_REFERENCED_SQL = `
+SELECT
+  'DRAFT_REFERENCED'                                          AS code,
+  t.repo                                                      AS repo,
+  t.file                                                      AS source_file,
+  t.line                                                      AS line,
+  t.req_id                                                    AS req_id,
+  ('Tag references Draft requirement ' || t.req_id ||
+    ' \u2014 code is bound to a promise nobody approved yet')      AS detail,
+  'warning'                                                   AS severity
+FROM tags t
+JOIN requirements r ON r.id = t.req_id
+WHERE r.status = 'Draft'
+ORDER BY t.repo, t.file, t.line
 `, Q3_DRIFT_SQL = `
 SELECT
   'DRIFT'                                                     AS code,
@@ -1680,6 +1822,7 @@ WHERE r.status = 'Active'
   -- code-coverage obligation \u2014 exclude the reserved TERM domain so a migrated
   -- term never fires ORPHAN_REQ. Literal 'TERM' only, never a real domain key;
   -- mirrors the coverage VIEW exclusion (WHERE r.key != 'TERM') in schema.ts.
+  -- @spec SCHM-017
   AND r.key != 'TERM'
   AND NOT EXISTS (
     SELECT 1 FROM tags t WHERE t.req_id = r.id AND t.kind != 'documents'
@@ -1853,7 +1996,7 @@ SELECT
 FROM repos
 WHERE repos.name != 'spec-engine'
 ORDER BY repos.name
-`, FTS_SEARCH_SQL = `SELECT r.id AS req_id, r.key AS key, r.text AS text, r.why AS why, r.source_file AS source_file, r.line AS line, bm25(requirements_fts, 1.0, 0.5) AS rank FROM requirements_fts JOIN requirements r ON r.rowid = requirements_fts.rowid WHERE requirements_fts MATCH $query AND r.status != 'Superseded' ORDER BY rank ASC LIMIT $limit`, RESOLVE_BY_FILES_SQL_PREFIX = "SELECT DISTINCT r.id, r.key, r.seq, r.status, r.superseded_by, r.text, r.why, r.source_file, r.line, r.spec_version, r.changed_at_version, r.superseded_at_version FROM tags t JOIN requirements r ON r.id = t.req_id WHERE t.file IN (", RESOLVE_BY_FILES_SQL_SUFFIX = ") ORDER BY r.key, r.seq", LIST_REPOS_SQL = "SELECT name, path, pinned_spec_version FROM repos ORDER BY name", GET_REPO_SQL = "SELECT name, path, pinned_spec_version FROM repos WHERE name = $name", LIST_TAGS_SQL = `SELECT id, req_id, repo, file, line, kind, level FROM tags
+`, FTS_SEARCH_SQL = `SELECT r.id AS req_id, r.key AS key, r.text AS text, r.why AS why, r.source_file AS source_file, r.line AS line, bm25(requirements_fts, 1.0, 0.5) AS rank FROM requirements_fts JOIN requirements r ON r.rowid = requirements_fts.rowid WHERE requirements_fts MATCH $query AND r.status NOT IN ('Superseded', 'Deprecated') ORDER BY rank ASC LIMIT $limit`, RESOLVE_BY_FILES_SQL_PREFIX = "SELECT DISTINCT r.id, r.key, r.seq, r.status, r.superseded_by, r.text, r.why, r.source_file, r.line, r.spec_version, r.changed_at_version, r.superseded_at_version FROM tags t JOIN requirements r ON r.id = t.req_id WHERE t.file IN (", RESOLVE_BY_FILES_SQL_SUFFIX = ") ORDER BY r.key, r.seq", LIST_REPOS_SQL = "SELECT name, path, pinned_spec_version FROM repos ORDER BY name", GET_REPO_SQL = "SELECT name, path, pinned_spec_version FROM repos WHERE name = $name", LIST_TAGS_SQL = `SELECT id, req_id, repo, file, line, kind, level FROM tags
   WHERE ($repo IS NULL OR repo = $repo)
     AND ($req_id IS NULL OR req_id = $req_id)
     AND ($file IS NULL OR file = $file)
@@ -2659,8 +2802,8 @@ var init_errors = __esm(() => {
 });
 
 // src/commands/_shared.ts
-import { existsSync as existsSync4, mkdirSync as mkdirSync2 } from "fs";
-import { dirname as dirname5 } from "path";
+import { existsSync as existsSync4, mkdirSync as mkdirSync2, readdirSync, statSync as statSync4 } from "fs";
+import { dirname as dirname5, join as join7 } from "path";
 function assertContainedPath(resolved, platformDir, subject) {
   if (!isContainedPath(resolved, platformDir)) {
     console.error(`${subject} path must be inside platformDir (resolved to ${resolved})`);
@@ -2692,6 +2835,23 @@ async function reindexAndListTags(platformDir, reqId) {
     storage2.close();
   }
 }
+function warnIfIndexStale(platformDir, dbPath) {
+  try {
+    const dbMtime = statSync4(dbPath).mtimeMs;
+    const specsDir = join7(platformDir, "spec-engine");
+    for (const entry of readdirSync(specsDir, { withFileTypes: true })) {
+      if (!entry.isDirectory())
+        continue;
+      const specPath = join7(specsDir, entry.name, "SPEC.json");
+      if (!existsSync4(specPath))
+        continue;
+      if (statSync4(specPath).mtimeMs > dbMtime) {
+        console.error(`spec: warning \u2014 spec-engine/${entry.name}/SPEC.json changed after the index was built; results may be stale. Pass --fresh to rebuild.`);
+        return;
+      }
+    }
+  } catch {}
+}
 async function withReadStorage(opts, fn) {
   const { platformDir, dbPath, fresh } = opts;
   try {
@@ -2704,6 +2864,8 @@ async function withReadStorage(opts, fn) {
     try {
       if (needsIndex || storage2.listRepos().length === 0) {
         await runIndex({ platformDir, storage: storage2 });
+      } else {
+        warnIfIndexStale(platformDir, dbPath);
       }
       await fn(storage2);
     } finally {
@@ -2987,6 +3149,147 @@ function renderDiagnostics(rows, mode) {
 `);
 }
 
+// src/authoring/domains.ts
+import { existsSync as existsSync5, readdirSync as readdirSync2 } from "fs";
+import { join as join8 } from "path";
+function normalizeDomainKey(raw) {
+  return raw.toUpperCase().replace(/\s+/g, "");
+}
+function listDomainKeys(platformDir) {
+  const specsDir = join8(platformDir, "spec-engine");
+  return readdirSync2(specsDir, { withFileTypes: true }).filter((e) => e.isDirectory() && existsSync5(join8(specsDir, e.name, "SPEC.json"))).map((e) => e.name).sort();
+}
+async function domainScope(platformDir, key) {
+  const jsonPath = join8(platformDir, "spec-engine", key, "SPEC.json");
+  if (!existsSync5(jsonPath))
+    return null;
+  try {
+    const env = JSON.parse(await Bun.file(jsonPath).text());
+    if (typeof env.scope !== "string" || env.scope.trim() === "")
+      return null;
+    return env.scope;
+  } catch (e) {
+    if (e instanceof SyntaxError)
+      return null;
+    console.error(`spec: could not read scope for ${key}: ${e.message}`);
+    return null;
+  }
+}
+async function domainsWithScope(platformDir) {
+  const keys = listDomainKeys(platformDir);
+  return Promise.all(keys.map(async (key) => ({ key, scope: await domainScope(platformDir, key) })));
+}
+function scaffoldDomainObject(key, today) {
+  return {
+    key,
+    owner: null,
+    ...key === "TERM" ? { specVersion: 1 } : {},
+    updated: today,
+    requirements: []
+  };
+}
+function maxSeqOf(domain2) {
+  const reqs = Array.isArray(domain2.requirements) ? domain2.requirements : [];
+  return reqs.reduce((m, r) => {
+    const id = typeof r?.id === "string" ? r.id : "";
+    const seq = Number(id.split("-")[1]);
+    return Number.isFinite(seq) ? Math.max(m, seq) : m;
+  }, 0);
+}
+async function headMaxSeq(platformDir, key) {
+  try {
+    const proc = Bun.spawn(["git", "-C", join8(platformDir, "spec-engine", key), "show", "HEAD:./SPEC.json"], { stdout: "pipe", stderr: "ignore" });
+    const text = await new Response(proc.stdout).text();
+    if (await proc.exited !== 0)
+      return 0;
+    return maxSeqOf(JSON.parse(text));
+  } catch {
+    return 0;
+  }
+}
+async function nextRequirementId(platformDir, key) {
+  const jsonPath = join8(platformDir, "spec-engine", key, "SPEC.json");
+  if (!existsSync5(jsonPath))
+    return `${key}-001`;
+  const domain2 = JSON.parse(await Bun.file(jsonPath).text());
+  const maxSeq = Math.max(maxSeqOf(domain2), await headMaxSeq(platformDir, key));
+  const next = String(maxSeq + 1).padStart(3, "0");
+  return `${key}-${next}`;
+}
+var init_domains = __esm(() => {
+  init_src();
+});
+
+// src/check/grammar.ts
+import { join as join9 } from "path";
+function lineOf(rawText, id) {
+  const lines = rawText.split(`
+`);
+  const needle = `"id": "${id}"`;
+  for (let i = 0;i < lines.length; i++) {
+    if (lines[i].includes(needle))
+      return i + 1;
+  }
+  return 0;
+}
+async function readDeclaredDomain(platformDir, key) {
+  try {
+    const raw = await Bun.file(join9(platformDir, "spec-engine", key, "SPEC.json")).text();
+    const doc = JSON.parse(raw);
+    if (doc.grammar !== "ears")
+      return null;
+    return {
+      raw,
+      severity: doc.grammarSeverity === "error" ? "error" : "warning",
+      requirements: Array.isArray(doc.requirements) ? doc.requirements : []
+    };
+  } catch {
+    return null;
+  }
+}
+function rowsForDomain(key, domain2) {
+  const rows = [];
+  for (const req of domain2.requirements) {
+    if (typeof req?.id !== "string" || typeof req.statement !== "string")
+      continue;
+    const status = typeof req.status === "string" ? req.status.toLowerCase() : "";
+    if (!CHECKED_STATUSES.has(status))
+      continue;
+    const result = parseEarsStatement(req.statement);
+    if (result.ok)
+      continue;
+    rows.push({
+      code: DiagnosticCode.STATEMENT_GRAMMAR,
+      severity: domain2.severity,
+      repo: null,
+      source_file: `spec-engine/${key}/SPEC.json`,
+      line: lineOf(domain2.raw, req.id),
+      req_id: req.id,
+      detail: `${result.problem}. Expected one of:
+  ${result.expected}`
+    });
+  }
+  return rows;
+}
+async function statementGrammarDiagnostics(platformDir) {
+  const rows = [];
+  for (const key of listDomainKeys(platformDir)) {
+    if (key === "TERM")
+      continue;
+    const domain2 = await readDeclaredDomain(platformDir, key);
+    if (domain2 !== null)
+      rows.push(...rowsForDomain(key, domain2));
+  }
+  rows.sort((a, b) => (a.source_file ?? "").localeCompare(b.source_file ?? "") || (a.line ?? 0) - (b.line ?? 0) || (a.req_id ?? "").localeCompare(b.req_id ?? ""));
+  return rows;
+}
+var CHECKED_STATUSES;
+var init_grammar = __esm(() => {
+  init_src();
+  init_domains();
+  CHECKED_STATUSES = new Set(["active", "draft"]);
+});
+
 // src/check/proven.ts
 function normalizeToSegments(path) {
   const out = [];
@@ -3154,7 +3457,8 @@ function requirementRemoved(baseReqs, changeReqs, relPathById) {
   for (const b of baseReqs) {
     if (changeIds.has(b.id))
       continue;
-    const exempt = b.supersededBy != null && changeIds.has(b.supersededBy) || changeReqs.some((y) => y.supersedes === b.id);
+    const activeAtBase = (b.status ?? "").toLowerCase() === "active";
+    const exempt = activeAtBase && (b.supersededBy != null && changeIds.has(b.supersededBy) || changeReqs.some((y) => y.supersedes === b.id));
     if (exempt)
       continue;
     out.push({
@@ -3163,7 +3467,7 @@ function requirementRemoved(baseReqs, changeReqs, relPathById) {
       line: 0,
       repo: null,
       req_id: b.id,
-      detail: `${b.id} was present in the base ref but is absent from the change with no approved supersession`,
+      detail: activeAtBase ? `${b.id} was present in the base ref but is absent from the change with no approved supersession` : `${b.id} (${b.status}) was present in the base ref but is absent from the change \u2014 a requirement is never deleted, and its history is the record`,
       severity: "error"
     });
   }
@@ -3193,11 +3497,11 @@ function normalizeHandle(h) {
   return (h.startsWith("@") ? h.slice(1) : h).toLowerCase();
 }
 function isNewTerminalFlip(base, change) {
-  if (change !== "superseded" && change !== "retired")
+  if (!TERMINAL_STATUSES.has(change))
     return false;
   if (base === undefined)
     return false;
-  if (base === "superseded" || base === "retired")
+  if (TERMINAL_STATUSES.has(base))
     return false;
   return base !== change;
 }
@@ -3226,8 +3530,10 @@ function unapprovedStatusFlip(baseReqs, changeReqs, codeowners, approvedBy, relP
   }
   return out;
 }
+var TERMINAL_STATUSES;
 var init_statusflip = __esm(() => {
   init_src();
+  TERMINAL_STATUSES = new Set(["superseded", "deprecated", "retired"]);
 });
 
 // src/check/unsourced.ts
@@ -3521,76 +3827,307 @@ var init_junit = __esm(() => {
   ]);
 });
 
-// src/commands/check.ts
-var exports_check = {};
-__export(exports_check, {
-  checkCommand: () => checkCommand
+// src/authoring/edit.ts
+function localToday() {
+  const d = new Date;
+  return `${d.getFullYear()}-` + `${String(d.getMonth() + 1).padStart(2, "0")}-` + `${String(d.getDate()).padStart(2, "0")}`;
+}
+
+// src/commands/glossary.ts
+var exports_glossary = {};
+__export(exports_glossary, {
+  parseGlossary: () => parseGlossary,
+  glossaryDriftDiagnostic: () => glossaryDriftDiagnostic,
+  glossaryCommand: () => glossaryCommand,
+  generateGlossary: () => generateGlossary
 });
-import { existsSync as existsSync5, mkdirSync as mkdirSync4, readFileSync } from "fs";
-import { dirname as dirname7, join as join7, resolve as resolve7 } from "path";
+import { existsSync as existsSync6, readFileSync } from "fs";
+import { join as join10, resolve as resolve7 } from "path";
 import { defineCommand as defineCommand3 } from "citty";
-function readCodeownersText(platformDir) {
-  const path = join7(platformDir, ".github", "CODEOWNERS");
-  if (!existsSync5(path))
-    return null;
-  return readFileSync(path, "utf-8");
-}
-function domainReqsFromText(text, platformRel) {
-  let parsed;
-  try {
-    parsed = JSON.parse(text);
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    return {
-      reqs: [],
-      diagnostics: [
-        {
-          code: DiagnosticCode.INVALID_DOMAIN_FILE,
-          source_file: platformRel,
-          line: 0,
-          repo: null,
-          req_id: null,
-          detail: `not valid JSON: ${msg}`,
-          severity: "error"
-        }
-      ]
-    };
+function parseGlossary(md) {
+  const terms = [];
+  let section = null;
+  let buf = null;
+  const flush = () => {
+    if (buf === null)
+      return;
+    const m = buf.match(/^\*\*(.+?)\*\*/);
+    if (m) {
+      const remainder = buf.slice(m[0].length);
+      const statement = remainder.replace(/^ \u2014 /, "").trim();
+      terms.push({ term: m[1], statement, section });
+    }
+    buf = null;
+  };
+  for (const line of md.split(`
+`)) {
+    if (line.startsWith("## ")) {
+      flush();
+      section = line.slice(3).trim();
+    } else if (line.startsWith("- ")) {
+      flush();
+      buf = line.slice(2);
+    } else if (buf !== null) {
+      if (line.trim() === "")
+        flush();
+      else
+        buf += ` ${line.trim()}`;
+    }
   }
-  const validated = validateDomainFile(parsed, platformRel);
-  if (!validated.ok)
-    return { reqs: [], diagnostics: validated.diagnostics };
-  return { reqs: validated.data.requirements, diagnostics: [] };
+  flush();
+  return terms;
 }
-async function ingestResults(storage2, platformDir, resultsArg, jsonMode, diagnostics2) {
-  if (!resultsArg) {
-    if (jsonMode) {
-      console.error("spec check: no --results supplied; proofs unconfirmed (PROOFS_UNCONFIRMED) \u2014 run with --results <junit.xml> to enforce trusted-red");
-    } else {
-      diagnostics2.push(proofsUnconfirmedWarning());
+function generateGlossary(terms) {
+  const parts = ["# Glossary", "", GLOSSARY_INTRO];
+  let section;
+  for (const t of terms) {
+    if (t.section !== section) {
+      section = t.section;
+      if (section !== null && section !== undefined) {
+        parts.push("", `## ${section}`, "");
+      }
     }
-    return { resultsParsed: undefined, verifyingTags: undefined };
+    parts.push(`- **${t.term}** \u2014 ${t.statement}`);
   }
-  const resultsPath = resolve7(platformDir, resultsArg);
-  if (!isContainedPath(resultsPath, platformDir)) {
-    console.error(`spec check: --results path must be inside platformDir (resolved to ${resultsPath})`);
-    try {
-      storage2.close();
-    } catch {}
-    process.exit(EXIT.USAGE);
+  return `${parts.join(`
+`)}
+`;
+}
+function resolvePlatform(platformDirRaw) {
+  const platformDir = resolve7(platformDirRaw ?? process.cwd());
+  try {
+    assertSpecPlatform(platformDir);
+  } catch (e) {
+    handleNotAPlatform(e);
   }
-  const xml = await Bun.file(resultsPath).text();
-  const resultsParsed = parseJUnit(xml);
-  const verifyingTags = storage2.listTags().filter((t) => t.kind === "verifies");
-  const active = storage2.listRequirements({ status: "Active" });
-  diagnostics2.push(...provenDetermination(active, verifyingTags, resultsParsed));
-  return { resultsParsed, verifyingTags };
+  return platformDir;
+}
+function readStoreTerms(platformDir) {
+  const specPath = join10(platformDir, "spec-engine", TERM_KEY, "SPEC.json");
+  if (!existsSync6(specPath))
+    return [];
+  const domain2 = JSON.parse(readFileSync(specPath, "utf8"));
+  const reqs = Array.isArray(domain2.requirements) ? domain2.requirements : [];
+  return reqs.filter((r) => String(r.status).toLowerCase() === "active").sort((a, b) => String(a.id) < String(b.id) ? -1 : String(a.id) > String(b.id) ? 1 : 0).map((r) => ({
+    term: String(r.term ?? ""),
+    statement: String(r.statement ?? ""),
+    section: r.section ?? null
+  }));
+}
+function glossaryPath(platformDir) {
+  return join10(platformDir, "GLOSSARY.md");
+}
+async function migrateGlossary(platformDir, json) {
+  const relFile = `spec-engine/${TERM_KEY}/SPEC.json`;
+  const specPath = join10(platformDir, "spec-engine", TERM_KEY, "SPEC.json");
+  if (!existsSync6(specPath)) {
+    console.error(`spec glossary: no TERM domain (expected ${relFile} under ${platformDir})`);
+    process.exit(EXIT.USAGE);
+  }
+  const domain2 = JSON.parse(readFileSync(specPath, "utf8"));
+  const existing = Array.isArray(domain2.requirements) ? domain2.requirements : [];
+  if (existing.length > 0) {
+    console.error(`spec glossary: TERM domain already holds ${existing.length} entries \u2014 migration skipped`);
+    if (json)
+      console.log(JSON.stringify({ migrated: 0, skipped: true }));
+    else
+      console.log("migration skipped (TERM domain not empty)");
+    return;
+  }
+  const gPath = glossaryPath(platformDir);
+  if (!existsSync6(gPath)) {
+    console.error(`spec glossary: no GLOSSARY.md to migrate (expected ${gPath})`);
+    process.exit(EXIT.USAGE);
+  }
+  const parsed = parseGlossary(readFileSync(gPath, "utf8"));
+  domain2.requirements = parsed.map((t, i) => ({
+    id: `${TERM_KEY}-${String(i + 1).padStart(3, "0")}`,
+    status: "active",
+    statement: t.statement,
+    term: t.term,
+    why: null,
+    supersedes: null,
+    supersededBy: null,
+    relates: [],
+    livesIn: [],
+    issues: [],
+    aliases: [],
+    cites: [],
+    changedAtVersion: 1,
+    section: t.section
+  }));
+  domain2.updated = localToday();
+  const res = await validateAndWrite(specPath, domain2, relFile);
+  if (!res.ok) {
+    for (const diag of res.diagnostics)
+      console.error(`spec glossary: ${diag.detail}`);
+    process.exit(EXIT.USAGE);
+  }
+  const count = parsed.length;
+  if (json)
+    console.log(JSON.stringify({ migrated: count, file: relFile }));
+  else
+    console.log(`migrated ${count} terms into ${relFile}`);
+}
+async function writeGlossary(platformDir, json) {
+  const terms = readStoreTerms(platformDir);
+  await Bun.write(glossaryPath(platformDir), generateGlossary(terms));
+  if (json)
+    console.log(JSON.stringify({ generated: terms.length, file: "GLOSSARY.md" }));
+  else
+    console.log(`generated GLOSSARY.md from ${terms.length} terms`);
+}
+function glossaryDriftDiagnostic(platformDir) {
+  const terms = readStoreTerms(platformDir);
+  if (terms.length === 0)
+    return null;
+  const gPath = glossaryPath(platformDir);
+  if (!existsSync6(gPath))
+    return null;
+  const generated = generateGlossary(terms);
+  const committed = readFileSync(gPath, "utf8");
+  if (generated === committed)
+    return null;
+  return {
+    code: DiagnosticCode.GLOSSARY_DRIFT,
+    severity: "warning",
+    repo: null,
+    source_file: "GLOSSARY.md",
+    line: 0,
+    req_id: null,
+    detail: "GLOSSARY.md does not match the TERM store \u2014 run `spec glossary .` to regenerate the human view"
+  };
+}
+function checkGlossary(platformDir, json) {
+  const generated = generateGlossary(readStoreTerms(platformDir));
+  const gPath = glossaryPath(platformDir);
+  const committed = existsSync6(gPath) ? readFileSync(gPath, "utf8") : "";
+  if (generated === committed) {
+    if (json)
+      console.log(JSON.stringify({ ok: true }));
+    else
+      console.error("glossary round-trip: OK (committed GLOSSARY.md == generated)");
+    return;
+  }
+  console.error("glossary drift: committed GLOSSARY.md != generated from the TERM store");
+  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);
+}
+var TERM_KEY = "TERM", GLOSSARY_INTRO = `Canonical names for Spec Engine concepts. When prose, code comments, diagnostics, or
+docs need one of these ideas, use the term below \u2014 not a synonym. Terms are ordered
+by the data model, outside-in.`, glossaryCommand;
+var init_glossary = __esm(() => {
+  init_src();
+  init_constants();
+  init_discover();
+  init__shared();
+  glossaryCommand = defineCommand3({
+    meta: {
+      name: "glossary",
+      description: "Generate GLOSSARY.md from the TERM store (byte-stable); --migrate parses GLOSSARY.md into TERM-001..N; --check fails on drift (committed != generated)"
+    },
+    args: {
+      platformDir: {
+        type: "positional",
+        required: false,
+        description: "Platform directory containing spec-engine/ (default: cwd)"
+      },
+      migrate: {
+        type: "boolean",
+        description: "One-time: parse the committed GLOSSARY.md into TERM-001..N (idempotent-skip)"
+      },
+      check: {
+        type: "boolean",
+        description: "Fail (exit 1) if the committed GLOSSARY.md differs from the generated output"
+      },
+      json: { type: "boolean", description: "Emit a JSON result instead of the text summary" }
+    },
+    async run({ args }) {
+      const platformDir = resolvePlatform(args.platformDir);
+      const json = Boolean(args.json);
+      if (args.migrate) {
+        await migrateGlossary(platformDir, json);
+      } else if (args.check) {
+        checkGlossary(platformDir, json);
+      } else {
+        await writeGlossary(platformDir, json);
+      }
+    }
+  });
+});
+
+// src/commands/check.ts
+var exports_check = {};
+__export(exports_check, {
+  checkCommand: () => checkCommand
+});
+import { existsSync as existsSync7, mkdirSync as mkdirSync4, readFileSync as readFileSync2 } from "fs";
+import { dirname as dirname7, join as join11, resolve as resolve8 } from "path";
+import { defineCommand as defineCommand4 } from "citty";
+function readCodeownersText(platformDir) {
+  const path = join11(platformDir, ".github", "CODEOWNERS");
+  if (!existsSync7(path))
+    return null;
+  return readFileSync2(path, "utf-8");
+}
+function domainReqsFromText(text, platformRel) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+      reqs: [],
+      diagnostics: [
+        {
+          code: DiagnosticCode.INVALID_DOMAIN_FILE,
+          source_file: platformRel,
+          line: 0,
+          repo: null,
+          req_id: null,
+          detail: `not valid JSON: ${msg}`,
+          severity: "error"
+        }
+      ]
+    };
+  }
+  const validated = validateDomainFile(parsed, platformRel);
+  if (!validated.ok)
+    return { reqs: [], diagnostics: validated.diagnostics };
+  return { reqs: validated.data.requirements, diagnostics: [] };
+}
+async function ingestResults(storage2, platformDir, resultsArg, jsonMode, diagnostics2) {
+  if (!resultsArg) {
+    if (jsonMode) {
+      console.error("spec check: no --results supplied; proofs unconfirmed (PROOFS_UNCONFIRMED) \u2014 run with --results <junit.xml> to enforce trusted-red");
+    } else {
+      diagnostics2.push(proofsUnconfirmedWarning());
+    }
+    return { resultsParsed: undefined, verifyingTags: undefined };
+  }
+  const resultsPath = resolve8(platformDir, resultsArg);
+  if (!isContainedPath(resultsPath, platformDir)) {
+    console.error(`spec check: --results path must be inside platformDir (resolved to ${resultsPath})`);
+    try {
+      storage2.close();
+    } catch {}
+    process.exit(EXIT.USAGE);
+  }
+  const xml = await Bun.file(resultsPath).text();
+  const resultsParsed = parseJUnit(xml);
+  const verifyingTags = storage2.listTags().filter((t) => t.kind === "verifies");
+  const active = storage2.listRequirements({ status: "Active" });
+  diagnostics2.push(...provenDetermination(active, verifyingTags, resultsParsed));
+  return { resultsParsed, verifyingTags };
 }
 async function collectChangeReqs(canonicalDir) {
   const reqs = [];
   const relPathById = new Map;
   for (const rel of await findDomainJsonFiles(canonicalDir)) {
     const platformRel = `spec-engine/${rel}`;
-    const text = await Bun.file(join7(canonicalDir, rel)).text();
+    const text = await Bun.file(join11(canonicalDir, rel)).text();
     const parsed = domainReqsFromText(text, platformRel);
     for (const r of parsed.reqs) {
       reqs.push(r);
@@ -3630,7 +4167,7 @@ async function runGovernanceGate(storage2, platformDir, args, diagnostics2, resu
     } catch {}
     process.exit(EXIT.USAGE);
   }
-  const canonicalDir = join7(platformDir, "spec-engine");
+  const canonicalDir = join11(platformDir, "spec-engine");
   const change = await collectChangeReqs(canonicalDir);
   const base = collectBaseReqs(platformDir, ref, diagnostics2);
   diagnostics2.push(...requirementRemoved(base.reqs, change.reqs, (id) => base.relPathById.get(id) ?? null));
@@ -3656,6 +4193,7 @@ function exitAfterCrash(e, storage2) {
 var checkCommand;
 var init_check = __esm(() => {
   init_src();
+  init_grammar();
   init_propagation_teeth();
   init_proven();
   init_removed();
@@ -3669,7 +4207,8 @@ var init_check = __esm(() => {
   init_fs();
   init_sqlite();
   init__shared();
-  checkCommand = defineCommand3({
+  init_glossary();
+  checkCommand = defineCommand4({
     meta: {
       name: "check",
       description: "Cross-repo integrity check. --ci rebuilds the index cold (rm db+wal+shm). Exits 1 on any error-severity diagnostic."
@@ -3718,7 +4257,7 @@ var init_check = __esm(() => {
       }
     },
     async run({ args }) {
-      const platformDir = resolve7(args.platformDir ?? process.cwd());
+      const platformDir = resolve8(args.platformDir ?? process.cwd());
       const outArg = args.out;
       const dbPath = resolveDbPath(platformDir, outArg);
       if (outArg)
@@ -3747,12 +4286,22 @@ var init_check = __esm(() => {
           const provenance = storage2.listProvenance();
           diagnostics2.push(...unsourcedChanges(superseded, provenance));
         }
+        diagnostics2.push(...await statementGrammarDiagnostics(platformDir));
+        const glossaryDrift = glossaryDriftDiagnostic(platformDir);
+        if (glossaryDrift !== null)
+          diagnostics2.push(glossaryDrift);
         const results = await ingestResults(storage2, platformDir, args.results, !!args.json, diagnostics2);
         await runGovernanceGate(storage2, platformDir, {
           base: args.base,
           approvedBy: args.approvedBy,
           requireOwnerApproval: args.requireOwnerApproval
         }, diagnostics2, results);
+        if (!args.base && gitRefResolves(platformDir, "HEAD")) {
+          const change = await collectChangeReqs(join11(platformDir, "spec-engine"));
+          const baseParseSink = [];
+          const base = collectBaseReqs(platformDir, "HEAD", baseParseSink);
+          diagnostics2.push(...requirementRemoved(base.reqs, change.reqs, (id) => base.relPathById.get(id) ?? null));
+        }
         const output = renderDiagnostics(diagnostics2, args.json ? "json" : "text");
         console.log(output);
         if (!args.json) {
@@ -3768,63 +4317,6 @@ var init_check = __esm(() => {
   });
 });
 
-// src/authoring/domains.ts
-import { existsSync as existsSync6, readdirSync } from "fs";
-import { join as join8 } from "path";
-function normalizeDomainKey(raw) {
-  return raw.toUpperCase().replace(/\s+/g, "");
-}
-function listDomainKeys(platformDir) {
-  const specsDir = join8(platformDir, "spec-engine");
-  return readdirSync(specsDir, { withFileTypes: true }).filter((e) => e.isDirectory() && existsSync6(join8(specsDir, e.name, "SPEC.json"))).map((e) => e.name).sort();
-}
-async function domainScope(platformDir, key) {
-  const jsonPath = join8(platformDir, "spec-engine", key, "SPEC.json");
-  if (!existsSync6(jsonPath))
-    return null;
-  try {
-    const env = JSON.parse(await Bun.file(jsonPath).text());
-    if (typeof env.scope !== "string" || env.scope.trim() === "")
-      return null;
-    return env.scope;
-  } catch (e) {
-    if (e instanceof SyntaxError)
-      return null;
-    console.error(`spec: could not read scope for ${key}: ${e.message}`);
-    return null;
-  }
-}
-async function domainsWithScope(platformDir) {
-  const keys = listDomainKeys(platformDir);
-  return Promise.all(keys.map(async (key) => ({ key, scope: await domainScope(platformDir, key) })));
-}
-function scaffoldDomainObject(key, today) {
-  return {
-    key,
-    owner: null,
-    ...key === "TERM" ? { specVersion: 1 } : {},
-    updated: today,
-    requirements: []
-  };
-}
-async function nextRequirementId(platformDir, key) {
-  const jsonPath = join8(platformDir, "spec-engine", key, "SPEC.json");
-  if (!existsSync6(jsonPath))
-    return `${key}-001`;
-  const domain2 = JSON.parse(await Bun.file(jsonPath).text());
-  const reqs = Array.isArray(domain2.requirements) ? domain2.requirements : [];
-  const maxSeq = reqs.reduce((m, r) => {
-    const id = typeof r?.id === "string" ? r.id : "";
-    const seq = Number(id.split("-")[1]);
-    return Number.isFinite(seq) ? Math.max(m, seq) : m;
-  }, 0);
-  const next = String(maxSeq + 1).padStart(3, "0");
-  return `${key}-${next}`;
-}
-var init_domains = __esm(() => {
-  init_src();
-});
-
 // src/commands/domain.ts
 var exports_domain = {};
 __export(exports_domain, {
@@ -3832,9 +4324,9 @@ __export(exports_domain, {
   domainListCommand: () => domainListCommand,
   domainCommand: () => domainCommand
 });
-import { existsSync as existsSync7, mkdirSync as mkdirSync5 } from "fs";
-import { dirname as dirname8, join as join9, resolve as resolve8 } from "path";
-import { defineCommand as defineCommand4 } from "citty";
+import { existsSync as existsSync8, mkdirSync as mkdirSync5 } from "fs";
+import { dirname as dirname8, join as join12, resolve as resolve9 } from "path";
+import { defineCommand as defineCommand5 } from "citty";
 var domainNewCommand, domainListCommand, domainCommand;
 var init_domain2 = __esm(() => {
   init_src();
@@ -3842,7 +4334,7 @@ var init_domain2 = __esm(() => {
   init_constants();
   init_discover();
   init__shared();
-  domainNewCommand = defineCommand4({
+  domainNewCommand = defineCommand5({
     meta: {
       name: "new",
       description: "Scaffold a fresh spec-engine/<KEY>/SPEC.json (input normalized)"
@@ -3861,7 +4353,7 @@ var init_domain2 = __esm(() => {
     },
     async run({ args }) {
       const raw = args.name;
-      const platformDir = resolve8(args.platformDir ?? process.cwd());
+      const platformDir = resolve9(args.platformDir ?? process.cwd());
       const key = normalizeDomainKey(raw);
       if (key !== raw) {
         console.log(`spec domain: normalized "${raw}" \u2192 ${key}`);
@@ -3871,21 +4363,21 @@ var init_domain2 = __esm(() => {
         process.exit(EXIT.USAGE);
         return;
       }
-      const dest = join9(platformDir, "spec-engine", key, "SPEC.json");
-      const resolvedDest = resolve8(dest);
-      const resolvedRoot = resolve8(platformDir);
+      const dest = join12(platformDir, "spec-engine", key, "SPEC.json");
+      const resolvedDest = resolve9(dest);
+      const resolvedRoot = resolve9(platformDir);
       if (!(resolvedDest === resolvedRoot || resolvedDest.startsWith(`${resolvedRoot}/`))) {
         console.error(`spec domain new: refusing to write outside platformDir (${resolvedDest})`);
         process.exit(EXIT.USAGE);
         return;
       }
-      if (existsSync7(dest)) {
+      if (existsSync8(dest)) {
         console.error(`refusing to overwrite ${dest}`);
         process.exit(EXIT.USAGE);
         return;
       }
-      const mdSibling = join9(dirname8(dest), "SPEC.md");
-      if (existsSync7(mdSibling)) {
+      const mdSibling = join12(dirname8(dest), "SPEC.md");
+      if (existsSync8(mdSibling)) {
         console.error(`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)");
         process.exit(EXIT.USAGE);
         return;
@@ -3905,7 +4397,7 @@ var init_domain2 = __esm(() => {
       console.log(`created ${relFile}`);
     }
   });
-  domainListCommand = defineCommand4({
+  domainListCommand = defineCommand5({
     meta: {
       name: "list",
       description: "List domain keys (sorted, read from the filesystem)"
@@ -3922,7 +4414,7 @@ var init_domain2 = __esm(() => {
       }
     },
     async run({ args }) {
-      const platformDir = resolve8(args.platformDir ?? process.cwd());
+      const platformDir = resolve9(args.platformDir ?? process.cwd());
       try {
         assertSpecPlatform(platformDir);
       } catch (e) {
@@ -3937,7 +4429,7 @@ var init_domain2 = __esm(() => {
       }
     }
   });
-  domainCommand = defineCommand4({
+  domainCommand = defineCommand5({
     meta: {
       name: "domain",
       description: "Manage spec domains (spec-engine/<KEY>/)"
@@ -4016,15 +4508,15 @@ var exports_map = {};
 __export(exports_map, {
   mapCommand: () => mapCommand
 });
-import { resolve as resolve9 } from "path";
-import { defineCommand as defineCommand5 } from "citty";
+import { resolve as resolve10 } from "path";
+import { defineCommand as defineCommand6 } from "citty";
 var mapCommand;
 var init_map = __esm(() => {
   init_constants();
   init_discover();
   init_prompt();
   init__shared();
-  mapCommand = defineCommand5({
+  mapCommand = defineCommand6({
     meta: {
       name: "map",
       description: "Render the cross-repo coverage matrix from the coverage VIEW. --json emits a deterministically sorted JSON array."
@@ -4053,7 +4545,7 @@ var init_map = __esm(() => {
       }
     },
     async run({ args }) {
-      const platformDir = resolve9(args.platformDir ?? process.cwd());
+      const platformDir = resolve10(args.platformDir ?? process.cwd());
       const outArg = args.out;
       const dbPath = resolveDbPath(platformDir, outArg);
       if (outArg)
@@ -4103,15 +4595,15 @@ var exports_propagation = {};
 __export(exports_propagation, {
   propagationCommand: () => propagationCommand
 });
-import { resolve as resolve10 } from "path";
-import { defineCommand as defineCommand6 } from "citty";
+import { resolve as resolve11 } from "path";
+import { defineCommand as defineCommand7 } from "citty";
 var propagationCommand;
 var init_propagation2 = __esm(() => {
   init_constants();
   init_discover();
   init_prompt();
   init__shared();
-  propagationCommand = defineCommand6({
+  propagationCommand = defineCommand7({
     meta: {
       name: "propagation",
       description: "Classify each member repo's relationship to a target requirement (PROP-01). States: MIGRATED_VERIFIED, MIGRATED_UNVERIFIED, ON_PREDECESSOR, ON_OTHER_DOMAIN_REQ, NO_DOMAIN_REFERENCE."
@@ -4151,7 +4643,7 @@ var init_propagation2 = __esm(() => {
         process.exit(EXIT.USAGE);
         return;
       }
-      const platformDir = resolve10(args.platformDir ?? process.cwd());
+      const platformDir = resolve11(args.platformDir ?? process.cwd());
       const outArg = args.out;
       const dbPath = resolveDbPath(platformDir, outArg);
       if (outArg)
@@ -4225,8 +4717,8 @@ var exports_query = {};
 __export(exports_query, {
   queryCommand: () => queryCommand
 });
-import { resolve as resolve11 } from "path";
-import { defineCommand as defineCommand7 } from "citty";
+import { resolve as resolve12 } from "path";
+import { defineCommand as defineCommand8 } from "citty";
 var queryCommand;
 var init_query = __esm(() => {
   init_src();
@@ -4234,7 +4726,7 @@ var init_query = __esm(() => {
   init_discover();
   init_prompt();
   init__shared();
-  queryCommand = defineCommand7({
+  queryCommand = defineCommand8({
     meta: {
       name: "query",
       description: "FTS5 retrieval over requirement text + why. Default LIMIT 10. Query syntax follows SQLite FTS5 MATCH (wrap phrases in double quotes; literal AND/OR/NOT are operators)."
@@ -4291,7 +4783,7 @@ var init_query = __esm(() => {
         process.exit(EXIT.USAGE);
         return;
       }
-      const platformDir = resolve11(args.platformDir ?? process.cwd());
+      const platformDir = resolve12(args.platformDir ?? process.cwd());
       const outArg = args.out;
       const dbPath = resolveDbPath(platformDir, outArg);
       if (outArg)
@@ -4380,8 +4872,8 @@ var exports_relations = {};
 __export(exports_relations, {
   relationsCommand: () => relationsCommand
 });
-import { resolve as resolve12 } from "path";
-import { defineCommand as defineCommand8 } from "citty";
+import { resolve as resolve13 } from "path";
+import { defineCommand as defineCommand9 } from "citty";
 function formatNoRelations(platformDir) {
   return [
     `No Relates links indexed under ${platformDir}.`,
@@ -4394,7 +4886,7 @@ var init_relations = __esm(() => {
   init_constants();
   init_prompt();
   init__shared();
-  relationsCommand = defineCommand8({
+  relationsCommand = defineCommand9({
     meta: {
       name: "relations",
       description: "Render the Relates links between requirements as a mermaid entity diagram. --json emits the sorted relation rows."
@@ -4423,7 +4915,7 @@ var init_relations = __esm(() => {
       }
     },
     async run({ args }) {
-      const platformDir = resolve12(args.platformDir ?? process.cwd());
+      const platformDir = resolve13(args.platformDir ?? process.cwd());
       const outArg = args.out;
       const dbPath = resolveDbPath(platformDir, outArg);
       if (outArg)
@@ -4510,7 +5002,8 @@ function renderProvenance(rows, mode) {
 function decorateRow(row, resolved) {
   const prefix = `  ${row.role}  ${row.issue_id}  ${row.source_file}:${row.line}`;
   if (resolved?.ok && resolved.title && resolved.url) {
-    return `${prefix}  ${resolved.title} [${resolved.status ?? ""}] ${resolved.url}`;
+    const staleMark = resolved.stale ? " (cached \u2014 refresh failed)" : "";
+    return `${prefix}  ${resolved.title} [${resolved.status ?? ""}] ${resolved.url}${staleMark}`;
   }
   return `${prefix}  (${TOKEN_HINT})`;
 }
@@ -4519,7 +5012,12 @@ function renderProvenanceDecorated(rows, resolved, mode) {
   if (mode === "json") {
     return JSON.stringify(sorted.map((r) => {
       const hit = resolved.get(r.issue_id);
-      const resolvedField = hit?.ok === true ? { title: hit.title ?? "", status: hit.status ?? "", url: hit.url ?? "" } : null;
+      const resolvedField = hit?.ok === true ? {
+        title: hit.title ?? "",
+        status: hit.status ?? "",
+        url: hit.url ?? "",
+        stale: hit.stale === true
+      } : null;
       return { ...r, resolved: resolvedField };
     }));
   }
@@ -4553,7 +5051,7 @@ var init_adapter = () => {};
 
 // ../tracker/src/cache.ts
 import { mkdirSync as mkdirSync6 } from "fs";
-import { dirname as dirname9, join as join10 } from "path";
+import { dirname as dirname9, join as join13 } from "path";
 function isFresh(entry, now, ttlMs = CACHE_TTL_MS) {
   const t = Date.parse(entry.fetched_at);
   if (Number.isNaN(t))
@@ -4567,7 +5065,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 join10(platformDir, ".spec-engine", SIDECAR_FILE);
+  return join13(platformDir, ".spec-engine", SIDECAR_FILE);
 }
 async function readCache(platformDir) {
   try {
@@ -4735,7 +5233,13 @@ async function resolveAndCache(rows, platformDir, adapter = makeLinearAdapter(),
   const out = new Map;
   for (const id of uniqueIds) {
     const entry = next[id];
-    out.set(id, entry ? { ok: true, title: entry.title, status: entry.status, url: entry.url } : { ok: false });
+    out.set(id, entry ? {
+      ok: true,
+      title: entry.title,
+      status: entry.status,
+      url: entry.url,
+      stale: !isFresh(entry, now)
+    } : { ok: false });
   }
   return out;
 }
@@ -4748,9 +5252,9 @@ var exports_provenance = {};
 __export(exports_provenance, {
   provenanceCommand: () => provenanceCommand
 });
-import { statSync as statSync4 } from "fs";
-import { resolve as resolve13 } from "path";
-import { defineCommand as defineCommand9 } from "citty";
+import { statSync as statSync5 } from "fs";
+import { resolve as resolve14 } from "path";
+import { defineCommand as defineCommand10 } from "citty";
 function formatNoProvenance(platformDir) {
   return [
     `No provenance links indexed under ${platformDir}.`,
@@ -4767,7 +5271,7 @@ var init_provenance = __esm(() => {
   init_prompt();
   init_resolve();
   init__shared();
-  provenanceCommand = defineCommand9({
+  provenanceCommand = defineCommand10({
     meta: {
       name: "provenance",
       description: "Render the per-requirement provenance matrix (creating/revising issues + backing tests + git pointer). --json emits the deterministically-sorted matrix rows."
@@ -4810,7 +5314,7 @@ var init_provenance = __esm(() => {
       if (issueId && platformArg === undefined) {
         let isDir = false;
         try {
-          isDir = statSync4(resolve13(issueId)).isDirectory();
+          isDir = statSync5(resolve14(issueId)).isDirectory();
         } catch {
           isDir = false;
         }
@@ -4819,7 +5323,7 @@ var init_provenance = __esm(() => {
           issueId = "";
         }
       }
-      const platformDir = resolve13(platformArg ?? process.cwd());
+      const platformDir = resolve14(platformArg ?? process.cwd());
       const outArg = args.out;
       const dbPath = resolveDbPath(platformDir, outArg);
       if (outArg)
@@ -4844,15 +5348,9 @@ var init_provenance = __esm(() => {
   });
 });
 
-// src/authoring/edit.ts
-function localToday() {
-  const d = new Date;
-  return `${d.getFullYear()}-` + `${String(d.getMonth() + 1).padStart(2, "0")}-` + `${String(d.getDate()).padStart(2, "0")}`;
-}
-
 // src/authoring/filerefs.ts
-import { existsSync as existsSync8 } from "fs";
-import { resolve as resolve14 } from "path";
+import { existsSync as existsSync9 } from "fs";
+import { resolve as resolve15 } from "path";
 function extractRefsFromText(s) {
   const out = [];
   for (const m of s.matchAll(FILE_REF_RE)) {
@@ -4863,17 +5361,55 @@ function extractRefsFromText(s) {
   return out;
 }
 function resolveFileRef(platformDir, ref) {
-  const root = resolve14(platformDir);
-  const abs = resolve14(root, ref);
+  const root = resolve15(platformDir);
+  const abs = resolve15(root, ref);
   if (!(abs === root || abs.startsWith(`${root}/`)))
     return false;
-  return existsSync8(abs);
+  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
+import { join as join14 } from "path";
+async function grammarConfig(platformDir, key) {
+  try {
+    const doc = JSON.parse(await Bun.file(join14(platformDir, "spec-engine", key, "SPEC.json")).text());
+    return {
+      grammar: doc.grammar === "ears" ? "ears" : "freeform",
+      severity: doc.grammarSeverity === "error" ? "error" : "warning"
+    };
+  } catch {
+    return { grammar: "freeform", severity: "warning" };
+  }
+}
+async function enforceStatementGrammar(platformDir, key, statement, cmdName) {
+  if (key === "TERM")
+    return;
+  const cfg = await grammarConfig(platformDir, key);
+  if (cfg.grammar !== "ears")
+    return;
+  const result = parseEarsStatement(statement);
+  if (result.ok)
+    return;
+  const message = `${cmdName}: the statement does not match the domain's EARS shape \u2014 ${result.problem}.
+` + `Expected one of:
+  ${result.expected}`;
+  if (cfg.severity === "error") {
+    console.error(`${message}
+(${key} sets grammarSeverity: "error", so the write is refused)`);
+    process.exit(EXIT.USAGE);
+  }
+  console.error(`${message}
+(warning \u2014 written anyway; ${key} sets grammar: "ears")`);
+}
+var init_grammar2 = __esm(() => {
+  init_src();
+  init_constants();
+});
+
 // src/commands/req.ts
 var exports_req = {};
 __export(exports_req, {
@@ -4882,10 +5418,10 @@ __export(exports_req, {
   askLine: () => askLine,
   appendEntry: () => appendEntry
 });
-import { existsSync as existsSync9 } from "fs";
-import { join as join11, resolve as resolve15 } from "path";
+import { existsSync as existsSync10 } from "fs";
+import { join as join15, resolve as resolve16 } from "path";
 import { createInterface as createInterface2 } from "readline";
-import { defineCommand as defineCommand10 } from "citty";
+import { defineCommand as defineCommand11 } from "citty";
 function resolveDomainKey(input, platformDir) {
   const prefix = normalizeDomainKey(input);
   const keys = listDomainKeys(platformDir);
@@ -4919,10 +5455,12 @@ async function authorFromFieldFlags(platformDir, key, nextId, textFlag, opts) {
     requirement,
     why,
     binds,
-    lives
+    lives,
+    issue: (opts.issue ?? "").trim() || undefined
   });
   if (opts.json) {
-    console.log(JSON.stringify({ id: nextId, file: relFile }));
+    const parsed = parseEarsStatement(requirement);
+    console.log(JSON.stringify(parsed.ok ? { id: nextId, file: relFile, clauses: parsed.clauses } : { id: nextId, file: relFile }));
   } else {
     console.log(`appended ${nextId} to ${relFile}`);
   }
@@ -4946,8 +5484,9 @@ function warnUnresolvableRefs(platformDir, fieldValues) {
 }
 async function appendEntry(platformDir, key, id, fields) {
   const relFile = `spec-engine/${key}/SPEC.json`;
-  const specPath = join11(platformDir, "spec-engine", key, "SPEC.json");
-  const domain2 = existsSync9(specPath) ? JSON.parse(await Bun.file(specPath).text()) : null;
+  const specPath = join15(platformDir, "spec-engine", key, "SPEC.json");
+  await enforceStatementGrammar(platformDir, key, fields.requirement, "spec req");
+  const domain2 = existsSync10(specPath) ? JSON.parse(await Bun.file(specPath).text()) : null;
   if (domain2 === null) {
     console.error(`spec req: no domain ${key} (expected ${relFile} under ${platformDir})`);
     process.exit(EXIT.USAGE);
@@ -4962,7 +5501,7 @@ async function appendEntry(platformDir, key, id, fields) {
     supersededBy: null,
     relates: [],
     livesIn: fields.lives ? [fields.lives] : [],
-    issues: []
+    issues: fields.issue ? [{ role: "created", id: fields.issue }] : []
   });
   domain2.requirements = requirements;
   domain2.updated = localToday();
@@ -4988,10 +5527,11 @@ var init_req = __esm(() => {
   init_src();
   init_domains();
   init_filerefs();
+  init_grammar2();
   init_constants();
   init_discover();
   init__shared();
-  reqCommand = defineCommand10({
+  reqCommand = defineCommand11({
     meta: {
       name: "req",
       description: "Author a new requirement interactively (TTY) or print the next unused id (non-TTY)"
@@ -5026,11 +5566,15 @@ var init_req = __esm(() => {
       lives: {
         type: "string",
         description: "Lives in field (only with --text)"
+      },
+      issue: {
+        type: "string",
+        description: "Originating ticket id, recorded as created-provenance on the entry (only with --text; opaque \u2014 never a requirement id)"
       }
     },
     async run({ args }) {
       const input = args.domainPrefix;
-      const platformDir = resolve15(args.platformDir ?? process.cwd());
+      const platformDir = resolve16(args.platformDir ?? process.cwd());
       try {
         assertSpecPlatform(platformDir);
       } catch (e) {
@@ -5039,9 +5583,9 @@ var init_req = __esm(() => {
       const key = resolveDomainKey(input, platformDir);
       const nextId = await nextRequirementId(platformDir, key);
       const textFlag = args.text;
-      const hasFieldFlags = typeof args.why === "string" || typeof args.binds === "string" || typeof args.lives === "string";
+      const hasFieldFlags = typeof args.why === "string" || typeof args.binds === "string" || typeof args.lives === "string" || typeof args.issue === "string";
       if (textFlag === undefined && hasFieldFlags) {
-        console.error("spec req: --why/--binds/--lives require --text (the Requirement field is mandatory)");
+        console.error("spec req: --why/--binds/--lives/--issue require --text (the Requirement field is mandatory)");
         process.exit(EXIT.USAGE);
         return;
       }
@@ -5050,6 +5594,7 @@ var init_req = __esm(() => {
           why: args.why,
           binds: args.binds,
           lives: args.lives,
+          issue: args.issue,
           json: Boolean(args.json)
         });
         return;
@@ -5086,7 +5631,7 @@ var init_req = __esm(() => {
 });
 
 // src/parser/grammar.ts
-var init_grammar = __esm(() => {
+var init_grammar3 = __esm(() => {
   init_src();
 });
 
@@ -5098,16 +5643,16 @@ __export(exports_term, {
   termConfirmCommand: () => termConfirmCommand,
   termCommand: () => termCommand
 });
-import { existsSync as existsSync10 } from "fs";
-import { join as join12, resolve as resolve16 } from "path";
-import { defineCommand as defineCommand11 } from "citty";
+import { existsSync as existsSync11 } from "fs";
+import { join as join16, resolve as resolve17 } from "path";
+import { defineCommand as defineCommand12 } from "citty";
 function parseAliases(raw) {
   if (typeof raw !== "string" || raw.trim() === "")
     return [];
   return raw.split(",").map((s) => s.trim()).filter((s) => s !== "");
 }
-function resolvePlatform(platformDirRaw) {
-  const platformDir = resolve16(platformDirRaw ?? process.cwd());
+function resolvePlatform2(platformDirRaw) {
+  const platformDir = resolve17(platformDirRaw ?? process.cwd());
   try {
     assertSpecPlatform(platformDir);
   } catch (e) {
@@ -5116,16 +5661,16 @@ function resolvePlatform(platformDirRaw) {
   return platformDir;
 }
 async function readTermEnvelope(platformDir, cmd) {
-  const specPath = join12(platformDir, "spec-engine", TERM_KEY, "SPEC.json");
-  if (!existsSync10(specPath)) {
+  const specPath = join16(platformDir, "spec-engine", TERM_KEY2, "SPEC.json");
+  if (!existsSync11(specPath)) {
     console.error(`spec ${cmd}: no TERM domain (expected spec-engine/TERM/SPEC.json under ${platformDir})`);
     process.exit(EXIT.USAGE);
   }
   return JSON.parse(await Bun.file(specPath).text());
 }
 async function appendTermEntry(platformDir, id, fields) {
-  const relFile = `spec-engine/${TERM_KEY}/SPEC.json`;
-  const specPath = join12(platformDir, "spec-engine", TERM_KEY, "SPEC.json");
+  const relFile = `spec-engine/${TERM_KEY2}/SPEC.json`;
+  const specPath = join16(platformDir, "spec-engine", TERM_KEY2, "SPEC.json");
   const domain2 = await readTermEnvelope(platformDir, "term");
   const requirements = Array.isArray(domain2.requirements) ? domain2.requirements : [];
   const entry = {
@@ -5158,11 +5703,11 @@ async function appendTermEntry(platformDir, id, fields) {
   return relFile;
 }
 async function authorOrQuery(opts) {
-  const platformDir = resolvePlatform(opts.platformDirRaw);
-  const nextId = await nextRequirementId(platformDir, TERM_KEY);
+  const platformDir = resolvePlatform2(opts.platformDirRaw);
+  const nextId = await nextRequirementId(platformDir, TERM_KEY2);
   if (opts.def === undefined) {
     if (opts.json) {
-      console.log(JSON.stringify({ domain: TERM_KEY, next_id: nextId }));
+      console.log(JSON.stringify({ domain: TERM_KEY2, next_id: nextId }));
     } else {
       console.log(nextId);
     }
@@ -5188,9 +5733,9 @@ async function authorOrQuery(opts) {
   }
 }
 async function listTerms(platformDirRaw, json) {
-  const platformDir = resolvePlatform(platformDirRaw);
-  const specPath = join12(platformDir, "spec-engine", TERM_KEY, "SPEC.json");
-  const domain2 = existsSync10(specPath) ? JSON.parse(await Bun.file(specPath).text()) : { requirements: [] };
+  const platformDir = resolvePlatform2(platformDirRaw);
+  const specPath = join16(platformDir, "spec-engine", TERM_KEY2, "SPEC.json");
+  const domain2 = existsSync11(specPath) ? JSON.parse(await Bun.file(specPath).text()) : { requirements: [] };
   const requirements = Array.isArray(domain2.requirements) ? domain2.requirements : [];
   const rows = requirements.map((r) => ({
     id: typeof r.id === "string" ? r.id : "",
@@ -5210,18 +5755,18 @@ async function resolveReviseTarget(id, platformDirRaw, defRaw) {
     console.error(`spec term revise: id must be a requirement id (TERM-NNN); got ${id}`);
     process.exit(EXIT.USAGE);
   }
-  if (id.slice(0, id.indexOf("-")) !== TERM_KEY) {
+  if (id.slice(0, id.indexOf("-")) !== TERM_KEY2) {
     console.error(`spec term revise: ${id} is not a TERM id \u2014 revise operates on the TERM store`);
     process.exit(EXIT.USAGE);
   }
-  const platformDir = resolvePlatform(platformDirRaw);
+  const platformDir = resolvePlatform2(platformDirRaw);
   const def = (defRaw ?? "").trim();
   if (def === "") {
     console.error("spec term revise: --def <definition> is required (a non-empty revision)");
     process.exit(EXIT.USAGE);
   }
-  const relFile = `spec-engine/${TERM_KEY}/SPEC.json`;
-  const specPath = join12(platformDir, "spec-engine", TERM_KEY, "SPEC.json");
+  const relFile = `spec-engine/${TERM_KEY2}/SPEC.json`;
+  const specPath = join16(platformDir, "spec-engine", TERM_KEY2, "SPEC.json");
   const domain2 = await readTermEnvelope(platformDir, "term revise");
   const requirements = Array.isArray(domain2.requirements) ? domain2.requirements : [];
   const req = requirements.find((r) => r?.id === id);
@@ -5279,7 +5824,7 @@ async function resolveConfirmTarget(platformDir, termId) {
   const termReqs = Array.isArray(termDomain.requirements) ? termDomain.requirements : [];
   const term = termReqs.find((r) => r?.id === termId);
   if (term === undefined) {
-    console.error(`spec term confirm: no term ${termId} in spec-engine/${TERM_KEY}/SPEC.json`);
+    console.error(`spec term confirm: no term ${termId} in spec-engine/${TERM_KEY2}/SPEC.json`);
     process.exit(EXIT.USAGE);
   }
   const targetPin = typeof termDomain.specVersion === "number" ? termDomain.specVersion : 1;
@@ -5297,8 +5842,8 @@ async function resolveConfirmTarget(platformDir, termId) {
 async function locateCitation(platformDir, reqId, termId) {
   const citKey = reqId.slice(0, reqId.indexOf("-"));
   const relFile = `spec-engine/${citKey}/SPEC.json`;
-  const specPath = join12(platformDir, "spec-engine", citKey, "SPEC.json");
-  if (!existsSync10(specPath)) {
+  const specPath = join16(platformDir, "spec-engine", citKey, "SPEC.json");
+  if (!existsSync11(specPath)) {
     console.error(`spec term confirm: no domain ${citKey} (expected ${relFile} under ${platformDir})`);
     process.exit(EXIT.USAGE);
   }
@@ -5309,6 +5854,12 @@ async function locateCitation(platformDir, reqId, termId) {
     console.error(`spec term confirm: no entry ${reqId} in ${relFile}`);
     process.exit(EXIT.USAGE);
   }
+  const rawStatus = typeof citReq.status === "string" ? citReq.status : "";
+  const statusLc = rawStatus.toLowerCase();
+  if (statusLc !== "active" && statusLc !== "draft") {
+    console.error(`spec term confirm: ${reqId} is ${rawStatus} \u2014 only Active/Draft entries re-pin a citation (a superseded entry is history)`);
+    process.exit(EXIT.USAGE);
+  }
   const cites = Array.isArray(citReq.cites) ? citReq.cites : [];
   const cite = cites.find((c) => c?.term === termId);
   if (cite === undefined) {
@@ -5323,11 +5874,11 @@ async function confirmCitation(opts) {
     console.error(`spec term confirm: req id must be a requirement id (KEY-NNN); got ${reqId}`);
     process.exit(EXIT.USAGE);
   }
-  if (!ID_RE.test(termId) || termId.slice(0, termId.indexOf("-")) !== TERM_KEY) {
+  if (!ID_RE.test(termId) || termId.slice(0, termId.indexOf("-")) !== TERM_KEY2) {
     console.error(`spec term confirm: ${termId} is not a TERM id \u2014 confirm re-pins a TERM citation`);
     process.exit(EXIT.USAGE);
   }
-  const platformDir = resolvePlatform(opts.platformDirRaw);
+  const platformDir = resolvePlatform2(opts.platformDirRaw);
   const { targetId, targetPin } = await resolveConfirmTarget(platformDir, termId);
   const { citDomain, specPath, relFile, cite } = await locateCitation(platformDir, reqId, termId);
   cite.term = targetId;
@@ -5347,18 +5898,18 @@ async function confirmCitation(opts) {
     console.log(`confirmed ${reqId} cites ${targetId} @${targetPin} in ${relFile}`);
   }
 }
-var TERM_KEY = "TERM", termListCommand, termReviseCommand, termConfirmCommand, termCommand;
+var TERM_KEY2 = "TERM", termListCommand, termReviseCommand, termConfirmCommand, termCommand;
 var init_term = __esm(() => {
   init_src();
   init_domains();
   init_constants();
   init_discover();
   init_pipeline();
-  init_grammar();
+  init_grammar3();
   init_sqlite();
   init__shared();
   init_req();
-  termListCommand = defineCommand11({
+  termListCommand = defineCommand12({
     meta: {
       name: "list",
       description: "List the glossary TERM entries (id, name, status), sorted by id"
@@ -5378,7 +5929,7 @@ var init_term = __esm(() => {
       await listTerms(args.platformDir, Boolean(args.json));
     }
   });
-  termReviseCommand = defineCommand11({
+  termReviseCommand = defineCommand12({
     meta: {
       name: "revise",
       description: "Revise a TERM's definition IN PLACE (same id) and BUMP the envelope specVersion \u2014 the drift signal (A2). Requirements have no such op."
@@ -5412,7 +5963,7 @@ var init_term = __esm(() => {
       });
     }
   });
-  termConfirmCommand = defineCommand11({
+  termConfirmCommand = defineCommand12({
     meta: {
       name: "confirm",
       description: "Re-pin a requirement's TERM citation to the term's current version (clears TERM_DRIFT); re-points to the successor when the term is superseded (clears SUPERSEDED_TERM_REFERENCED)."
@@ -5447,7 +5998,7 @@ var init_term = __esm(() => {
       });
     }
   });
-  termCommand = defineCommand11({
+  termCommand = defineCommand12({
     meta: {
       name: "term",
       description: "Author a glossary TERM (spec term <name> --def <definition>), list terms (spec term list), or revise a definition in place (spec term revise TERM-NNN)"
@@ -5456,271 +6007,68 @@ var init_term = __esm(() => {
       name: {
         type: "positional",
         required: true,
-        description: "The term's headword, or the literal `list` / `revise` verb. Without --def (author form), prints the next unused TERM id."
-      },
-      platformDir: {
-        type: "positional",
-        required: false,
-        description: "Platform directory (author/list), or \u2014 after `revise` \u2014 the TERM-NNN id to revise, or \u2014 after `confirm` \u2014 the citing KEY-NNN id"
-      },
-      extra: {
-        type: "positional",
-        required: false,
-        description: "After `revise <TERM-NNN>`: the platform directory (default: cwd). After `confirm <KEY-NNN>`: the TERM-NNN id."
-      },
-      extra2: {
-        type: "positional",
-        required: false,
-        description: "After `confirm <KEY-NNN> <TERM-NNN>`: the platform directory (default: cwd)"
-      },
-      def: { type: "string", description: "The term's definition (stored in the statement field)" },
-      text: { type: "string", description: "Alias for --def (the definition)" },
-      aliases: { type: "string", description: "Comma-separated synonyms \u2192 aliases[]" },
-      section: { type: "string", description: "GLOSSARY.md layout bucket (Wave F)" },
-      noBump: { type: "boolean", description: "revise: do not bump the envelope specVersion" },
-      json: {
-        type: "boolean",
-        description: "Author: { id, file } (or { domain, next_id } as an id query). list: the entries array. revise: { id, file, spec_version }."
-      }
-    },
-    async run({ args }) {
-      const verb = args.name;
-      const def = args.def ?? args.text;
-      const json = Boolean(args.json);
-      if (verb === "list") {
-        await listTerms(args.platformDir, json);
-        return;
-      }
-      if (verb === "revise") {
-        await reviseTerm({
-          id: args.platformDir ?? "",
-          platformDirRaw: args.extra,
-          def,
-          noBump: Boolean(args.noBump),
-          json
-        });
-        return;
-      }
-      if (verb === "confirm") {
-        await confirmCitation({
-          reqId: args.platformDir ?? "",
-          termId: args.extra ?? "",
-          platformDirRaw: args.extra2,
-          json
-        });
-        return;
-      }
-      await authorOrQuery({
-        name: verb,
-        platformDirRaw: args.platformDir,
-        def,
-        aliasesRaw: args.aliases,
-        section: args.section,
-        json
-      });
-    }
-  });
-});
-
-// src/commands/glossary.ts
-var exports_glossary = {};
-__export(exports_glossary, {
-  parseGlossary: () => parseGlossary,
-  glossaryCommand: () => glossaryCommand,
-  generateGlossary: () => generateGlossary
-});
-import { existsSync as existsSync11, readFileSync as readFileSync2 } from "fs";
-import { join as join13, resolve as resolve17 } from "path";
-import { defineCommand as defineCommand12 } from "citty";
-function parseGlossary(md) {
-  const terms = [];
-  let section = null;
-  let buf = null;
-  const flush = () => {
-    if (buf === null)
-      return;
-    const m = buf.match(/^\*\*(.+?)\*\*/);
-    if (m) {
-      const remainder = buf.slice(m[0].length);
-      const statement = remainder.replace(/^ \u2014 /, "").trim();
-      terms.push({ term: m[1], statement, section });
-    }
-    buf = null;
-  };
-  for (const line of md.split(`
-`)) {
-    if (line.startsWith("## ")) {
-      flush();
-      section = line.slice(3).trim();
-    } else if (line.startsWith("- ")) {
-      flush();
-      buf = line.slice(2);
-    } else if (buf !== null) {
-      if (line.trim() === "")
-        flush();
-      else
-        buf += ` ${line.trim()}`;
-    }
-  }
-  flush();
-  return terms;
-}
-function generateGlossary(terms) {
-  const parts = ["# Glossary", "", GLOSSARY_INTRO];
-  let section;
-  for (const t of terms) {
-    if (t.section !== section) {
-      section = t.section;
-      if (section !== null && section !== undefined) {
-        parts.push("", `## ${section}`, "");
-      }
-    }
-    parts.push(`- **${t.term}** \u2014 ${t.statement}`);
-  }
-  return `${parts.join(`
-`)}
-`;
-}
-function resolvePlatform2(platformDirRaw) {
-  const platformDir = resolve17(platformDirRaw ?? process.cwd());
-  try {
-    assertSpecPlatform(platformDir);
-  } catch (e) {
-    handleNotAPlatform(e);
-  }
-  return platformDir;
-}
-function readStoreTerms(platformDir) {
-  const specPath = join13(platformDir, "spec-engine", TERM_KEY2, "SPEC.json");
-  if (!existsSync11(specPath))
-    return [];
-  const domain2 = JSON.parse(readFileSync2(specPath, "utf8"));
-  const reqs = Array.isArray(domain2.requirements) ? domain2.requirements : [];
-  return reqs.filter((r) => String(r.status).toLowerCase() === "active").sort((a, b) => String(a.id) < String(b.id) ? -1 : String(a.id) > String(b.id) ? 1 : 0).map((r) => ({
-    term: String(r.term ?? ""),
-    statement: String(r.statement ?? ""),
-    section: r.section ?? null
-  }));
-}
-function glossaryPath(platformDir) {
-  return join13(platformDir, "GLOSSARY.md");
-}
-async function migrateGlossary(platformDir, json) {
-  const relFile = `spec-engine/${TERM_KEY2}/SPEC.json`;
-  const specPath = join13(platformDir, "spec-engine", TERM_KEY2, "SPEC.json");
-  if (!existsSync11(specPath)) {
-    console.error(`spec glossary: no TERM domain (expected ${relFile} under ${platformDir})`);
-    process.exit(EXIT.USAGE);
-  }
-  const domain2 = JSON.parse(readFileSync2(specPath, "utf8"));
-  const existing = Array.isArray(domain2.requirements) ? domain2.requirements : [];
-  if (existing.length > 0) {
-    console.error(`spec glossary: TERM domain already holds ${existing.length} entries \u2014 migration skipped`);
-    if (json)
-      console.log(JSON.stringify({ migrated: 0, skipped: true }));
-    else
-      console.log("migration skipped (TERM domain not empty)");
-    return;
-  }
-  const gPath = glossaryPath(platformDir);
-  if (!existsSync11(gPath)) {
-    console.error(`spec glossary: no GLOSSARY.md to migrate (expected ${gPath})`);
-    process.exit(EXIT.USAGE);
-  }
-  const parsed = parseGlossary(readFileSync2(gPath, "utf8"));
-  domain2.requirements = parsed.map((t, i) => ({
-    id: `${TERM_KEY2}-${String(i + 1).padStart(3, "0")}`,
-    status: "active",
-    statement: t.statement,
-    term: t.term,
-    why: null,
-    supersedes: null,
-    supersededBy: null,
-    relates: [],
-    livesIn: [],
-    issues: [],
-    aliases: [],
-    cites: [],
-    changedAtVersion: 1,
-    section: t.section
-  }));
-  domain2.updated = localToday();
-  const res = await validateAndWrite(specPath, domain2, relFile);
-  if (!res.ok) {
-    for (const diag of res.diagnostics)
-      console.error(`spec glossary: ${diag.detail}`);
-    process.exit(EXIT.USAGE);
-  }
-  const count = parsed.length;
-  if (json)
-    console.log(JSON.stringify({ migrated: count, file: relFile }));
-  else
-    console.log(`migrated ${count} terms into ${relFile}`);
-}
-async function writeGlossary(platformDir, json) {
-  const terms = readStoreTerms(platformDir);
-  await Bun.write(glossaryPath(platformDir), generateGlossary(terms));
-  if (json)
-    console.log(JSON.stringify({ generated: terms.length, file: "GLOSSARY.md" }));
-  else
-    console.log(`generated GLOSSARY.md from ${terms.length} terms`);
-}
-function checkGlossary(platformDir, json) {
-  const generated = generateGlossary(readStoreTerms(platformDir));
-  const gPath = glossaryPath(platformDir);
-  const committed = existsSync11(gPath) ? readFileSync2(gPath, "utf8") : "";
-  if (generated === committed) {
-    if (json)
-      console.log(JSON.stringify({ ok: true }));
-    else
-      console.error("glossary round-trip: OK (committed GLOSSARY.md == generated)");
-    return;
-  }
-  console.error("glossary drift: committed GLOSSARY.md != generated from the TERM store");
-  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);
-}
-var TERM_KEY2 = "TERM", GLOSSARY_INTRO = `Canonical names for Spec Engine concepts. When prose, code comments, diagnostics, or
-docs need one of these ideas, use the term below \u2014 not a synonym. Terms are ordered
-by the data model, outside-in.`, glossaryCommand;
-var init_glossary = __esm(() => {
-  init_src();
-  init_constants();
-  init_discover();
-  init__shared();
-  glossaryCommand = defineCommand12({
-    meta: {
-      name: "glossary",
-      description: "Generate GLOSSARY.md from the TERM store (byte-stable); --migrate parses GLOSSARY.md into TERM-001..N; --check fails on drift (committed != generated)"
-    },
-    args: {
+        description: "The term's headword, or the literal `list` / `revise` verb. Without --def (author form), prints the next unused TERM id."
+      },
       platformDir: {
         type: "positional",
         required: false,
-        description: "Platform directory containing spec-engine/ (default: cwd)"
+        description: "Platform directory (author/list), or \u2014 after `revise` \u2014 the TERM-NNN id to revise, or \u2014 after `confirm` \u2014 the citing KEY-NNN id"
       },
-      migrate: {
-        type: "boolean",
-        description: "One-time: parse the committed GLOSSARY.md into TERM-001..N (idempotent-skip)"
+      extra: {
+        type: "positional",
+        required: false,
+        description: "After `revise <TERM-NNN>`: the platform directory (default: cwd). After `confirm <KEY-NNN>`: the TERM-NNN id."
       },
-      check: {
-        type: "boolean",
-        description: "Fail (exit 1) if the committed GLOSSARY.md differs from the generated output"
+      extra2: {
+        type: "positional",
+        required: false,
+        description: "After `confirm <KEY-NNN> <TERM-NNN>`: the platform directory (default: cwd)"
       },
-      json: { type: "boolean", description: "Emit a JSON result instead of the text summary" }
+      def: { type: "string", description: "The term's definition (stored in the statement field)" },
+      text: { type: "string", description: "Alias for --def (the definition)" },
+      aliases: { type: "string", description: "Comma-separated synonyms \u2192 aliases[]" },
+      section: { type: "string", description: "GLOSSARY.md layout bucket (Wave F)" },
+      noBump: { type: "boolean", description: "revise: do not bump the envelope specVersion" },
+      json: {
+        type: "boolean",
+        description: "Author: { id, file } (or { domain, next_id } as an id query). list: the entries array. revise: { id, file, spec_version }."
+      }
     },
     async run({ args }) {
-      const platformDir = resolvePlatform2(args.platformDir);
+      const verb = args.name;
+      const def = args.def ?? args.text;
       const json = Boolean(args.json);
-      if (args.migrate) {
-        await migrateGlossary(platformDir, json);
-      } else if (args.check) {
-        checkGlossary(platformDir, json);
-      } else {
-        await writeGlossary(platformDir, json);
+      if (verb === "list") {
+        await listTerms(args.platformDir, json);
+        return;
+      }
+      if (verb === "revise") {
+        await reviseTerm({
+          id: args.platformDir ?? "",
+          platformDirRaw: args.extra,
+          def,
+          noBump: Boolean(args.noBump),
+          json
+        });
+        return;
+      }
+      if (verb === "confirm") {
+        await confirmCitation({
+          reqId: args.platformDir ?? "",
+          termId: args.extra ?? "",
+          platformDirRaw: args.extra2,
+          json
+        });
+        return;
       }
+      await authorOrQuery({
+        name: verb,
+        platformDirRaw: args.platformDir,
+        def,
+        aliasesRaw: args.aliases,
+        section: args.section,
+        json
+      });
     }
   });
 });
@@ -5775,7 +6123,7 @@ __export(exports_supersede, {
   supersedeCommand: () => supersedeCommand
 });
 import { existsSync as existsSync12 } from "fs";
-import { join as join14, resolve as resolve18 } from "path";
+import { join as join17, resolve as resolve18 } from "path";
 import { defineCommand as defineCommand13 } from "citty";
 async function resolveSupersedeTarget(id, platformDir) {
   if (!ID_RE.test(id)) {
@@ -5789,7 +6137,7 @@ async function resolveSupersedeTarget(id, platformDir) {
   }
   const key = id.slice(0, id.indexOf("-"));
   const relFile = `spec-engine/${key}/SPEC.json`;
-  const specPath = join14(platformDir, "spec-engine", key, "SPEC.json");
+  const specPath = join17(platformDir, "spec-engine", key, "SPEC.json");
   if (!existsSync12(specPath)) {
     console.error(`spec supersede: no domain ${key} (expected ${relFile} under ${platformDir})`);
     process.exit(EXIT.USAGE);
@@ -5848,10 +6196,18 @@ function resolveSuccessorTermFields(args, req) {
   const aliases = typeof rawAliases === "string" ? rawAliases.split(",").map((s) => s.trim()).filter((s) => s !== "") : Array.isArray(req.aliases) ? req.aliases.map((a) => String(a)) : [];
   return { term, aliases };
 }
-function applySupersedeEdit(target, newId, requirement, why, lives, noBump, termFields) {
-  const { domain: domain2, requirements, req } = target;
+function flipPredecessor(req, newId, issue) {
   req.status = "superseded";
   req.supersededBy = newId;
+  if (issue) {
+    const issues = Array.isArray(req.issues) ? req.issues : [];
+    issues.push({ role: "supersedes-via", id: issue });
+    req.issues = issues;
+  }
+}
+function applySupersedeEdit(target, newId, requirement, why, lives, noBump, termFields, issue) {
+  const { domain: domain2, requirements, req } = target;
+  flipPredecessor(req, newId, issue);
   const successor = {
     id: newId,
     status: "active",
@@ -5861,7 +6217,7 @@ function applySupersedeEdit(target, newId, requirement, why, lives, noBump, term
     supersededBy: null,
     relates: [],
     livesIn: lives === "" ? [] : [lives],
-    issues: [],
+    issues: issue ? [{ role: "created", id: issue }] : [],
     changedAtVersion: 1
   };
   if (termFields !== null) {
@@ -5900,10 +6256,11 @@ var supersedeCommand;
 var init_supersede = __esm(() => {
   init_src();
   init_domains();
+  init_grammar2();
   init_constants();
   init_discover();
   init_domainJson();
-  init_grammar();
+  init_grammar3();
   init__shared();
   init_req();
   supersedeCommand = defineCommand13({
@@ -5950,6 +6307,10 @@ var init_supersede = __esm(() => {
         type: "boolean",
         description: "Do not bump the envelope specVersion"
       },
+      issue: {
+        type: "string",
+        description: "Ticket that caused this supersession \u2014 recorded as supersedes-via on the predecessor and created on the successor (opaque provenance)"
+      },
       json: {
         type: "boolean",
         description: "Emit { old_id, new_id, file, spec_version, retag } as JSON instead of the text summary"
@@ -5960,11 +6321,12 @@ var init_supersede = __esm(() => {
       const platformDir = resolve18(args.platformDir ?? process.cwd());
       const target = await resolveSupersedeTarget(id, platformDir);
       const requirement = await resolveSuccessorText(args, id);
+      await enforceStatementGrammar(platformDir, target.key, requirement, "spec supersede");
       const { why, lives, binds } = resolveSuccessorFields(args, target.req);
       warnUnresolvableRefs(platformDir, [requirement, why, binds, lives]);
       const newId = await nextRequirementId(platformDir, target.key);
       const termFields = target.key === "TERM" ? resolveSuccessorTermFields(args, target.req) : null;
-      const newVersion = applySupersedeEdit(target, newId, requirement, why, lives, Boolean(args.noBump), termFields);
+      const newVersion = applySupersedeEdit(target, newId, requirement, why, lives, Boolean(args.noBump), termFields, (args.issue ?? "").trim() || undefined);
       const res = await validateAndWrite(target.specPath, target.domain, target.relFile);
       if (!res.ok) {
         for (const diag of res.diagnostics) {
@@ -5998,18 +6360,133 @@ var init_supersede = __esm(() => {
   });
 });
 
+// src/commands/deprecate.ts
+var exports_deprecate = {};
+__export(exports_deprecate, {
+  deprecateCommand: () => deprecateCommand
+});
+import { existsSync as existsSync13 } from "fs";
+import { join as join18, resolve as resolve19 } from "path";
+import { defineCommand as defineCommand14 } from "citty";
+async function resolveDeprecateTarget(platformDir, id) {
+  const key = id.slice(0, id.indexOf("-"));
+  const relFile = `spec-engine/${key}/SPEC.json`;
+  const specPath = join18(platformDir, "spec-engine", key, "SPEC.json");
+  if (!existsSync13(specPath)) {
+    console.error(`spec deprecate: no domain ${key} (expected ${relFile} under ${platformDir})`);
+    process.exit(EXIT.USAGE);
+  }
+  const domain2 = JSON.parse(await Bun.file(specPath).text());
+  const requirements = Array.isArray(domain2.requirements) ? domain2.requirements : [];
+  const req = requirements.find((r) => r?.id === id);
+  if (req === undefined) {
+    console.error(`spec deprecate: no entry ${id} in ${relFile}`);
+    process.exit(EXIT.USAGE);
+  }
+  const statusLc = (typeof req.status === "string" ? req.status : "").toLowerCase();
+  if (statusLc === "deprecated" || statusLc === "retired") {
+    console.error(`spec deprecate: ${id} is already deprecated`);
+    process.exit(EXIT.USAGE);
+  }
+  if (statusLc !== "active" && statusLc !== "draft") {
+    console.error(`spec deprecate: ${id} is ${req.status} \u2014 only Active/Draft entries deprecate (a superseded entry is already history)`);
+    process.exit(EXIT.USAGE);
+  }
+  return { domain: domain2, req, specPath, relFile };
+}
+var deprecateCommand;
+var init_deprecate = __esm(() => {
+  init_src();
+  init_constants();
+  init_discover();
+  init_grammar3();
+  init__shared();
+  deprecateCommand = defineCommand14({
+    meta: {
+      name: "deprecate",
+      description: "Mark a requirement end-of-life with a recorded reason (a requirement is never deleted)"
+    },
+    args: {
+      id: {
+        type: "positional",
+        required: true,
+        description: "Requirement id to deprecate (KEY-NNN)"
+      },
+      platformDir: {
+        type: "positional",
+        required: false,
+        description: "Platform directory (default: cwd)"
+      },
+      reason: {
+        type: "string",
+        description: "Why this requirement is end-of-life (required \u2014 the durable record)"
+      },
+      json: {
+        type: "boolean",
+        description: "Print { id, file, reason, sites } instead of text"
+      }
+    },
+    async run({ args }) {
+      const id = args.id;
+      const platformDir = resolve19(args.platformDir ?? process.cwd());
+      const reason = (args.reason ?? "").trim();
+      if (!ID_RE.test(id)) {
+        console.error(`spec deprecate: id must be a requirement id (KEY-NNN); got ${id}`);
+        process.exit(EXIT.USAGE);
+      }
+      if (reason === "") {
+        console.error("spec deprecate: --reason is required \u2014 the reason is the durable record of why this requirement ended");
+        process.exit(EXIT.USAGE);
+      }
+      try {
+        assertSpecPlatform(platformDir);
+      } catch (e) {
+        handleNotAPlatform(e);
+      }
+      const { domain: domain2, req, specPath, relFile } = await resolveDeprecateTarget(platformDir, id);
+      req.status = "deprecated";
+      req.deprecatedReason = reason;
+      domain2.updated = localToday();
+      const res = await validateAndWrite(specPath, domain2, relFile);
+      if (!res.ok) {
+        for (const diag of res.diagnostics)
+          console.error(`spec deprecate: ${diag.detail}`);
+        process.exit(EXIT.USAGE);
+      }
+      const tags = await reindexAndListTags(platformDir, id);
+      const sites = tags.map(({ req_id, repo, file, line, kind, level }) => ({
+        req_id,
+        repo,
+        file,
+        line,
+        kind,
+        level: level ?? null
+      }));
+      if (args.json) {
+        console.log(JSON.stringify({ id, file: relFile, reason, sites }));
+        return;
+      }
+      console.log(`deprecated ${id} in ${relFile} \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"));
+      }
+    }
+  });
+});
+
 // src/commands/move.ts
 var exports_move = {};
 __export(exports_move, {
   moveCommand: () => moveCommand
 });
-import { existsSync as existsSync13 } from "fs";
-import { join as join15, resolve as resolve19 } from "path";
-import { defineCommand as defineCommand14 } from "citty";
+import { existsSync as existsSync14 } from "fs";
+import { join as join19, resolve as resolve20 } from "path";
+import { defineCommand as defineCommand15 } from "citty";
 async function loadDomainSide(platformDir, key) {
   const relFile = `spec-engine/${key}/SPEC.json`;
-  const specPath = join15(platformDir, "spec-engine", key, "SPEC.json");
-  if (!existsSync13(specPath))
+  const specPath = join19(platformDir, "spec-engine", key, "SPEC.json");
+  if (!existsSync14(specPath))
     return null;
   const domain2 = JSON.parse(await Bun.file(specPath).text());
   const requirements = Array.isArray(domain2.requirements) ? domain2.requirements : [];
@@ -6068,6 +6545,15 @@ function resolveSuccessorFields2(args, req) {
     lives: (args.lives ?? srcLives).trim()
   };
 }
+async function assertMovableStatement(platformDir, id, targetKey, statement, args) {
+  if (statement === "") {
+    console.error(`spec move: ${id} has an empty Requirement \u2014 cannot move a blank statement`);
+    process.exit(EXIT.USAGE);
+  }
+  if (typeof args.text === "string") {
+    await enforceStatementGrammar(platformDir, targetKey, statement, "spec move");
+  }
+}
 function resolveMoveVersion(domain2, key, noBump) {
   domain2.updated = localToday();
   if (key !== "TERM") {
@@ -6123,15 +6609,16 @@ var moveCommand;
 var init_move = __esm(() => {
   init_src();
   init_domains();
+  init_grammar2();
   init_constants();
   init_discover();
   init_pipeline();
   init_domainJson();
-  init_grammar();
+  init_grammar3();
   init_sqlite();
   init__shared();
   init_req();
-  moveCommand = defineCommand14({
+  moveCommand = defineCommand15({
     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."
@@ -6176,13 +6663,10 @@ var init_move = __esm(() => {
     async run({ args }) {
       const id = args.id;
       const rawTargetKey = args.newDomain;
-      const platformDir = resolve19(args.platformDir ?? process.cwd());
+      const platformDir = resolve20(args.platformDir ?? process.cwd());
       const target = await resolveMoveTarget(id, rawTargetKey, platformDir);
       const fields = resolveSuccessorFields2(args, target.req);
-      if (fields.statement === "") {
-        console.error(`spec move: ${id} has an empty Requirement \u2014 cannot move a blank statement`);
-        process.exit(EXIT.USAGE);
-      }
+      await assertMovableStatement(platformDir, id, target.target.key, fields.statement, args);
       warnUnresolvableRefs(platformDir, [fields.statement, fields.why, fields.lives]);
       const newId = await nextRequirementId(platformDir, target.target.key);
       const { sourceVersion, targetVersion } = applyMoveEdit(target, newId, fields, Boolean(args.noBump));
@@ -6234,17 +6718,18 @@ var exports_amend = {};
 __export(exports_amend, {
   amendCommand: () => amendCommand
 });
-import { existsSync as existsSync14 } from "fs";
-import { join as join16, resolve as resolve20 } from "path";
-import { defineCommand as defineCommand15 } from "citty";
+import { existsSync as existsSync15 } from "fs";
+import { join as join20, resolve as resolve21 } from "path";
+import { defineCommand as defineCommand16 } from "citty";
 function validateAmendFields(args) {
   const hasText = typeof args.text === "string";
+  const hasIssue = typeof args.issue === "string" && args.issue.trim() !== "";
   const hasWhy = typeof args.why === "string";
   const hasLives = typeof args.lives === "string";
   const hasBinds = typeof args.binds === "string";
   const hasTerm = typeof args.term === "string";
   const hasAliases = typeof args.aliases === "string";
-  if (!hasText && !hasWhy && !hasLives && !hasTerm && !hasAliases) {
+  if (!hasText && !hasWhy && !hasLives && !hasTerm && !hasAliases && !hasIssue) {
     console.error("spec amend: nothing to amend \u2014 pass at least one of --text / --why / --lives / --term / --aliases");
     process.exit(EXIT.USAGE);
   }
@@ -6256,13 +6741,13 @@ function validateAmendFields(args) {
     console.error("spec amend: --term must be a non-empty headword");
     process.exit(EXIT.USAGE);
   }
-  return { hasText, hasWhy, hasLives, hasBinds, hasTerm, hasAliases };
+  return { hasText, hasWhy, hasLives, hasBinds, hasTerm, hasAliases, hasIssue };
 }
 async function locateAmendEntry(platformDir, id) {
   const key = id.slice(0, id.indexOf("-"));
   const relFile = `spec-engine/${key}/SPEC.json`;
-  const specPath = join16(platformDir, "spec-engine", key, "SPEC.json");
-  if (!existsSync14(specPath)) {
+  const specPath = join20(platformDir, "spec-engine", key, "SPEC.json");
+  if (!existsSync15(specPath)) {
     console.error(`spec amend: no domain ${key} (expected ${relFile} under ${platformDir})`);
     process.exit(EXIT.USAGE);
   }
@@ -6324,6 +6809,12 @@ function applyAmendMutations(req, args, fields) {
     fieldsChanged.push("term");
     refValues.push(v);
   }
+  if (fields.hasIssue) {
+    const issues = Array.isArray(req.issues) ? req.issues : [];
+    issues.push({ role: "amends-via", id: args.issue.trim() });
+    req.issues = issues;
+    fieldsChanged.push("issue");
+  }
   if (fields.hasAliases) {
     const raw = args.aliases.trim();
     req.aliases = raw === "" ? [] : raw.split(",").map((s) => s.trim()).filter((s) => s !== "");
@@ -6334,12 +6825,13 @@ function applyAmendMutations(req, args, fields) {
 var amendCommand;
 var init_amend = __esm(() => {
   init_src();
+  init_grammar2();
   init_constants();
   init_discover();
-  init_grammar();
+  init_grammar3();
   init__shared();
   init_req();
-  amendCommand = defineCommand15({
+  amendCommand = defineCommand16({
     meta: {
       name: "amend",
       description: "Revise an unshipped requirement's fields in place (same id, no specVersion bump). Supersede shipped truth instead."
@@ -6362,6 +6854,10 @@ var init_amend = __esm(() => {
         description: "Binds value (validated for @-refs; not persisted in JSON \u2014 STOR-01)"
       },
       lives: { type: "string", description: "New Lives in (livesIn) field value" },
+      issue: {
+        type: "string",
+        description: "Ticket that motivated this amendment \u2014 recorded as amends-via provenance (opaque, never a requirement id)"
+      },
       term: { type: "string", description: "New TERM headword (term field; TERM ids)" },
       aliases: {
         type: "string",
@@ -6379,7 +6875,7 @@ var init_amend = __esm(() => {
         process.exit(EXIT.USAGE);
         return;
       }
-      const platformDir = resolve20(args.platformDir ?? process.cwd());
+      const platformDir = resolve21(args.platformDir ?? process.cwd());
       try {
         assertSpecPlatform(platformDir);
       } catch (e) {
@@ -6392,6 +6888,10 @@ var init_amend = __esm(() => {
       if (statusLc === "active") {
         await assertUnshipped(platformDir, id);
       }
+      if (fields.hasText) {
+        const key = id.slice(0, id.indexOf("-"));
+        await enforceStatementGrammar(platformDir, key, args.text.trim(), "spec amend");
+      }
       const { fieldsChanged, refValues } = applyAmendMutations(req, args, fields);
       warnUnresolvableRefs(platformDir, refValues);
       domain2.updated = localToday();
@@ -6428,13 +6928,14 @@ Target domain: ${opts.domain} (no charter/scope recorded \u2014 check placement
     opts.brief,
     "",
     "Steps:",
-    "1. One requirement per TESTABLE PROMISE \u2014 never one per ticket; a brief fans out.",
-    "2. Placement: concept-wins per the domain charter above; run `spec query <text>` first to dedup.",
-    "3. Draft each to the GUARD template: `<command/surface> <promise> when <condition>` \u2014 name the subject explicitly.",
-    "4. Cold-read self-check: the statement must stand alone (restate referenced rules; no sibling free-riding; glossary terms only); timeless; observable inputs\u2192outputs; the why carries the failure mode. See spec-engine/TAXONOMY.md \xA74.10 for the eight-point standard.",
-    "5. Present the full batch for approval BEFORE writing.",
-    '6. Mint each approved requirement: `spec req <domain> --text "\u2026" --why "\u2026" --lives "\u2026"`.',
-    "7. The originating ticket is `Issues:` PROVENANCE ONLY \u2014 never a requirement id, never a code tag."
+    "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.",
+    "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"`.',
+    "8. The originating ticket is provenance only \u2014 never a requirement id, never a code tag."
   ].join(`
 `);
 }
@@ -6571,7 +7072,7 @@ var init_mcp = __esm(() => {
   init_domains();
   init_constants();
   init_pipeline();
-  init_grammar();
+  init_grammar3();
   init_sqlite();
 });
 
@@ -6580,15 +7081,15 @@ var exports_mcp = {};
 __export(exports_mcp, {
   mcpCommand: () => mcpCommand
 });
-import { resolve as resolve21 } from "path";
+import { resolve as resolve22 } from "path";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { defineCommand as defineCommand16 } from "citty";
+import { defineCommand as defineCommand17 } from "citty";
 var mcpCommand;
 var init_mcp2 = __esm(() => {
   init_discover();
   init_mcp();
   init__shared();
-  mcpCommand = defineCommand16({
+  mcpCommand = defineCommand17({
     meta: {
       name: "mcp",
       description: "Serve Spec Engine as an MCP (Model Context Protocol) server over stdio \u2014 agent-native query/resolve/check/report tools."
@@ -6601,7 +7102,7 @@ var init_mcp2 = __esm(() => {
       }
     },
     async run({ args }) {
-      const platformDir = resolve21(args.platformDir ?? process.cwd());
+      const platformDir = resolve22(args.platformDir ?? process.cwd());
       try {
         assertSpecPlatform(platformDir);
       } catch (e) {
@@ -6619,9 +7120,9 @@ var exports_resolve = {};
 __export(exports_resolve, {
   resolveCommand: () => resolveCommand
 });
-import { statSync as statSync5 } from "fs";
-import { join as join17, relative, resolve as resolve22, sep as sep3 } from "path";
-import { defineCommand as defineCommand17 } from "citty";
+import { statSync as statSync6 } from "fs";
+import { join as join21, relative, resolve as resolve23, sep as sep3 } from "path";
+import { defineCommand as defineCommand18 } from "citty";
 function classifyArg(a) {
   if (a.startsWith("--")) {
     const eq = a.indexOf("=");
@@ -6656,10 +7157,10 @@ function splitFilesAndPlatformDir(positionals, fallbackPlatformDir) {
   let lastIsPlatformDir = false;
   let lastIsDirWithoutSpecEngine = false;
   try {
-    const resolved = resolve22(last);
-    if (statSync5(resolved).isDirectory()) {
+    const resolved = resolve23(last);
+    if (statSync6(resolved).isDirectory()) {
       try {
-        if (statSync5(join17(resolved, "spec-engine")).isDirectory()) {
+        if (statSync6(join21(resolved, "spec-engine")).isDirectory()) {
           lastIsPlatformDir = true;
         } else {
           lastIsDirWithoutSpecEngine = true;
@@ -6753,7 +7254,7 @@ async function dispatchReverseQuery(reqArg, resolved, args) {
   }
   await runReverseQuery({
     reqId: reqArg,
-    platformDir: resolve22(lone ?? process.cwd()),
+    platformDir: resolve23(lone ?? process.cwd()),
     outArg: args.out,
     json: Boolean(args.json),
     fresh: Boolean(args.fresh),
@@ -6763,7 +7264,7 @@ async function dispatchReverseQuery(reqArg, resolved, args) {
 function normalizeFileInputs(files, platformDir) {
   const normalized = [];
   for (const input of files) {
-    const rel = relative(platformDir, resolve22(platformDir, input));
+    const rel = relative(platformDir, resolve23(platformDir, input));
     const segments = rel.split(sep3);
     if (rel === "" || rel === "." || segments[0] === "..") {
       console.error(`spec resolve: file path must be inside platformDir: ${input}`);
@@ -6781,7 +7282,7 @@ var init_resolve2 = __esm(() => {
   init_prompt();
   init__shared();
   VALUE_FLAGS = new Set(["--out", "-o", "--platformDir", "--req"]);
-  resolveCommand = defineCommand17({
+  resolveCommand = defineCommand18({
     meta: {
       name: "resolve",
       description: "Return the requirements tagged in the given files (RSLV-01). 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."
@@ -6836,7 +7337,7 @@ var init_resolve2 = __esm(() => {
         process.exit(EXIT.USAGE);
         return;
       }
-      const platformDir = resolve22(resolved.platformDir ?? process.cwd());
+      const platformDir = resolve23(resolved.platformDir ?? process.cwd());
       const outArg = args.out;
       const dbPath = resolveDbPath(platformDir, outArg);
       if (outArg)
@@ -6905,6 +7406,18 @@ function classifyGate(input) {
       pinned_spec_version: pin
     };
   }
+  if (req.status === "Deprecated") {
+    return {
+      pass: false,
+      reason: "DEPRECATED",
+      repo: requestedRepoName,
+      req_id: requestedReqId,
+      detail: `Requirement ${requestedReqId} is Deprecated \u2014 it is end-of-life with no successor; do not build against it`,
+      status: req.status,
+      changed_at_version: req.changed_at_version,
+      pinned_spec_version: pin
+    };
+  }
   if (req.changed_at_version > pin) {
     return {
       pass: false,
@@ -6942,9 +7455,9 @@ var exports_gate = {};
 __export(exports_gate, {
   gateCommand: () => gateCommand
 });
-import { existsSync as existsSync15, mkdirSync as mkdirSync7 } from "fs";
-import { dirname as dirname10, join as join18, resolve as resolve23 } from "path";
-import { defineCommand as defineCommand18 } from "citty";
+import { existsSync as existsSync16, mkdirSync as mkdirSync7 } from "fs";
+import { dirname as dirname10, join as join22, resolve as resolve24 } from "path";
+import { defineCommand as defineCommand19 } from "citty";
 function isEpipe(e) {
   if (e === null || typeof e !== "object")
     return false;
@@ -6958,8 +7471,8 @@ function resolveGateArgs(args) {
     console.error("spec gate: <repo> and <reqId> are required (e.g., spec gate api BILLING-009)");
     process.exit(EXIT.USAGE);
   }
-  const platformDir = resolve23(args.platformDir ?? process.cwd());
-  const hasSpecEngineDir = existsSync15(join18(platformDir, "spec-engine"));
+  const platformDir = resolve24(args.platformDir ?? process.cwd());
+  const hasSpecEngineDir = existsSync16(join22(platformDir, "spec-engine"));
   if (!hasSpecEngineDir) {
     console.error(formatNotASpecPlatform(platformDir));
     process.exit(EXIT.USAGE);
@@ -6998,7 +7511,7 @@ var init_gate = __esm(() => {
   init_prompt();
   init_sqlite();
   init__shared();
-  gateCommand = defineCommand18({
+  gateCommand = defineCommand19({
     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."
@@ -7084,26 +7597,8 @@ var init_gate = __esm(() => {
   });
 });
 
-// src/guard/directives.ts
-function scanApprovals(text) {
-  const out = [];
-  for (const line of text.split(`
-`)) {
-    const m = APPROVE_RE.exec(line);
-    if (m !== null) {
-      out.push({ req_id: m[1], reason: m[2].trim() });
-    }
-  }
-  return out;
-}
-var APPROVE_RE;
-var init_directives = __esm(() => {
-  APPROVE_RE = /@spec\s+approve\s+([A-Z][A-Z0-9]*-\d+)\s+(\S.*)$/;
-});
-
 // src/guard/collect.ts
-import { existsSync as existsSync16 } from "fs";
-import { join as join19 } from "path";
+import { join as join23 } from "path";
 function isIgnored(path) {
   return isPathIgnored(path);
 }
@@ -7160,7 +7655,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(join19(canonicalDir, rel)).text();
+    const text = await Bun.file(join23(canonicalDir, rel)).text();
     for (const r of parseReqs(text)) {
       ids.add(r.id);
       if (r.status.toLowerCase() === "active")
@@ -7181,20 +7676,6 @@ function tallyWorktreeTags(storage2) {
   }
   return { implCount, verifyCount };
 }
-async function collectApprovals(platformDir, changed) {
-  const approved = new Set;
-  for (const entry of changed) {
-    if (entry.status === "D")
-      continue;
-    const abs = join19(platformDir, entry.path);
-    if (!existsSync16(abs))
-      continue;
-    const text = await Bun.file(abs).text();
-    for (const a of scanApprovals(text))
-      approved.add(a.req_id);
-  }
-  return approved;
-}
 async function collectFacts(platformDir, ref, storage2) {
   const changed = gitDiffNameStatus(platformDir, ref);
   const specPaths = changed.filter((e) => isSpecFile(e.path)).map((e) => e.path);
@@ -7202,9 +7683,8 @@ async function collectFacts(platformDir, ref, storage2) {
   const deletedSpecFiles = changed.filter((e) => e.status === "D" && isSpecFile(e.path)).map((e) => e.path);
   const base = collectBaseReqs2(platformDir, ref, specPaths);
   const baseTags = collectBaseTags(platformDir, ref, codePaths);
-  const worktree = await collectWorktreeReqs(join19(platformDir, CANONICAL_SPECS_DIR));
+  const worktree = await collectWorktreeReqs(join23(platformDir, CANONICAL_SPECS_DIR));
   const counts = tallyWorktreeTags(storage2);
-  const approved = await collectApprovals(platformDir, changed);
   return {
     baseReqs: base.reqs,
     baseReqPath: base.path,
@@ -7215,7 +7695,6 @@ async function collectFacts(platformDir, ref, storage2) {
     worktreeSupersedesTargets: worktree.supersedesTargets,
     worktreeImplCount: counts.implCount,
     worktreeVerifyCount: counts.verifyCount,
-    approved,
     deletedSpecFiles
   };
 }
@@ -7225,7 +7704,6 @@ var init_collect = __esm(() => {
   init_constants();
   init_fs();
   init_tags();
-  init_directives();
   CODE_EXTS = new Set(DEFAULT_EXTS);
 });
 
@@ -7263,7 +7741,7 @@ function deletesClause(losses) {
   return joinClauses(parts);
 }
 function requirementBlock(reqId, losses) {
-  return `${STOP} spec-guard: ${reqId} is Active and this change deletes ${deletesClause(losses)}. ` + "Requirements are superseded, never deleted. " + `Either run \`spec supersede ${reqId}\` with a successor, ` + "or stop and ask the user whether this requirement should die.";
+  return `${STOP} spec-guard: ${reqId} is Active and this change deletes ${deletesClause(losses)}. ` + "Requirements are superseded, never deleted. " + `Either run \`spec supersede ${reqId}\` with a successor, or run ` + `\`spec deprecate ${reqId} --reason "..."\` to end it with a recorded reason.`;
 }
 function fileBlock(loss) {
   return `${STOP} spec-guard: the canonical spec file ${loss.file} was deleted. ` + "Requirements are superseded, never deleted \u2014 restore the file or supersede " + "its requirements into another domain before removing it.";
@@ -7314,7 +7792,17 @@ function reqDeletedLoss(base, f) {
     req_id: base.id,
     file: f.baseReqPath.get(base.id) ?? "",
     line: 0,
-    detail: `${base.id} was Active at the ref but is absent from the working-tree spec with no approved supersession`
+    detail: `${base.id} was Active at the ref but is absent from the working-tree spec and was not superseded \u2014 a requirement is never deleted`
+  };
+}
+function historyRemovedLoss(base, f) {
+  const display = base.status.charAt(0).toUpperCase() + base.status.slice(1).toLowerCase();
+  return {
+    kind: "REQUIREMENT_REMOVED",
+    req_id: base.id,
+    file: f.baseReqPath.get(base.id) ?? "",
+    line: 0,
+    detail: `${base.id} was ${display} at the ref but is absent from the working-tree spec \u2014 a requirement is never deleted, and its history is the record`
   };
 }
 function implLostLoss(id, site) {
@@ -7345,18 +7833,16 @@ function specFileDeletedLoss(path) {
   };
 }
 function reqDeletedFor(base, f) {
-  if (!isActive(base.status))
-    return null;
-  if (f.approved.has(base.id))
-    return null;
   if (f.worktreeReqIds.has(base.id))
     return null;
+  if (!isActive(base.status))
+    return historyRemovedLoss(base, f);
   if (isSuperseded(base, f))
     return null;
   return reqDeletedLoss(base, f);
 }
 function lastTagGone(id, count, f) {
-  return !f.approved.has(id) && f.worktreeActiveIds.has(id) && count === 0;
+  return f.worktreeActiveIds.has(id) && count === 0;
 }
 function classifyLosses(f) {
   const out = [];
@@ -7383,14 +7869,14 @@ var exports_guard = {};
 __export(exports_guard, {
   guardCommand: () => guardCommand
 });
-import { resolve as resolve24 } from "path";
-import { defineCommand as defineCommand19 } from "citty";
+import { resolve as resolve25 } from "path";
+import { defineCommand as defineCommand20 } from "citty";
 var guardCommand;
 var init_guard = __esm(() => {
   init_constants();
   init_collect();
   init__shared();
-  guardCommand = defineCommand19({
+  guardCommand = defineCommand20({
     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."
@@ -7411,7 +7897,7 @@ var init_guard = __esm(() => {
       }
     },
     async run({ args }) {
-      const platformDir = resolve24(args.platformDir ?? process.cwd());
+      const platformDir = resolve25(args.platformDir ?? process.cwd());
       const ref = args.against ?? "HEAD";
       const jsonMode = Boolean(args.json);
       if (!gitRefResolves(platformDir, ref)) {
@@ -7482,6 +7968,9 @@ function link(href, key, label, active) {
 function comingSoon(label) {
   return html`<span class="sidebar-link disabled" aria-disabled="true"><span class="sidebar-dot"></span><span class="sidebar-label">${label}<span class="soon">coming soon</span></span></span>`;
 }
+function flagged(feature, href, key, label, active) {
+  return featureEnabled(feature) ? link(href, key, label, active) : comingSoon(label);
+}
 function navBar(active = "") {
   return html`<nav class="sidebar">
   <a href="/" class="sidebar-brand">${clampMark}<span>Spec Engine</span></a>
@@ -7490,22 +7979,22 @@ function navBar(active = "") {
       <div class="sidebar-group-label">Registry</div>
       ${link("/", "coverage", "Coverage", active)}
       ${link("/requirements", "requirements", "Requirements", active)}
-      ${comingSoon("Glossary")}
+      ${flagged("glossary", "/glossary", "glossary", "Glossary", active)}
     </div>
     <div class="sidebar-group">
       <div class="sidebar-group-label">Trace</div>
-      ${comingSoon("Relations")}
-      ${comingSoon("Provenance")}
+      ${flagged("relations", "/relations", "relations", "Relations", active)}
+      ${flagged("provenance", "/provenance", "provenance", "Provenance", active)}
     </div>
     <div class="sidebar-group">
       <div class="sidebar-group-label">Workspace</div>
-      ${comingSoon("Query")}
-      ${comingSoon("Editor")}
+      ${flagged("query", "/query", "query", "Query", active)}
+      ${flagged("editor", "/editor", "editor", "Editor", active)}
     </div>
     <div class="sidebar-group">
       <div class="sidebar-group-label">System</div>
       ${link("/setup", "setup", "Setup", active)}
-      ${comingSoon("Logs")}
+      ${flagged("logs", "/logs", "logs", "Logs", active)}
     </div>
   </div>
   <div class="sidebar-footer">
@@ -7516,6 +8005,7 @@ function navBar(active = "") {
 }
 var clampMark;
 var init_nav = __esm(() => {
+  init_src();
   clampMark = html`<svg width="22" height="22" viewBox="0 0 64 64" fill="none" aria-hidden="true">
     <path d="M25 13 H13 V51 H25" stroke="var(--fg)" stroke-width="6" />
     <path d="M39 13 H51 V51 H39" stroke="var(--fg)" stroke-width="6" />
@@ -9053,7 +9543,7 @@ var init_components = __esm(() => {
     Active: "ACTIVE",
     Superseded: "SUPERSEDED",
     Draft: "DRAFT",
-    Retired: "DEPRECATED"
+    Deprecated: "DEPRECATED"
   };
 });
 
@@ -9184,8 +9674,8 @@ function mountCoverage(app) {
     const reqs = await apiJson(app, "/api/requirements");
     const titleOf = new Map(reqs.map((r) => [r.id, r.text]));
     const showAll = c.req.query("all") === "1";
-    const visible = showAll ? rows : rows.filter((r) => r.req_status !== "Superseded" && r.req_status !== "Retired");
-    const hiddenCount = new Set(rows.filter((r) => r.req_status === "Superseded" || r.req_status === "Retired").map((r) => r.req_id)).size;
+    const visible = showAll ? rows : rows.filter((r) => r.req_status !== "Superseded" && r.req_status !== "Deprecated");
+    const hiddenCount = new Set(rows.filter((r) => r.req_status === "Superseded" || r.req_status === "Deprecated").map((r) => r.req_id)).size;
     const { repos, domains } = pivot(visible);
     const reqCount = domains.reduce((n, d) => n + d.reqs.length, 0);
     const reportRows = await apiJson(app, "/api/report");
@@ -9216,7 +9706,7 @@ function mountCoverage(app) {
         <span class="legend-sep"></span>
         <span class="legend-item">${requirementStatusBadge("Active")}</span>
         ${showAll ? html4`<span class="legend-item">${requirementStatusBadge("Superseded")}</span>
-        <span class="legend-item">${requirementStatusBadge("Retired")}</span>` : ""}
+        <span class="legend-item">${requirementStatusBadge("Deprecated")}</span>` : ""}
         <span class="panel-spacer"></span>
         <span class="req-controls">
           ${showAll ? html4`<a class="req-btn status-toggle" href="/">Hide superseded &amp; retired</a>` : html4`<a class="req-btn status-toggle" href="/?all=1">Show superseded &amp; retired${hiddenCount > 0 ? html4` (${hiddenCount})` : ""}</a>`}
@@ -9391,6 +9881,8 @@ async function renderResult(res) {
 }
 function mountEditor(app) {
   app.get("/editor", (c) => {
+    if (!featureEnabled("editor"))
+      return c.html(comingSoonDoc("editor", "Editor"));
     const body = html5`
       ${navBar("editor")}
       <div class="eyebrow">/ Editor</div>
@@ -9445,6 +9937,8 @@ function mountEditor(app) {
     return c.html(page("Editor", body));
   });
   app.post("/editor/create", editorBodyLimit, async (c) => {
+    if (!featureEnabled("editor"))
+      return c.html(rejectPage(featureDisabledMessage("editor")), 404);
     if (crossOriginRejected(c))
       return c.html(rejectPage("cross-origin request rejected"), 403);
     const form = await c.req.parseBody();
@@ -9467,6 +9961,8 @@ function mountEditor(app) {
     return c.html(await renderResult(res));
   });
   app.post("/editor/amend", editorBodyLimit, async (c) => {
+    if (!featureEnabled("editor"))
+      return c.html(rejectPage(featureDisabledMessage("editor")), 404);
     if (crossOriginRejected(c))
       return c.html(rejectPage("cross-origin request rejected"), 403);
     const form = await c.req.parseBody();
@@ -9489,6 +9985,7 @@ function mountEditor(app) {
 var styleTag4, MAX_EDITOR_BODY_BYTES, editorBodyLimit;
 var init_editor = __esm(() => {
   init_src();
+  init_components();
   init_nav();
   init_styles();
   styleTag4 = raw4(`<style>${styles_default}</style>`);
@@ -9571,7 +10068,7 @@ var init_propagation3 = __esm(() => {
 import { html as html7, raw as raw6 } from "hono/html";
 function mountProvenance(app) {
   app.get("/provenance", async (c) => {
-    if (!PROVENANCE_ENABLED)
+    if (!featureEnabled("provenance"))
       return c.html(comingSoonDoc("provenance", "Provenance matrix"));
     const text = await apiText(app, "/api/provenance?resolve=1");
     let body;
@@ -9604,8 +10101,9 @@ function mountProvenance(app) {
 </html>`);
   });
 }
-var styleTag6, PROVENANCE_ENABLED = false;
+var styleTag6;
 var init_provenance2 = __esm(() => {
+  init_src();
   init_components();
   init_data();
   init_nav();
@@ -9617,7 +10115,7 @@ var init_provenance2 = __esm(() => {
 import { html as html8, raw as raw7 } from "hono/html";
 function mountQuery(app) {
   app.get("/query", async (c) => {
-    if (!QUERY_ENABLED)
+    if (!featureEnabled("query"))
       return c.html(comingSoonDoc("query", "Query"));
     const q = (c.req.query("q") ?? "").trim();
     const form = html8`
@@ -9703,8 +10201,9 @@ function mountQuery(app) {
 </html>`);
   });
 }
-var styleTag7, QUERY_ENABLED = false;
+var styleTag7;
 var init_query2 = __esm(() => {
+  init_src();
   init_components();
   init_data();
   init_nav();
@@ -9716,7 +10215,7 @@ var init_query2 = __esm(() => {
 import { html as html9, raw as raw8 } from "hono/html";
 function mountRelations(app) {
   app.get("/relations", async (c) => {
-    if (!RELATIONS_ENABLED)
+    if (!featureEnabled("relations"))
       return c.html(comingSoonDoc("relations", "Relates graph"));
     const rows = await apiJson(app, "/api/relations");
     let body;
@@ -9754,8 +10253,9 @@ function mountRelations(app) {
 </html>`);
   });
 }
-var styleTag8, RELATIONS_ENABLED = false;
+var styleTag8;
 var init_relations2 = __esm(() => {
+  init_src();
   init_components();
   init_data();
   init_nav();
@@ -9829,7 +10329,7 @@ function verPill(r, versioned) {
   return html10`<span class="ver-pill ${versioned ? "versioned" : ""}" title="domain spec version (envelope)">v${r.spec_version}</span>`;
 }
 function chainVerLabel(v) {
-  const dead = v.status === "Superseded" || v.status === "Retired";
+  const dead = v.status === "Superseded" || v.status === "Deprecated";
   if (dead && v.superseded_at_version != null) {
     return html10`<span class="chain-ver">superseded at v${v.superseded_at_version}</span>`;
   }
@@ -9972,8 +10472,8 @@ function mountRequirements(app) {
     const reqs = await apiJson(app, "/api/requirements");
     const coverage = await apiJson(app, "/api/coverage");
     const showAll = c.req.query("all") === "1";
-    const listed = showAll ? reqs : reqs.filter((r) => r.status !== "Superseded" && r.status !== "Retired");
-    const hiddenCount = reqs.filter((r) => r.status === "Superseded" || r.status === "Retired").length;
+    const listed = showAll ? reqs : reqs.filter((r) => r.status !== "Superseded" && r.status !== "Deprecated");
+    const hiddenCount = reqs.filter((r) => r.status === "Superseded" || r.status === "Deprecated").length;
     const tagLists = await Promise.all(listed.map((r) => apiJson(app, `/api/resolve?req=${encodeURIComponent(r.id)}`)));
     const tagsById = new Map(listed.map((r, i) => [r.id, tagLists[i] ?? []]));
     const { domains, defaultId } = buildDomains(reqs, listed, coverage, tagsById);
@@ -10249,7 +10749,7 @@ var init_server = __esm(() => {
 
 // src/server/api.ts
 import { existsSync as existsSync17 } from "fs";
-import { join as join20 } from "path";
+import { join as join24 } from "path";
 function hasTraversalSegment(p) {
   return p.split(/[/\\]/).some((seg) => seg === "..");
 }
@@ -10356,7 +10856,7 @@ function resolveCreateTarget(c, platformDir, body) {
     return { ok: false, res: c.json({ error: "unknown domain key" }, 400) };
   }
   const relFile = `spec-engine/${key}/SPEC.json`;
-  const specPath = join20(platformDir, "spec-engine", key, "SPEC.json");
+  const specPath = join24(platformDir, "spec-engine", key, "SPEC.json");
   if (!existsSync17(specPath))
     return { ok: false, res: c.json({ error: "not found" }, 404) };
   return { ok: true, key, relFile, specPath };
@@ -10376,7 +10876,7 @@ function buildRequirement(body, id) {
 }
 async function locateRequirement(platformDir, id) {
   for (const key of listDomainKeys(platformDir)) {
-    const specPath = join20(platformDir, "spec-engine", key, "SPEC.json");
+    const specPath = join24(platformDir, "spec-engine", key, "SPEC.json");
     const relFile = `spec-engine/${key}/SPEC.json`;
     let domain2;
     try {
@@ -10406,6 +10906,40 @@ function applyAmendFields(req, body) {
     req.livesIn = toLivesIn(body.livesIn);
   return true;
 }
+function hasAmendFields(body) {
+  return typeof body.statement === "string" || "why" in body || "livesIn" in body;
+}
+async function amendGateRejection(c, platformDir, storage2, id, req) {
+  const rawStatus = typeof req.status === "string" ? req.status : "";
+  const statusLc = rawStatus.toLowerCase();
+  if (statusLc !== "active" && statusLc !== "draft") {
+    return c.json({
+      error: `${id} is ${rawStatus} \u2014 only Active/Draft entries amend (a superseded entry is history; supersede its successor instead)`
+    }, 409);
+  }
+  if (statusLc === "active") {
+    await runIndex({ platformDir, storage: storage2 });
+    const bound = storage2.listTags({ req_id: id }).filter((t) => t.kind === "implements" || t.kind === "verifies");
+    if (bound.length > 0) {
+      const site = bound[0];
+      return c.json({
+        error: `${id} is shipped \u2014 ${bound.length} code tag(s) bind it (e.g. ${site.file}:${site.line}). A bound requirement is immutable; supersede it with a successor instead of amending in place.`
+      }, 409);
+    }
+  }
+  return null;
+}
+function searchFtsResponse(c, storage2, q, limit) {
+  try {
+    return c.json(storage2.searchFts(q, limit));
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    if (msg.startsWith(FTS_SYNTAX_ERROR_PREFIX)) {
+      return c.json({ error: "FTS5 grammar error; wrap phrases in double quotes" }, 400);
+    }
+    throw e;
+  }
+}
 function parseQueryLimit(c, rawLimit) {
   if (!POSITIVE_INT_RE.test(rawLimit)) {
     return {
@@ -10449,6 +10983,9 @@ function mountApi(app, storage2, platformDir = process.cwd()) {
     return row ? c.json(row) : c.json({ error: "not found" }, 404);
   }));
   app.post("/api/requirements", guarded(async function createRequirement(c) {
+    if (!featureEnabled("editor")) {
+      return c.json({ error: featureDisabledMessage("editor") }, 404);
+    }
     const originReject = rejectCrossOrigin(c);
     if (originReject)
       return originReject;
@@ -10483,6 +11020,9 @@ function mountApi(app, storage2, platformDir = process.cwd()) {
     });
   }));
   app.put("/api/requirements/:id", guarded(async function amendRequirement(c) {
+    if (!featureEnabled("editor")) {
+      return c.json({ error: featureDisabledMessage("editor") }, 404);
+    }
     const originReject = rejectCrossOrigin(c);
     if (originReject)
       return originReject;
@@ -10501,9 +11041,13 @@ function mountApi(app, storage2, platformDir = process.cwd()) {
       if (found.kind === "invalid") {
         return c.json({ error: "INVALID_DOMAIN_FILE", detail: `${found.relFile} is not valid JSON` }, 400);
       }
-      if (!applyAmendFields(found.req, body)) {
+      if (!hasAmendFields(body)) {
         return c.json({ error: "nothing to amend \u2014 provide statement, why, or livesIn" }, 400);
       }
+      const gateReject = await amendGateRejection(c, platformDir, storage2, id, found.req);
+      if (gateReject)
+        return gateReject;
+      applyAmendFields(found.req, body);
       found.domain.updated = localToday();
       const res = await validateAndWrite(found.specPath, found.domain, found.relFile);
       if (!res.ok) {
@@ -10515,6 +11059,9 @@ function mountApi(app, storage2, platformDir = process.cwd()) {
   }));
   app.get("/api/propagation/:id", guarded((c) => c.json(storage2.propagationFor(c.req.param("id") ?? ""))));
   app.get("/api/query", guarded((c) => {
+    if (!featureEnabled("query")) {
+      return c.json({ error: featureDisabledMessage("query") }, 404);
+    }
     const q = (c.req.query("q") ?? "").trim();
     if (!q) {
       return c.json({ error: "q is required (non-empty FTS5 MATCH query)" }, 400);
@@ -10523,17 +11070,12 @@ function mountApi(app, storage2, platformDir = process.cwd()) {
     const parsedLimit = parseQueryLimit(c, rawLimit);
     if (!parsedLimit.ok)
       return parsedLimit.res;
-    try {
-      return c.json(storage2.searchFts(q, parsedLimit.limit));
-    } catch (e) {
-      const msg = e instanceof Error ? e.message : String(e);
-      if (msg.startsWith(FTS_SYNTAX_ERROR_PREFIX)) {
-        return c.json({ error: "FTS5 grammar error; wrap phrases in double quotes" }, 400);
-      }
-      throw e;
-    }
+    return searchFtsResponse(c, storage2, q, parsedLimit.limit);
   }));
   app.get("/api/relations", guarded((c) => {
+    if (!featureEnabled("relations")) {
+      return c.json({ error: featureDisabledMessage("relations") }, 404);
+    }
     const format = c.req.query("format");
     if (format !== undefined && format !== "mermaid") {
       return c.json({ error: 'format must be "mermaid" when provided' }, 400);
@@ -10545,6 +11087,9 @@ function mountApi(app, storage2, platformDir = process.cwd()) {
     return c.json(sortRelations(rows));
   }));
   app.get("/api/provenance", guarded(async (c) => {
+    if (!featureEnabled("provenance")) {
+      return c.json({ error: featureDisabledMessage("provenance") }, 404);
+    }
     const resolveParam = c.req.query("resolve");
     if (resolveParam !== undefined && resolveParam !== "1") {
       return c.json({ error: 'resolve must be "1" when provided' }, 400);
@@ -10556,7 +11101,15 @@ function mountApi(app, storage2, platformDir = process.cwd()) {
     }
     return c.json(rows);
   }));
-  app.get("/api/provenance/:issue", guarded((c) => c.json(storage2.provenanceByIssue(c.req.param("issue") ?? ""))));
+  app.get("/api/provenance/by-issue", guarded((c) => {
+    if (!featureEnabled("provenance")) {
+      return c.json({ error: featureDisabledMessage("provenance") }, 404);
+    }
+    const issue = (c.req.query("issue") ?? "").trim();
+    if (issue === "")
+      return c.json({ error: "issue is required (non-empty)" }, 400);
+    return c.json(storage2.provenanceByIssue(issue));
+  }));
   app.get("/api/resolve", guarded((c) => {
     const reqParam = c.req.query("req");
     if (reqParam !== undefined)
@@ -10597,8 +11150,8 @@ __export(exports_serve, {
   composeServeApp: () => composeServeApp
 });
 import { existsSync as existsSync18, mkdirSync as mkdirSync8 } from "fs";
-import { dirname as dirname11, resolve as resolve25 } from "path";
-import { defineCommand as defineCommand20 } from "citty";
+import { dirname as dirname11, resolve as resolve26 } from "path";
+import { defineCommand as defineCommand21 } from "citty";
 import { Hono as Hono2 } from "hono";
 function composeServeApp(storage2, platformDir = process.cwd()) {
   const app = new Hono2;
@@ -10646,7 +11199,7 @@ var init_serve = __esm(() => {
   init_api();
   init_sqlite();
   init__shared();
-  serveCommand = defineCommand20({
+  serveCommand = defineCommand21({
     meta: {
       name: "serve",
       description: "Run the local webapp. Binds 127.0.0.1 on --port (loopback only \u2014 no --host). --probe is the SERV-04 asset-embedding smoke."
@@ -10692,7 +11245,7 @@ var init_serve = __esm(() => {
         process.exit(EXIT.USAGE);
         return;
       }
-      const platformDir = resolve25(args.platformDir ?? process.cwd());
+      const platformDir = resolve26(args.platformDir ?? process.cwd());
       const outArg = args.out;
       const dbPath = resolveDbPath(platformDir, outArg);
       if (outArg)
@@ -10743,18 +11296,20 @@ var init_serve = __esm(() => {
 // src/commands/docs.ts
 var exports_docs = {};
 __export(exports_docs, {
+  runProbe: () => runProbe2,
   resolveDocsRootFrom: () => resolveDocsRootFrom,
   resolveDocsRoot: () => resolveDocsRoot,
+  exitNoDocsRoot: () => exitNoDocsRoot,
   docsCommand: () => docsCommand,
   createDocsFetchHandler: () => createDocsFetchHandler
 });
-import { existsSync as existsSync19, statSync as statSync6 } from "fs";
-import { join as join21, normalize, sep as sep4 } from "path";
+import { existsSync as existsSync19, statSync as statSync7 } from "fs";
+import { join as join25, normalize, sep as sep4 } from "path";
 import { fileURLToPath } from "url";
-import { defineCommand as defineCommand21 } from "citty";
+import { defineCommand as defineCommand22 } from "citty";
 function resolveDocsRootFrom(candidates) {
   for (const candidate of candidates) {
-    if (existsSync19(join21(candidate, "index.html")))
+    if (existsSync19(join25(candidate, "index.html")))
       return candidate;
   }
   return null;
@@ -10778,16 +11333,16 @@ function createDocsFetchHandler(root) {
     if (pathname.includes("\x00")) {
       return new Response("Bad request", { status: 400 });
     }
-    const target = normalize(join21(normalRoot, pathname));
+    const target = normalize(join25(normalRoot, pathname));
     if (target !== normalRoot && !target.startsWith(rootPrefix)) {
       return new Response("Not found", { status: 404 });
     }
-    for (const candidate of [target, join21(target, "index.html"), `${target}.html`]) {
-      if (existsSync19(candidate) && statSync6(candidate).isFile()) {
+    for (const candidate of [target, join25(target, "index.html"), `${target}.html`]) {
+      if (existsSync19(candidate) && statSync7(candidate).isFile()) {
         return new Response(Bun.file(candidate));
       }
     }
-    const notFoundPage = join21(normalRoot, "404.html");
+    const notFoundPage = join25(normalRoot, "404.html");
     if (existsSync19(notFoundPage)) {
       return new Response(Bun.file(notFoundPage), { status: 404 });
     }
@@ -10822,10 +11377,14 @@ async function runProbe2(root) {
   server.stop();
   process.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.");
+  process.exit(EXIT.USAGE);
+}
 var docsCommand;
 var init_docs2 = __esm(() => {
   init_constants();
-  docsCommand = defineCommand21({
+  docsCommand = defineCommand22({
     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."
@@ -10844,8 +11403,7 @@ var init_docs2 = __esm(() => {
     async run({ args }) {
       const root = resolveDocsRoot();
       if (!root) {
-        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.");
-        process.exit(EXIT.USAGE);
+        exitNoDocsRoot();
         return;
       }
       if (args.probe) {
@@ -10887,10 +11445,10 @@ __export(exports___smoke, {
   schemaSmokeCommand: () => schemaSmokeCommand,
   schemaMismatchSmokeCommand: () => schemaMismatchSmokeCommand
 });
-import { defineCommand as defineCommand22 } from "citty";
+import { defineCommand as defineCommand23 } from "citty";
 var schemaSmokeCommand, schemaMismatchSmokeCommand;
 var init___smoke = __esm(() => {
-  schemaSmokeCommand = defineCommand22({
+  schemaSmokeCommand = defineCommand23({
     meta: {
       name: "__schema-smoke",
       description: "(hidden CI) open a fresh DB, exec DDL, assert the schema shape",
@@ -10933,7 +11491,7 @@ var init___smoke = __esm(() => {
       console.log("__schema-smoke OK");
     }
   });
-  schemaMismatchSmokeCommand = defineCommand22({
+  schemaMismatchSmokeCommand = defineCommand23({
     meta: {
       name: "__schema-mismatch-smoke",
       description: "(hidden CI) corrupt _schema_version, re-open, assert silent rebuild",
@@ -10958,11 +11516,11 @@ var init___smoke = __esm(() => {
 });
 
 // src/cli.ts
-import { defineCommand as defineCommand23, runMain, showUsage } from "citty";
+import { defineCommand as defineCommand24, runMain, showUsage } from "citty";
 // package.json
 var package_default = {
   name: "@spec-engine/spec-engine",
-  version: "0.1.1",
+  version: "0.2.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",
@@ -10972,6 +11530,10 @@ var package_default = {
   files: [
     "dist"
   ],
+  publishConfig: {
+    access: "public",
+    provenance: true
+  },
   engines: {
     bun: ">=1.3.0"
   },
@@ -11010,7 +11572,7 @@ var package_default = {
 };
 
 // src/cli.ts
-var main = defineCommand23({
+var main = defineCommand24({
   meta: {
     name: "spec",
     version: package_default.version,
@@ -11030,6 +11592,7 @@ var main = defineCommand23({
     term: () => Promise.resolve().then(() => (init_term(), exports_term)).then((m) => m.termCommand),
     glossary: () => Promise.resolve().then(() => (init_glossary(), exports_glossary)).then((m) => m.glossaryCommand),
     supersede: () => Promise.resolve().then(() => (init_supersede(), exports_supersede)).then((m) => m.supersedeCommand),
+    deprecate: () => Promise.resolve().then(() => (init_deprecate(), exports_deprecate)).then((m) => m.deprecateCommand),
     move: () => Promise.resolve().then(() => (init_move(), exports_move)).then((m) => m.moveCommand),
     amend: () => Promise.resolve().then(() => (init_amend(), exports_amend)).then((m) => m.amendCommand),
     mcp: () => Promise.resolve().then(() => (init_mcp2(), exports_mcp)).then((m) => m.mcpCommand),