@popovych.co/witness 0.4.0

package/dist/verbs/write.js

@@ -0,0 +1,349 @@
+import { existsSync, readFileSync, unlinkSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { EXIT } from '../cli.js';
+import { loadConfig } from '../config.js';
+import { designPending, designRel, designStamp } from '../design.js';
+import { ID_RE } from '../dsl.js';
+import { serializeDoc, splitDoc, writeDoc } from '../fm.js';
+import { dirtyStatePaths, primaryRoot, stateCommit } from '../gitio.js';
+import { appendEntry, entryLine, journalRel, latestRecap, readStream, streamExists } from '../journal.js';
+import { acquireLock } from '../lock.js';
+import { renderRefusal, v } from '../refusal.js';
+import { baseForSpec, contentAtSha } from '../history.js';
+import { findById, findCycle, loadCanon } from '../scan.js';
+import { canonicalJson, canonicalSha, short } from '../sha.js';
+import { kv } from '../toon.js';
+import { crashPoint, guardTxn, withTxn } from '../txn.js';
+import { validateDoc } from '../schemas.js';
+function buildSpecMeta(root, id, manifest, recap, canon, existing, body) {
+    const violations = [];
+    const type = manifest.type;
+    if (recap.class === 'chore') {
+        violations.push(v('type', 'class-tripwire', `chore effort writing ${type} content`, 'chores never change state — reclassify via recap --amend, or write a plan'));
+    }
+    const covers = Array.isArray(manifest.covers) ? manifest.covers : [];
+    const goalIds = new Set(recap.goals.map((g) => g.id));
+    covers.forEach((g, i) => {
+        if (!goalIds.has(g))
+            violations.push(v(`covers[${i}]`, 'unknown-goal', String(g), `a goal id from the latest recap: ${[...goalIds].join(' ')}`));
+    });
+    const meta = {
+        id,
+        type,
+        status: 'draft',
+        ...(type === 'spec' ? { summary: manifest.summary } : {}),
+        ...(type === 'spec' && manifest.ui !== undefined ? { ui: manifest.ui } : {}),
+        depends: manifest.depends ?? [],
+        needs: manifest.needs ?? [],
+        ...(type === 'spec' ? { criteria: manifest.criteria } : {}),
+        ...(manifest.supersedes !== undefined ? { supersedes: manifest.supersedes } : {}),
+    };
+    if (existing) {
+        for (const volatile of ['drift', 'pr', 'design']) {
+            if (existing.meta[volatile] !== undefined)
+                meta[volatile] = existing.meta[volatile];
+        }
+    }
+    violations.push(...validateDoc(meta, body));
+    const depends = Array.isArray(meta.depends) ? meta.depends : [];
+    depends.forEach((dep, i) => {
+        if (dep !== id && !findById(canon, dep))
+            violations.push(v(`depends[${i}]`, 'unknown-dep', dep, 'an existing doc id'));
+    });
+    const cycle = findCycle(canon, { id, depends });
+    if (cycle)
+        violations.push(v('depends', 'cycle', cycle.join(' -> '), 'an acyclic depends graph'));
+    if (typeof manifest.supersedes === 'string' && !findById(canon, manifest.supersedes) && !streamExists(root, manifest.supersedes)) {
+        violations.push(v('supersedes', 'unknown-ref', manifest.supersedes, 'an existing spec id or frozen journal stream'));
+    }
+    return { meta, covers, violations, warnings: [] };
+}
+export async function run(ctx, argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        options: { effort: { type: 'string' }, meta: { type: 'string' }, body: { type: 'string' } },
+        allowPositionals: true,
+    });
+    const id = positionals[0];
+    const missing = [];
+    if (!id || !ID_RE.test(id))
+        missing.push(v('id', 'id-charset', String(id ?? 'absent'), 'witness write <id> with [a-z0-9-]+'));
+    for (const flag of ['effort', 'meta', 'body']) {
+        if (!values[flag])
+            missing.push(v(`--${flag}`, 'required', 'absent', `--${flag} <value>`));
+    }
+    if (missing.length) {
+        renderRefusal(missing).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const rootRes = primaryRoot(ctx.cwd);
+    if (!rootRes.ok) {
+        renderRefusal(rootRes.violations).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const root = rootRes.value;
+    const blocked = guardTxn(ctx, root);
+    if (blocked !== undefined)
+        return blocked;
+    const cfg = loadConfig(root);
+    if (!cfg.ok) {
+        renderRefusal(cfg.violations).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    if (cfg.value.warning)
+        ctx.err(`warn: ${cfg.value.warning}`);
+    const effort = values.effort;
+    if (!streamExists(root, effort)) {
+        renderRefusal([v('--effort', 'unknown-effort', effort, 'an effort born by witness recap')]).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const recap = latestRecap(root, effort);
+    if (!recap) {
+        renderRefusal([v('--effort', 'unknown-effort', `${effort} has no recap entry`, 'an effort born by witness recap')]).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    let manifest;
+    let body;
+    try {
+        // resolve, not join: absolute --meta/--body paths (scratch dirs) must be honored as-is
+        manifest = JSON.parse(readFileSync(resolve(ctx.cwd, values.meta), 'utf8'));
+        body = readFileSync(resolve(ctx.cwd, values.body), 'utf8');
+    }
+    catch (e) {
+        renderRefusal([v('--meta/--body', 'input-unreadable', String(e.message).slice(0, 120), 'readable manifest JSON and body file')]).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const lock = acquireLock(root);
+    if (!lock.ok) {
+        renderRefusal(lock.violations).forEach(ctx.err);
+        return EXIT.BLOCKED;
+    }
+    try {
+        const canon = loadCanon(root);
+        const existing = findById(canon, id);
+        const refuseWrite = (viol) => {
+            journalRefusal(ctx, root, effort, id, viol);
+            renderRefusal(viol).forEach(ctx.err);
+            return EXIT.REFUSED;
+        };
+        const built = manifest.type === 'plan'
+            ? buildPlanMeta(root, id, manifest, recap, canon, existing, body)
+            : buildSpecMeta(root, id, manifest, recap, canon, existing, body);
+        if (existing && existing.meta.type !== manifest.type) {
+            built.violations.push(v('type', 'type-immutable', `${id} is a ${existing.meta.type}`, 'amendments keep the original type'));
+        }
+        if (built.violations.length)
+            return refuseWrite(built.violations);
+        built.warnings.forEach((w) => ctx.err(`warn: ${w}`));
+        // supersedes effects (re-slice): resolved after validation, before the txn, so a
+        // refusal here never touches disk. Applies only to specs — buildPlanMeta never sets
+        // meta.supersedes, so this is a no-op for plan writes.
+        const supersedes = built.meta.supersedes === undefined ? undefined : String(built.meta.supersedes);
+        let reslice;
+        if (supersedes !== undefined) {
+            if (supersedes === id) {
+                return refuseWrite([v('supersedes', 'self-supersede', id, 'a different spec')]);
+            }
+            if ((manifest.depends ?? []).includes(supersedes)) {
+                return refuseWrite([v('depends', 'supersedes-in-depends', supersedes, 'a re-slice must not depend on the doc it deletes')]);
+            }
+            const target = findById(canon, supersedes);
+            if (!target) {
+                const alreadyTerminal = readStream(root, supersedes)
+                    .some((e) => e.t === 'status' && e.to === 'superseded');
+                if (!alreadyTerminal) {
+                    return refuseWrite([v('supersedes', 'unknown-supersedes', supersedes, 'an existing spec (or one already journal-terminal)')]);
+                }
+            }
+            else {
+                const dependents = canon.docs
+                    .filter((d) => String(d.meta.id) !== id)
+                    .filter((d) => (d.meta.depends ?? []).includes(supersedes))
+                    .map((d) => String(d.meta.id));
+                if (dependents.length > 0) {
+                    return refuseWrite([v('supersedes', 'dangling-depends', dependents.join(' '), 'dependents rewritten first — the re-slice rewrites them before deleting')]);
+                }
+                const entry = {
+                    v: 1, t: 'status', artifact: supersedes, from: String(target.meta.status),
+                    to: 'superseded', cause: 'supersede', by: id,
+                };
+                reslice = { doc: target, entry, line: entryLine(entry) };
+            }
+        }
+        const rel = existing ? existing.rel : `${manifest.type === 'plan' ? cfg.value.paths.plans : cfg.value.paths.specs}/${id}.md`;
+        const stream = journalRel(effort);
+        const unrelated = dirtyStatePaths(root).filter((p) => p !== rel && p !== stream);
+        if (unrelated.length) {
+            renderRefusal(unrelated.map((p) => v(p, 'unrelated-dirty', 'uncommitted change on a state path', 'revert or re-apply via witness write, then re-run'))).forEach(ctx.err);
+            return EXIT.REFUSED;
+        }
+        // serializeDoc normalizes body whitespace (leading/trailing) on write, and splitDoc
+        // reflects that on every future read — hashing the raw pre-write body here would
+        // make this entry's sha permanently disagree with canonicalSha(reReadDoc), even
+        // when nothing was ever amended. Round-trip through the same normalization so the
+        // journaled sha matches what every later loadCanon()/readDoc() will compute.
+        const roundTripped = splitDoc(serializeDoc({ meta: built.meta, body }));
+        const sha = roundTripped.ok
+            ? canonicalSha(roundTripped.value.meta, roundTripped.value.body)
+            : canonicalSha(built.meta, body);
+        const entry = {
+            t: 'write', effort, artifact: id, sha,
+            ...(manifest.type === 'plan' ? {} : { covers: built.covers }),
+            ...(existing === undefined ? { created: true } : {}),
+            ...(supersedes !== undefined ? { supersedes } : {}),
+        };
+        const line = JSON.stringify({ v: 1, ...entry });
+        const supersededDesignRel = reslice ? designRel(cfg.value.paths, reslice.entry.artifact) : undefined;
+        const files = [rel, stream,
+            ...(reslice ? [reslice.doc.rel, journalRel(reslice.entry.artifact)] : []),
+            ...(supersededDesignRel && existsSync(join(root, supersededDesignRel)) ? [supersededDesignRel] : []),
+        ];
+        const res = withTxn(root, {
+            op: `write(${id})`, files, journal: { stream: effort, line },
+            ...(reslice ? { journalMulti: [{ stream: reslice.entry.artifact, line: reslice.line }] } : {}),
+        }, () => {
+            writeDoc(join(root, rel), { meta: built.meta, body });
+            crashPoint(ctx.env, 'artifact-write');
+            if (reslice) {
+                unlinkSync(join(root, reslice.doc.rel));
+                const supersededDesign = designRel(cfg.value.paths, reslice.entry.artifact);
+                if (existsSync(join(root, supersededDesign))) {
+                    unlinkSync(join(root, supersededDesign));
+                }
+                appendEntry(root, reslice.entry.artifact, reslice.entry);
+                crashPoint(ctx.env, 'reslice-commit');
+            }
+            appendEntry(root, effort, entry);
+            crashPoint(ctx.env, 'journal-append');
+            return stateCommit(root, files, `write(${id}): ${existing ? 'amend' : 'create'} ${manifest.type}`);
+        });
+        if (!res.ok) {
+            renderRefusal(res.violations).forEach(ctx.err);
+            return EXIT.REFUSED;
+        }
+        ctx.out(kv('written', id));
+        ctx.out(kv('path', rel));
+        ctx.out(kv('sha', short(sha)));
+        ctx.out(kv('status', 'draft'));
+        ctx.out('next: witness check · witness index');
+        return EXIT.OK;
+    }
+    finally {
+        lock.value();
+    }
+}
+function journalRefusal(ctx, root, effort, artifact, violations) {
+    const entry = {
+        t: 'write-refused', effort, artifact,
+        rules: violations.map(({ field, rule }) => ({ field, rule })),
+    };
+    const line = JSON.stringify({ v: 1, ...entry });
+    const stream = journalRel(effort);
+    const res = withTxn(root, { op: `write-refused(${artifact})`, files: [stream], journal: { stream: effort, line } }, () => {
+        appendEntry(root, effort, entry);
+        return stateCommit(root, [stream], `write-refused(${artifact})`);
+    });
+    if (!res.ok)
+        ctx.err('warn: refusal could not be journaled (state paths dirty)');
+}
+function buildPlanMeta(root, id, manifest, recap, canon, existing, body) {
+    const violations = [];
+    const warnings = [];
+    const parentId = typeof manifest.parent === 'string' ? manifest.parent : '';
+    const parent = parentId ? findById(canon, parentId) : undefined;
+    if (!parent) {
+        violations.push(v('parent', 'unknown-parent', parentId || 'absent', 'an existing spec id (or principles for chores)'));
+        return { meta: {}, covers: [], violations, warnings };
+    }
+    if (parent.meta.type === 'principles' && recap.class !== 'chore') {
+        violations.push(v('parent', 'class-mismatch', `principles parent on a ${recap.class} effort`, 'feature and fix plans derive from a spec'));
+    }
+    else if (parent.meta.type !== 'spec' && parent.meta.type !== 'principles') {
+        violations.push(v('parent', 'kind', String(parent.meta.type), 'a spec (or principles for chores)'));
+    }
+    if (parent.meta.status === 'draft') {
+        violations.push(v('parent', 'parent-not-approved', String(parentId), 'a parent stamped approved by its gate — run: witness gate decompose --effort <slug>'));
+    }
+    const computed = canonicalSha(parent.meta, parent.body);
+    const supplied = manifest['derives-from'];
+    if (typeof supplied === 'string' && supplied !== computed) {
+        violations.push(v('derives-from', 'stale-derivation', short(supplied), `current parent content is ${short(computed)} — re-derive from witness diff ${parentId}`));
+    }
+    const parentUi = parent.meta.ui === true;
+    const suppliedDesignFrom = manifest['design-from'];
+    if (!parentUi && suppliedDesignFrom !== undefined) {
+        violations.push(v('design-from', 'not-ui-parent', String(parentId), 'omit design-from — the parent spec is not ui-flagged'));
+    }
+    let designFrom;
+    if (parentUi) {
+        const stamp = designStamp(parent);
+        if (!stamp || designPending(root, parent)) {
+            violations.push(v('design-from', 'design-not-approved', String(parentId), `an approved, current design — run: witness design ${parentId} --file <html> && witness gate design ${parentId}`));
+        }
+        else if (suppliedDesignFrom !== stamp.sha) {
+            violations.push(v('design-from', 'stale-design', short(String(suppliedDesignFrom ?? 'absent')), `the parent's current design sha ${short(stamp.sha)} — pin it in the manifest`));
+        }
+        else {
+            designFrom = stamp.sha;
+        }
+    }
+    const meta = {
+        id,
+        type: 'plan',
+        status: 'draft',
+        parent: parentId,
+        'derives-from': computed,
+        ...(designFrom !== undefined ? { 'design-from': designFrom } : {}),
+        depends: manifest.depends ?? [],
+        needs: manifest.needs ?? [],
+        steps: manifest.steps,
+    };
+    if (existing?.meta.pr !== undefined)
+        meta.pr = existing.meta.pr;
+    violations.push(...validateDoc(meta, body));
+    const parentCriteria = Array.isArray(parent.meta.criteria)
+        ? parent.meta.criteria
+        : [];
+    const currentIds = new Set(parentCriteria.map((c) => String(c.id)));
+    const steps = Array.isArray(manifest.steps) ? manifest.steps : [];
+    const referenced = new Set();
+    steps.forEach((s, i) => {
+        const refs = Array.isArray(s.criteria) ? s.criteria : [];
+        refs.forEach((ref, j) => {
+            if (!currentIds.has(ref)) {
+                violations.push(v(`steps[${i}].criteria[${j}]`, 'unknown-criterion', ref, `a criterion id on ${parentId}: ${[...currentIds].join(' ') || '(none)'}`));
+            }
+            referenced.add(ref);
+        });
+    });
+    const delta = deltaCriteriaIds(root, canon, parent, id);
+    const uncovered = [...delta].filter((c) => !referenced.has(c));
+    if (uncovered.length) {
+        violations.push(v('steps', 'criteria-uncovered', uncovered.join('+'), 'every delta criterion realized by >=1 step'));
+    }
+    const depends = Array.isArray(meta.depends) ? meta.depends : [];
+    depends.forEach((dep, i) => {
+        if (dep !== id && !findById(canon, dep))
+            violations.push(v(`depends[${i}]`, 'unknown-dep', dep, 'an existing doc id'));
+    });
+    const cycle = findCycle(canon, { id, depends });
+    if (cycle)
+        violations.push(v('depends', 'cycle', cycle.join(' -> '), 'an acyclic depends graph'));
+    return { meta, covers: [], violations, warnings };
+}
+function deltaCriteriaIds(root, canon, parent, excludePlanId) {
+    const current = Array.isArray(parent.meta.criteria)
+        ? parent.meta.criteria
+        : [];
+    const all = new Set(current.map((c) => String(c.id)));
+    const base = baseForSpec(root, canon, String(parent.meta.id), excludePlanId);
+    if (base.kind === 'empty')
+        return all;
+    const baseDoc = contentAtSha(root, parent.rel, base.sha);
+    if (!baseDoc)
+        return all;
+    const baseById = new Map((Array.isArray(baseDoc.meta.criteria) ? baseDoc.meta.criteria : [])
+        .map((c) => [String(c.id), canonicalJson(c)]));
+    return new Set(current.filter((c) => baseById.get(String(c.id)) !== canonicalJson(c)).map((c) => String(c.id)));
+}

package/dist/verdict.js

@@ -0,0 +1,257 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { isAbsolute, join, normalize } from 'node:path';
+import { ok, refuse, v } from './refusal.js';
+const isOmission = (a) => typeof a === 'object' && a !== null &&
+    a.kind === 'omission' &&
+    typeof a.scope === 'string';
+const isAnchor = (a) => (typeof a === 'string' && a.trim() !== '') || isOmission(a);
+export function parseVerdict(raw) {
+    const violations = [];
+    const obj = raw;
+    if (typeof raw !== 'object' || raw === null) {
+        return refuse([v('verdict', 'not-object', typeof raw, 'a JSON object')]);
+    }
+    if (!Array.isArray(obj.coverage)) {
+        violations.push(v('coverage', 'coverage-missing', String(obj.coverage), 'required [{anchor, note}] — a clean verdict must prove reading'));
+    }
+    else {
+        obj.coverage.forEach((c, i) => {
+            const item = c;
+            if (!isAnchor(item?.anchor))
+                violations.push(v(`coverage[${i}].anchor`, 'anchor-shape', JSON.stringify(item?.anchor), 'a heading path, file[#symbol], or {kind: "omission", scope}'));
+            if (typeof item?.note !== 'string')
+                violations.push(v(`coverage[${i}].note`, 'note-missing', String(item?.note), 'a short note per coverage anchor'));
+        });
+    }
+    if (!Array.isArray(obj.findings)) {
+        violations.push(v('findings', 'findings-missing', String(obj.findings), 'an array (empty means clean)'));
+    }
+    else {
+        obj.findings.forEach((f, i) => {
+            const item = f;
+            if (typeof item?.blocking !== 'boolean')
+                violations.push(v(`findings[${i}].blocking`, 'blocking-shape', String(item?.blocking), 'true | false — the one calibrated bit'));
+            if (!isAnchor(item?.anchor))
+                violations.push(v(`findings[${i}].anchor`, 'anchor-shape', JSON.stringify(item?.anchor), 'a heading path, file[#symbol], or {kind: "omission", scope}'));
+            if (typeof item?.claim !== 'string' || item.claim.trim() === '')
+                violations.push(v(`findings[${i}].claim`, 'claim-missing', String(item?.claim), 'a one-sentence claim'));
+            const cp = item.contradicts_pin;
+            if (cp !== undefined && (!Number.isInteger(cp) || cp < 1)) {
+                violations.push(v(`findings[${i}].contradicts_pin`, 'contradicts-pin-shape', String(cp), 'a pin ordinal (integer ≥1), or omit'));
+            }
+        });
+    }
+    if (violations.length > 0)
+        return refuse(violations);
+    return ok({ coverage: obj.coverage, findings: obj.findings });
+}
+const HEADING_RE = /^#{1,6}\s+.*$/;
+const collapse = (s) => s.trim().replace(/\s+/g, ' ');
+function headingLines(body) {
+    return body.split('\n').filter((l) => HEADING_RE.test(l)).map(collapse);
+}
+// every line is a verbatim-copyable anchor that resolveAnchor accepts — the menu
+// exists because reviewers paraphrasing headings was the top malformed-verdict cause
+export function anchorMenu(reviewed) {
+    if (reviewed.kind === 'design') {
+        const lines = [
+            ...reviewed.artifact.ids.map((id) => `design#${id}`),
+            reviewed.spec.id,
+            ...headingLines(reviewed.spec.body).map((h) => `${reviewed.spec.id} > ${h}`),
+        ];
+        return [
+            '## Valid anchors',
+            '',
+            'Copy one line VERBATIM per coverage/finding item. `design#<id>` names an element in the design artifact; `' +
+                reviewed.spec.id + ' > ## Heading` names a section of the parent spec. Anything else rejects the whole verdict.',
+            '',
+            ...lines.map((l) => `- ${l}`),
+        ].join('\n');
+    }
+    if (reviewed.kind === 'screens') {
+        return [
+            '## Valid anchors',
+            '',
+            'Every capture below is a resolvable anchor — copy one VERBATIM (a bare filename) per coverage/finding item. Anything else rejects the whole verdict.',
+            '',
+            ...reviewed.captures.map((c) => `- ${c.name}`),
+        ].join('\n');
+    }
+    if (reviewed.kind !== 'docs')
+        return '';
+    const lines = reviewed.docs.flatMap((d) => [d.id, ...headingLines(d.body).map((h) => `${d.id} > ${h}`)]);
+    return [
+        '## Valid anchors',
+        '',
+        'Every line below is a resolvable anchor — copy one VERBATIM per coverage/finding item. Deeper ` > ` chains of one doc\'s headings in document order also resolve; anything else rejects the whole verdict.',
+        '',
+        ...lines.map((l) => `- ${l}`),
+    ].join('\n');
+}
+function resolveDocPath(segments, body) {
+    const heads = headingLines(body);
+    let cursor = -1;
+    for (const seg of segments) {
+        const want = collapse(seg);
+        const idx = heads.findIndex((h, i) => i > cursor && h === want);
+        if (idx === -1)
+            return `no heading "${seg}" (in order) in the reviewed doc`;
+        cursor = idx;
+    }
+    return undefined;
+}
+function safeRel(rel) {
+    return !isAbsolute(rel) && !normalize(rel).split(/[\\/]/).includes('..');
+}
+function resolveCodeAnchor(anchor, root) {
+    if (/[:#]L?\d+$/.test(anchor))
+        return 'line numbers refused — they drift across revisions; use file#symbol';
+    const [file = '', symbol] = anchor.split('#', 2);
+    if (!safeRel(file))
+        return `path escapes the reviewed tree: ${file}`;
+    const abs = join(root, file);
+    if (!existsSync(abs) || !statSync(abs).isFile())
+        return `no file ${file} in the reviewed tree`;
+    if (symbol !== undefined) {
+        const re = new RegExp(`\\b${symbol.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`);
+        if (!re.test(readFileSync(abs, 'utf8')))
+            return `symbol "${symbol}" not found in ${file}`;
+    }
+    return undefined;
+}
+function resolveDesignAnchor(anchor, reviewed) {
+    const asElement = (scope) => scope.startsWith('design#') && reviewed.artifact.ids.includes(scope.slice('design#'.length));
+    const asSpec = (scope) => {
+        const segments = scope.split(' > ');
+        if (segments[0] === reviewed.spec.id)
+            return resolveDocPath(segments.slice(1), reviewed.spec.body);
+        if (segments[0].startsWith('#'))
+            return resolveDocPath(segments, reviewed.spec.body);
+        return `no reviewed anchor "${scope}" (want design#<id> or ${reviewed.spec.id} > ## Heading)`;
+    };
+    if (isOmission(anchor)) {
+        const scope = anchor.scope;
+        if (scope === '.' || asElement(scope) || asSpec(scope) === undefined)
+            return undefined;
+        return `omission scope "${scope}" resolves to no element id or spec heading`;
+    }
+    if (anchor.startsWith('design#')) {
+        return reviewed.artifact.ids.includes(anchor.slice('design#'.length))
+            ? undefined
+            : `no element id "${anchor.slice('design#'.length)}" in the design artifact`;
+    }
+    return asSpec(anchor);
+}
+export function resolveAnchor(anchor, reviewed) {
+    if (reviewed.kind === 'design')
+        return resolveDesignAnchor(anchor, reviewed);
+    if (reviewed.kind === 'screens') {
+        const target = isOmission(anchor) ? anchor.scope : anchor;
+        if (reviewed.captures.some((c) => c.name === target))
+            return undefined;
+        return `${isOmission(anchor) ? 'omission scope' : 'anchor'} "${target}" names no reviewed capture`;
+    }
+    if (isOmission(anchor)) {
+        const scope = anchor.scope;
+        if (reviewed.kind === 'docs') {
+            if (reviewed.docs.some((d) => d.id === scope))
+                return undefined;
+            const seg = scope.split(' > ');
+            const scoped = reviewed.docs.find((d) => d.id === seg[0]);
+            const target = scoped ? seg.slice(1) : seg;
+            const pool = scoped ? [scoped] : reviewed.docs;
+            return pool.some((d) => resolveDocPath(target, d.body) === undefined)
+                ? undefined
+                : `omission scope "${scope}" resolves to no reviewed doc or heading`;
+        }
+        if (scope === '.')
+            return undefined;
+        if (!safeRel(scope))
+            return `omission scope escapes the reviewed tree: ${scope}`;
+        return existsSync(join(reviewed.root, scope))
+            ? undefined
+            : `omission scope "${scope}" is no file or directory in the reviewed tree`;
+    }
+    if (reviewed.kind === 'tree')
+        return resolveCodeAnchor(anchor, reviewed.root);
+    const segments = anchor.split(' > ');
+    if (!segments[0].startsWith('#')) {
+        const doc = reviewed.docs.find((d) => d.id === segments[0]);
+        if (!doc)
+            return `no reviewed doc "${segments[0]}"`;
+        return resolveDocPath(segments.slice(1), doc.body);
+    }
+    return reviewed.docs.some((d) => resolveDocPath(segments, d.body) === undefined)
+        ? undefined
+        : `no heading path "${anchor}" in any reviewed doc`;
+}
+export function verdictViolations(verdict, reviewed) {
+    const violations = [];
+    const anchorText = (a) => (typeof a === 'string' ? a : JSON.stringify(a));
+    verdict.findings.forEach((f, i) => {
+        const why = resolveAnchor(f.anchor, reviewed);
+        if (why) {
+            const rule = why.startsWith('line numbers') ? 'line-numbers-refused' : 'anchor-unresolvable';
+            violations.push(v(`findings[${i}].anchor`, rule, anchorText(f.anchor), why));
+        }
+    });
+    verdict.coverage.forEach((c, i) => {
+        const why = resolveAnchor(c.anchor, reviewed);
+        if (why)
+            violations.push(v(`coverage[${i}].anchor`, 'anchor-unresolvable', anchorText(c.anchor), why));
+    });
+    if (reviewed.kind === 'design') {
+        const strings = verdict.coverage.filter((c) => typeof c.anchor === 'string');
+        const artifactRead = strings.some((c) => c.anchor.startsWith('design#') && reviewed.artifact.ids.includes(c.anchor.slice('design#'.length)));
+        const specRead = strings.some((c) => resolveDesignAnchor(c.anchor, reviewed) === undefined && !c.anchor.startsWith('design#'));
+        if (!artifactRead)
+            violations.push(v('coverage', 'coverage-minimum', 'no design#<id> coverage anchor', '>=1 coverage anchor naming a design artifact element (proof the look was read)'));
+        if (!specRead)
+            violations.push(v('coverage', 'coverage-minimum', 'no parent-spec coverage anchor', '>=1 coverage anchor naming a parent-spec heading (proof the spec was read)'));
+        return violations;
+    }
+    if (reviewed.kind === 'docs') {
+        const covered = new Set();
+        verdict.coverage.forEach((c, i) => {
+            if (typeof c.anchor !== 'string')
+                return;
+            const [first = ''] = c.anchor.split(' > ');
+            if (!first.startsWith('#')) {
+                covered.add(first);
+                return;
+            }
+            if (reviewed.docs.length > 1) {
+                violations.push(v(`coverage[${i}].anchor`, 'coverage-unscoped', c.anchor, 'multi-doc reviews need doc-scoped coverage anchors: "<doc-id> > ## Heading"'));
+            }
+            else if (reviewed.docs[0])
+                covered.add(reviewed.docs[0].id);
+        });
+        for (const d of reviewed.docs) {
+            if (!covered.has(d.id)) {
+                violations.push(v('coverage', 'coverage-minimum', `docs covered: ${[...covered].sort().join(' ') || '(none)'}`, `≥ 1 coverage anchor per reviewed doc — missing ${d.id}`));
+            }
+        }
+    }
+    else if (reviewed.kind === 'screens') {
+        const covered = new Set(verdict.coverage
+            .filter((c) => typeof c.anchor === 'string')
+            .map((c) => c.anchor)
+            .filter((a) => reviewed.captures.some((c) => c.name === a)));
+        for (const cap of reviewed.captures) {
+            if (!covered.has(cap.name)) {
+                violations.push(v('coverage', 'coverage-minimum', `captures covered: ${[...covered].sort().join(' ') || '(none)'}`, `≥ 1 coverage anchor per reviewed capture — missing ${cap.name}`));
+            }
+        }
+    }
+    else {
+        const distinct = new Set(verdict.coverage
+            .filter((c) => typeof c.anchor === 'string')
+            .map((c) => c.anchor.split('#')[0] ?? '')
+            .filter((f) => reviewed.files.includes(f)));
+        const want = Math.min(5, reviewed.files.length);
+        if (distinct.size < want) {
+            violations.push(v('coverage', 'coverage-minimum', `${distinct.size} distinct changed files covered`, `≥ ${want} coverage anchors naming distinct changed files`));
+        }
+    }
+    return violations;
+}