docguard-cli 0.37.1 → 0.39.0

package/README.md

@@ -69,13 +69,13 @@ 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 (22)"]
+    CLI["CLI Entry<br/>docguard.mjs"] --> Commands["Commands (23)"]
     Commands --> guard["guard"]
     Commands --> generate["generate"]
     Commands --> score["score"]
     Commands --> diagnose["diagnose"]
     Commands --> setup["setup wizard"]
-    Commands --> other["diff · init · fix · trace · impact · sync · retire · specs<br/>explain · memory · upgrade · agents · hooks · badge · ci · watch"]
+    Commands --> other["diff · init · fix · trace · impact · sync · reconcile · retire · specs<br/>explain · memory · upgrade · agents · hooks · badge · ci · watch"]
 
     guard --> Validators["Validators (29)"]
     generate --> Scanners["Scanners (4)<br/>routes · schemas · doc-tools · speckit"]
@@ -268,7 +268,7 @@ This installs DocGuard's slash commands (`/docguard.init`, `/docguard.guard`, `/
 
 ## Usage
 
-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.
+DocGuard ships **23 commands** (the "Daily 5" + 18 situational tools, including lifecycle reconciliation, 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:
 
@@ -294,8 +294,10 @@ DocGuard ships **22 commands** (the "Daily 5" + 17 situational tools, including
 | `explain <warning\|CODE>` | Paste any warning — or a finding code like `SEC001` — to get the validator's docstring, fix path, and how to suppress |
 | `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) |
+| `feedback` | Review any finding or a synthetic false-positive/false-negative/unsupported fixture; verify its opposite control, reduce it deterministically, search open and closed duplicates, and optionally emit a test-only contribution. Nothing is submitted automatically. |
 | `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. |
+| `reconcile` | Build a read-only code↔spec review graph since a Git ref. Classifies mechanical facts, approved intent, decisions, unrelated changes, and unsupported evidence; `--write` applies only mechanical generated-section refreshes. |
+| `specs` | Maintain the versioned spec registry, preflight new specs, and apply evidence-gated completion transactions with bounded outcomes and active-context regeneration. Verified living specs can record later reviewed maintenance without reopening or duplicating the specification. |
 | `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`) |
@@ -333,7 +335,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, retire, specs |
+| `--format json` | Machine-readable output (clean JSON, no ANSI bleed) | guard, score, diff, trace, diagnose, memory, impact, explain, reconcile, 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 |

package/cli/commands/feedback.mjs

@@ -12,15 +12,23 @@
  *
  * Nothing is transmitted automatically. This command never scaffolds skills
  * or edits source files. Zero npm dependencies — pure Node.js built-ins.
+ * @implements docguard.precision-evidence-loop#FR-012
+ * @implements docguard.precision-evidence-loop#FR-015
+ * @implements docguard.precision-evidence-loop#FR-016
  */
 
-import { existsSync, mkdirSync, readFileSync } from 'node:fs';
-import { resolve, dirname } from 'node:path';
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { resolve, dirname, join, relative, sep } from 'node:path';
+import { tmpdir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { c } from '../shared.mjs';
 import { CODES } from '../findings.mjs';
 import { safeWrite } from '../writers/generate-io.mjs';
 import { runGuardInternal } from './guard.mjs';
+import {
+  buildTestOnlyContribution, feedbackFindingIdentity, feedbackSearchUrls, parseFeedbackFixture,
+  reduceFixtureDeterministically,
+} from '../feedback-fixture.mjs';
 
 const _PKG = JSON.parse(
   readFileSync(resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json'), 'utf-8')
@@ -39,16 +47,20 @@ function shortId(str) {
 }
 
 /** Shared output deliberately excludes every source-derived string. */
-export function buildIssueUrl(finding) {
+export function buildIssueUrl(finding, context = null) {
   const code = Object.hasOwn(CODES, finding.code || '') ? finding.code : 'FINDING';
   const validator = CODES[code]?.validator || 'unknown';
-  const title = `[feedback] ${code} (${validator}): detection feedback`;
+  const classification = context?.classification || 'false_positive';
+  const title = `[feedback] ${code} (${validator}): ${classification.replaceAll('_', ' ')}`;
   const confidence = ['high', 'medium', 'low'].includes(finding.confidence) ? finding.confidence : 'unknown';
   const body = [
     `DocGuard v${CLI_VERSION}`,
     `- Code: ${code}`,
     `- Validator: ${validator}`,
     `- Confidence: ${confidence}`,
+    `- Classification: ${classification}`,
+    ...(context?.parserTier ? [`- Parser tier: ${context.parserTier}`] : []),
+    ...(context?.duplicateIdentity ? [`- Duplicate identity: ${context.duplicateIdentity}`] : []),
     '',
     'Expected behavior:',
     'Actual behavior:',
@@ -60,12 +72,139 @@ export function buildIssueUrl(finding) {
     'Generated by docguard feedback. No project paths, messages, source code, or secret values are included.',
   ].join('\n');
   const url = `${ISSUES_BASE}/new?labels=docguard-feedback&title=${encodeURIComponent(title)}&body=${encodeURIComponent(body)}`;
-  const query = `repo:raccioly/docguard ${code}`;
+  const query = context?.duplicateIdentity ? `repo:raccioly/docguard "${context.duplicateIdentity}"` : `repo:raccioly/docguard ${code}`;
   const searchUrl = `https://github.com/search?q=${encodeURIComponent(query)}&type=issues`;
   return { url: url.length <= URL_CAP ? url : `${ISSUES_BASE}/new`, title, searchUrl };
 }
 
+const FEEDBACK_CLASSES = new Set(['false_positive', 'false_negative', 'unsupported_syntax', 'ambiguous', 'policy_disagreement']);
+
+function projectFile(projectDir, value, label) {
+  if (typeof value !== 'string' || !value || value.includes('\\')) throw new Error(`${label} must be a project-relative path.`);
+  const root = resolve(projectDir);
+  const path = resolve(root, value);
+  const rel = relative(root, path);
+  if (!rel || rel.startsWith(`..${sep}`) || rel === '..' || rel.split(sep).some(part => ['.git', '.local'].includes(part.toLowerCase()))) {
+    throw new Error(`${label} must remain in the project and outside protected directories.`);
+  }
+  return path;
+}
+
+function evaluateFileSet(manifest, fileSet) {
+  const root = mkdtempSync(join(tmpdir(), 'docguard-feedback-fixture-'));
+  try {
+    for (const file of fileSet.files) {
+      const target = resolve(root, file.path);
+      mkdirSync(dirname(target), { recursive: true });
+      writeFileSync(target, file.content, 'utf8');
+    }
+    const report = runGuardInternal(root, manifest.config);
+    const validator = (report.validators || []).find(item => item.key === manifest.detector.validator);
+    return {
+      identities: (report.findings || []).filter(item => item.code === manifest.detector.code).map(feedbackFindingIdentity).sort(),
+      applicability: validator?.applicability?.status || 'unknown',
+    };
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+function predicateMatches(manifest, result) {
+  if (manifest.interestingness.predicate === 'finding_present') return result.identities.includes(manifest.expectedIdentity);
+  if (manifest.interestingness.predicate === 'finding_absent') return !result.identities.includes(manifest.expectedIdentity);
+  return result.applicability === 'unsupported';
+}
+
+function oppositeMatches(manifest, result) {
+  if (manifest.interestingness.predicate === 'finding_present') return result.identities.includes(manifest.expectedIdentity);
+  if (manifest.interestingness.predicate === 'finding_absent') return !result.identities.includes(manifest.expectedIdentity);
+  return result.applicability === 'checked';
+}
+
+function runFixtureFeedback(projectDir, flags) {
+  let manifest;
+  try {
+    const manifestPath = projectFile(projectDir, flags.fixtureManifest, '--fixture-manifest');
+    if (!existsSync(manifestPath) || lstatSync(manifestPath).isSymbolicLink()) throw new Error('Fixture manifest must be a regular non-symlink file.');
+    const text = readFileSync(manifestPath, 'utf8');
+    if (Buffer.byteLength(text) > 262_144) throw new Error('Fixture manifest exceeds 256 KiB.');
+    manifest = parseFeedbackFixture(JSON.parse(text));
+    if (flags.classification && flags.classification !== manifest.classification) throw new Error('--classification disagrees with the fixture manifest.');
+  } catch (error) {
+    console.log(JSON.stringify({ status: 'ERROR', error: error.message }, null, 2));
+    process.exitCode = 1;
+    return;
+  }
+
+  const initial = evaluateFileSet(manifest, manifest.fixture);
+  const control = evaluateFileSet(manifest, manifest.oppositeControl);
+  const reproduced = predicateMatches(manifest, initial);
+  const controlConfirmed = oppositeMatches(manifest, control);
+  if (!reproduced || !controlConfirmed) {
+    console.log(JSON.stringify({
+      status: 'NOT_REPRODUCED', classification: manifest.classification,
+      reproductionConfirmed: reproduced, controlConfirmed,
+      message: 'The explicit predicate and opposite control must both reproduce before reduction or contribution.',
+    }, null, 2));
+    process.exitCode = 1;
+    return;
+  }
+
+  let reduction = null;
+  if (flags.reduce) {
+    reduction = reduceFixtureDeterministically(manifest, candidate => predicateMatches(candidate, evaluateFileSet(candidate, candidate.fixture)));
+    manifest = reduction.manifest;
+  }
+  const searches = feedbackSearchUrls(manifest, ISSUES_BASE);
+  const issue = buildIssueUrl({ code: manifest.detector.code, confidence: 'unknown' }, {
+    classification: manifest.classification, parserTier: manifest.parserTier, duplicateIdentity: searches.identity,
+  });
+  const feedbackDir = resolve(projectDir, '.docguard', 'feedback');
+  let record = null;
+  let contribution = null;
+  let contributionPreview = null;
+  try {
+    if (!flags.preview) {
+      record = resolve(feedbackDir, `${searches.identity}.fixture.json`);
+      safeWrite(record, `${JSON.stringify(manifest, null, 2)}\n`);
+    }
+    if (flags.contribution) {
+      if (!/^tests\/[^/]+\.test\.mjs$/.test(flags.contribution)) {
+        throw new Error('--contribution must be a direct tests/<name>.test.mjs path.');
+      }
+      contributionPreview = buildTestOnlyContribution(manifest);
+      if (!flags.preview) {
+        contribution = projectFile(projectDir, flags.contribution, '--contribution');
+        safeWrite(contribution, contributionPreview);
+      }
+    }
+  } catch (error) {
+    console.log(JSON.stringify({ status: 'ERROR', error: error.message }, null, 2));
+    process.exitCode = 1;
+    return;
+  }
+  const output = {
+    status: 'READY', preview: Boolean(flags.preview), classification: manifest.classification,
+    reproductionConfirmed: true, controlConfirmed: true, reduction: reduction ? { status: reduction.status, attempts: reduction.attempts } : null,
+    duplicateIdentity: searches.identity, searchUrls: searches, issueUrl: issue.url,
+    record: record ? relative(projectDir, record).split(sep).join('/') : null,
+    contribution: contribution ? relative(projectDir, contribution).split(sep).join('/') : null,
+    contributionPreview: flags.preview && flags.contribution ? contributionPreview : undefined,
+  };
+  console.log(JSON.stringify(output, null, 2));
+}
+
 export function runFeedback(projectDir, config, flags) {
+  if (flags.fixtureManifest) return runFixtureFeedback(projectDir, flags);
+  const classification = flags.classification || 'false_positive';
+  if (!FEEDBACK_CLASSES.has(classification) || classification === 'false_negative' || classification === 'unsupported_syntax') {
+    const error = classification === 'false_negative' || classification === 'unsupported_syntax'
+      ? 'This classification requires --fixture-manifest with an explicit expected identity and opposite control.'
+      : 'Unknown feedback classification.';
+    if (flags.format === 'json') console.log(JSON.stringify({ error, reportable: [] })); else console.error(error);
+    process.exitCode = 1;
+    return;
+  }
   const data = runGuardInternal(projectDir, config);
   const selectedCode = typeof flags.code === 'string' ? flags.code.toUpperCase() : null;
   if (flags.code !== undefined && (!selectedCode || !Object.hasOwn(CODES, selectedCode))) {
@@ -93,7 +232,7 @@ export function runFeedback(projectDir, config, flags) {
   const feedbackDir = resolve(projectDir, '.docguard', 'feedback');
   const items = reportable.map((f) => {
     const id = shortId(`${f.code}|${f.location || f.message}`);
-    const { url, title, searchUrl } = buildIssueUrl(f);
+    const { url, title, searchUrl } = buildIssueUrl(f, { classification });
     const fileName = `${(f.code || 'finding').toLowerCase()}-${id}.json`;
     const filePath = resolve(feedbackDir, fileName);
     return { finding: f, id, url, title, searchUrl, fileName, filePath, saved: false, error: null };
@@ -105,6 +244,7 @@ export function runFeedback(projectDir, config, flags) {
       if (!existsSync(feedbackDir)) mkdirSync(feedbackDir, { recursive: true });
       safeWrite(it.filePath, JSON.stringify({
         capturedBy: `docguard feedback (v${CLI_VERSION})`,
+        classification,
         finding: it.finding,
         issueUrl: it.url,
         searchUrl: it.searchUrl,
@@ -123,6 +263,7 @@ export function runFeedback(projectDir, config, flags) {
     console.log(JSON.stringify({
       version: CLI_VERSION,
       preview: Boolean(flags.preview),
+      classification,
       reportable: items.map(it => ({
         code: it.finding.code,
         location: it.finding.location,

package/cli/commands/reconcile.mjs

@@ -0,0 +1,42 @@
+/**
+ * Review code/spec changes before any documentation intent is changed.
+ * @implements docguard.document-lifecycle#FR-010
+ * @implements docguard.document-lifecycle#FR-012
+ */
+
+import { buildReconciliationPlan } from '../scanners/reconciliation.mjs';
+import { runSync } from './sync.mjs';
+
+function printPlan(result) {
+  console.log(`Reconciliation: ${result.status}`);
+  console.log(`Revision: ${result.baseRevision || 'unknown'} → ${result.revision || 'unknown'}`);
+  for (const item of result.classifications) {
+    console.log(`  [${item.confidence}] ${item.path || item.kind}: ${item.disposition}`);
+  }
+  if (result.writes.length) console.log(`Mechanical write available: ${result.writes[0].command}`);
+}
+
+export function runReconcile(projectDir, config, flags = {}) {
+  try {
+    if (flags.write && flags.check) throw new Error('Use either --check or --write, not both.');
+    const plan = buildReconciliationPlan(projectDir, config, flags.since);
+    let mechanical = null;
+    if (flags.write) {
+      if (plan.status === 'UNSUPPORTED' || plan.status === 'BLOCKED') {
+        throw new Error('Reconciliation write refused because evidence coverage is incomplete or the registry is invalid.');
+      }
+      mechanical = runSync(projectDir, config, { ...flags, write: true, silent: true });
+    }
+    const result = { command: 'reconcile', ...plan, applied: Boolean(flags.write), mechanical };
+    if (flags.format === 'json') console.log(JSON.stringify(result, null, 2));
+    else printPlan(result);
+    if (flags.check && !['READY'].includes(result.status)) process.exitCode = 2;
+    return result;
+  } catch (error) {
+    const result = { command: 'reconcile', 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/retire.mjs

@@ -4,6 +4,7 @@
  * 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.
+ * @implements docguard.document-lifecycle#FR-013
  */
 
 import {
@@ -12,11 +13,10 @@ import {
   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 { commitFileTransaction } from '../writers/file-transaction.mjs';
 import { scanDocumentLifecycle } from '../scanners/document-lifecycle.mjs';
 import { parseSpecId, readSpecRegistry } from '../scanners/spec-registry.mjs';
 import {
@@ -279,19 +279,15 @@ function writeArchive(projectDir, config, flags) {
 
   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;
-  }
+  commitFileTransaction([
+    { path: resolve(projectDir, MANIFEST_PATH), content: `${JSON.stringify(next, null, 2)}\n` },
+    ...files.map(file => ({ path: resolve(projectDir, file), content: null })),
+  ], {
+    validate: () => {
+      const written = loadManifest(projectDir);
+      if (written.entries.length !== next.entries.length) throw new Error('recovery manifest did not commit completely');
+    },
+  });
 
   const directories = [...new Set(files.map(dirname))]
     .filter(path => path !== '.')

package/cli/commands/specs.mjs

@@ -1,14 +1,201 @@
-/** Manage and preflight the deterministic spec lifecycle registry. */
+/**
+ * Manage and preflight the deterministic spec lifecycle registry.
+ * @implements docguard.document-lifecycle#FR-016
+ * @implements docguard.document-lifecycle#FR-017
+ * @implements docguard.document-lifecycle#FR-020
+ */
 
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { safeWrite } from '../writers/generate-io.mjs';
-import { preflightSpec, projectSpecRegistry, SPEC_REGISTRY_PATH } from '../scanners/spec-registry.mjs';
+import { commitFileTransaction } from '../writers/file-transaction.mjs';
+import { appendImplementationOutcome } from '../writers/spec-outcomes.mjs';
+import { serializeLifecycleContext } from '../scanners/lifecycle-context.mjs';
+import { buildReconciliationPlan } from '../scanners/reconciliation.mjs';
+import { preflightSpec, projectSpecRegistry, readSpecRegistry, SPEC_REGISTRY_PATH } from '../scanners/spec-registry.mjs';
+import { runGuardInternal } from './guard.mjs';
+
+const CONTEXT_PATH = '.docguard/current-context.json';
+const digest = content => `sha256:${createHash('sha256').update(content).digest('hex')}`;
+
+export function normalizeExternalDeliveryStatus(value) {
+  const normalized = String(value || '').trim().toLowerCase().replace(/[ -]+/g, '_');
+  return new Map([
+    ['planned', 'planned'], ['in_progress', 'in_progress'], ['started', 'in_progress'],
+    ['implemented', 'implemented'], ['complete', 'implemented'], ['completed', 'implemented'], ['done', 'implemented'],
+    ['verified', 'verified'], ['validated', 'verified'], ['released', 'released'], ['shipped', 'released'],
+  ]).get(normalized) || null;
+}
+
+function headRevision(projectDir) {
+  try {
+    return execFileSync('git', ['rev-parse', 'HEAD'], { cwd: projectDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  } catch { return null; }
+}
+
+function trackedDirty(projectDir) {
+  try {
+    return execFileSync('git', ['status', '--porcelain=v1', '--untracked-files=no'], {
+      cwd: projectDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch { return 'git-unavailable'; }
+}
+
+function archiveReadiness(spec, targetVerified = false) {
+  if (!spec) return { status: 'BLOCKED', reason: 'Spec identity is unresolved.' };
+  const model = spec.reviewed.lifecycle.persistenceModel;
+  const delivery = targetVerified ? 'verified' : spec.reviewed.lifecycle.delivery;
+  if (model === 'living') return { status: 'KEEP_CURRENT', reason: 'Living specs remain in active context after verification.' };
+  if (!model) return { status: 'REVIEW', reason: 'Choose a persistence model before retiring the verified spec.' };
+  if (delivery !== 'verified' && delivery !== 'released') return { status: 'BLOCKED', reason: 'Spec must be verified before retirement.' };
+  if (model === 'flow_forward' && !spec.reviewed.relations.supersededBy.length) {
+    return { status: 'BLOCKED', reason: 'Flow-forward retirement requires a reviewed successor.' };
+  }
+  return { status: 'READY', reason: 'Run the reviewed spec retirement flow after the verified state is committed and retained.' };
+}
+
+function completionTransition(spec) {
+  if (spec?.reviewed.lifecycle.delivery === 'verified') return 'verified→verified';
+  return spec?.reviewed.lifecycle.delivery === 'in_progress'
+    ? 'in_progress→implemented→verified'
+    : 'implemented→verified';
+}
+
+export function planSpecCompletion(projectDir, config, flags, options = {}) {
+  const projection = projectSpecRegistry(projectDir, config);
+  const loaded = readSpecRegistry(projectDir);
+  const revision = headRevision(projectDir);
+  const spec = projection.registry.specs.find(entry => entry.specId === flags.id);
+  const blockers = [...projection.issues];
+  if (!flags.id) blockers.push({ code: 'SPC001', message: 'Completion requires --id <spec-id>.' });
+  if (!loaded.exists || loaded.error || !projection.current) blockers.push({ code: 'SPC001', message: 'Committed registry must be current before completion.' });
+  if (!spec) blockers.push({ code: 'SPC001', message: `Unknown spec ID: ${flags.id || '<missing>'}.` });
+  if (!revision) blockers.push({ code: 'SPC001', message: 'Completion requires a resolvable Git HEAD.' });
+  if (trackedDirty(projectDir)) blockers.push({ code: 'SPC001', message: 'Completion requires a clean tracked working tree at the recorded revision.' });
+
+  let reconcile = null;
+  if (spec) {
+    const maintenance = spec.reviewed.lifecycle.delivery === 'verified'
+      && spec.reviewed.lifecycle.persistenceModel === 'living';
+    if (spec.reviewed.lifecycle.approval !== 'approved') blockers.push({ code: 'SPC002', message: 'Only an approved spec can become verified.' });
+    if (!['in_progress', 'implemented'].includes(spec.reviewed.lifecycle.delivery) && !maintenance) {
+      blockers.push({ code: 'SPC002', message: `Expected delivery=in_progress, implemented, or verified with persistenceModel=living; found ${spec.reviewed.lifecycle.delivery}/${spec.reviewed.lifecycle.persistenceModel || 'unset'}.` });
+    }
+    const tasks = spec.observed.taskCompletion;
+    if (!tasks.total || tasks.checked !== tasks.total) blockers.push({ code: 'SPC003', message: `All tasks must be checked (${tasks.checked}/${tasks.total}).` });
+    if (spec.observed.implementationEvidence.length === 0) blockers.push({ code: 'SPC004', message: 'At least one qualified source implementation annotation is required.' });
+    if (spec.observed.testEvidence.length === 0) blockers.push({ code: 'SPC004', message: 'At least one qualified test annotation is required.' });
+    const covered = new Set([...spec.observed.implementationEvidence, ...spec.observed.testEvidence].map(item => item.requirementId));
+    const missing = spec.intent.requirements
+      .map(identity => identity.slice(identity.lastIndexOf('#') + 1))
+      .filter(id => !covered.has(id));
+    if (missing.length) blockers.push({ code: 'SPC004', message: `Qualified implementation or test evidence is missing for: ${missing.join(', ')}.` });
+    if (spec.reviewed.scope.canonicalDocs.length === 0) blockers.push({ code: 'SPC005', message: 'Completion requires at least one reviewed affected canonical document.' });
+    for (const path of spec.reviewed.scope.canonicalDocs) {
+      if (!existsSync(resolve(projectDir, path))) blockers.push({ code: 'SPC005', message: `Affected canonical document is missing: ${path}.` });
+    }
+    const since = flags.since || spec.reviewed.reconciliation.lastReviewedRevision;
+    if (!since) blockers.push({ code: 'SPC006', message: 'Completion requires --since <review-baseline> for the first reconciliation.' });
+    else {
+      reconcile = buildReconciliationPlan(projectDir, config, since);
+      if (reconcile.status === 'UNSUPPORTED' || reconcile.status === 'BLOCKED') blockers.push({ code: 'SPC006', message: 'Reconciliation coverage is unsupported or blocked.' });
+      const unresolved = reconcile.classifications.filter(item => item.disposition === 'unsupported_or_ambiguous');
+      if (unresolved.length) blockers.push({ code: 'SPC006', message: `Unresolved changed files: ${unresolved.map(item => item.path).join(', ')}.` });
+      if (maintenance) {
+        const reviewable = reconcile.classifications.filter(item =>
+          item.specs.includes(spec.specId)
+          && ['source', 'test', 'canonical_doc', 'decision'].includes(item.kind));
+        if (revision === spec.reviewed.reconciliation.lastReviewedRevision || reviewable.length === 0) {
+          blockers.push({ code: 'SPC006', message: 'Living-spec maintenance requires a new linked source, test, canonical-document, or decision change since the last reviewed revision.' });
+        }
+      }
+    }
+  }
+  const guard = options.guardResult || runGuardInternal(projectDir, config);
+  if ((guard.errors || 0) > 0) blockers.push({ code: 'SPC007', message: `Guard has ${guard.errors} error(s).` });
+  return {
+    status: blockers.length ? 'BLOCKED' : 'READY',
+    specId: flags.id || null,
+    revision,
+    transition: completionTransition(spec),
+    blockers,
+    reconciliation: reconcile,
+    evidence: spec ? [...new Set([
+      ...spec.observed.implementationEvidence.map(item => item.file),
+      ...spec.observed.testEvidence.map(item => item.file),
+      ...spec.reviewed.scope.canonicalDocs,
+    ])].sort() : [],
+    context: CONTEXT_PATH,
+    archiveReadiness: archiveReadiness(spec, true),
+    guard: { status: guard.status, errors: guard.errors, warnings: guard.warnings },
+  };
+}
+
+export function completeSpec(projectDir, config, flags, options = {}) {
+  const plan = planSpecCompletion(projectDir, config, flags, options);
+  if (plan.status !== 'READY') return { command: 'complete', ...plan, applied: false };
+  if (!flags.write) return { command: 'complete', ...plan, applied: false };
+  const reason = String(flags.reason || '').replace(/\s+/g, ' ').trim();
+  if (!reason || reason.length > 500) throw new Error('Completion --write requires --reason with 1-500 characters.');
+  const projection = projectSpecRegistry(projectDir, config);
+  const spec = projection.registry.specs.find(entry => entry.specId === flags.id);
+  const specPath = resolve(projectDir, spec.path);
+  const successor = flags.successor
+    ? projection.registry.specs.find(entry => entry.specId === flags.successor) : null;
+  if (flags.successor && (!successor || successor.reviewed.lifecycle.context !== 'current'
+    || successor.reviewed.lifecycle.approval !== 'approved')) {
+    throw new Error('Completion successor must be an approved current spec ID.');
+  }
+  const deviations = [...new Set(flags.deviations || [])]
+    .map(item => String(item).replace(/\s+/g, ' ').trim())
+    .filter(Boolean);
+  if (deviations.length > 20 || deviations.some(item => item.length > 500)) {
+    throw new Error('Completion accepts at most 20 deviations of 1-500 characters.');
+  }
+  const outcome = {
+    revision: plan.revision,
+    reason,
+    evidence: plan.evidence,
+    deviations,
+    successor: flags.successor || null,
+  };
+  const specContent = appendImplementationOutcome(readFileSync(specPath, 'utf8'), outcome);
+  spec.reviewed.lifecycle.delivery = 'verified';
+  spec.reviewed.reconciliation.lastReviewedRevision = plan.revision;
+  spec.reviewed.reconciliation.outcomes = [...spec.reviewed.reconciliation.outcomes, outcome].slice(-20);
+  const artifact = spec.observed.artifacts.find(item => item.path === spec.path);
+  if (artifact) artifact.digest = digest(specContent);
+  projection.registry.schemaVersion = 2;
+  const registryContent = `${JSON.stringify(projection.registry, null, 2)}\n`;
+  const contextContent = serializeLifecycleContext(projectDir, projection.registry, plan.revision);
+  commitFileTransaction([
+    { path: specPath, content: specContent },
+    { path: resolve(projectDir, SPEC_REGISTRY_PATH), content: registryContent },
+    { path: resolve(projectDir, CONTEXT_PATH), content: contextContent },
+  ], {
+    validate: () => {
+      const next = projectSpecRegistry(projectDir, config);
+      if (next.issues.length || !next.current) throw new Error('completed registry does not match the resulting repository');
+      const context = JSON.parse(readFileSync(resolve(projectDir, CONTEXT_PATH), 'utf8'));
+      if (context.generatedFrom !== plan.revision) throw new Error('active context revision mismatch');
+    },
+  });
+  return { command: 'complete', ...plan, status: 'VERIFIED', applied: true, outcome };
+}
 
 function printIssues(issues) {
   for (const issue of issues) console.log(`  ${issue.code} ${issue.path}: ${issue.message}`);
 }
 
 function printResult(result) {
+  if (result.command === 'complete') {
+    console.log(`Spec completion: ${result.status}`);
+    console.log(`${result.specId || '<missing>'}: ${result.transition}`);
+    if (result.blockers?.length) printIssues(result.blockers.map(issue => ({ path: result.specId || SPEC_REGISTRY_PATH, ...issue })));
+    return;
+  }
   if (result.command === 'preflight') {
     console.log(`Spec preflight: ${result.status}`);
     console.log(`Current specs: ${result.briefing.length}`);
@@ -34,7 +221,7 @@ function printResult(result) {
 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 (action && !['preflight', 'complete'].includes(action)) 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') {
@@ -46,6 +233,14 @@ export function runSpecs(projectDir, config, flags = {}) {
       return result;
     }
 
+    if (action === 'complete') {
+      const result = completeSpec(projectDir, config, flags);
+      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(' ')}`);