@popovych.co/witness 0.4.0

package/dist/gates/implement.js

@@ -0,0 +1,144 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { ok, refuse, v } from '../refusal.js';
+import { serializeDoc } from '../fm.js';
+import { canonicalSha } from '../sha.js';
+import { designRel } from '../design.js';
+import { git } from '../gitio.js';
+import { latestRecap, readStream } from '../journal.js';
+import { findById } from '../scan.js';
+import { changedFiles, diffBase, evidenceForDiff, screensDir } from '../evidence.js';
+import { runCriteria } from '../criteria.js';
+import { effortOf, worktreeTreeSha } from '../reviewed.js';
+import { worktreePath } from '../worktree.js';
+import { registerGate } from '../gate.js';
+export function codePromptBody(wt, base, files, header) {
+    const diff = git(wt, 'diff', base);
+    const untracked = files.filter((f) => {
+        const abs = join(wt, f);
+        if (!existsSync(abs) || !statSync(abs).isFile())
+            return false;
+        return git(wt, 'ls-files', '--', f).trim() === '';
+    });
+    const untrackedBlocks = untracked.map((f) => `#### untracked: ${f}\n${readFileSync(join(wt, f), 'utf8')}`);
+    return [
+        header,
+        `### Changed files\n${files.join('\n')}`,
+        `### Diff vs base ${base.slice(0, 7)}\n${diff}`,
+        ...untrackedBlocks,
+    ].join('\n\n');
+}
+// A UI plan (design-from pinned) must ship screenshots the CLI witnessed: ≥1 capture
+// from the latest green evidence cycle whose on-disk bytes still match the journaled sha.
+// Zero verified → screens-matched-nothing (the D67 filter-matched-nothing pattern) before
+// a reviewer spends tokens; bytes-drift → capture-sha-mismatch (a hand-swapped screenshot
+// is doctorable by exactly the adversary CLI-witnessing exists for).
+function resolveDesignCaptures(stateRoot, wt, planId) {
+    const green = readStream(stateRoot, planId)
+        .filter((e) => e.t === 'test-evidence' && e.phase === 'green');
+    const journaled = (green.at(-1)?.captures) ?? [];
+    const dir = screensDir(wt, planId);
+    const out = [];
+    for (const c of journaled) {
+        const path = join(dir, c.name);
+        if (!existsSync(path) || !statSync(path).isFile())
+            continue; // regenerable — a missing file is just "no capture"
+        const sha = createHash('sha256').update(readFileSync(path)).digest('hex');
+        if (sha !== c.sha) {
+            return refuse([v('screens', 'capture-sha-mismatch', c.name, 'a capture whose bytes match the sha test-evidence witnessed — re-run the browser suite to regenerate; never hand-edit a screenshot')]);
+        }
+        out.push({ name: c.name, path });
+    }
+    if (out.length === 0) {
+        return refuse([v('screens', 'screens-matched-nothing', `0 verified captures for the latest green cycle of ${planId}`, 'a UI plan (design-from pinned) must witness ≥1 screenshot — name captures in the browser test, then re-run: witness test-evidence <plan> --phase green')]);
+    }
+    return ok(out);
+}
+function screensPromptBody(caps) {
+    return [
+        'The reviewed content is the screenshots below. **Read each PNG at its absolute path with the Read tool before judging** — the images are the artifact, not this text.',
+        '',
+        ...caps.map((c) => `- ${c.name} — ${c.path}`),
+    ].join('\n');
+}
+registerGate({
+    gate: 'implement',
+    targetKind: 'plan',
+    async resolve(root, ctx, canon, cfg, planId) {
+        const plan = findById(canon, planId);
+        if (!plan || plan.meta.type !== 'plan') {
+            return refuse([v('plan', 'unknown-plan', planId, 'a plans/ doc id')]);
+        }
+        const wt = worktreePath(root, planId);
+        if (String(plan.meta.status) !== 'in-progress' || !existsSync(wt)) {
+            return refuse([v('plan', 'not-started', String(plan.meta.status), `an in-progress plan with a worktree — run: witness start ${planId}`)]);
+        }
+        const parent = findById(canon, String(plan.meta.parent));
+        if (!parent) {
+            return refuse([v('parent', 'unknown-parent', String(plan.meta.parent), 'an existing canon doc')]);
+        }
+        const baseR = diffBase(wt, cfg);
+        if (!baseR.ok)
+            return baseR;
+        const base = baseR.value;
+        const files = changedFiles(wt, base);
+        const pin = plan.meta['design-from'];
+        const lensOverrides = {};
+        const skipLenses = [];
+        if (typeof pin === 'string' && pin !== '') {
+            const capR = resolveDesignCaptures(root, wt, planId);
+            if (!capR.ok)
+                return capR;
+            const artRel = designRel(cfg.paths, String(plan.meta.parent));
+            const artAbs = join(root, artRel);
+            if (!existsSync(artAbs) || !statSync(artAbs).isFile()) {
+                return refuse([v('design', 'design-artifact-missing', artRel, 'the approved living design the plan pins — restore it or re-run the design stage')]);
+            }
+            const living = { path: artRel, contents: readFileSync(artAbs, 'utf8') };
+            lensOverrides['design-reviewer'] = {
+                reviewed: { kind: 'screens', captures: capR.value },
+                promptBody: screensPromptBody(capR.value),
+                docs: [living], // joins prompts_sha → an amended design re-rolls on unchanged code
+            };
+        }
+        else {
+            // not UI-work: drop the lens if a battery names it (stages shrink, never skip)
+            skipLenses.push('design-reviewer');
+        }
+        const checks = [];
+        checks.push({ name: 'diff', ok: files.length > 0,
+            detail: files.length ? `${files.length} files changed vs ${base.slice(0, 7)}` : 'nothing changed vs base' });
+        const report = evidenceForDiff(wt, root, plan, base);
+        const missing = report.required.filter((r) => !(r.red && r.green && !r.vacuous));
+        checks.push({ name: 'evidence', ok: report.satisfied,
+            detail: report.satisfied
+                ? `${report.required.length} tags with red→green pairs`
+                : missing.map((m) => `${m.tag}: red=${m.red} green=${m.green}${m.vacuous ? ' vacuous' : ''}`).join(' · ') });
+        const lane = await runCriteria(wt, ctx, parent, { trustRoot: root });
+        checks.push({
+            name: 'drift-lane',
+            ok: lane.ok && lane.value.ok,
+            detail: lane.ok
+                ? lane.value.criteria.map((c) => `${c.id}:${c.ok ? 'ok' : 'fail'}`).join(' · ')
+                : lane.violations.map((x) => `${x.field}:${x.rule}`).join(' · '),
+        });
+        const effort = effortOf(root, planId);
+        const recap = effort ? latestRecap(root, effort) : undefined;
+        return ok({
+            class: (recap?.class ?? 'feature'),
+            reviewedSha: worktreeTreeSha(wt),
+            artifactSha: canonicalSha(plan.meta, plan.body),
+            reviewed: { kind: 'tree', root: wt, files },
+            promptBody: codePromptBody(wt, base, files, `### Plan under implementation: ${planId}\n${serializeDoc({ meta: plan.meta, body: plan.body })}`),
+            checks,
+            stamps: [],
+            lensOverrides,
+            skipLenses,
+        });
+    },
+    currentSha(root, _canon, _cfg, planId) {
+        const wt = worktreePath(root, planId);
+        return existsSync(wt) ? worktreeTreeSha(wt) : undefined;
+    },
+});

package/dist/gates/index.js

@@ -0,0 +1,6 @@
+// Side-effect imports register the gate specs.
+import './decompose.js';
+import './plan.js';
+import './implement.js';
+import './ship.js';
+import './design.js';

package/dist/gates/plan.js

@@ -0,0 +1,86 @@
+import { ok, refuse, v } from '../refusal.js';
+import { serializeDoc } from '../fm.js';
+import { canonicalSha, short } from '../sha.js';
+import { latestRecap } from '../journal.js';
+import { baseForSpec } from '../history.js';
+import { findById } from '../scan.js';
+import { effortOf, planPairSha } from '../reviewed.js';
+import { validateDoc } from '../schemas.js';
+import { registerGate } from '../gate.js';
+import { designPending, designStamp } from '../design.js';
+registerGate({
+    gate: 'plan',
+    targetKind: 'plan',
+    async resolve(root, _ctx, canon, _cfg, planId) {
+        const plan = findById(canon, planId);
+        if (!plan || plan.meta.type !== 'plan') {
+            return refuse([v('plan', 'unknown-plan', planId, 'a plans/ doc id')]);
+        }
+        const effort = effortOf(root, planId);
+        if (!effort) {
+            return refuse([v('plan', 'no-effort', planId, 'a plan written via witness write --effort <slug> (class is read from the effort stream)')]);
+        }
+        const recap = latestRecap(root, effort);
+        const parent = findById(canon, String(plan.meta.parent));
+        if (!parent) {
+            return refuse([v('parent', 'unknown-parent', String(plan.meta.parent), 'an existing canon doc')]);
+        }
+        const checks = [];
+        const schemaProblems = validateDoc(plan.meta, plan.body).map((x) => `${x.field}:${x.rule}`);
+        checks.push({ name: 'schema', ok: schemaProblems.length === 0, detail: schemaProblems.slice(0, 5).join(' · ') });
+        const parentStatus = String(parent.meta.status);
+        const parentOk = parent.meta.type === 'principles'
+            ? parentStatus === 'approved'
+            : parentStatus === 'approved' || parentStatus === 'live';
+        checks.push({ name: 'parent-approved', ok: parentOk,
+            detail: `${String(parent.meta.id)} is ${parentStatus}` });
+        const parentSha = canonicalSha(parent.meta, parent.body);
+        const pin = String(plan.meta['derives-from']);
+        checks.push({ name: 'pin-fresh', ok: pin === parentSha,
+            detail: pin === parentSha
+                ? `pin ${short(parentSha)}`
+                : `derives-from ${short(pin)} but parent is at ${short(parentSha)} — rewrite the plan (witness write re-stamps the pin)` });
+        if (parent.meta.ui === true) {
+            const stamp = designStamp(parent);
+            const planPin = plan.meta['design-from'];
+            const okPin = stamp !== undefined && !designPending(root, parent) && planPin === stamp.sha;
+            checks.push({ name: 'design-pin', ok: okPin,
+                detail: okPin ? `design ${short(stamp.sha)}`
+                    : !stamp ? `${String(parent.meta.id)} has no approved design — gate design first`
+                        : designPending(root, parent) ? `${String(parent.meta.id)} design is stale — re-approve or reconfirm`
+                            : `design-from ${short(String(planPin ?? 'absent'))} ≠ current design ${short(stamp.sha)}` });
+        }
+        const base = baseForSpec(root, canon, String(parent.meta.id), planId);
+        const promptBody = [
+            `### Parent spec: ${String(parent.meta.id)}`, serializeDoc({ meta: parent.meta, body: parent.body }),
+            `### Delta base`, base.kind === 'empty'
+                ? 'new spec — the delta is the whole spec'
+                : `previous plan ${base.planId} pinned ${short(base.sha ?? '')} — the plan must realize what changed since`,
+            `### Plan: ${planId}`, serializeDoc({ meta: plan.meta, body: plan.body }),
+        ].join('\n\n');
+        return ok({
+            class: (recap?.class ?? 'feature'),
+            reviewedSha: planPairSha(plan, parent),
+            artifactSha: canonicalSha(plan.meta, plan.body),
+            reviewed: {
+                kind: 'docs',
+                docs: [
+                    { id: planId, body: plan.body },
+                    { id: String(parent.meta.id), body: parent.body },
+                ],
+            },
+            promptBody,
+            checks,
+            stamps: [{ artifact: planId, to: 'approved' }],
+        });
+    },
+    currentSha(_root, canon, _cfg, planId) {
+        const plan = findById(canon, planId);
+        const parent = plan ? findById(canon, String(plan.meta.parent)) : undefined;
+        return plan && parent ? planPairSha(plan, parent) : undefined;
+    },
+    approveStamps(_root, canon, planId) {
+        const doc = findById(canon, planId);
+        return doc && String(doc.meta.status) === 'draft' ? [{ artifact: planId, to: 'approved' }] : [];
+    },
+});

package/dist/gates/ship.js

@@ -0,0 +1,98 @@
+import { existsSync } from 'node:fs';
+import { ok, refuse, v } from '../refusal.js';
+import { canonicalSha } from '../sha.js';
+import { latestRecap, readStream } from '../journal.js';
+import { findById } from '../scan.js';
+import { changedFiles, diffBase } from '../evidence.js';
+import { runCriteria } from '../criteria.js';
+import { execCommand } from '../runner.js';
+import { ensureTrusted } from '../allowlist.js';
+import { effortOf, worktreeTreeSha } from '../reviewed.js';
+import { worktreePath } from '../worktree.js';
+import { codePromptBody } from './implement.js';
+import { registerGate } from '../gate.js';
+import { lastGateRun } from '../rounds.js';
+import { serializeDoc } from '../fm.js';
+async function commandLane(wt, root, ctx, name, cmd) {
+    if (!cmd)
+        return { name, ok: false, detail: `ship.${name === 'tests' ? 'test' : 'lint'} not configured` };
+    const trust = await ensureTrusted(root, ctx, cmd);
+    if (trust !== 'trusted')
+        return { name, ok: false, detail: `${cmd}: ${trust}` };
+    const run = execCommand(wt, ctx, cmd);
+    return { name, ok: run.exitZero, detail: run.exitZero ? cmd : run.output.slice(-300) };
+}
+registerGate({
+    gate: 'ship',
+    targetKind: 'plan',
+    async resolve(root, ctx, canon, cfg, planId) {
+        const plan = findById(canon, planId);
+        if (!plan || plan.meta.type !== 'plan') {
+            return refuse([v('plan', 'unknown-plan', planId, 'a plans/ doc id')]);
+        }
+        const wt = worktreePath(root, planId);
+        if (String(plan.meta.status) !== 'in-progress' || !existsSync(wt)) {
+            return refuse([v('plan', 'not-started', String(plan.meta.status), `an in-progress plan with a worktree — run: witness start ${planId}`)]);
+        }
+        const parent = findById(canon, String(plan.meta.parent));
+        if (!parent) {
+            return refuse([v('parent', 'unknown-parent', String(plan.meta.parent), 'an existing canon doc')]);
+        }
+        const baseR = diffBase(wt, cfg);
+        if (!baseR.ok)
+            return baseR;
+        const base = baseR.value;
+        const files = changedFiles(wt, base);
+        const checks = [];
+        const entries = readStream(root, planId);
+        const lastImplement = lastGateRun(entries, 'implement');
+        const implementSettled = (() => {
+            if (!lastImplement)
+                return false;
+            if (lastImplement.outcome === 'passed')
+                return true;
+            const after = entries.slice(entries.lastIndexOf(lastImplement) + 1);
+            return after.some((e) => e.t === 'human-decision' &&
+                e.gate === 'implement' &&
+                e.decision === 'approve');
+        })();
+        checks.push({ name: 'implement-gate', ok: implementSettled,
+            detail: lastImplement
+                ? `last implement round ${lastImplement.round}: ${lastImplement.outcome}`
+                : 'implement gate never ran — witness gate implement ' + planId });
+        const ship = (cfg.raw.ship ?? {});
+        checks.push(await commandLane(wt, root, ctx, 'tests', ship.test));
+        checks.push(await commandLane(wt, root, ctx, 'lint', ship.lint));
+        // deterministic drift lane: spec content from MAIN, execution in the worktree
+        const lane = await runCriteria(wt, ctx, parent, { trustRoot: root });
+        const laneOk = lane.ok && lane.value.ok;
+        checks.push({
+            name: 'drift-lane',
+            ok: laneOk,
+            detail: lane.ok
+                ? lane.value.criteria.map((c) => `${c.id}:${c.ok ? 'ok' : 'fail'}`).join(' · ')
+                : lane.violations.map((x) => `${x.field}:${x.rule}`).join(' · '),
+        });
+        const pin = String(plan.meta['derives-from']);
+        const repin = lane.ok && lane.value.ok && pin !== lane.value.sha
+            ? { rel: plan.rel, meta: plan.meta, body: plan.body, sha: lane.value.sha }
+            : undefined;
+        const effort = effortOf(root, planId);
+        const recap = effort ? latestRecap(root, effort) : undefined;
+        return ok({
+            class: (recap?.class ?? 'feature'),
+            reviewedSha: worktreeTreeSha(wt),
+            artifactSha: canonicalSha(plan.meta, plan.body),
+            reviewed: { kind: 'tree', root: wt, files },
+            promptBody: codePromptBody(wt, base, files, `### Parent spec (from main): ${String(parent.meta.id)}\n${serializeDoc({ meta: parent.meta, body: parent.body })}\n\n### Plan: ${planId}\n${serializeDoc({ meta: plan.meta, body: plan.body })}`),
+            checks,
+            standingStop: 'ship always stops — a human sends every PR',
+            stamps: [],
+            repin,
+        });
+    },
+    currentSha(root, _canon, _cfg, planId) {
+        const wt = worktreePath(root, planId);
+        return existsSync(wt) ? worktreeTreeSha(wt) : undefined;
+    },
+});

package/dist/gitio.js

@@ -0,0 +1,97 @@
+import { execFileSync } from 'node:child_process';
+import { dirname } from 'node:path';
+import { canonPaths } from './config.js';
+import { ok, refuse, v } from './refusal.js';
+export function git(root, ...args) {
+    return execFileSync('git', args, {
+        cwd: root,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+    }).replace(/\n$/, '');
+}
+export function tryGit(root, ...args) {
+    try {
+        return { ok: true, out: git(root, ...args) };
+    }
+    catch (e) {
+        const err = e;
+        // most git failures (like `pull --rebase` with no upstream) write to stderr with
+        // an empty stdout — `??` only falls through on nullish, so it must prefer the
+        // first NON-EMPTY stream, not just the first non-nullish one
+        return { ok: false, out: String(err.stdout || err.stderr || e).trim() };
+    }
+}
+export function primaryRoot(cwd) {
+    const top = tryGit(cwd, 'rev-parse', '--show-toplevel');
+    if (!top.ok) {
+        return refuse([v('repo', 'not-a-git-repo', cwd, 'run inside a git repository (git init first)')]);
+    }
+    const common = git(cwd, 'rev-parse', '--path-format=absolute', '--git-common-dir');
+    const gitDir = git(cwd, 'rev-parse', '--path-format=absolute', '--git-dir');
+    if (common === gitDir)
+        return ok(top.out);
+    return ok(dirname(common));
+}
+export function stateDirs(root) {
+    const p = canonPaths(root);
+    return [p.specs, p.plans, p.designs, '.witness'];
+}
+export function isStatePath(root, rel) {
+    return stateDirs(root).some((d) => rel === d || rel.startsWith(d + '/'));
+}
+const LOCAL_STATE_FILES = new Set([
+    '.witness/lock',
+    '.witness/txn.json',
+    '.witness/allow.json',
+    '.witness/calibration.local.yaml',
+]);
+export function dirtyStatePaths(root) {
+    const res = tryGit(root, 'status', '--porcelain', '--untracked-files=all', '--', ...stateDirs(root));
+    if (!res.ok || res.out === '')
+        return [];
+    return res.out
+        .split('\n')
+        // a rename (e.g. from `git mv`) porcelain-formats as "old -> new" on one line —
+        // split it into its two paths so each is checked against the caller's planned set
+        .flatMap((l) => l.slice(3).replace(/^"|"$/g, '').split(' -> '))
+        .filter((p) => !LOCAL_STATE_FILES.has(p));
+}
+export const TRAILER = 'Witness-State: 1';
+export function commitWithTrailer(root, files, subject) {
+    // tryGit, not git: a path already fully processed by a prior `git mv` (both sides
+    // of a rename staged atomically) is absent from working tree AND index, so `add`
+    // reports it unmatched — even though the rename itself is already staged. `commit
+    // --only` resolves its pathspecs against the index-vs-HEAD diff, where the rename
+    // is visible, so it still succeeds and is the real validation here.
+    tryGit(root, 'add', '--', ...files);
+    // --no-verify: state commits are machine-authored and scope-restricted to non-source
+    // paths (isStatePath), so a host lint/test hook has nothing to validate here — while
+    // its stash/restore step can destroy the human's unrelated dirty work, and a
+    // tree-mutating hook (formatters) can desync the index from the txn marker.
+    // stateCommit's own `unrelated-dirty` refusal is the real gate on these commits.
+    git(root, 'commit', '--no-verify', '--only', '-m', subject, '-m', TRAILER, '--', ...files);
+    return ok({ sha: git(root, 'rev-parse', 'HEAD') });
+}
+export function stateCommit(root, files, subject) {
+    const dirs = stateDirs(root);
+    const bad = files.filter((f) => !isStatePath(root, f));
+    if (bad.length) {
+        return refuse(bad.map((f) => v(f, 'out-of-scope', f, `state commits touch only ${dirs.map((d) => `${d}/`).join(', ')}`)));
+    }
+    const planned = new Set(files);
+    const unrelated = dirtyStatePaths(root).filter((p) => !planned.has(p));
+    if (unrelated.length) {
+        return refuse(unrelated.map((p) => v(p, 'unrelated-dirty', 'uncommitted change on a state path', 'revert it or re-apply via witness write, then re-run')));
+    }
+    return commitWithTrailer(root, files, subject);
+}
+export function auditStateCommits(root) {
+    const p = canonPaths(root);
+    const res = tryGit(root, 'log', '--format=%H%x1f%s%x1f%(trailers:key=Witness-State,valueonly=true)', '--', p.specs, p.plans, p.designs, '.witness/journal');
+    if (!res.ok || res.out === '')
+        return [];
+    return res.out.split('\n').filter(Boolean).map((line) => {
+        const [sha, subject, trailer] = line.split('\x1f');
+        return { sha: sha ?? '', subject: subject ?? '', trailered: (trailer ?? '').trim() === '1' };
+    });
+}

package/dist/glob.js

@@ -0,0 +1,32 @@
+import { readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+export function globToRegExp(pattern) {
+    const segs = pattern.split('/');
+    const parts = segs.map((seg, i) => {
+        const last = i === segs.length - 1;
+        if (seg === '**')
+            return last ? '.*' : '(?:[^/]+/)*';
+        const body = seg
+            .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+            .replace(/\*/g, '[^/]*');
+        return last ? body : `${body}/`;
+    });
+    return new RegExp(`^${parts.join('')}$`);
+}
+export function walkFiles(root) {
+    const skip = new Set(['.git', 'node_modules']);
+    const out = [];
+    const rec = (rel) => {
+        for (const name of readdirSync(join(root, rel || '.'))) {
+            if (skip.has(name))
+                continue;
+            const r = rel ? `${rel}/${name}` : name;
+            if (statSync(join(root, r)).isDirectory())
+                rec(r);
+            else
+                out.push(r);
+        }
+    };
+    rec('');
+    return out.sort();
+}