@popovych.co/witness 0.4.0

package/dist/gate.js

@@ -0,0 +1,371 @@
+import { join } from 'node:path';
+import { EXIT, version } from './cli.js';
+import { loadConfig } from './config.js';
+import { writeDoc } from './fm.js';
+import { crashPoint, guardTxn, withTxn } from './txn.js';
+import { acquireLock } from './lock.js';
+import { appendEntry, entryLine, journalRel, policyPins, readStream } from './journal.js';
+import { primaryRoot, stateCommit } from './gitio.js';
+import { loadCanon, findById } from './scan.js';
+import { newRunId } from './drift.js';
+import { resolveHarness } from './harness.js';
+import { ok, refuse, renderRefusal, v } from './refusal.js';
+import { kv, rows } from './toon.js';
+import { loadMatrix, resolveModel, SESSION_DEFAULT } from './model.js';
+import { docKeysFor, docsBlock, invokeReviewer, loadLensDocs, parseVerdictText, pinsBlock, promptsSha, resolvePrompt } from './reviewer.js';
+import { anchorMenu, parseVerdict, verdictViolations } from './verdict.js';
+import { ROUND_BOUND, appendKind, boundReached, gateRuns, roundsSinceApprove, } from './rounds.js';
+import { prepareStamp, writeStamp } from './stamp.js';
+const GATES = new Map();
+export function registerGate(spec) { GATES.set(spec.gate, spec); }
+export function gateSpec(name) { return GATES.get(name); }
+export const DEFAULT_BATTERIES = {
+    decompose: ['slicing-critic'],
+    plan: ['plan-critic'],
+    implement: {
+        feature: ['code-reviewer', 'silent-failure-hunter', 'type-design', 'pr-test', 'design-reviewer'],
+        fix: ['code-reviewer', 'silent-failure-hunter', 'design-reviewer'],
+        chore: ['code-reviewer'],
+    },
+    ship: ['drift-reviewer', 'code-reviewer'],
+    design: ['design-critic'],
+};
+export function batteryFor(cfg, gate, cls) {
+    const gates = (cfg.raw.gates ?? {});
+    const raw = gates[gate]?.reviewers ?? DEFAULT_BATTERIES[gate];
+    const picked = Array.isArray(raw) ? raw : raw[cls];
+    if (!Array.isArray(picked) || picked.length === 0 || !picked.every((x) => typeof x === 'string')) {
+        return refuse([v(`gates.${gate}.reviewers`, 'battery-shape', JSON.stringify(raw), 'a reviewer list or a per-class map of lists')]);
+    }
+    return ok(picked);
+}
+// Which decisions are legal RIGHT NOW is a pure function of journal state, so it belongs
+// where the state is. Skills used to recite a fixed triple, which is wrong at the bound
+// (D67's endgame set) — and now wrong in three more states.
+export function liveExits(gate, target, entries, stale) {
+    if (stale)
+        return `witness gate ${gate} ${target}`;
+    if (boundReached(entries, gate)) {
+        return `witness decide ${gate} ${target} --approve --override | --revise --upstream <id> | --stop`;
+    }
+    return `witness decide ${gate} ${target} --approve | --revise --note "<why>" | --revise --upstream <id> | --stop`;
+}
+export function renderGateRun(ctx, entry, mode) {
+    ctx.out(kv('gate', entry.gate));
+    ctx.out(kv('target', entry.artifact));
+    ctx.out(kv('round', `${entry.round} of ${ROUND_BOUND}${mode === 'resume' ? ' (resume — content unchanged)' : ''}`));
+    ctx.out(kv('reviewed', entry.reviewed_sha.slice(0, 7)));
+    ctx.out(kv('model', `${entry.model} · calibration: ${entry.calibration}${entry.cached ? ' · cached' : ''}`));
+    if (entry.skipped?.length)
+        ctx.out(kv('skipped', entry.skipped.join(' · ')));
+    if (entry.fallback?.length)
+        ctx.out(kv('fallback', entry.fallback.join(' → ')));
+    if (entry.rerolled?.length)
+        ctx.out(kv('rerolled', entry.rerolled.join(' · ')));
+    ctx.out(rows('checks', ['name', 'ok', 'detail'], entry.checks.map((c) => ({ name: c.name, ok: String(c.ok), detail: c.detail ?? '' }))).join('\n'));
+    const findings = (entry.verdicts ?? []).flatMap((rv) => rv.findings.map((f) => ({
+        reviewer: rv.reviewer, blocking: String(f.blocking),
+        pin: f.contradicts_pin !== undefined ? `#${f.contradicts_pin}` : '',
+        anchor: typeof f.anchor === 'string' ? f.anchor : `omission:${f.anchor.scope}`, claim: f.claim,
+    })));
+    if (findings.length)
+        ctx.out(rows('findings', ['reviewer', 'blocking', 'pin', 'anchor', 'claim'], findings).join('\n'));
+    if (entry.malformed?.length) {
+        ctx.out(rows('malformed', ['reviewer', 'field', 'rule'], entry.malformed.flatMap((m) => m.violations.map((x) => ({ reviewer: m.reviewer, field: x.field, rule: x.rule })))).join('\n'));
+    }
+    if (entry.standing)
+        ctx.out(kv('standing-stop', entry.standing));
+    ctx.out(kv('outcome', entry.outcome));
+    if (entry.outcome !== 'passed') {
+        // `[]` keeps this a pure formatter over the entry it was handed — callers that know
+        // the stream (`--show`) render their own `exits:` line from the real entries. The
+        // non-bound triple is correct for runGate's own post-run render: a run that reached
+        // the bound short-circuits before rendering.
+        ctx.out(`help: ${liveExits(entry.gate, entry.artifact, [], false)}`);
+    }
+}
+// Row 79: the human approving a plan sees the run's shape before it starts.
+// Display only — no lens, no threshold; loads config/canon itself so the
+// entry-renderers stay pure formatters.
+export function printDispatchArithmetic(ctx, root, gateName, target) {
+    if (gateName !== 'plan')
+        return;
+    const cfg = loadConfig(root);
+    if (!cfg.ok)
+        return;
+    const doc = findById(loadCanon(root), target);
+    if (!doc || doc.meta.type !== 'plan')
+        return;
+    const budget = cfg.value.implement.stepsPerDispatch;
+    const steps = (doc.meta.steps ?? []).length;
+    ctx.out(kv('dispatches', `${steps} step(s) ≈ ${Math.ceil(steps / budget)} dispatch(es) at budget ${budget}`));
+}
+export async function runGate(ctx, gateName, target, flags) {
+    const rootR = primaryRoot(ctx.cwd);
+    if (!rootR.ok) {
+        renderRefusal(rootR.violations).forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
+    const root = rootR.value;
+    const blocked = guardTxn(ctx, root);
+    if (blocked !== undefined)
+        return blocked;
+    const spec = gateSpec(gateName);
+    if (!spec) {
+        renderRefusal([v('gate', 'unknown-gate', gateName, 'decompose | plan | implement | ship | design')]).forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
+    const cfgR = loadConfig(root);
+    if (!cfgR.ok) {
+        renderRefusal(cfgR.violations).forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
+    const canon = loadCanon(root);
+    const inputR = await spec.resolve(root, ctx, canon, cfgR.value, target);
+    if (!inputR.ok) {
+        renderRefusal(inputR.violations).forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
+    const input = inputR.value;
+    const batteryR = batteryFor(cfgR.value, spec.gate, input.class);
+    if (!batteryR.ok) {
+        renderRefusal(batteryR.violations).forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
+    const skip = new Set(input.skipLenses ?? []);
+    const active = batteryR.value.filter((n) => !skip.has(n));
+    const dropped = batteryR.value.filter((n) => skip.has(n));
+    const entries = readStream(root, target);
+    const pins = policyPins(entries);
+    const pinsText = pinsBlock(pins);
+    const lenses = [];
+    for (const name of active) {
+        const lensR = resolvePrompt(name);
+        if (!lensR.ok) {
+            renderRefusal(lensR.violations).forEach((l) => ctx.err(l));
+            return EXIT.REFUSED;
+        }
+        const lens = lensR.value;
+        const docPaths = docKeysFor(spec.gate, name).flatMap((k) => cfgR.value.docs[k] ?? []);
+        let docs = [];
+        if (docPaths.length > 0) {
+            const docsR = loadLensDocs(root, docPaths);
+            if (!docsR.ok) {
+                renderRefusal(docsR.violations).forEach((l) => ctx.err(l));
+                return EXIT.REFUSED;
+            }
+            docs = docsR.value;
+        }
+        const ov = input.lensOverrides?.[name];
+        if (ov?.docs?.length)
+            docs = [...docs, ...ov.docs]; // living design joins prompts_sha
+        if (docs.length)
+            lens.docs = docs;
+        lenses.push(lens);
+    }
+    const hxR = resolveHarness(ctx.env, cfgR.value.raw);
+    if (!hxR.ok) {
+        renderRefusal(hxR.violations).forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
+    const harness = hxR.value.harness;
+    const modelR = resolveModel(cfgR.value, loadMatrix(root, harness.name), spec.gate);
+    if (!modelR.ok) {
+        renderRefusal(modelR.violations).forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
+    const { chain, calibrationOf, warning } = modelR.value;
+    if (warning)
+        ctx.err(`warning: ${warning}`);
+    const key = {
+        reviewed_sha: input.reviewedSha, gate: spec.gate,
+        prompts_sha: promptsSha(lenses, pinsText === '' ? undefined : pinsText), model: chain[0], witness: version(),
+        harness: harness.name,
+    };
+    const kind = flags.fresh ? { kind: 'fresh' } : appendKind(entries, spec.gate, key);
+    if (kind.kind === 'resume') {
+        renderGateRun(ctx, kind.entry, 'resume');
+        printDispatchArithmetic(ctx, root, spec.gate, target);
+        return kind.entry.outcome === 'passed' ? EXIT.OK : EXIT.FINDINGS;
+    }
+    if (kind.kind === 'changed-nothing') {
+        ctx.out(kv('gate', spec.gate));
+        ctx.out(kv('outcome', 'revise changed nothing — reviewed content is identical to the last round'));
+        ctx.out('help: edit the artifact (or code) before re-running, or decide --approve/--stop');
+        return EXIT.FINDINGS;
+    }
+    if (boundReached(entries, spec.gate)) {
+        ctx.out(kv('gate', spec.gate));
+        ctx.out(kv('outcome', `round bound reached (${roundsSinceApprove(entries, spec.gate)} rounds since last approve)`));
+        ctx.out(`help: witness decide ${spec.gate} ${target} --approve --override | --revise --upstream <id> | --stop`);
+        ctx.out(`help: or discard the plan: witness abandon ${target}`);
+        return EXIT.BLOCKED;
+    }
+    if (!flags.fresh) {
+        // malformed rounds don't spend the bound (rounds.ts) — this brake is what
+        // stops an unreliable battery from re-running for free forever instead
+        const tail = gateRuns(entries, spec.gate).slice(-2);
+        const sameSetup = (r) => r.outcome === 'malformed' && r.model === key.model && r.prompts_sha === key.prompts_sha &&
+            (r.harness ?? 'claude-code') === key.harness;
+        if (tail.length === 2 && tail.every(sameSetup)) {
+            renderRefusal([v('reviewers', 'malformed-streak', `${tail.length} consecutive malformed rounds on ${tail[1].model}`, `a changed gates.${spec.gate}.model pin or updated prompts — the battery is emitting invalid verdicts (or force with --fresh)`)]).forEach((l) => ctx.err(l));
+            return EXIT.REFUSED;
+        }
+    }
+    // The reviewer battery runs UNLOCKED. It writes nothing — every symbol it produces is
+    // an in-memory local, and reviewer caching is journal-derived (appendKind), not on-disk.
+    // Holding the repo-global lock across a multi-minute LLM battery refuses every state
+    // write in every other flow for its full duration, on a lock whose real job is a ~100ms
+    // commit. The guarded window opens below, immediately before the journal append.
+    let verdicts = [];
+    const malformed = [];
+    const fallback = [];
+    const rerolled = [];
+    let rung = 0;
+    let model = chain[0];
+    let cached = false;
+    if (kind.kind === 'cached') {
+        verdicts = kind.from.verdicts ?? [];
+        model = kind.from.model;
+        cached = true;
+    }
+    else {
+        for (const lens of lenses) {
+            const ov = input.lensOverrides?.[lens.name];
+            const reviewed = ov?.reviewed ?? input.reviewed;
+            const body = ov?.promptBody ?? input.promptBody;
+            const menu = anchorMenu(reviewed);
+            let prompt = `${lens.contents}\n\n${docsBlock(lens.docs ?? [])}${pinsText}${menu ? `${menu}\n\n` : ''}## Reviewed content\n\n${body}\n`;
+            for (let attempt = 0;; attempt++) {
+                let answered;
+                for (;;) {
+                    const id = chain[rung];
+                    const r = invokeReviewer(ctx, harness, { cwd: root, prompt, model: id === SESSION_DEFAULT ? undefined : id });
+                    if (r.ok) {
+                        answered = r.value.text;
+                        model = id;
+                        break;
+                    }
+                    if (rung >= chain.length - 1) {
+                        renderRefusal(r.violations).forEach((l) => ctx.err(l));
+                        return EXIT.REFUSED;
+                    }
+                    fallback.push(id);
+                    rung += 1;
+                }
+                const rawR = parseVerdictText(answered);
+                const parsedR = rawR.ok ? parseVerdict(rawR.value) : rawR;
+                const violations = parsedR.ok ? verdictViolations(parsedR.value, reviewed) : parsedR.violations;
+                if (parsedR.ok && violations.length === 0) {
+                    verdicts.push({ reviewer: lens.name, coverage: parsedR.value.coverage, findings: parsedR.value.findings });
+                    break;
+                }
+                if (attempt === 0) {
+                    // one self-repair reroll per reviewer — a single flaky verdict would
+                    // otherwise poison the whole round as 'malformed'; the reroll is not
+                    // part of the gate key, so cached rounds replay the settled result
+                    rerolled.push(lens.name);
+                    prompt += `\n## Previous attempt rejected\n\n${violations.map((x) => `- ${x.field}: ${x.rule} — got ${x.got}; want ${x.want}`).join('\n')}\n\nRe-emit the complete corrected verdict JSON.\n`;
+                    continue;
+                }
+                malformed.push({ reviewer: lens.name, violations });
+                break;
+            }
+        }
+    }
+    if (fallback.length > 0 && chain[0] !== SESSION_DEFAULT && fallback.includes(chain[0])) {
+        ctx.err(`warning: head model ${chain[0]} failed to invoke — reviewers ran on ${model}; check gates.${spec.gate}.model`);
+    }
+    const blocking = verdicts.flatMap((x) => x.findings).filter((f) => f.blocking).length;
+    const pinConflicts = verdicts.flatMap((x) => x.findings).filter((f) => f.contradicts_pin !== undefined).length;
+    const standing = [
+        input.standingStop,
+        pinConflicts > 0 ? 'contradicts-pin — a finding disputes a settled policy pin; the human decides which one dies' : undefined,
+    ].filter((s) => s !== undefined).join(' · ') || undefined;
+    const checksGreen = input.checks.every((c) => c.ok);
+    const outcome = malformed.length > 0 ? 'malformed'
+        : !checksGreen || blocking > 0 ? 'stopped'
+            : standing !== undefined || flags.manual ? 'stopped'
+                : 'passed';
+    const lockR = acquireLock(root);
+    if (!lockR.ok) {
+        renderRefusal(lockR.violations).forEach((l) => ctx.err(l));
+        return EXIT.BLOCKED;
+    }
+    const release = lockR.value;
+    try {
+        // The battery ran unlocked, so the journal may have moved under us. `entries` (read
+        // at :160) feeds appendKind, boundReached, and the round number — all three must be
+        // recomputed against the stream as it stands NOW, or two concurrent gate runs on one
+        // target both journal round N and both slip past the bound.
+        // Content staleness is deliberately NOT checked here: the entry we write is honest
+        // (it records the sha we judged), and a stale verdict stops settling its gate at
+        // consumption time (gateSettled's reviewed_sha check).
+        const entriesNow = readStream(root, target);
+        if (boundReached(entriesNow, spec.gate)) {
+            ctx.out(kv('gate', spec.gate));
+            ctx.out(kv('outcome', `round bound reached (${roundsSinceApprove(entriesNow, spec.gate)} rounds since last approve)`));
+            ctx.out(`help: witness decide ${spec.gate} ${target} --approve --override | --revise --upstream <id> | --stop`);
+            ctx.out(`help: or discard the plan: witness abandon ${target}`);
+            return EXIT.BLOCKED;
+        }
+        const entry = {
+            v: 1, t: 'gate-run', gate: spec.gate, artifact: target,
+            round: roundsSinceApprove(entriesNow, spec.gate) + 1, run_id: newRunId(),
+            reviewed_sha: input.reviewedSha, prompts_sha: key.prompts_sha,
+            witness: key.witness, model, harness: harness.name, calibration: calibrationOf(model),
+            ...(cached ? { cached: true } : {}),
+            ...(flags.manual ? { manual: true } : {}),
+            ...(fallback.length ? { fallback } : {}),
+            ...(rerolled.length ? { rerolled } : {}),
+            ...(dropped.length ? { skipped: dropped } : {}),
+            ...(outcome === 'stopped' && standing ? { standing } : {}),
+            ...(input.artifactSha ? { artifact_sha: input.artifactSha } : {}),
+            checks: input.checks,
+            ...(verdicts.length ? { verdicts } : {}),
+            ...(malformed.length ? { malformed } : {}),
+            outcome,
+        };
+        const stamps = outcome === 'passed'
+            ? input.stamps.flatMap((s) => {
+                const doc = findById(canon, s.artifact);
+                return doc && String(doc.meta.status) !== s.to
+                    ? [prepareStamp(doc, s.to, 'gate-approve', { run_id: entry.run_id })] : [];
+            })
+            : [];
+        const files = [
+            journalRel(target), ...stamps.flatMap((s) => [s.rel, journalRel(s.stream)]),
+            ...(input.repin ? [input.repin.rel] : []),
+        ];
+        const marker = {
+            op: `gate-${spec.gate}`,
+            files: [...new Set(files)],
+            journalMulti: [
+                { stream: target, line: entryLine(entry) },
+                ...stamps.map((s) => ({ stream: s.stream, line: s.line })),
+            ],
+        };
+        const txn = withTxn(root, marker, () => {
+            appendEntry(root, target, entry);
+            for (const s of stamps)
+                writeStamp(root, s);
+            if (input.repin) {
+                writeDoc(join(root, input.repin.rel), { meta: { ...input.repin.meta, 'derives-from': input.repin.sha }, body: input.repin.body });
+            }
+            crashPoint(ctx.env, 'gate-journal');
+            return stateCommit(root, marker.files, `gate(${spec.gate}): ${target} round ${entry.round} ${outcome}`);
+        });
+        if (!txn.ok) {
+            renderRefusal(txn.violations).forEach((l) => ctx.err(l));
+            return EXIT.REFUSED;
+        }
+        renderGateRun(ctx, entry, 'ran');
+        printDispatchArithmetic(ctx, root, spec.gate, target);
+        if (input.repin)
+            ctx.out(kv('re-pinned', `derives-from → ${input.repin.sha.slice(0, 7)} (witnessed by the drift lane)`));
+        return outcome === 'passed' ? EXIT.OK : EXIT.FINDINGS;
+    }
+    finally {
+        release();
+    }
+}

package/dist/gates/decompose.js

@@ -0,0 +1,90 @@
+import { ok, refuse, v } from '../refusal.js';
+import { serializeDoc } from '../fm.js';
+import { canonicalJson, canonicalSha } from '../sha.js';
+import { latestRecap, streamExists } from '../journal.js';
+import { findCycle, findById } from '../scan.js';
+import { effortReviewedSha, effortSpecs, effortWrites } from '../reviewed.js';
+import { validateDoc } from '../schemas.js';
+import { registerGate } from '../gate.js';
+function stampsFor(docs) {
+    return docs
+        .filter((d) => String(d.meta.status) === 'draft')
+        .map((d) => ({ artifact: String(d.meta.id), to: 'approved' }));
+}
+registerGate({
+    gate: 'decompose',
+    targetKind: 'effort',
+    async resolve(root, _ctx, canon, _cfg, effort) {
+        if (!streamExists(root, effort)) {
+            return refuse([v('effort', 'unknown-effort', effort, 'an effort born by witness recap')]);
+        }
+        const recap = latestRecap(root, effort);
+        if (!recap)
+            return refuse([v('effort', 'unknown-effort', effort, 'a stream whose first entry is a recap')]);
+        const writes = effortWrites(root, effort);
+        const docs = effortSpecs(root, canon, effort);
+        if (docs.length === 0) {
+            return refuse([v('effort', 'nothing-to-gate', effort, `written specs — run: witness write <id> --effort ${effort} --meta m.json --body b.md`)]);
+        }
+        const checks = [];
+        const schemaProblems = docs.flatMap((d) => validateDoc(d.meta, d.body).map((x) => `${String(d.meta.id)} ${x.field}:${x.rule}`));
+        checks.push({ name: 'schema', ok: schemaProblems.length === 0, detail: schemaProblems.slice(0, 5).join(' · ') });
+        const cycle = findCycle(canon);
+        checks.push({ name: 'graph', ok: cycle === undefined, detail: cycle?.join(' → ') ?? '' });
+        const goals = (recap.goals ?? []).map((g) => g.id);
+        const covered = new Set();
+        const orphans = [];
+        for (const d of docs) {
+            const covers = writes.get(String(d.meta.id))?.covers ?? [];
+            covers.forEach((g) => covered.add(g));
+            if (covers.length === 0)
+                orphans.push(String(d.meta.id));
+        }
+        const missing = goals.filter((g) => !covered.has(g));
+        checks.push({ name: 'goal-coverage', ok: missing.length === 0,
+            detail: missing.length ? `uncovered goals: ${missing.join(' ')}` : `${goals.length} goals covered` });
+        checks.push({ name: 'spec-coverage', ok: orphans.length === 0,
+            detail: orphans.length ? `specs covering no goal: ${orphans.join(' ')}` : 'every spec covers ≥ 1 goal' });
+        const staleChildren = canon.docs
+            .filter((p) => p.meta.type === 'plan' && String(p.meta.status) === 'in-progress')
+            .filter((p) => docs.some((d) => String(d.meta.id) === String(p.meta.parent)))
+            .filter((p) => {
+            const parent = findById(canon, String(p.meta.parent));
+            return String(p.meta['derives-from']) !== canonicalSha(parent.meta, parent.body);
+        })
+            .map((p) => String(p.meta.id));
+        checks.push({ name: 'amendment-ack', ok: staleChildren.length === 0,
+            detail: staleChildren.length
+                ? `amended under in-progress plans (approve = explicit ack): ${staleChildren.join(' ')}`
+                : '' });
+        const created = [...writes.values()].some((w) => w.created === true);
+        const standingStop = recap.class === 'feature' ? 'feature scope approval — scope is approved as its concrete slicing'
+            : recap.class === 'fix' && created
+                ? 'fix created a new spec — misroute tripwire (young canon: expect new-spec stops at first)'
+                : undefined;
+        const coverageTable = docs
+            .map((d) => `${String(d.meta.id)}: covers ${(writes.get(String(d.meta.id))?.covers ?? []).join(' ') || '(none)'}`)
+            .join('\n');
+        const promptBody = [
+            '### Confirmed scope recap (latest)', canonicalJson(recap),
+            '### Goal coverage (journaled)', coverageTable,
+            ...docs.flatMap((d) => [`### Spec: ${String(d.meta.id)}`, serializeDoc({ meta: d.meta, body: d.body })]),
+        ].join('\n\n');
+        const { sha } = effortReviewedSha(root, canon, effort);
+        return ok({
+            class: (recap.class ?? 'feature'),
+            reviewedSha: sha,
+            reviewed: { kind: 'docs', docs: docs.map((d) => ({ id: String(d.meta.id), body: d.body })) },
+            promptBody,
+            checks,
+            standingStop,
+            stamps: stampsFor(docs),
+        });
+    },
+    currentSha(root, canon, _cfg, effort) {
+        return effortReviewedSha(root, canon, effort).sha;
+    },
+    approveStamps(root, canon, effort) {
+        return stampsFor(effortSpecs(root, canon, effort));
+    },
+});

package/dist/gates/design.js

@@ -0,0 +1,84 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { serializeDoc } from '../fm.js';
+import { designPairSha, designRel, designUnseen, elementIds, htmlSha, validateDesignArtifact } from '../design.js';
+import { registerGate } from '../gate.js';
+import { latestRecap } from '../journal.js';
+import { ok, refuse, v } from '../refusal.js';
+import { effortOf } from '../reviewed.js';
+import { findById } from '../scan.js';
+import { canonicalSha, short } from '../sha.js';
+// What this gate judges: the artifact PAIRED with the spec it realizes. With no artifact
+// the spec alone is the sha, so a re-authored spec still lapses a prior verdict. Shared
+// by `resolve` and `currentSha` so the two can never disagree about what moved.
+const reviewedShaOf = (html, spec) => html !== undefined ? designPairSha(html, spec) : canonicalSha(spec.meta, spec.body);
+registerGate({
+    gate: 'design',
+    targetKind: 'spec',
+    async resolve(root, _ctx, canon, cfg, specId) {
+        const spec = findById(canon, specId);
+        if (!spec || spec.meta.type !== 'spec') {
+            return refuse([v('spec', 'unknown-spec', specId, 'a specs/ doc id')]);
+        }
+        const effort = effortOf(root, specId);
+        const recap = effort ? latestRecap(root, effort) : undefined;
+        const rel = designRel(cfg.paths, specId);
+        const abs = join(root, rel);
+        const html = existsSync(abs) ? readFileSync(abs, 'utf8') : undefined;
+        // Sight is a PRECONDITION of gating, not a byproduct of it. Refusing here costs no
+        // reviewer call and keeps `resolve` pure — the rejected shape spawned the opener from
+        // this function, which fires on the four runGate paths that write no entry (resume,
+        // changed-nothing, bound, malformed-streak), producing a window the journal never
+        // learns about. An agent that drops the show step now hits a loud refusal its repair
+        // loop already handles, instead of silently gating something nobody was shown.
+        const unseen = designUnseen(root, cfg.paths, specId);
+        if (unseen !== undefined) {
+            return refuse([v('design', 'design-unseen', `no sight witnessed for ${short(unseen)}`, `a human shown this artifact — run: witness design ${specId} --open`)]);
+        }
+        const checks = [];
+        checks.push({ name: 'ui-flag', ok: spec.meta.ui === true, detail: spec.meta.ui === true ? 'ui: true' : 'spec is not ui-flagged' });
+        checks.push({ name: 'feature-class', ok: recap?.class === 'feature', detail: `effort class: ${recap?.class ?? 'none'}` });
+        checks.push({ name: 'artifact', ok: html !== undefined, detail: html !== undefined ? rel : `${rel} missing — run: witness design ${specId} --file <html>` });
+        const template = html !== undefined ? validateDesignArtifact(html) : [];
+        checks.push({ name: 'template', ok: html !== undefined && template.length === 0,
+            detail: template.length ? template.map((x) => x.rule).join(' · ') : 'self-contained, id-attributed' });
+        // With no artifact, reviewer input is empty ids + the spec — the checks already
+        // fail-stop; still produce a well-formed GateInput so the gate stops cleanly.
+        const ids = html !== undefined ? elementIds(html) : [];
+        const promptBody = [
+            `### Design artifact: ${rel}`, html ?? '(missing — no artifact to review)',
+            `### Parent spec: ${specId}`, serializeDoc({ meta: spec.meta, body: spec.body }),
+        ].join('\n\n');
+        return ok({
+            class: (recap?.class ?? 'feature'),
+            reviewedSha: reviewedShaOf(html, spec),
+            artifactSha: html !== undefined ? htmlSha(html) : undefined,
+            reviewed: { kind: 'design', artifact: { ids }, spec: { id: specId, body: spec.body } },
+            promptBody,
+            checks,
+            standingStop: 'design always stops — a human approves every screen (same footing as ship)',
+            stamps: [],
+        });
+    },
+    currentSha(root, canon, cfg, specId) {
+        const spec = findById(canon, specId);
+        if (!spec || spec.meta.type !== 'spec')
+            return undefined;
+        const abs = join(root, designRel(cfg.paths, specId));
+        return reviewedShaOf(existsSync(abs) ? readFileSync(abs, 'utf8') : undefined, spec);
+    },
+    approveMeta(root, canon, cfg, specId) {
+        const spec = findById(canon, specId);
+        if (!spec || spec.meta.type !== 'spec')
+            return [];
+        const abs = join(root, designRel(cfg.paths, specId));
+        if (!existsSync(abs))
+            return [];
+        const sha = htmlSha(readFileSync(abs, 'utf8'));
+        return [{
+                artifact: specId,
+                patch: { design: { sha, spec: canonicalSha(spec.meta, spec.body) } },
+                entryType: 'design-stamp',
+            }];
+    },
+});