@popovych.co/witness 0.4.0

package/dist/verbs/design.js

@@ -0,0 +1,203 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { hostname, userInfo } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { EXIT } from '../cli.js';
+import { loadConfig } from '../config.js';
+import { designPending, designRel, designStamp, htmlSha, validateDesignArtifact } from '../design.js';
+import { writeDoc } from '../fm.js';
+import { dirtyStatePaths, primaryRoot, stateCommit } from '../gitio.js';
+import { appendEntry, entryLine, journalRel, latestRecap } from '../journal.js';
+import { acquireLock } from '../lock.js';
+import { openArtifact } from '../opener.js';
+import { renderRefusal, v } from '../refusal.js';
+import { effortOf } from '../reviewed.js';
+import { findById, loadCanon } from '../scan.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 { values, positionals } = parseArgs({
+        args: argv, allowPositionals: true,
+        options: { file: { type: 'string' }, reconfirm: { type: 'boolean' }, open: { type: 'boolean' } },
+    });
+    const specId = positionals[0];
+    if (!specId) {
+        ctx.err('usage: witness design <spec-id> --file <html> | --reconfirm | --open');
+        return EXIT.REFUSED;
+    }
+    const rootR = primaryRoot(ctx.cwd);
+    if (!rootR.ok) {
+        renderRefusal(rootR.violations).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const root = rootR.value;
+    const blocked = guardTxn(ctx, root);
+    if (blocked !== undefined)
+        return blocked;
+    const cfgR = loadConfig(root);
+    if (!cfgR.ok) {
+        renderRefusal(cfgR.violations).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const canon = loadCanon(root);
+    const spec = findById(canon, specId);
+    if (!spec || spec.meta.type !== 'spec') {
+        renderRefusal([v('spec', 'unknown-spec', specId, 'a specs/ doc id')]).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    if (values.open)
+        return openOnly(ctx, root, designRel(cfgR.value.paths, specId), specId);
+    if (spec.meta.ui !== true) {
+        renderRefusal([v('spec', 'not-ui', specId, 'a ui-flagged spec — set ui: true at decompose to earn a design stage')]).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const effort = effortOf(root, specId);
+    if (!effort || latestRecap(root, effort)?.class !== 'feature') {
+        renderRefusal([v('effort', 'not-feature', String(effort ?? 'none'), 'a feature-class effort — fix/chore specs ride straight to plan')]).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const rel = designRel(cfgR.value.paths, specId);
+    const stream = journalRel(specId);
+    const specSha = canonicalSha(spec.meta, spec.body);
+    const lock = acquireLock(root);
+    if (!lock.ok) {
+        renderRefusal(lock.violations).forEach(ctx.err);
+        return EXIT.BLOCKED;
+    }
+    try {
+        if (values.reconfirm)
+            return reconfirm(ctx, root, spec, specSha);
+        return persist(ctx, root, spec, effort, rel, stream, specSha, values.file);
+    }
+    finally {
+        lock.value();
+    }
+}
+// The one place anything is ever spawned at a human. Journals a sha-keyed witness that
+// `gate design`, `decide --approve` and `next` all consult. Deliberately reachable for
+// any registered artifact — re-showing a file that exists needs no ui/feature eligibility,
+// and gating it on those would dead-end the very refusals that point here.
+function openOnly(ctx, root, rel, id) {
+    const abs = join(root, rel);
+    if (!existsSync(abs)) {
+        renderRefusal([v('design', 'no-artifact', rel, `a registered design — run: witness design ${id} --file <html>`)]).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const sha = htmlSha(readFileSync(abs, 'utf8'));
+    const { outcome, command } = openArtifact(ctx.env, abs);
+    if (outcome === 'failed') {
+        renderRefusal([v('design', 'opener-failed', `${command} did not resolve`, `a working platform opener, or WITNESS_OPENER — meanwhile open it yourself: file://${abs}`)]).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    // `by` is the account and machine the spawn happened on — not a claim about who looked.
+    // It answers "was this shown on my box or someone else's" on a shared branch, which is
+    // the most the CLI can honestly know.
+    const by = `${userInfo().username}@${hostname()}`;
+    const stream = journalRel(id);
+    const entry = { t: 'design-shown', artifact: id, sha, opener: command, by };
+    const lock = acquireLock(root);
+    if (!lock.ok) {
+        renderRefusal(lock.violations).forEach(ctx.err);
+        return EXIT.BLOCKED;
+    }
+    try {
+        const res = withTxn(root, {
+            op: `design-open(${id})`, files: [stream], journal: { stream: id, line: entryLine(entry) },
+        }, () => {
+            appendEntry(root, id, entry);
+            crashPoint(ctx.env, 'design-shown');
+            return stateCommit(root, [stream], `design-shown(${id}): ${short(sha)}`);
+        });
+        if (!res.ok) {
+            renderRefusal(res.violations).forEach(ctx.err);
+            return EXIT.REFUSED;
+        }
+    }
+    finally {
+        lock.value();
+    }
+    ctx.out(kv('shown', id));
+    ctx.out(kv('path', rel));
+    ctx.out(kv('sha', short(sha)));
+    ctx.out(kv('opener', command));
+    ctx.out(`next: witness gate design ${id}`);
+    return EXIT.OK;
+}
+function persist(ctx, root, spec, effort, rel, stream, specSha, file) {
+    if (!file) {
+        renderRefusal([v('--file', 'required', 'absent', 'a scratch HTML file — or --reconfirm')]).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    let html;
+    try {
+        html = readFileSync(resolve(ctx.cwd, file), 'utf8');
+    }
+    catch (e) {
+        renderRefusal([v('--file', 'input-unreadable', String(e.message).slice(0, 120), 'a readable HTML file')]).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const problems = validateDesignArtifact(html);
+    if (problems.length) {
+        renderRefusal(problems).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const unrelated = dirtyStatePaths(root).filter((p) => p !== rel && p !== stream);
+    if (unrelated.length) {
+        renderRefusal(unrelated.map((p) => v(p, 'unrelated-dirty', 'uncommitted change on a state path', 'revert or adopt it, then re-run'))).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const sha = htmlSha(html);
+    const id = String(spec.meta.id);
+    const entry = { t: 'design-write', effort, artifact: id, sha, spec: specSha };
+    const res = withTxn(root, {
+        op: `design(${id})`, files: [rel, stream], journal: { stream: id, line: entryLine(entry) },
+    }, () => {
+        mkdirSync(join(root, dirname(rel)), { recursive: true });
+        writeFileSync(join(root, rel), html);
+        crashPoint(ctx.env, 'design-artifact');
+        appendEntry(root, id, entry);
+        crashPoint(ctx.env, 'design-journal');
+        return stateCommit(root, [rel, stream], `design(${id}): ${short(sha)}`);
+    });
+    if (!res.ok) {
+        renderRefusal(res.violations).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    ctx.out(kv('design', id));
+    ctx.out(kv('path', rel));
+    ctx.out(kv('sha', short(sha)));
+    ctx.out(`next: witness gate design ${id}`);
+    return EXIT.OK;
+}
+function reconfirm(ctx, root, spec, specSha) {
+    const id = String(spec.meta.id);
+    const stamp = designStamp(spec);
+    if (!stamp) {
+        renderRefusal([v('design', 'no-stamp', id, 'an approved design (witness gate design <id>) — nothing to reconfirm')]).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    if (!designPending(root, spec)) {
+        renderRefusal([v('design', 'not-pending', 'stamp already current', 'a stale stamp — reconfirm applies only after a feature amendment with no visual delta')]).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const stream = journalRel(id);
+    const nextMeta = { ...spec.meta, design: { sha: stamp.sha, spec: specSha } };
+    const entry = { t: 'design-reconfirm', artifact: id, sha: stamp.sha, spec: specSha };
+    const res = withTxn(root, {
+        op: `design-reconfirm(${id})`, files: [spec.rel, stream],
+        journal: { stream: id, line: entryLine(entry) },
+    }, () => {
+        writeDoc(join(root, spec.rel), { meta: nextMeta, body: spec.body });
+        appendEntry(root, id, entry);
+        crashPoint(ctx.env, 'design-reconfirm');
+        return stateCommit(root, [spec.rel, stream], `design-reconfirm(${id}): no visual delta`);
+    });
+    if (!res.ok) {
+        renderRefusal(res.violations).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    ctx.out(kv('reconfirmed', id));
+    ctx.out(kv('design', `re-pinned to ${short(specSha)} (artifact unchanged)`));
+    return EXIT.OK;
+}

package/dist/verbs/diff.js

@@ -0,0 +1,60 @@
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { EXIT } from '../cli.js';
+import { serializeDoc } from '../fm.js';
+import { primaryRoot, tryGit } from '../gitio.js';
+import { baseForSpec, contentAtSha } from '../history.js';
+import { renderRefusal, v } from '../refusal.js';
+import { findById, loadCanon } from '../scan.js';
+import { canonicalSha, short, VOLATILE_FIELDS } from '../sha.js';
+import { kv, rows } from '../toon.js';
+function canonicalRender(meta, body) {
+    const kept = Object.fromEntries(Object.entries(meta).filter(([k]) => !VOLATILE_FIELDS.includes(k)));
+    return serializeDoc({ meta: kept, body });
+}
+export async function run(ctx, argv) {
+    const id = argv[0];
+    if (!id) {
+        renderRefusal([v('id', 'required', 'absent', 'witness diff <spec-id>')]).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const rootRes = primaryRoot(ctx.cwd);
+    if (!rootRes.ok) {
+        renderRefusal(rootRes.violations).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const root = rootRes.value;
+    const canon = loadCanon(root);
+    const spec = findById(canon, id);
+    if (!spec || spec.meta.type !== 'spec') {
+        renderRefusal([v('id', 'unknown-spec', id, 'a spec id from witness index')]).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const current = canonicalSha(spec.meta, spec.body);
+    const base = baseForSpec(root, canon, id);
+    if (base.kind === 'empty') {
+        ctx.out(kv('base', 'empty (never realized)'));
+        ctx.out(kv('sha', short(current)));
+        ctx.out('delta: full content is the delta — new spec');
+        return EXIT.OK;
+    }
+    ctx.out(kv('base', `plan-pin ${base.planId} @ ${short(base.sha)}`));
+    if (base.sha === current) {
+        ctx.out('delta: none — no delta since the last plan');
+        return EXIT.OK;
+    }
+    const baseDoc = contentAtSha(root, spec.rel, base.sha);
+    if (!baseDoc) {
+        rows('findings', ['field', 'rule', 'detail'], [
+            { field: spec.rel, rule: 'pin-unresolvable', detail: `no committed version of ${id} hashes to ${short(base.sha)}` },
+        ]).forEach(ctx.out);
+        return EXIT.FINDINGS;
+    }
+    const tmp = mkdtempSync(join(tmpdir(), 'witness-diff-'));
+    writeFileSync(join(tmp, 'base.md'), canonicalRender(baseDoc.meta, baseDoc.body));
+    writeFileSync(join(tmp, 'current.md'), canonicalRender(spec.meta, spec.body));
+    const diff = tryGit(root, 'diff', '--no-index', '--', join(tmp, 'base.md'), join(tmp, 'current.md'));
+    ctx.out(diff.out);
+    return EXIT.OK;
+}

package/dist/verbs/dispatch.js

@@ -0,0 +1,102 @@
+import { EXIT } from '../cli.js';
+import { acquireLock } from '../lock.js';
+import { guardTxn, withTxn } from '../txn.js';
+import { appendEntry, entryLine, journalRel, readStream } from '../journal.js';
+import { primaryRoot, stateCommit } from '../gitio.js';
+import { loadConfig } from '../config.js';
+import { relayLine, resolveHarness } from '../harness.js';
+import { findById, loadCanon } from '../scan.js';
+import { renderRefusal, v } from '../refusal.js';
+import { kv } from '../toon.js';
+const FLAGS = ['--steps-assigned', '--steps-completed', '--tokens', '--tool-uses', '--duration-ms'];
+function intFlag(argv, flag, violations, required) {
+    const at = argv.indexOf(flag);
+    if (at === -1) {
+        if (required)
+            violations.push(v(flag.slice(2), 'required', 'absent', 'a non-negative integer'));
+        return undefined;
+    }
+    const n = Number(argv[at + 1]);
+    if (!Number.isInteger(n) || n < 0) {
+        violations.push(v(flag.slice(2), 'invalid', String(argv[at + 1]), 'a non-negative integer'));
+        return undefined;
+    }
+    return n;
+}
+// Row 81: telemetry, not evidence. The numbers are the orchestrator's report of the
+// Agent-tool return block — labeled reported, and no gate may ever consume this entry.
+export async function run(ctx, argv) {
+    const planId = argv.find((a) => !a.startsWith('--') && !FLAGS.includes(argv[argv.indexOf(a) - 1]));
+    const violations = [];
+    const assigned = intFlag(argv, '--steps-assigned', violations, true);
+    const completed = intFlag(argv, '--steps-completed', violations, true);
+    const tokens = intFlag(argv, '--tokens', violations, false);
+    const toolUses = intFlag(argv, '--tool-uses', violations, false);
+    const durationMs = intFlag(argv, '--duration-ms', violations, false);
+    if (!planId)
+        violations.push(v('plan-id', 'required', 'absent', 'witness dispatch-report <plan-id> --steps-assigned <n> --steps-completed <n>'));
+    if (violations.length) {
+        renderRefusal(violations).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const rootR = primaryRoot(ctx.cwd);
+    if (!rootR.ok) {
+        renderRefusal(rootR.violations).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const root = rootR.value;
+    const blocked = guardTxn(ctx, root);
+    if (blocked !== undefined)
+        return blocked;
+    const plan = findById(loadCanon(root), planId);
+    if (!plan || plan.meta.type !== 'plan') {
+        renderRefusal([v('plan-id', 'unknown-plan', planId, 'an existing plan id')]).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const lock = acquireLock(root);
+    if (!lock.ok) {
+        renderRefusal(lock.violations).forEach(ctx.err);
+        return EXIT.BLOCKED;
+    }
+    try {
+        const ordinal = readStream(root, planId).filter((e) => e.t === 'dispatch').length + 1;
+        const usage = tokens !== undefined || toolUses !== undefined || durationMs !== undefined
+            ? {
+                ...(tokens !== undefined ? { tokens } : {}),
+                ...(toolUses !== undefined ? { tool_uses: toolUses } : {}),
+                ...(durationMs !== undefined ? { duration_ms: durationMs } : {}),
+            }
+            : undefined;
+        const entry = {
+            t: 'dispatch', plan: planId, ordinal,
+            steps_assigned: assigned, steps_completed: completed,
+            ...(usage ? { usage } : {}), reported: true,
+        };
+        const marker = {
+            op: `dispatch-report(${planId})`,
+            files: [journalRel(planId)],
+            journalMulti: [{ stream: planId, line: entryLine(entry) }],
+        };
+        const txn = withTxn(root, marker, () => {
+            appendEntry(root, planId, entry);
+            return stateCommit(root, marker.files, marker.op);
+        });
+        if (!txn.ok) {
+            renderRefusal(txn.violations).forEach(ctx.err);
+            return EXIT.REFUSED;
+        }
+        ctx.out(kv('dispatch', `${planId} · #${ordinal} · ${completed}/${assigned} step(s)`));
+        // The relay is a session-boundary fact the skill must not hardcode: /clear on
+        // Claude Code, /new on Pi. A broken config must not cost the telemetry entry that
+        // was already journalled, so an unresolvable harness simply omits the line and the
+        // skill stops for the human.
+        const cfgR = loadConfig(root);
+        const hxR = resolveHarness(ctx.env, cfgR.ok ? cfgR.value.raw : {});
+        if (hxR.ok)
+            ctx.out(kv('relay', relayLine(hxR.value.harness)));
+        return EXIT.OK;
+    }
+    finally {
+        lock.ok && lock.value();
+    }
+}

package/dist/verbs/evidence.js

@@ -0,0 +1,118 @@
+import { EXIT } from '../cli.js';
+import { checkoutRoot, diffBase, recordEvidence, verifyRed } from '../evidence.js';
+import { loadConfig } from '../config.js';
+import { primaryRoot } from '../gitio.js';
+import { renderRefusal, v } from '../refusal.js';
+import { findById, loadCanon } from '../scan.js';
+import { kv } from '../toon.js';
+import { guardTxn } from '../txn.js';
+import { acquireLock } from '../lock.js';
+export async function run(ctx, argv) {
+    const [planId] = argv.filter((a) => !a.startsWith('--'));
+    const phase = argv[argv.indexOf('--phase') + 1];
+    if (!planId || (phase !== 'red' && phase !== 'green')) {
+        renderRefusal([v('args', 'usage', argv.join(' '), 'witness test-evidence <plan-id> --phase red|green')]).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const runRootRes = checkoutRoot(ctx.cwd);
+    const stateRootRes = primaryRoot(ctx.cwd);
+    if (!runRootRes.ok || !stateRootRes.ok) {
+        renderRefusal([...(runRootRes.ok ? [] : runRootRes.violations), ...(stateRootRes.ok ? [] : stateRootRes.violations)]).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const stateRoot = stateRootRes.value;
+    const blocked = guardTxn(ctx, stateRoot);
+    if (blocked !== undefined)
+        return blocked;
+    const plan = findById(loadCanon(stateRoot), planId);
+    if (!plan || plan.meta.type !== 'plan') {
+        renderRefusal([v('plan-id', 'unknown-plan', planId, 'an existing plan id')]).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const parentId = String(plan.meta.parent);
+    const lock = acquireLock(stateRoot);
+    if (!lock.ok) {
+        renderRefusal(lock.violations).forEach(ctx.err);
+        return EXIT.BLOCKED;
+    }
+    try {
+        const probe = await recordEvidence(runRootRes.value, stateRoot, ctx, planId, parentId, phase);
+        if (!probe.ok) {
+            renderRefusal(probe.violations).forEach(ctx.err);
+            return EXIT.REFUSED;
+        }
+        const { allOk, tests } = probe.value;
+        ctx.out(kv('test-evidence', `${planId} · ${phase} · ${tests.length} outcome(s) · ${allOk ? 'all green' : 'red present'}`));
+        if (phase === 'red' && allOk) {
+            ctx.err('vacuous: tests pass before implementation — the test may assert nothing, or the behavior already exists');
+            return EXIT.FINDINGS;
+        }
+        if (phase === 'green' && !allOk) {
+            ctx.err('not green — fix the implementation and re-run');
+            return EXIT.FINDINGS;
+        }
+        return EXIT.OK;
+    }
+    finally {
+        lock.ok && lock.value();
+    }
+}
+export async function runVerifyRed(ctx, argv) {
+    const [planId] = argv.filter((a) => !a.startsWith('--'));
+    const baseArg = argv.includes('--base') ? argv[argv.indexOf('--base') + 1] : undefined;
+    if (!planId) {
+        renderRefusal([v('args', 'usage', argv.join(' '), 'witness verify-red <plan-id> [--base <ref>]')]).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const runRootRes = checkoutRoot(ctx.cwd);
+    const stateRootRes = primaryRoot(ctx.cwd);
+    if (!runRootRes.ok || !stateRootRes.ok) {
+        renderRefusal([...(runRootRes.ok ? [] : runRootRes.violations), ...(stateRootRes.ok ? [] : stateRootRes.violations)]).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const stateRoot = stateRootRes.value;
+    const blocked = guardTxn(ctx, stateRoot);
+    if (blocked !== undefined)
+        return blocked;
+    const plan = findById(loadCanon(stateRoot), planId);
+    if (!plan || plan.meta.type !== 'plan') {
+        renderRefusal([v('plan-id', 'unknown-plan', planId, 'an existing plan id')]).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const cfg = loadConfig(runRootRes.value);
+    if (!cfg.ok) {
+        renderRefusal(cfg.violations).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const base = diffBase(runRootRes.value, cfg.value, baseArg);
+    if (!base.ok) {
+        renderRefusal(base.violations).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const lock = acquireLock(stateRoot);
+    if (!lock.ok) {
+        renderRefusal(lock.violations).forEach(ctx.err);
+        return EXIT.BLOCKED;
+    }
+    try {
+        const res = await verifyRed(runRootRes.value, stateRoot, ctx, planId, String(plan.meta.parent), base.value);
+        if (!res.ok) {
+            renderRefusal(res.violations).forEach(ctx.err);
+            return EXIT.REFUSED;
+        }
+        const { redOk, greenOk, vacuous } = res.value;
+        ctx.out(kv('verify-red', `red ${redOk ? 'observed' : 'NOT observed'} · green ${greenOk ? 'confirmed' : 'NOT confirmed'}`));
+        if (vacuous) {
+            ctx.err('vacuous: tests pass against base — the test may assert nothing, or the behavior already existed');
+            return EXIT.FINDINGS;
+        }
+        if (!greenOk) {
+            ctx.err('suite not green after restore — repository state was restored; investigate before trusting this diff');
+            return EXIT.FINDINGS;
+        }
+        return EXIT.OK;
+    }
+    finally {
+        lock.ok && lock.value();
+    }
+}

package/dist/verbs/gate.js

@@ -0,0 +1,12 @@
+import { EXIT } from '../cli.js';
+import '../gates/index.js';
+import { runGate } from '../gate.js';
+export async function run(ctx, argv) {
+    const positional = argv.filter((a) => !a.startsWith('--'));
+    const [gate, target] = positional;
+    if (!gate || !target) {
+        ctx.err('usage: witness gate <decompose|plan|implement|ship|design> <target> [--fresh] [--manual]');
+        return EXIT.REFUSED;
+    }
+    return runGate(ctx, gate, target, { fresh: argv.includes('--fresh'), manual: argv.includes('--manual') });
+}

package/dist/verbs/index-verb.js

@@ -0,0 +1,34 @@
+import { dirname } from 'node:path';
+import { EXIT } from '../cli.js';
+import { primaryRoot } from '../gitio.js';
+import { renderRefusal } from '../refusal.js';
+import { loadCanon } from '../scan.js';
+import { rows } from '../toon.js';
+export async function run(ctx) {
+    const rootRes = primaryRoot(ctx.cwd);
+    if (!rootRes.ok) {
+        renderRefusal(rootRes.violations).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const canon = loadCanon(rootRes.value);
+    const specs = canon.docs.filter((d) => d.rel.startsWith(`${canon.paths.specs}/`));
+    const groups = new Map();
+    for (const doc of specs) {
+        const dir = dirname(doc.rel);
+        if (!groups.has(dir))
+            groups.set(dir, []);
+        groups.get(dir).push(doc);
+    }
+    for (const dir of [...groups.keys()].sort()) {
+        const items = groups.get(dir).sort((a, b) => String(a.meta.id).localeCompare(String(b.meta.id)));
+        rows(dir, ['id', 'summary', 'ui', 'status', 'depends'], items.map((d) => ({
+            id: d.meta.id,
+            summary: d.meta.summary ?? '',
+            ui: d.meta.ui === true ? 'ui' : '',
+            status: d.meta.status,
+            depends: Array.isArray(d.meta.depends) ? d.meta.depends.join(' ') : '',
+        }))).forEach(ctx.out);
+    }
+    ctx.out('help: witness diff <id> · witness log <id>');
+    return EXIT.OK;
+}