docguard-cli 0.37.1 → 0.38.0

package/cli/scanners/lifecycle-context.mjs

@@ -0,0 +1,50 @@
+/**
+ * Deterministic active-intent projection for AI tools and lifecycle hooks.
+ * @implements docguard.document-lifecycle#FR-014
+ * @implements docguard.document-lifecycle#FR-017
+ */
+
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs';
+import { relative, resolve, sep } from 'node:path';
+
+const digest = content => `sha256:${createHash('sha256').update(content).digest('hex')}`;
+const posix = path => path.split(sep).join('/');
+
+function safeDigest(projectDir, path) {
+  if (!path || path.split(/[\\/]/).includes('.local')) return null;
+  try {
+    const root = realpathSync(projectDir);
+    const absolute = resolve(projectDir, path);
+    const real = realpathSync(absolute);
+    if (!existsSync(absolute) || !lstatSync(absolute).isFile() || lstatSync(absolute).isSymbolicLink()
+      || (real !== root && !real.startsWith(`${root}${sep}`))) return null;
+    return digest(readFileSync(absolute));
+  } catch { return null; }
+}
+
+export function buildLifecycleContext(projectDir, registry, revision) {
+  const specs = registry.specs
+    .filter(spec => spec.reviewed.lifecycle.context === 'current'
+      && spec.reviewed.lifecycle.approval === 'approved')
+    .map(spec => ({
+      specId: spec.specId,
+      path: posix(relative(projectDir, resolve(projectDir, spec.path))),
+      digest: spec.observed.artifacts.find(artifact => artifact.path === spec.path)?.digest || safeDigest(projectDir, spec.path),
+      delivery: spec.reviewed.lifecycle.delivery,
+      requirements: [...spec.intent.requirements].sort(),
+      canonicalDocs: spec.reviewed.scope.canonicalDocs.map(path => ({ path, digest: safeDigest(projectDir, path) })),
+    }))
+    .sort((a, b) => a.specId.localeCompare(b.specId));
+  return {
+    schemaVersion: 1,
+    generatedFrom: revision,
+    assurance: 'pointers-and-content-hashes-only',
+    factualAccuracy: null,
+    specs,
+  };
+}
+
+export function serializeLifecycleContext(projectDir, registry, revision) {
+  return `${JSON.stringify(buildLifecycleContext(projectDir, registry, revision), null, 2)}\n`;
+}

package/cli/scanners/reconciliation.mjs

@@ -0,0 +1,141 @@
+/**
+ * Build a deterministic review graph for code/spec changes since a Git ref.
+ * @implements docguard.document-lifecycle#FR-010
+ * @implements docguard.document-lifecycle#FR-011
+ * @implements docguard.document-lifecycle#FR-012
+ */
+
+import { execFileSync } from 'node:child_process';
+import { extname } from 'node:path';
+import { getDiffText, getHeadInfo } from '../shared-git.mjs';
+import { parseUnifiedDiff } from '../shared-diff.mjs';
+import { mechanicalSectionsForChanges } from '../shared-sync-scope.mjs';
+import { projectSpecRegistry } from './spec-registry.mjs';
+
+const CODE = new Set(['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.py', '.go', '.rs', '.java', '.kt', '.rb', '.php', '.sh', '.cs', '.swift']);
+const TEST = /(?:^|\/)(?:__tests__|tests?|specs?)\/|\.(?:test|spec)\./;
+const DECISION = /(?:^|\/)(?:adr|adrs|decisions?|rfcs?)(?:\/|$)/i;
+
+function resolveRevision(projectDir, ref) {
+  try {
+    return execFileSync('git', ['rev-parse', '--verify', `${ref}^{commit}`], {
+      cwd: projectDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim() || null;
+  } catch { return null; }
+}
+
+function fileKind(path, registry) {
+  if (registry.specs.some(spec => spec.observed.artifacts.some(artifact => artifact.path === path))) return 'spec_artifact';
+  if (path.startsWith('docs-canonical/')) return 'canonical_doc';
+  if (DECISION.test(path) && /\.md$/i.test(path)) return 'decision';
+  if (TEST.test(path) && CODE.has(extname(path).toLowerCase())) return 'test';
+  if (CODE.has(extname(path).toLowerCase())) return 'source';
+  return 'other';
+}
+
+function directSpecLinks(path, text, registry) {
+  const links = [];
+  for (const spec of registry.specs) {
+    const evidencePaths = [
+      ...spec.observed.artifacts.map(item => item.path),
+      ...spec.observed.implementationEvidence.map(item => item.file),
+      ...spec.observed.testEvidence.map(item => item.file),
+      ...spec.reviewed.scope.canonicalDocs,
+    ];
+    const explicit = (spec.intent.requirements || []).some(identity => text.includes(identity));
+    if (evidencePaths.includes(path) || explicit) links.push(spec.specId);
+  }
+  return [...new Set(links)].sort();
+}
+
+function disposition(kind, linked, companionKinds, currentSpecs) {
+  if (kind === 'decision') return { evidenceClass: 'decision', disposition: 'superseded_decision_review', confidence: 'medium' };
+  if (kind === 'spec_artifact' || kind === 'canonical_doc') {
+    return { evidenceClass: 'approved_intent', disposition: 'intent_change_review', confidence: 'high' };
+  }
+  if (kind === 'source' || kind === 'test') {
+    if (linked.length === 0) return { evidenceClass: 'unsupported', disposition: 'unsupported_or_ambiguous', confidence: 'low' };
+    const governingChanged = companionKinds.has('spec_artifact') || companionKinds.has('canonical_doc') || companionKinds.has('decision');
+    if (governingChanged) return { evidenceClass: 'approved_intent', disposition: 'intentional_behavior_change_review', confidence: 'medium' };
+    const governs = linked.some(id => currentSpecs.has(id));
+    if (governs) return { evidenceClass: 'approved_intent', disposition: 'possible_implementation_regression', confidence: 'medium' };
+    return { evidenceClass: 'decision', disposition: 'superseded_decision_review', confidence: 'medium' };
+  }
+  return { evidenceClass: 'unrelated', disposition: 'unrelated_change', confidence: 'high' };
+}
+
+export function buildReconciliationPlan(projectDir, config = {}, since) {
+  if (!since) throw new Error('Reconcile requires --since <git-ref>.');
+  const baseRevision = resolveRevision(projectDir, since);
+  const head = getHeadInfo(projectDir);
+  if (!baseRevision || !head?.commit) {
+    return {
+      schemaVersion: 1,
+      status: 'UNSUPPORTED',
+      since,
+      baseRevision,
+      revision: head?.commit || null,
+      coverage: { status: 'unsupported', reason: 'Git ref or HEAD could not be resolved.' },
+      nodes: [], edges: [], classifications: [], writes: [], issues: [],
+    };
+  }
+  const projection = projectSpecRegistry(projectDir, config);
+  const diff = parseUnifiedDiff(getDiffText(projectDir, since))
+    .filter(file => ![file.oldPath, file.newPath].some(path => path?.split('/').includes('.local')));
+  const changed = diff.map(file => file.newPath || file.oldPath).filter(Boolean);
+  const textByPath = new Map(diff.map(file => [
+    file.newPath || file.oldPath,
+    file.hunks.flatMap(hunk => hunk.lines.filter(line => line.op !== ' ').map(line => line.text)).join('\n'),
+  ]));
+  const preliminary = changed.map(path => ({
+    path,
+    kind: fileKind(path, projection.registry),
+    specs: directSpecLinks(path, textByPath.get(path) || '', projection.registry),
+  }));
+  const currentSpecs = new Set(projection.registry.specs
+    .filter(spec => spec.reviewed.lifecycle.context === 'current' && spec.reviewed.lifecycle.approval === 'approved')
+    .map(spec => spec.specId));
+  const classifications = preliminary.map(item => {
+    const companionKinds = new Set(preliminary
+      .filter(other => other.specs.some(id => item.specs.includes(id)))
+      .map(other => other.kind));
+    return { ...item, ...disposition(item.kind, item.specs, companionKinds, currentSpecs) };
+  });
+  const mechanicalSections = mechanicalSectionsForChanges(changed.filter(path => CODE.has(extname(path).toLowerCase()) || /(?:package\.json|pyproject\.toml|Cargo\.toml|go\.mod|pom\.xml|Gemfile)$/.test(path)));
+  if (mechanicalSections.length > 0) {
+    classifications.push({
+      path: null,
+      kind: 'generated_section_projection',
+      specs: [],
+      evidenceClass: 'mechanical_fact',
+      disposition: 'mechanical_fact_refresh',
+      confidence: 'high',
+      sections: mechanicalSections,
+    });
+  }
+  const nodes = [
+    ...projection.registry.specs.map(spec => ({ id: `spec:${spec.specId}`, type: 'spec', path: spec.path, lifecycle: spec.reviewed.lifecycle })),
+    ...preliminary.map(item => ({ id: `change:${item.path}`, type: 'change', path: item.path, kind: item.kind })),
+  ];
+  const edges = preliminary.flatMap(item => item.specs.map(specId => ({
+    from: `change:${item.path}`,
+    to: `spec:${specId}`,
+    kind: 'direct_evidence',
+    confidence: 'high',
+  })));
+  const review = classifications.some(item => !['mechanical_fact_refresh', 'unrelated_change'].includes(item.disposition));
+  return {
+    schemaVersion: 1,
+    status: projection.issues.length ? 'BLOCKED' : review ? 'REVIEW' : 'READY',
+    since,
+    baseRevision,
+    revision: head.commit,
+    dirty: head.dirty,
+    coverage: { status: 'complete', reason: null },
+    nodes,
+    edges,
+    classifications,
+    writes: mechanicalSections.length ? [{ command: `docguard sync --since ${since} --write`, scope: 'mechanical_fact' }] : [],
+    issues: projection.issues,
+  };
+}

package/cli/scanners/requirement-evidence.mjs

@@ -1,4 +1,8 @@
-/** Pure requirement-reference evidence shared by validators and registry projections. */
+/**
+ * Pure requirement-reference evidence shared by validators and registry projections.
+ * @implements docguard.document-lifecycle#FR-013
+ * @implements docguard.document-lifecycle#FR-016
+ */
 
 import { existsSync, readFileSync } from 'node:fs';
 import { extname, resolve } from 'node:path';
@@ -96,31 +100,60 @@ function testDeclarations(content, filename) {
   return declarations;
 }
 
-export function scanTestFilesForReferences(projectDir, projectFiles, patterns) {
-  const testRefs = new Map();
-  for (const relPath of projectFiles.filter(isTestSource)) {
+function implementationDeclarations(content, filename) {
+  const declarations = [];
+  const ext = extname(filename);
+  const hashComments = /\.(?:py|rb|php|sh)$/.test(ext);
+  const tokens = /\/\*[\s\S]*?(?:\*\/|$)|\/\/[^\n]*|\#[^\n]*/g;
+  for (const token of content.matchAll(tokens)) {
+    if (token[0].startsWith('#') && !hashComments) continue;
+    const line = content.slice(0, token.index).split('\n').length;
+    const text = token[0].replace(/^(?:\/\/|\/\*|#)/, '');
+    if (/@(?:req|implements)\s/i.test(text)) declarations.push({ text, line });
+  }
+  return declarations;
+}
+
+function collectReferences(projectDir, projectFiles, patterns, select, declarationsForFile) {
+  const refs = new Map();
+  for (const relPath of projectFiles.filter(select)) {
     const fullPath = resolve(projectDir, relPath);
     if (!existsSync(fullPath)) continue;
     let content;
     try { content = readFileSync(fullPath, 'utf8'); } catch { continue; }
     const hasMatch = patterns.some(pattern => { pattern.lastIndex = 0; return pattern.test(content); });
     if (!hasMatch) continue;
-    for (const declaration of testDeclarations(content, relPath)) {
+    for (const declaration of declarationsForFile(content, relPath)) {
       for (const pattern of patterns) {
         pattern.lastIndex = 0;
         let match;
         while ((match = pattern.exec(declaration.text)) !== null) {
           if (!match[0]) { pattern.lastIndex++; continue; }
           const reqId = match[0];
-          if (!testRefs.has(reqId)) testRefs.set(reqId, []);
+          if (!refs.has(reqId)) refs.set(reqId, []);
           const line = declaration.line + (declaration.text.slice(0, match.index).match(/\n/g) || []).length;
           const prefix = declaration.text.slice(0, match.index);
           const qualifier = prefix.match(/([^\s`"'<>()[\]{}]+)#$/);
           const scope = qualifier ? qualifier[1].replaceAll('\\', '/').replace(/^\.\//, '') : null;
-          testRefs.get(reqId).push({ file: relPath, line, scope });
+          refs.get(reqId).push({ file: relPath, line, scope });
         }
       }
     }
   }
-  return testRefs;
+  return refs;
+}
+
+export function scanTestFilesForReferences(projectDir, projectFiles, patterns) {
+  return collectReferences(projectDir, projectFiles, patterns, isTestSource, testDeclarations);
+}
+
+/** Source annotations are explicit implementation evidence, never inferred from names. */
+export function scanImplementationFilesForReferences(projectDir, projectFiles, patterns) {
+  return collectReferences(
+    projectDir,
+    projectFiles,
+    patterns,
+    path => !isTestSource(path) && /\.(?:[cm]?[jt]sx?|py|go|rs|java|kt|rb|php|sh|cs|swift)$/.test(path),
+    implementationDeclarations,
+  );
 }

package/cli/scanners/retirement-manifest.mjs

@@ -0,0 +1,52 @@
+/**
+ * Validate recovery evidence before archived requirements can leave the active
+ * working tree or become traceability tombstones.
+ * @implements docguard.document-lifecycle#FR-007
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const MANIFEST_PATH = '.docguard-archive.json';
+
+export function readRetirementManifest(projectDir) {
+  const path = resolve(projectDir, MANIFEST_PATH);
+  if (!existsSync(path)) return { ok: true, paths: new Set(), entries: [], retention: null, error: null };
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    if (parsed?.schemaVersion !== 1 || parsed?.strategy !== 'git-history' || !Array.isArray(parsed.entries)) {
+      throw new Error('unsupported schema');
+    }
+    const globalRecovery = parsed.retention?.recoverability === 'verified'
+      && typeof parsed.retention?.ref === 'string'
+      && /^(?:sha1|sha256)$/.test(parsed.retention?.objectFormat || '');
+    for (const entry of parsed.entries) {
+      const path = entry?.path;
+      const entryRecovery = entry?.recoverability === 'verified'
+        && typeof entry?.retentionRef === 'string'
+        && /^(?:sha1|sha256)$/.test(entry?.objectFormat || '');
+      if (typeof path !== 'string' || !path || path.startsWith('/')
+        || path.replaceAll('\\', '/').split('/').includes('..')
+        || typeof entry?.archivedFrom !== 'string'
+        || !/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/.test(entry.archivedFrom)
+        || typeof entry?.blob !== 'string'
+        || !/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/.test(entry.blob)
+        || typeof entry?.reason !== 'string' || !entry.reason.trim()
+        || (entry?.requirementIds !== undefined && (!Array.isArray(entry.requirementIds)
+          || entry.requirementIds.some(id => typeof id !== 'string' || !id || id.length > 128 || /[\s#\0]/.test(id))))
+        || (entry?.specId !== undefined && (typeof entry.specId !== 'string'
+          || !/^[a-z0-9][a-z0-9._-]{2,127}$/.test(entry.specId)))
+        || (!globalRecovery && !entryRecovery)) {
+        throw new Error(`invalid recovery entry for ${path || '<unknown path>'}`);
+      }
+    }
+    return {
+      ok: true,
+      paths: new Set(parsed.entries.map(entry => entry.path)),
+      entries: parsed.entries,
+      retention: parsed.retention || null,
+      error: null,
+    };
+  } catch (error) {
+    return { ok: false, paths: new Set(), entries: [], retention: null, error: `${MANIFEST_PATH}: ${error.message}` };
+  }
+}

package/cli/scanners/spec-registry.mjs

@@ -4,6 +4,8 @@
  * Specs own requirement prose. The registry owns reviewed lifecycle metadata
  * and regenerates only observable facts, so a refresh cannot silently rewrite
  * intent or declare work complete.
+ * @implements docguard.document-lifecycle#FR-013
+ * @implements docguard.document-lifecycle#FR-016
  */
 
 import { createHash } from 'node:crypto';
@@ -11,13 +13,13 @@ import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { dirname, relative, resolve, sep } from 'node:path';
 import { detectSpecKit } from './speckit.mjs';
-import { readRetirementManifest } from './document-lifecycle.mjs';
+import { readRetirementManifest } from './retirement-manifest.mjs';
 import { collectRequirementIdsFromContent, requirementPatterns } from '../shared-requirements.mjs';
 import { walkFiles } from '../shared-ignore.mjs';
-import { scanTestFilesForReferences } from './requirement-evidence.mjs';
+import { scanImplementationFilesForReferences, scanTestFilesForReferences } from './requirement-evidence.mjs';
 
 export const SPEC_REGISTRY_PATH = '.docguard-specs.json';
-export const SPEC_REGISTRY_SCHEMA_VERSION = 1;
+export const SPEC_REGISTRY_SCHEMA_VERSION = 2;
 export const SPEC_REGISTRY_SCHEMA_URL = 'https://raccioly.github.io/docguard/schemas/docguard-specs.schema.json';
 
 const SPEC_ID_RE = /^[a-z0-9][a-z0-9._-]{2,127}$/;
@@ -77,7 +79,7 @@ function defaultControl() {
         supersededBy: [],
       },
       scope: { canonicalDocs: [] },
-      reconciliation: { lastReviewedRevision: null },
+      reconciliation: { lastReviewedRevision: null, outcomes: [] },
     },
   };
 }
@@ -140,11 +142,26 @@ function validatedControl(entry, issues) {
   const reconciliation = reviewed.reconciliation || {};
   rejectUnknownKeys(relations, new Set(['extends', 'duplicates', 'conflictsWith', 'supersedes', 'supersededBy']), `${entry.specId}.reviewed.relations`, issues);
   rejectUnknownKeys(scope, new Set(['canonicalDocs']), `${entry.specId}.reviewed.scope`, issues);
-  rejectUnknownKeys(reconciliation, new Set(['lastReviewedRevision']), `${entry.specId}.reviewed.reconciliation`, issues);
+  rejectUnknownKeys(reconciliation, new Set(['lastReviewedRevision', 'outcomes']), `${entry.specId}.reviewed.reconciliation`, issues);
   const revision = reconciliation.lastReviewedRevision ?? null;
   if (revision !== null && (typeof revision !== 'string' || !/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/.test(revision))) {
     issues.push({ code: 'SPR003', path: SPEC_REGISTRY_PATH, message: `Invalid reconciliation revision for ${entry.specId}.` });
   }
+  const outcomes = reconciliation.outcomes ?? [];
+  if (!Array.isArray(outcomes) || outcomes.length > 20 || outcomes.some(outcome => {
+    if (!outcome || typeof outcome !== 'object' || Array.isArray(outcome)) return true;
+    const allowed = new Set(['revision', 'reason', 'evidence', 'deviations', 'successor']);
+    return Object.keys(outcome).some(key => !allowed.has(key))
+      || !/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/.test(outcome.revision || '')
+      || typeof outcome.reason !== 'string' || !outcome.reason.trim() || outcome.reason.length > 500
+      || !Array.isArray(outcome.evidence) || outcome.evidence.length > 100
+      || outcome.evidence.some(path => typeof path !== 'string' || !path.trim())
+      || !Array.isArray(outcome.deviations) || outcome.deviations.length > 20
+      || outcome.deviations.some(item => typeof item !== 'string' || !item.trim() || item.length > 500)
+      || (outcome.successor !== null && outcome.successor !== undefined && !SPEC_ID_RE.test(outcome.successor));
+  })) {
+    issues.push({ code: 'SPR003', path: SPEC_REGISTRY_PATH, message: `Invalid or unbounded reconciliation outcomes for ${entry.specId}.` });
+  }
   return {
     reviewed: {
       lifecycle: {
@@ -165,7 +182,16 @@ function validatedControl(entry, issues) {
       scope: {
         canonicalDocs: validateCanonicalPaths(scope.canonicalDocs ?? [], `${entry.specId}.scope.canonicalDocs`, issues),
       },
-      reconciliation: { lastReviewedRevision: revision },
+      reconciliation: {
+        lastReviewedRevision: revision,
+        outcomes: Array.isArray(outcomes) ? outcomes.slice(-20).map(outcome => ({
+          revision: outcome.revision,
+          reason: outcome.reason,
+          evidence: sortedUnique(outcome.evidence || []),
+          deviations: sortedUnique(outcome.deviations || []),
+          successor: outcome.successor ?? null,
+        })) : [],
+      },
     },
   };
 }
@@ -174,9 +200,9 @@ export function readSpecRegistry(projectDir) {
   const loaded = readJson(resolve(projectDir, SPEC_REGISTRY_PATH), SPEC_REGISTRY_PATH);
   if (!loaded.exists || loaded.error) return loaded;
   const value = loaded.value;
-  if (value?.$schema !== SPEC_REGISTRY_SCHEMA_URL || value?.schemaVersion !== SPEC_REGISTRY_SCHEMA_VERSION
+  if (value?.$schema !== SPEC_REGISTRY_SCHEMA_URL || ![1, SPEC_REGISTRY_SCHEMA_VERSION].includes(value?.schemaVersion)
     || !Array.isArray(value?.specs) || !Array.isArray(value?.tombstones)) {
-    return { exists: true, value: null, error: `${SPEC_REGISTRY_PATH} does not use supported schema version 1.` };
+    return { exists: true, value: null, error: `${SPEC_REGISTRY_PATH} does not use a supported schema version.` };
   }
   const topKeys = new Set(['$schema', 'schemaVersion', 'specs', 'tombstones']);
   const unknownTop = Object.keys(value).filter(key => !topKeys.has(key));
@@ -328,6 +354,7 @@ export function projectSpecRegistry(projectDir, config = {}, options = {}) {
   const files = projectFiles(projectDir);
   const patterns = requirementPatterns(config);
   const testReferences = scanTestFilesForReferences(projectDir, files, patterns);
+  const implementationReferences = scanImplementationFilesForReferences(projectDir, files, patterns);
   const ids = new Map();
   const specs = [];
 
@@ -377,7 +404,7 @@ export function projectSpecRegistry(projectDir, config = {}, options = {}) {
       observed: {
         artifacts,
         taskCompletion: taskCompletion(feature.tasksPath),
-        implementationEvidence: [],
+        implementationEvidence: evidenceForSpec(specId, path, requirements, implementationReferences),
         testEvidence: evidenceForSpec(specId, path, requirements, testReferences),
       },
     });

package/cli/shared-sync-scope.mjs

@@ -0,0 +1,35 @@
+/**
+ * Shared changed-file to generated-section applicability rules.
+ * @implements docguard.document-lifecycle#FR-010
+ */
+
+export 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),
+  'setup':             (p) => /\.env(\..+)?$|(^|\/)config\//.test(p),
+};
+
+export function sectionTouchedByChanges(sectionId, changedFiles) {
+  if (!changedFiles || changedFiles.length === 0) return true;
+  const matcher = SECTION_FILE_MATCHERS[sectionId];
+  if (!matcher) return true;
+  return changedFiles.some(matcher);
+}
+
+export function mechanicalSectionsForChanges(changedFiles) {
+  if (!Array.isArray(changedFiles) || changedFiles.length === 0) return [];
+  return Object.keys(SECTION_FILE_MATCHERS)
+    .filter(section => sectionTouchedByChanges(section, changedFiles))
+    .sort();
+}

package/cli/validators/traceability.mjs

@@ -11,6 +11,7 @@
  *
  * Inspired by ISO/IEC/IEEE 29119, IEEE 1016, and V-Model methodology.
  * V-Model concepts informed by spec-kit-v-model (github.com/leocamello/spec-kit-v-model).
+ * @implements docguard.document-lifecycle#FR-013
  */
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
@@ -30,7 +31,7 @@ import {
   collectRequirementIdsFromContent,
   requirementPatterns,
 } from '../shared-requirements.mjs';
-import { readRetirementManifest } from '../scanners/document-lifecycle.mjs';
+import { readRetirementManifest } from '../scanners/retirement-manifest.mjs';
 import { parseSpecId } from '../scanners/spec-registry.mjs';
 
 /**

package/cli/writers/file-transaction.mjs

@@ -0,0 +1,85 @@
+/**
+ * Small, dependency-free multi-file transaction for lifecycle state.
+ *
+ * Every replacement is staged beside its destination before the first visible
+ * mutation. Originals are retained in memory and restored if any replacement,
+ * deletion, or post-commit validation fails. When the operation returns or
+ * throws, callers see the all-old or all-new set. This is in-process rollback,
+ * not a durable transaction journal across power loss or forced termination.
+ * @implements docguard.document-lifecycle#FR-013
+ */
+
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { dirname } from 'node:path';
+
+function cleanup(paths) {
+  for (const path of paths) {
+    try { rmSync(path, { force: true }); } catch { /* best-effort cleanup */ }
+  }
+}
+
+/**
+ * Commit a bounded set of file replacements/deletions.
+ *
+ * `content: null` deletes a file. `validate` runs after all visible mutations;
+ * throwing from it rolls the complete set back. The optional `afterMutation`
+ * test seam is intentionally undocumented outside the module tests.
+ */
+export function commitFileTransaction(entries, { validate = null, afterMutation = null } = {}) {
+  if (!Array.isArray(entries) || entries.length === 0) throw new Error('File transaction requires at least one entry.');
+  const targets = new Set();
+  const tx = randomUUID();
+  const prepared = [];
+  try {
+    for (const [index, entry] of entries.entries()) {
+      if (!entry?.path || typeof entry.path !== 'string') throw new Error('Every file transaction entry needs a path.');
+      if (targets.has(entry.path)) throw new Error(`File transaction repeats target: ${entry.path}`);
+      targets.add(entry.path);
+      const existed = existsSync(entry.path);
+      const original = existed ? readFileSync(entry.path) : null;
+      const staged = entry.content === null ? null : `${entry.path}.docguard-${tx}-${index}.tmp`;
+      prepared.push({ ...entry, existed, original, staged });
+      if (staged) {
+        mkdirSync(dirname(entry.path), { recursive: true });
+        writeFileSync(staged, entry.content, 'utf8');
+      }
+    }
+  } catch (error) {
+    cleanup(prepared.map(entry => entry.staged).filter(Boolean));
+    throw new Error(`File transaction preparation failed: ${error.message}`);
+  }
+
+  const applied = [];
+  try {
+    for (const entry of prepared) {
+      if (entry.content === null) {
+        if (entry.existed) rmSync(entry.path);
+      } else {
+        // copyFileSync overwrites on every supported Node platform. renameSync
+        // cannot replace an existing destination consistently on Windows.
+        copyFileSync(entry.staged, entry.path);
+      }
+      applied.push(entry);
+      if (afterMutation) afterMutation(entry, applied.length);
+    }
+    if (validate) validate();
+  } catch (error) {
+    for (const entry of [...applied].reverse()) {
+      try {
+        if (entry.existed) writeFileSync(entry.path, entry.original);
+        else rmSync(entry.path, { force: true });
+      } catch { /* report the initiating error; callers validate on next run */ }
+    }
+    cleanup(prepared.map(entry => entry.staged).filter(Boolean));
+    throw new Error(`File transaction rolled back: ${error.message}`);
+  }
+  cleanup(prepared.map(entry => entry.staged).filter(Boolean));
+}

package/cli/writers/spec-outcomes.mjs

@@ -0,0 +1,27 @@
+/**
+ * Append a bounded, machine-owned outcome index without rewriting spec intent.
+ * @implements docguard.document-lifecycle#FR-016
+ */
+
+const START = '<!-- docguard:implementation-outcomes:start -->';
+const END = '<!-- docguard:implementation-outcomes:end -->';
+
+function clean(value, max = 500) {
+  return String(value || '').replace(/\s+/g, ' ').replace(/[<>`]/g, '').trim().slice(0, max);
+}
+
+export function appendImplementationOutcome(content, outcome) {
+  const reason = clean(outcome.reason);
+  if (!reason) throw new Error('Implementation outcome requires a non-empty reviewed reason.');
+  const evidence = [...new Set(outcome.evidence || [])].sort().map(path => `\`${path}\``).join(', ') || 'none';
+  const deviations = [...new Set(outcome.deviations || [])].sort().map(item => clean(item)).filter(Boolean).join('; ') || 'none';
+  const successor = outcome.successor ? `\`${outcome.successor}\`` : 'none';
+  const line = `- \`${outcome.revision}\` — ${reason} Evidence: ${evidence}. Accepted deviations: ${deviations}. Successor: ${successor}.`;
+  const block = `${START}\n## Implementation Outcomes\n\n${line}\n${END}`;
+  const pattern = new RegExp(`${START.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[\\s\\S]*?${END.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`);
+  if (!pattern.test(content)) return `${content.trimEnd()}\n\n${block}\n`;
+  const prior = content.match(pattern)?.[0]
+    .split('\n').filter(item => item.startsWith('- `')) || [];
+  const lines = [...prior.filter(item => !item.startsWith(`- \`${outcome.revision}\``)), line].slice(-20);
+  return content.replace(pattern, `${START}\n## Implementation Outcomes\n\n${lines.join('\n')}\n${END}`);
+}

package/extensions/spec-kit-docguard/README.md

@@ -53,6 +53,7 @@ docguard score
 | `speckit.docguard.generate` | — | Reverse-engineer canonical docs from codebase |
 | `speckit.docguard.brief` | — | Load current spec intent before specification |
 | `speckit.docguard.preflight` | — | Gate the generated spec before task generation |
+| `speckit.docguard.complete` | — | Plan reviewed completion and regenerate active context after verification |
 
 ## AI Skills
 
@@ -78,8 +79,11 @@ DocGuard integrates into the spec-kit workflow through hooks:
 hooks:
   before_specify:    # Mandatory — read current spec intent first
     command: speckit.docguard.brief
-  after_implement:   # Mandatory — quality gate after /speckit.implement
-    command: speckit.docguard.guard
+  after_implement:   # Guard is mandatory; completion review is optional
+    - command: speckit.docguard.guard
+    - command: speckit.docguard.complete
+  after_converge:    # Optional completion review after convergence
+    command: speckit.docguard.complete
   before_tasks:      # Mandatory — gate the generated spec
     command: speckit.docguard.preflight
   after_tasks:       # Optional — show score after tasks

package/extensions/spec-kit-docguard/commands/complete.md

@@ -0,0 +1,38 @@
+---
+description: "Review implementation evidence and plan the spec completion transaction"
+allowed-tools: Bash, Read
+---
+
+# DocGuard Spec Completion Review
+
+Run after implementation or convergence. This hook plans the lifecycle gate; it
+does not mark the feature verified without a reviewed rationale.
+
+1. Resolve the current feature `spec.md` and read its `Spec ID` metadata.
+2. Run `docguard guard --format json`. Stop on errors.
+3. Refresh deterministic evidence with `docguard specs --write`, then review and
+   commit that projection with the implementation.
+4. Select the Git baseline that covers the implementation changes. Prefer the
+   registry's prior reconciliation revision; otherwise use the feature branch's
+   merge base with its configured default branch.
+5. Run:
+
+```bash
+docguard specs complete --id <spec-id> --since <ref> --check --format json
+```
+
+6. Review every reconciliation classification. Unsupported or ambiguous changes
+   block completion. A possible implementation regression requires deciding
+   whether to fix code, amend approved intent, or record an accepted deviation.
+7. When the evidence is complete, present the exact reviewed write command to
+   the maintainer. Apply it only when the maintainer supplies the rationale:
+
+```bash
+docguard specs complete --id <spec-id> --since <ref> --write --reason "<reviewed outcome>"
+```
+
+The write records the outcome, advances delivery through `implemented` to
+`verified`, and regenerates `.docguard/current-context.json` as one staged,
+post-validated set. In-process write or validation failures roll the set back;
+the command does not claim a durable journal across power loss or forced
+termination.