docguard-cli 0.37.0 → 0.38.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:
 
@@ -296,6 +296,8 @@ DocGuard ships **22 commands** (the "Daily 5" + 17 situational tools, including
 | `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. |
+| `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. |
 | `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/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,182 @@
-/** 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.' };
+}
+
+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) {
+    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)) blockers.push({ code: 'SPC002', message: `Expected delivery=in_progress or implemented, found ${spec.reviewed.lifecycle.delivery}.` });
+    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(', ')}.` });
+    }
+  }
+  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: spec?.reviewed.lifecycle.delivery === 'in_progress' ? 'in_progress→implemented→verified' : 'implemented→verified',
+    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 +202,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 +214,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(' ')}`);

package/cli/commands/sync.mjs

@@ -12,6 +12,7 @@ import { assertDefaultDocWrites } from '../shared-doc-roles.mjs';
  *
  * Default is a DRY RUN (preview); `--write` applies. `--since <ref>` adds the
  * git diff as context. Only edits docguard:generated docs unless `--force`.
+ * @implements docguard.document-lifecycle#FR-010
  */
 
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
@@ -22,6 +23,7 @@ import { buildMemoryPlan } from '../scanners/memory-plan.mjs';
 import { getSection, replaceSection } from '../writers/sections.mjs';
 import { hasGeneratedMarker } from '../writers/api-reference.mjs';
 import { runSyncTests } from './sync-tests.mjs';
+import { sectionTouchedByChanges } from '../shared-sync-scope.mjs';
 
 function gitChangedFiles(projectDir, since) {
   const run = (args) => {
@@ -44,39 +46,6 @@ function gitChangedFiles(projectDir, since) {
  * The predicates are matched against project-relative POSIX paths (the form
  * `git diff --name-only` returns).
  */
-const SECTION_FILE_MATCHERS = {
-  'tech-stack':        (p) => /package\.json$|pyproject\.toml$|Cargo\.toml$|go\.mod$|pom\.xml$|Gemfile$/.test(p),
-  'frontend-modules':  (p) => /(^|\/)(src\/)?(stores|hooks|contexts|features)\//.test(p),
-  'endpoints-table':   (p) => /(^|\/)(routes|controllers|handlers|app\/api)\//.test(p)
-                              || /\.(yaml|yml|json)$/i.test(p) && /openapi|swagger/i.test(p),
-  'entities-table':    (p) => /(^|\/)(models|schemas|entities)\//.test(p)
-                              || /\.prisma$/.test(p),
-  'relationships':     (p) => /(^|\/)(models|schemas|entities)\//.test(p)
-                              || /\.prisma$/.test(p),
-  'screens-table':     (p) => /(^|\/)(screens|pages|app)\//.test(p)
-                              || /\.(tsx|jsx)$/.test(p),
-  'flows':             (p) => /(^|\/)(screens|pages|app|routes)\//.test(p),
-  'integrations-table':(p) => /package\.json$|pyproject\.toml$|requirements.*\.txt$|Cargo\.toml$/.test(p),
-  'features-table':    (p) => /(^|\/)(features|domains)\//.test(p),
-  'features':          (p) => /(^|\/)(features|domains)\//.test(p),
-  'env-vars-table':    (p) => /\.env(\..+)?$|(^|\/)config\//.test(p)
-                              || /\.(ts|tsx|js|jsx|mjs|py|go|rs|java|kt|rb)$/.test(p), // any code may use env
-  'setup':             (p) => /\.env(\..+)?$|(^|\/)config\//.test(p),
-};
-
-/**
- * Decide whether a given code-truth section should be re-synced based on the
- * set of changed files. Returns true when:
- *   - changedFiles is null/empty (no scope info → sync everything), OR
- *   - any changed file matches the section's known source patterns, OR
- *   - the section has no matcher registered (unknown → conservative: sync)
- */
-function sectionTouchedByChanges(sectionId, changedFiles) {
-  if (!changedFiles || changedFiles.length === 0) return true;
-  const matcher = SECTION_FILE_MATCHERS[sectionId];
-  if (!matcher) return true; // unknown section → don't accidentally skip it
-  return changedFiles.some(matcher);
-}
 
 export function runSync(projectDir, config, flags) {
   if (flags.write) assertDefaultDocWrites(config);
@@ -144,18 +113,20 @@ export function runSync(projectDir, config, flags) {
     if (apply && docChanged) writeFileSync(full, content, 'utf-8');
   }
 
+  const result = {
+    project: config.projectName,
+    since: flags.since || null,
+    changedFiles: changed,
+    applied: apply,
+    updates,
+    reviews,
+    skipped,
+    timestamp: new Date().toISOString(),
+  };
+  if (flags.silent) return result;
   if (isJson) {
-    console.log(JSON.stringify({
-      project: config.projectName,
-      since: flags.since || null,
-      changedFiles: changed,
-      applied: apply,
-      updates,
-      reviews,
-      skipped,
-      timestamp: new Date().toISOString(),
-    }, null, 2));
-    return;
+    console.log(JSON.stringify(result, null, 2));
+    return result;
   }
 
   console.log(`${c.bold}🔄 DocGuard Sync — ${config.projectName}${c.reset}`);
@@ -184,4 +155,5 @@ export function runSync(projectDir, config, flags) {
     for (const s of skipped) console.log(`     ${c.dim}- ${s.doc}: ${s.reason}${c.reset}`);
     console.log('');
   }
+  return result;
 }

package/cli/docguard.mjs

@@ -13,6 +13,8 @@ import { assertDefaultDocWrites } from './shared-doc-roles.mjs';
  *   npx docguard-cli --help    — Show help
  * 
  * @see https://github.com/raccioly/docguard
+ * @implements docguard.document-lifecycle#FR-012
+ * @implements docguard.document-lifecycle#FR-020
  */
 
 import { readFileSync, existsSync } from 'node:fs';
@@ -53,6 +55,7 @@ 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 { runReconcile } from './commands/reconcile.mjs';
 import { ensureSkills } from './ensure-skills.mjs';
 
 // ── Shared constants (imported to break circular dependencies) ──────────
@@ -101,6 +104,7 @@ ${c.bold}Tools (situational, but day-to-day useful)${c.reset}
   ${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}reconcile${c.reset}  Classify code/spec changes since a Git ref before changing intent
   ${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
@@ -331,15 +335,32 @@ const COMMAND_HELP = {
   },
   specs: {
     summary: 'Maintain the deterministic spec lifecycle and evidence registry.',
-    usage: 'docguard specs [--check|--write] | docguard specs preflight [--path <spec>] [--format json]',
+    usage: 'docguard specs [--check|--write] | docguard specs preflight [--path <spec>] | docguard specs complete --id <spec-id> [--since <ref>] [--write --reason <text>]',
     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'],
+      ['complete', 'Plan or apply the implemented→verified evidence transaction'],
+      ['--id <spec-id>', 'Immutable spec identity to complete'],
+      ['--since <ref>', 'First reconciliation baseline when none is recorded'],
+      ['--reason <text>', 'Reviewed implementation outcome required for completion writes'],
+      ['--deviation <text>', 'Accepted deviation to record; repeatable'],
+      ['--successor <id>', 'Approved current successor spec to record'],
       ['--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'],
+    examples: ['docguard specs --check', 'docguard specs --write', 'docguard specs preflight --path specs/007-feature/spec.md', 'docguard specs complete --id acme.feature --since main --write --reason "Reviewed implementation"'],
+  },
+  reconcile: {
+    summary: 'Classify changed implementation facts, approved intent, decisions, and unsupported evidence.',
+    usage: 'docguard reconcile --since <ref> [--check|--write] [--format json]',
+    flags: [
+      ['--since <ref>', 'Required Git baseline for the review graph'],
+      ['--check', 'Exit 2 while reviewed reconciliation remains'],
+      ['--write', 'Apply only deterministic generated-section refreshes'],
+      ['--format json', 'Machine-readable nodes, edges, classifications, and write plan'],
+    ],
+    examples: ['docguard reconcile --since main --format json', 'docguard reconcile --since HEAD~1 --write'],
   },
 };
 
@@ -589,6 +610,16 @@ async function main() {
     } else if (args[i] === '--retention-ref' && args[i + 1]) {
       flags.retentionRef = args[i + 1];
       i++;
+    } else if (args[i] === '--id' && args[i + 1]) {
+      flags.id = args[i + 1];
+      i++;
+    } else if (args[i] === '--deviation' && args[i + 1]) {
+      flags.deviations = flags.deviations || [];
+      flags.deviations.push(args[i + 1]);
+      i++;
+    } else if (args[i] === '--successor' && args[i + 1]) {
+      flags.successor = args[i + 1];
+      i++;
     } else if (args[i] === '--code') {
       flags.code = args[i + 1] && !args[i + 1].startsWith('--') ? args[++i] : '';
     } else if (args[i] === '--all') {
@@ -662,10 +693,11 @@ async function main() {
   // same way runGuardInternal sees everything else.
   if (flags.noBaseline) config.baseline = false;
 
-  // Commands that only READ and REPORT — they must never mutate the working
-  // tree. Scaffolding (ensureSkills → .agent/.specify, spawning `specify`)
-  // belongs to setup/init/generate and the `init --with` family, where the
-  // user is establishing or expanding their setup, not auditing it.
+  // Commands whose normal mode only reads/reports, plus explicit writers whose
+  // mutations must stay scoped to their named output. They must never add
+  // unrelated setup files. Scaffolding (ensureSkills → .agent/.specify,
+  // spawning `specify`) belongs to setup/init/generate and `init --with`, where
+  // the user is establishing or expanding setup rather than inspecting it.
   //
   // v0.26 (field report Bug #3): a bare `docguard guard` used to run
   // ensureSkills → auto-init Spec Kit → spawn `specify` and write ~9 files into
@@ -675,7 +707,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', 'retire', 'archive', 'specs',
+    'diagnose', 'fix', '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',
@@ -703,6 +735,7 @@ async function main() {
     command !== 'setup' &&
     command !== 'init' &&
     !READ_ONLY_COMMANDS.has(command) &&
+    !(command === 'hooks' && flags.list) &&
     // Agent-family staleness checks must not bootstrap skills or Spec Kit.
     !(command === 'agents' && flags.check) &&
     !headless
@@ -798,8 +831,9 @@ async function main() {
       runAgent(projectDir, config, flags);
       break;
     case 'hooks':
-      if (flags.claude) {
-        // Agent nudge hook (.claude/settings.json) — direct path, no wizard.
+      if (flags.claude || flags.list) {
+        // Agent nudge and read-only inventory paths bypass the setup wizard.
+        // Listing hooks must not refresh unrelated skills in the repository.
         runHooks(projectDir, config, flags);
         break;
       }
@@ -887,6 +921,9 @@ async function main() {
     case 'specs':
       runSpecs(projectDir, config, flags);
       break;
+    case 'reconcile':
+      runReconcile(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