@popovych.co/witness 0.4.0

package/dist/verbs/abandon.js

@@ -0,0 +1,105 @@
+import { EXIT } from '../cli.js';
+import { guardTxn } from '../txn.js';
+import { primaryRoot } from '../gitio.js';
+import { findById, loadCanon } from '../scan.js';
+import { effortAbandoned, latestRecap, readStream, streamExists } from '../journal.js';
+import { effortWrites } from '../reviewed.js';
+import { canonicalSha } from '../sha.js';
+import { renderRefusal, v } from '../refusal.js';
+import { kv } from '../toon.js';
+import { executeAbandon, planItems, specRevertFor } from '../abandon.js';
+export async function run(ctx, argv) {
+    const target = argv.find((a) => !a.startsWith('--'));
+    if (!target) {
+        ctx.err('usage: witness abandon <plan-id | effort-slug>');
+        return EXIT.REFUSED;
+    }
+    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 canon = loadCanon(root);
+    const doc = findById(canon, target);
+    if (doc && doc.meta.type === 'plan') {
+        if (String(doc.meta.status) === 'abandoned') {
+            ctx.out(kv('abandon', `${target} already abandoned`));
+            return EXIT.OK;
+        }
+        const itemR = planItems(root, canon, doc, new Set([target]), 'pair-parent');
+        if (!itemR.ok) {
+            renderRefusal(itemR.violations).forEach((l) => ctx.err(l));
+            return EXIT.REFUSED;
+        }
+        const done = executeAbandon(root, ctx, [itemR.value], undefined, `abandon(${target})`);
+        if (!done.ok) {
+            renderRefusal(done.violations).forEach((l) => ctx.err(l));
+            return EXIT.REFUSED;
+        }
+        ctx.out(kv('abandoned', target));
+        if (itemR.value.revert) {
+            ctx.out(kv('reverted', `${String(itemR.value.revert.doc.meta.id)} (${itemR.value.revert.action}) — journal untouched`));
+        }
+        return EXIT.OK;
+    }
+    if (streamExists(root, target) && latestRecap(root, target)) {
+        const entries = readStream(root, target);
+        if (effortAbandoned(entries)) {
+            ctx.out(kv('abandon', `${target} already abandoned`));
+            return EXIT.OK;
+        }
+        const writes = effortWrites(root, target);
+        const abandonSet = new Set(writes.keys());
+        const items = [];
+        const problems = [];
+        for (const id of writes.keys()) {
+            const artifact = findById(canon, id);
+            if (!artifact)
+                continue; // already gone (re-slice, earlier abandon)
+            if (artifact.meta.type !== 'plan')
+                continue;
+            // 'stamp-only': the spec loop below is this path's sole spec revert, pinned on
+            // THIS effort's write sha. A paired revert here would re-derive the owner and
+            // could land on a sibling effort's amendment — see Pairing in abandon.ts.
+            const itemR = planItems(root, canon, artifact, abandonSet, 'stamp-only');
+            if (!itemR.ok) {
+                problems.push(...itemR.violations);
+                continue;
+            }
+            items.push(itemR.value);
+        }
+        for (const [id, w] of writes) {
+            const artifact = findById(canon, id);
+            if (!artifact || artifact.meta.type !== 'spec')
+                continue;
+            if (canonicalSha(artifact.meta, artifact.body) !== w.sha) {
+                problems.push(v('spec', 'stacked-amendment', id, 'the effort\'s write is no longer the newest'));
+                continue;
+            }
+            const revertR = specRevertFor(root, canon, artifact, w.sha, abandonSet);
+            if (!revertR.ok) {
+                problems.push(...revertR.violations);
+                continue;
+            }
+            if (revertR.value)
+                items.push({ revert: revertR.value });
+        }
+        if (problems.length > 0) {
+            renderRefusal(problems).forEach((l) => ctx.err(l));
+            return EXIT.REFUSED;
+        }
+        const done = executeAbandon(root, ctx, items, { effort: target }, `abandon(${target})`);
+        if (!done.ok) {
+            renderRefusal(done.violations).forEach((l) => ctx.err(l));
+            return EXIT.REFUSED;
+        }
+        ctx.out(kv('abandoned', `effort ${target} — ${items.length} artifacts walked, journal remembers the attempt`));
+        return EXIT.OK;
+    }
+    renderRefusal([v('target', 'unknown-target', target, 'a plan id or an effort slug')]).forEach((l) => ctx.err(l));
+    return EXIT.REFUSED;
+}

package/dist/verbs/adopt.js

@@ -0,0 +1,118 @@
+import { join } from 'node:path';
+import { adoptedCommits, lastWitnessed, untrailedCommitsFor } from '../adopt.js';
+import { EXIT } from '../cli.js';
+import { canonPaths } from '../config.js';
+import { runCriteria } from '../criteria.js';
+import { clearDrift, stampDrift } from '../drift.js';
+import { readDoc } from '../fm.js';
+import { dirtyStatePaths, primaryRoot, stateCommit } from '../gitio.js';
+import { appendEntry, entryLine, journalRel } from '../journal.js';
+import { acquireLock } from '../lock.js';
+import { renderRefusal, v } from '../refusal.js';
+import { findById, findCycle, loadCanon } from '../scan.js';
+import { validateDoc } from '../schemas.js';
+import { canonicalSha, short } from '../sha.js';
+import { kv } from '../toon.js';
+import { crashPoint, guardTxn, withTxn } from '../txn.js';
+export async function run(ctx, argv) {
+    const [rel] = argv.filter((a) => !a.startsWith('--'));
+    const rootRes = primaryRoot(ctx.cwd);
+    if (!rootRes.ok) {
+        renderRefusal(rootRes.violations).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const root = rootRes.value;
+    const paths = canonPaths(root);
+    if (!rel || !(rel.startsWith(`${paths.specs}/`) || rel.startsWith(`${paths.plans}/`)) || !rel.endsWith('.md')) {
+        renderRefusal([v('path', 'usage', String(rel ?? ''), `witness adopt <${paths.specs}/... | ${paths.plans}/...>.md`)]).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const blocked = guardTxn(ctx, root);
+    if (blocked !== undefined)
+        return blocked;
+    const raw = readDoc(join(root, rel));
+    if (!raw.ok) {
+        renderRefusal(raw.violations).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const { meta, body } = raw.value;
+    const violations = validateDoc(meta, body);
+    const canon = loadCanon(root);
+    const id = String(meta.id);
+    if (canon.docs.filter((d) => String(d.meta.id) === id).length > 1) {
+        violations.push(v('id', 'duplicate-id', id, 'one doc per id'));
+    }
+    for (const dep of Array.isArray(meta.depends) ? meta.depends : []) {
+        if (!findById(canon, dep))
+            violations.push(v('depends', 'unknown-dep', dep, 'an existing doc id'));
+    }
+    const cycle = findCycle(canon);
+    if (cycle)
+        violations.push(v('depends', 'cycle', cycle.join(' -> '), 'an acyclic graph'));
+    if (violations.length) {
+        renderRefusal(violations).forEach(ctx.err);
+        ctx.err(`help: fix the file and re-run, or revert instead: git checkout HEAD -- ${rel}`);
+        return EXIT.REFUSED;
+    }
+    const witnessed = lastWitnessed(root, rel);
+    const currentSha = canonicalSha(meta, body);
+    const changed = witnessed?.sha !== currentSha;
+    const criteriaChanged = JSON.stringify(meta.criteria ?? null) !== JSON.stringify(witnessed?.criteria ?? null);
+    const commits = untrailedCommitsFor(root, rel).filter((sha) => !adoptedCommits(root).has(sha));
+    const dirty = dirtyStatePaths(root).includes(rel);
+    if (!changed && !dirty && commits.length === 0) {
+        ctx.out(kv('adopt', `${id}: nothing to adopt — content matches the last witnessed state`));
+        return EXIT.OK;
+    }
+    const doc = findById(canon, id);
+    const isLiveSpec = doc?.meta.type === 'spec' && doc.meta.status === 'live';
+    let reverify;
+    if (isLiveSpec && changed && doc) {
+        const lane = await runCriteria(root, ctx, doc);
+        if (!lane.ok) {
+            renderRefusal(lane.violations).forEach(ctx.err);
+            return EXIT.REFUSED;
+        }
+        reverify = { ok: lane.value.ok, criteria: lane.value.criteria };
+    }
+    const unreviewed = isLiveSpec && changed && !criteriaChanged;
+    const entry = {
+        t: 'adopt',
+        artifact: id,
+        sha: currentSha,
+        commits,
+        ...(reverify ? { reverify } : {}),
+        ...(unreviewed ? { unreviewed_amendment: true } : {}),
+    };
+    const flagTouched = doc && reverify !== undefined;
+    const files = [...new Set([...(dirty || flagTouched ? [rel] : []), journalRel(id)])];
+    const lock = acquireLock(root);
+    if (!lock.ok) {
+        renderRefusal(lock.violations).forEach(ctx.err);
+        return EXIT.BLOCKED;
+    }
+    try {
+        const marker = { op: `adopt(${id})`, files, journalMulti: [{ stream: id, line: entryLine(entry) }] };
+        const committed = withTxn(root, marker, () => {
+            if (doc && reverify && !reverify.ok)
+                stampDrift(root, doc, currentSha);
+            else if (doc && reverify?.ok && doc.meta.drift !== undefined)
+                clearDrift(root, doc);
+            appendEntry(root, id, entry);
+            crashPoint(ctx.env, 'adopt-journal');
+            return stateCommit(root, files, `adopt(${id}): ${short(currentSha)}`);
+        });
+        if (!committed.ok) {
+            renderRefusal(committed.violations).forEach(ctx.err);
+            return EXIT.REFUSED;
+        }
+    }
+    finally {
+        lock.ok && lock.value();
+    }
+    ctx.out(kv('adopt', `${id} · ${short(currentSha)} · ${commits.length} commit(s) absolved${unreviewed ? ' · unreviewed-amendment' : ''}`));
+    if (reverify)
+        ctx.out(kv('reverify', reverify.ok ? 'lane green — stays live' : 'lane RED — drift stamped immediately (hand-edit, no debounce)'));
+    ctx.out('help: history: witness log ' + id);
+    return reverify && !reverify.ok ? EXIT.FINDINGS : EXIT.OK;
+}

package/dist/verbs/calibrate.js

@@ -0,0 +1,130 @@
+import { EXIT } from '../cli.js';
+import { kv, rows } from '../toon.js';
+import { renderRefusal, v } from '../refusal.js';
+import { loadConfig } from '../config.js';
+import { resolveHarness } from '../harness.js';
+import { MODEL_ALIASES } from '../model.js';
+import { primaryRoot } from '../gitio.js';
+import { PROMPT_NAMES } from '../reviewer.js';
+import { addToLocalOverlay, publishScore, reportPass, runReviewerSuites, runSkillSuites, SKILL_NAMES, } from '../calibrate.js';
+export async function run(ctx, argv) {
+    const args = [...argv];
+    const flags = { suite: 'all', only: undefined, samples: 10, publish: false };
+    const positional = [];
+    while (args.length > 0) {
+        const a = args.shift();
+        if (a === '--suite')
+            flags.suite = args.shift() ?? '';
+        else if (a === '--only')
+            flags.only = args.shift();
+        else if (a === '--samples')
+            flags.samples = Number(args.shift() ?? '10');
+        else if (a === '--publish')
+            flags.publish = true;
+        else
+            positional.push(a);
+    }
+    const model = positional[0];
+    if (model === undefined || model === '') {
+        for (const line of renderRefusal([v('model', 'required', '', 'witness calibrate <exact-model-id>')]))
+            ctx.err(line);
+        return EXIT.REFUSED;
+    }
+    if (MODEL_ALIASES.includes(model)) {
+        for (const line of renderRefusal([v('model', 'alias-refused', model, 'an exact model id')]))
+            ctx.err(line);
+        return EXIT.REFUSED;
+    }
+    if (!['all', 'reviewers', 'skills'].includes(flags.suite)) {
+        for (const line of renderRefusal([v('--suite', 'unknown-suite', flags.suite, 'all | reviewers | skills')]))
+            ctx.err(line);
+        return EXIT.REFUSED;
+    }
+    let runReviewers = flags.suite === 'all' || flags.suite === 'reviewers';
+    let runSkills = flags.suite === 'all' || flags.suite === 'skills';
+    let reviewerOnly;
+    let skillOnly;
+    if (flags.only !== undefined) {
+        if (PROMPT_NAMES.includes(flags.only)) {
+            reviewerOnly = flags.only;
+            runReviewers = true;
+            runSkills = false;
+        }
+        else if (SKILL_NAMES.includes(flags.only)) {
+            skillOnly = flags.only;
+            runSkills = true;
+            runReviewers = false;
+        }
+        else {
+            const want = `reviewer: ${PROMPT_NAMES.join(' ')} · skill: ${SKILL_NAMES.join(' ')}`;
+            for (const line of renderRefusal([v('--only', 'unknown-name', flags.only, want)]))
+                ctx.err(line);
+            return EXIT.REFUSED;
+        }
+    }
+    const rootR = primaryRoot(ctx.cwd);
+    if (!rootR.ok) {
+        for (const line of renderRefusal(rootR.violations))
+            ctx.err(line);
+        return EXIT.REFUSED;
+    }
+    // Decision 88: calibration measures the (harness, model) pair — the same spawn the
+    // gate battery will use. Resolved once, threaded into every suite and the overlay.
+    const cfgR = loadConfig(rootR.value);
+    const hxR = resolveHarness(ctx.env, cfgR.ok ? cfgR.value.raw : {});
+    if (!hxR.ok) {
+        for (const line of renderRefusal(hxR.violations))
+            ctx.err(line);
+        return EXIT.REFUSED;
+    }
+    const harness = hxR.value.harness;
+    const reviewers = runReviewers ? await runReviewerSuites(ctx, harness, model, flags.samples, reviewerOnly) : undefined;
+    if (reviewers && !reviewers.ok) {
+        for (const line of renderRefusal(reviewers.violations))
+            ctx.err(line);
+        return EXIT.REFUSED;
+    }
+    const skills = runSkills ? await runSkillSuites(ctx, harness, model, flags.samples, { only: skillOnly }) : undefined;
+    if (skills && !skills.ok) {
+        for (const line of renderRefusal(skills.violations))
+            ctx.err(line);
+        return EXIT.REFUSED;
+    }
+    const report = { model, reviewers: reviewers?.value ?? [], skills: skills?.value ?? [] };
+    ctx.out(kv('calibrate', model));
+    if (report.reviewers.length > 0) {
+        for (const line of rows('reviewers', ['reviewer', 'catch', 'clean', 'inject', 'pass'], report.reviewers.map((s) => ({
+            reviewer: s.reviewer,
+            catch: `${s.catches.ok}/${s.catches.total}`,
+            clean: `${s.clean.ok}/${s.clean.total}`,
+            inject: s.inject.total === 0 ? '-' : `${s.inject.ok}/${s.inject.total}`,
+            pass: s.pass ? 'yes' : 'NO',
+        }))))
+            ctx.out(line);
+    }
+    if (report.skills.length > 0) {
+        for (const line of rows('skills', ['skill', 'metric', 'score', 'pass'], report.skills.map((s) => ({
+            skill: s.skill,
+            metric: s.metric,
+            score: `${s.ok}/${s.total}`,
+            pass: s.pass ? 'yes' : 'NO',
+        }))))
+            ctx.out(line);
+    }
+    const pass = reportPass(report);
+    ctx.out(kv('result', pass ? 'PASS' : 'FAIL'));
+    if (!pass)
+        return EXIT.FINDINGS;
+    addToLocalOverlay(rootR.value, model, harness.name);
+    ctx.out(kv('overlay', `.witness/calibration.local.yaml + ${harness.name}/${model} (gate-runs stamp calibration: local)`));
+    if (flags.publish) {
+        const pub = publishScore(rootR.value, model, report);
+        if (!pub.ok) {
+            for (const line of renderRefusal(pub.violations))
+                ctx.err(line);
+            return EXIT.REFUSED;
+        }
+        ctx.out(kv('published', pub.value.path));
+    }
+    return EXIT.OK;
+}

package/dist/verbs/check.js

@@ -0,0 +1,233 @@
+import { readdirSync, existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { adoptedCommits } from '../adopt.js';
+import { EXIT, version } from '../cli.js';
+import { HARNESSES, resolveHarness, skillsVisibility } from '../harness.js';
+import { probe } from '../probe.js';
+import { loadConfig } from '../config.js';
+import { designPending } from '../design.js';
+import { runDrift } from '../drift.js';
+import { auditStateCommits, dirtyStatePaths, primaryRoot } from '../gitio.js';
+import { contentAtSha } from '../history.js';
+import { effortStreams, readStream } from '../journal.js';
+import { sourceTags } from '../matcher.js';
+import { evaluateNeeds } from '../needs.js';
+import { renderRefusal } from '../refusal.js';
+import { pendingDecision } from '../rounds.js';
+import { criteriaExcludes } from '../runner.js';
+import { findById, findCycle, loadCanon } from '../scan.js';
+import { canonicalSha } from '../sha.js';
+import { lazyStamp } from '../stamp.js';
+import { kv, rows } from '../toon.js';
+import { pendingTxn } from '../txn.js';
+import { listWorktrees, worktreePath } from '../worktree.js';
+const f = (level, area, field, rule, detail) => ({ level, area, field, rule, detail });
+export async function run(ctx, argv = []) {
+    if (argv.includes('--drift'))
+        return runDrift(ctx, argv);
+    const rootRes = primaryRoot(ctx.cwd);
+    if (!rootRes.ok) {
+        renderRefusal(rootRes.violations).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const root = rootRes.value;
+    const findings = [];
+    const cfg = loadConfig(root);
+    if (!cfg.ok)
+        cfg.violations.forEach((x) => findings.push(f('error', 'config', x.field, x.rule, x.got)));
+    else if (cfg.value.warning)
+        findings.push(f('warn', 'config', 'schema', 'older-schema', cfg.value.warning));
+    const canon0 = loadCanon(root);
+    const lazy = lazyStamp(root, ctx, canon0);
+    const canon = lazy.stamped.length > 0 ? loadCanon(root) : canon0;
+    canon.errors.forEach((x) => findings.push(f('error', 'parse', x.field, x.rule, x.got)));
+    for (const doc of canon.docs) {
+        doc.violations.forEach((x) => findings.push(f('error', 'schema', `${doc.rel}: ${x.field}`, x.rule, x.got)));
+    }
+    const byId = new Map();
+    canon.docs.forEach((d) => byId.set(String(d.meta.id), (byId.get(String(d.meta.id)) ?? 0) + 1));
+    for (const [id, count] of byId) {
+        if (count > 1)
+            findings.push(f('error', 'graph', id, 'duplicate-id', `${count} docs carry this id`));
+    }
+    for (const doc of canon.docs) {
+        const depends = Array.isArray(doc.meta.depends) ? doc.meta.depends : [];
+        depends.forEach((dep) => {
+            if (!findById(canon, dep))
+                findings.push(f('error', 'graph', `${doc.rel}: depends`, 'unknown-dep', dep));
+        });
+    }
+    const cycle = findCycle(canon);
+    if (cycle)
+        findings.push(f('error', 'graph', 'depends', 'cycle', cycle.join(' -> ')));
+    for (const plan of canon.docs.filter((d) => d.meta.type === 'plan')) {
+        const parent = typeof plan.meta.parent === 'string' ? findById(canon, plan.meta.parent) : undefined;
+        if (!parent) {
+            findings.push(f('error', 'invariants', `${plan.rel}: parent`, 'unknown-parent', String(plan.meta.parent)));
+            continue;
+        }
+        if (plan.meta.status !== 'draft' && plan.meta.status !== 'abandoned' && parent.meta.status === 'draft') {
+            findings.push(f('error', 'invariants', `${plan.rel}: status`, 'status-pairing', `plan is ${plan.meta.status} but parent is draft`));
+        }
+        const pin = plan.meta['derives-from'];
+        if (typeof pin === 'string' && !contentAtSha(root, parent.rel, pin)) {
+            findings.push(f('error', 'invariants', `${plan.rel}: derives-from`, 'pin-unresolvable', `no committed version of ${parent.rel} matches ${pin.slice(0, 7)}`));
+        }
+    }
+    for (const plan of canon.docs.filter((d) => d.meta.type === 'plan')) {
+        const id = String(plan.meta.id);
+        if (String(plan.meta.status) === 'in-progress') {
+            const parent = findById(canon, String(plan.meta.parent));
+            if (parent && canonicalSha(parent.meta, parent.body) !== String(plan.meta['derives-from'])) {
+                findings.push(f('warn', 'motion', id, 'mid-flight-amendment', `parent ${String(parent.meta.id)} moved off the pin — ship will re-verify against current content`));
+            }
+            if (!existsSync(worktreePath(root, id))) {
+                findings.push(f('warn', 'motion', id, 'missing-worktree', `witness start ${id} recreates it`));
+            }
+        }
+        for (const gate of ['plan', 'implement', 'ship']) {
+            if (pendingDecision(readStream(root, id), gate)) {
+                findings.push(f('warn', 'motion', id, 'gate-awaiting-decision', `witness decide ${gate} ${id} --show`));
+            }
+        }
+    }
+    for (const slug of effortStreams(root)) {
+        if (pendingDecision(readStream(root, slug), 'decompose')) {
+            findings.push(f('warn', 'motion', slug, 'gate-awaiting-decision', `witness decide decompose ${slug} --show`));
+        }
+    }
+    for (const spec of canon.docs.filter((d) => d.meta.type === 'spec')) {
+        const id = String(spec.meta.id);
+        if (pendingDecision(readStream(root, id), 'design')) {
+            findings.push(f('warn', 'motion', id, 'gate-awaiting-decision', `witness decide design ${id} --show`));
+        }
+        if (designPending(root, spec) && String(spec.meta.status) === 'approved') {
+            findings.push(f('warn', 'motion', id, 'design-pending', `ui spec owes a design — witness design ${id} --file <html>`));
+        }
+    }
+    for (const planId of listWorktrees(root)) {
+        const doc = findById(canon, planId);
+        if (!doc || ['done', 'abandoned'].includes(String(doc.meta.status))) {
+            findings.push(f('warn', 'motion', planId, 'stray-worktree', 'witness clean sweeps it'));
+        }
+    }
+    for (const doc of canon.docs) {
+        const needs = Array.isArray(doc.meta.needs) ? doc.meta.needs : [];
+        if (needs.length === 0)
+            continue;
+        for (const r of await evaluateNeeds(root, ctx, needs)) {
+            if (r.status === 'ok')
+                continue;
+            const rule = r.status === 'unmet' ? 'need-unmet' : `need-${r.status}`;
+            findings.push(f('warn', 'needs', `${doc.rel}: ${r.label}`, rule, r.detail));
+        }
+    }
+    const absolved = adoptedCommits(root);
+    auditStateCommits(root).forEach((c) => {
+        if (!c.trailered && !absolved.has(c.sha)) {
+            findings.push(f('error', 'audit', c.sha.slice(0, 7), 'untrailered-commit', `${c.subject} — adopt: witness adopt <path> · or revert`));
+        }
+    });
+    if (pendingTxn(root)) {
+        findings.push(f('error', 'audit', '.witness/txn.json', 'pending-txn', 'crashed invocation — witness recover --complete | --rollback'));
+    }
+    else if (dirtyStatePaths(root).length) {
+        dirtyStatePaths(root).forEach((p) => findings.push(f('error', 'audit', p, 'hand-edit-in-progress', 'uncommitted change on a state path — adopt: witness adopt <path> · or revert')));
+    }
+    const journalDir = join(root, '.witness', 'journal');
+    if (existsSync(journalDir)) {
+        for (const file of readdirSync(journalDir)) {
+            if (!file.endsWith('.jsonl'))
+                continue;
+            const id = file.slice(0, -'.jsonl'.length);
+            const entries = readStream(root, id);
+            if (entries[0]?.t === 'recap')
+                continue;
+            if (!findById(canon, id))
+                findings.push(f('warn', 'journal', file, 'orphan-journal', 'stream matches no doc (frozen lineage or stray)'));
+        }
+    }
+    if (cfg.ok) {
+        const src = sourceTags(root, criteriaExcludes(cfg.value));
+        for (const [tag, files] of src.files) {
+            if (!findById(canon, tag)) {
+                findings.push(f('warn', 'criteria', tag, 'orphan-tag', `${files[0] ?? '?'} tags a spec that does not exist`));
+            }
+        }
+    }
+    if (!probe('gh', ['--version'], ctx.env))
+        findings.push(f('warn', 'probes', 'gh', 'missing', 'PR operations (later slice) will stop loudly'));
+    else if (!probe('gh', ['auth', 'status'], ctx.env))
+        findings.push(f('warn', 'probes', 'gh', 'unauthenticated', 'run gh auth login'));
+    if (cfg.ok) {
+        for (const [key, paths] of Object.entries(cfg.value.docs)) {
+            for (const p of paths ?? []) {
+                if (!existsSync(join(root, p))) {
+                    findings.push(f('error', 'config', `docs.${key}`, 'doc-missing', `${p} — gates inject configured docs fail-closed`));
+                }
+            }
+        }
+    }
+    // `harness:` is the config rung of the resolution ladder, consulted only when no
+    // detection rung answered — so a typo there is silent on the machine that has one.
+    // check is the diagnostic verb: it reports the value regardless of who answered.
+    const configuredHarness = cfg.ok ? cfg.value.raw.harness : undefined;
+    if (configuredHarness !== undefined && !HARNESSES.includes(String(configuredHarness))) {
+        findings.push(f('error', 'config', 'harness', 'unknown-harness', `${String(configuredHarness)} — expected ${HARNESSES.join(' | ')}`));
+    }
+    const hxR = resolveHarness(ctx.env, cfg.ok ? cfg.value.raw : {});
+    if (!hxR.ok) {
+        hxR.violations.forEach((x) => findings.push(f('error', 'harness', x.field, x.rule, x.got)));
+    }
+    else {
+        const harness = hxR.value.harness;
+        // Decision 88: the judgment lane runs on the RESOLVED harness — the probe follows it.
+        // (Decision 12 probed `claude` unconditionally; that was true only while every
+        // harness's reviewers were claude, and it is a false prerequisite for a pi user.)
+        if (!probe(harness.launch, ['--version'], ctx.env)) {
+            findings.push(f('warn', 'probes', harness.launch, 'missing', `the ${harness.launch} CLI runs this harness's gate reviewers — install and authenticate it`));
+        }
+        // Decision 14: pi resolves project skills cwd-relative with no upward walk, and
+        // implement runs with cwd inside .witness/worktrees/<plan-id>. A project-scope
+        // install therefore loses every skill in the stage that does the most work.
+        const visibility = skillsVisibility(ctx.env, root, harness);
+        if (visibility === 'project-only') {
+            findings.push(f('warn', 'harness', 'skills', 'skills-project-scope', `${harness.skills.project} is invisible from a worktree cwd — reinstall at global scope (${harness.skills.global} under $HOME)`));
+        }
+        else if (visibility === 'absent' && !harness.bundled) {
+            findings.push(f('warn', 'harness', 'skills', 'skills-not-installed', `${harness.name} sees none of the six stage skills — npx skills add <witness tarball url> at global scope`));
+        }
+        // Revision 3. Skills present + payload absent is the worst state in the design: the
+        // pipeline looks like it works, and nothing blocks a direct edit to canon. `bundled`
+        // is the same bit that silences the skills warning — Claude Code's marketplace plugin
+        // ships engine, guard and dashboard out of band, so absence there proves nothing.
+        const installed = harness.payload.map((p) => p.to).filter((rel) => existsSync(join(root, rel)));
+        if (installed.length === 0) {
+            if (!harness.bundled) {
+                findings.push(f('warn', 'harness', 'payload', 'payload-not-installed', `${harness.name} has no engine, guard or dashboard here — run witness init --agent ${harness.name}`));
+            }
+        }
+        else {
+            // Revision 1's other half: the sync can restamp, but only if someone knows to run
+            // it. The engine file's pin decides which CLI the whole pipeline runs, so a lagging
+            // pin is a finding, not a detail.
+            // The capture must be a semver and nothing else. Both payloads embed the pin as
+            // `${WITNESS_BIN:-npx -y @popovych.co/witness@<v>}`, so a trailing-delimiter
+            // class that omits `}` swallows the brace and NEVER equals version() — which made
+            // payload-stale fire on every fresh install until Task 9's manual pass caught it.
+            // Same shape as install.ts's PIN, deliberately.
+            const stale = installed.filter((rel) => {
+                const m = /@popovych\.co\/witness@(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/.exec(readFileSync(join(root, rel), 'utf8'));
+                return m !== null && m[1] !== version();
+            });
+            if (stale.length > 0) {
+                findings.push(f('warn', 'harness', 'payload', 'payload-stale', `${stale.join(' · ')} pin an older CLI than ${version()} — run witness init --agent ${harness.name} to restamp`));
+            }
+        }
+    }
+    const errors = findings.filter((x) => x.level === 'error');
+    if (findings.length)
+        rows('findings', ['level', 'area', 'field', 'rule', 'detail'], findings).forEach(ctx.out);
+    ctx.out(kv('checks', `${canon.docs.length} docs · ${auditStateCommits(root).length} commits audited · ${errors.length} errors`));
+    return errors.length ? EXIT.FINDINGS : EXIT.OK;
+}

package/dist/verbs/clean.js

@@ -0,0 +1,34 @@
+import { EXIT } from '../cli.js';
+import { primaryRoot } from '../gitio.js';
+import { findById, loadCanon } from '../scan.js';
+import { renderRefusal } from '../refusal.js';
+import { kv, rows } from '../toon.js';
+import { listWorktrees, removeWorktree } from '../worktree.js';
+export async function run(ctx, _argv) {
+    const rootR = primaryRoot(ctx.cwd);
+    if (!rootR.ok) {
+        renderRefusal(rootR.violations).forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
+    const root = rootR.value;
+    const canon = loadCanon(root);
+    const swept = [];
+    for (const planId of listWorktrees(root)) {
+        const doc = findById(canon, planId);
+        const status = doc ? String(doc.meta.status) : undefined;
+        if (!doc) {
+            removeWorktree(root, planId);
+            swept.push({ plan: planId, why: 'no such plan' });
+            continue;
+        }
+        if (status === 'done' || status === 'abandoned') {
+            removeWorktree(root, planId);
+            swept.push({ plan: planId, why: `plan is ${status}` });
+        }
+    }
+    if (swept.length)
+        ctx.out(rows('swept', ['plan', 'why'], swept).join('\n'));
+    else
+        ctx.out(kv('clean', 'no stray worktrees'));
+    return EXIT.OK;
+}