@popovych.co/witness 0.4.0

package/dist/verbs/rename.js

@@ -0,0 +1,99 @@
+import { join } from 'node:path';
+import { EXIT } from '../cli.js';
+import { loadConfig } from '../config.js';
+import { ID_RE } from '../dsl.js';
+import { writeDoc } from '../fm.js';
+import { guardTxn, withTxn } from '../txn.js';
+import { acquireLock } from '../lock.js';
+import { journalRel, streamExists } from '../journal.js';
+import { git, primaryRoot, stateCommit } from '../gitio.js';
+import { findById, loadCanon } from '../scan.js';
+import { criteriaExcludes } from '../runner.js';
+import { sourceTags } from '../matcher.js';
+import { renderRefusal, v } from '../refusal.js';
+import { kv } from '../toon.js';
+function rewriteRefs(meta, oldId, newId) {
+    const out = { ...meta };
+    if (Array.isArray(out.depends))
+        out.depends = out.depends.map((d) => (d === oldId ? newId : d));
+    if (out.parent === oldId)
+        out.parent = newId;
+    if (out.supersedes === oldId)
+        out.supersedes = newId;
+    return out;
+}
+export async function run(ctx, argv) {
+    const [oldId, newId] = argv.filter((a) => !a.startsWith('--'));
+    if (!oldId || !newId) {
+        ctx.err('usage: witness rename <old-id> <new-id>');
+        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, oldId);
+    if (!doc) {
+        renderRefusal([v('id', 'unknown-id', oldId, 'an existing canon doc')]).forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
+    if (!ID_RE.test(newId)) {
+        renderRefusal([v('id', 'id-charset', newId, 'ids match ^[a-z0-9-]+$')]).forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
+    if (findById(canon, newId) || streamExists(root, newId)) {
+        renderRefusal([v('id', 'id-taken', newId, 'an unused id (canon and journal)')]).forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
+    const touched = [];
+    const selfMeta = rewriteRefs({ ...doc.meta, id: newId }, oldId, newId);
+    if (Array.isArray(selfMeta.criteria)) {
+        selfMeta.criteria = selfMeta.criteria.map((c) => c.test === `@spec:${oldId}` ? { ...c, test: `@spec:${newId}` } : c);
+    }
+    const others = canon.docs.filter((d) => d !== doc).filter((d) => {
+        const deps = (d.meta.depends ?? []);
+        return deps.includes(oldId) || d.meta.parent === oldId || d.meta.supersedes === oldId;
+    });
+    const files = [doc.rel, ...others.map((d) => d.rel)];
+    const hadStream = streamExists(root, oldId);
+    if (hadStream)
+        files.push(journalRel(oldId), journalRel(newId));
+    const lockR = acquireLock(root);
+    if (!lockR.ok) {
+        renderRefusal(lockR.violations).forEach((l) => ctx.err(l));
+        return EXIT.BLOCKED;
+    }
+    try {
+        const txn = withTxn(root, { op: 'rename', files }, () => {
+            writeDoc(join(root, doc.rel), { meta: selfMeta, body: doc.body });
+            for (const d of others) {
+                writeDoc(join(root, d.rel), { meta: rewriteRefs(d.meta, oldId, newId), body: d.body });
+                touched.push(d);
+            }
+            if (hadStream)
+                git(root, 'mv', journalRel(oldId), journalRel(newId));
+            return stateCommit(root, files, `rename(${oldId} → ${newId})`);
+        });
+        if (!txn.ok) {
+            renderRefusal(txn.violations).forEach((l) => ctx.err(l));
+            return EXIT.REFUSED;
+        }
+    }
+    finally {
+        lockR.value();
+    }
+    ctx.out(kv('renamed', `${oldId} → ${newId} (${touched.length} referencing docs rewritten, journal moved)`));
+    const cfgR = loadConfig(root);
+    const excludes = cfgR.ok ? criteriaExcludes(cfgR.value) : [];
+    const stale = sourceTags(root, excludes).counts.get(oldId) ?? 0;
+    if (stale > 0) {
+        ctx.out(kv('warning', `${stale} source tag${stale === 1 ? '' : 's'} still reference @spec:${oldId} — update the tests (the CLI never edits code)`));
+    }
+    return EXIT.OK;
+}

package/dist/verbs/satisfy.js

@@ -0,0 +1,69 @@
+import { join } from 'node:path';
+import { parseArgs } from 'node:util';
+import { EXIT } from '../cli.js';
+import { writeDoc } from '../fm.js';
+import { primaryRoot, stateCommit } from '../gitio.js';
+import { acquireLock } from '../lock.js';
+import { renderRefusal, v } from '../refusal.js';
+import { findById, loadCanon } from '../scan.js';
+import { kv } from '../toon.js';
+import { guardTxn, withTxn } from '../txn.js';
+export async function run(ctx, argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        options: { need: { type: 'string' } },
+        allowPositionals: true,
+    });
+    const id = positionals[0];
+    if (!id || !values.need) {
+        renderRefusal([v('usage', 'required', 'missing id or --need', 'witness satisfy <doc-id> --need <text | index>')]).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 blocked = guardTxn(ctx, root);
+    if (blocked !== undefined)
+        return blocked;
+    const doc = findById(loadCanon(root), id);
+    if (!doc) {
+        renderRefusal([v('id', 'unknown-doc', id, 'a doc id from witness index')]).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const needs = Array.isArray(doc.meta.needs) ? doc.meta.needs : [];
+    const manuals = needs.filter((n) => typeof n.manual === 'string');
+    const byIndex = /^[0-9]+$/.test(values.need) ? manuals[Number(values.need) - 1] : undefined;
+    const target = byIndex ?? manuals.find((n) => n.manual === values.need);
+    if (!target) {
+        renderRefusal([v('--need', 'unknown-manual-need', values.need, `one of: ${manuals.map((m, i) => `${i + 1}='${m.manual}'`).join(' · ') || '(no manual needs)'}`)]).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    if (target.satisfied === true) {
+        ctx.out(kv('satisfy', `already satisfied: ${target.manual}`));
+        return EXIT.OK;
+    }
+    const lock = acquireLock(root);
+    if (!lock.ok) {
+        renderRefusal(lock.violations).forEach(ctx.err);
+        return EXIT.BLOCKED;
+    }
+    try {
+        target.satisfied = true;
+        const res = withTxn(root, { op: `satisfy(${id})`, files: [doc.rel] }, () => {
+            writeDoc(join(root, doc.rel), { meta: doc.meta, body: doc.body });
+            return stateCommit(root, [doc.rel], `satisfy(${id}): ${target.manual}`);
+        });
+        if (!res.ok) {
+            renderRefusal(res.violations).forEach(ctx.err);
+            return EXIT.REFUSED;
+        }
+        ctx.out(kv('satisfied', String(target.manual)));
+        return EXIT.OK;
+    }
+    finally {
+        lock.value();
+    }
+}

package/dist/verbs/ship.js

@@ -0,0 +1,11 @@
+import { EXIT } from '../cli.js';
+import '../gates/index.js';
+import { runShip } from '../ship.js';
+export async function run(ctx, argv) {
+    const planId = argv.find((a) => !a.startsWith('--'));
+    if (!planId) {
+        ctx.err('usage: witness ship <plan-id>');
+        return EXIT.REFUSED;
+    }
+    return runShip(ctx, planId);
+}

package/dist/verbs/start.js

@@ -0,0 +1,133 @@
+import { relative } from 'node:path';
+import { EXIT } from '../cli.js';
+import { loadConfig } from '../config.js';
+import { acquireLock } from '../lock.js';
+import { crashPoint, guardTxn, withTxn } from '../txn.js';
+import { journalRel } from '../journal.js';
+import { primaryRoot, stateCommit } from '../gitio.js';
+import { findById, loadCanon } from '../scan.js';
+import { evaluateNeeds } from '../needs.js';
+import { renderRefusal, v } from '../refusal.js';
+import { kv } from '../toon.js';
+import { prepareStamp, writeStamp } from '../stamp.js';
+import { SESSION_DEFAULT, stagePin } from '../model.js';
+import { branchName, createWorktree, worktreePath } from '../worktree.js';
+import { existsSync } from 'node:fs';
+export async function run(ctx, argv) {
+    const planId = argv.find((a) => !a.startsWith('--'));
+    if (!planId) {
+        ctx.err('usage: witness start <plan-id>');
+        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 cfgR = loadConfig(root);
+    if (!cfgR.ok) {
+        renderRefusal(cfgR.violations).forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
+    const canon = loadCanon(root);
+    const plan = findById(canon, planId);
+    if (!plan || plan.meta.type !== 'plan') {
+        renderRefusal([v('plan', 'unknown-plan', planId, 'a plans/ doc id')]).forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
+    const status = String(plan.meta.status);
+    const ship = (cfgR.value.raw.ship ?? {});
+    const base = ship.branch ?? 'main';
+    // the implement-stage pin drives the worker agent too — surfaced so the
+    // orchestrator dispatches the implementer on the configured model
+    const pinR = stagePin(cfgR.value, 'implement');
+    if (!pinR.ok) {
+        renderRefusal(pinR.violations).forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
+    const agentModel = pinR.value ?? SESSION_DEFAULT;
+    // Row 79: surface the run's shape so the implement skill reads the dispatch
+    // budget mechanically instead of guessing at relay boundaries.
+    const budget = cfgR.value.implement.stepsPerDispatch;
+    const stepCount = (plan.meta.steps ?? []).length;
+    const dispatchLine = `${stepCount} step(s) ≈ ${Math.ceil(stepCount / budget)} dispatch(es) at budget ${budget}`;
+    if (status === 'in-progress') {
+        const had = existsSync(worktreePath(root, planId));
+        const wt = createWorktree(root, planId, base);
+        if (!wt.ok) {
+            renderRefusal(wt.violations).forEach((l) => ctx.err(l));
+            return EXIT.REFUSED;
+        }
+        ctx.out(kv('start', `${planId} already in-progress — worktree ${had ? 'present' : 'recreated'}`));
+        ctx.out(kv('worktree', wt.value.path));
+        ctx.out(kv('agent-model', agentModel));
+        ctx.out(kv('dispatch-budget', String(budget)));
+        ctx.out(kv('dispatches', dispatchLine));
+        return EXIT.OK;
+    }
+    if (status !== 'approved') {
+        const rule = status === 'done' || status === 'abandoned' ? 'terminal-status' : 'not-approved';
+        renderRefusal([v('status', rule, status, 'an approved plan — run: witness gate plan ' + planId)]).forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
+    const deps = (plan.meta.depends ?? []);
+    const notReady = deps.filter((d) => {
+        const doc = findById(canon, d);
+        if (!doc)
+            return true;
+        const s = String(doc.meta.status);
+        return doc.meta.type === 'plan' ? s !== 'done' : s !== 'live';
+    });
+    if (notReady.length) {
+        renderRefusal([v('depends', 'blocked-deps', notReady.join(' '), 'spec deps live / plan deps done before implement starts')]).forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
+    const needs = await evaluateNeeds(root, ctx, (plan.meta.needs ?? []));
+    const unmet = needs.filter((n) => n.status !== 'ok');
+    if (unmet.length) {
+        renderRefusal([v('needs', 'needs-unmet', unmet.map((n) => n.label).join(' · '), 'all needs ok (witness check shows details; witness satisfy flips manual ones)')]).forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
+    const wt = createWorktree(root, planId, base);
+    if (!wt.ok) {
+        renderRefusal(wt.violations).forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
+    const stamp = prepareStamp(plan, 'in-progress', 'start', {
+        worktree: relative(root, wt.value.path), branch: branchName(planId),
+    });
+    const lockR = acquireLock(root);
+    if (!lockR.ok) {
+        renderRefusal(lockR.violations).forEach((l) => ctx.err(l));
+        return EXIT.BLOCKED;
+    }
+    try {
+        const txn = withTxn(root, {
+            op: 'start', files: [stamp.rel, journalRel(stamp.stream)],
+            journalMulti: [{ stream: stamp.stream, line: stamp.line }],
+        }, () => {
+            writeStamp(root, stamp);
+            crashPoint(ctx.env, 'start-commit');
+            return stateCommit(root, [stamp.rel, journalRel(stamp.stream)], `start(${planId}): worktree created`);
+        });
+        if (!txn.ok) {
+            renderRefusal(txn.violations).forEach((l) => ctx.err(l));
+            return EXIT.REFUSED;
+        }
+    }
+    finally {
+        lockR.value();
+    }
+    ctx.out(kv('start', `${planId} approved → in-progress`));
+    ctx.out(kv('worktree', wt.value.path));
+    ctx.out(kv('branch', branchName(planId)));
+    ctx.out(kv('agent-model', agentModel));
+    ctx.out(kv('dispatch-budget', String(budget)));
+    ctx.out(kv('dispatches', dispatchLine));
+    ctx.out(`help: implement inside the worktree; witness test-evidence ${planId} --phase red|green as you go`);
+    return EXIT.OK;
+}

package/dist/verbs/sync.js

@@ -0,0 +1,45 @@
+import { EXIT } from '../cli.js';
+import { guardTxn } from '../txn.js';
+import { acquireLock } from '../lock.js';
+import { primaryRoot, tryGit } from '../gitio.js';
+import { renderRefusal, v } from '../refusal.js';
+import { kv } from '../toon.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 blocked = guardTxn(ctx, root);
+    if (blocked !== undefined)
+        return blocked;
+    const lockR = acquireLock(root);
+    if (!lockR.ok) {
+        renderRefusal(lockR.violations).forEach((l) => ctx.err(l));
+        return EXIT.BLOCKED;
+    }
+    try {
+        const pull = tryGit(root, 'pull', '--rebase');
+        if (!pull.ok) {
+            if (/no tracking information|no such ref|does not appear to be a git repository/i.test(pull.out)) {
+                renderRefusal([v('remote', 'no-upstream', pull.out.trim().slice(0, 120), 'an upstream — git push -u origin main once, then witness sync')]).forEach((l) => ctx.err(l));
+                return EXIT.REFUSED;
+            }
+            tryGit(root, 'rebase', '--abort');
+            ctx.out(kv('sync', 'rebase conflict — resolve manually, then re-run witness sync'));
+            ctx.out(kv('detail', pull.out.trim().slice(-200)));
+            return EXIT.FINDINGS;
+        }
+        const push = tryGit(root, 'push');
+        if (!push.ok) {
+            ctx.out(kv('sync', `push failed: ${push.out.trim().slice(-200)}`));
+            return EXIT.FINDINGS;
+        }
+        ctx.out(kv('sync', 'pulled --rebase and pushed accumulated state commits'));
+        return EXIT.OK;
+    }
+    finally {
+        lockR.value();
+    }
+}