docguard-cli 0.37.1 → 0.39.0

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
@@ -297,10 +301,10 @@ const COMMAND_HELP = {
     examples: ['docguard memory', 'docguard memory --diff'],
   },
   feedback: {
-    summary: 'Review detection feedback locally. Select any finding with --code or --all, check duplicates, and prepare a metadata-only issue URL. Nothing is submitted automatically.',
-    usage: 'docguard feedback [--code <CODE> | --all] [--preview] [--format json]',
-    flags: [['--code <CODE>', 'Select a finding regardless of confidence'], ['--all', 'Select every active finding'], ['--preview', 'Skip local feedback-record writes'], ['--format json', 'Machine-readable selected findings and issue/search URLs']],
-    examples: ['docguard feedback', 'docguard feedback --code TRC005 --preview', 'docguard feedback --all --format json'],
+    summary: 'Review detection feedback locally, or validate and reduce a synthetic fixture manifest. Duplicate searches cover open and closed work; nothing is submitted automatically.',
+    usage: 'docguard feedback [--code <CODE> | --all] [--classification <class>] [--fixture-manifest <path> [--reduce] [--contribution <path>]] [--preview] [--format json]',
+    flags: [['--code <CODE>', 'Select a finding regardless of confidence'], ['--all', 'Select every active finding'], ['--classification <class>', 'false_positive, false_negative, unsupported_syntax, ambiguous, or policy_disagreement'], ['--fixture-manifest <path>', 'Validate a reviewed synthetic fixture and opposite control'], ['--reduce', 'Deterministically reduce a reproducing fixture'], ['--contribution <path>', 'Write a test-only contribution when required evidence is present'], ['--preview', 'Skip local writes and return contribution text inline'], ['--format json', 'Machine-readable evidence and issue/search URLs']],
+    examples: ['docguard feedback', 'docguard feedback --code TRC005 --preview', 'docguard feedback --fixture-manifest feedback.json --reduce --preview --format json'],
   },
   verify: {
     summary: 'Extract the semantic claims in your canonical docs — documented numbers, limits, and enums (retention days, rate limits, GSI/role counts, status enums) — as a verification task list the agent checks against the code. This is the highest-value bug class (a doc value that drifted from code) and the one regex/AST cannot judge. DocGuard finds the claims; the LLM confirms them.',
@@ -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,12 +610,33 @@ 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') {
       flags.all = true;
     } else if (args[i] === '--preview') {
       flags.preview = true;
+    } else if (args[i] === '--classification' && args[i + 1]) {
+      flags.classification = args[i + 1].replaceAll('-', '_');
+      i++;
+    } else if (args[i] === '--fixture-manifest' && args[i + 1]) {
+      flags.fixtureManifest = args[i + 1];
+      i++;
+    } else if (args[i] === '--reduce') {
+      flags.reduce = true;
+    } else if (args[i] === '--contribution' && args[i + 1]) {
+      flags.contribution = args[i + 1];
+      i++;
     } else if (args[i] === '--signals') {
       flags.signals = true;
     } else if (args[i] === '--debate') {
@@ -890,6 +932,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

package/cli/feedback-fixture.mjs

@@ -0,0 +1,188 @@
+/**
+ * Strict, privacy-bounded feedback fixtures and deterministic reduction.
+ * @implements docguard.precision-evidence-loop#FR-011
+ * @implements docguard.precision-evidence-loop#FR-013
+ * @implements docguard.precision-evidence-loop#FR-014
+ * @implements docguard.precision-evidence-loop#FR-015
+ * @implements docguard.precision-evidence-loop#FR-016
+ */
+
+import { createHash } from 'node:crypto';
+import { extname, isAbsolute } from 'node:path';
+
+export const FEEDBACK_SCHEMA_URL = 'https://raccioly.github.io/docguard/schemas/docguard-feedback-fixture.schema.json';
+const CLASSIFICATIONS = new Set(['false_positive', 'false_negative', 'unsupported_syntax', 'ambiguous', 'policy_disagreement']);
+const PARSER_TIERS = new Set(['js-ast', 'py-ast', 'regex-fallback', 'fallback-language', 'mixed', 'not-applicable']);
+const PREDICATES = new Set(['finding_present', 'finding_absent', 'validator_unsupported']);
+const ROOT_KEYS = new Set(['$schema', 'schemaVersion', 'classification', 'detector', 'parserTier', 'config', 'expectedIdentity', 'interestingness', 'fixture', 'oppositeControl', 'provenance', 'contribution']);
+
+function object(value, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${label} must be an object.`);
+  return value;
+}
+
+function exactKeys(value, keys, label) {
+  const unknown = Object.keys(value).filter(key => !keys.has(key));
+  if (unknown.length) throw new Error(`${label} has unknown field(s): ${unknown.join(', ')}.`);
+}
+
+function safePath(value, label) {
+  if (typeof value !== 'string' || !value || value.includes('\\') || isAbsolute(value)) throw new Error(`${label} must be a POSIX relative path.`);
+  const parts = value.split('/');
+  if (parts.some(part => !part || part === '.' || part === '..' || ['.git', '.local'].includes(part.toLowerCase()))) {
+    throw new Error(`${label} enters a protected or escaping path.`);
+  }
+  return value;
+}
+
+function validateConfig(value, label = 'config', depth = 0) {
+  if (depth > 6) throw new Error(`${label} is too deeply nested.`);
+  if (value === null || typeof value === 'boolean' || Number.isFinite(value)) return;
+  if (typeof value === 'string') {
+    if (value.length > 10_000 || value.includes('\0') || isAbsolute(value) || /(?:^|[/\\])\.\.(?:[/\\]|$)/.test(value) || value.includes('.local') || value.includes('.git')) {
+      throw new Error(`${label} contains an unsafe value.`);
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    if (value.length > 100) throw new Error(`${label} is too large.`);
+    value.forEach((item, index) => validateConfig(item, `${label}[${index}]`, depth + 1));
+    return;
+  }
+  object(value, label);
+  const keys = Object.keys(value);
+  if (keys.length > 100 || keys.some(key => ['__proto__', 'prototype', 'constructor'].includes(key))) throw new Error(`${label} has unsafe keys.`);
+  for (const key of keys) validateConfig(value[key], `${label}.${key}`, depth + 1);
+}
+
+function parseFiles(value, label) {
+  const holder = object(value, label);
+  exactKeys(holder, new Set(['files']), label);
+  if (!Array.isArray(holder.files) || holder.files.length < 1 || holder.files.length > 16) throw new Error(`${label}.files requires 1-16 files.`);
+  let bytes = 0;
+  const seen = new Set();
+  const files = holder.files.map((entry, index) => {
+    object(entry, `${label}.files[${index}]`);
+    exactKeys(entry, new Set(['path', 'content']), `${label}.files[${index}]`);
+    const path = safePath(entry.path, `${label}.files[${index}].path`);
+    if (seen.has(path)) throw new Error(`${label}.files contains duplicate path ${path}.`);
+    seen.add(path);
+    if (typeof entry.content !== 'string' || entry.content.includes('\0')) throw new Error(`${label}.files[${index}].content must be text.`);
+    bytes += Buffer.byteLength(entry.content);
+    return { path, content: entry.content };
+  });
+  if (bytes > 131_072) throw new Error(`${label} exceeds 128 KiB.`);
+  return { files };
+}
+
+function parseContribution(value) {
+  if (value === undefined) return null;
+  const contribution = object(value, 'contribution');
+  exactKeys(contribution, new Set(['testOnly', 'scopeDocumented', 'benchmarkDelta']), 'contribution');
+  const delta = object(contribution.benchmarkDelta, 'contribution.benchmarkDelta');
+  exactKeys(delta, new Set(['falsePositives', 'falseNegatives', 'unsupportedCases', 'abstainedSupportedCases']), 'contribution.benchmarkDelta');
+  for (const [key, count] of Object.entries(delta)) {
+    if (!Number.isInteger(count) || count < 0) throw new Error(`contribution.benchmarkDelta.${key} must be a non-negative integer.`);
+  }
+  return { testOnly: contribution.testOnly === true, scopeDocumented: contribution.scopeDocumented === true, benchmarkDelta: delta };
+}
+
+export function parseFeedbackFixture(value) {
+  const root = object(value, 'feedback fixture');
+  exactKeys(root, ROOT_KEYS, 'feedback fixture');
+  if (root.$schema !== FEEDBACK_SCHEMA_URL || root.schemaVersion !== 1) throw new Error('Feedback fixture uses an unsupported schema contract.');
+  if (!CLASSIFICATIONS.has(root.classification)) throw new Error('feedback fixture classification is invalid.');
+  if (!PARSER_TIERS.has(root.parserTier)) throw new Error('feedback fixture parserTier is invalid.');
+  const detector = object(root.detector, 'detector');
+  exactKeys(detector, new Set(['code', 'validator']), 'detector');
+  if (!/^[A-Z]{3}\d{3}$/.test(detector.code) || !/^[A-Za-z][A-Za-z0-9]{1,63}$/.test(detector.validator)) throw new Error('detector code or validator is invalid.');
+  const match = String(root.expectedIdentity || '').match(/^([A-Z]{3}\d{3})@(.+)$/);
+  if (!match || match[1] !== detector.code) throw new Error('expectedIdentity must use the detector code.');
+  const expectedPath = safePath(match[2], 'expectedIdentity path');
+  const interestingness = object(root.interestingness, 'interestingness');
+  exactKeys(interestingness, new Set(['predicate']), 'interestingness');
+  if (!PREDICATES.has(interestingness.predicate)) throw new Error('interestingness.predicate is invalid.');
+  const fixture = parseFiles(root.fixture, 'fixture');
+  const oppositeControl = parseFiles(root.oppositeControl, 'oppositeControl');
+  const fixturePaths = fixture.files.map(file => file.path).sort();
+  const controlPaths = oppositeControl.files.map(file => file.path).sort();
+  if (JSON.stringify(fixturePaths) !== JSON.stringify(controlPaths) || !fixturePaths.includes(expectedPath)) {
+    throw new Error('fixture and oppositeControl must share paths and include the expectedIdentity path.');
+  }
+  const provenance = object(root.provenance, 'provenance');
+  exactKeys(provenance, new Set(['synthetic', 'redactionAttested']), 'provenance');
+  if (provenance.synthetic !== true || provenance.redactionAttested !== true) throw new Error('Synthetic provenance and reviewed redaction must both be attested.');
+  validateConfig(root.config);
+  return {
+    $schema: FEEDBACK_SCHEMA_URL, schemaVersion: 1, classification: root.classification,
+    detector: { code: detector.code, validator: detector.validator }, parserTier: root.parserTier,
+    config: root.config, expectedIdentity: `${detector.code}@${expectedPath}`,
+    interestingness: { predicate: interestingness.predicate }, fixture, oppositeControl,
+    provenance: { synthetic: true, redactionAttested: true }, contribution: parseContribution(root.contribution),
+  };
+}
+
+function shape(files) {
+  return files.map(file => {
+    const normalized = file.content
+      .replace(/(['"`])(?:\\.|(?!\1).)*\1/g, ' STRING ')
+      .replace(/\b\d+(?:\.\d+)?\b/g, ' NUMBER ')
+      .replace(/\b[A-Za-z_$][\w$]*\b/g, ' ID ')
+      .replace(/\s+/g, ' ').trim();
+    return `${extname(file.path).toLowerCase()}:${normalized}`;
+  }).sort().join('|');
+}
+
+export function feedbackDuplicateIdentity(manifest) {
+  const input = [manifest.detector.code, manifest.classification, manifest.parserTier, shape(manifest.fixture.files)].join('|');
+  return `dgf-${createHash('sha256').update(input).digest('hex').slice(0, 16)}`;
+}
+
+export function feedbackFindingIdentity(finding) {
+  const raw = typeof finding.location === 'string' ? finding.location : finding.location?.file || '<project>';
+  return `${finding.code}@${raw.replace(/:\d+(?::\d+)?$/, '').replaceAll('\\', '/')}`;
+}
+
+export function feedbackSearchUrls(manifest, issuesBase = 'https://github.com/raccioly/docguard/issues') {
+  const repository = issuesBase.replace(/^https:\/\/github\.com\//, '').replace(/\/issues.*$/, '');
+  const identity = feedbackDuplicateIdentity(manifest);
+  const build = state => `https://github.com/search?q=${encodeURIComponent(`repo:${repository} "${identity}" state:${state}`)}&type=issues`;
+  return { identity, all: build('open').replace(encodeURIComponent(' state:open'), ''), open: build('open'), closed: build('closed') };
+}
+
+export function reduceFixtureDeterministically(manifest, interesting, maxAttempts = 100) {
+  let current = structuredClone(manifest);
+  let attempts = 0;
+  if (!interesting(current)) return { status: 'NOT_REPRODUCED', attempts, manifest: current };
+  for (let fileIndex = 0; fileIndex < current.fixture.files.length && attempts < maxAttempts; fileIndex++) {
+    let changed = true;
+    while (changed && attempts < maxAttempts) {
+      changed = false;
+      const lines = current.fixture.files[fileIndex].content.split('\n');
+      if (lines.length <= 1) break;
+      for (let line = 0; line < lines.length && attempts < maxAttempts; line++) {
+        const candidate = structuredClone(current);
+        candidate.fixture.files[fileIndex].content = lines.filter((_, index) => index !== line).join('\n');
+        attempts++;
+        if (interesting(candidate)) { current = candidate; changed = true; break; }
+      }
+    }
+  }
+  return { status: attempts >= maxAttempts ? 'REDUCED_LIMIT' : 'REDUCED', attempts, manifest: current };
+}
+
+export function assertContributionReady(manifest) {
+  if (!['false_positive', 'false_negative', 'unsupported_syntax'].includes(manifest.classification)) {
+    throw new Error('Ambiguous and policy-disagreement fixtures require adjudication before a test contribution.');
+  }
+  if (!manifest.contribution?.testOnly || !manifest.contribution.scopeDocumented) {
+    throw new Error('Contribution requires testOnly and scopeDocumented attestations plus benchmarkDelta.');
+  }
+  return true;
+}
+
+export function buildTestOnlyContribution(manifest) {
+  assertContributionReady(manifest);
+  const encoded = JSON.stringify(manifest);
+  return `import { test } from 'node:test';\nimport assert from 'node:assert/strict';\nimport { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';\nimport { dirname, join } from 'node:path';\nimport { tmpdir } from 'node:os';\nimport { runGuardInternal } from '../cli/commands/guard.mjs';\nimport { feedbackFindingIdentity } from '../cli/feedback-fixture.mjs';\n\nconst manifest = ${encoded};\nfunction run(files) {\n  const root = mkdtempSync(join(tmpdir(), 'docguard-contribution-'));\n  try {\n    for (const file of files) { const target = join(root, file.path); mkdirSync(dirname(target), { recursive: true }); writeFileSync(target, file.content); }\n    return runGuardInternal(root, manifest.config);\n  } finally { rmSync(root, { recursive: true, force: true }); }\n}\n\ntest('${manifest.detector.code} ${manifest.classification} synthetic reproduction (${feedbackDuplicateIdentity(manifest)})', () => {\n  const fixture = run(manifest.fixture.files);\n  const control = run(manifest.oppositeControl.files);\n  const fixtureHas = fixture.findings.some(finding => feedbackFindingIdentity(finding) === manifest.expectedIdentity);\n  const controlHas = control.findings.some(finding => feedbackFindingIdentity(finding) === manifest.expectedIdentity);\n  const fixtureApplicability = fixture.validators.find(item => item.key === manifest.detector.validator)?.applicability?.status;\n  const controlApplicability = control.validators.find(item => item.key === manifest.detector.validator)?.applicability?.status;\n  ${manifest.classification === 'false_positive' ? 'assert.equal(fixtureHas, false); assert.equal(controlHas, true);' : manifest.classification === 'false_negative' ? 'assert.equal(fixtureHas, true); assert.equal(controlHas, false);' : `assert.notEqual(fixtureApplicability, 'unsupported'); assert.equal(controlApplicability, 'checked'); assert.equal(controlHas, false);`}\n});\n`;
+}

package/cli/scanners/document-lifecycle.mjs

@@ -7,53 +7,28 @@ import { existsSync, readFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { dirname, resolve } from 'node:path';
 import { shouldIgnore } from '../shared-ignore.mjs';
+import { readSpecRegistry } from './spec-registry.mjs';
+import { readRetirementManifest } from './retirement-manifest.mjs';
 
 const RETIRED_STATUSES = new Set(['archived', 'deprecated', 'obsolete', 'superseded']);
 const COMPLETION_STATUSES = new Set(['complete', 'completed']);
 const EXCLUDED_PREFIXES = ['.git', '.local', '.docguard'];
-const MANIFEST_PATH = '.docguard-archive.json';
+const SUPPRESSIBLE_DELIVERY = new Set(['verified', 'released']);
 
-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}` };
-  }
+/**
+ * Read only the narrow registry state needed to avoid asking users to retire a
+ * verified living specification. Any malformed or unknown shape fails closed:
+ * the ordinary lifecycle review signal remains visible.
+ * @implements docguard.document-lifecycle#FR-002
+ */
+function readVerifiedLivingSpecPaths(projectDir) {
+  const registry = readSpecRegistry(projectDir);
+  if (!registry.exists || registry.error) return new Set();
+  return new Set(registry.value.specs
+    .filter(spec => spec.reviewed.lifecycle.context === 'current'
+      && spec.reviewed.lifecycle.persistenceModel === 'living'
+      && SUPPRESSIBLE_DELIVERY.has(spec.reviewed.lifecycle.delivery))
+    .map(spec => spec.path));
 }
 
 function trackedFiles(projectDir) {
@@ -110,6 +85,7 @@ export function scanDocumentLifecycle(projectDir, config = {}) {
     };
   }
   const tracked = new Set(inventory.files);
+  const verifiedLivingSpecs = readVerifiedLivingSpecPaths(projectDir);
   const markdown = inventory.files.filter(path => /\.md$/i.test(path));
   const candidates = [];
   const unreadable = [];
@@ -159,7 +135,7 @@ export function scanDocumentLifecycle(projectDir, config = {}) {
     }
     if (path.startsWith('specs/') && /(?:^|\/)spec\.md$/i.test(path)) {
       const tasks = completedTaskSignal(projectDir, path, content, tracked);
-      if (tasks) {
+      if (tasks && !verifiedLivingSpecs.has(path)) {
         candidates.push({
           code: 'DLC002',
           path: dirname(path),

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`;
+}