@outcomeeng/spx 0.2.0 → 0.3.1

package/dist/cli.js

@@ -7,6 +7,227 @@ import {
 import { Command } from "commander";
 import { createRequire as createRequire2 } from "module";
 
+// src/audit/paths.ts
+import { existsSync } from "fs";
+import { relative, resolve } from "path";
+function validatePaths(verdict, projectRoot) {
+  const defects = [];
+  const root = resolve(projectRoot);
+  for (const gate of verdict.gates) {
+    for (const finding of gate.findings) {
+      checkPath(finding.spec_file, root, defects);
+      checkPath(finding.test_file, root, defects);
+    }
+  }
+  return defects;
+}
+function checkPath(filePath, root, defects) {
+  if (!filePath) return;
+  const rel = relative(root, resolve(root, filePath));
+  if (rel.startsWith("..")) {
+    defects.push(`path escapes project root: ${filePath}`);
+    return;
+  }
+  if (!existsSync(resolve(root, filePath))) {
+    defects.push(`missing file: ${filePath}`);
+  }
+}
+
+// src/audit/reader.ts
+import { readFile } from "fs/promises";
+import { XMLParser, XMLValidator } from "fast-xml-parser";
+var ARRAY_TAGS = /* @__PURE__ */ new Set(["gate", "finding"]);
+var PARSER_OPTIONS = {
+  ignoreAttributes: false,
+  attributeNamePrefix: "@_",
+  parseTagValue: false,
+  parseAttributeValue: false,
+  isArray: (name) => ARRAY_TAGS.has(name)
+};
+async function readVerdictFile(filePath) {
+  let xml;
+  try {
+    xml = await readFile(filePath, "utf-8");
+  } catch (cause) {
+    throw new Error(`Failed to read verdict file: ${filePath}`, { cause });
+  }
+  const validation = XMLValidator.validate(xml);
+  if (validation !== true) {
+    throw new Error(
+      `Malformed XML in verdict file: ${filePath}: ${validation.err.msg}`
+    );
+  }
+  const parser = new XMLParser(PARSER_OPTIONS);
+  const parsed = parser.parse(xml);
+  return buildVerdict(parsed);
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null;
+}
+function asString(value) {
+  return typeof value === "string" ? value : void 0;
+}
+function buildVerdict(parsed) {
+  const rootUnknown = parsed["audit_verdict"];
+  if (!isObject(rootUnknown)) {
+    return { gates: [] };
+  }
+  const headerUnknown = rootUnknown["header"];
+  const gatesUnknown = rootUnknown["gates"];
+  return {
+    header: isObject(headerUnknown) ? buildHeader(headerUnknown) : void 0,
+    gates: isObject(gatesUnknown) ? buildGates(gatesUnknown) : []
+  };
+}
+function buildHeader(raw) {
+  return {
+    spec_node: asString(raw["spec_node"]),
+    verdict: asString(raw["verdict"]),
+    timestamp: asString(raw["timestamp"])
+  };
+}
+function buildGates(raw) {
+  const gatesUnknown = raw["gate"];
+  if (!Array.isArray(gatesUnknown)) return [];
+  return gatesUnknown.filter(isObject).map(buildGate);
+}
+function buildGate(raw) {
+  const findingsUnknown = raw["findings"];
+  return {
+    name: asString(raw["name"]),
+    status: asString(raw["status"]),
+    skipped_reason: asString(raw["skipped_reason"]),
+    count: isObject(findingsUnknown) ? asString(findingsUnknown["@_count"]) : void 0,
+    findings: isObject(findingsUnknown) ? buildFindings(findingsUnknown) : []
+  };
+}
+function buildFindings(raw) {
+  const findingsUnknown = raw["finding"];
+  if (!Array.isArray(findingsUnknown)) return [];
+  return findingsUnknown.filter(isObject).map(buildFinding);
+}
+function buildFinding(raw) {
+  return {
+    spec_file: asString(raw["spec_file"]),
+    test_file: asString(raw["test_file"])
+  };
+}
+
+// src/audit/semantic.ts
+function validateSemantics(verdict) {
+  const defects = [];
+  const hasFail = verdict.gates.some((g) => g.status === "FAIL");
+  const hasSkipped = verdict.gates.some((g) => g.status === "SKIPPED");
+  if (verdict.header?.verdict === "APPROVED" && (hasFail || hasSkipped)) {
+    defects.push("incoherent verdict: APPROVED but at least one gate is not PASS");
+  } else if (verdict.header?.verdict === "REJECT" && !hasFail && !hasSkipped) {
+    defects.push("incoherent verdict: REJECT but all gates are PASS");
+  }
+  for (const gate of verdict.gates) {
+    const label = gate.name ? `gate "${gate.name}"` : "gate";
+    if (gate.status === "FAIL" && gate.findings.length === 0) {
+      defects.push(`failed gate has no findings: ${label}`);
+    }
+    if (gate.status === "SKIPPED" && !gate.skipped_reason) {
+      defects.push(`skipped gate missing reason: ${label}`);
+    }
+  }
+  return defects;
+}
+
+// src/audit/structural.ts
+var VALID_VERDICTS = /* @__PURE__ */ new Set(["APPROVED", "REJECT"]);
+var VALID_GATE_STATUSES = /* @__PURE__ */ new Set(["PASS", "FAIL", "SKIPPED"]);
+function validateStructure(verdict) {
+  const defects = [];
+  if (!verdict.header) {
+    defects.push("missing required element: <header>");
+    return defects;
+  }
+  if (!verdict.header.spec_node) {
+    defects.push("missing required element: <spec_node>");
+  }
+  if (!verdict.header.verdict) {
+    defects.push("missing required element: <verdict> in <header>");
+  } else if (!VALID_VERDICTS.has(verdict.header.verdict)) {
+    defects.push(
+      `invalid enum value: verdict "${verdict.header.verdict}" is not one of APPROVED, REJECT`
+    );
+  }
+  if (!verdict.header.timestamp) {
+    defects.push("missing required element: <timestamp>");
+  }
+  if (verdict.gates.length === 0) {
+    defects.push("missing required element: at least one <gate> in <gates>");
+  }
+  for (const gate of verdict.gates) {
+    const label = gate.name ? `gate "${gate.name}"` : "gate";
+    if (gate.status !== void 0 && !VALID_GATE_STATUSES.has(gate.status)) {
+      defects.push(
+        `invalid enum value: ${label} status "${gate.status}" is not one of PASS, FAIL, SKIPPED`
+      );
+    }
+    if (gate.count !== void 0) {
+      const declared = parseInt(gate.count, 10);
+      const actual = gate.findings.length;
+      if (isNaN(declared) || declared !== actual) {
+        defects.push(
+          `count mismatch: ${label} declares count="${gate.count}" but has ${actual} finding(s)`
+        );
+      }
+    }
+  }
+  return defects;
+}
+
+// src/audit/verify.ts
+async function runVerifyPipeline(filePath, projectRoot) {
+  let verdict;
+  try {
+    verdict = await readVerdictFile(filePath);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { lines: [`reader: ${message}`], exitCode: 1 };
+  }
+  const structuralDefects = validateStructure(verdict);
+  if (structuralDefects.length > 0) {
+    return { lines: structuralDefects.map((d) => `structural: ${d}`), exitCode: 1 };
+  }
+  const semanticDefects = validateSemantics(verdict);
+  if (semanticDefects.length > 0) {
+    return { lines: semanticDefects.map((d) => `semantic: ${d}`), exitCode: 1 };
+  }
+  const pathDefects = validatePaths(verdict, projectRoot);
+  if (pathDefects.length > 0) {
+    return { lines: pathDefects.map((d) => `paths: ${d}`), exitCode: 1 };
+  }
+  return { lines: [], exitCode: 0, verdict: verdict.header?.verdict };
+}
+
+// src/audit/cli.ts
+async function runVerifyCommand(filePath, projectRoot, writeLine) {
+  const result = await runVerifyPipeline(filePath, projectRoot);
+  if (result.exitCode === 0) {
+    writeLine(result.verdict ?? "");
+  } else {
+    for (const line of result.lines) {
+      writeLine(line);
+    }
+  }
+  return result.exitCode;
+}
+var auditDomain = {
+  name: "audit",
+  description: "Audit verdict verification",
+  register: (program2) => {
+    const auditCmd = program2.command("audit").description("Audit verdict verification");
+    auditCmd.command("verify <file>").description("Verify an audit verdict XML file").action(async (file) => {
+      const exitCode = await runVerifyCommand(file, process.cwd(), console.log);
+      process.exit(exitCode);
+    });
+  }
+};
+
 // src/commands/claude/init.ts
 import { execa } from "execa";
 async function initCommand(options = {}) {
@@ -86,9 +307,7 @@ async function findSettingsFiles(root, visited = /* @__PURE__ */ new Set()) {
       if (error.message.includes("EACCES")) {
         throw new Error(`Permission denied: ${normalizedRoot}`);
       }
-      throw new Error(
-        `Failed to search directory "${normalizedRoot}": ${error.message}`
-      );
+      throw new Error(`Failed to search directory "${normalizedRoot}": ${error.message}`);
     }
     throw error;
   }
@@ -549,11 +768,11 @@ import fs5 from "fs/promises";
 import os from "os";
 import path3 from "path";
 var realFs = {
-  writeFile: (path8, content) => fs5.writeFile(path8, content, "utf-8"),
+  writeFile: (path9, content) => fs5.writeFile(path9, content, "utf-8"),
   rename: fs5.rename,
   unlink: fs5.unlink,
-  mkdir: async (path8, options) => {
-    await fs5.mkdir(path8, options);
+  mkdir: async (path9, options) => {
+    await fs5.mkdir(path9, options);
   }
 };
 async function writeSettings(filePath, settings, deps = { fs: realFs }) {
@@ -702,13 +921,459 @@ var claudeDomain = {
   }
 };
 
+// src/commands/config/defaults.ts
+import { stringify as yamlStringify } from "yaml";
+var JSON_INDENT = 2;
+function defaultsCommand(options, deps) {
+  const config = {};
+  for (const descriptor of deps.descriptors) {
+    config[descriptor.section] = descriptor.defaults;
+  }
+  return Promise.resolve({
+    stdout: formatConfig(config, options.json === true),
+    stderr: "",
+    exitCode: 0
+  });
+}
+function formatConfig(config, asJson) {
+  if (asJson) {
+    return `${JSON.stringify(config, null, JSON_INDENT)}
+`;
+  }
+  return yamlStringify(config);
+}
+
+// src/commands/config/show.ts
+import { stringify as yamlStringify2 } from "yaml";
+var JSON_INDENT2 = 2;
+var EXIT_CODE_ERROR = 1;
+async function showCommand(options, deps) {
+  const projectRoot = deps.resolveProjectRoot();
+  const result = await deps.resolveConfig(projectRoot);
+  if (!result.ok) {
+    return {
+      stdout: "",
+      stderr: `${result.error}
+`,
+      exitCode: EXIT_CODE_ERROR
+    };
+  }
+  return {
+    stdout: formatConfig2(result.value, options.json === true),
+    stderr: "",
+    exitCode: 0
+  };
+}
+function formatConfig2(config, asJson) {
+  if (asJson) {
+    return `${JSON.stringify(config, null, JSON_INDENT2)}
+`;
+  }
+  return yamlStringify2(config);
+}
+
+// src/commands/config/types.ts
+var CONFIG_FILENAME = "spx.config.yaml";
+
+// src/commands/config/validate.ts
+var EXIT_CODE_INVALID = 1;
+async function validateCommand(_options, deps) {
+  const projectRoot = deps.resolveProjectRoot();
+  const result = await deps.resolveConfig(projectRoot);
+  if (!result.ok) {
+    return {
+      stdout: "",
+      stderr: `${result.error}
+`,
+      exitCode: EXIT_CODE_INVALID
+    };
+  }
+  return {
+    stdout: `${CONFIG_FILENAME} at ${projectRoot} passes every registered descriptor's validator.
+`,
+    stderr: "",
+    exitCode: 0
+  };
+}
+
+// src/config/index.ts
+import { readFile as readFile2 } from "fs/promises";
+import { join } from "path";
+import { parse as parseToml } from "smol-toml";
+import { parse as parseYaml } from "yaml";
+
+// src/spec/config.ts
+var KIND_REGISTRY = {
+  enabler: { category: "node", suffix: ".enabler" },
+  outcome: { category: "node", suffix: ".outcome" },
+  adr: { category: "decision", suffix: ".adr.md" },
+  pdr: { category: "decision", suffix: ".pdr.md" }
+};
+var NODE_KINDS = Object.keys(KIND_REGISTRY).filter(
+  (k) => KIND_REGISTRY[k].category === "node"
+);
+var DECISION_KINDS = Object.keys(KIND_REGISTRY).filter(
+  (k) => KIND_REGISTRY[k].category === "decision"
+);
+var NODE_SUFFIXES = NODE_KINDS.map((k) => KIND_REGISTRY[k].suffix);
+var DECISION_SUFFIXES = DECISION_KINDS.map((k) => KIND_REGISTRY[k].suffix);
+var SPEC_TREE_SECTION = "specTree";
+function isKind(value) {
+  return Object.prototype.hasOwnProperty.call(KIND_REGISTRY, value);
+}
+function buildDefaults() {
+  return { kinds: { ...KIND_REGISTRY } };
+}
+function validate(value) {
+  if (typeof value !== "object" || value === null) {
+    return { ok: false, error: `${SPEC_TREE_SECTION} section must be an object` };
+  }
+  const candidate = value;
+  if (typeof candidate.kinds !== "object" || candidate.kinds === null || Array.isArray(candidate.kinds)) {
+    return {
+      ok: false,
+      error: `${SPEC_TREE_SECTION}.kinds must be an object keyed by kind name`
+    };
+  }
+  const entries = [];
+  const kindEntries = candidate.kinds;
+  for (const [key, entry] of Object.entries(kindEntries)) {
+    if (!isKind(key)) {
+      return {
+        ok: false,
+        error: `${SPEC_TREE_SECTION}.kinds contains unknown kind "${key}"`
+      };
+    }
+    if (typeof entry !== "object" || entry === null) {
+      return {
+        ok: false,
+        error: `${SPEC_TREE_SECTION}.kinds.${key} must be an object with category and suffix`
+      };
+    }
+    const def = entry;
+    const expected = KIND_REGISTRY[key];
+    if (def.category !== expected.category) {
+      return {
+        ok: false,
+        error: `${SPEC_TREE_SECTION}.kinds.${key}.category must be "${expected.category}"`
+      };
+    }
+    if (def.suffix !== expected.suffix) {
+      return {
+        ok: false,
+        error: `${SPEC_TREE_SECTION}.kinds.${key}.suffix must be "${expected.suffix}"`
+      };
+    }
+    entries.push([key, expected]);
+  }
+  const kinds = Object.fromEntries(entries);
+  return { ok: true, value: { kinds } };
+}
+var specTreeConfigDescriptor = {
+  section: SPEC_TREE_SECTION,
+  defaults: buildDefaults(),
+  validate
+};
+
+// src/validation/literal/config.ts
+var LITERAL_SECTION = "literal";
+var DEFAULT_MIN_STRING_LENGTH = 4;
+var DEFAULT_MIN_NUMBER_DIGITS = 4;
+var WEB_PRESET = /* @__PURE__ */ new Set([
+  "GET",
+  "POST",
+  "PUT",
+  "DELETE",
+  "PATCH",
+  "Content-Type",
+  "Authorization",
+  "Accept",
+  "status",
+  "message",
+  "error",
+  "data",
+  "class",
+  "id",
+  "href",
+  "src",
+  "type",
+  "name",
+  "value"
+]);
+var PRESET_REGISTRY = /* @__PURE__ */ new Map([
+  ["web", WEB_PRESET]
+]);
+function resolveAllowlist(config) {
+  const effective = /* @__PURE__ */ new Set();
+  for (const presetId of config.presets ?? []) {
+    const preset = PRESET_REGISTRY.get(presetId);
+    if (preset !== void 0) {
+      for (const v of preset) effective.add(v);
+    }
+  }
+  for (const v of config.include ?? []) {
+    effective.add(v);
+  }
+  for (const v of config.exclude ?? []) {
+    effective.delete(v);
+  }
+  return effective;
+}
+var defaults = {
+  allowlist: {},
+  minStringLength: DEFAULT_MIN_STRING_LENGTH,
+  minNumberDigits: DEFAULT_MIN_NUMBER_DIGITS
+};
+function validate2(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return { ok: false, error: `${LITERAL_SECTION} section must be an object` };
+  }
+  const candidate = value;
+  const allowlistRaw = candidate["allowlist"] ?? {};
+  const allowlistResult = validateAllowlist(allowlistRaw);
+  if (!allowlistResult.ok) {
+    return allowlistResult;
+  }
+  const minStringLength = candidate["minStringLength"] ?? defaults.minStringLength;
+  if (typeof minStringLength !== "number" || !Number.isInteger(minStringLength) || minStringLength < 0) {
+    return {
+      ok: false,
+      error: `${LITERAL_SECTION}.minStringLength must be a non-negative integer`
+    };
+  }
+  const minNumberDigits = candidate["minNumberDigits"] ?? defaults.minNumberDigits;
+  if (typeof minNumberDigits !== "number" || !Number.isInteger(minNumberDigits) || minNumberDigits < 0) {
+    return {
+      ok: false,
+      error: `${LITERAL_SECTION}.minNumberDigits must be a non-negative integer`
+    };
+  }
+  return { ok: true, value: { allowlist: allowlistResult.value, minStringLength, minNumberDigits } };
+}
+function validateAllowlist(raw) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    return { ok: false, error: `${LITERAL_SECTION}.allowlist must be an object` };
+  }
+  const candidate = raw;
+  const presets = candidate["presets"];
+  if (presets !== void 0) {
+    if (!Array.isArray(presets) || !presets.every((x) => typeof x === "string")) {
+      return { ok: false, error: `${LITERAL_SECTION}.allowlist.presets must be an array of strings` };
+    }
+    for (const id of presets) {
+      if (!PRESET_REGISTRY.has(id)) {
+        return { ok: false, error: `${LITERAL_SECTION}.allowlist.presets: unrecognized preset "${id}"` };
+      }
+    }
+  }
+  const include = candidate["include"];
+  if (include !== void 0 && (!Array.isArray(include) || !include.every((x) => typeof x === "string"))) {
+    return { ok: false, error: `${LITERAL_SECTION}.allowlist.include must be an array of strings` };
+  }
+  const exclude = candidate["exclude"];
+  if (exclude !== void 0 && (!Array.isArray(exclude) || !exclude.every((x) => typeof x === "string"))) {
+    return { ok: false, error: `${LITERAL_SECTION}.allowlist.exclude must be an array of strings` };
+  }
+  return {
+    ok: true,
+    value: {
+      presets,
+      include,
+      exclude
+    }
+  };
+}
+var literalConfigDescriptor = {
+  section: LITERAL_SECTION,
+  defaults,
+  validate: validate2
+};
+
+// src/config/registry.ts
+var productionRegistry = [
+  specTreeConfigDescriptor,
+  literalConfigDescriptor
+];
+
+// src/config/index.ts
+var CONFIG_FILENAMES = {
+  json: "spx.config.json",
+  yaml: "spx.config.yaml",
+  toml: "spx.config.toml"
+};
+async function resolveConfig(projectRoot, descriptors = productionRegistry) {
+  const detectedResult = await detectConfigFiles(projectRoot);
+  if (!detectedResult.ok) {
+    return detectedResult;
+  }
+  const detected = detectedResult.value;
+  if (detected.length > 1) {
+    const names = detected.map((f) => f.filename).join(", ");
+    return { ok: false, error: `multiple config files found: ${names}` };
+  }
+  const sectionsResult = detected.length === 0 ? { ok: true, value: {} } : parseSections(detected[0]);
+  if (!sectionsResult.ok) {
+    return sectionsResult;
+  }
+  const sections = sectionsResult.value;
+  const resolved = {};
+  for (const descriptor of descriptors) {
+    const sectionValue = sections[descriptor.section];
+    if (sectionValue === void 0) {
+      resolved[descriptor.section] = descriptor.defaults;
+      continue;
+    }
+    const validated = descriptor.validate(sectionValue);
+    if (!validated.ok) {
+      return { ok: false, error: `${descriptor.section}: ${validated.error}` };
+    }
+    resolved[descriptor.section] = validated.value;
+  }
+  return { ok: true, value: resolved };
+}
+async function detectConfigFiles(projectRoot) {
+  const detected = [];
+  for (const filename of Object.values(CONFIG_FILENAMES)) {
+    let raw;
+    try {
+      raw = await readFile2(join(projectRoot, filename), "utf8");
+    } catch (error) {
+      if (isFileNotFound(error)) continue;
+      return { ok: false, error: `failed to read ${filename}: ${toMessage(error)}` };
+    }
+    detected.push({ filename, raw });
+  }
+  return { ok: true, value: detected };
+}
+function parseSections(file) {
+  switch (file.filename) {
+    case CONFIG_FILENAMES.json:
+      return parseJsonSections(file.filename, file.raw);
+    case CONFIG_FILENAMES.yaml:
+      return parseYamlSections(file.filename, file.raw);
+    default:
+      return parseTomlSections(file.filename, file.raw);
+  }
+}
+function parseJsonSections(filename, raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    return { ok: false, error: `${filename} is not valid json: ${toMessage(error)}` };
+  }
+  return validateParsedSections(filename, parsed);
+}
+function parseYamlSections(filename, raw) {
+  let parsed;
+  try {
+    parsed = parseYaml(raw);
+  } catch (error) {
+    return { ok: false, error: `${filename} is not valid yaml: ${toMessage(error)}` };
+  }
+  if (parsed === null || parsed === void 0) {
+    return { ok: true, value: {} };
+  }
+  return validateParsedSections(filename, parsed);
+}
+function parseTomlSections(filename, raw) {
+  let parsed;
+  try {
+    parsed = parseToml(raw);
+  } catch (error) {
+    return { ok: false, error: `${filename} is not valid toml: ${toMessage(error)}` };
+  }
+  return validateParsedSections(filename, parsed);
+}
+function validateParsedSections(filename, parsed) {
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return { ok: false, error: `${filename} must parse to a mapping of descriptor sections` };
+  }
+  return { ok: true, value: parsed };
+}
+function isFileNotFound(error) {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+function toMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// src/domains/config/root.ts
+import { execSync } from "child_process";
+import { resolve as resolve2 } from "path";
+var GIT_TOPLEVEL_CMD = "git rev-parse --show-toplevel";
+var GIT_NOT_REPO_MARKER = "not a git repository";
+function resolveProjectRoot(cwd = process.cwd()) {
+  const resolvedCwd = resolve2(cwd);
+  try {
+    const stdout = execSync(GIT_TOPLEVEL_CMD, {
+      cwd: resolvedCwd,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf8"
+    });
+    const toplevel = stdout.trim();
+    if (toplevel.length > 0) {
+      return { projectRoot: resolve2(toplevel) };
+    }
+  } catch {
+  }
+  return {
+    projectRoot: resolvedCwd,
+    warning: `warning: ${resolvedCwd} is not inside a git worktree \u2014 falling back to the current working directory. ${GIT_NOT_REPO_MARKER}.`
+  };
+}
+
+// src/domains/config/index.ts
+function buildDefaultDeps() {
+  return {
+    resolveConfig,
+    resolveProjectRoot: () => {
+      const resolved = resolveProjectRoot();
+      if (resolved.warning !== void 0) {
+        process.stderr.write(`${resolved.warning}
+`);
+      }
+      return resolved.projectRoot;
+    },
+    descriptors: productionRegistry
+  };
+}
+async function emit(result) {
+  if (result.stdout.length > 0) {
+    process.stdout.write(result.stdout);
+  }
+  if (result.stderr.length > 0) {
+    process.stderr.write(result.stderr);
+  }
+  return process.exit(result.exitCode);
+}
+function registerConfigCommands(configCmd) {
+  configCmd.command("show").description("Print the resolved configuration as YAML (or JSON with --json)").option("--json", "Output as JSON").action(async (options) => {
+    await emit(await showCommand(options, buildDefaultDeps()));
+  });
+  configCmd.command("validate").description("Verify that spx.config.yaml passes every registered descriptor's validator").action(async (options) => {
+    await emit(await validateCommand(options, buildDefaultDeps()));
+  });
+  configCmd.command("defaults").description("Print each registered descriptor's defaults \u2014 ignores spx.config.yaml").option("--json", "Output as JSON").action(async (options) => {
+    await emit(await defaultsCommand(options, buildDefaultDeps()));
+  });
+}
+var configDomain = {
+  name: "config",
+  description: "Inspect and validate the resolved spx configuration",
+  register: (program2) => {
+    const configCmd = program2.command("config").description("Inspect and validate the resolved spx configuration");
+    registerConfigCommands(configCmd);
+  }
+};
+
 // src/commands/session/archive.ts
 import { mkdir, rename, stat } from "fs/promises";
-import { dirname as dirname2, join as join2 } from "path";
+import { dirname as dirname2, join as join3 } from "path";
 
 // src/git/root.ts
 import { execa as execa2 } from "execa";
-import { dirname, isAbsolute, join, resolve } from "path";
+import { dirname, isAbsolute, join as join2, resolve as resolve3 } from "path";
 
 // src/config/defaults.ts
 var DEFAULT_CONFIG = {
@@ -779,7 +1444,7 @@ async function detectMainRepoRoot(cwd = process.cwd(), deps = defaultDeps) {
       };
     }
     const commonDir = extractStdout(commonDirResult.stdout);
-    const absoluteCommonDir = isAbsolute(commonDir) ? commonDir : resolve(toplevel, commonDir);
+    const absoluteCommonDir = isAbsolute(commonDir) ? commonDir : resolve3(toplevel, commonDir);
     const mainRepoRoot = dirname(absoluteCommonDir);
     return {
       root: mainRepoRoot,
@@ -799,24 +1464,52 @@ async function resolveSessionConfig(options = {}) {
   if (sessionsDir) {
     return {
       config: {
-        todoDir: join(sessionsDir, statusDirs2.todo),
-        doingDir: join(sessionsDir, statusDirs2.doing),
-        archiveDir: join(sessionsDir, statusDirs2.archive)
+        todoDir: join2(sessionsDir, statusDirs2.todo),
+        doingDir: join2(sessionsDir, statusDirs2.doing),
+        archiveDir: join2(sessionsDir, statusDirs2.archive)
       }
     };
   }
   const gitResult = await detectMainRepoRoot(cwd, deps);
-  const baseDir = join(gitResult.root, DEFAULT_CONFIG.sessions.dir);
+  const baseDir = join2(gitResult.root, DEFAULT_CONFIG.sessions.dir);
   return {
     config: {
-      todoDir: join(baseDir, statusDirs2.todo),
-      doingDir: join(baseDir, statusDirs2.doing),
-      archiveDir: join(baseDir, statusDirs2.archive)
+      todoDir: join2(baseDir, statusDirs2.todo),
+      doingDir: join2(baseDir, statusDirs2.doing),
+      archiveDir: join2(baseDir, statusDirs2.archive)
     },
     warning: gitResult.warning
   };
 }
 
+// src/session/archive.ts
+var SESSION_FILE_EXTENSION = ".md";
+var ARCHIVABLE_DIR_KEY = {
+  todo: "todoDir",
+  doing: "doingDir"
+};
+function buildArchivePaths(sessionId, currentStatus, config) {
+  const filename = `${sessionId}${SESSION_FILE_EXTENSION}`;
+  const dirKey = ARCHIVABLE_DIR_KEY[currentStatus];
+  const sourceDir = config[dirKey];
+  return {
+    source: `${sourceDir}/${filename}`,
+    target: `${config.archiveDir}/${filename}`
+  };
+}
+var ARCHIVE_SEARCH_ORDER = ["todo", "doing"];
+function findSessionForArchive(existingPaths) {
+  if (existingPaths.archive !== null) {
+    return null;
+  }
+  for (const status of ARCHIVE_SEARCH_ORDER) {
+    if (existingPaths[status] !== null) {
+      return { status, path: existingPaths[status] };
+    }
+  }
+  return null;
+}
+
 // src/session/batch.ts
 var BatchError = class extends Error {
   results;
@@ -910,39 +1603,36 @@ var SessionAlreadyArchivedError = class extends Error {
     this.sessionId = sessionId;
   }
 };
-async function resolveArchivePaths(sessionId, config) {
-  const filename = `${sessionId}.md`;
-  const todoPath = join2(config.todoDir, filename);
-  const doingPath = join2(config.doingDir, filename);
-  const archivePath = join2(config.archiveDir, filename);
+async function fileExists(path9) {
   try {
-    const archiveStats = await stat(archivePath);
-    if (archiveStats.isFile()) {
-      throw new SessionAlreadyArchivedError(sessionId);
-    }
-  } catch (error) {
-    if (error instanceof Error && "code" in error && error.code !== "ENOENT") {
-      throw error;
-    }
-    if (error instanceof SessionAlreadyArchivedError) {
-      throw error;
-    }
-  }
-  try {
-    const todoStats = await stat(todoPath);
-    if (todoStats.isFile()) {
-      return { source: todoPath, target: archivePath };
-    }
+    const stats = await stat(path9);
+    return stats.isFile();
   } catch {
+    return false;
   }
-  try {
-    const doingStats = await stat(doingPath);
-    if (doingStats.isFile()) {
-      return { source: doingPath, target: archivePath };
-    }
-  } catch {
+}
+async function probeSessionPaths(sessionId, config) {
+  const filename = `${sessionId}${SESSION_FILE_EXTENSION}`;
+  const todoPath = join3(config.todoDir, filename);
+  const doingPath = join3(config.doingDir, filename);
+  const archivePath = join3(config.archiveDir, filename);
+  return {
+    todo: await fileExists(todoPath) ? todoPath : null,
+    doing: await fileExists(doingPath) ? doingPath : null,
+    archive: await fileExists(archivePath) ? archivePath : null
+  };
+}
+async function resolveArchivePaths(sessionId, config) {
+  const existingPaths = await probeSessionPaths(sessionId, config);
+  if (existingPaths.archive !== null) {
+    throw new SessionAlreadyArchivedError(sessionId);
+  }
+  const location = findSessionForArchive(existingPaths);
+  if (!location) {
+    throw new SessionNotFoundError(sessionId);
   }
-  throw new SessionNotFoundError(sessionId);
+  const paths = buildArchivePaths(sessionId, location.status, config);
+  return paths;
 }
 async function archiveSingle(sessionId, config) {
   const { source, target } = await resolveArchivePaths(sessionId, config);
@@ -961,7 +1651,7 @@ import { stat as stat2, unlink } from "fs/promises";
 
 // src/session/delete.ts
 function resolveDeletePath(sessionId, existingPaths) {
-  const matchingPath = existingPaths.find((path8) => path8.includes(sessionId));
+  const matchingPath = existingPaths.find((path9) => path9.includes(sessionId));
   if (!matchingPath) {
     throw new SessionNotFoundError(sessionId);
   }
@@ -969,10 +1659,10 @@ function resolveDeletePath(sessionId, existingPaths) {
 }
 
 // src/session/show.ts
-import { join as join3 } from "path";
+import { join as join4 } from "path";
 
 // src/session/list.ts
-import { parse as parseYaml } from "yaml";
+import { parse as parseYaml2 } from "yaml";
 
 // src/session/timestamp.ts
 var SESSION_ID_PATTERN = /^(\d{4})-(\d{2})-(\d{2})_(\d{2})-(\d{2})-(\d{2})$/;
@@ -1017,6 +1707,17 @@ var PRIORITY_ORDER = {
   low: 2
 };
 var DEFAULT_PRIORITY = "medium";
+var SESSION_FRONT_MATTER = {
+  PRIORITY: "priority",
+  TAGS: "tags",
+  ID: "id",
+  BRANCH: "branch",
+  CREATED_AT: "created_at",
+  AGENT_SESSION_ID: "agent_session_id",
+  WORKING_DIRECTORY: "working_directory",
+  SPECS: "specs",
+  FILES: "files"
+};
 
 // src/session/list.ts
 var FRONT_MATTER_PATTERN = /^---\r?\n([\s\S]*?)\r?\n(?:---|\.\.\.)\r?\n?/;
@@ -1032,43 +1733,35 @@ function parseSessionMetadata(content) {
     };
   }
   try {
-    const parsed = parseYaml(match[1]);
+    const parsed = parseYaml2(match[1]);
     if (!parsed || typeof parsed !== "object") {
       return {
         priority: DEFAULT_PRIORITY,
         tags: []
       };
     }
-    const priority = isValidPriority(parsed.priority) ? parsed.priority : DEFAULT_PRIORITY;
-    let tags = [];
-    if (Array.isArray(parsed.tags)) {
-      tags = parsed.tags.filter((t) => typeof t === "string");
-    }
-    const metadata = {
-      priority,
-      tags
-    };
-    if (typeof parsed.id === "string") {
-      metadata.id = parsed.id;
-    }
-    if (typeof parsed.branch === "string") {
-      metadata.branch = parsed.branch;
-    }
-    if (typeof parsed.created_at === "string") {
-      metadata.createdAt = parsed.created_at;
-    }
-    if (typeof parsed.working_directory === "string") {
-      metadata.workingDirectory = parsed.working_directory;
-    }
-    if (Array.isArray(parsed.specs)) {
-      metadata.specs = parsed.specs.filter(
-        (s) => typeof s === "string"
-      );
-    }
-    if (Array.isArray(parsed.files)) {
-      metadata.files = parsed.files.filter(
-        (f) => typeof f === "string"
-      );
+    const rawPriority = parsed[SESSION_FRONT_MATTER.PRIORITY];
+    const priority = isValidPriority(rawPriority) ? rawPriority : DEFAULT_PRIORITY;
+    const rawTags = parsed[SESSION_FRONT_MATTER.TAGS];
+    const tags = Array.isArray(rawTags) ? rawTags.filter((t) => typeof t === "string") : [];
+    const metadata = { priority, tags };
+    const id = parsed[SESSION_FRONT_MATTER.ID];
+    if (typeof id === "string") metadata.id = id;
+    const branch = parsed[SESSION_FRONT_MATTER.BRANCH];
+    if (typeof branch === "string") metadata.branch = branch;
+    const createdAt = parsed[SESSION_FRONT_MATTER.CREATED_AT];
+    if (typeof createdAt === "string") metadata.createdAt = createdAt;
+    const agentSessionId = parsed[SESSION_FRONT_MATTER.AGENT_SESSION_ID];
+    if (typeof agentSessionId === "string") metadata.agentSessionId = agentSessionId;
+    const workingDirectory = parsed[SESSION_FRONT_MATTER.WORKING_DIRECTORY];
+    if (typeof workingDirectory === "string") metadata.workingDirectory = workingDirectory;
+    const specs = parsed[SESSION_FRONT_MATTER.SPECS];
+    if (Array.isArray(specs)) {
+      metadata.specs = specs.filter((s) => typeof s === "string");
+    }
+    const files = parsed[SESSION_FRONT_MATTER.FILES];
+    if (Array.isArray(files)) {
+      metadata.files = files.filter((f) => typeof f === "string");
     }
     return metadata;
   } catch {
@@ -1097,9 +1790,9 @@ function sortSessions(sessions) {
 // src/session/show.ts
 var { dir: sessionsBaseDir, statusDirs } = DEFAULT_CONFIG.sessions;
 var DEFAULT_SESSION_CONFIG = {
-  todoDir: join3(sessionsBaseDir, statusDirs.todo),
-  doingDir: join3(sessionsBaseDir, statusDirs.doing),
-  archiveDir: join3(sessionsBaseDir, statusDirs.archive)
+  todoDir: join4(sessionsBaseDir, statusDirs.todo),
+  doingDir: join4(sessionsBaseDir, statusDirs.doing),
+  archiveDir: join4(sessionsBaseDir, statusDirs.archive)
 };
 var SEARCH_ORDER = [...SESSION_STATUSES];
 function resolveSessionPaths(id, config = DEFAULT_SESSION_CONFIG) {
@@ -1136,11 +1829,11 @@ function formatShowOutput(content, options) {
 // src/commands/session/delete.ts
 async function findExistingPaths(paths) {
   const existing = [];
-  for (const path8 of paths) {
+  for (const path9 of paths) {
     try {
-      const stats = await stat2(path8);
+      const stats = await stat2(path9);
       if (stats.isFile()) {
-        existing.push(path8);
+        existing.push(path9);
       }
     } catch {
     }
@@ -1161,10 +1854,20 @@ async function deleteCommand(options) {
 
 // src/commands/session/handoff.ts
 import { mkdir as mkdir2, writeFile } from "fs/promises";
-import { join as join4, resolve as resolve2 } from "path";
+import { join as join5, resolve as resolve4 } from "path";
 
 // src/session/create.ts
 var MIN_CONTENT_LENGTH = 1;
+var FRONT_MATTER_OPEN = /^---\r?\n/;
+function preFillSessionContent(content, params) {
+  const match = FRONT_MATTER_OPEN.exec(content);
+  if (!match) return content;
+  const lines = [`${SESSION_FRONT_MATTER.CREATED_AT}: "${params.createdAt.toISOString()}"`];
+  if (params.agentSessionId !== void 0) {
+    lines.push(`${SESSION_FRONT_MATTER.AGENT_SESSION_ID}: "${params.agentSessionId}"`);
+  }
+  return match[0] + lines.join("\n") + "\n" + content.slice(match[0].length);
+}
 function validateSessionContent(content) {
   if (!content || content.trim().length < MIN_CONTENT_LENGTH) {
     return {
@@ -1172,12 +1875,6 @@ function validateSessionContent(content) {
       error: "Session content cannot be empty"
     };
   }
-  if (content.trim().length === 0) {
-    return {
-      valid: false,
-      error: "Session content cannot be only whitespace"
-    };
-  }
   return { valid: true };
 }
 
@@ -1208,14 +1905,19 @@ ${content}`;
 async function handoffCommand(options) {
   const { config, warning } = await resolveSessionConfig({ sessionsDir: options.sessionsDir });
   const sessionId = generateSessionId();
-  const fullContent = buildSessionContent(options.content);
+  const baseContent = buildSessionContent(options.content);
+  const agentSessionId = process.env.CLAUDE_SESSION_ID ?? process.env.CODEX_THREAD_ID;
+  const fullContent = preFillSessionContent(baseContent, {
+    createdAt: /* @__PURE__ */ new Date(),
+    agentSessionId
+  });
   const validation = validateSessionContent(fullContent);
   if (!validation.valid) {
     throw new SessionInvalidContentError(validation.error ?? "Unknown validation error");
   }
   const filename = `${sessionId}.md`;
-  const sessionPath = join4(config.todoDir, filename);
-  const absolutePath = resolve2(sessionPath);
+  const sessionPath = join5(config.todoDir, filename);
+  const absolutePath = resolve4(sessionPath);
   await mkdir2(config.todoDir, { recursive: true });
   await writeFile(sessionPath, fullContent, "utf-8");
   if (warning) {
@@ -1227,8 +1929,8 @@ async function handoffCommand(options) {
 }
 
 // src/commands/session/list.ts
-import { readdir, readFile } from "fs/promises";
-import { join as join5 } from "path";
+import { readdir, readFile as readFile3 } from "fs/promises";
+import { join as join6 } from "path";
 async function loadSessionsFromDir(dir, status) {
   try {
     const files = await readdir(dir);
@@ -1236,8 +1938,8 @@ async function loadSessionsFromDir(dir, status) {
     for (const file of files) {
       if (!file.endsWith(".md")) continue;
       const id = file.replace(".md", "");
-      const filePath = join5(dir, file);
-      const content = await readFile(filePath, "utf-8");
+      const filePath = join6(dir, file);
+      const content = await readFile3(filePath, "utf-8");
       const metadata = parseSessionMetadata(content);
       sessions.push({
         id,
@@ -1299,8 +2001,8 @@ async function listCommand(options) {
 }
 
 // src/commands/session/pickup.ts
-import { mkdir as mkdir3, readdir as readdir2, readFile as readFile2, rename as rename2 } from "fs/promises";
-import { join as join6 } from "path";
+import { mkdir as mkdir3, readdir as readdir2, readFile as readFile4, rename as rename2 } from "fs/promises";
+import { join as join7 } from "path";
 
 // src/session/pickup.ts
 function buildClaimPaths(sessionId, config) {
@@ -1345,8 +2047,8 @@ async function loadTodoSessions(config) {
     for (const file of files) {
       if (!file.endsWith(".md")) continue;
       const id = file.replace(".md", "");
-      const filePath = join6(config.todoDir, file);
-      const content = await readFile2(filePath, "utf-8");
+      const filePath = join7(config.todoDir, file);
+      const content = await readFile4(filePath, "utf-8");
       const metadata = parseSessionMetadata(content);
       sessions.push({
         id,
@@ -1385,7 +2087,7 @@ async function pickupCommand(options) {
   } catch (error) {
     throw classifyClaimError(error, sessionId);
   }
-  const content = await readFile2(paths.target, "utf-8");
+  const content = await readFile4(paths.target, "utf-8");
   const output = formatShowOutput(content, { status: PICKUP_TARGET_STATUS });
   return `Claimed session <PICKUP_ID>${sessionId}</PICKUP_ID>
 
@@ -1393,10 +2095,30 @@ ${output}`;
 }
 
 // src/commands/session/prune.ts
-import { readdir as readdir3, readFile as readFile3, unlink as unlink2 } from "fs/promises";
-import { join as join7 } from "path";
-var PRUNE_STATUS = SESSION_STATUSES[2];
+import { readdir as readdir3, readFile as readFile5, unlink as unlink2 } from "fs/promises";
+import { join as join8 } from "path";
+
+// src/session/prune.ts
 var DEFAULT_KEEP_COUNT = 5;
+function selectSessionsToDelete(sessions, options = {}) {
+  const keep = options.keep ?? DEFAULT_KEEP_COUNT;
+  if (sessions.length <= keep) {
+    return [];
+  }
+  const sorted = [...sessions].sort((a, b) => {
+    const dateA = parseSessionId(a.id);
+    const dateB = parseSessionId(b.id);
+    if (!dateA && !dateB) return 0;
+    if (!dateA) return -1;
+    if (!dateB) return 1;
+    return dateA.getTime() - dateB.getTime();
+  });
+  const deleteCount = sessions.length - keep;
+  return sorted.slice(0, deleteCount);
+}
+
+// src/commands/session/prune.ts
+var PRUNE_STATUS = SESSION_STATUSES[2];
 var PruneValidationError = class extends Error {
   constructor(message) {
     super(message);
@@ -1419,8 +2141,8 @@ async function loadArchiveSessions(config) {
     for (const file of files) {
       if (!file.endsWith(".md")) continue;
       const id = file.replace(".md", "");
-      const filePath = join7(config.archiveDir, file);
-      const content = await readFile3(filePath, "utf-8");
+      const filePath = join8(config.archiveDir, file);
+      const content = await readFile5(filePath, "utf-8");
       const metadata = parseSessionMetadata(content);
       sessions.push({
         id,
@@ -1437,20 +2159,13 @@ async function loadArchiveSessions(config) {
     throw error;
   }
 }
-function selectSessionsToPrune(sessions, keep) {
-  const sorted = sortSessions(sessions);
-  if (sorted.length <= keep) {
-    return [];
-  }
-  return sorted.slice(keep);
-}
 async function pruneCommand(options) {
   validatePruneOptions(options);
   const keep = options.keep ?? DEFAULT_KEEP_COUNT;
   const dryRun = options.dryRun ?? false;
   const { config } = await resolveSessionConfig({ sessionsDir: options.sessionsDir });
   const sessions = await loadArchiveSessions(config);
-  const toPrune = selectSessionsToPrune(sessions, keep);
+  const toPrune = selectSessionsToDelete(sessions, { keep });
   if (toPrune.length === 0) {
     return `No sessions to prune. ${sessions.length} sessions kept.`;
   }
@@ -1512,19 +2227,7 @@ async function loadDoingSessions(config) {
     throw error;
   }
 }
-async function releaseCommand(options) {
-  const { config } = await resolveSessionConfig({ sessionsDir: options.sessionsDir });
-  let sessionId;
-  if (options.sessionId) {
-    sessionId = options.sessionId;
-  } else {
-    const sessions = await loadDoingSessions(config);
-    const current = findCurrentSession(sessions);
-    if (!current) {
-      throw new SessionNotClaimedError("(none)");
-    }
-    sessionId = current.id;
-  }
+async function releaseSingle(sessionId, config) {
   const paths = buildReleasePaths(sessionId, config);
   try {
     await rename3(paths.source, paths.target);
@@ -1537,9 +2240,22 @@ async function releaseCommand(options) {
   return `Released session: ${sessionId}
 Session returned to todo directory.`;
 }
+async function releaseCommand(options) {
+  const { config } = await resolveSessionConfig({ sessionsDir: options.sessionsDir });
+  let ids = options.sessionIds;
+  if (ids.length === 0) {
+    const sessions = await loadDoingSessions(config);
+    const current = findCurrentSession(sessions);
+    if (!current) {
+      throw new SessionNotClaimedError("(none)");
+    }
+    ids = [current.id];
+  }
+  return processBatch(ids, (id) => releaseSingle(id, config));
+}
 
 // src/commands/session/show.ts
-import { readFile as readFile4, stat as stat3 } from "fs/promises";
+import { readFile as readFile6, stat as stat3 } from "fs/promises";
 async function findExistingPath(paths, _config) {
   for (let i = 0; i < paths.length; i++) {
     const filePath = paths[i];
@@ -1559,10 +2275,10 @@ async function showSingle(sessionId, config) {
   if (!found) {
     throw new SessionNotFoundError(sessionId);
   }
-  const content = await readFile4(found.path, "utf-8");
+  const content = await readFile6(found.path, "utf-8");
   return formatShowOutput(content, { status: found.status });
 }
-async function showCommand(options) {
+async function showCommand2(options) {
   const { config } = await resolveSessionConfig({ sessionsDir: options.sessionsDir });
   return processBatch(options.sessionIds, (id) => showSingle(id, config));
 }
@@ -1630,17 +2346,17 @@ async function readStdin() {
   if (process.stdin.isTTY) {
     return void 0;
   }
-  return new Promise((resolve3) => {
+  return new Promise((resolve6) => {
     let data = "";
     process.stdin.setEncoding("utf-8");
     process.stdin.on("data", (chunk) => {
       data += chunk;
     });
     process.stdin.on("end", () => {
-      resolve3(data.trim() || void 0);
+      resolve6(data.trim() || void 0);
     });
     process.stdin.on("error", () => {
-      resolve3(void 0);
+      resolve6(void 0);
     });
   });
 }
@@ -1675,7 +2391,7 @@ function registerSessionCommands(sessionCmd) {
   });
   sessionCmd.command("show <id...>").description("Show session content").option("--sessions-dir <path>", "Custom sessions directory").action(async (ids, options) => {
     try {
-      const output = await showCommand({
+      const output = await showCommand2({
         sessionIds: ids,
         sessionsDir: options.sessionsDir
       });
@@ -1700,10 +2416,10 @@ function registerSessionCommands(sessionCmd) {
       handleError(error);
     }
   });
-  sessionCmd.command("release [id]").description("Release a session (move from doing to todo)").option("--sessions-dir <path>", "Custom sessions directory").action(async (id, options) => {
+  sessionCmd.command("release [ids...]").description("Release one or more sessions (move from doing to todo)").option("--sessions-dir <path>", "Custom sessions directory").action(async (ids, options) => {
     try {
       const output = await releaseCommand({
-        sessionId: id,
+        sessionIds: ids,
         sessionsDir: options.sessionsDir
       });
       console.log(output);
@@ -1777,8 +2493,7 @@ var sessionDomain = {
 };
 
 // src/domains/spec/index.ts
-import { access as access2 } from "fs/promises";
-import { readFile as readFile5, writeFile as writeFile2 } from "fs/promises";
+import { access as access2, readFile as readFile7, writeFile as writeFile2 } from "fs/promises";
 
 // src/scanner/scanner.ts
 import path5 from "path";
@@ -1897,34 +2612,28 @@ var StatusDeterminationError = class extends Error {
 };
 async function getWorkItemStatus(workItemPath) {
   try {
-    try {
-      await access(workItemPath);
-    } catch (error) {
-      if (error.code === "ENOENT") {
-        throw new Error(`Work item not found: ${workItemPath}`);
-      }
-      throw error;
-    }
     const testsPath = path6.join(workItemPath, "tests");
-    let hasTests;
+    let entries;
     try {
-      await access(testsPath);
-      hasTests = true;
+      entries = await readdir5(testsPath);
     } catch (error) {
       if (error.code === "ENOENT") {
-        hasTests = false;
-      } else {
-        throw error;
+        try {
+          await access(workItemPath);
+        } catch (workItemError) {
+          if (workItemError.code === "ENOENT") {
+            throw new Error(`Work item not found: ${workItemPath}`);
+          }
+          throw workItemError;
+        }
+        return determineStatus({
+          hasTestsDir: false,
+          hasDoneMd: false,
+          testsIsEmpty: true
+        });
       }
+      throw error;
     }
-    if (!hasTests) {
-      return determineStatus({
-        hasTestsDir: false,
-        hasDoneMd: false,
-        testsIsEmpty: true
-      });
-    }
-    const entries = await readdir5(testsPath);
     const hasDone = entries.includes("DONE.md");
     if (hasDone) {
       const donePath = path6.join(testsPath, "DONE.md");
@@ -2044,6 +2753,14 @@ function rollupStatus(nodes) {
 }
 
 // src/commands/spec/next.ts
+var EMPTY_WORK_ITEMS_MESSAGE = "No work items found in specs/work/doing";
+var ALL_COMPLETE_MESSAGE = "All work items are complete! \u{1F389}";
+var NEXT_WORK_ITEM_HEADING = "Next work item:";
+var STATUS_LABEL = "Status";
+var PATH_LABEL = "Path";
+var INDENT = "  ";
+var BLANK_LINE = "";
+var PATH_SEPARATOR = " > ";
 function findNextWorkItem(tree) {
   return findFirstNonDoneLeaf(tree.nodes);
 }
@@ -2053,46 +2770,18 @@ function findFirstNonDoneLeaf(nodes) {
       if (node.status !== "DONE") {
         return node;
       }
-    } else {
-      const found = findFirstNonDoneLeaf(node.children);
-      if (found) {
-        return found;
-      }
+      continue;
+    }
+    const found = findFirstNonDoneLeaf(node.children);
+    if (found !== null) {
+      return found;
     }
   }
   return null;
 }
 function formatWorkItemName(node) {
-  const displayNum = node.kind === "capability" ? node.number + 1 : node.number;
-  return `${node.kind}-${displayNum}_${node.slug}`;
-}
-async function nextCommand(options = {}) {
-  const cwd = options.cwd || process.cwd();
-  const scanner = new Scanner(cwd, DEFAULT_CONFIG);
-  const workItems = await scanner.scan();
-  if (workItems.length === 0) {
-    return `No work items found in ${DEFAULT_CONFIG.specs.root}/${DEFAULT_CONFIG.specs.work.dir}/${DEFAULT_CONFIG.specs.work.statusDirs.doing}`;
-  }
-  const tree = await buildTree(workItems);
-  const next = findNextWorkItem(tree);
-  if (!next) {
-    return "All work items are complete! \u{1F389}";
-  }
-  const parents = findParents(tree.nodes, next);
-  const lines = [];
-  lines.push("Next work item:");
-  lines.push("");
-  if (parents.capability && parents.feature) {
-    lines.push(
-      `  ${formatWorkItemName(parents.capability)} > ${formatWorkItemName(parents.feature)} > ${formatWorkItemName(next)}`
-    );
-  } else {
-    lines.push(`  ${formatWorkItemName(next)}`);
-  }
-  lines.push("");
-  lines.push(`  Status: ${next.status}`);
-  lines.push(`  Path: ${next.path}`);
-  return lines.join("\n");
+  const displayNumber = node.kind === "capability" ? node.number + 1 : node.number;
+  return `${node.kind}-${displayNumber}_${node.slug}`;
 }
 function findParents(nodes, target) {
   for (const capability of nodes) {
@@ -2106,9 +2795,32 @@ function findParents(nodes, target) {
   }
   return {};
 }
+async function nextCommand(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const scanner = new Scanner(cwd, DEFAULT_CONFIG);
+  const workItems = await scanner.scan();
+  if (workItems.length === 0) {
+    return EMPTY_WORK_ITEMS_MESSAGE;
+  }
+  const tree = await buildTree(workItems);
+  const next = findNextWorkItem(tree);
+  if (next === null) {
+    return ALL_COMPLETE_MESSAGE;
+  }
+  const parents = findParents(tree.nodes, next);
+  const pathLine = parents.capability !== void 0 && parents.feature !== void 0 ? `${INDENT}${formatWorkItemName(parents.capability)}${PATH_SEPARATOR}${formatWorkItemName(parents.feature)}${PATH_SEPARATOR}${formatWorkItemName(next)}` : `${INDENT}${formatWorkItemName(next)}`;
+  return [
+    NEXT_WORK_ITEM_HEADING,
+    BLANK_LINE,
+    pathLine,
+    BLANK_LINE,
+    `${INDENT}${STATUS_LABEL}: ${next.status}`,
+    `${INDENT}${PATH_LABEL}: ${next.path}`
+  ].join("\n");
+}
 
 // src/reporter/json.ts
-var JSON_INDENT = 2;
+var JSON_INDENT3 = 2;
 function formatJSON(tree, config) {
   const capabilities = tree.nodes.map((node) => nodeToJSON(node));
   const summary = calculateSummary(tree);
@@ -2120,7 +2832,7 @@ function formatJSON(tree, config) {
     summary,
     capabilities
   };
-  return JSON.stringify(output, null, JSON_INDENT);
+  return JSON.stringify(output, null, JSON_INDENT3);
 }
 function nodeToJSON(node) {
   const displayNumber = getDisplayNumber(node);
@@ -2302,26 +3014,32 @@ function formatStatus(status) {
 }
 
 // src/commands/spec/status.ts
+var DEFAULT_FORMAT = "text";
+function buildMissingDirectoryMessage() {
+  const {
+    root,
+    work: {
+      dir,
+      statusDirs: { doing }
+    }
+  } = DEFAULT_CONFIG.specs;
+  return `Directory ${root}/${dir}/${doing} not found.`;
+}
 async function statusCommand(options = {}) {
-  const cwd = options.cwd || process.cwd();
-  const format2 = options.format || "text";
+  const cwd = options.cwd ?? process.cwd();
+  const format2 = options.format ?? DEFAULT_FORMAT;
   const scanner = new Scanner(cwd, DEFAULT_CONFIG);
   let workItems;
   try {
     workItems = await scanner.scan();
   } catch (error) {
     if (error instanceof Error && error.message.includes("ENOENT")) {
-      const doingPath = `${DEFAULT_CONFIG.specs.root}/${DEFAULT_CONFIG.specs.work.dir}/${DEFAULT_CONFIG.specs.work.statusDirs.doing}`;
-      throw new Error(
-        `Directory ${doingPath} not found.
-
-This command is for legacy specs/ projects. For CODE framework projects, check the spx/ directory for specifications.`
-      );
+      throw new Error(buildMissingDirectoryMessage());
     }
     throw error;
   }
   if (workItems.length === 0) {
-    return `No work items found in ${DEFAULT_CONFIG.specs.root}/${DEFAULT_CONFIG.specs.work.dir}/${DEFAULT_CONFIG.specs.work.statusDirs.doing}`;
+    return "No work items found in specs/work/doing";
   }
   const tree = await buildTree(workItems);
   switch (format2) {
@@ -2332,17 +3050,16 @@ This command is for legacy specs/ projects. For CODE framework projects, check t
     case "table":
       return formatTable(tree);
     case "text":
-    default:
       return formatText(tree);
   }
 }
 
 // src/spec/apply/exclude/adapters/detect.ts
-import { join as join8 } from "path";
+import { join as join9 } from "path";
 
 // src/spec/apply/exclude/constants.ts
 var SPX_PREFIX = "spx/";
-var NODE_SUFFIXES = [".outcome/", ".enabler/", ".capability/", ".feature/", ".story/"];
+var NODE_SUFFIXES2 = [".outcome/", ".enabler/", ".capability/", ".feature/", ".story/"];
 var COMMENT_CHAR = "#";
 var EXCLUDE_FILENAME = "EXCLUDE";
 
@@ -2362,7 +3079,7 @@ function toPyrightPath(node) {
 }
 function isExcludedEntry(val) {
   const hasPrefix = val.includes(SPX_PREFIX);
-  const hasSuffix = NODE_SUFFIXES.some((suffix) => val.includes(suffix));
+  const hasSuffix = NODE_SUFFIXES2.some((suffix) => val.includes(suffix));
   return hasPrefix && hasSuffix;
 }
 
@@ -2465,7 +3182,7 @@ var pythonAdapter = {
 var ADAPTERS = [pythonAdapter];
 async function detectLanguage(projectRoot, deps) {
   for (const adapter of ADAPTERS) {
-    const configPath = join8(projectRoot, adapter.configFile);
+    const configPath = join9(projectRoot, adapter.configFile);
     const exists = await deps.fileExists(configPath);
     if (exists) {
       return adapter;
@@ -2510,15 +3227,15 @@ var APPLY_HELP = buildApplyHelp();
 // src/spec/apply/exclude/exclude-file.ts
 var TOML_UNSAFE_PATTERN = /["\\\n\r\t]/;
 var PATH_TRAVERSAL_PATTERN = /(?:^|\/)\.\.(?:\/|$)/;
-function validateNodePath(path8) {
-  if (path8.startsWith("/")) {
-    return `absolute path rejected: ${path8}`;
+function validateNodePath(path9) {
+  if (path9.startsWith("/")) {
+    return `absolute path rejected: ${path9}`;
   }
-  if (PATH_TRAVERSAL_PATTERN.test(path8)) {
-    return `path traversal rejected: ${path8}`;
+  if (PATH_TRAVERSAL_PATTERN.test(path9)) {
+    return `path traversal rejected: ${path9}`;
   }
-  if (TOML_UNSAFE_PATTERN.test(path8)) {
-    return `TOML-unsafe characters rejected: ${path8}`;
+  if (TOML_UNSAFE_PATTERN.test(path9)) {
+    return `TOML-unsafe characters rejected: ${path9}`;
   }
   return null;
 }
@@ -2527,10 +3244,10 @@ function readExcludedNodes(content) {
 }
 
 // src/spec/apply/exclude/command.ts
-import { join as join9 } from "path";
+import { join as join10 } from "path";
 async function applyExcludeCommand(options) {
   const { cwd, deps } = options;
-  const excludePath = join9(cwd, SPX_PREFIX, EXCLUDE_FILENAME);
+  const excludePath = join10(cwd, SPX_PREFIX, EXCLUDE_FILENAME);
   const excludeExists = await deps.fileExists(excludePath);
   if (!excludeExists) {
     return { exitCode: 1, output: `error: ${excludePath} not found` };
@@ -2539,7 +3256,7 @@ async function applyExcludeCommand(options) {
   if (!adapter) {
     return { exitCode: 1, output: "error: no supported config file found (checked: pyproject.toml)" };
   }
-  const configPath = join9(cwd, adapter.configFile);
+  const configPath = join10(cwd, adapter.configFile);
   const excludeContent = await deps.readFile(excludePath);
   const configContent = await deps.readFile(configPath);
   const nodes = readExcludedNodes(excludeContent);
@@ -2554,77 +3271,541 @@ async function applyExcludeCommand(options) {
       output: `Updated ${adapter.configFile} from spx/EXCLUDE (${nodes.length} nodes).`
     };
   }
-  return { exitCode: 0, output: `${adapter.configFile} is already in sync with spx/EXCLUDE.` };
+  return { exitCode: 0, output: `${adapter.configFile} is already in sync with spx/EXCLUDE.` };
+}
+
+// src/domains/spec/index.ts
+var VALID_STATUS_FORMATS = [
+  "text",
+  "json",
+  "markdown",
+  "table"
+];
+function handleCommandError(error) {
+  console.error("Error:", error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}
+function resolveStatusFormat(options) {
+  if (options.json === true) {
+    return "json";
+  }
+  if (options.format === void 0) {
+    return "text";
+  }
+  if (VALID_STATUS_FORMATS.includes(options.format)) {
+    return options.format;
+  }
+  throw new Error(
+    `Invalid format "${options.format}". Must be one of: ${VALID_STATUS_FORMATS.join(", ")}`
+  );
+}
+function registerSpecCommands(specCmd) {
+  specCmd.command("status").description("Get project status").option("--json", "Output as JSON").option("--format <format>", "Output format (text|json|markdown|table)").action(async (options) => {
+    try {
+      const output = await statusCommand({
+        cwd: process.cwd(),
+        format: resolveStatusFormat(options)
+      });
+      console.log(output);
+    } catch (error) {
+      handleCommandError(error);
+    }
+  });
+  specCmd.command("next").description("Find next work item to work on").action(async () => {
+    try {
+      const output = await nextCommand({ cwd: process.cwd() });
+      console.log(output);
+    } catch (error) {
+      handleCommandError(error);
+    }
+  });
+  specCmd.command("apply").description("Apply spec-tree state to project configuration").addHelpText("after", APPLY_HELP).action(async () => {
+    try {
+      const result = await applyExcludeCommand({
+        cwd: process.cwd(),
+        deps: {
+          readFile: (path9) => readFile7(path9, "utf-8"),
+          writeFile: (path9, content) => writeFile2(path9, content, "utf-8"),
+          fileExists: async (path9) => {
+            try {
+              await access2(path9);
+              return true;
+            } catch {
+              return false;
+            }
+          }
+        }
+      });
+      if (result.output) console.log(result.output);
+      process.exit(result.exitCode);
+    } catch (error) {
+      handleCommandError(error);
+    }
+  });
+}
+var specDomain = {
+  name: "spec",
+  description: "Manage spec workflow",
+  register: (program2) => {
+    const specCmd = program2.command("spec").description("Manage spec workflow");
+    registerSpecCommands(specCmd);
+  }
+};
+
+// src/validation/literal/allowlist-existing.ts
+import { readFile as readFile10, rename as rename4, writeFile as writeFile3 } from "fs/promises";
+import { dirname as dirname3, join as join13 } from "path";
+import { parse as tomlParse, stringify as tomlStringify } from "smol-toml";
+import { Document, isMap, parseDocument } from "yaml";
+
+// src/validation/literal/index.ts
+import { readFile as readFile9 } from "fs/promises";
+import { isAbsolute as isAbsolute2, relative as relative3, resolve as resolve5 } from "path";
+
+// src/validation/literal/detector.ts
+import { parse as parseTypeScript } from "@typescript-eslint/parser";
+import { visitorKeys as typescriptVisitorKeys } from "@typescript-eslint/visitor-keys";
+var REMEDIATION = {
+  IMPORT_FROM_SOURCE: "import-from-source",
+  EXTRACT_TO_SHARED_TEST_SUPPORT: "extract-to-shared-test-support"
+};
+var defaultVisitorKeys = typescriptVisitorKeys;
+var MODULE_NAMING_SKIP = {
+  ImportDeclaration: /* @__PURE__ */ new Set(["source"]),
+  ExportNamedDeclaration: /* @__PURE__ */ new Set(["source"]),
+  ExportAllDeclaration: /* @__PURE__ */ new Set(["source"]),
+  ImportExpression: /* @__PURE__ */ new Set(["source"]),
+  TSImportType: /* @__PURE__ */ new Set(["source", "argument"]),
+  TSExternalModuleReference: /* @__PURE__ */ new Set(["expression"])
+};
+var EMPTY_SKIP = /* @__PURE__ */ new Set();
+function collectLiterals(source, filename, options) {
+  const ast = parseTypeScript(source, {
+    loc: true,
+    range: true,
+    comment: false,
+    jsx: true,
+    ecmaVersion: "latest",
+    sourceType: "module"
+  });
+  const out = [];
+  walk(ast, filename, options, out);
+  return out;
+}
+function walk(node, filename, options, out) {
+  emitLiteral(node, filename, options, out);
+  const keys = options.visitorKeys[node.type];
+  if (!keys) {
+    return;
+  }
+  const skip = MODULE_NAMING_SKIP[node.type] ?? EMPTY_SKIP;
+  for (const key of keys) {
+    if (skip.has(key)) continue;
+    const child = node[key];
+    if (Array.isArray(child)) {
+      for (const item of child) {
+        if (isNode(item)) walk(item, filename, options, out);
+      }
+    } else if (isNode(child)) {
+      walk(child, filename, options, out);
+    }
+  }
+}
+function isNode(value) {
+  return typeof value === "object" && value !== null && typeof value.type === "string";
+}
+function emitLiteral(node, filename, options, out) {
+  const line = node.loc?.start?.line ?? 0;
+  if (node.type === "Literal") {
+    if (typeof node.value === "string") {
+      if (node.value.length >= options.minStringLength) {
+        out.push({ kind: "string", value: node.value, loc: { file: filename, line } });
+      }
+    } else if (typeof node.value === "number") {
+      const raw = typeof node.raw === "string" ? node.raw : String(node.value);
+      if (isMeaningfulNumber(raw, options.minNumberDigits)) {
+        out.push({ kind: "number", value: String(node.value), loc: { file: filename, line } });
+      }
+    }
+    return;
+  }
+  if (node.type === "TemplateElement") {
+    const value = node.value;
+    const cooked = value?.cooked ?? "";
+    if (cooked.length >= options.minStringLength) {
+      out.push({ kind: "string", value: cooked, loc: { file: filename, line } });
+    }
+  }
+}
+function isMeaningfulNumber(raw, minDigits) {
+  const digits = raw.replace(/[^0-9]/g, "");
+  return digits.length >= minDigits;
+}
+function buildIndex(occurrences) {
+  const map = /* @__PURE__ */ new Map();
+  for (const occ of occurrences) {
+    const key = makeKey(occ.kind, occ.value);
+    const existing = map.get(key);
+    if (existing) {
+      existing.push(occ.loc);
+    } else {
+      map.set(key, [occ.loc]);
+    }
+  }
+  return map;
+}
+function makeKey(kind, value) {
+  return `${kind}\0${value}`;
+}
+function splitKey(key) {
+  const idx = key.indexOf("\0");
+  return { kind: key.slice(0, idx), value: key.slice(idx + 1) };
+}
+function detectReuse(input) {
+  const srcReuse = [];
+  const testDupe = [];
+  const testIndex = /* @__PURE__ */ new Map();
+  for (const [file, occurrences] of input.testOccurrencesByFile) {
+    for (const occ of occurrences) {
+      if (input.allowlist.has(occ.value)) continue;
+      const key = makeKey(occ.kind, occ.value);
+      let byFile = testIndex.get(key);
+      if (!byFile) {
+        byFile = /* @__PURE__ */ new Map();
+        testIndex.set(key, byFile);
+      }
+      const locsInFile = byFile.get(file);
+      if (locsInFile) locsInFile.push(occ.loc);
+      else byFile.set(file, [occ.loc]);
+    }
+  }
+  for (const [key, byFile] of testIndex) {
+    const { kind, value } = splitKey(key);
+    const srcLocs = input.srcIndex.get(key);
+    const allTestLocs = [];
+    for (const locs of byFile.values()) allTestLocs.push(...locs);
+    if (srcLocs && srcLocs.length > 0) {
+      for (const testLoc of allTestLocs) {
+        srcReuse.push({
+          test: testLoc,
+          kind,
+          value,
+          src: srcLocs,
+          remediation: REMEDIATION.IMPORT_FROM_SOURCE
+        });
+      }
+    } else if (byFile.size >= 2) {
+      for (let i = 0; i < allTestLocs.length; i += 1) {
+        const otherTests = [...allTestLocs.slice(0, i), ...allTestLocs.slice(i + 1)];
+        testDupe.push({
+          test: allTestLocs[i],
+          kind,
+          value,
+          otherTests,
+          remediation: REMEDIATION.EXTRACT_TO_SHARED_TEST_SUPPORT
+        });
+      }
+    }
+  }
+  return { srcReuse, testDupe };
+}
+
+// src/validation/literal/exclude.ts
+import { readFile as readFile8 } from "fs/promises";
+import { join as join11 } from "path";
+var EXCLUDE_FILENAME2 = "EXCLUDE";
+var SPX_DIR = "spx";
+async function readExcludePaths(projectRoot) {
+  const filePath = join11(projectRoot, SPX_DIR, EXCLUDE_FILENAME2);
+  try {
+    const content = await readFile8(filePath, "utf8");
+    return parseExcludeContent(content);
+  } catch (err) {
+    if (isNodeError(err) && err.code === "ENOENT") {
+      return [];
+    }
+    throw err;
+  }
+}
+function isUnderExcluded(relPath, excludePaths) {
+  for (const raw of excludePaths) {
+    const prefix = `${SPX_DIR}/${raw}`;
+    if (relPath === prefix || relPath.startsWith(`${prefix}/`)) {
+      return true;
+    }
+  }
+  return false;
+}
+function parseExcludeContent(content) {
+  return content.split("\n").map((line) => line.trim()).filter((line) => line.length > 0 && !line.startsWith("#"));
+}
+function isNodeError(err) {
+  return typeof err === "object" && err !== null && "code" in err;
+}
+
+// src/validation/literal/walker.ts
+import { readdir as readdir6 } from "fs/promises";
+import { join as join12, relative as relative2 } from "path";
+var ARTIFACT_DIRECTORIES = /* @__PURE__ */ new Set([
+  "node_modules",
+  "dist",
+  "build",
+  ".next",
+  ".source",
+  ".git",
+  "out",
+  "coverage"
+]);
+var TYPESCRIPT_EXTENSIONS = /* @__PURE__ */ new Set([".ts", ".tsx"]);
+var DECLARATION_SUFFIX = ".d.ts";
+async function walkTypescriptFiles(projectRoot, excludePaths) {
+  const out = [];
+  await walk2(projectRoot, projectRoot, excludePaths, out);
+  return out;
+}
+async function walk2(dir, projectRoot, excludePaths, out) {
+  let entries;
+  try {
+    entries = await readdir6(dir, { withFileTypes: true });
+  } catch (err) {
+    if (isNodeError2(err) && (err.code === "ENOENT" || err.code === "ENOTDIR")) {
+      return;
+    }
+    throw err;
+  }
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (ARTIFACT_DIRECTORIES.has(entry.name)) continue;
+      const subdir = join12(dir, entry.name);
+      const rel = relative2(projectRoot, subdir);
+      if (isUnderExcluded(rel, excludePaths)) continue;
+      await walk2(subdir, projectRoot, excludePaths, out);
+    } else if (entry.isFile()) {
+      if (!isTypescriptSource(entry.name)) continue;
+      out.push(join12(dir, entry.name));
+    }
+  }
+}
+function isTypescriptSource(name) {
+  if (name.endsWith(DECLARATION_SUFFIX)) return false;
+  const ext = extensionOf(name);
+  return TYPESCRIPT_EXTENSIONS.has(ext);
+}
+function extensionOf(name) {
+  const idx = name.lastIndexOf(".");
+  return idx === -1 ? "" : name.slice(idx);
+}
+function isNodeError2(err) {
+  return typeof err === "object" && err !== null && "code" in err;
+}
+function isTestFile(relPath) {
+  return /\.test\.tsx?$/.test(relPath);
+}
+
+// src/validation/literal/index.ts
+async function validateLiteralReuse(input) {
+  const config = input.config ?? literalConfigDescriptor.defaults;
+  const excludePaths = await readExcludePaths(input.projectRoot);
+  const candidateFiles = input.files ? input.files.map((f) => isAbsolute2(f) ? f : resolve5(input.projectRoot, f)) : await walkTypescriptFiles(input.projectRoot, excludePaths);
+  const collectOptions = {
+    visitorKeys: defaultVisitorKeys,
+    minStringLength: config.minStringLength,
+    minNumberDigits: config.minNumberDigits
+  };
+  const srcOccurrences = [];
+  const testOccurrencesByFile = /* @__PURE__ */ new Map();
+  const indexedOccurrencesByFile = /* @__PURE__ */ new Map();
+  for (const abs of candidateFiles) {
+    const rel = relative3(input.projectRoot, abs).split(/[\\/]/g).join("/");
+    if (isUnderExcluded(rel, excludePaths)) continue;
+    const content = await readSafe(abs);
+    if (content === null) continue;
+    const occurrences = collectLiterals(content, rel, collectOptions);
+    indexedOccurrencesByFile.set(rel, occurrences);
+    if (isTestFile(rel)) {
+      testOccurrencesByFile.set(rel, occurrences);
+    } else {
+      srcOccurrences.push(...occurrences);
+    }
+  }
+  const srcIndex = buildIndex(srcOccurrences);
+  const findings = detectReuse({
+    srcIndex,
+    testOccurrencesByFile,
+    allowlist: resolveAllowlist(config.allowlist)
+  });
+  return { findings, indexedOccurrencesByFile };
+}
+async function readSafe(path9) {
+  try {
+    return await readFile9(path9, "utf8");
+  } catch (err) {
+    if (typeof err === "object" && err !== null && "code" in err) {
+      const code = err.code;
+      if (code === "ENOENT" || code === "EISDIR") return null;
+    }
+    throw err;
+  }
 }
 
-// src/domains/spec/index.ts
-function registerSpecCommands(specCmd) {
-  specCmd.command("status").description("Get project status").option("--json", "Output as JSON").option("--format <format>", "Output format (text|json|markdown|table)").action(async (options) => {
-    try {
-      let format2 = "text";
-      if (options.json) {
-        format2 = "json";
-      } else if (options.format) {
-        const validFormats = ["text", "json", "markdown", "table"];
-        if (validFormats.includes(options.format)) {
-          format2 = options.format;
-        } else {
-          console.error(
-            `Error: Invalid format "${options.format}". Must be one of: ${validFormats.join(", ")}`
-          );
-          process.exit(1);
-        }
+// src/validation/literal/allowlist-existing.ts
+var EXIT_OK = 0;
+var EXIT_ERROR = 1;
+var DEFAULT_FORMAT2 = "yaml";
+var ALLOWLIST_INCLUDE_PATH = [LITERAL_SECTION, "allowlist", "include"];
+var TEMP_FILE_PREFIX = ".spx-allowlist-existing-";
+var TEMP_FILE_SUFFIX = ".tmp";
+var RANDOM_BASE = 36;
+var RANDOM_PREFIX_SLICE = 2;
+var RANDOM_TOKEN_LENGTH = 10;
+var JSON_INDENT4 = 2;
+var FORMAT_FILENAMES = {
+  json: CONFIG_FILENAMES.json,
+  yaml: CONFIG_FILENAMES.yaml,
+  toml: CONFIG_FILENAMES.toml
+};
+var DETECTION_ORDER = ["json", "yaml", "toml"];
+var productionReader = {
+  async read(projectRoot) {
+    const detected = [];
+    for (const format2 of DETECTION_ORDER) {
+      const filename = FORMAT_FILENAMES[format2];
+      const path9 = join13(projectRoot, filename);
+      try {
+        const raw = await readFile10(path9, "utf8");
+        detected.push({ path: path9, format: format2, raw });
+      } catch (error) {
+        if (!isFileNotFound2(error)) throw error;
       }
-      const output = await statusCommand({ cwd: process.cwd(), format: format2 });
-      console.log(output);
-    } catch (error) {
-      console.error(
-        "Error:",
-        error instanceof Error ? error.message : String(error)
-      );
-      process.exit(1);
     }
-  });
-  specCmd.command("next").description("Find next work item to work on").action(async () => {
-    try {
-      const output = await nextCommand({ cwd: process.cwd() });
-      console.log(output);
-    } catch (error) {
-      console.error(
-        "Error:",
-        error instanceof Error ? error.message : String(error)
-      );
-      process.exit(1);
+    if (detected.length === 0) return { kind: "absent" };
+    if (detected.length > 1) {
+      return { kind: "ambiguous", detected: detected.map((file) => FORMAT_FILENAMES[file.format]) };
     }
+    return { kind: "ok", file: detected[0] };
+  }
+};
+var productionWriter = {
+  async write(filePath, content) {
+    const dir = dirname3(filePath);
+    const random = Math.random().toString(RANDOM_BASE).slice(RANDOM_PREFIX_SLICE, RANDOM_PREFIX_SLICE + RANDOM_TOKEN_LENGTH);
+    const tmpPath = join13(dir, `${TEMP_FILE_PREFIX}${random}${TEMP_FILE_SUFFIX}`);
+    await writeFile3(tmpPath, content, "utf8");
+    await rename4(tmpPath, filePath);
+  }
+};
+async function allowlistExisting(options) {
+  const reader = options.reader ?? productionReader;
+  const writer = options.writer ?? productionWriter;
+  const readResult = await reader.read(options.projectRoot);
+  if (readResult.kind === "ambiguous") {
+    const names = readResult.detected.join(", ");
+    return { exitCode: EXIT_ERROR, output: `multiple config files found: ${names}` };
+  }
+  const currentLiteralConfig = readCurrentLiteralConfig(readResult);
+  const detection = await validateLiteralReuse({
+    projectRoot: options.projectRoot,
+    config: currentLiteralConfig
   });
-  specCmd.command("apply").description("Apply spec-tree state to project configuration").addHelpText("after", APPLY_HELP).action(async () => {
-    const result = await applyExcludeCommand({
-      cwd: process.cwd(),
-      deps: {
-        readFile: (path8) => readFile5(path8, "utf-8"),
-        writeFile: (path8, content) => writeFile2(path8, content, "utf-8"),
-        fileExists: async (path8) => {
-          try {
-            await access2(path8);
-            return true;
-          } catch {
-            return false;
-          }
-        }
-      }
-    });
-    if (result.output) console.log(result.output);
-    process.exit(result.exitCode);
-  });
+  const findingValues = collectFindingValues(detection.findings);
+  const updatedInclude = computeUpdatedInclude(
+    currentLiteralConfig.allowlist.include,
+    findingValues
+  );
+  const target = readResult.kind === "ok" ? readResult.file : {
+    path: join13(options.projectRoot, FORMAT_FILENAMES[DEFAULT_FORMAT2]),
+    format: DEFAULT_FORMAT2,
+    raw: ""
+  };
+  const serialized = serializeWithUpdatedInclude(target, updatedInclude);
+  await writer.write(target.path, serialized);
+  return { exitCode: EXIT_OK, output: "" };
+}
+function readCurrentLiteralConfig(read) {
+  if (read.kind !== "ok") return literalConfigDescriptor.defaults;
+  const sections = parseSections2(read.file);
+  const literalRaw = sections[LITERAL_SECTION];
+  if (literalRaw === void 0) return literalConfigDescriptor.defaults;
+  const validated = literalConfigDescriptor.validate(literalRaw);
+  return validated.ok ? validated.value : literalConfigDescriptor.defaults;
+}
+function parseSections2(file) {
+  if (file.raw.trim() === "") return {};
+  switch (file.format) {
+    case "json":
+      return JSON.parse(file.raw);
+    case "yaml": {
+      const parsed = parseDocument(file.raw).toJS({ maxAliasCount: 0 });
+      return parsed ?? {};
+    }
+    case "toml":
+      return tomlParse(file.raw);
+  }
+}
+function collectFindingValues(findings) {
+  const values = /* @__PURE__ */ new Set();
+  for (const finding of findings.srcReuse) values.add(finding.value);
+  for (const finding of findings.testDupe) values.add(finding.value);
+  return [...values];
+}
+function computeUpdatedInclude(existing, findingValues) {
+  const existingArr = existing ?? [];
+  const existingSet = new Set(existingArr);
+  const additions = findingValues.filter((value) => !existingSet.has(value)).sort();
+  return [...existingArr, ...additions];
+}
+function serializeWithUpdatedInclude(target, include) {
+  switch (target.format) {
+    case "yaml":
+      return serializeYaml(target.raw, include);
+    case "json":
+      return serializeJson(target.raw, include);
+    case "toml":
+      return serializeToml(target.raw, include);
+  }
 }
-var specDomain = {
-  name: "spec",
-  description: "Manage spec workflow",
-  register: (program2) => {
-    const specCmd = program2.command("spec").description("Manage spec workflow");
-    registerSpecCommands(specCmd);
+function serializeYaml(raw, include) {
+  const doc = isEffectivelyEmpty(raw, "yaml") ? new Document({}) : parseDocument(raw);
+  doc.setIn([...ALLOWLIST_INCLUDE_PATH], [...include]);
+  return doc.toString();
+}
+function serializeJson(raw, include) {
+  const obj = isEffectivelyEmpty(raw, "json") ? {} : JSON.parse(raw);
+  setNested(obj, [...ALLOWLIST_INCLUDE_PATH], [...include]);
+  return JSON.stringify(obj, null, JSON_INDENT4) + "\n";
+}
+function serializeToml(raw, include) {
+  const obj = isEffectivelyEmpty(raw, "toml") ? {} : tomlParse(raw);
+  setNested(obj, [...ALLOWLIST_INCLUDE_PATH], [...include]);
+  return tomlStringify(obj);
+}
+function isEffectivelyEmpty(raw, format2) {
+  if (raw.trim() === "") return true;
+  if (format2 === "yaml") {
+    const doc = parseDocument(raw);
+    if (doc.contents === null) return true;
+    if (isMap(doc.contents) && doc.contents.items.length === 0) return true;
   }
-};
+  return false;
+}
+function setNested(target, path9, value) {
+  let cursor = target;
+  for (let i = 0; i < path9.length - 1; i += 1) {
+    const key = path9[i];
+    const existing = cursor[key];
+    if (typeof existing === "object" && existing !== null && !Array.isArray(existing)) {
+      cursor = existing;
+    } else {
+      const fresh = {};
+      cursor[key] = fresh;
+      cursor = fresh;
+    }
+  }
+  cursor[path9[path9.length - 1]] = value;
+}
+function isFileNotFound2(error) {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
 
 // node_modules/.pnpm/jsonc-parser@3.3.1/node_modules/jsonc-parser/lib/esm/impl/scanner.js
 function createScanner(text, ignoreTrivia = false) {
@@ -3486,15 +4667,15 @@ var ParseErrorCode;
 })(ParseErrorCode || (ParseErrorCode = {}));
 
 // src/validation/config/scope.ts
-import { existsSync, readdirSync, readFileSync } from "fs";
-import { join as join10 } from "path";
+import { existsSync as existsSync2, readdirSync, readFileSync } from "fs";
+import { join as join14 } from "path";
 var TSCONFIG_FILES = {
   full: "tsconfig.json",
   production: "tsconfig.production.json"
 };
 var defaultScopeDeps = {
   readFileSync,
-  existsSync,
+  existsSync: existsSync2,
   readdirSync
 };
 function parseTypeScriptConfig(configPath, deps = defaultScopeDeps) {
@@ -3534,7 +4715,7 @@ function hasTypeScriptFilesRecursive(dirPath, maxDepth = 2, deps = defaultScopeD
     if (hasDirectTsFiles) return true;
     const subdirs = items.filter((item) => item.isDirectory() && !item.name.startsWith("."));
     for (const subdir of subdirs.slice(0, 5)) {
-      if (hasTypeScriptFilesRecursive(join10(dirPath, subdir.name), maxDepth - 1, deps)) {
+      if (hasTypeScriptFilesRecursive(join14(dirPath, subdir.name), maxDepth - 1, deps)) {
         return true;
       }
     }
@@ -3595,7 +4776,7 @@ function getTypeScriptScope(scope, deps = defaultScopeDeps) {
 }
 
 // src/validation/discovery/tool-finder.ts
-import { execSync } from "child_process";
+import { execSync as execSync2 } from "child_process";
 import fs6 from "fs";
 import { createRequire } from "module";
 import path7 from "path";
@@ -3643,7 +4824,7 @@ var defaultToolDiscoveryDeps = {
   existsSync: fs6.existsSync,
   whichSync: (tool) => {
     try {
-      const result = execSync(`which ${tool}`, {
+      const result = execSync2(`which ${tool}`, {
         encoding: "utf-8",
         stdio: ["pipe", "pipe", "pipe"]
       });
@@ -3703,44 +4884,32 @@ function formatSkipMessage(stepName, result) {
   return TOOL_DISCOVERY.MESSAGES.SKIP_FORMAT(stepName, result.notFound.tool);
 }
 
-// src/validation/steps/circular.ts
-import madge from "madge";
-
-// src/validation/steps/constants.ts
-var STEP_IDS = {
-  CIRCULAR: "circular-deps",
-  ESLINT: "eslint",
-  TYPESCRIPT: "typescript",
-  KNIP: "knip"
-};
-var STEP_NAMES = {
-  CIRCULAR: "Circular Dependencies",
-  ESLINT: "ESLint",
-  TYPESCRIPT: "TypeScript",
-  KNIP: "Unused Code"
-};
-var STEP_DESCRIPTIONS = {
-  CIRCULAR: "Checking for circular dependencies",
-  ESLINT: "Validating ESLint compliance",
-  TYPESCRIPT: "Validating TypeScript",
-  KNIP: "Detecting unused exports, dependencies, and files"
-};
-var CACHE_PATHS = {
-  ESLINT: "dist/.eslintcache",
-  TIMINGS: "dist/.validation-timings.json"
-};
-var VALIDATION_KEYS = {
-  TYPESCRIPT: "TYPESCRIPT",
-  ESLINT: "ESLINT",
-  KNIP: "KNIP"
-};
-var VALIDATION_DEFAULTS = {
-  [VALIDATION_KEYS.TYPESCRIPT]: true,
-  [VALIDATION_KEYS.ESLINT]: true,
-  [VALIDATION_KEYS.KNIP]: false
+// src/validation/discovery/language-finder.ts
+import fs7 from "fs";
+import path8 from "path";
+var TYPESCRIPT_MARKER = "tsconfig.json";
+var ESLINT_CONFIG_FILES = [
+  "eslint.config.ts",
+  "eslint.config.js",
+  "eslint.config.mjs",
+  "eslint.config.cjs"
+];
+var defaultLanguageDetectionDeps = {
+  existsSync: fs7.existsSync
 };
+function detectTypeScript(projectRoot, deps = defaultLanguageDetectionDeps) {
+  const present = deps.existsSync(path8.join(projectRoot, TYPESCRIPT_MARKER));
+  if (!present) {
+    return { present: false };
+  }
+  const eslintConfigFile = ESLINT_CONFIG_FILES.find(
+    (configFile) => deps.existsSync(path8.join(projectRoot, configFile))
+  );
+  return eslintConfigFile === void 0 ? { present: true } : { present: true, eslintConfigFile };
+}
 
 // src/validation/steps/circular.ts
+import madge from "madge";
 var defaultCircularDeps = {
   madge
 };
@@ -3776,34 +4945,20 @@ async function validateCircularDependencies(scope, typescriptScope, deps = defau
     return { success: false, error: errorMessage };
   }
 }
-var circularDependencyStep = {
-  id: STEP_IDS.CIRCULAR,
-  name: STEP_NAMES.CIRCULAR,
-  description: STEP_DESCRIPTIONS.CIRCULAR,
-  enabled: (context) => !context.isFileSpecificMode && context.enabledValidations[VALIDATION_KEYS.TYPESCRIPT] === true,
-  execute: async (context) => {
-    const startTime = performance.now();
-    try {
-      const result = await validateCircularDependencies(context.scope, context.scopeConfig);
-      return {
-        success: result.success,
-        error: result.error,
-        duration: performance.now() - startTime
-      };
-    } catch (error) {
-      return {
-        success: false,
-        error: error instanceof Error ? error.message : String(error),
-        duration: performance.now() - startTime
-      };
-    }
-  }
-};
 
 // src/commands/validation/circular.ts
+var TYPESCRIPT_ABSENT_MESSAGE = "\u23ED Skipping Circular dependencies (TypeScript not detected in project)";
 async function circularCommand(options) {
   const { cwd, quiet } = options;
   const startTime = Date.now();
+  const tsDetection = detectTypeScript(cwd);
+  if (!tsDetection.present) {
+    return {
+      exitCode: 0,
+      output: quiet ? "" : TYPESCRIPT_ABSENT_MESSAGE,
+      durationMs: Date.now() - startTime
+    };
+  }
   const toolResult = await discoverTool("madge", { projectRoot: cwd });
   if (!toolResult.found) {
     const skipMessage = formatSkipMessage("circular dependency check", toolResult);
@@ -3864,20 +5019,27 @@ var EXECUTION_MODES = {
   WRITE: "write"
 };
 
+// src/validation/steps/constants.ts
+var CACHE_PATHS = {
+  ESLINT: "dist/.eslintcache",
+  TIMINGS: "dist/.validation-timings.json"
+};
+
 // src/validation/steps/eslint.ts
 var defaultEslintProcessRunner = { spawn };
+var DEFAULT_ESLINT_CONFIG_FILE = "eslint.config.ts";
 function buildEslintArgs(context) {
-  const { validatedFiles, mode, cacheFile } = context;
+  const { validatedFiles, mode, cacheFile, configFile = DEFAULT_ESLINT_CONFIG_FILE } = context;
   const fixArg = mode === EXECUTION_MODES.WRITE ? ["--fix"] : [];
   const cacheArgs = ["--cache", "--cache-location", cacheFile];
   if (validatedFiles && validatedFiles.length > 0) {
-    return ["eslint", "--config", "eslint.config.ts", ...cacheArgs, ...fixArg, "--", ...validatedFiles];
+    return ["eslint", "--config", configFile, ...cacheArgs, ...fixArg, "--", ...validatedFiles];
   }
-  return ["eslint", ".", "--config", "eslint.config.ts", ...cacheArgs, ...fixArg];
+  return ["eslint", ".", "--config", configFile, ...cacheArgs, ...fixArg];
 }
 async function validateESLint(context, runner = defaultEslintProcessRunner) {
-  const { scope, validatedFiles, mode } = context;
-  return new Promise((resolve3) => {
+  const { projectRoot, scope, validatedFiles, mode, eslintConfigFile } = context;
+  return new Promise((resolve6) => {
     if (!validatedFiles || validatedFiles.length === 0) {
       if (scope === VALIDATION_SCOPES.PRODUCTION) {
         process.env.ESLINT_PRODUCTION_ONLY = "1";
@@ -3888,57 +5050,35 @@ async function validateESLint(context, runner = defaultEslintProcessRunner) {
     const eslintArgs = buildEslintArgs({
       validatedFiles,
       mode,
-      cacheFile: CACHE_PATHS.ESLINT
+      cacheFile: CACHE_PATHS.ESLINT,
+      configFile: eslintConfigFile
     });
     const eslintProcess = runner.spawn("npx", eslintArgs, {
-      cwd: process.cwd(),
+      cwd: projectRoot,
       stdio: "inherit"
     });
     eslintProcess.on("close", (code) => {
       if (code === 0) {
-        resolve3({ success: true });
+        resolve6({ success: true });
       } else {
-        resolve3({ success: false, error: `ESLint exited with code ${code}` });
+        resolve6({ success: false, error: `ESLint exited with code ${code}` });
       }
     });
     eslintProcess.on("error", (error) => {
-      resolve3({ success: false, error: error.message });
+      resolve6({ success: false, error: error.message });
     });
   });
 }
-function validationEnabled(envVarKey, defaults = {}) {
+function validationEnabled(envVarKey, defaults2 = {}) {
   const envVar = `${envVarKey}_VALIDATION_ENABLED`;
   const explicitlyDisabled = process.env[envVar] === "0";
   const explicitlyEnabled = process.env[envVar] === "1";
-  const defaultValue = defaults[envVarKey] ?? true;
+  const defaultValue = defaults2[envVarKey] ?? true;
   if (defaultValue) {
     return !explicitlyDisabled;
   }
   return explicitlyEnabled;
 }
-var eslintStep = {
-  id: STEP_IDS.ESLINT,
-  name: STEP_NAMES.ESLINT,
-  description: STEP_DESCRIPTIONS.ESLINT,
-  enabled: (context) => context.enabledValidations[VALIDATION_KEYS.ESLINT] === true && validationEnabled(VALIDATION_KEYS.ESLINT),
-  execute: async (context) => {
-    const startTime = performance.now();
-    try {
-      const result = await validateESLint(context);
-      return {
-        success: result.success,
-        error: result.error,
-        duration: performance.now() - startTime
-      };
-    } catch (error) {
-      return {
-        success: false,
-        error: error instanceof Error ? error.message : String(error),
-        duration: performance.now() - startTime
-      };
-    }
-  }
-};
 
 // src/validation/steps/knip.ts
 import { spawn as spawn2 } from "child_process";
@@ -3949,7 +5089,7 @@ async function validateKnip(typescriptScope, runner = defaultKnipProcessRunner)
     if (analyzeDirectories.length === 0) {
       return { success: true };
     }
-    return new Promise((resolve3) => {
+    return new Promise((resolve6) => {
       const knipProcess = runner.spawn("npx", ["knip"], {
         cwd: process.cwd(),
         stdio: "pipe"
@@ -3964,17 +5104,17 @@ async function validateKnip(typescriptScope, runner = defaultKnipProcessRunner)
       });
       knipProcess.on("close", (code) => {
         if (code === 0) {
-          resolve3({ success: true });
+          resolve6({ success: true });
         } else {
           const errorOutput = knipOutput || knipError || "Unused code detected";
-          resolve3({
+          resolve6({
             success: false,
             error: errorOutput
           });
         }
       });
       knipProcess.on("error", (error) => {
-        resolve3({ success: false, error: error.message });
+        resolve6({ success: false, error: error.message });
       });
     });
   } catch (error) {
@@ -3982,29 +5122,6 @@ async function validateKnip(typescriptScope, runner = defaultKnipProcessRunner)
     return { success: false, error: errorMessage };
   }
 }
-var knipStep = {
-  id: STEP_IDS.KNIP,
-  name: STEP_NAMES.KNIP,
-  description: STEP_DESCRIPTIONS.KNIP,
-  enabled: (context) => context.enabledValidations[VALIDATION_KEYS.KNIP] === true && validationEnabled(VALIDATION_KEYS.KNIP, VALIDATION_DEFAULTS) && !context.isFileSpecificMode,
-  execute: async (context) => {
-    const startTime = performance.now();
-    try {
-      const result = await validateKnip(context.scopeConfig);
-      return {
-        success: result.success,
-        error: result.error,
-        duration: performance.now() - startTime
-      };
-    } catch (error) {
-      return {
-        success: false,
-        error: error instanceof Error ? error.message : String(error),
-        duration: performance.now() - startTime
-      };
-    }
-  }
-};
 
 // src/commands/validation/knip.ts
 async function knipCommand(options) {
@@ -4032,9 +5149,26 @@ async function knipCommand(options) {
 }
 
 // src/commands/validation/lint.ts
+var TYPESCRIPT_ABSENT_MESSAGE2 = "\u23ED Skipping ESLint (TypeScript not detected in project)";
+var MISSING_CONFIG_MESSAGE = "ESLint config not found: project has tsconfig.json but no eslint.config.{ts,js,mjs,cjs}";
 async function lintCommand(options) {
   const { cwd, scope = "full", files, fix, quiet } = options;
   const startTime = Date.now();
+  const tsDetection = detectTypeScript(cwd);
+  if (!tsDetection.present) {
+    return {
+      exitCode: 0,
+      output: quiet ? "" : TYPESCRIPT_ABSENT_MESSAGE2,
+      durationMs: Date.now() - startTime
+    };
+  }
+  if (tsDetection.eslintConfigFile === void 0) {
+    return {
+      exitCode: 1,
+      output: MISSING_CONFIG_MESSAGE,
+      durationMs: Date.now() - startTime
+    };
+  }
   const toolResult = await discoverTool("eslint", { projectRoot: cwd });
   if (!toolResult.found) {
     const skipMessage = formatSkipMessage("ESLint", toolResult);
@@ -4048,7 +5182,8 @@ async function lintCommand(options) {
     mode: fix ? "write" : "read",
     enabledValidations: { ESLINT: true },
     validatedFiles: files,
-    isFileSpecificMode: Boolean(files && files.length > 0)
+    isFileSpecificMode: Boolean(files && files.length > 0),
+    eslintConfigFile: tsDetection.eslintConfigFile
   };
   const result = await validateESLint(context);
   const durationMs = Date.now() - startTime;
@@ -4061,18 +5196,222 @@ async function lintCommand(options) {
   }
 }
 
+// src/commands/validation/literal.ts
+var EXIT_OK2 = 0;
+var EXIT_FINDINGS = 1;
+var EXIT_CONFIG_ERROR = 2;
+var TYPESCRIPT_ABSENT_MESSAGE3 = "\u23ED Skipping Literal (TypeScript not detected in project)";
+var DISABLED_MESSAGE = "\u23ED Skipping Literal (LITERAL_VALIDATION_ENABLED=0)";
+async function literalCommand(options) {
+  const start = Date.now();
+  const tsDetection = detectTypeScript(options.cwd);
+  if (!tsDetection.present) {
+    return {
+      exitCode: EXIT_OK2,
+      output: options.quiet ? "" : TYPESCRIPT_ABSENT_MESSAGE3,
+      durationMs: Date.now() - start
+    };
+  }
+  if (!validationEnabled("LITERAL")) {
+    return {
+      exitCode: EXIT_OK2,
+      output: options.quiet ? "" : DISABLED_MESSAGE,
+      durationMs: Date.now() - start
+    };
+  }
+  let resolvedConfig;
+  if (options.config !== void 0) {
+    resolvedConfig = options.config;
+  } else {
+    const loaded = await resolveConfig(options.cwd, [literalConfigDescriptor]);
+    if (!loaded.ok) {
+      return {
+        exitCode: EXIT_CONFIG_ERROR,
+        output: `Literal: \u2717 config error \u2014 ${loaded.error}`,
+        durationMs: Date.now() - start
+      };
+    }
+    resolvedConfig = loaded.value[literalConfigDescriptor.section];
+  }
+  const result = await validateLiteralReuse({
+    projectRoot: options.cwd,
+    files: options.files,
+    config: resolvedConfig
+  });
+  const totalFindings = result.findings.srcReuse.length + result.findings.testDupe.length;
+  const exitCode = totalFindings === 0 ? EXIT_OK2 : EXIT_FINDINGS;
+  const output = options.json ? JSON.stringify(result.findings) : options.quiet ? "" : totalFindings === 0 ? "Literal: \u2713 No findings" : `Literal: \u2717 ${totalFindings} finding${totalFindings === 1 ? "" : "s"}
+${formatText2(result.findings)}`;
+  return { exitCode, output, durationMs: Date.now() - start };
+}
+function formatText2(findings) {
+  const lines = [];
+  for (const f of findings.srcReuse) {
+    lines.push(
+      `[reuse] ${formatLoc(f.test)}: ${f.kind} literal "${f.value}" also in ${f.src.map(formatLoc).join(", ")} \u2014 import from source`
+    );
+  }
+  for (const f of findings.testDupe) {
+    lines.push(
+      `[dupe] ${formatLoc(f.test)}: ${f.kind} literal "${f.value}" also in ${f.otherTests.map(formatLoc).join(", ")} \u2014 extract to shared test support`
+    );
+  }
+  return lines.join("\n");
+}
+function formatLoc(loc) {
+  return `${loc.file}:${loc.line}`;
+}
+
+// src/validation/steps/markdown.ts
+import { existsSync as existsSync3, readFileSync as readFileSync2 } from "fs";
+import { basename, join as join15 } from "path";
+import { main as markdownlintMain } from "markdownlint-cli2";
+import relativeLinksRule from "markdownlint-rule-relative-links";
+var DEFAULT_DIRECTORY_NAMES = ["spx", "docs"];
+var ENABLED_RULES = {
+  MD001: true,
+  MD003: true,
+  MD009: true,
+  MD010: true,
+  MD025: true,
+  MD047: true
+};
+var MD024_DISABLED_DIRECTORIES = ["docs"];
+var ERROR_LINE_PATTERN = /^(.+?):(\d+)(?::\d+)?\s+(.+)$/;
+function buildMarkdownlintConfig(directoryName) {
+  const md024Disabled = MD024_DISABLED_DIRECTORIES.includes(
+    directoryName
+  );
+  return {
+    default: false,
+    ...ENABLED_RULES,
+    MD024: md024Disabled ? false : { siblings_only: true },
+    customRules: [relativeLinksRule]
+  };
+}
+function getDefaultDirectories(projectRoot) {
+  return DEFAULT_DIRECTORY_NAMES.map((name) => join15(projectRoot, name)).filter((dir) => existsSync3(dir));
+}
+function getExcludeGlobs(spxDir) {
+  const excludePath = join15(spxDir, EXCLUDE_FILENAME);
+  if (!existsSync3(excludePath)) {
+    return [];
+  }
+  const content = readFileSync2(excludePath, "utf-8");
+  const nodes = readExcludedNodes(content);
+  return nodes.map((node) => `${node}/**`);
+}
+var DATA_URI_PATTERN = /\bdata:/;
+function parseErrorLine(line) {
+  if (DATA_URI_PATTERN.test(line)) {
+    return null;
+  }
+  const match = ERROR_LINE_PATTERN.exec(line);
+  if (!match) {
+    return null;
+  }
+  const [, file, lineStr, detail] = match;
+  return {
+    file,
+    line: parseInt(lineStr, 10),
+    detail
+  };
+}
+async function validateMarkdown(options) {
+  const { directories, projectRoot } = options;
+  const errors = [];
+  for (const directory of directories) {
+    const dirName = basename(directory);
+    const config = buildMarkdownlintConfig(dirName);
+    const excludeGlobs = getExcludeGlobs(directory);
+    const dirErrors = await validateDirectory(directory, config, projectRoot, excludeGlobs);
+    errors.push(...dirErrors);
+  }
+  return {
+    success: errors.length === 0,
+    errors
+  };
+}
+async function validateDirectory(directory, config, projectRoot, ignoreGlobs = []) {
+  const errors = [];
+  const { customRules, ...markdownlintConfig } = config;
+  const optionsOverride = {
+    config: {
+      ...markdownlintConfig,
+      "relative-links": projectRoot ? { root_path: projectRoot } : true
+    },
+    customRules,
+    noProgress: true,
+    noBanner: true,
+    ...ignoreGlobs.length > 0 ? { ignores: ignoreGlobs } : {}
+  };
+  await markdownlintMain({
+    directory,
+    argv: ["**/*.md"],
+    optionsOverride,
+    noImport: true,
+    logMessage: () => {
+    },
+    logError: (message) => {
+      const parsed = parseErrorLine(message);
+      if (parsed) {
+        errors.push({
+          ...parsed,
+          file: join15(directory, parsed.file)
+        });
+      }
+    }
+  });
+  return errors;
+}
+
+// src/commands/validation/markdown.ts
+var MARKDOWN_EXTENSIONS = /* @__PURE__ */ new Set([".md", ".markdown"]);
+function isMarkdownOrDirectory(path9) {
+  const lastDot = path9.lastIndexOf(".");
+  if (lastDot < 0) return true;
+  const ext = path9.slice(lastDot).toLowerCase();
+  return MARKDOWN_EXTENSIONS.has(ext);
+}
+async function markdownCommand(options) {
+  const { cwd, files, quiet } = options;
+  const startTime = Date.now();
+  const markdownScopedFiles = files?.filter(isMarkdownOrDirectory);
+  const directories = markdownScopedFiles && markdownScopedFiles.length > 0 ? markdownScopedFiles : files && files.length > 0 ? [] : getDefaultDirectories(cwd);
+  if (directories.length === 0) {
+    const reason = files && files.length > 0 ? "no markdown files in --files scope" : "no spx/ or docs/ directories found";
+    const output = quiet ? "" : `Markdown: skipped (${reason})`;
+    return { exitCode: 0, output, durationMs: Date.now() - startTime };
+  }
+  const result = await validateMarkdown({
+    directories,
+    projectRoot: cwd
+  });
+  const durationMs = Date.now() - startTime;
+  if (result.success) {
+    const output = quiet ? "" : "Markdown: No issues found";
+    return { exitCode: 0, output, durationMs };
+  } else {
+    const errorLines = result.errors.map(
+      (error) => `  ${error.file}:${error.line} ${error.detail}`
+    );
+    const output = [`Markdown: ${result.errors.length} error(s) found`, ...errorLines].join("\n");
+    return { exitCode: 1, output, durationMs };
+  }
+}
+
 // src/validation/steps/typescript.ts
 import { spawn as spawn3 } from "child_process";
-import { existsSync as existsSync2, mkdirSync, rmSync, writeFileSync } from "fs";
+import { existsSync as existsSync4, mkdirSync, rmSync, writeFileSync } from "fs";
 import { mkdtemp } from "fs/promises";
 import { tmpdir } from "os";
-import { isAbsolute as isAbsolute2, join as join11 } from "path";
+import { isAbsolute as isAbsolute3, join as join16 } from "path";
 var defaultTypeScriptProcessRunner = { spawn: spawn3 };
 var defaultTypeScriptDeps = {
   mkdtemp,
   writeFileSync,
   rmSync,
-  existsSync: existsSync2,
+  existsSync: existsSync4,
   mkdirSync
 };
 function buildTypeScriptArgs(context) {
@@ -4080,19 +5419,19 @@ function buildTypeScriptArgs(context) {
   return scope === VALIDATION_SCOPES.FULL ? ["tsc", "--noEmit"] : ["tsc", "--project", configFile];
 }
 async function createFileSpecificTsconfig(scope, files, deps = defaultTypeScriptDeps) {
-  const tempDir = await deps.mkdtemp(join11(tmpdir(), "validate-ts-"));
-  const configPath = join11(tempDir, "tsconfig.json");
+  const tempDir = await deps.mkdtemp(join16(tmpdir(), "validate-ts-"));
+  const configPath = join16(tempDir, "tsconfig.json");
   const baseConfigFile = TSCONFIG_FILES[scope];
   const projectRoot = process.cwd();
-  const absoluteFiles = files.map((file) => isAbsolute2(file) ? file : join11(projectRoot, file));
+  const absoluteFiles = files.map((file) => isAbsolute3(file) ? file : join16(projectRoot, file));
   const tempConfig = {
-    extends: join11(projectRoot, baseConfigFile),
+    extends: join16(projectRoot, baseConfigFile),
     files: absoluteFiles,
     include: [],
     exclude: [],
     compilerOptions: {
       noEmit: true,
-      typeRoots: [join11(projectRoot, "node_modules", "@types")],
+      typeRoots: [join16(projectRoot, "node_modules", "@types")],
       types: ["node"]
     }
   };
@@ -4112,7 +5451,7 @@ async function validateTypeScript(scope, typescriptScope, files, runner = defaul
   if (files && files.length > 0) {
     const { configPath, cleanup } = await createFileSpecificTsconfig(scope, files, deps);
     try {
-      return await new Promise((resolve3) => {
+      return await new Promise((resolve6) => {
         const tscProcess = runner.spawn("npx", ["tsc", "--project", configPath], {
           cwd: process.cwd(),
           stdio: "inherit"
@@ -4120,14 +5459,14 @@ async function validateTypeScript(scope, typescriptScope, files, runner = defaul
         tscProcess.on("close", (code) => {
           cleanup();
           if (code === 0) {
-            resolve3({ success: true, skipped: false });
+            resolve6({ success: true, skipped: false });
           } else {
-            resolve3({ success: false, error: `TypeScript exited with code ${code}` });
+            resolve6({ success: false, error: `TypeScript exited with code ${code}` });
           }
         });
         tscProcess.on("error", (error) => {
           cleanup();
-          resolve3({ success: false, error: error.message });
+          resolve6({ success: false, error: error.message });
         });
       });
     } catch (error) {
@@ -4139,56 +5478,37 @@ async function validateTypeScript(scope, typescriptScope, files, runner = defaul
     tool = "npx";
     tscArgs = buildTypeScriptArgs({ scope, configFile });
   }
-  return new Promise((resolve3) => {
+  return new Promise((resolve6) => {
     const tscProcess = runner.spawn(tool, tscArgs, {
       cwd: process.cwd(),
       stdio: "inherit"
     });
     tscProcess.on("close", (code) => {
       if (code === 0) {
-        resolve3({ success: true, skipped: false });
+        resolve6({ success: true, skipped: false });
       } else {
-        resolve3({ success: false, error: `TypeScript exited with code ${code}` });
+        resolve6({ success: false, error: `TypeScript exited with code ${code}` });
       }
     });
     tscProcess.on("error", (error) => {
-      resolve3({ success: false, error: error.message });
+      resolve6({ success: false, error: error.message });
     });
   });
 }
-var typescriptStep = {
-  id: STEP_IDS.TYPESCRIPT,
-  name: STEP_NAMES.TYPESCRIPT,
-  description: STEP_DESCRIPTIONS.TYPESCRIPT,
-  enabled: (context) => context.enabledValidations[VALIDATION_KEYS.TYPESCRIPT] === true && validationEnabled(VALIDATION_KEYS.TYPESCRIPT),
-  execute: async (context) => {
-    const startTime = performance.now();
-    try {
-      const result = await validateTypeScript(
-        context.scope,
-        context.scopeConfig,
-        context.validatedFiles
-      );
-      return {
-        success: result.success,
-        error: result.error,
-        duration: performance.now() - startTime,
-        skipped: result.skipped
-      };
-    } catch (error) {
-      return {
-        success: false,
-        error: error instanceof Error ? error.message : String(error),
-        duration: performance.now() - startTime
-      };
-    }
-  }
-};
 
 // src/commands/validation/typescript.ts
+var TYPESCRIPT_ABSENT_MESSAGE4 = "\u23ED Skipping TypeScript (TypeScript not detected in project)";
 async function typescriptCommand(options) {
   const { cwd, scope = "full", files, quiet } = options;
   const startTime = Date.now();
+  const tsDetection = detectTypeScript(cwd);
+  if (!tsDetection.present) {
+    return {
+      exitCode: 0,
+      output: quiet ? "" : TYPESCRIPT_ABSENT_MESSAGE4,
+      durationMs: Date.now() - startTime
+    };
+  }
   const toolResult = await discoverTool("typescript", { projectRoot: cwd });
   if (!toolResult.found) {
     const skipMessage = formatSkipMessage("TypeScript", toolResult);
@@ -4207,7 +5527,7 @@ async function typescriptCommand(options) {
 }
 
 // src/commands/validation/all.ts
-var TOTAL_STEPS = 4;
+var TOTAL_STEPS = 6;
 function formatStepWithTiming(stepNumber, result, quiet) {
   if (quiet || !result.output) return "";
   const timing = result.durationMs === void 0 ? "" : ` (${formatDuration(result.durationMs)})`;
@@ -4233,6 +5553,14 @@ async function allCommand(options) {
   const tsOutput = formatStepWithTiming(4, tsResult, quiet);
   if (tsOutput) outputs.push(tsOutput);
   if (tsResult.exitCode !== 0) hasFailure = true;
+  const markdownResult = await markdownCommand({ cwd, files, quiet });
+  const markdownOutput = formatStepWithTiming(5, markdownResult, quiet);
+  if (markdownOutput) outputs.push(markdownOutput);
+  if (markdownResult.exitCode !== 0) hasFailure = true;
+  const literalResult = await literalCommand({ cwd, files, quiet, json });
+  const literalOutput = formatStepWithTiming(6, literalResult, quiet);
+  if (literalOutput) outputs.push(literalOutput);
+  if (literalResult.exitCode !== 0) hasFailure = true;
   const totalDurationMs = Date.now() - startTime;
   if (!quiet) {
     const summary = formatSummary({ success: !hasFailure, totalDurationMs });
@@ -4245,12 +5573,121 @@ async function allCommand(options) {
   };
 }
 
+// src/lib/sanitize-cli-argument.ts
+var MAX_CLI_ARGUMENT_DISPLAY_LENGTH = 120;
+var ELLIPSIS_TOKEN = "...";
+var SENTINEL_UNDEFINED = "<undefined>";
+var SENTINEL_NULL = "<null>";
+var SENTINEL_EMPTY = "<empty>";
+var CONTROL_CHAR_UPPER_BOUND = 31;
+var DEL_CHAR_CODE = 127;
+var HEX_RADIX = 16;
+var HEX_PAD = 2;
+function nonStringSentinel(type) {
+  return `<non-string:${type}>`;
+}
+function sanitizeCliArgument(input) {
+  if (input === void 0) return SENTINEL_UNDEFINED;
+  if (input === null) return SENTINEL_NULL;
+  if (typeof input !== "string") return nonStringSentinel(typeof input);
+  if (input.length === 0) return SENTINEL_EMPTY;
+  const escaped = escapeControlCharacters(input);
+  return truncate(escaped);
+}
+function escapeControlCharacters(value) {
+  let out = "";
+  for (const char of value) {
+    const code = char.codePointAt(0);
+    if (code === void 0) continue;
+    if (code <= CONTROL_CHAR_UPPER_BOUND || code === DEL_CHAR_CODE) {
+      out += `\\x${code.toString(HEX_RADIX).padStart(HEX_PAD, "0")}`;
+    } else {
+      out += char;
+    }
+  }
+  return out;
+}
+function truncate(value) {
+  if (value.length <= MAX_CLI_ARGUMENT_DISPLAY_LENGTH) return value;
+  return value.slice(0, MAX_CLI_ARGUMENT_DISPLAY_LENGTH - ELLIPSIS_TOKEN.length) + ELLIPSIS_TOKEN;
+}
+
 // src/domains/validation/index.ts
+var validationCliDefinition = {
+  domain: {
+    commandName: "validation",
+    alias: "v",
+    description: "Run code validation tools"
+  },
+  subcommands: {
+    typescript: {
+      commandName: "typescript",
+      alias: "ts",
+      description: "Run TypeScript type checking"
+    },
+    lint: {
+      commandName: "lint",
+      description: "Run ESLint"
+    },
+    circular: {
+      commandName: "circular",
+      description: "Check for circular dependencies"
+    },
+    knip: {
+      commandName: "knip",
+      description: "Detect unused code"
+    },
+    literal: {
+      commandName: "literal",
+      description: "Detect cross-file literal reuse between source and tests"
+    },
+    markdown: {
+      commandName: "markdown",
+      alias: "md",
+      description: "Validate markdown link integrity and structure"
+    },
+    all: {
+      commandName: "all",
+      description: "Run all validations"
+    }
+  },
+  commanderHelpOperands: {
+    subcommand: "help",
+    longFlag: "--help",
+    shortFlag: "-h"
+  },
+  diagnostics: {
+    unknownSubcommand: {
+      messageLabel: "unknown subcommand",
+      exitCode: 1
+    }
+  }
+};
+var validationSubcommandOperands = Object.values(validationCliDefinition.subcommands).flatMap(
+  (subcommand) => {
+    const operands = [subcommand.commandName];
+    if (subcommand.alias !== void 0) operands.push(subcommand.alias);
+    return operands;
+  }
+);
+var validationKnownOperands = /* @__PURE__ */ new Set([
+  ...validationSubcommandOperands,
+  ...Object.values(validationCliDefinition.commanderHelpOperands)
+]);
+var validationOptionPrefix = validationCliDefinition.commanderHelpOperands.longFlag.slice(0, 1);
 function addCommonOptions(cmd) {
   return cmd.option("--scope <scope>", "Validation scope (full|production)", "full").option("--files <paths...>", "Specific files/directories to validate").option("--quiet", "Suppress progress output").option("--json", "Output results as JSON");
 }
+function addValidationSubcommand(validationCmd, definition) {
+  let subcommand = validationCmd.command(definition.commandName).description(definition.description);
+  if (definition.alias !== void 0) {
+    subcommand = subcommand.alias(definition.alias);
+  }
+  return subcommand;
+}
 function registerValidationCommands(validationCmd) {
-  const tsCmd = validationCmd.command("typescript").alias("ts").description("Run TypeScript type checking").action(async (options) => {
+  const { subcommands } = validationCliDefinition;
+  const tsCmd = addValidationSubcommand(validationCmd, subcommands.typescript).action(async (options) => {
     const result = await typescriptCommand({
       cwd: process.cwd(),
       scope: options.scope,
@@ -4262,7 +5699,7 @@ function registerValidationCommands(validationCmd) {
     process.exit(result.exitCode);
   });
   addCommonOptions(tsCmd);
-  const lintCmd = validationCmd.command("lint").description("Run ESLint").option("--fix", "Auto-fix issues").action(async (options) => {
+  const lintCmd = addValidationSubcommand(validationCmd, subcommands.lint).option("--fix", "Auto-fix issues").action(async (options) => {
     const result = await lintCommand({
       cwd: process.cwd(),
       scope: options.scope,
@@ -4275,7 +5712,7 @@ function registerValidationCommands(validationCmd) {
     process.exit(result.exitCode);
   });
   addCommonOptions(lintCmd);
-  const circularCmd = validationCmd.command("circular").description("Check for circular dependencies").action(async (options) => {
+  const circularCmd = addValidationSubcommand(validationCmd, subcommands.circular).action(async (options) => {
     const result = await circularCommand({
       cwd: process.cwd(),
       quiet: options.quiet,
@@ -4285,7 +5722,7 @@ function registerValidationCommands(validationCmd) {
     process.exit(result.exitCode);
   });
   addCommonOptions(circularCmd);
-  const knipCmd = validationCmd.command("knip").description("Detect unused code").action(async (options) => {
+  const knipCmd = addValidationSubcommand(validationCmd, subcommands.knip).action(async (options) => {
     const result = await knipCommand({
       cwd: process.cwd(),
       quiet: options.quiet,
@@ -4295,7 +5732,42 @@ function registerValidationCommands(validationCmd) {
     process.exit(result.exitCode);
   });
   addCommonOptions(knipCmd);
-  const allCmd = validationCmd.command("all", { isDefault: true }).description("Run all validations").option("--fix", "Auto-fix ESLint issues").action(async (options) => {
+  const literalCmd = addValidationSubcommand(validationCmd, subcommands.literal).option(
+    "--allowlist-existing",
+    "Append every current finding's value to literal.allowlist.include and exit"
+  ).addHelpText(
+    "after",
+    "\nEnabled for TypeScript projects by default. Set LITERAL_VALIDATION_ENABLED=0\nto skip (useful when migrating a project with many existing violations)."
+  ).action(async (options) => {
+    if (options.allowlistExisting) {
+      const result2 = await allowlistExisting({ projectRoot: process.cwd() });
+      if (result2.output) console.log(result2.output);
+      process.exit(result2.exitCode);
+    }
+    const result = await literalCommand({
+      cwd: process.cwd(),
+      files: options.files,
+      quiet: options.quiet,
+      json: options.json
+    });
+    if (result.output) console.log(result.output);
+    process.exit(result.exitCode);
+  });
+  addCommonOptions(literalCmd);
+  const markdownCmd = addValidationSubcommand(validationCmd, subcommands.markdown).addHelpText(
+    "after",
+    "\nValidates spx/ and docs/ by default. Nodes listed in spx/EXCLUDE are\nskipped \u2014 use this for declared-state nodes whose [test] links point\nto files that do not exist yet."
+  ).action(async (options) => {
+    const result = await markdownCommand({
+      cwd: process.cwd(),
+      files: options.files,
+      quiet: options.quiet
+    });
+    if (result.output) console.log(result.output);
+    process.exit(result.exitCode);
+  });
+  addCommonOptions(markdownCmd);
+  const allCmd = addValidationSubcommand(validationCmd, subcommands.all).option("--fix", "Auto-fix ESLint issues").action(async (options) => {
     const result = await allCommand({
       cwd: process.cwd(),
       scope: options.scope,
@@ -4309,11 +5781,24 @@ function registerValidationCommands(validationCmd) {
   });
   addCommonOptions(allCmd);
 }
+function handleUnknownSubcommand(operands) {
+  const [first] = operands;
+  const sanitized = sanitizeCliArgument(first);
+  const { domain, diagnostics } = validationCliDefinition;
+  const { unknownSubcommand } = diagnostics;
+  process.stderr.write(`spx ${domain.commandName}: ${unknownSubcommand.messageLabel}: ${sanitized}
+`);
+  process.exit(unknownSubcommand.exitCode);
+}
 var validationDomain = {
-  name: "validation",
-  description: "Run code validation tools",
+  name: validationCliDefinition.domain.commandName,
+  description: validationCliDefinition.domain.description,
   register: (program2) => {
-    const validationCmd = program2.command("validation").alias("v").description("Run code validation tools");
+    const { domain } = validationCliDefinition;
+    const validationCmd = program2.command(domain.commandName).alias(domain.alias).description(domain.description);
+    validationCmd.on("command:*", (operands) => {
+      handleUnknownSubcommand(operands);
+    });
     registerValidationCommands(validationCmd);
   }
 };
@@ -4323,7 +5808,9 @@ var require3 = createRequire2(import.meta.url);
 var { version } = require3("../package.json");
 var program = new Command();
 program.name("spx").description("Fast, deterministic CLI tool for spec workflow management").version(version);
+auditDomain.register(program);
 claudeDomain.register(program);
+configDomain.register(program);
 sessionDomain.register(program);
 specDomain.register(program);
 validationDomain.register(program);