@popovych.co/witness 0.4.0

package/dist/harness.js

@@ -0,0 +1,229 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { CLAUDE_THINKING_BUDGET, parsePin } from './pin.js';
+import { ok, refuse, v } from './refusal.js';
+export const HARNESSES = ['claude-code', 'pi'];
+export const DEFAULT_HARNESS = 'claude-code';
+// The six shipped stage skills, by directory name. `check`'s visibility probe asks
+// whether the resolved harness can see all of them; a partial install is a warn, not
+// a pass, because the missing one is always the stage you are about to reach.
+export const STAGE_SKILLS = [
+    'witness-brainstorm', 'witness-decompose', 'witness-design',
+    'witness-implement', 'witness-plan', 'witness-ship',
+];
+function parseClaudeEnvelope(stdout) {
+    try {
+        const envelope = JSON.parse(stdout);
+        if (typeof envelope.result !== 'string')
+            throw new Error('missing result');
+        return ok({ text: envelope.result });
+    }
+    catch {
+        return refuse([v('claude', 'envelope-unparseable', stdout.slice(0, 120), 'a --output-format json envelope carrying a result string')]);
+    }
+}
+// pi --mode json emits an NDJSON event stream; the terminal agent_end event carries the
+// full message history. Provider failures arrive IN-stream (stopReason: "error") — the
+// process can still exit 0, so exit-code checks alone cannot detect them.
+function parsePiEnvelope(stdout) {
+    let end;
+    for (const line of stdout.split('\n')) {
+        if (!line.startsWith('{'))
+            continue;
+        try {
+            const evt = JSON.parse(line);
+            if (evt.type === 'agent_end')
+                end = evt;
+        }
+        catch { /* interleaved non-JSON output — skip the line, keep scanning */ }
+    }
+    const assistant = end?.messages?.filter((m) => m.role === 'assistant').at(-1);
+    if (assistant?.stopReason === 'error') {
+        return refuse([v('pi', 'reviewer-invocation', (assistant.errorMessage ?? 'provider error').slice(0, 200), 'a provider the pinned model can reach — check auth and billing for that provider')]);
+    }
+    const text = (assistant?.content ?? []).filter((c) => c.type === 'text').map((c) => c.text ?? '').join('\n');
+    if (text === '') {
+        return refuse([v('pi', 'envelope-unparseable', stdout.slice(0, 120), 'a --mode json event stream whose agent_end carries assistant text')]);
+    }
+    return ok({ text });
+}
+// Revision 10: a typed constant, not `harness/<name>.json`. Every consumer is
+// TypeScript and the name set is closed by loadHarness's refusal, so a data file bought
+// extensibility the design forbids — while costing an unchecked `as Harness` cast, a
+// registry-missing path, packageRoot(), and a packaging failure mode NO test can catch:
+// drop the dir from package.json `files` and every verb refuses in the published
+// package while the whole suite stays green, because vitest reads from the repo root.
+const REGISTRY = {
+    'claude-code': {
+        name: 'claude-code',
+        launch: 'claude',
+        relay: '/clear',
+        settings: '.claude/settings.json',
+        bundled: true,
+        payload: [
+            { from: 'plugin/commands/witness.md', to: '.claude/commands/witness.md' },
+            { from: 'plugin/hooks/canon-guard.mjs', to: '.claude/hooks/canon-guard.mjs' },
+            { from: 'plugin/hooks/guard-state.mjs', to: '.claude/hooks/guard-state.mjs' },
+            { from: 'plugin/hooks/session-dashboard.sh', to: '.claude/hooks/session-dashboard.sh' },
+        ],
+        skills: { project: '.claude/skills', global: '.claude/skills' },
+        reviewer: {
+            spawn(pin) {
+                const args = ['-p', '--output-format', 'json'];
+                const env = {};
+                if (pin !== undefined) {
+                    args.push('--model', pin.model);
+                    if (pin.thinking !== 'off')
+                        env.MAX_THINKING_TOKENS = String(CLAUDE_THINKING_BUDGET[pin.thinking]);
+                }
+                return { cmd: 'claude', args, env };
+            },
+            parseEnvelope: parseClaudeEnvelope,
+        },
+        worker: {
+            // claude gates every tool behind an approval prompt, which no headless run can
+            // answer — the bypass flag is what makes print mode able to edit at all.
+            spawn: (prompt) => ({ cmd: 'claude', args: ['-p', prompt, '--dangerously-skip-permissions'], env: {} }),
+        },
+    },
+    pi: {
+        name: 'pi',
+        launch: 'pi',
+        defaultProvider: 'anthropic',
+        relay: '/new',
+        bundled: false,
+        payload: [
+            { from: 'plugin/commands/witness.md', to: '.pi/prompts/witness.md' },
+            { from: 'plugin/hooks/canon-guard.mjs', to: '.pi/extensions/canon-guard.mjs' },
+            // Source-tree sibling of canon-guard.mjs, exactly as it is in .pi/extensions/:
+            // the adapter imports the core with ONE static relative specifier, and a
+            // specifier that only resolves after install is a trap no unit test can hold.
+            { from: 'plugin/hooks/witness-pi.ts', to: '.pi/extensions/witness.ts' },
+            { from: 'plugin/hooks/session-dashboard.sh', to: '.pi/extensions/session-dashboard.sh' },
+        ],
+        skills: { project: '.pi/skills', global: '.pi/agent/skills' },
+        // Hermetic (Decision 88): every omitted flag here is a machine-local variable that
+        // would silently change reviewer behavior — this machine's `defaultThinkingLevel:
+        // xhigh` was the probable true cause of row 87's "stalls on long prompts".
+        reviewer: {
+            spawn(pin) {
+                const args = ['-p', '--mode', 'json', '--no-session', '--no-extensions',
+                    '--no-skills', '--no-context-files', '--thinking', pin?.thinking ?? 'off'];
+                if (pin !== undefined)
+                    args.push('--model', `${pin.provider ?? 'anthropic'}/${pin.model}`);
+                return { cmd: 'pi', args, env: {} };
+            },
+            parseEnvelope: parsePiEnvelope,
+        },
+        worker: {
+            // No bypass flag exists or is needed: pi's built-in tools are not approval-gated
+            // (`pi --help` lists only --approve/--no-approve, which govern trusting
+            // project-local files). --no-session keeps a calibration run out of the user's
+            // session store; the worker otherwise keeps its skills and context files, which
+            // are exactly what the implement seed is measuring.
+            spawn: (prompt) => ({ cmd: 'pi', args: ['-p', prompt, '--no-session'], env: {} }),
+        },
+    },
+};
+export function loadHarness(name) {
+    const harness = REGISTRY[name];
+    if (harness === undefined) {
+        return refuse([v('harness', 'unknown-harness', name, HARNESSES.join(' | '))]);
+    }
+    return ok(harness);
+}
+const relabel = (violations, field) => violations.map((x) => ({ ...x, field }));
+// Decision 5. Detection is the authority; config is the fallback. A config-authority
+// default in a fresh repo emits a runnable-LOOKING, unrunnable handoff behind a warning
+// that gets scrolled past — bug B2's exact shape. Detection tests PRESENCE: neither
+// CLAUDECODE=1 nor PI_CODING_AGENT=true is a documented value contract.
+//
+// Deliberately NOT wired into loadConfig: every verb calls that, so an invalid
+// `harness:` there would brick `witness check` on a key nothing read. Verbs that need
+// a harness ask for one; `check` reports a malformed config value as a finding.
+export function resolveHarness(env, raw) {
+    const override = env.WITNESS_HARNESS;
+    if (override !== undefined && override !== '') {
+        const r = loadHarness(override);
+        return r.ok ? ok({ harness: r.value, source: 'env' }) : refuse(relabel(r.violations, 'WITNESS_HARNESS'));
+    }
+    if (env.PI_CODING_AGENT !== undefined) {
+        const r = loadHarness('pi');
+        return r.ok ? ok({ harness: r.value, source: 'detected' }) : refuse(r.violations);
+    }
+    if (env.CLAUDECODE !== undefined) {
+        const r = loadHarness('claude-code');
+        return r.ok ? ok({ harness: r.value, source: 'detected' }) : refuse(r.violations);
+    }
+    const configured = raw.harness;
+    if (configured !== undefined) {
+        const r = loadHarness(String(configured));
+        return r.ok ? ok({ harness: r.value, source: 'config' }) : refuse(r.violations);
+    }
+    const r = loadHarness(DEFAULT_HARNESS);
+    return r.ok ? ok({ harness: r.value, source: 'default' }) : refuse(r.violations);
+}
+// Decision 9: the model flag is a renderer, not a string. Pi's default provider is
+// `google`, so a bare `--model claude-opus-5` in a Pi handoff resolves wrong or not at
+// all — and a relay session silently running an unpinned model corrupts what row 83's
+// pins and the calibration story rest on.
+//
+// Revision 9: the provider is the HARNESS's default, never a config key.
+//
+// Extended by Decision 88: the flag renders over the PARSED pin, not the raw string.
+// Treating the whole string as {model} emitted `--model anthropic/google/gemini-3.6-pro`
+// for a provider-qualified pin — pastes cleanly, resolves to nothing: bug B2's shape.
+// Pi renders the provider and its native `:thinking` suffix; claude-code renders the
+// bare id and carries non-off thinking as a MAX_THINKING_TOKENS prefix on the line.
+function modelArg(harness, model) {
+    if (model === undefined || model === '')
+        return '';
+    const parsed = parsePin('gates.model', model);
+    if (!parsed.ok)
+        return ''; // stagePin refused upstream; render nothing rather than garbage
+    const pin = parsed.value;
+    if (harness.name === 'pi') {
+        const suffix = pin.thinking === 'off' ? '' : `:${pin.thinking}`;
+        return ` --model ${pin.provider ?? harness.defaultProvider ?? ''}/${pin.model}${suffix}`;
+    }
+    return ` --model ${pin.model}`;
+}
+// Single quotes: a double-quoted form trips toon esc() quoting and emits an
+// unpasteable line (see the note this replaces at verbs/next.ts:69).
+export function handoffLine(harness, home, model) {
+    const parsed = model !== undefined && model !== '' ? parsePin('gates.model', model) : undefined;
+    const budget = harness.name === 'claude-code' && parsed?.ok === true && parsed.value.thinking !== 'off'
+        ? `MAX_THINKING_TOKENS=${CLAUDE_THINKING_BUDGET[parsed.value.thinking]} `
+        : '';
+    return `cd '${home}' && ${budget}${harness.launch}${modelArg(harness, model)} '/witness'`;
+}
+// No comma: toon's esc() quotes any value containing one (toon.ts:3), and a quoted
+// `relay: "/clear, then /witness"` is what the implement skill would then print
+// verbatim — the same class of defect as the double-quoted handoff note above.
+export function relayLine(harness) {
+    return `${harness.relay} then /witness`;
+}
+// Decision 14. Pi resolves project skills at resolve(cwd, '.pi', 'skills') with no
+// upward walk, and implement runs with cwd inside .witness/worktrees/<plan-id> — an
+// untracked directory the installer never touched. A project-scope install therefore
+// loses every skill in the stage that does the most work.
+export function skillsVisibility(env, root, harness) {
+    const home = env.HOME ?? env.USERPROFILE ?? '';
+    const has = (dir) => STAGE_SKILLS.every((s) => existsSync(join(dir, s, 'SKILL.md')));
+    if (home !== '' && has(join(home, harness.skills.global)))
+        return 'global';
+    if (has(join(root, harness.skills.project)))
+        return 'project-only';
+    return 'absent';
+}
+// Harness-compat rung of pin validation. Grammar and alias checks live in stagePin
+// (model.ts); THIS check needs the harness, which stagePin deliberately never resolves.
+export function validatePin(harness, field, raw) {
+    const r = parsePin(field, raw);
+    if (!r.ok)
+        return r;
+    if (harness.name === 'claude-code' && r.value.provider !== undefined) {
+        return refuse([v(field, 'provider-unrunnable', raw, 'a bare model id — the claude CLI cannot run provider-qualified models')]);
+    }
+    return r;
+}

package/dist/history.js

@@ -0,0 +1,35 @@
+import { splitDoc } from './fm.js';
+import { tryGit } from './gitio.js';
+import { canonicalSha } from './sha.js';
+export function contentAtSha(root, rel, sha) {
+    const log = tryGit(root, 'log', '--format=%H', '--', rel);
+    if (!log.ok || log.out === '')
+        return undefined;
+    for (const commit of log.out.split('\n')) {
+        const shown = tryGit(root, 'show', `${commit}:${rel}`);
+        if (!shown.ok)
+            continue;
+        const parsed = splitDoc(shown.out + '\n');
+        if (!parsed.ok)
+            continue;
+        if (canonicalSha(parsed.value.meta, parsed.value.body) === sha)
+            return parsed.value;
+    }
+    return undefined;
+}
+export function baseForSpec(root, canon, specId, excludePlanId) {
+    const candidates = canon.docs.filter((d) => d.meta.type === 'plan' &&
+        d.meta.parent === specId &&
+        typeof d.meta['derives-from'] === 'string' &&
+        d.meta.id !== excludePlanId);
+    if (candidates.length === 0)
+        return { kind: 'empty' };
+    const stamped = candidates.map((p) => {
+        const res = tryGit(root, 'log', '-1', '--format=%ct', '--', p.rel);
+        const at = res.ok && res.out !== '' ? Number(res.out) : Number.POSITIVE_INFINITY;
+        return { p, at };
+    });
+    stamped.sort((a, b) => b.at - a.at || String(b.p.meta.id).localeCompare(String(a.p.meta.id)));
+    const latest = stamped[0].p;
+    return { kind: 'plan-pin', sha: String(latest.meta['derives-from']), planId: String(latest.meta.id) };
+}

package/dist/install.js

@@ -0,0 +1,133 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { tryGit } from './gitio.js';
+import { ok, refuse, v } from './refusal.js';
+// dist/install.js and src/install.ts both sit one level under the package root, so the
+// same '..' works built and under vitest — the pattern model.ts:14 already uses. This is
+// the only place that still needs it: locating the shipped `plugin/` tree, which is a
+// genuine data dir already listed in package.json `files`.
+export function packageRoot() {
+    return join(dirname(fileURLToPath(import.meta.url)), '..');
+}
+// Project-scope hook commands. ${CLAUDE_PLUGIN_ROOT} exists only for plugin installs;
+// a project install anchors on $CLAUDE_PROJECT_DIR, which Claude Code substitutes in
+// hook commands (verified against 2.1.220).
+const GUARD_CMD = 'node "$CLAUDE_PROJECT_DIR/.claude/hooks/guard-state.mjs"';
+const DASHBOARD_CMD = 'sh "$CLAUDE_PROJECT_DIR/.claude/hooks/session-dashboard.sh"';
+const PIN = /@popovych\.co\/witness@\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?/g;
+// Revision 6. Committing the payload is load-bearing: the implement stage runs with cwd
+// inside .witness/worktrees/<plan-id>, which is a checkout of the branch, so only
+// committed files reach it. A gitignored target therefore has exactly one honest answer
+// — refuse. `git add -f` would override a rule the human wrote down; writing without
+// committing would leave the payload in the primary root and the worktree with no guard,
+// while every `check` reads clean. Called BEFORE the lock and before any scaffold write,
+// so a refusal leaves nothing half-installed.
+export function preflightPayload(root, harness) {
+    const ignored = [...harness.payload.map((p) => p.to), ...(harness.settings ? [harness.settings] : [])]
+        .filter((rel) => tryGit(root, 'check-ignore', '-q', '--', rel).ok);
+    if (ignored.length === 0)
+        return ok(undefined);
+    return refuse(ignored.map((rel) => v(rel, 'payload-ignored', 'matched by .gitignore', 'a committable path — worktrees are branch checkouts, so only committed payloads reach ' +
+        '.witness/worktrees/<plan-id>; un-ignore it, or install a different agent here')));
+}
+// A shipped file and an installed file that differ ONLY by version pin are the same
+// file, one upgrade apart. Substituting the installed pin into the shipped text and
+// comparing is exact — no heuristics, no diffing.
+function pinOnlyDifference(shipped, installed) {
+    const installedPin = installed.match(PIN)?.[0];
+    if (installedPin === undefined)
+        return false;
+    return shipped.replace(PIN, installedPin) === installed;
+}
+// Revision 1: SYNC, not install-once. These files are witness's artifacts that happen
+// to live in the user's repo, and the engine file's pin is the single point deciding
+// which CLI version the entire pipeline runs — so an install-once rule pinned every repo
+// to whatever version first touched it, forever, with `payload: already installed`
+// printed on every attempt to fix it. A file the human actually edited is still theirs:
+// report it, never clobber it.
+export function installPayload(root, harness) {
+    const pre = preflightPayload(root, harness);
+    if (!pre.ok)
+        return refuse(pre.violations);
+    const out = { written: [], restamped: [], modified: [] };
+    for (const { from, to } of harness.payload) {
+        const src = join(packageRoot(), from);
+        if (!existsSync(src)) {
+            return refuse([v('payload', 'source-missing', from, 'a file shipped in the witness tarball — reinstall @popovych.co/witness')]);
+        }
+        const shipped = readFileSync(src, 'utf8');
+        const dst = join(root, to);
+        if (!existsSync(dst)) {
+            mkdirSync(dirname(dst), { recursive: true });
+            writeFileSync(dst, shipped);
+            out.written.push(to);
+            continue;
+        }
+        const installed = readFileSync(dst, 'utf8');
+        if (installed === shipped)
+            continue;
+        if (pinOnlyDifference(shipped, installed)) {
+            writeFileSync(dst, shipped);
+            out.restamped.push(to);
+            continue;
+        }
+        out.modified.push(to);
+    }
+    return ok(out);
+}
+function hasCommand(entries, command) {
+    return (entries ?? []).some((e) => (e.hooks ?? []).some((h) => h.command === command));
+}
+// Merge, never replace: .claude/settings.json is the human's file and may already carry
+// their own hooks, model pin and permissions. We append only what is missing, matched
+// by command string, and preserve every other key byte for byte.
+export function mergeSettings(existing) {
+    let doc = {};
+    if (existing !== undefined && existing.trim() !== '') {
+        try {
+            doc = JSON.parse(existing);
+        }
+        catch {
+            // Unparseable settings are the human's problem to fix; refusing to touch them is
+            // safer than rewriting them. Signal "no change" and let init report it.
+            return { text: existing, changed: false };
+        }
+    }
+    const hooks = (doc.hooks ?? {});
+    let changed = false;
+    const pre = [...(hooks.PreToolUse ?? [])];
+    for (const matcher of ['Edit|Write|MultiEdit', 'Bash']) {
+        if (!pre.some((e) => e.matcher === matcher && hasCommand([e], GUARD_CMD))) {
+            pre.push({ matcher, hooks: [{ type: 'command', command: GUARD_CMD }] });
+            changed = true;
+        }
+    }
+    const start = [...(hooks.SessionStart ?? [])];
+    if (!hasCommand(start, DASHBOARD_CMD)) {
+        start.push({ hooks: [{ type: 'command', command: DASHBOARD_CMD }] });
+        changed = true;
+    }
+    if (!changed)
+        return { text: existing ?? '', changed: false };
+    doc.hooks = { ...hooks, PreToolUse: pre, SessionStart: start };
+    return { text: `${JSON.stringify(doc, null, 2)}\n`, changed: true };
+}
+// The config rung of Decision 5's ladder. Recorded once, on the run that installs the
+// first payload set; a later `--agent` for a second harness leaves it alone, because
+// detection outranks it anyway and rewriting config is not what that run was asked for.
+export function recordHarness(configText, name) {
+    if (/^harness:/m.test(configText))
+        return { text: configText, changed: false };
+    const suffix = configText.endsWith('\n') ? '' : '\n';
+    return { text: `${configText}${suffix}harness: ${name}   # detection wins; this is the fallback\n`, changed: true };
+}
+export function writeSettings(root, rel, text) {
+    const p = join(root, rel);
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, text);
+}
+export function readIfExists(root, rel) {
+    const p = join(root, rel);
+    return existsSync(p) ? readFileSync(p, 'utf8') : undefined;
+}

package/dist/journal.js

@@ -0,0 +1,43 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+const dir = (root) => join(root, '.witness', 'journal');
+export const journalRel = (id) => `.witness/journal/${id}.jsonl`;
+export function streamExists(root, id) {
+    return existsSync(join(root, journalRel(id)));
+}
+export const entryLine = (entry) => JSON.stringify({ v: 1, ...entry });
+export function appendEntry(root, id, entry) {
+    mkdirSync(dir(root), { recursive: true });
+    const line = entryLine(entry);
+    appendFileSync(join(root, journalRel(id)), line + '\n');
+    return line;
+}
+export function readStream(root, id) {
+    if (!streamExists(root, id))
+        return [];
+    return readFileSync(join(root, journalRel(id)), 'utf8')
+        .split('\n')
+        .filter(Boolean)
+        .map((l) => JSON.parse(l));
+}
+export function latestRecap(root, effort) {
+    const recaps = readStream(root, effort).filter((e) => e.t === 'recap');
+    return recaps.at(-1);
+}
+export function effortStreams(root) {
+    if (!existsSync(dir(root)))
+        return [];
+    return readdirSync(dir(root))
+        .filter((f) => f.endsWith('.jsonl'))
+        .map((f) => f.slice(0, -'.jsonl'.length))
+        .filter((id) => readStream(root, id)[0]?.t === 'recap')
+        .sort();
+}
+export function effortAbandoned(entries) {
+    return entries.some((e) => e.t === 'human-decision' && e.decision === 'abandon-effort');
+}
+export function policyPins(entries) {
+    return entries
+        .filter((e) => e.t === 'policy-pin')
+        .map((e, i) => ({ ordinal: Number(e.ordinal ?? i + 1), text: String(e.text ?? '') }));
+}

package/dist/junit.js

@@ -0,0 +1,54 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { globToRegExp, walkFiles } from './glob.js';
+import { ok, refuse, v } from './refusal.js';
+const ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" };
+function decode(s) {
+    return s.replace(/&(#x?[0-9a-fA-F]+|[a-z]+);/g, (whole, e) => {
+        if (e.startsWith('#x') || e.startsWith('#X'))
+            return String.fromCodePoint(Number.parseInt(e.slice(2), 16));
+        if (e.startsWith('#'))
+            return String.fromCodePoint(Number.parseInt(e.slice(1), 10));
+        return ENTITIES[e] ?? whole;
+    });
+}
+function attrs(tag) {
+    const out = {};
+    for (const m of tag.matchAll(/([\w:-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g)) {
+        out[m[1] ?? ''] = decode(m[2] ?? m[3] ?? '');
+    }
+    return out;
+}
+export function parseJUnit(xml) {
+    const clean = xml.replace(/<!\[CDATA\[[\s\S]*?\]\]>/g, '').replace(/<!--[\s\S]*?-->/g, '');
+    const out = [];
+    const re = /<testcase\b([^>]*?)(\/)?>/g;
+    let m;
+    while ((m = re.exec(clean)) !== null) {
+        const a = attrs(m[1] ?? '');
+        let status = 'passed';
+        if (m[2] !== '/') {
+            const end = clean.indexOf('</testcase>', re.lastIndex);
+            const inner = clean.slice(re.lastIndex, end === -1 ? undefined : end);
+            if (/<(?:failure|error)\b/.test(inner))
+                status = 'failed';
+            else if (/<skipped\b/.test(inner))
+                status = 'skipped';
+            if (end !== -1)
+                re.lastIndex = end + '</testcase>'.length;
+        }
+        out.push({ name: a.name ?? '', classname: a.classname ?? '', status });
+    }
+    return out;
+}
+export function reportFiles(root, glob) {
+    const re = globToRegExp(glob);
+    return walkFiles(root).filter((f) => re.test(f));
+}
+export function mergeReports(root, glob) {
+    const files = reportFiles(root, glob);
+    if (files.length === 0) {
+        return refuse([v('criteria.report', 'no-reports', `junit:${glob} matched no files`, 'at least one report — did the suite run?')]);
+    }
+    return ok(files.flatMap((f) => parseJUnit(readFileSync(join(root, f), 'utf8'))));
+}

package/dist/lock.js

@@ -0,0 +1,37 @@
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ok, refuse, v } from './refusal.js';
+const lockPath = (root) => join(root, '.witness', 'lock');
+function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function acquireLock(root, pid = process.pid) {
+    mkdirSync(join(root, '.witness'), { recursive: true });
+    const p = lockPath(root);
+    const release = () => rmSync(p, { force: true });
+    try {
+        writeFileSync(p, JSON.stringify({ pid }), { flag: 'wx' });
+        return ok(release);
+    }
+    catch {
+        let holder;
+        try {
+            holder = JSON.parse(readFileSync(p, 'utf8')).pid;
+        }
+        catch {
+            holder = undefined;
+        }
+        if (holder !== undefined && holder !== pid && isAlive(holder)) {
+            return refuse([v('.witness/lock', 'locked', `held by pid ${holder}`, 'one clone, one writer — wait for the other witness invocation')]);
+        }
+        rmSync(p, { force: true });
+        writeFileSync(p, JSON.stringify({ pid }), { flag: 'wx' });
+        return ok(release);
+    }
+}

package/dist/matcher.js

@@ -0,0 +1,52 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { globToRegExp } from './glob.js';
+import { git } from './gitio.js';
+export function normalizeName(s) {
+    return s.toLowerCase().replace(/_/g, '-');
+}
+const CHARSET = /[a-z0-9-]/;
+const ALNUM = /[a-z0-9]/;
+export function matchesTag(testName, specId) {
+    const n = normalizeName(testName);
+    for (const form of [`@spec:${specId}`, `spec-${specId}`]) {
+        for (let i = n.indexOf(form); i !== -1; i = n.indexOf(form, i + 1)) {
+            const before = i === 0 ? undefined : n[i - 1];
+            const after = n[i + form.length];
+            const beforeOk = form.startsWith('@') || before === undefined || !ALNUM.test(before);
+            const afterOk = after === undefined || !CHARSET.test(after);
+            if (beforeOk && afterOk)
+                return true;
+        }
+    }
+    return false;
+}
+export function extractCanonicalTags(text) {
+    return [...text.matchAll(/@spec:([a-z0-9-]+)/g)].map((m) => m[1] ?? '').filter(Boolean);
+}
+const MAX_SCAN_BYTES = 512 * 1024;
+export function sourceTags(root, excludes) {
+    const res = { counts: new Map(), files: new Map() };
+    const skip = excludes.map(globToRegExp);
+    const listed = git(root, 'ls-files', '--cached', '--others', '--exclude-standard')
+        .split('\n')
+        .filter(Boolean);
+    for (const rel of new Set(listed)) {
+        if (skip.some((re) => re.test(rel)))
+            continue;
+        const abs = join(root, rel);
+        if (!existsSync(abs) || statSync(abs).size > MAX_SCAN_BYTES)
+            continue;
+        const content = readFileSync(abs, 'utf8');
+        if (content.includes('\0'))
+            continue;
+        for (const tag of extractCanonicalTags(content)) {
+            res.counts.set(tag, (res.counts.get(tag) ?? 0) + 1);
+            const list = res.files.get(tag) ?? [];
+            if (!list.includes(rel))
+                list.push(rel);
+            res.files.set(tag, list);
+        }
+    }
+    return res;
+}

package/dist/model.js

@@ -0,0 +1,73 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parse } from 'yaml';
+import { parsePin } from './pin.js';
+import { ok, refuse, v } from './refusal.js';
+export const MODEL_ALIASES = ['sonnet', 'opus', 'haiku', 'fable', 'default', 'latest'];
+export const SESSION_DEFAULT = 'session-default';
+export function shippedMatrixPath() {
+    return join(dirname(fileURLToPath(import.meta.url)), '..', 'calibration.yaml');
+}
+// Per-(harness, model) calibration (Decision 88): a pi-invoked reviewer on the same
+// model id is a DIFFERENT reviewer. Legacy top-level `models:` predates the harness
+// dimension and was only ever measured through claude -p — it reads as claude-code.
+function readModels(path, harness) {
+    if (!existsSync(path))
+        return [];
+    const doc = parse(readFileSync(path, 'utf8'));
+    const scoped = doc?.matrices?.[harness]?.models;
+    if (Array.isArray(scoped))
+        return scoped.map(String);
+    return harness === 'claude-code' && Array.isArray(doc?.models) ? doc.models.map(String) : [];
+}
+export function loadMatrix(root, harness) {
+    return {
+        shipped: readModels(shippedMatrixPath(), harness),
+        local: readModels(join(root, '.witness', 'calibration.local.yaml'), harness),
+    };
+}
+// the stage's model pin from config — per-gate wins over the global gates.model;
+// the same pin drives that stage's gate reviewers AND its worker agent (implement)
+export function stagePin(cfg, gate) {
+    const gates = (cfg.raw.gates ?? {});
+    const gateBlock = gate !== undefined && typeof gates[gate] === 'object' && gates[gate] !== null
+        ? gates[gate]
+        : undefined;
+    const pinRaw = gateBlock?.model ?? gates.model;
+    const pinField = gateBlock?.model !== undefined ? `gates.${gate}.model` : 'gates.model';
+    const pin = pinRaw === undefined ? undefined : String(pinRaw);
+    if (pin !== undefined) {
+        const parsed = parsePin(pinField, pin);
+        if (!parsed.ok)
+            return refuse(parsed.violations);
+        if (MODEL_ALIASES.includes(parsed.value.model)) {
+            return refuse([v(pinField, 'alias-refused', pin, 'an exact model id — aliases re-point under the calibration (Decision 55)')]);
+        }
+    }
+    return ok(pin);
+}
+export function resolveModel(cfg, matrix, gate) {
+    const pinR = stagePin(cfg, gate);
+    if (!pinR.ok)
+        return refuse(pinR.violations);
+    const pin = pinR.value;
+    const calibrated = [...matrix.shipped, ...matrix.local.filter((m) => !matrix.shipped.includes(m))];
+    const chain = [];
+    if (pin !== undefined)
+        chain.push(pin);
+    for (const m of calibrated)
+        if (!chain.includes(m))
+            chain.push(m);
+    chain.push(SESSION_DEFAULT);
+    const calibrationOf = (id) => matrix.shipped.includes(id) ? 'shipped' : matrix.local.includes(id) ? 'local' : 'none';
+    const head = chain[0];
+    const headLabel = head === SESSION_DEFAULT ? '(session default)' : head;
+    const matrixEmpty = matrix.shipped.length === 0 && matrix.local.length === 0;
+    const warning = calibrationOf(head) !== 'none'
+        ? undefined
+        : matrixEmpty
+            ? `calibration matrix is empty — no calibrated model exists yet; ${headLabel} runs uncalibrated`
+            : `reviewer model ${headLabel} is below the model floor — no calibration matrix entry covers it`;
+    return ok({ chain, calibrationOf, warning });
+}