docguard-cli 0.38.0 → 0.40.0

package/cli/evidence/manifest.mjs

@@ -0,0 +1,194 @@
+/**
+ * Strict loader for evidence-scoped verification declarations.
+ * @implements docguard.evidence-scoped-verification#FR-001
+ * @implements docguard.evidence-scoped-verification#FR-002
+ */
+
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { createEvidenceReader } from '../scanners/semantic-claims.mjs';
+
+export const EVIDENCE_MANIFEST_PATH = '.docguard-evidence.json';
+export const EVIDENCE_SCHEMA_URL = 'https://raccioly.github.io/docguard/schemas/docguard-evidence.schema.json';
+export const EVIDENCE_SCHEMA_VERSION = 1;
+export const MAX_DECLARATIONS = 128;
+export const MAX_REPORT_INPUTS = 32;
+
+const ID_RE = /^[a-z0-9][a-z0-9._-]{2,127}$/;
+const HASH_RE = /^sha256:[0-9a-f]{64}$/;
+const VALUE_PREDICATES = new Set(['equals', 'set-equals', 'count-equals']);
+const REPORT_ADAPTERS = new Set(['oasdiff', 'buf']);
+
+function issue(message, declarationId = null) {
+  return { code: 'invalid-manifest', message, declarationId };
+}
+
+function object(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function exactKeys(value, allowed, label, errors, id = null) {
+  if (!object(value)) {
+    errors.push(issue(`${label} must be an object.`, id));
+    return false;
+  }
+  const unknown = Object.keys(value).filter(key => !allowed.includes(key));
+  if (unknown.length) errors.push(issue(`${label} has unknown field(s): ${unknown.join(', ')}.`, id));
+  return unknown.length === 0;
+}
+
+export function isSafeEvidencePath(path) {
+  return typeof path === 'string' && path.length > 0 && path.length <= 512
+    && !path.startsWith('/') && !/[\\:\0]/.test(path)
+    && !path.split('/').some(part => part === '..' || part.toLowerCase() === '.local' || /^\.env(?:\.|$)/i.test(part));
+}
+
+function validateTarget(target, errors, id) {
+  exactKeys(target, ['document', 'heading', 'statement'], `${id}.target`, errors, id);
+  if (!isSafeEvidencePath(target?.document) || !target.document.endsWith('.md')) {
+    errors.push(issue(`${id}.target.document must be a safe repository-relative Markdown path.`, id));
+  }
+  if (typeof target?.heading !== 'string' || !target.heading.trim() || target.heading.length > 200) {
+    errors.push(issue(`${id}.target.heading must contain 1-200 characters.`, id));
+  }
+  if (typeof target?.statement !== 'string' || !target.statement.trim() || target.statement.length > 1000) {
+    errors.push(issue(`${id}.target.statement must contain 1-1000 characters.`, id));
+  }
+}
+
+function validateInputs(inputs, errors, id) {
+  if (!Array.isArray(inputs) || inputs.length < 1 || inputs.length > MAX_REPORT_INPUTS) {
+    errors.push(issue(`${id}.source.inputs must contain 1-${MAX_REPORT_INPUTS} input snapshots.`, id));
+    return;
+  }
+  const seen = new Set();
+  for (const [index, input] of inputs.entries()) {
+    exactKeys(input, ['path', 'sha256'], `${id}.source.inputs[${index}]`, errors, id);
+    if (!isSafeEvidencePath(input?.path)) errors.push(issue(`${id}.source.inputs[${index}].path is unsafe.`, id));
+    if (!HASH_RE.test(input?.sha256 || '')) errors.push(issue(`${id}.source.inputs[${index}].sha256 must be a lowercase SHA-256 identity.`, id));
+    if (seen.has(input?.path)) errors.push(issue(`${id}.source.inputs repeats ${input.path}.`, id));
+    seen.add(input?.path);
+  }
+}
+
+function validateSource(source, errors, id) {
+  if (!object(source)) {
+    errors.push(issue(`${id}.source must be an object.`, id));
+    return;
+  }
+  if (source.adapter === 'json-pointer') {
+    exactKeys(source, ['adapter', 'path', 'pointer'], `${id}.source`, errors, id);
+    if (!isSafeEvidencePath(source.path)) errors.push(issue(`${id}.source.path is unsafe.`, id));
+    if (typeof source.pointer !== 'string' || source.pointer.length > 512 || (source.pointer && !source.pointer.startsWith('/'))) {
+      errors.push(issue(`${id}.source.pointer must be an RFC 6901 JSON Pointer.`, id));
+    }
+    return;
+  }
+  if (source.adapter === 'collection-count') {
+    exactKeys(source, ['adapter', 'glob', 'allowEmpty'], `${id}.source`, errors, id);
+    if (!isSafeEvidencePath(source.glob) || source.glob.length > 512) errors.push(issue(`${id}.source.glob is unsafe or unbounded.`, id));
+    if (typeof source.allowEmpty !== 'boolean') errors.push(issue(`${id}.source.allowEmpty must be boolean.`, id));
+    return;
+  }
+  if (REPORT_ADAPTERS.has(source.adapter)) {
+    exactKeys(source, ['adapter', 'adapterVersion', 'path', 'producerVersion', 'command', 'inputs'], `${id}.source`, errors, id);
+    if (!Number.isInteger(source.adapterVersion) || source.adapterVersion < 1 || source.adapterVersion > 100) {
+      errors.push(issue(`${id}.source.adapterVersion must be an integer from 1-100.`, id));
+    }
+    if (!isSafeEvidencePath(source.path)) errors.push(issue(`${id}.source.path is unsafe.`, id));
+    if (typeof source.producerVersion !== 'string' || !source.producerVersion.trim() || source.producerVersion.length > 80) {
+      errors.push(issue(`${id}.source.producerVersion must contain 1-80 characters.`, id));
+    }
+    if (typeof source.command !== 'string' || !source.command.trim() || source.command.length > 40) {
+      errors.push(issue(`${id}.source.command must contain 1-40 characters.`, id));
+    }
+    validateInputs(source.inputs, errors, id);
+    return;
+  }
+  errors.push(issue(`${id}.source.adapter is unsupported.`, id));
+}
+
+function validatePredicate(predicate, source, statement, errors, id) {
+  if (!object(predicate)) {
+    errors.push(issue(`${id}.predicate must be an object.`, id));
+    return;
+  }
+  if (predicate.kind === 'equals') {
+    exactKeys(predicate, ['kind', 'valueType'], `${id}.predicate`, errors, id);
+    if (!['string', 'number', 'boolean', 'null'].includes(predicate.valueType)) {
+      errors.push(issue(`${id}.predicate.valueType is unsupported.`, id));
+    }
+  } else if (predicate.kind === 'set-equals') {
+    exactKeys(predicate, ['kind', 'itemType', 'separator'], `${id}.predicate`, errors, id);
+    if (predicate.itemType !== 'string') errors.push(issue(`${id}.predicate.itemType must be string.`, id));
+    if (typeof predicate.separator !== 'string' || !predicate.separator || predicate.separator.length > 16) {
+      errors.push(issue(`${id}.predicate.separator must contain 1-16 characters.`, id));
+    }
+  } else if (predicate.kind === 'count-equals' || predicate.kind === 'no-findings') {
+    exactKeys(predicate, ['kind'], `${id}.predicate`, errors, id);
+  } else {
+    errors.push(issue(`${id}.predicate.kind is unsupported.`, id));
+  }
+
+  const slots = typeof statement === 'string' ? statement.split('{{value}}').length - 1 : 0;
+  if (VALUE_PREDICATES.has(predicate.kind) && slots !== 1) {
+    errors.push(issue(`${id}.target.statement must contain exactly one {{value}} slot for ${predicate.kind}.`, id));
+  }
+  if (predicate.kind === 'no-findings' && slots !== 0) {
+    errors.push(issue(`${id}.target.statement cannot contain {{value}} for no-findings.`, id));
+  }
+  if (source?.adapter === 'json-pointer' && !['equals', 'set-equals'].includes(predicate.kind)) {
+    errors.push(issue(`${id} combines json-pointer with an incompatible predicate.`, id));
+  }
+  if (source?.adapter === 'collection-count' && predicate.kind !== 'count-equals') {
+    errors.push(issue(`${id} must combine collection-count with count-equals.`, id));
+  }
+  if (REPORT_ADAPTERS.has(source?.adapter) && predicate.kind !== 'no-findings') {
+    errors.push(issue(`${id} must combine ${source.adapter} with no-findings.`, id));
+  }
+}
+
+function validateDeclaration(declaration, index, errors) {
+  const label = declaration?.id || `declarations[${index}]`;
+  exactKeys(declaration, ['id', 'applicability', 'target', 'source', 'predicate'], label, errors, label);
+  if (!ID_RE.test(declaration?.id || '')) errors.push(issue(`${label}.id is invalid.`, label));
+  exactKeys(declaration?.applicability, ['mode'], `${label}.applicability`, errors, label);
+  if (declaration?.applicability?.mode !== 'always') errors.push(issue(`${label}.applicability.mode is unsupported.`, label));
+  validateTarget(declaration?.target, errors, label);
+  validateSource(declaration?.source, errors, label);
+  validatePredicate(declaration?.predicate, declaration?.source, declaration?.target?.statement, errors, label);
+}
+
+export function validateEvidenceManifest(manifest) {
+  const errors = [];
+  exactKeys(manifest, ['$schema', 'schemaVersion', 'declarations'], 'manifest', errors);
+  if (manifest?.$schema !== EVIDENCE_SCHEMA_URL) errors.push(issue(`$schema must be ${EVIDENCE_SCHEMA_URL}.`));
+  if (manifest?.schemaVersion !== EVIDENCE_SCHEMA_VERSION) errors.push(issue(`schemaVersion must be ${EVIDENCE_SCHEMA_VERSION}.`));
+  if (!Array.isArray(manifest?.declarations) || manifest.declarations.length < 1 || manifest.declarations.length > MAX_DECLARATIONS) {
+    errors.push(issue(`declarations must contain 1-${MAX_DECLARATIONS} entries.`));
+    return errors;
+  }
+  const ids = new Set();
+  for (const [index, declaration] of manifest.declarations.entries()) {
+    validateDeclaration(declaration, index, errors);
+    if (ids.has(declaration?.id)) errors.push(issue(`Duplicate declaration ID ${declaration.id}.`, declaration.id));
+    ids.add(declaration?.id);
+  }
+  return errors;
+}
+
+export function loadEvidenceManifest(projectDir, read = createEvidenceReader(projectDir)) {
+  const path = resolve(projectDir, EVIDENCE_MANIFEST_PATH);
+  if (!existsSync(path)) return { exists: false, manifest: null, errors: [], evidence: null };
+  const snapshot = read(EVIDENCE_MANIFEST_PATH);
+  if (snapshot.content === null) {
+    return { exists: true, manifest: null, errors: [issue(`Cannot safely read ${EVIDENCE_MANIFEST_PATH}: ${snapshot.evidence.reason}.`)], evidence: snapshot.evidence };
+  }
+  let manifest;
+  try { manifest = JSON.parse(snapshot.content); }
+  catch (error) {
+    return { exists: true, manifest: null, errors: [issue(`${EVIDENCE_MANIFEST_PATH} is invalid JSON: ${error.message}`)], evidence: snapshot.evidence };
+  }
+  const errors = validateEvidenceManifest(manifest);
+  return { exists: true, manifest: errors.length ? null : manifest, errors, evidence: snapshot.evidence };
+}

package/cli/evidence/markdown.mjs

@@ -0,0 +1,107 @@
+/**
+ * Exact, heading-scoped Markdown statement selection.
+ * @implements docguard.evidence-scoped-verification#FR-006
+ */
+
+function normalizeHorizontal(value) {
+  return String(value).replace(/[ \t]+/g, ' ').trim();
+}
+
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/[ \t]+/g, '[ \\t]+');
+}
+
+function visibleLines(content) {
+  const lines = String(content).split(/\r?\n/);
+  let fence = null;
+  return lines.map((text, index) => {
+    const marker = text.match(/^\s*(`{3,}|~{3,})/);
+    if (marker) {
+      const char = marker[1][0];
+      if (!fence) fence = { char, length: marker[1].length };
+      else if (fence.char === char && marker[1].length >= fence.length) fence = null;
+      return { line: index + 1, text: '', hidden: true };
+    }
+    return { line: index + 1, text: fence ? '' : text, hidden: Boolean(fence) };
+  });
+}
+
+function headings(lines) {
+  const out = [];
+  for (let index = 0; index < lines.length; index++) {
+    const row = lines[index];
+    const match = row.text.match(/^\s{0,3}(#{1,6})[ \t]+(.+?)[ \t]*#*[ \t]*$/);
+    if (match) {
+      out.push({ level: match[1].length, text: normalizeHorizontal(match[2]), line: row.line, endLine: row.line });
+      continue;
+    }
+    const underline = lines[index + 1]?.text.match(/^\s{0,3}(=+|-+)[ \t]*$/);
+    if (!row.hidden && normalizeHorizontal(row.text) && underline) {
+      out.push({ level: underline[1][0] === '=' ? 1 : 2, text: normalizeHorizontal(row.text), line: row.line, endLine: lines[index + 1].line });
+      index++;
+    }
+  }
+  return out;
+}
+
+export function selectMarkdownStatement(content, target, predicateKind) {
+  const lines = visibleLines(content);
+  const foundHeadings = headings(lines).filter(item => item.text === normalizeHorizontal(target.heading));
+  if (foundHeadings.length === 0) return { status: 'inconclusive', reasonCode: 'heading-missing', message: `Heading “${target.heading}” was not found.` };
+  if (foundHeadings.length > 1) return { status: 'inconclusive', reasonCode: 'heading-ambiguous', message: `Heading “${target.heading}” is not unique.` };
+  const heading = foundHeadings[0];
+  const allHeadings = headings(lines);
+  const next = allHeadings.find(item => item.line > heading.line && item.level <= heading.level);
+  const section = lines.filter(row => row.line > heading.endLine && (!next || row.line < next.line));
+  const valueMode = predicateKind !== 'no-findings';
+  const pieces = target.statement.split('{{value}}');
+  const pattern = valueMode
+    ? `${escapeRegex(pieces[0])}(.+?)${escapeRegex(pieces[1])}`
+    : escapeRegex(target.statement);
+  const matcher = new RegExp(pattern, 'g');
+  const matches = [];
+  for (const row of section) {
+    const normalized = normalizeHorizontal(row.text);
+    if (!normalized) continue;
+    matcher.lastIndex = 0;
+    let match;
+    while ((match = matcher.exec(normalized))) {
+      matches.push({ line: row.line, statement: normalizeHorizontal(match[0]), value: valueMode ? normalizeHorizontal(match[1]) : null });
+      if (!match[0]) matcher.lastIndex++;
+    }
+  }
+  if (matches.length === 0) return { status: 'inconclusive', reasonCode: 'statement-missing', message: 'The declared statement was not found in the selected heading.' };
+  if (matches.length > 1) return { status: 'inconclusive', reasonCode: 'statement-ambiguous', message: 'The declared statement is not unique in the selected heading.' };
+  return { status: 'ok', reasonCode: 'statement-selected', message: 'Markdown statement selected.', ...matches[0] };
+}
+
+export function parseDocumentValue(raw, predicate) {
+  if (predicate.kind === 'count-equals') {
+    if (!/^(?:0|[1-9][0-9]*)$/.test(raw)) return { ok: false, reasonCode: 'invalid-count', message: 'Document value is not a non-negative base-ten integer.' };
+    const value = Number(raw);
+    if (!Number.isSafeInteger(value)) return { ok: false, reasonCode: 'unsafe-count', message: 'Document count exceeds the safe integer range.' };
+    return { ok: true, value };
+  }
+  if (predicate.kind === 'set-equals') {
+    const values = raw.split(predicate.separator).map(item => item.trim());
+    if (values.some(item => !item)) return { ok: false, reasonCode: 'empty-set-item', message: 'Document set contains an empty item.' };
+    if (new Set(values).size !== values.length) return { ok: false, reasonCode: 'duplicate-set-item', message: 'Document set contains duplicate items.' };
+    return { ok: true, value: values };
+  }
+  if (predicate.valueType === 'string') return { ok: true, value: raw };
+  if (predicate.valueType === 'number') {
+    if (!/^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$/.test(raw)) return { ok: false, reasonCode: 'invalid-number', message: 'Document value is not a canonical JSON number.' };
+    const value = Number(raw);
+    if (!Number.isFinite(value)) return { ok: false, reasonCode: 'non-finite-number', message: 'Document number is not finite.' };
+    return { ok: true, value };
+  }
+  if (predicate.valueType === 'boolean') {
+    if (raw !== 'true' && raw !== 'false') return { ok: false, reasonCode: 'invalid-boolean', message: 'Document value must be true or false.' };
+    return { ok: true, value: raw === 'true' };
+  }
+  if (predicate.valueType === 'null') {
+    if (raw !== 'null') return { ok: false, reasonCode: 'invalid-null', message: 'Document value must be null.' };
+    return { ok: true, value: null };
+  }
+  return { ok: false, reasonCode: 'unsupported-value-type', message: 'Predicate value type is unsupported.' };
+}

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/findings.mjs

@@ -1,4 +1,5 @@
 /**
+ * @implements docguard.evidence-scoped-verification#FR-010
  * Findings — the structured, LLM-addressable result unit (v0.27).
  *
  * Background (LLM field report #3): DocGuard's whole job is to tell an agent
@@ -686,6 +687,36 @@ export const CODES = {
     help: 'An API doc unit is vague/generic or barely exceeds the signature it documents (deterministic Lazy detector F1 0.95). Document parameters, return, and errors concretely.',
     suppress: '<!-- docguard:quality api-smell off — your reason -->',
   },
+  EVD001: {
+    validator: 'evidence',
+    title: 'Evidence manifest is invalid',
+    help: 'The strict `.docguard-evidence.json` contract is malformed, unsafe, duplicated, or combines an adapter with an incompatible predicate. Compare it with `templates/evidence-manifest.json`, repair the named field, and rerun `docguard verify --evidence`.',
+    suppress: null,
+  },
+  EVD002: {
+    validator: 'evidence',
+    title: 'Declared evidence contradicts documentation',
+    help: 'A unique Markdown statement and its current declared source disagree under an exact predicate. Review approved intent before changing either side; implementation may have regressed from the document.',
+    suppress: null,
+  },
+  EVD003: {
+    validator: 'evidence',
+    title: 'Saved evidence is stale',
+    help: 'A saved oasdiff or Buf report names an input whose current SHA-256 differs from the declared snapshot. Regenerate the upstream report with the recorded command and producer version, update every input digest, then review the dependent statement.',
+    suppress: null,
+  },
+  EVD004: {
+    validator: 'evidence',
+    title: 'Evidence verification is inconclusive',
+    help: 'DocGuard could not safely and uniquely read the declaration, document statement, source, or report. Restore the evidence or narrow the target; missing evidence never becomes a pass.',
+    suppress: null,
+  },
+  EVD005: {
+    validator: 'evidence',
+    title: 'Evidence format is unsupported',
+    help: 'The adapter version, command, source type, report shape, or predicate is outside the implemented contract. Keep the finding visible and contribute a synthetic failing fixture plus a neighboring valid control before expanding support.',
+    suppress: null,
+  },
 };
 
 /**