docguard-cli 0.36.1 → 0.37.0

package/cli/commands/specs.mjs

@@ -0,0 +1,77 @@
+/** Manage and preflight the deterministic spec lifecycle registry. */
+
+import { resolve } from 'node:path';
+import { safeWrite } from '../writers/generate-io.mjs';
+import { preflightSpec, projectSpecRegistry, SPEC_REGISTRY_PATH } from '../scanners/spec-registry.mjs';
+
+function printIssues(issues) {
+  for (const issue of issues) console.log(`  ${issue.code} ${issue.path}: ${issue.message}`);
+}
+
+function printResult(result) {
+  if (result.command === 'preflight') {
+    console.log(`Spec preflight: ${result.status}`);
+    console.log(`Current specs: ${result.briefing.length}`);
+    for (const spec of result.briefing) {
+      console.log(`  ${spec.specId} — ${spec.approval}/${spec.delivery}; tasks ${spec.taskCompletion.checked}/${spec.taskCompletion.total}; test evidence ${spec.testEvidence}`);
+    }
+    if (result.blockers.length) {
+      console.log('Blockers:');
+      printIssues(result.blockers);
+    }
+    if (result.overlaps.length) {
+      console.log('Review-only semantic overlap:');
+      for (const overlap of result.overlaps) console.log(`  ${(overlap.similarity * 100).toFixed(0)}% ${overlap.specId} (${overlap.path})`);
+    }
+    return;
+  }
+  console.log(`Spec registry: ${result.status}`);
+  console.log(`Registry: ${SPEC_REGISTRY_PATH}`);
+  console.log(`Specs: ${result.specs}; tombstones: ${result.tombstones}`);
+  if (result.issues.length) printIssues(result.issues);
+}
+
+export function runSpecs(projectDir, config, flags = {}) {
+  try {
+    const action = flags.args?.[0] || null;
+    if (action && action !== 'preflight') throw new Error(`Unknown specs action: ${action}`);
+    if (flags.check && flags.write) throw new Error('Use either --check or --write, not both.');
+
+    if (action === 'preflight') {
+      if (flags.write) throw new Error('Specs preflight is read-only.');
+      const result = { command: 'preflight', ...preflightSpec(projectDir, config, flags.path || null) };
+      if (flags.format === 'json') console.log(JSON.stringify(result, null, 2));
+      else printResult(result);
+      if (result.status === 'BLOCKED') process.exitCode = 2;
+      return result;
+    }
+
+    const projection = projectSpecRegistry(projectDir, config);
+    if (flags.write && projection.issues.length > 0) {
+      throw new Error(`Registry refresh refused: ${projection.issues.map(issue => issue.message).join(' ')}`);
+    }
+    let status = projection.current ? 'CURRENT' : projection.exists ? 'STALE' : 'MISSING';
+    if (flags.write && !projection.current) {
+      safeWrite(resolve(projectDir, SPEC_REGISTRY_PATH), projection.serialized);
+      status = 'WRITTEN';
+    }
+    const result = {
+      command: 'specs',
+      status,
+      registry: SPEC_REGISTRY_PATH,
+      specs: projection.registry.specs.length,
+      tombstones: projection.registry.tombstones.length,
+      issues: projection.issues,
+    };
+    if (flags.format === 'json') console.log(JSON.stringify(result, null, 2));
+    else printResult(result);
+    if (flags.check && (status !== 'CURRENT' || result.issues.length > 0)) process.exitCode = 2;
+    return result;
+  } catch (error) {
+    const result = { command: 'specs', status: 'ERROR', error: error.message };
+    if (flags.format === 'json') console.log(JSON.stringify(result, null, 2));
+    else console.error(`Error: ${error.message}`);
+    process.exitCode = 1;
+    return result;
+  }
+}

package/cli/commands/trace.mjs

@@ -10,6 +10,7 @@ import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, extname, basename, relative, dirname } from 'node:path';
 import { c } from '../shared.mjs';
 import { detectSpecKit } from '../scanners/speckit.mjs';
+import { scanTestFilesForReferences, collectRequirementIds, resolveRequirementReferences } from '../validators/traceability.mjs';
 import { listCanonicalDocs } from '../shared-ignore.mjs';
 
 const IGNORE_DIRS = new Set([
@@ -378,7 +379,7 @@ function scanDir(rootDir, dir, files) {
 // repo-wide scores that `docguard score` produces. Deterministic signals only —
 // no LLM judgment:
 //
-//   reqCoverage          40%  FR-/SC- IDs in spec.md referenced by any test file
+//   reqCoverage          40%  FR-/SC- IDs in spec.md explicitly annotated or labeled in test sources
 //   taskCompletion       25%  checked/total `- [x]` tasks in tasks.md
 //   taskEvidence         20%  checked tasks whose line names an existing file
 //   artifactCompleteness 15%  spec.md (40%) + plan.md (30%) + tasks.md (30%)
@@ -425,34 +426,31 @@ function featureBar(score) {
 }
 
 /**
- * Collect every FR-/SC- ID referenced anywhere in a test file, once for the
- * whole project. Test-file discovery mirrors the traceability validator's
- * scanTestFilesForReferences(): TEST_PATTERNS ∪ __tests__/ ∪ tests?/ dirs, and
- * any occurrence of the ID in file content counts (not just @req lines).
+ * Collect declared FR-/SC- test links once for the whole project, using the
+ * validator's source eligibility and annotation/label parser. This is positive
+ * linkage evidence, independent of validator findings or suppression policy.
  */
 function collectTestReferencedIds(projectDir) {
   const projectFiles = [];
   scanDir(projectDir, projectDir, projectFiles);
-  const testFiles = projectFiles.filter(f =>
-    TEST_PATTERNS.some(p => p.test(f)) || /__tests__\//.test(f) || /tests?\//.test(f)
-  );
-
-  const ids = new Set();
-  for (const rel of testFiles) {
-    let content;
-    try { content = readFileSync(resolve(projectDir, rel), 'utf-8'); } catch { continue; }
-    FEATURE_REQ_RE.lastIndex = 0;
-    let m;
-    while ((m = FEATURE_REQ_RE.exec(content)) !== null) ids.add(m[0]);
+  const references = scanTestFilesForReferences(projectDir, projectFiles, [FEATURE_REQ_RE]);
+  // Feature completion evidence must survive spec retirement and ID reuse.
+  // Bare FR-001 references can be useful navigation for the repo-wide matrix,
+  // but they can rebind to a different feature after the original spec leaves
+  // the working tree. Keep only document-qualified identities here.
+  const qualified = new Map();
+  for (const [id, refs] of references) {
+    const scoped = refs.filter(ref => ref.scope);
+    if (scoped.length > 0) qualified.set(id, scoped);
   }
-  return ids;
+  return qualified;
 }
 
 /**
  * Compute the four adherence signals for one detected spec-kit feature.
  * Each signal: { applicable, value (0..1 | null), ...n/m detail fields }.
  */
-function computeFeatureSignals(projectDir, feature, testRefIds) {
+function computeFeatureSignals(projectDir, feature, testRefIds, definitions) {
   // ── artifactCompleteness — always measurable ──
   const artifactValue = (feature.hasSpec ? 0.4 : 0)
     + (feature.hasPlan ? 0.3 : 0)
@@ -483,21 +481,11 @@ function computeFeatureSignals(projectDir, feature, testRefIds) {
     }
   }
 
-  // ── reqCoverage — spec.md IDs that appear in ANY test file ──
-  const specIds = [];
-  if (feature.hasSpec && feature.specPath) {
-    try {
-      const spec = readFileSync(feature.specPath, 'utf-8');
-      const seen = new Set();
-      FEATURE_REQ_RE.lastIndex = 0;
-      let m;
-      while ((m = FEATURE_REQ_RE.exec(spec)) !== null) {
-        if (!seen.has(m[0])) { seen.add(m[0]); specIds.push(m[0]); }
-      }
-    } catch { /* unreadable spec → no IDs */ }
-  }
-  const covered = specIds.filter(id => testRefIds.has(id));
-  const uncovered = specIds.filter(id => !testRefIds.has(id));
+  // ── reqCoverage — spec.md IDs declared in eligible test annotations or labels ──
+  const specPath = feature.specPath ? relative(projectDir, feature.specPath).replaceAll('\\', '/') : null;
+  const specIds = [...definitions.values()].filter(def => def.file === specPath).map(def => def.id);
+  const covered = specIds.filter(id => testRefIds.has(`${specPath}#${id}`));
+  const uncovered = specIds.filter(id => !testRefIds.has(`${specPath}#${id}`));
 
   return {
     reqCoverage: {
@@ -606,10 +594,11 @@ export function runTraceFeatures(projectDir, config, flags) {
     return;
   }
 
-  const testRefIds = collectTestReferencedIds(projectDir);
+  const definitions = collectRequirementIds(projectDir, config, [FEATURE_REQ_RE]);
+  const testRefIds = resolveRequirementReferences(definitions, collectTestReferencedIds(projectDir));
 
   const features = speckit.specs.map(f => {
-    const signals = computeFeatureSignals(projectDir, f, testRefIds);
+    const signals = computeFeatureSignals(projectDir, f, testRefIds, definitions);
     const score = scoreFromSignals(signals);
     const weakest = weakestSignal(signals);
     const needsFix = weakest !== null && signals[weakest].value < 1;

package/cli/config.mjs

@@ -79,6 +79,8 @@ export function loadConfig(projectDir) {
       security: false,
       environment: true,
       freshness: true,
+      documentLifecycle: true,
+      specRegistry: true,
       // v0.31.0 — all three default ON. Soft (confidence:low, never break CI),
       // heuristic (field cases require ongoing precision checks), and quiet when
       // not applicable (no diff / no API-reference doc). api-doc-smells is

package/cli/docguard.mjs

@@ -51,6 +51,8 @@ import { runMemory } from './commands/memory.mjs';
 import { runDemo } from './commands/demo.mjs';
 import { runAgent } from './commands/agent.mjs';
 import { runMcp } from './commands/mcp.mjs';
+import { runArchive } from './commands/retire.mjs';
+import { runSpecs } from './commands/specs.mjs';
 import { ensureSkills } from './ensure-skills.mjs';
 
 // ── Shared constants (imported to break circular dependencies) ──────────
@@ -97,6 +99,8 @@ ${c.bold}Tools (situational, but day-to-day useful)${c.reset}
   ${c.green}report${c.reset}     Compliance-evidence bundle — guard + score + ALCOA+ + integrity hash (${c.cyan}--format json${c.reset}, ${c.cyan}--out <file>${c.reset})
   ${c.green}ci${c.reset}         Pipeline gate: guard + score in one command (${c.cyan}--threshold <n>${c.reset}, ${c.cyan}--fail-on-warning${c.reset}, ${c.cyan}--format json${c.reset}; records score history)
   ${c.green}memory${c.reset}     Show what DocGuard remembers (${c.cyan}--diff${c.reset} drills into drift)
+  ${c.green}retire${c.reset}     Remove reviewed docs from active AI context (${c.cyan}--plan${c.reset}; explicit ${c.cyan}--write --path${c.reset})
+  ${c.green}specs${c.reset}      Track spec lifecycle and evidence (${c.cyan}--check|--write${c.reset}; ${c.cyan}preflight --path <spec>${c.reset})
   ${c.green}trace${c.reset}      Requirements traceability matrix (${c.cyan}--reverse${c.reset} for code→doc map, ${c.cyan}--features${c.reset} for per-feature adherence)
   ${c.green}upgrade${c.reset}    Migrate ${c.cyan}.docguard.json${c.reset} schema + CLI (${c.cyan}--apply --pr${c.reset} for team-wide PR)
   ${c.green}watch${c.reset}      Live mode: re-run guard on file changes
@@ -109,12 +113,12 @@ ${c.bold}init --with <name>${c.reset} ${c.dim}— optional scaffolders, picked a
   ${c.dim}llms${c.reset}       llms.txt generation
   ${c.dim}publish${c.reset}    External doc-site scaffold (Mintlify) ${c.dim}— experimental${c.reset}
 
-${c.bold}Deprecation aliases${c.reset} ${c.dim}— still work in v0.20.x with a yellow warning${c.reset}
+${c.bold}Deprecation aliases${c.reset} ${c.dim}— supported until v1.0 with a yellow warning${c.reset}
   ${c.dim}setup${c.reset} → ${c.cyan}init --wizard${c.reset}
   ${c.dim}agents · hooks · badge · llms · publish${c.reset} → ${c.cyan}init --with <name>${c.reset}
   ${c.dim}impact${c.reset} → ${c.cyan}diff --since <ref>${c.reset}
   ${c.dim}audit${c.reset} → ${c.green}guard${c.reset} ${c.dim}(permanent — no warning, no removal planned)${c.reset}
-  ${c.dim}See docs-implementation/MIGRATION-v0.20.md for the full timeline.${c.reset}
+  ${c.dim}Run the legacy form to see its replacement.${c.reset}
 
 ${c.bold}Options:${c.reset}
   --dir <path>    Project directory (default: current directory)
@@ -129,9 +133,9 @@ ${c.bold}Options:${c.reset}
   --threshold <n> Minimum score for CI pass (used with ci command)
   --fail-on-warning  Fail CI on warnings (used with ci command)
   --auto          Auto-fix what's possible (used with fix command)
-  --write         Apply deterministic fixes in place (fix command): removes
-                  documented endpoints the OpenAPI spec confirms are gone.
-                  Only edits docguard:generated docs unless --force.
+  --write         Apply a command's explicit deterministic write path. For fix,
+                  only edits docguard:generated docs unless --force; specs
+                  refreshes observed registry evidence; retire requires --path.
   --plan          AI-powered Generate (generate command): scan any project
                   (JS/Python/Rust/Go/Java/…), emit the agent task manifest +
                   code-truth skeleton. Add --write to scaffold, --format json
@@ -308,6 +312,35 @@ const COMMAND_HELP = {
     ],
     examples: ['docguard verify --semantic', 'docguard verify --semantic --format json'],
   },
+  retire: {
+    summary: 'Remove reviewed docs from active AI context while preserving recovery from a retained Git ref.',
+    usage: 'docguard retire [--plan|--check] | --write --path <document> [--path <document>...] --reason <text> [--superseded-by <document>] [--evidence <document>...] [--retention-ref <ref>]',
+    flags: [
+      ['--plan', 'Read-only lifecycle candidate inventory (default behavior)'],
+      ['--check', 'Exit 2 when high-confidence lifecycle candidates remain'],
+      ['--fail-on-warning', 'With --check: also gate low-confidence review candidates'],
+      ['--write', 'Retire only the explicitly selected clean tracked documents'],
+      ['--path <path>', 'Documentation file or document-only directory; repeatable'],
+      ['--reason <text>', 'Required explanation recorded in the archive manifest'],
+      ['--superseded-by <path>', 'Current document that replaces the archived material'],
+      ['--evidence <path>', 'Clean current document that contains the consolidated outcome; repeatable'],
+      ['--retention-ref <ref>', 'Branch ref that must retain the source revision'],
+      ['--format json', 'Machine-readable plan or result'],
+    ],
+    examples: ['docguard retire --plan', 'docguard retire --check --format json', 'docguard retire --write --path specs/001-done --reason "Implemented in v1.2"'],
+  },
+  specs: {
+    summary: 'Maintain the deterministic spec lifecycle and evidence registry.',
+    usage: 'docguard specs [--check|--write] | docguard specs preflight [--path <spec>] [--format json]',
+    flags: [
+      ['--check', 'Exit 2 when the committed registry is missing, stale, or inconsistent'],
+      ['--write', 'Refresh observed evidence while preserving reviewed lifecycle fields'],
+      ['preflight', 'Brief prior specs, or gate a generated draft with --path'],
+      ['--path <spec>', 'Generated spec to compare against current lifecycle state'],
+      ['--format json', 'Machine-readable registry or preflight result'],
+    ],
+    examples: ['docguard specs --check', 'docguard specs --write', 'docguard specs preflight', 'docguard specs preflight --path specs/007-feature/spec.md'],
+  },
 };
 
 function printCommandHelp(command) {
@@ -535,8 +568,26 @@ async function main() {
       flags.apiKey = args[i + 1];
       i++;
     } else if (args[i] === '--path' && args[i + 1]) {
-      // mcp --transport http: HTTP mount path (default /mcp).
-      flags.path = args[i + 1];
+      if (command === 'retire' || command === 'archive') {
+        flags.paths = flags.paths || [];
+        flags.paths.push(args[i + 1]);
+      } else {
+        // mcp --transport http: HTTP mount path (default /mcp).
+        flags.path = args[i + 1];
+      }
+      i++;
+    } else if (args[i] === '--reason' && args[i + 1]) {
+      flags.reason = args[i + 1];
+      i++;
+    } else if (args[i] === '--superseded-by' && args[i + 1]) {
+      flags.supersededBy = args[i + 1];
+      i++;
+    } else if (args[i] === '--evidence' && args[i + 1]) {
+      flags.evidencePaths = flags.evidencePaths || [];
+      flags.evidencePaths.push(args[i + 1]);
+      i++;
+    } else if (args[i] === '--retention-ref' && args[i + 1]) {
+      flags.retentionRef = args[i + 1];
       i++;
     } else if (args[i] === '--code') {
       flags.code = args[i + 1] && !args[i + 1].startsWith('--') ? args[++i] : '';
@@ -624,7 +675,7 @@ async function main() {
   // `diff`/`impact` only read; `demo` runs against a throwaway fixture.)
   const READ_ONLY_COMMANDS = new Set([
     'guard', 'audit', 'score', 'diff', 'impact',
-    'diagnose', 'trace', 'explain', 'memory', 'demo', 'agent',
+    'diagnose', 'trace', 'explain', 'memory', 'demo', 'agent', 'retire', 'archive', 'specs',
     // feedback only writes its own .docguard/feedback/ — it must NOT scaffold
     // skills or touch source, so it's gated out of ensureSkills like the rest.
     'feedback',
@@ -652,15 +703,16 @@ async function main() {
     command !== 'setup' &&
     command !== 'init' &&
     !READ_ONLY_COMMANDS.has(command) &&
+    // Agent-family staleness checks must not bootstrap skills or Spec Kit.
+    !(command === 'agents' && flags.check) &&
     !headless
   ) {
     ensureSkills(projectDir, flags);
   }
 
-  // v0.20: deprecation aliases. The legacy command keeps working through v0.20
+  // v0.20: deprecation aliases. The legacy command keeps working until v1.0
   // and emits a yellow stderr warning suggesting the new shape. Quiet mode
   // (e.g. inside hooks) suppresses the warning so CI output stays clean.
-  // The full deprecation timeline is in docs-implementation/MIGRATION-v0.20.md.
   const DEPRECATED_COMMANDS = {
     setup:   { since: '0.20', replacement: 'docguard init --wizard' },
     agents:  { since: '0.20', replacement: 'docguard init --with agents' },
@@ -692,7 +744,7 @@ async function main() {
   if (DROPPED_ALIASES[command]) {
     console.error(`${c.red}Unknown command: ${command}${c.reset}`);
     console.error(`${c.yellow}Hint: this alias was removed in v0.20. Try ${c.cyan}docguard ${DROPPED_ALIASES[command]}${c.yellow}.${c.reset}`);
-    console.error(`${c.dim}See docs-implementation/MIGRATION-v0.20.md for the full list.${c.reset}`);
+    console.error(`${c.dim}Use the replacement shown above; removed aliases are not restored.${c.reset}`);
     process.exit(1);
   }
 
@@ -701,7 +753,7 @@ async function main() {
   if (DEPRECATED_COMMANDS[command] && !flags.quiet && !(command === 'hooks' && flags.claude)) {
     const { since, replacement } = DEPRECATED_COMMANDS[command];
     console.error(`${c.yellow}⚠ Deprecated since v${since}:${c.reset} ${c.cyan}docguard ${command}${c.reset} → use ${c.cyan}${replacement}${c.reset}`);
-    console.error(`${c.dim}  The old form still works in v0.20.x but will be removed in v1.0. See MIGRATION-v0.20.md.${c.reset}`);
+    console.error(`${c.dim}  The old form remains compatible until v1.0.${c.reset}`);
   }
 
   switch (command) {
@@ -733,8 +785,9 @@ async function main() {
       }
       break;
     case 'agents':
-      // v0.20: deprecated → dispatches through init --with
-      await runInit(projectDir, config, { ...flags, with: ['agents'], skipPrompts: true });
+      // A staleness check must bypass init's scaffolding and skill installation.
+      if (flags.check) runAgents(projectDir, config, flags);
+      else await runInit(projectDir, config, { ...flags, with: ['agents'], skipPrompts: true });
       break;
     case 'generate':
       runGenerate(projectDir, config, flags);
@@ -827,6 +880,13 @@ async function main() {
     case 'memory':
       runMemory(projectDir, config, flags);
       break;
+    case 'retire':
+    case 'archive': // Development alias; `retire` avoids collision with Spec Kit Archive.
+      runArchive(projectDir, config, flags);
+      break;
+    case 'specs':
+      runSpecs(projectDir, config, flags);
+      break;
     case 'demo':
       // v0.21: zero-install "ah-ha" moment — runs guard against a baked-in
       // fixture (templates/demo-fixture/) and prints curated drift findings

package/cli/findings.mjs

@@ -486,6 +486,60 @@ export const CODES = {
     help: 'Guard reports at most 10 phantom-completion findings (SPK008) per run to avoid noise; this line counts the remainder. Fix or uncheck the reported tasks and re-run guard to surface more, or set `"specKit": { "phantomCheck": false }` in .docguard.json to disable the check.',
     suppress: null,
   },
+  DLC001: {
+    validator: 'documentLifecycle',
+    title: 'Terminal document remains in active context',
+    help: 'A tracked Markdown file declares itself superseded, deprecated, obsolete, or archived but remains searchable as current repository context. Confirm its outcomes are represented in current docs, then use `docguard retire --write --path <path> --reason <reason>`.',
+    suppress: null,
+  },
+  DLC002: {
+    validator: 'documentLifecycle',
+    title: 'Completed task list needs lifecycle review',
+    help: 'A spec has checked tasks and no open tasks. This is a review signal, not proof that the feature shipped. Confirm release evidence and current documentation before archiving the spec.',
+    suppress: null,
+  },
+  DLC003: {
+    validator: 'documentLifecycle',
+    title: 'Document lifecycle coverage incomplete',
+    help: 'DocGuard could not enumerate or read every tracked Markdown document. Fix Git access or file readability and rerun guard; an incomplete lifecycle scan must not be interpreted as a clean result.',
+    suppress: null,
+  },
+  DLC004: {
+    validator: 'documentLifecycle',
+    title: 'Retired document remains active',
+    help: 'The retirement manifest records this path, but the document still exists in the working tree. Remove it through the reviewed retirement transaction or remove the incorrect manifest event; the two states must agree.',
+    suppress: null,
+  },
+  SPR001: {
+    validator: 'specRegistry',
+    title: 'Spec registry missing or stale',
+    help: 'The committed `.docguard-specs.json` does not match the deterministic projection of current specs, tasks, tests, and archive tombstones. Run `docguard specs --write`, review the diff, and commit it with the behavior change.',
+    suppress: null,
+  },
+  SPR002: {
+    validator: 'specRegistry',
+    title: 'Spec identity missing or reused',
+    help: 'Every active spec needs one immutable lowercase Spec ID in authoritative metadata. IDs survive moves and retirement and may never be reused. Add `**Spec ID**: ` followed by a unique namespaced ID in backticks.',
+    suppress: null,
+  },
+  SPR003: {
+    validator: 'specRegistry',
+    title: 'Spec registry is invalid',
+    help: 'The registry is malformed or contains an unsupported lifecycle value. DocGuard refuses to overwrite invalid reviewed state. Repair the named field, then run `docguard specs --write`.',
+    suppress: null,
+  },
+  SPR004: {
+    validator: 'specRegistry',
+    title: 'Spec lifecycle contradicts storage',
+    help: 'Working-tree presence, lifecycle context, storage state, and the recovery archive disagree. Active specs must be current/working_tree; retired specs must be retired/git_history with a reason and matching archive event.',
+    suppress: null,
+  },
+  SPR005: {
+    validator: 'specRegistry',
+    title: 'New spec overlaps prior intent',
+    help: 'Preflight found lexical overlap with a prior spec. This is a review hint, never proof of duplication or delivery. Inspect the prior lifecycle and evidence before adding an explicit supersedes or related relationship.',
+    suppress: null,
+  },
   XRF001: {
     validator: 'crossReference',
     title: 'Broken doc link',

package/cli/scanners/document-lifecycle.mjs

@@ -0,0 +1,184 @@
+/**
+ * Read-only document lifecycle signals shared by `retire` and guard.
+ * Signals identify review candidates; they never authorize deletion.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { dirname, resolve } from 'node:path';
+import { shouldIgnore } from '../shared-ignore.mjs';
+
+const RETIRED_STATUSES = new Set(['archived', 'deprecated', 'obsolete', 'superseded']);
+const COMPLETION_STATUSES = new Set(['complete', 'completed']);
+const EXCLUDED_PREFIXES = ['.git', '.local', '.docguard'];
+const MANIFEST_PATH = '.docguard-archive.json';
+
+export function readRetirementManifest(projectDir) {
+  const path = resolve(projectDir, MANIFEST_PATH);
+  if (!existsSync(path)) return { ok: true, paths: new Set(), entries: [], retention: null, error: null };
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    if (parsed?.schemaVersion !== 1 || parsed?.strategy !== 'git-history' || !Array.isArray(parsed.entries)) {
+      throw new Error('unsupported schema');
+    }
+    const globalRecovery = parsed.retention?.recoverability === 'verified'
+      && typeof parsed.retention?.ref === 'string'
+      && /^(?:sha1|sha256)$/.test(parsed.retention?.objectFormat || '');
+    for (const entry of parsed.entries) {
+      const path = entry?.path;
+      const entryRecovery = entry?.recoverability === 'verified'
+        && typeof entry?.retentionRef === 'string'
+        && /^(?:sha1|sha256)$/.test(entry?.objectFormat || '');
+      if (typeof path !== 'string' || !path || path.startsWith('/')
+        || path.replaceAll('\\', '/').split('/').includes('..')
+        || typeof entry?.archivedFrom !== 'string'
+        || !/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/.test(entry.archivedFrom)
+        || typeof entry?.blob !== 'string'
+        || !/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/.test(entry.blob)
+        || typeof entry?.reason !== 'string' || !entry.reason.trim()
+        || (entry?.requirementIds !== undefined && (!Array.isArray(entry.requirementIds)
+          || entry.requirementIds.some(id => typeof id !== 'string' || !id || id.length > 128 || /[\s#\0]/.test(id))))
+        || (entry?.specId !== undefined && (typeof entry.specId !== 'string'
+          || !/^[a-z0-9][a-z0-9._-]{2,127}$/.test(entry.specId)))
+        || (!globalRecovery && !entryRecovery)) {
+        throw new Error(`invalid recovery entry for ${path || '<unknown path>'}`);
+      }
+    }
+    return {
+      ok: true,
+      paths: new Set(parsed.entries.map(entry => entry.path)),
+      entries: parsed.entries,
+      retention: parsed.retention || null,
+      error: null,
+    };
+  } catch (error) {
+    return { ok: false, paths: new Set(), entries: [], retention: null, error: `${MANIFEST_PATH}: ${error.message}` };
+  }
+}
+
+function trackedFiles(projectDir) {
+  const result = spawnSync('git', ['ls-files', '-z'], {
+    cwd: projectDir,
+    encoding: 'utf8',
+    maxBuffer: 8 * 1024 * 1024,
+  });
+  if (result.status !== 0) {
+    const error = result.error?.message || result.stderr || result.stdout || 'git ls-files failed';
+    return {
+      ok: false,
+      files: [],
+      reason: /not a git repository|must be run in a work tree/i.test(error)
+        ? 'not-git'
+        : 'git-unavailable',
+      error: error.trim(),
+    };
+  }
+  return { ok: true, files: result.stdout.split('\0').filter(Boolean), reason: null, error: null };
+}
+
+export function parseLifecycleStatus(content) {
+  const header = content.split('\n').slice(0, 40).join('\n');
+  const match = header.match(/(?:^|\n)\s*(?:#{1,6}\s*)?(?:\*\*)?Status(?::)?(?:\*\*)?\s*:?\s*(?:\*\*)?([^*\n]+)/i);
+  return match?.[1]?.trim() || null;
+}
+
+function completedTaskSignal(projectDir, path, content, tracked) {
+  let taskContent = content;
+  if (!/(?:^|\n)\s*- \[[ xX]\]/.test(taskContent) && /(?:^|\/)spec\.md$/i.test(path)) {
+    const taskRel = `${dirname(path)}/tasks.md`;
+    const taskPath = resolve(projectDir, taskRel);
+    if (tracked.has(taskRel) && existsSync(taskPath)) taskContent = readFileSync(taskPath, 'utf8');
+  }
+  const checked = taskContent.match(/(?:^|\n)\s*- \[[xX]\]/g)?.length || 0;
+  const open = taskContent.match(/(?:^|\n)\s*- \[ \]/g)?.length || 0;
+  return checked > 0 && open === 0 ? { checked, open } : null;
+}
+
+export function scanDocumentLifecycle(projectDir, config = {}) {
+  const inventory = trackedFiles(projectDir);
+  const retired = readRetirementManifest(projectDir);
+  if (!inventory.ok || !retired.ok) {
+    return {
+      scanned: 0,
+      candidates: [],
+      coverage: {
+        status: 'unavailable',
+        reason: inventory.ok ? 'manifest-invalid' : inventory.reason,
+        error: inventory.error || retired.error,
+        unreadable: [],
+      },
+    };
+  }
+  const tracked = new Set(inventory.files);
+  const markdown = inventory.files.filter(path => /\.md$/i.test(path));
+  const candidates = [];
+  const unreadable = [];
+  let scanned = 0;
+  for (const path of retired.paths) {
+    if (existsSync(resolve(projectDir, path))) {
+      candidates.push({
+        code: 'DLC004',
+        path,
+        confidence: 'high',
+        status: 'retired',
+        reason: 'retirement manifest records this path but it remains in the working tree',
+      });
+    }
+  }
+  for (const path of markdown) {
+    if (EXCLUDED_PREFIXES.some(prefix => path === prefix || path.startsWith(`${prefix}/`))) continue;
+    if (shouldIgnore(path, config, 'documentLifecycle')) continue;
+    if (retired.paths.has(path) && !existsSync(resolve(projectDir, path))) continue;
+    let content;
+    try { content = readFileSync(resolve(projectDir, path), 'utf8'); } catch {
+      unreadable.push(path);
+      continue;
+    }
+    scanned++;
+    const status = parseLifecycleStatus(content);
+    const normalizedStatus = status?.trim().toLowerCase() || null;
+    if (normalizedStatus && RETIRED_STATUSES.has(normalizedStatus)) {
+      candidates.push({
+        code: 'DLC001',
+        path,
+        confidence: 'high',
+        status,
+        reason: `explicit lifecycle status: ${status}`,
+      });
+      continue;
+    }
+    if (normalizedStatus && COMPLETION_STATUSES.has(normalizedStatus)) {
+      candidates.push({
+        code: 'DLC002',
+        path: /(?:^|\/)spec\.md$/i.test(path) ? dirname(path) : path,
+        confidence: 'review',
+        status,
+        reason: `artifact maturity is ${status}; verify persistence policy and backreferences before retirement`,
+      });
+      continue;
+    }
+    if (path.startsWith('specs/') && /(?:^|\/)spec\.md$/i.test(path)) {
+      const tasks = completedTaskSignal(projectDir, path, content, tracked);
+      if (tasks) {
+        candidates.push({
+          code: 'DLC002',
+          path: dirname(path),
+          confidence: 'review',
+          status,
+          reason: `${tasks.checked} checked tasks and no open tasks; confirm the outcome is documented`,
+        });
+      }
+    }
+  }
+  return {
+    scanned,
+    candidates: [...new Map(candidates.map(candidate => [candidate.path, candidate])).values()]
+      .sort((a, b) => a.path.localeCompare(b.path)),
+    coverage: {
+      status: unreadable.length > 0 ? 'partial' : 'complete',
+      reason: unreadable.length > 0 ? 'unreadable-files' : null,
+      error: null,
+      unreadable,
+    },
+  };
+}