docguard-cli 0.36.1 → 0.37.0

package/README.md

@@ -69,15 +69,15 @@ DocGuard is an official [GitHub Spec Kit](https://github.com/github/spec-kit) co
 
 ```mermaid
 graph TD
-    CLI["CLI Entry<br/>docguard.mjs"] --> Commands["Commands (20)"]
+    CLI["CLI Entry<br/>docguard.mjs"] --> Commands["Commands (22)"]
     Commands --> guard["guard"]
     Commands --> generate["generate"]
     Commands --> score["score"]
     Commands --> diagnose["diagnose"]
     Commands --> setup["setup wizard"]
-    Commands --> other["diff · init · fix · trace · impact · sync<br/>explain · memory · upgrade · agents · hooks · badge · ci · watch"]
+    Commands --> other["diff · init · fix · trace · impact · sync · retire · specs<br/>explain · memory · upgrade · agents · hooks · badge · ci · watch"]
 
-    guard --> Validators["Validators (27)"]
+    guard --> Validators["Validators (29)"]
     generate --> Scanners["Scanners (4)<br/>routes · schemas · doc-tools · speckit"]
     score --> Scoring["Weighted Scoring<br/>8 categories"]
     diagnose --> Validators
@@ -108,7 +108,7 @@ A guard result describes the checks performed. The CDD grade measures structural
 
 Research motivates evaluation of this approach. A 2026 study found that repository context files did not generally improve task success and increased inference cost in its evaluated settings. It also found agents generally followed the instructions. These results support testing concise, relevant context and measuring actual task outcomes; they do not establish DocGuard's effectiveness. [Evaluating AGENTS.md, revised June 2026](https://arxiv.org/abs/2602.11988v2).
 
-The development plan prioritizes accurate detection, reproducible evidence, and contributor-supplied regression cases. See [the trust roadmap](docs-implementation/TRUST-ROADMAP.md) for implementation status, proposed experiments, and acceptance criteria.
+The [current roadmap](ROADMAP.md) prioritizes accurate detection, reproducible evidence, document lifecycle management, and contributor-supplied regression cases. Released plans and superseded specifications are removed from active AI context and remain recoverable from Git.
 
 ---
 
@@ -268,14 +268,14 @@ This installs DocGuard's slash commands (`/docguard.init`, `/docguard.guard`, `/
 
 ## Usage
 
-DocGuard ships **20 commands** (the "Daily 5" + 15 situational tools, including the zero-install `demo`, the `mcp` server, and the `ci` pipeline gate). Six additional one-shot scaffolders are accessed via `docguard init --with <name>`. Seven v0.19 commands continue to work as deprecation aliases through v0.20.x — see [MIGRATION-v0.20.md](docs-implementation/MIGRATION-v0.20.md).
+DocGuard ships **22 commands** (the "Daily 5" + 17 situational tools, including lifecycle retirement and spec tracking, the zero-install `demo`, the `mcp` server, and the `ci` pipeline gate). Six additional one-shot scaffolders are accessed via `docguard init --with <name>`. Legacy command forms remain compatible until v1.0 and print their replacements.
 
 **The Daily 5** — what you'll reach for 95% of the time:
 
 | Command | What It Does |
 |:--------|:-------------|
 | `init`  | Bootstrap a project (`--wizard` for interactive · `--with <name>` for scaffolders) |
-| `guard` | Validate against canonical docs — 27 validators |
+| `guard` | Validate against canonical docs — 29 validators |
 | `diff`  | Show gaps between docs and code (`--since <ref>` for impact mode) |
 | `sync`  | Refresh code-truth doc sections — keeps memory always up to date |
 | `score` | CDD maturity score (0-100; `--diff` for delta between refs) |
@@ -295,6 +295,9 @@ DocGuard ships **20 commands** (the "Daily 5" + 15 situational tools, including
 | `verify --semantic` | Extract documented numbers/limits/enums (retention days, rate limits, GSI/role counts, status enums) as a task list for an agent to check against code — the semantic-drift class regex/AST can't see |
 | `verify --instructions` | Audit AGENTS.md/CLAUDE.md themselves for drift: duplicate rules, never-vs-always contradictions, stale file pointers, unknown commands — plus clustered rule pairs as agent judgment tasks |
 | `feedback` | Report likely false positives back to DocGuard — local-first record + a 1-click prefilled, redacted GitHub issue (zero typing) |
+| `retire` | Find completed or superseded planning material (`--plan`/`--check`; `--fail-on-warning` gates advisory candidates) and explicitly remove clean tracked documentation from active AI context. `.docguard-archive.json` records recovery metadata and retired requirement identities, and `--retention-ref` proves the source revision remains reachable. This is separate from the Spec Kit Archive extension, which consolidates feature documents. |
+| `specs --check` / `specs --write` | Validate or refresh `.docguard-specs.json`, the byte-stable index of immutable spec IDs, reviewed lifecycle/lineage/scope, artifact digests, task state, explicitly scoped test evidence, and archive tombstones. Refreshes preserve the reviewed block. |
+| `specs preflight [--path <spec>]` | Before specification, print current spec lifecycle and evidence. Before planning, check the generated draft for structural blockers and report semantic overlap as review-only evidence. |
 | `mcp` | MCP server — exposes guard/score/explain/verify/report/diagnose as native tools for Claude, Cursor, and any MCP client. Stdio: `claude mcp add docguard -- npx docguard-cli mcp`. Team-shared HTTP: `docguard mcp --transport http --port 8585` (loopback by default; non-loopback binds require `--api-key`) |
 | `report` | Compliance-evidence bundle for audits — guard verdict + CDD score + ALCOA+ attributes + fix history, stamped with git commit and a tamper-evident sha256 integrity hash (`--format json`, `--out <file>`). Evidence, not a gate: always exits 0 |
 | `ci` | Pipeline gate: guard + score in one command — never scaffolds or touches source; its only write is its own `.docguard/history.jsonl` (opt out: `--no-history`). `--threshold <n>` fails below a score, `--fail-on-warning` for strict mode, `--format json` for parsers |
@@ -321,7 +324,7 @@ DocGuard ships **20 commands** (the "Daily 5" + 15 situational tools, including
 
 Run them solo (`docguard init --with hooks`) or stacked (`docguard init --with agents,hooks,badge,ci`).
 
-**Deprecation aliases** — `setup` · `agents` · `hooks` · `ci` · `badge` · `llms` · `publish` · `impact` keep working in v0.20.x with a yellow stderr warning. `audit → guard` is permanent (no warning). See [MIGRATION-v0.20.md](docs-implementation/MIGRATION-v0.20.md).
+**Deprecation aliases** — `setup` · `agents` · `hooks` · `badge` · `llms` · `publish` · `impact` remain compatible until v1.0 with a yellow stderr warning. `audit → guard` is permanent and silent; `ci` is a current first-class pipeline command.
 
 ### CLI Flags
 
@@ -330,7 +333,7 @@ Run them solo (`docguard init --with hooks`) or stacked (`docguard init --with a
 | `--dir <path>` | Project directory (default: `.`) | All |
 | `--verbose` | Show detailed output | All |
 | `--quiet` / `-q` | Suppress banner — for hooks, CI loops, scripts | All |
-| `--format json` | Machine-readable output (clean JSON, no ANSI bleed) | guard, score, diff, trace, diagnose, memory, impact, explain |
+| `--format json` | Machine-readable output (clean JSON, no ANSI bleed) | guard, score, diff, trace, diagnose, memory, impact, explain, retire, specs |
 | `--format sarif` | SARIF 2.1.0 output — findings as rules/results for GitHub Code Scanning and SARIF dashboards | guard |
 | `--format junit` | JUnit XML output — one testcase per validator, for GitLab CI (`artifacts:reports:junit`), Jenkins, Azure DevOps, CircleCI | guard |
 | `--update-baseline` | Adopt DocGuard on a legacy repo without a red day one: freeze today's findings into a committed `.docguard.baseline.json`; guard/ci then gate only NEW drift. Suppression is always visible ("N pre-existing finding(s) suppressed"), and `--no-baseline` shows the full picture | guard |
@@ -389,7 +392,7 @@ $ npx docguard-cli generate
 
 ## 🔍 Validators
 
-DocGuard runs **27 automated validators** on every `guard` check. Every one is **language-aware** as of v0.16 — patterns for Python (`test_*.py`), Rust (`tests/*.rs`), Go (`*_test.go`), Java (`*Test.java`), Ruby (`*_spec.rb`), PHP, and JS/TS all match.
+DocGuard runs **29 automated validators** on every `guard` check. Source-facing validators are language-aware where their evidence model applies; repository and document validators operate independently of source language.
 
 | # | Validator | What It Checks | Default |
 |:--|:----------|:--------------|:--------|
@@ -412,14 +415,16 @@ DocGuard runs **27 automated validators** on every `guard` check. Every one is *
 | 17 | **TODO-Tracking** | Untracked TODOs/FIXMEs and skipped tests (skips test files by default) | ✅ On |
 | 18 | **Schema-Sync** | Database models documented in DATA-MODEL.md | ✅ On |
 | 19 | **Spec-Kit** | Spec quality validation (FR-IDs, mandatory sections, phased tasks) | ✅ On |
-| 20 | **Cross-Reference** | Internal markdown links + anchors resolve (with "did you mean?" hints); Obsidian wikilinks validated when the repo uses them as file links (`.obsidian` present or a target resolves) | ✅ On |
-| 21 | **Generated-Staleness** | `source=code` sections match scanner output; `status: draft` doc age | ✅ On |
-| 22 | **Canonical-Sync** | DocGuard's own README count claims match code-truth (DocGuard repo only — N/A elsewhere) | ✅ On |
-| 23 | **Metrics-Consistency** | Hardcoded numbers match actual counts | ✅ On |
-| 24 | **Surface-Sync** | Item-level enumerable drift — names in doc tables/lists (commands, checks, etc.) match code-truth (opt-in via `surfaceSync.surfaces`; N/A unless configured) | ✅ On |
-| 25 | **Diff-Suspicion** | Change-driven: a doc/agent-instruction file that references code changed since the ref AND shares removed domain symbols is flagged for review (arXiv 2010.01625, F1 74.7) | ✅ On |
-| 26 | **Reference-Existence** | Two-revision check: a backticked code symbol present when the doc was last updated but gone at HEAD is flagged as outdated (arXiv 2212.01479) | ✅ On |
-| 27 | **API-Doc-Smells** | Bloated (≥300 words) / Lazy (≤6 prose words) API documentation units, keyed on signature-headed sections (F1 0.90/0.95) | ✅ On |
+| 20 | **Document-Lifecycle** | Exact terminal states, advisory completion signals, incomplete coverage, and manifest/working-tree inconsistencies | ✅ On |
+| 21 | **Spec-Registry** | Immutable spec identities, byte-stable evidence projection, reviewed lifecycle preservation, and archive/storage consistency | ✅ On |
+| 22 | **Cross-Reference** | Internal markdown links + anchors resolve (with "did you mean?" hints); Obsidian wikilinks validated when the repo uses them as file links (`.obsidian` present or a target resolves) | ✅ On |
+| 23 | **Generated-Staleness** | `source=code` sections match scanner output; `status: draft` doc age | ✅ On |
+| 24 | **Canonical-Sync** | DocGuard's own README count claims match code-truth (DocGuard repo only — N/A elsewhere) | ✅ On |
+| 25 | **Metrics-Consistency** | Hardcoded numbers match actual counts | ✅ On |
+| 26 | **Surface-Sync** | Item-level enumerable drift — names in doc tables/lists (commands, checks, etc.) match code-truth (opt-in via `surfaceSync.surfaces`; N/A unless configured) | ✅ On |
+| 27 | **Diff-Suspicion** | Change-driven: a doc/agent-instruction file that references code changed since the ref AND shares removed domain symbols is flagged for review (arXiv 2010.01625, F1 74.7) | ✅ On |
+| 28 | **Reference-Existence** | Two-revision check: a backticked code symbol present when the doc was last updated but gone at HEAD is flagged as outdated (arXiv 2212.01479) | ✅ On |
+| 29 | **API-Doc-Smells** | Bloated (≥300 words) / Lazy (≤6 prose words) API documentation units, keyed on signature-headed sections (F1 0.90/0.95) | ✅ On |
 
 **Per-validator controls** (in `.docguard.json`):
 ```json
@@ -510,7 +515,7 @@ DocGuard provides AI agent slash commands for integrated workflows. Installed au
 | Command | What It Does |
 |:--------|:-------------|
 | `/docguard.init` | Initialize Canonical-Driven Development in a new or existing project |
-| `/docguard.guard` | Run quality validation — check all 27 validators |
+| `/docguard.guard` | Run quality validation — check all 29 validators |
 | `/docguard.review` | Analyze doc quality and suggest improvements |
 | `/docguard.fix` | Generate targeted fix prompts for specific issues |
 | `/docguard.update` | Update canonical docs after code changes — detect drift and sync documentation |

package/cli/commands/diagnose.mjs

@@ -101,10 +101,8 @@ const FIX_INSTRUCTIONS = {
     autoFixable: false,
   },
   'Freshness': {
-    action: 'Review stale documents',
-    command: 'docguard fix --doc',
-    llmCommand: '/docguard.fix --doc',
-    description: 'Documents haven\'t been reviewed since recent code changes. Re-run fix --doc for each stale doc.',
+    action: 'Review document evidence against relevant changes',
+    description: 'Review signals do not establish incorrect documentation. Check whether the documentation or implementation needs a change; preserve approved intent.',
     autoFixable: false,
   },
   // ── Routed (Phase F): these used to fall through to a generic "Manual review needed" ──
@@ -257,23 +255,6 @@ export function runDiagnose(projectDir, config, flags) {
     }
   }
 
-  // Detect stale docs from freshness and map to specific fix --doc targets
-  for (const issue of issues) {
-    if (issue.validator === 'Freshness' && !issue.docTarget) {
-      const match = issue.message.match(/([\w-]+\.md)/i);
-      if (match) {
-        const docName = match[1].toLowerCase().replace('.md', '');
-        const docMap = { 'architecture': 'architecture', 'data-model': 'data-model', 'security': 'security', 'test-spec': 'test-spec', 'environment': 'environment' };
-        issue.docTarget = docMap[docName] || null;
-        if (issue.docTarget) {
-          issue.command = agentMode === 'llm'
-            ? `/docguard.fix --doc ${issue.docTarget}`
-            : `docguard fix --doc ${issue.docTarget}`;
-        }
-      }
-    }
-  }
-
   // ── Step 4: Output ──
   if (flags.format === 'json') {
     outputJSON(guardData, scoreData, issues);
@@ -497,7 +478,7 @@ function outputPrompt(projectDir, guardData, scoreData, issues, flags, agentMode
   } else {
     lines.push('After making all fixes, run: docguard guard');
   }
-  lines.push('Expected result: All checks pass (0 errors, 0 warnings)');
+  lines.push('Expected result: Resolve verified defects; explain remaining review signals and unsupported checks. Do not rewrite correct documents merely to remove warnings.');
   lines.push(`Structural baseline: ${scoreData.score}/100. Resolve evidenced defects; verify material claims separately.`);
   lines.push('Preserve approved requirements when implementation disagrees. A higher score is not proof of factual correctness.');
 

package/cli/commands/explain.mjs

@@ -252,6 +252,32 @@ const EXPLAINERS = {
     example: 'plan.md has Summary, Technical Context, Constitution Check, Project Structure',
     standard: 'GitHub Spec Kit',
   },
+  documentLifecycle: {
+    title: 'Document-Lifecycle — retired documents leave active AI context safely',
+    what: 'Scans Git-tracked Markdown for exact terminal lifecycle metadata, completed specs that merit review, and disagreement between the working tree and .docguard-archive.json. It does not infer that completed work is safe to retire.',
+    why: 'Historical specs and plans can mislead people and agents when they remain mixed with current intent. Retirement must preserve recovery evidence and avoid deleting still-referenced context.',
+    triggers: [
+      ['declares terminal lifecycle status', 'Review the document, its backreferences, and its replacement or evidence, then retire the explicit clean tracked path with `docguard retire --write`.'],
+      ['artifact maturity is', 'Completion is only a review signal. Confirm the implemented outcome is represented in current documentation before considering retirement.'],
+      ['fully checked task list', 'Checked tasks do not prove delivery or documentation reconciliation. Verify code/test evidence and current docs.'],
+      ['Document lifecycle coverage is', 'Restore Git access, repair the retirement manifest, or make tracked Markdown readable before relying on the lifecycle result.'],
+      ['recorded as retired but remains', 'Complete the recorded retirement or correct the manifest so active context and recovery metadata agree.'],
+    ],
+    example: 'A superseded plan is absent from the working tree, recorded in .docguard-archive.json with a retained Git ref, and linked to its current replacement.',
+    standard: 'Canonical-Driven Development lifecycle and Git-backed recovery contract',
+  },
+  specRegistry: {
+    title: 'Spec-Registry — one lifecycle index for intent, delivery, and evidence',
+    what: 'Checks that every active spec has an immutable identity and that `.docguard-specs.json` exactly reflects spec artifacts, task counts, explicit test references, and archive tombstones while preserving reviewed lifecycle, lineage, and scope fields.',
+    why: 'Agents need to know which intent is current and what evidence exists before they create another spec. A deterministic registry makes stale state visible without copying or rewriting requirement prose.',
+    triggers: [
+      ['registry is missing or stale', 'Run `docguard specs --write`, review the projection, and commit it with the relevant change.'],
+      ['identity missing or reused', 'Add one unique namespaced Spec ID to the authoritative spec metadata; never recycle a retired ID.'],
+      ['lifecycle contradicts storage', 'Align current/retired context and working_tree/git_history storage with the recovery archive.'],
+    ],
+    example: '`docguard specs preflight --path specs/007-feature/spec.md` blocks reused IDs and reports prior lifecycle/evidence before planning.',
+    standard: 'Canonical-Driven Development lifecycle registry contract',
+  },
 
   // ── Backfilled in v0.24 (field report, Issue A) ─────────────────────────
   // These validators were registered in guard but had no explain entry, so
@@ -377,6 +403,8 @@ const DISPLAY_NAMES = {
   todoTracking: 'TODO-Tracking',
   schemaSync: 'Schema-Sync',
   specKit: 'Spec-Kit',
+  documentLifecycle: 'Document-Lifecycle',
+  specRegistry: 'Spec-Registry',
   crossReference: 'Cross-Reference',
   generatedStaleness: 'Generated-Staleness',
   surfaceSync: 'Surface-Sync',

package/cli/commands/guard.mjs

@@ -155,6 +155,8 @@ import { validateSurfaceSync } from '../validators/surface-sync.mjs';
 import { validateDiffSuspicion } from '../validators/diff-suspicion.mjs';
 import { validateReferenceExistence } from '../validators/reference-existence.mjs';
 import { validateApiDocSmells } from '../validators/api-doc-smells.mjs';
+import { validateDocumentLifecycle } from '../validators/document-lifecycle.mjs';
+import { validateSpecRegistry } from '../validators/spec-registry.mjs';
 
 /**
  * Internal guard — returns structured data, no console output, no process.exit.
@@ -319,6 +321,8 @@ export function runGuardInternal(projectDir, config) {
     { key: 'todoTracking', name: 'TODO-Tracking', fn: () => validateTodoTracking(projectDir, config) },
     { key: 'schemaSync', name: 'Schema-Sync', fn: () => validateSchemaSync(projectDir, config) },
     { key: 'specKit', name: 'Spec-Kit', fn: () => validateSpecKitIntegration(projectDir, config) },
+    { key: 'documentLifecycle', name: 'Document-Lifecycle', fn: () => validateDocumentLifecycle(projectDir, config) },
+    { key: 'specRegistry', name: 'Spec-Registry', fn: () => validateSpecRegistry(projectDir, config) },
     { key: 'crossReference', name: 'Cross-Reference', fn: () => validateCrossReferences(projectDir, config) },
     { key: 'generatedStaleness', name: 'Generated-Staleness', fn: () => validateGeneratedStaleness(projectDir, config) },
     { key: 'surfaceSync', name: 'Surface-Sync', fn: () => validateSurfaceSync(projectDir, config) },

package/cli/commands/llms.mjs

@@ -15,10 +15,11 @@
  *   - `docguard guard` validates llms.txt exists and is current
  */
 
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { resolve, join, basename } from 'node:path';
 import { c } from '../shared.mjs';
 import { listCanonicalDocs } from '../shared-ignore.mjs';
+import { safeWrite } from '../writers/generate-io.mjs';
 
 // ──── Doc descriptions for llms.txt ────
 const DOC_DESCRIPTIONS = {
@@ -201,7 +202,7 @@ export function runLlms(projectDir, config, flags) {
 
   const fileName = full ? 'llms-full.txt' : 'llms.txt';
   const outputPath = resolve(projectDir, fileName);
-  writeFileSync(outputPath, content, 'utf-8');
+  safeWrite(outputPath, content);
 
   console.log(`${c.bold}📄 DocGuard ${fileName} Generator${c.reset}`);
   console.log(`${c.green}✅ Generated ${outputPath}${c.reset}`);

package/cli/commands/retire.mjs

@@ -0,0 +1,352 @@
+/**
+ * Document lifecycle retirement.
+ *
+ * Historical prose leaves the working tree so agents cannot mistake it for
+ * current intent. Git remains the content store; a compact manifest records
+ * why each path left and how to restore it.
+ */
+
+import {
+  existsSync,
+  lstatSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  unlinkSync,
+} from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { basename, dirname, extname, relative, resolve, sep } from 'node:path';
+import { safeWrite } from '../writers/generate-io.mjs';
+import { scanDocumentLifecycle } from '../scanners/document-lifecycle.mjs';
+import { parseSpecId, readSpecRegistry } from '../scanners/spec-registry.mjs';
+import {
+  collectRequirementIdsFromContent,
+  requirementPatterns,
+} from '../shared-requirements.mjs';
+
+const MANIFEST_PATH = '.docguard-archive.json';
+const PROTECTED_PREFIXES = ['.git', '.local', '.docguard'];
+const DOCUMENT_EXTENSIONS = new Set(['.md', '.mdx', '.rst', '.adoc']);
+
+function git(projectDir, args) {
+  const result = spawnSync('git', args, {
+    cwd: projectDir,
+    encoding: 'utf8',
+    maxBuffer: 8 * 1024 * 1024,
+  });
+  if (result.status !== 0) {
+    const detail = (result.stderr || result.stdout || '').trim();
+    throw new Error(detail || `git ${args.join(' ')} failed`);
+  }
+  return result.stdout;
+}
+
+function repositoryRoot(projectDir) {
+  const root = git(projectDir, ['rev-parse', '--show-toplevel']).trim();
+  const requested = realpathSync(projectDir);
+  if (realpathSync(root) !== requested) {
+    throw new Error('Retirement must run from the repository root. Pass --dir <repository-root>.');
+  }
+  return requested;
+}
+
+function toPosix(path) {
+  return path.split(sep).join('/').replace(/^\.\//, '');
+}
+
+function validateSelection(root, input) {
+  if (!input || input.includes('\0')) throw new Error('Retirement paths must be non-empty.');
+  const absolute = resolve(root, input);
+  const rel = toPosix(relative(root, absolute));
+  if (!rel || rel === '.' || rel === '..' || rel.startsWith('../')) {
+    throw new Error(`Retirement path must stay inside the repository: ${input}`);
+  }
+  if (PROTECTED_PREFIXES.some(prefix => rel === prefix || rel.startsWith(`${prefix}/`))) {
+    throw new Error(`Retirement refuses protected path: ${rel}`);
+  }
+  if (rel === MANIFEST_PATH) throw new Error(`Retirement refuses its recovery manifest: ${rel}`);
+  if (!existsSync(absolute)) throw new Error(`Retirement path does not exist: ${rel}`);
+  if (lstatSync(absolute).isSymbolicLink()) throw new Error(`Retirement refuses symlinks: ${rel}`);
+  const resolved = realpathSync(absolute);
+  if (resolved !== root && !resolved.startsWith(`${root}${sep}`)) {
+    throw new Error(`Retirement path resolves outside the repository: ${rel}`);
+  }
+  return rel;
+}
+
+function trackedFiles(projectDir, selections) {
+  const files = new Set();
+  for (const selection of selections) {
+    const output = git(projectDir, ['ls-files', '-z', '--', selection]);
+    const matches = output.split('\0').filter(Boolean);
+    if (matches.length === 0) throw new Error(`Retirement path is not tracked by Git: ${selection}`);
+    for (const match of matches) files.add(toPosix(match));
+  }
+  return [...files].sort();
+}
+
+function assertSelectionsContainOnlyTrackedFiles(projectDir, selections) {
+  for (const selection of selections) {
+    const status = git(projectDir, [
+      'status', '--porcelain=v1', '--untracked-files=all', '--ignored', '--', selection,
+    ]);
+    if (status.split('\n').some(line => line.startsWith('?? ') || line.startsWith('!! '))) {
+      throw new Error(`Retirement selection contains untracked or ignored files: ${selection}`);
+    }
+  }
+}
+
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", `'\\''`)}'`;
+}
+
+function requiredFiles(config) {
+  const required = config?.requiredFiles || {};
+  const values = [
+    ...(Array.isArray(required.canonical) ? required.canonical : []),
+    ...(Array.isArray(required.agentFile) ? required.agentFile : []),
+    required.changelog,
+    required.driftLog,
+  ];
+  return new Set(values.filter(value => typeof value === 'string').map(toPosix));
+}
+
+function assertArchivable(projectDir, files, config) {
+  const protectedFiles = requiredFiles(config);
+  for (const file of files) {
+    if (!DOCUMENT_EXTENSIONS.has(extname(file).toLowerCase())) {
+      throw new Error(`Retirement accepts documentation files only; refusing ${file}.`);
+    }
+    if (protectedFiles.has(file)) {
+      throw new Error(`Retirement refuses required file ${file}; replace and reconfigure it first.`);
+    }
+    const absolute = resolve(projectDir, file);
+    if (!existsSync(absolute)) throw new Error(`Retirement path disappeared: ${file}`);
+    if (lstatSync(absolute).isSymbolicLink()) throw new Error(`Retirement refuses symlinks: ${file}`);
+    const status = git(projectDir, ['status', '--porcelain=v1', '--', file]).trim();
+    if (status) throw new Error(`Retirement requires a clean tracked file: ${file}`);
+    const stage = git(projectDir, ['ls-files', '--stage', '--', file]).trim();
+    if (stage.startsWith('160000 ')) throw new Error(`Retirement refuses Git submodules: ${file}`);
+  }
+}
+
+function assertCleanTrackedDocument(projectDir, input, label) {
+  const rel = validateSelection(projectDir, input);
+  const files = trackedFiles(projectDir, [rel]);
+  if (files.length !== 1 || files[0] !== rel || !DOCUMENT_EXTENSIONS.has(extname(rel).toLowerCase())) {
+    throw new Error(`${label} must name one tracked documentation file: ${rel}`);
+  }
+  const status = git(projectDir, ['status', '--porcelain=v1', '--', rel]).trim();
+  if (status) throw new Error(`${label} must be clean at the recorded source revision: ${rel}`);
+  return rel;
+}
+
+function assertNoLiveBackreferences(projectDir, files) {
+  const selected = new Set(files);
+  const docs = trackedFiles(projectDir, ['*.md']);
+  for (const doc of docs) {
+    if (selected.has(doc)) continue;
+    const absolute = resolve(projectDir, doc);
+    if (!existsSync(absolute)) continue;
+    let content;
+    try { content = readFileSync(absolute, 'utf8'); } catch { continue; }
+    const link = /!?\[[^\]]*\]\((?:<([^>]+)>|([^\s)]+))(?:\s+[^)]*)?\)/g;
+    let match;
+    while ((match = link.exec(content)) !== null) {
+      const raw = (match[1] || match[2] || '').split('#')[0].split('?')[0];
+      if (!raw || raw.startsWith('/') || /^[a-z][a-z0-9+.-]*:/i.test(raw)) continue;
+      let decoded = raw;
+      try { decoded = decodeURIComponent(raw); } catch { /* use literal path */ }
+      const target = toPosix(relative(projectDir, resolve(dirname(absolute), decoded)));
+      if (!selected.has(target)) continue;
+      const line = content.slice(0, match.index).split('\n').length;
+      throw new Error(`Retirement refuses ${target}; live backreference remains at ${doc}:${line}.`);
+    }
+  }
+}
+
+function assertNoCurrentRegisteredSpec(projectDir, files) {
+  const loaded = readSpecRegistry(projectDir);
+  if (loaded.error) throw new Error(`Retirement cannot verify spec lifecycle: ${loaded.error}`);
+  if (!loaded.exists) return;
+  for (const entry of loaded.value.specs) {
+    const lifecycle = entry.reviewed?.lifecycle || entry.lifecycle;
+    if (lifecycle?.context !== 'current') continue;
+    const specDir = dirname(entry.path);
+    const selected = files.find(path => path === entry.path || path.startsWith(`${specDir}/`));
+    if (selected) {
+      throw new Error(`Retirement refuses active registered spec ${entry.specId} (${selected}). Transition it through the docguard specs lifecycle before removing its artifacts.`);
+    }
+  }
+}
+
+function refExists(projectDir, ref) {
+  const result = spawnSync('git', ['show-ref', '--verify', '--quiet', ref], { cwd: projectDir });
+  return result.status === 0;
+}
+
+function retentionRef(projectDir, explicit) {
+  let ref = explicit?.trim() || null;
+  if (!ref) {
+    const remoteHead = spawnSync('git', ['symbolic-ref', '--quiet', 'refs/remotes/origin/HEAD'], {
+      cwd: projectDir,
+      encoding: 'utf8',
+    });
+    if (remoteHead.status === 0) ref = remoteHead.stdout.trim();
+  }
+  if (!ref && refExists(projectDir, 'refs/heads/main')) ref = 'refs/heads/main';
+  if (!ref && refExists(projectDir, 'refs/heads/master')) ref = 'refs/heads/master';
+  if (!ref) {
+    throw new Error('Retirement needs a retained branch ref. Pass --retention-ref <ref> after pushing the source revision.');
+  }
+  git(projectDir, ['rev-parse', '--verify', ref]);
+  const contains = spawnSync('git', ['merge-base', '--is-ancestor', 'HEAD', ref], { cwd: projectDir });
+  if (contains.status !== 0) {
+    throw new Error(`Retirement source HEAD is not retained by ${ref}; push or merge it before retirement.`);
+  }
+  return ref;
+}
+
+function loadManifest(projectDir) {
+  const path = resolve(projectDir, MANIFEST_PATH);
+  if (!existsSync(path)) return { schemaVersion: 1, strategy: 'git-history', entries: [] };
+  let parsed;
+  try { parsed = JSON.parse(readFileSync(path, 'utf8')); } catch {
+    throw new Error(`${MANIFEST_PATH} is not valid JSON.`);
+  }
+  if (parsed?.schemaVersion !== 1 || parsed?.strategy !== 'git-history' || !Array.isArray(parsed.entries)) {
+    throw new Error(`${MANIFEST_PATH} does not use the supported schema.`);
+  }
+  return parsed;
+}
+
+function writeArchive(projectDir, config, flags) {
+  if (!flags.paths?.length) throw new Error('Retire --write requires at least one --path <file-or-directory>.');
+  if (!flags.reason?.trim()) throw new Error('Retire --write requires --reason <why-this-is-no-longer-current>.');
+
+  const selections = flags.paths.map(path => validateSelection(projectDir, path));
+  const supersededBy = flags.supersededBy
+    ? assertCleanTrackedDocument(projectDir, flags.supersededBy, 'Replacement')
+    : null;
+  const evidence = (flags.evidencePaths || []).map(path =>
+    assertCleanTrackedDocument(projectDir, path, 'Evidence'));
+  assertSelectionsContainOnlyTrackedFiles(projectDir, selections);
+  const files = trackedFiles(projectDir, selections);
+  if (supersededBy) {
+    git(projectDir, ['ls-files', '--error-unmatch', '--', supersededBy]);
+    if (files.includes(supersededBy)) throw new Error('A replacement document cannot be archived in the same operation.');
+  }
+  const selectedEvidence = evidence.find(path => files.includes(path));
+  if (selectedEvidence) throw new Error(`Evidence cannot be retired in the same operation: ${selectedEvidence}`);
+  assertArchivable(projectDir, files, config);
+  assertNoCurrentRegisteredSpec(projectDir, files);
+  assertNoLiveBackreferences(projectDir, files);
+
+  const commit = git(projectDir, ['rev-parse', 'HEAD']).trim();
+  const retainedBy = retentionRef(projectDir, flags.retentionRef);
+  const objectFormat = git(projectDir, ['rev-parse', '--show-object-format']).trim();
+  const archivedAt = new Date().toISOString();
+  const manifest = loadManifest(projectDir);
+  const patterns = requirementPatterns(config);
+  const specIdsByDirectory = new Map();
+  for (const path of files) {
+    if (basename(path).toLowerCase() !== 'spec.md') continue;
+    const specId = parseSpecId(readFileSync(resolve(projectDir, path), 'utf8'));
+    if (specId) specIdsByDirectory.set(dirname(path), specId);
+  }
+  const entries = files.map(path => {
+    const content = readFileSync(resolve(projectDir, path), 'utf8');
+    const requirementIds = [...new Set(
+      [...collectRequirementIdsFromContent(content, path, patterns).values()]
+        .map(definition => definition.id),
+    )].sort();
+    return {
+      path,
+      archivedAt,
+      archivedFrom: commit,
+      blob: git(projectDir, ['rev-parse', `HEAD:${path}`]).trim(),
+      reason: flags.reason.trim(),
+      ...(specIdsByDirectory.get(dirname(path)) ? { specId: specIdsByDirectory.get(dirname(path)) } : {}),
+      ...(supersededBy ? { supersededBy } : {}),
+      ...(evidence.length > 0 ? { evidence } : {}),
+      ...(requirementIds.length > 0 ? { requirementIds } : {}),
+      retentionRef: retainedBy,
+      objectFormat,
+      recoverability: 'verified',
+      restore: `git restore --source=${shellQuote(commit)} -- ${shellQuote(path)}`,
+    };
+  });
+
+  const next = { ...manifest, entries: [...manifest.entries, ...entries] };
+  assertArchivable(projectDir, files, config);
+  const removed = [];
+  try {
+    for (const file of files) {
+      unlinkSync(resolve(projectDir, file));
+      removed.push(file);
+    }
+    safeWrite(resolve(projectDir, MANIFEST_PATH), `${JSON.stringify(next, null, 2)}\n`);
+  } catch (error) {
+    if (removed.length > 0) {
+      spawnSync('git', ['restore', `--source=${commit}`, '--', ...removed], { cwd: projectDir });
+    }
+    throw error;
+  }
+
+  const directories = [...new Set(files.map(dirname))]
+    .filter(path => path !== '.')
+    .sort((a, b) => b.length - a.length);
+  for (const directory of directories) {
+    try { rmSync(resolve(projectDir, directory)); } catch { /* non-empty directories remain */ }
+  }
+  return { status: 'ARCHIVED', strategy: 'git-history', manifest: MANIFEST_PATH, entries };
+}
+
+function printText(result) {
+  if (result.status === 'ARCHIVED') {
+    console.log(`Retired ${result.entries.length} tracked file(s) from the working tree.`);
+    console.log(`Manifest: ${result.manifest}`);
+    for (const entry of result.entries) console.log(`  ${entry.path}`);
+    return;
+  }
+  console.log('DocGuard Retirement Plan');
+  console.log('Strategy: Git history + compact manifest (obsolete prose is not copied).');
+  if (result.candidates.length === 0) {
+    console.log('No lifecycle candidates found.');
+  } else {
+    for (const candidate of result.candidates) {
+      console.log(`  [${candidate.confidence}] ${candidate.path} — ${candidate.reason}`);
+    }
+  }
+  console.log('Review candidates, then retire explicitly with --write --path <path> --reason <reason>.');
+}
+
+export function runArchive(projectDir, config, flags = {}) {
+  try {
+    const root = repositoryRoot(projectDir);
+    const result = flags.write
+      ? writeArchive(root, config, flags)
+      : {
+          status: 'PLAN',
+          strategy: 'git-history',
+          manifest: MANIFEST_PATH,
+          ...scanDocumentLifecycle(root, config),
+        };
+    if (result.status === 'PLAN' && result.coverage.status !== 'complete') {
+      throw new Error(result.coverage.error || `Lifecycle scan is ${result.coverage.status}.`);
+    }
+    if (flags.format === 'json') console.log(JSON.stringify(result, null, 2));
+    else printText(result);
+    if (flags.check && result.status === 'PLAN') {
+      const blocking = result.candidates.filter(candidate => candidate.confidence === 'high');
+      if (blocking.length > 0 || (flags.failOnWarning && result.candidates.length > 0)) process.exitCode = 2;
+    }
+    return result;
+  } catch (error) {
+    const result = { status: 'ERROR', error: error.message };
+    if (flags.format === 'json') console.log(JSON.stringify(result, null, 2));
+    else console.error(`Retirement failed: ${error.message}`);
+    process.exitCode = 1;
+    return result;
+  }
+}