@popovych.co/witness 0.4.0

package/dist/drift.js

@@ -0,0 +1,280 @@
+import { randomBytes } from 'node:crypto';
+import { join } from 'node:path';
+import { EXIT } from './cli.js';
+import { loadConfig } from './config.js';
+import { runCriteria } from './criteria.js';
+import { serializeDoc, writeDoc } from './fm.js';
+import { acquireLock } from './lock.js';
+import { appendEntry, entryLine, journalRel, readStream } from './journal.js';
+import { primaryRoot, stateCommit } from './gitio.js';
+import { renderRefusal, v, ok } from './refusal.js';
+import { resolveHarness } from './harness.js';
+import { invokeReviewer, parseVerdictText, resolvePrompt } from './reviewer.js';
+import { runFullSuite, runnerConfig } from './runner.js';
+import { findById, loadCanon } from './scan.js';
+import { canonicalSha } from './sha.js';
+import { kv, rows } from './toon.js';
+import { crashPoint, guardTxn, withTxn } from './txn.js';
+import { parseVerdict, verdictViolations } from './verdict.js';
+export const newRunId = () => `r-${randomBytes(4).toString('hex')}`;
+export function driftEntry(run, runId) {
+    return {
+        t: 'drift-check',
+        run_id: runId,
+        artifact: run.spec,
+        artifact_sha: run.sha,
+        ok: run.ok,
+        tags: run.tagCount,
+        criteria: run.criteria.map((c) => ({ id: c.id, kind: c.kind, ok: c.ok, detail: c.detail })),
+    };
+}
+export function trailingFails(entries) {
+    const checks = entries.filter((e) => e.t === 'drift-check');
+    let n = 0;
+    for (let i = checks.length - 1; i >= 0 && checks[i]?.ok === false; i--)
+        n++;
+    return n;
+}
+export const liveSpecs = (canon) => canon.docs.filter((d) => d.meta.type === 'spec' && d.meta.status === 'live');
+const today = () => new Date().toISOString().slice(0, 10);
+export function stampDrift(root, doc, sha) {
+    writeDoc(join(root, doc.rel), { meta: { ...doc.meta, drift: { sha, at: today() } }, body: doc.body });
+}
+export function clearDrift(root, doc) {
+    const meta = { ...doc.meta };
+    delete meta.drift;
+    writeDoc(join(root, doc.rel), { meta, body: doc.body });
+}
+export function flapScore(entries) {
+    const checks = entries.filter((e) => e.t === 'drift-check').slice(-10);
+    let flips = 0;
+    for (let i = 1; i < checks.length; i++) {
+        if (checks[i]?.ok !== checks[i - 1]?.ok)
+            flips++;
+    }
+    return flips;
+}
+export function reconcileRows(root, canon) {
+    const out = [];
+    for (const doc of liveSpecs(canon)) {
+        const id = String(doc.meta.id);
+        const entries = readStream(root, id);
+        const flag = doc.meta.drift;
+        if (flag)
+            out.push({ spec: id, why: 'drift', detail: `${flag.sha.slice(0, 7)} since ${flag.at} — fix the code or amend the spec` });
+        else if (trailingFails(entries) === 1)
+            out.push({ spec: id, why: 'unconfirmed', detail: 'seen red once — one more red stamps drift' });
+        const flips = flapScore(entries);
+        if (flips >= 3)
+            out.push({ spec: id, why: 'flapping', detail: `${flips} pass/fail flips in the last 10 runs — fix the test or the spec` });
+        const last = entries.at(-1);
+        if (last?.t === 'adopt' && last.unreviewed_amendment === true) {
+            out.push({ spec: id, why: 'unreviewed-amendment', detail: 'prose changed without review — amend properly or accept' });
+        }
+    }
+    return out;
+}
+export async function driftSweep(root, ctx, canon) {
+    const specs = liveSpecs(canon);
+    const cfg = loadConfig(root);
+    if (!cfg.ok)
+        return cfg;
+    const rcRes = runnerConfig(cfg.value);
+    if (!rcRes.ok)
+        return rcRes;
+    let suite;
+    if (rcRes.value.mode === 'full-suite' && specs.length > 0) {
+        const res = await runFullSuite(root, ctx, rcRes.value);
+        if (res.ok)
+            suite = res.value.tests;
+        // a refusal here (untrusted, no reports) falls through: each runCriteria call
+        // re-attempts and reports the same problem as failing criteria — fail-closed either way
+    }
+    const runs = [];
+    for (const doc of specs) {
+        const res = await runCriteria(root, ctx, doc, { suite });
+        if (!res.ok)
+            return res;
+        runs.push(res.value);
+    }
+    return ok(runs);
+}
+export async function deepDrift(root, ctx, canon, specId) {
+    if (ctx.env.CI) {
+        renderRefusal([v('deep', 'deep-in-ci', 'CI env', 'a local run — CI never invokes reviewers or writes state')])
+            .forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const doc = findById(canon, specId);
+    if (!doc || doc.meta.type !== 'spec') {
+        renderRefusal([v('spec', 'unknown-spec', specId, 'a live spec id')]).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const lane = await runCriteria(root, ctx, doc, {});
+    const lensR = resolvePrompt('drift-reviewer');
+    if (!lensR.ok) {
+        renderRefusal(lensR.violations).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    // Decision 88: the deep lane is a reviewer lane — it runs on the RESOLVED harness,
+    // like every other. A silent claude fallback here would swap the reviewer identity
+    // for pure-pi users on the one check that judges live specs.
+    const cfgR = loadConfig(root);
+    const hxR = resolveHarness(ctx.env, cfgR.ok ? cfgR.value.raw : {});
+    if (!hxR.ok) {
+        renderRefusal(hxR.violations).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const prompt = `${lensR.value.contents}\n\n## Reviewed content\n\n### Spec: ${specId}\n${serializeDoc({ meta: doc.meta, body: doc.body })}\n\n(Deterministic lane: ${lane.ok ? lane.value.criteria.map((c) => `${c.id}:${c.ok ? 'ok' : 'fail'}`).join(' · ') : 'unrunnable'})\n`;
+    const invoked = invokeReviewer(ctx, hxR.value.harness, { cwd: root, prompt });
+    if (!invoked.ok) {
+        renderRefusal(invoked.violations).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const rawR = parseVerdictText(invoked.value.text);
+    const parsed = rawR.ok ? parseVerdict(rawR.value) : rawR;
+    const violations = parsed.ok
+        ? verdictViolations(parsed.value, { kind: 'tree', root, files: [] })
+        : parsed.violations;
+    const entry = {
+        v: 1, t: 'drift-check', run_id: newRunId(), artifact: specId,
+        artifact_sha: lane.ok ? lane.value.sha : canonicalSha(doc.meta, doc.body),
+        ok: lane.ok && lane.value.ok, tags: lane.ok ? lane.value.tagCount : 0,
+        criteria: lane.ok ? lane.value.criteria.map((c) => ({ id: c.id, kind: c.kind, ok: c.ok, detail: c.detail })) : [],
+        deep: true,
+        ...(violations.length === 0 && parsed.ok ? { verdict: parsed.value } : { malformed: violations }),
+    };
+    const lockR = acquireLock(root);
+    if (!lockR.ok) {
+        renderRefusal(lockR.violations).forEach(ctx.err);
+        return EXIT.BLOCKED;
+    }
+    try {
+        const txn = withTxn(root, {
+            op: 'drift-deep', files: [journalRel(specId)],
+            journalMulti: [{ stream: specId, line: entryLine(entry) }],
+        }, () => {
+            appendEntry(root, specId, entry);
+            crashPoint(ctx.env, 'drift-journal');
+            return stateCommit(root, [journalRel(specId)], `drift-deep(${specId})`);
+        });
+        if (!txn.ok) {
+            renderRefusal(txn.violations).forEach(ctx.err);
+            return EXIT.REFUSED;
+        }
+    }
+    finally {
+        lockR.value();
+    }
+    const blocking = parsed.ok && violations.length === 0
+        ? parsed.value.findings.filter((f) => f.blocking).length : 1;
+    return (lane.ok && lane.value.ok && blocking === 0) ? EXIT.OK : EXIT.FINDINGS;
+}
+export async function runDrift(ctx, argv) {
+    if (argv.includes('--deep')) {
+        const specId = argv.find((a) => !a.startsWith('--'));
+        const rootRes0 = primaryRoot(ctx.cwd);
+        if (!rootRes0.ok) {
+            renderRefusal(rootRes0.violations).forEach(ctx.err);
+            return EXIT.REFUSED;
+        }
+        if (!specId) {
+            renderRefusal([v('spec-id', 'required', 'absent', 'witness check --drift --deep <spec-id>')]).forEach(ctx.err);
+            return EXIT.REFUSED;
+        }
+        if (argv.includes('--ci')) {
+            renderRefusal([v('deep', 'deep-in-ci', '--ci', 'a local run — CI never invokes reviewers or writes state')]).forEach(ctx.err);
+            return EXIT.REFUSED;
+        }
+        return deepDrift(rootRes0.value, ctx, loadCanon(rootRes0.value), specId);
+    }
+    const rootRes = primaryRoot(ctx.cwd);
+    if (!rootRes.ok) {
+        renderRefusal(rootRes.violations).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const root = rootRes.value;
+    const readonly = argv.includes('--ci') || Boolean(ctx.env.CI);
+    if (!readonly) {
+        const blocked = guardTxn(ctx, root);
+        if (blocked !== undefined)
+            return blocked;
+    }
+    const canon = loadCanon(root);
+    const sweep = await driftSweep(root, ctx, canon);
+    if (!sweep.ok) {
+        renderRefusal(sweep.violations).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const runs = sweep.value;
+    const failing = runs.filter((r) => !r.ok);
+    if (runs.length) {
+        rows('drift', ['spec', 'ok', 'tags', 'detail'], runs.map((r) => {
+            const doc = findById(canon, r.spec);
+            const unconfirmed = !r.ok && doc?.meta.drift === undefined && trailingFails(readStream(root, r.spec)) === 0;
+            return {
+                spec: r.spec, ok: String(r.ok), tags: r.tagCount,
+                detail: unconfirmed
+                    ? 'unconfirmed — seen red once — one more red stamps drift'
+                    : r.criteria.filter((c) => !c.ok).map((c) => `${c.id}: ${c.detail}`).join(' · ') || 'clean',
+            };
+        })).forEach(ctx.out);
+    }
+    if (readonly) {
+        ctx.out(kv('drift-summary', `${failing.length}/${runs.length} failing · mode read-only`));
+        ctx.out('help: read-only run — the next local check --drift journals and stamps');
+        return failing.length ? EXIT.FINDINGS : EXIT.OK;
+    }
+    const lock = acquireLock(root);
+    if (!lock.ok) {
+        renderRefusal(lock.violations).forEach(ctx.err);
+        return EXIT.BLOCKED;
+    }
+    try {
+        const runId = newRunId();
+        const entries = runs.map((r) => ({ spec: r.spec, entry: driftEntry(r, runId) }));
+        const actions = runs.map((run) => {
+            const doc = findById(canon, run.spec);
+            const flagged = doc?.meta.drift !== undefined;
+            const priorFails = trailingFails(readStream(root, run.spec));
+            return {
+                run, doc,
+                stamp: doc && !run.ok && priorFails >= 1 && !flagged,
+                clear: doc && run.ok && flagged,
+            };
+        });
+        const marker = {
+            op: `drift-check ${runId}`,
+            files: [...new Set([
+                    ...entries.map((e) => journalRel(e.spec)),
+                    ...actions.filter((a) => a.stamp || a.clear).map((a) => a.doc.rel),
+                ])],
+            journalMulti: entries.map((e) => ({ stream: e.spec, line: entryLine(e.entry) })),
+        };
+        const committed = withTxn(root, marker, () => {
+            for (const { spec, entry } of entries)
+                appendEntry(root, spec, entry);
+            for (const a of actions) {
+                if (a.stamp)
+                    stampDrift(root, a.doc, a.run.sha);
+                else if (a.clear)
+                    clearDrift(root, a.doc);
+            }
+            crashPoint(ctx.env, 'drift-journal');
+            return stateCommit(root, marker.files, `drift-check: ${failing.length}/${runs.length} failing`);
+        });
+        if (!committed.ok) {
+            renderRefusal(committed.violations).forEach(ctx.err);
+            return EXIT.REFUSED;
+        }
+        const stamped = actions.filter((a) => a.stamp).length;
+        const cleared = actions.filter((a) => a.clear).length;
+        const suffix = `${stamped ? ` · stamped ${stamped}` : ''}${cleared ? ` · cleared ${cleared}` : ''}`;
+        ctx.out(kv('drift-summary', `${failing.length}/${runs.length} failing · mode local${suffix}`));
+    }
+    finally {
+        lock.ok && lock.value();
+    }
+    ctx.out('help: drift history: witness log <spec-id>');
+    return failing.length ? EXIT.FINDINGS : EXIT.OK;
+}

package/dist/dsl.js

@@ -0,0 +1,68 @@
+import { v } from './refusal.js';
+export const ID_RE = /^[a-z0-9-]+$/;
+export function validateCriteria(raw, specId) {
+    if (!Array.isArray(raw) || raw.length === 0) {
+        return [v('criteria', 'required', Array.isArray(raw) ? 'empty list' : String(raw ?? 'absent'), '>=1 machine-checkable criterion')];
+    }
+    const out = [];
+    const seen = new Set();
+    raw.forEach((c, i) => {
+        const at = `criteria[${i}]`;
+        if (typeof c !== 'object' || c === null) {
+            out.push(v(at, 'shape', String(c), '{id, test|cmd}'));
+            return;
+        }
+        const e = c;
+        if (typeof e.id !== 'string' || !ID_RE.test(e.id)) {
+            out.push(v(`${at}.id`, 'id-charset', String(e.id ?? 'absent'), '[a-z0-9-]+'));
+        }
+        else if (seen.has(e.id)) {
+            out.push(v(`${at}.id`, 'id-unique', e.id, 'unique per spec'));
+        }
+        else {
+            seen.add(e.id);
+        }
+        const hasTest = typeof e.test === 'string';
+        const hasCmd = typeof e.cmd === 'string';
+        if (hasTest === hasCmd) {
+            out.push(v(at, 'kind', hasTest ? 'both test and cmd' : 'neither test nor cmd', 'exactly one of test | cmd'));
+            return;
+        }
+        if (hasTest && e.test !== `@spec:${specId}`) {
+            out.push(v(`${at}.test`, 'tag-format', String(e.test), `@spec:${specId}`));
+        }
+        if (hasCmd && e.cmd === '') {
+            out.push(v(`${at}.cmd`, 'shape', 'empty string', 'non-empty command'));
+        }
+    });
+    return out;
+}
+export function validateNeeds(raw) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw)) {
+        return [v('needs', 'shape', typeof raw, 'list of {env} | {cmd} | {manual, satisfied}')];
+    }
+    const out = [];
+    raw.forEach((n, i) => {
+        const at = `needs[${i}]`;
+        if (typeof n !== 'object' || n === null) {
+            out.push(v(at, 'shape', String(n), '{env} | {cmd} | {manual, satisfied}'));
+            return;
+        }
+        const e = n;
+        const kinds = ['env', 'cmd', 'manual'].filter((k) => e[k] !== undefined);
+        if (kinds.length !== 1) {
+            out.push(v(at, 'kind', kinds.join('+') || 'none', 'exactly one of env | cmd | manual'));
+            return;
+        }
+        const kind = kinds[0];
+        if (typeof e[kind] !== 'string' || e[kind] === '') {
+            out.push(v(`${at}.${kind}`, 'shape', String(e[kind]), 'non-empty string'));
+        }
+        if (kind === 'manual' && typeof e.satisfied !== 'boolean') {
+            out.push(v(`${at}.satisfied`, 'required', String(e.satisfied ?? 'absent'), 'boolean'));
+        }
+    });
+    return out;
+}

package/dist/evidence.js

@@ -0,0 +1,221 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { loadConfig } from './config.js';
+import { entryLine, appendEntry, journalRel, readStream } from './journal.js';
+import { mergeReports, reportFiles } from './junit.js';
+import { extractCanonicalTags, matchesTag } from './matcher.js';
+import { ok, refuse, v } from './refusal.js';
+import { runFiltered, runFullSuite, runnerConfig } from './runner.js';
+import { git, stateCommit, tryGit } from './gitio.js';
+import { withTxn } from './txn.js';
+export function isTestPath(rel) {
+    if (/\.(test|spec)\./.test(rel))
+        return true;
+    return rel.split('/').some((seg) => seg === 'test' || seg === 'tests' || seg === '__tests__');
+}
+export function screensDir(runRoot, planId) {
+    return join(runRoot, '.witness', 'screens', planId);
+}
+export function collectCaptures(runRoot, planId) {
+    const dir = screensDir(runRoot, planId);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((n) => n.endsWith('.png') && statSync(join(dir, n)).isFile())
+        .sort()
+        .map((name) => ({ name, sha: createHash('sha256').update(readFileSync(join(dir, name))).digest('hex') }));
+}
+export function checkoutRoot(cwd) {
+    const res = tryGit(cwd, 'rev-parse', '--show-toplevel');
+    if (!res.ok)
+        return refuse([v('cwd', 'not-a-repo', cwd, 'run inside a git checkout')]);
+    return ok(res.out.trim());
+}
+export async function runSpecTests(runRoot, ctx, parentId, trustRoot) {
+    const cfg = loadConfig(runRoot);
+    if (!cfg.ok)
+        return cfg;
+    const rcRes = runnerConfig(cfg.value);
+    if (!rcRes.ok)
+        return rcRes;
+    const rc = rcRes.value;
+    if (rc.mode === 'filtered') {
+        if (rc.reportGlob !== undefined) {
+            for (const f of reportFiles(runRoot, rc.reportGlob))
+                rmSync(join(runRoot, f));
+        }
+        const run = await runFiltered(runRoot, ctx, rc.template, parentId, trustRoot);
+        if (!run.ok)
+            return run;
+        if (rc.reportGlob === undefined) {
+            const tests = [{ name: `@spec:${parentId}`, ok: run.value.exitZero }];
+            return ok({ runner: 'filtered', tests, allOk: run.value.exitZero });
+        }
+        const merged = mergeReports(runRoot, rc.reportGlob);
+        if (!merged.ok)
+            return merged;
+        const tests = merged.value
+            .filter((t) => matchesTag(t.name, parentId))
+            .map((t) => ({ name: t.name, ok: t.status === 'passed' }));
+        if (tests.length === 0) {
+            return refuse([v('criteria.runner', 'filter-matched-nothing', `0 tests matched @spec:${parentId}`, 'a runner whose filter reaches the tagged tests — check the template forwards the pattern')]);
+        }
+        return ok({ runner: 'filtered', tests, allOk: tests.every((t) => t.ok) });
+    }
+    const suite = await runFullSuite(runRoot, ctx, rc, trustRoot);
+    if (!suite.ok)
+        return suite;
+    const tests = suite.value.tests
+        .filter((t) => matchesTag(t.name, parentId))
+        .map((t) => ({ name: t.name, ok: t.status === 'passed' }));
+    if (tests.length === 0) {
+        return refuse([v('criteria.report', 'filter-matched-nothing', `0 tests matched @spec:${parentId}`, 'tagged tests present in the merged junit reports')]);
+    }
+    return ok({ runner: 'full-suite', tests, allOk: tests.every((t) => t.ok) });
+}
+export function journalEvidence(stateRoot, planId, phase, run, extra = {}) {
+    const entry = { t: 'test-evidence', artifact: planId, phase, runner: run.runner, tests: run.tests, ...extra };
+    const marker = {
+        op: `test-evidence(${planId}): ${phase}`,
+        files: [journalRel(planId)],
+        journalMulti: [{ stream: planId, line: entryLine(entry) }],
+    };
+    return withTxn(stateRoot, marker, () => {
+        appendEntry(stateRoot, planId, entry);
+        return stateCommit(stateRoot, marker.files, marker.op);
+    });
+}
+export async function recordEvidence(runRoot, stateRoot, ctx, planId, parentId, phase, extra = {}) {
+    // latest-cycle by construction: a fresh empty dir per cycle means captures can
+    // only be this run's. Browser tests screenshot iff WITNESS_SCREENS_DIR is set,
+    // so non-UI plans and the gate's own drift lane (which does not set it) write nothing.
+    const dir = screensDir(runRoot, planId);
+    rmSync(dir, { recursive: true, force: true });
+    mkdirSync(dir, { recursive: true });
+    const runCtx = { ...ctx, env: { ...ctx.env, WITNESS_SCREENS_DIR: dir } };
+    const run = await runSpecTests(runRoot, runCtx, parentId, stateRoot);
+    if (!run.ok)
+        return run;
+    const vacuous = phase === 'red' && run.value.allOk ? { vacuous: true } : {};
+    const captures = collectCaptures(runRoot, planId);
+    const capExtra = captures.length ? { captures } : {};
+    const committed = journalEvidence(stateRoot, planId, phase, run.value, { ...extra, ...vacuous, ...capExtra });
+    if (!committed.ok)
+        return committed;
+    return run;
+}
+export function diffBase(runRoot, cfg, override) {
+    if (override) {
+        const res = tryGit(runRoot, 'rev-parse', '--verify', `${override}^{commit}`);
+        if (!res.ok)
+            return refuse([v('--base', 'no-base', override, 'a resolvable commit-ish')]);
+        return ok(res.out.trim());
+    }
+    const ship = (cfg.raw.ship ?? {});
+    const branch = typeof ship.branch === 'string' ? ship.branch : 'main';
+    const res = tryGit(runRoot, 'merge-base', 'HEAD', branch);
+    if (!res.ok)
+        return refuse([v('ship.branch', 'no-base', branch, 'an existing base branch, or pass --base <ref>')]);
+    return ok(res.out.trim());
+}
+export function changedFiles(runRoot, base) {
+    const tracked = git(runRoot, 'diff', '--name-only', base).split('\n').filter(Boolean);
+    const untracked = git(runRoot, 'ls-files', '--others', '--exclude-standard').split('\n').filter(Boolean);
+    return [...new Set([...tracked, ...untracked])].sort();
+}
+const inCommit = (runRoot, ref, rel) => tryGit(runRoot, 'cat-file', '-e', `${ref}:${rel}`).ok;
+export async function verifyRed(runRoot, stateRoot, ctx, planId, parentId, base) {
+    const files = changedFiles(runRoot, base);
+    if (!files.some(isTestPath)) {
+        return refuse([v('diff', 'no-test-changes', `${files.length} changed files, none are tests`, 'a diff that adds or modifies tagged tests')]);
+    }
+    const nonTest = files.filter((f) => !isTestPath(f));
+    const untracked = new Set(git(runRoot, 'ls-files', '--others', '--exclude-standard').split('\n').filter(Boolean));
+    const trackedNonTest = nonTest.filter((f) => !untracked.has(f));
+    let stashed = false;
+    if (nonTest.length) {
+        const before = git(runRoot, 'stash', 'list').split('\n').filter(Boolean).length;
+        git(runRoot, 'stash', 'push', '--include-untracked', '--', ...nonTest);
+        stashed = git(runRoot, 'stash', 'list').split('\n').filter(Boolean).length > before;
+    }
+    let red;
+    try {
+        for (const rel of trackedNonTest) {
+            if (inCommit(runRoot, base, rel))
+                git(runRoot, 'checkout', base, '--', rel);
+            else if (existsSync(join(runRoot, rel)))
+                rmSync(join(runRoot, rel));
+        }
+        red = await recordEvidence(runRoot, stateRoot, ctx, planId, parentId, 'red', { reconstructed: true });
+    }
+    finally {
+        for (const rel of trackedNonTest) {
+            if (inCommit(runRoot, 'HEAD', rel))
+                git(runRoot, 'checkout', 'HEAD', '--', rel);
+        }
+        if (stashed)
+            git(runRoot, 'stash', 'pop');
+    }
+    if (!red.ok)
+        return red;
+    const green = await recordEvidence(runRoot, stateRoot, ctx, planId, parentId, 'green', { reconstructed: true });
+    if (!green.ok)
+        return green;
+    return ok({ redOk: !red.value.allOk, greenOk: green.value.allOk, vacuous: red.value.allOk });
+}
+export function diffTags(runRoot, base) {
+    const tags = new Set();
+    for (const rel of changedFiles(runRoot, base).filter(isTestPath)) {
+        let added;
+        if (inCommit(runRoot, base, rel)) {
+            added = git(runRoot, 'diff', base, '--', rel)
+                .split('\n')
+                .filter((l) => l.startsWith('+') && !l.startsWith('+++'))
+                .join('\n');
+        }
+        else {
+            const abs = join(runRoot, rel);
+            added = existsSync(abs) ? readFileSync(abs, 'utf8') : '';
+        }
+        for (const tag of extractCanonicalTags(added))
+            tags.add(tag);
+    }
+    return [...tags].sort();
+}
+export function evidenceForDiff(runRoot, stateRoot, plan, base) {
+    const planId = String(plan.meta.id);
+    const entries = readStream(stateRoot, planId).filter((e) => e.t === 'test-evidence');
+    const matching = (e, tag) => (Array.isArray(e.tests) ? e.tests : []).filter((t) => matchesTag(t.name, tag));
+    const required = diffTags(runRoot, base).map((tag) => {
+        // latest-cycle semantics: the newest red matching the tag is the verdict on
+        // "was failure observed"; a green only counts if it post-dates that red.
+        // One early vacuous red must not poison the tag forever (append-only journal).
+        let lastRedIdx = -1;
+        let lastGreenIdx = -1;
+        for (let i = 0; i < entries.length; i++) {
+            const e = entries[i];
+            if (matching(e, tag).length === 0)
+                continue;
+            if (e.phase === 'red')
+                lastRedIdx = i;
+            else if (e.phase === 'green')
+                lastGreenIdx = i;
+        }
+        const lastRed = lastRedIdx >= 0 ? entries[lastRedIdx] : undefined;
+        const lastGreen = lastGreenIdx >= 0 ? entries[lastGreenIdx] : undefined;
+        return {
+            tag,
+            red: lastRed !== undefined && matching(lastRed, tag).some((t) => !t.ok),
+            green: lastGreen !== undefined && lastGreenIdx > lastRedIdx &&
+                matching(lastGreen, tag).every((t) => t.ok),
+            vacuous: lastRed?.vacuous === true,
+        };
+    });
+    return {
+        plan: planId,
+        base,
+        required,
+        satisfied: required.every((r) => r.red && r.green && !r.vacuous),
+    };
+}

package/dist/fm.js

@@ -0,0 +1,51 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { ok, refuse, v } from './refusal.js';
+const FIELD_ORDER = [
+    'id', 'type', 'status', 'summary', 'ui', 'parent', 'derives-from', 'design-from',
+    'supersedes', 'depends', 'needs', 'criteria', 'steps', 'pr', 'drift', 'design',
+];
+export function splitDoc(raw) {
+    const m = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+    if (!m) {
+        return refuse([v('frontmatter', 'missing', 'no leading --- block', 'doc starts with ---\\n<yaml>\\n---')]);
+    }
+    let meta;
+    try {
+        meta = parseYaml(m[1]);
+    }
+    catch (e) {
+        return refuse([v('frontmatter', 'yaml-parse', String(e.message).slice(0, 120), 'valid YAML')]);
+    }
+    if (meta === null || typeof meta !== 'object' || Array.isArray(meta)) {
+        return refuse([v('frontmatter', 'shape', Array.isArray(meta) ? 'sequence' : String(meta), 'YAML mapping')]);
+    }
+    return ok({ meta: meta, body: m[2] });
+}
+export function serializeDoc(doc) {
+    const ordered = {};
+    for (const k of FIELD_ORDER)
+        if (doc.meta[k] !== undefined)
+            ordered[k] = doc.meta[k];
+    for (const k of Object.keys(doc.meta))
+        if (!(k in ordered))
+            ordered[k] = doc.meta[k];
+    const yaml = stringifyYaml(ordered, { lineWidth: 0 });
+    const body = doc.body.replace(/^\n+/, '').replace(/\s+$/, '') + '\n';
+    return `---\n${yaml}---\n\n${body}`;
+}
+export function readDoc(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch {
+        return refuse([v(path, 'unreadable', 'missing or unreadable file', 'existing utf8 file')]);
+    }
+    return splitDoc(raw);
+}
+export function writeDoc(path, doc) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, serializeDoc(doc));
+}