docguard-cli 0.39.0 → 0.40.1

package/cli/evidence/evaluate.mjs

@@ -0,0 +1,185 @@
+/**
+ * Five-state evidence evaluation and stable identities.
+ * @implements docguard.evidence-scoped-verification#FR-007
+ * @implements docguard.evidence-scoped-verification#FR-008
+ * @implements docguard.evidence-scoped-verification#FR-010
+ * @implements docguard.evidence-scoped-verification#FR-011
+ * @implements docguard.evidence-scoped-verification#FR-012
+ */
+
+import { createEvidenceReader, contentHash } from '../scanners/semantic-claims.mjs';
+import { loadEvidenceManifest } from './manifest.mjs';
+import { readEvidenceSource } from './adapters.mjs';
+import { parseDocumentValue, selectMarkdownStatement } from './markdown.mjs';
+
+export const EVIDENCE_SCOPE_LIMITATION = 'Verification applies only to the declared Markdown statement, source adapter, predicate, producer metadata, and captured local inputs. It does not establish whole-document, runtime, deployment, or compliance accuracy.';
+export const EVIDENCE_STATES = ['verified-within-scope', 'contradicted', 'stale', 'inconclusive', 'unsupported'];
+
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])]));
+  }
+  return value;
+}
+
+function identity(prefix, value) {
+  return `${prefix}.${contentHash(JSON.stringify(canonical(value))).slice(7)}`;
+}
+
+function resultState(declaration, selection, source, state, reasonCode, message, extra = {}) {
+  const selectedStatement = selection?.statement || declaration.target.statement;
+  const claimId = identity('claim', {
+    declaration,
+    selectedStatement,
+    sourceValue: source?.value,
+    sourceEvidence: source?.sourceEvidence || null,
+    inputHashes: source?.inputHashes || [],
+  });
+  const evidencePayload = {
+    claimId,
+    sourceEvidence: source?.sourceEvidence || null,
+    inputHashes: source?.inputHashes || [],
+    sourceValue: source?.value,
+  };
+  return {
+    declarationId: declaration.id,
+    state,
+    claimId,
+    evidenceId: identity('evidence', evidencePayload),
+    document: declaration.target.document,
+    location: selection?.line ? `${declaration.target.document}:${selection.line}` : declaration.target.document,
+    heading: declaration.target.heading,
+    statement: selectedStatement,
+    adapter: declaration.source.adapter,
+    predicate: declaration.predicate.kind,
+    inputHashes: source?.inputHashes || [],
+    evidenceHash: source?.sourceEvidence?.hash || identity('snapshot', evidencePayload),
+    reasonCode,
+    message,
+    scopeLimitation: EVIDENCE_SCOPE_LIMITATION,
+    ...extra,
+  };
+}
+
+function compare(declaration, selection, source) {
+  const predicate = declaration.predicate;
+  if (predicate.kind === 'no-findings') {
+    return source.value === 0
+      ? { match: true, documentValue: null, sourceValue: 0 }
+      : { match: false, documentValue: null, sourceValue: source.value };
+  }
+  const document = parseDocumentValue(selection.value, predicate);
+  if (!document.ok) return { unsupported: false, inconclusive: true, ...document };
+  if (predicate.kind === 'equals') {
+    const expectedType = predicate.valueType;
+    const actualType = source.value === null ? 'null' : typeof source.value;
+    if (actualType !== expectedType || (actualType === 'number' && !Number.isFinite(source.value))) {
+      return { unsupported: true, reasonCode: 'source-type-mismatch', message: `JSON source type ${actualType} does not match declared ${expectedType}.` };
+    }
+    return { match: Object.is(document.value, source.value), documentValue: document.value, sourceValue: source.value };
+  }
+  if (predicate.kind === 'set-equals') {
+    if (!Array.isArray(source.value) || source.value.some(item => typeof item !== 'string')) {
+      return { unsupported: true, reasonCode: 'source-set-shape', message: 'JSON source must be an array of strings for set-equals.' };
+    }
+    if (new Set(source.value).size !== source.value.length) {
+      return { unsupported: true, reasonCode: 'duplicate-source-set-item', message: 'JSON source set contains duplicate items.' };
+    }
+    const left = [...document.value].sort();
+    const right = [...source.value].sort();
+    return { match: left.length === right.length && left.every((item, index) => item === right[index]), documentValue: document.value, sourceValue: source.value };
+  }
+  if (predicate.kind === 'count-equals') {
+    if (!Number.isSafeInteger(source.value) || source.value < 0) {
+      return { unsupported: true, reasonCode: 'source-count-shape', message: 'Collection source did not produce a non-negative safe integer.' };
+    }
+    return { match: document.value === source.value, documentValue: document.value, sourceValue: source.value };
+  }
+  return { unsupported: true, reasonCode: 'unsupported-predicate', message: `Predicate ${predicate.kind} is unsupported.` };
+}
+
+function evaluateDeclaration(projectDir, config, declaration, read) {
+  const document = read(declaration.target.document);
+  if (document.content === null) {
+    return resultState(declaration, null, document, 'inconclusive', `document-${document.evidence.reason}`, `Cannot safely read ${declaration.target.document}.`);
+  }
+  const selection = selectMarkdownStatement(document.content, declaration.target, declaration.predicate.kind);
+  if (selection.status !== 'ok') {
+    return resultState(declaration, selection, document, 'inconclusive', selection.reasonCode, selection.message);
+  }
+  const source = readEvidenceSource(projectDir, declaration, read, config);
+  if (source.status !== 'ok') {
+    return resultState(declaration, selection, source, source.status, source.reasonCode, source.message);
+  }
+  const compared = compare(declaration, selection, source);
+  if (compared.unsupported) return resultState(declaration, selection, source, 'unsupported', compared.reasonCode, compared.message);
+  if (compared.inconclusive) return resultState(declaration, selection, source, 'inconclusive', compared.reasonCode, compared.message);
+  const state = compared.match ? 'verified-within-scope' : 'contradicted';
+  const message = compared.match
+    ? 'The selected statement matches its current declared evidence.'
+    : 'The selected statement contradicts its current declared evidence.';
+  return resultState(declaration, selection, source, state, compared.match ? 'predicate-satisfied' : 'predicate-mismatch', message, {
+    documentValue: compared.documentValue,
+  });
+}
+
+export function evaluateEvidence(projectDir, config = {}) {
+  const read = createEvidenceReader(projectDir);
+  const loaded = loadEvidenceManifest(projectDir, read);
+  if (!loaded.exists) {
+    return {
+      command: 'verify --evidence', exists: false, manifest: '.docguard-evidence.json',
+      status: 'not-configured', errors: [], results: [], summary: Object.fromEntries(EVIDENCE_STATES.map(state => [state, 0])),
+      scopeLimitation: EVIDENCE_SCOPE_LIMITATION,
+    };
+  }
+  if (loaded.errors.length) {
+    return {
+      command: 'verify --evidence', exists: true, manifest: '.docguard-evidence.json',
+      status: 'invalid', manifestEvidence: loaded.evidence, errors: loaded.errors, results: [],
+      summary: Object.fromEntries(EVIDENCE_STATES.map(state => [state, 0])), scopeLimitation: EVIDENCE_SCOPE_LIMITATION,
+    };
+  }
+  const results = loaded.manifest.declarations.map(declaration => evaluateDeclaration(projectDir, config, declaration, read));
+  const summary = Object.fromEntries(EVIDENCE_STATES.map(state => [state, results.filter(result => result.state === state).length]));
+  const status = summary.contradicted > 0 ? 'contradicted'
+    : summary.stale + summary.inconclusive + summary.unsupported > 0 ? 'attention-required'
+      : 'verified-within-scope';
+  return {
+    command: 'verify --evidence', exists: true, manifest: '.docguard-evidence.json', status,
+    manifestEvidence: loaded.evidence, errors: [], results, summary, scopeLimitation: EVIDENCE_SCOPE_LIMITATION,
+  };
+}
+
+/** Reduce heuristic work only when one verified declaration maps to one exact extracted claim. */
+export function coverSemanticClaims(claims, evaluation) {
+  const verified = evaluation?.results?.filter(result => result.state === 'verified-within-scope') || [];
+  const candidates = new Map();
+  for (const claim of claims) {
+    const matches = verified.filter(result => {
+      const line = Number(String(result.location).match(/:(\d+)$/)?.[1]);
+      if (result.document !== claim.doc || line !== claim.line || !String(claim.text).includes(result.statement)) return false;
+      if (Array.isArray(result.documentValue)) return claim.kind === 'enum' && result.documentValue.join('/') === claim.value;
+      if (result.documentValue === null) return false;
+      return String(result.documentValue) === String(claim.value);
+    });
+    candidates.set(claim.stableId, matches);
+  }
+  const resultUse = new Map();
+  for (const matches of candidates.values()) {
+    for (const result of matches) resultUse.set(result.claimId, (resultUse.get(result.claimId) || 0) + 1);
+  }
+  const covered = claims.filter(claim => {
+    const matches = candidates.get(claim.stableId) || [];
+    return matches.length === 1 && resultUse.get(matches[0].claimId) === 1;
+  });
+  const coveredIds = new Set(covered.map(claim => claim.stableId));
+  return {
+    total: claims.length,
+    verifiedWithinScope: covered.length,
+    unverified: claims.length - covered.length,
+    covered: covered.map(claim => claim.stableId),
+    remaining: claims.filter(claim => !coveredIds.has(claim.stableId)),
+  };
+}

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/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,
+  },
 };
 
 /**

package/cli/release-pr-policy.mjs

@@ -0,0 +1,107 @@
+/**
+ * Pure policy for privileged release pull-request evaluation.
+ *
+ * @implements docguard.tokenless-scheduled-releases#FR-005
+ * @implements docguard.tokenless-scheduled-releases#FR-006
+ * @implements docguard.tokenless-scheduled-releases#FR-007
+ * @implements docguard.tokenless-scheduled-releases#FR-008
+ * @implements docguard.tokenless-scheduled-releases#FR-011
+ */
+
+export const REQUIRED_RELEASE_JOBS = Object.freeze([
+  'test (18)',
+  'test (20)',
+  'test (22)',
+  'test (24)',
+]);
+
+export const RELEASE_PATH_ALLOWLIST = /^(package(-lock)?\.json|pyproject\.toml|server\.json|CHANGELOG\.md|templates\/ci\/github-actions\.yml|extensions\/spec-kit-docguard\/(extension\.yml|templates\/github-workflows\/(docguard-guard|docguard-autofix)\.yml|skills\/docguard-(fix|guard|review|score|sync)\/SKILL\.md)|\.agent\/skills\/docguard-(fix|guard|review|score|sync)\/SKILL\.md)$/;
+
+const VERSION_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+
+function parseVersion(value) {
+  const match = VERSION_PATTERN.exec(value || '');
+  return match ? match.slice(1).map(Number) : null;
+}
+
+function nextAllowed(base, candidate) {
+  if (!base || !candidate || candidate[0] !== base[0]) return false;
+  const nextPatch = candidate[1] === base[1] && candidate[2] === base[2] + 1;
+  const nextMinor = candidate[1] === base[1] + 1 && candidate[2] === 0;
+  return nextPatch || nextMinor;
+}
+
+function parseJson(text, label, errors) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    errors.push(`${label}: invalid JSON`);
+    return {};
+  }
+}
+
+function extractVersions(files, errors) {
+  const pkg = parseJson(files.packageJson, 'package.json', errors);
+  const lock = parseJson(files.packageLock, 'package-lock.json', errors);
+  const server = parseJson(files.server, 'server.json', errors);
+  const python = /^version\s*=\s*["']([^"']+)["']/m.exec(files.pyproject || '')?.[1];
+  const extension = /^  version:\s*["']([^"']+)["']/m.exec(files.extension || '')?.[1];
+  return {
+    package: pkg.version,
+    lock: lock.version,
+    lockPackage: lock.packages?.['']?.version,
+    python,
+    server: server.version,
+    extension,
+  };
+}
+
+export function evaluateReleaseCandidate(input) {
+  const errors = [];
+  const branchMatch = /^release\/v(\d+\.\d+\.\d+)$/.exec(input.headRef || '');
+  const titleMatch = /^release: v(\d+\.\d+\.\d+) — automated weekly batch$/.exec(input.title || '');
+  const branchVersion = branchMatch?.[1];
+  const titleVersion = titleMatch?.[1];
+
+  if (input.headRepo !== input.repository) errors.push('head repository: mismatch');
+  if (input.baseRef !== input.defaultBranch) errors.push('base branch: mismatch');
+  if (input.author !== 'github-actions[bot]') errors.push('author: must be github-actions[bot]');
+  if (!branchVersion) errors.push('head branch: invalid release branch');
+  if (!titleVersion) errors.push('title: invalid automated release title');
+
+  const unexpectedPaths = (input.paths || []).filter(path => !RELEASE_PATH_ALLOWLIST.test(path));
+  if (unexpectedPaths.length) errors.push(`paths: unexpected ${unexpectedPaths.join(', ')}`);
+  if (!(input.paths || []).includes('package.json')) errors.push('paths: package.json is required');
+  if (!(input.paths || []).includes('CHANGELOG.md')) errors.push('paths: CHANGELOG.md is required');
+
+  const versions = extractVersions(input.files || {}, errors);
+  const candidateVersion = versions.package;
+  for (const [surface, value] of Object.entries(versions)) {
+    if (!value) errors.push(`${surface}: missing version`);
+    else if (candidateVersion && value !== candidateVersion) errors.push(`${surface}: version mismatch`);
+  }
+  if (branchVersion && candidateVersion && branchVersion !== candidateVersion) errors.push('branch: version mismatch');
+  if (titleVersion && candidateVersion && titleVersion !== candidateVersion) errors.push('title: version mismatch');
+  if (!nextAllowed(parseVersion(input.baseVersion), parseVersion(candidateVersion))) {
+    errors.push('version: must be the next patch or next minor');
+  }
+  if (input.tagExists) errors.push('tag: release already exists');
+
+  return { ok: errors.length === 0, version: candidateVersion || branchVersion || null, errors };
+}
+
+export function evaluateReleaseJobs(jobs) {
+  const errors = [];
+  for (const name of REQUIRED_RELEASE_JOBS) {
+    const matches = (jobs || []).filter(job => job.name === name);
+    if (matches.length !== 1) {
+      errors.push(`${name}: expected one job, found ${matches.length}`);
+      continue;
+    }
+    const [job] = matches;
+    if (job.status !== 'completed' || job.conclusion !== 'success') {
+      errors.push(`${name}: ${job.status || 'unknown'}/${job.conclusion || 'unknown'}`);
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}