@popovych.co/witness 0.4.0

package/calibration/skills/implement/seeds/s3-two-steps/plan.body.md

@@ -0,0 +1,11 @@
+## Step: s1
+
+Failing test first in `tests/pad.test.mjs` — name carries `@spec:pad-strings`;
+assert `padLeft("7", 3, "0")` equals `"007"` and `padLeft("777", 2, "0")`
+equals `"777"` (unchanged). Then implement `padLeft` in `src/pad.mjs`; green.
+
+## Step: s2
+
+Failing test — name carries `@spec:pad-strings`; assert `padRight("7", 3, "0")`
+equals `"700"` and `padRight("777", 2, "0")` equals `"777"` (unchanged). Then
+implement `padRight` in `src/pad.mjs`; green.

package/calibration/skills/implement/seeds/s3-two-steps/plan.meta.json

@@ -0,0 +1,10 @@
+{
+  "type": "plan",
+  "parent": "pad-strings",
+  "depends": [],
+  "needs": [],
+  "steps": [
+    { "id": "s1", "title": "implement padLeft with TDD", "criteria": ["ac-left"] },
+    { "id": "s2", "title": "implement padRight with TDD", "criteria": ["ac-right"] }
+  ]
+}

package/calibration/skills/implement/seeds/s3-two-steps/recap.json

@@ -0,0 +1,8 @@
+{
+  "effort": "cal-implement",
+  "class": "feature",
+  "goals": [{ "id": "g1", "text": "The promised utility behavior exists with tagged tests" }],
+  "non_goals": [],
+  "constraints": [],
+  "slices": []
+}

package/calibration/skills/implement/seeds/s3-two-steps/repo/package.json

@@ -0,0 +1 @@
+{ "name": "cal-implement-s3", "type": "module", "private": true }

package/calibration/skills/implement/seeds/s3-two-steps/repo/src/pad.mjs

@@ -0,0 +1,2 @@
+// padLeft/padRight are promised by the pad-strings spec — not implemented yet.
+export {};

package/calibration/skills/implement/seeds/s3-two-steps/spec.body.md

@@ -0,0 +1,9 @@
+## Motivation
+
+Fixed-width columns line up in monospace output (g1).
+
+## Behavior
+
+`padLeft(str, width, ch)` pads `str` on the left with `ch` until it reaches
+`width` characters, unchanged if already at or past `width` (ac-left).
+`padRight(str, width, ch)` does the same on the right (ac-right).

package/calibration/skills/implement/seeds/s3-two-steps/spec.meta.json

@@ -0,0 +1,11 @@
+{
+  "type": "spec",
+  "summary": "Strings pad to a fixed width on either side",
+  "depends": [],
+  "needs": [],
+  "criteria": [
+    { "id": "ac-left", "test": "@spec:pad-strings" },
+    { "id": "ac-right", "test": "@spec:pad-strings" }
+  ],
+  "covers": ["g1"]
+}

package/calibration/skills/plan/seeds/s1-two-criteria/expect.json

@@ -0,0 +1 @@
+{ "defect": "none — two-criterion mapping; measures unaided step totality" }

package/calibration/skills/plan/seeds/s1-two-criteria/parent.body.md

@@ -0,0 +1,10 @@
+## Motivation
+
+Slugs appear in every shared URL (g1).
+
+## Behavior
+
+`slugify(title)` lowercases, replaces whitespace runs with single hyphens,
+strips characters outside `[a-z0-9-]`, and collapses repeated hyphens. Slugs
+are capped at 80 characters without cutting mid-word where possible (ac-len's
+suite asserts the cap; the cap value lives here: 80).

package/calibration/skills/plan/seeds/s1-two-criteria/parent.meta.json

@@ -0,0 +1,11 @@
+{
+  "type": "spec",
+  "summary": "Titles convert to lowercase URL-safe slugs",
+  "depends": [],
+  "needs": [],
+  "criteria": [
+    { "id": "ac-fmt", "test": "@spec:slug-format" },
+    { "id": "ac-len", "cmd": "node --test --test-name-pattern \"@spec:slug-format\" tests/" }
+  ],
+  "covers": ["g1"]
+}

package/calibration/skills/plan/seeds/s1-two-criteria/recap.json

@@ -0,0 +1,8 @@
+{
+  "effort": "slugify",
+  "class": "feature",
+  "goals": [{ "id": "g1", "text": "Titles convert to URL-safe slugs" }],
+  "non_goals": [{ "id": "n1", "text": "No transliteration of non-Latin scripts" }],
+  "constraints": [],
+  "slices": ["slugify"]
+}

package/calibration/skills/plan/seeds/s2-five-criteria/expect.json

@@ -0,0 +1 @@
+{ "defect": "none — five-way mapping stresses totality" }

package/calibration/skills/plan/seeds/s2-five-criteria/parent.body.md

@@ -0,0 +1,11 @@
+## Motivation
+
+Weak passwords are the largest account-takeover vector (g1).
+
+## Behavior
+
+A password is accepted only if it satisfies every rule: at least 12
+characters (ac-min); at least one uppercase letter (ac-upper); at least one
+digit (ac-digit); not present in the top-1000 common-passwords list shipped
+at `data/common-passwords.txt` (ac-common). The full policy suite runs as one
+filtered command (ac-suite).

package/calibration/skills/plan/seeds/s2-five-criteria/parent.meta.json

@@ -0,0 +1,14 @@
+{
+  "type": "spec",
+  "summary": "Passwords are validated against the published policy",
+  "depends": [],
+  "needs": [],
+  "criteria": [
+    { "id": "ac-min", "test": "@spec:password-policy" },
+    { "id": "ac-upper", "test": "@spec:password-policy" },
+    { "id": "ac-digit", "test": "@spec:password-policy" },
+    { "id": "ac-common", "test": "@spec:password-policy" },
+    { "id": "ac-suite", "cmd": "node --test --test-name-pattern \"@spec:password-policy\" tests/" }
+  ],
+  "covers": ["g1"]
+}

package/calibration/skills/plan/seeds/s2-five-criteria/recap.json

@@ -0,0 +1,8 @@
+{
+  "effort": "password-rules",
+  "class": "feature",
+  "goals": [{ "id": "g1", "text": "Passwords are validated against the published policy" }],
+  "non_goals": [],
+  "constraints": [],
+  "slices": ["password policy validation"]
+}

package/calibration/skills/plan/seeds/s3-mixed-needs/expect.json

@@ -0,0 +1 @@
+{ "defect": "none — needs entry must survive into the plan's world untouched" }

package/calibration/skills/plan/seeds/s3-mixed-needs/parent.body.md

@@ -0,0 +1,10 @@
+## Motivation
+
+Receivers need to trust that a webhook actually came from us (g1).
+
+## Behavior
+
+Every outbound webhook carries an `X-Hook-Signature` header: hex-encoded
+HMAC-SHA256 of the raw request body, keyed by `WEBHOOK_SIGNING_KEY` (ac-sign).
+A receiver recomputing the same HMAC over the same body and key must match
+byte-for-byte, and a tampered body must fail verification (ac-verify).

package/calibration/skills/plan/seeds/s3-mixed-needs/parent.meta.json

@@ -0,0 +1,11 @@
+{
+  "type": "spec",
+  "summary": "Outbound webhooks are HMAC-signed and verifiable",
+  "depends": [],
+  "needs": [{ "env": "WEBHOOK_SIGNING_KEY" }],
+  "criteria": [
+    { "id": "ac-sign", "test": "@spec:webhook-signatures" },
+    { "id": "ac-verify", "test": "@spec:webhook-signatures" }
+  ],
+  "covers": ["g1"]
+}

package/calibration/skills/plan/seeds/s3-mixed-needs/recap.json

@@ -0,0 +1,8 @@
+{
+  "effort": "webhook-signing",
+  "class": "feature",
+  "goals": [{ "id": "g1", "text": "Outbound webhooks are HMAC-signed and verifiable" }],
+  "non_goals": [],
+  "constraints": [],
+  "slices": ["webhook signing"]
+}

package/calibration/skills/plan/seeds/s4-scaffolding-pull/expect.json

@@ -0,0 +1 @@
+{ "defect": "tempts an unmapped rigging step — write refuses it unless honestly marked scaffolding" }

package/calibration/skills/plan/seeds/s4-scaffolding-pull/parent.body.md

@@ -0,0 +1,9 @@
+## Motivation
+
+Long-lived access tokens widen the theft window (g1).
+
+## Behavior
+
+An access token issued at time T is rejected by every endpoint from T+15
+minutes onward (ac-expiry). Testing this without real sleeps requires a
+controllable clock the test suite can advance deterministically.

package/calibration/skills/plan/seeds/s4-scaffolding-pull/parent.meta.json

@@ -0,0 +1,10 @@
+{
+  "type": "spec",
+  "summary": "Access tokens expire after 15 minutes",
+  "depends": [],
+  "needs": [],
+  "criteria": [
+    { "id": "ac-expiry", "test": "@spec:token-expiry" }
+  ],
+  "covers": ["g1"]
+}

package/calibration/skills/plan/seeds/s4-scaffolding-pull/recap.json

@@ -0,0 +1,8 @@
+{
+  "effort": "expiry-windows",
+  "class": "feature",
+  "goals": [{ "id": "g1", "text": "Access tokens expire after 15 minutes" }],
+  "non_goals": [],
+  "constraints": [],
+  "slices": ["token expiry"]
+}

package/calibration.yaml

@@ -0,0 +1,5 @@
+# witness shipped calibration matrix.
+# Populated by `witness calibrate <model>` at release time (Plan 4).
+# Until then no model is calibrated: every gate-run stamps calibration: "none"
+# and the dashboard warns below-floor — which is the truth.
+models: []

package/dist/abandon.js

@@ -0,0 +1,154 @@
+import { unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { splitDoc } from './fm.js';
+import { canonicalSha } from './sha.js';
+import { tryGit, stateCommit } from './gitio.js';
+import { acquireLock } from './lock.js';
+import { crashPoint, withTxn } from './txn.js';
+import { appendEntry, entryLine, journalRel } from './journal.js';
+import { findById } from './scan.js';
+import { effortOf, effortWrites } from './reviewed.js';
+import { ok, refuse, v } from './refusal.js';
+import { prepareStamp, writeStamp } from './stamp.js';
+import { removeWorktree } from './worktree.js';
+export function pinCommit(root, rel, pin) {
+    const log = tryGit(root, 'log', '--format=%H', '--', rel);
+    if (!log.ok)
+        return undefined;
+    // Status-only touch-ups (approve, stampLive, a gate's writeStamp) commit the same
+    // canonical sha under a new commit, since status is a volatile field excluded from
+    // it. Walking newest-first and stopping at the first non-match — rather than
+    // returning the first match — lands on the OLDEST commit that established this
+    // content, so its parent is the true prior (different-content) version.
+    let found;
+    for (const sha of log.out.split('\n').filter(Boolean)) {
+        const show = tryGit(root, 'show', `${sha}:${rel}`);
+        if (!show.ok)
+            break;
+        const doc = splitDoc(show.out);
+        if (!doc.ok || canonicalSha(doc.value.meta, doc.value.body) !== pin)
+            break;
+        found = sha;
+    }
+    return found;
+}
+export function specRevertFor(root, canon, spec, pin, abandonSet) {
+    const current = canonicalSha(spec.meta, spec.body);
+    if (current !== pin) {
+        return refuse([v('spec', 'stacked-amendment', `${String(spec.meta.id)} is at ${current.slice(0, 7)}, pin is ${pin.slice(0, 7)}`, 'abandon newest-first: a later amendment touched this spec')]);
+    }
+    const commit = pinCommit(root, spec.rel, pin);
+    if (!commit) {
+        return refuse([v('spec', 'pin-unresolvable', pin.slice(0, 7), 'a committed version matching the pin')]);
+    }
+    const prior = tryGit(root, 'show', `${commit}^:${spec.rel}`);
+    if (!prior.ok) {
+        const dependents = canon.docs
+            .filter((d) => !abandonSet.has(String(d.meta.id)))
+            .filter((d) => (d.meta.depends ?? []).includes(String(spec.meta.id)))
+            .map((d) => String(d.meta.id));
+        if (dependents.length > 0) {
+            return refuse([v('spec', 'waiting-dependents', dependents.join(' '), 'no docs outside the abandon set may depend on a spec being deleted')]);
+        }
+        return ok({ doc: spec, action: 'delete' });
+    }
+    const parsed = splitDoc(prior.out);
+    const toStatus = parsed.ok ? String(parsed.value.meta.status) : 'draft';
+    return ok({ doc: spec, action: 'restore', content: prior.out, toStatus });
+}
+export function executeAbandon(root, ctx, items, effortEntry, subject) {
+    const files = new Set();
+    const journalMulti = [];
+    const stamps = [];
+    const specEntries = [];
+    for (const item of items) {
+        if (item.planStamp) {
+            stamps.push(item.planStamp);
+            files.add(item.planStamp.rel);
+            files.add(journalRel(item.planStamp.stream));
+            journalMulti.push({ stream: item.planStamp.stream, line: item.planStamp.line });
+        }
+        if (item.revert) {
+            const spec = item.revert.doc;
+            const id = String(spec.meta.id);
+            const entry = {
+                v: 1, t: 'status', artifact: id, from: String(spec.meta.status),
+                to: item.revert.action === 'restore' ? item.revert.toStatus : 'removed',
+                cause: 'abandon',
+            };
+            specEntries.push({ stream: id, entry });
+            files.add(spec.rel);
+            files.add(journalRel(id));
+            journalMulti.push({ stream: id, line: entryLine(entry) });
+        }
+    }
+    let effortLine;
+    if (effortEntry) {
+        const entry = {
+            v: 1, t: 'human-decision', gate: 'effort', artifact: effortEntry.effort,
+            round: 0, decision: 'abandon-effort',
+        };
+        effortLine = { stream: effortEntry.effort, line: entryLine(entry) };
+        files.add(journalRel(effortEntry.effort));
+        journalMulti.push(effortLine);
+    }
+    const lockR = acquireLock(root);
+    if (!lockR.ok)
+        return lockR;
+    try {
+        return withTxn(root, { op: 'abandon', files: [...files], journalMulti }, () => {
+            for (const item of items) {
+                if (item.revert) {
+                    const abs = join(root, item.revert.doc.rel);
+                    if (item.revert.action === 'restore')
+                        writeFileSync(abs, item.revert.content);
+                    else
+                        unlinkSync(abs); // stateCommit's `git add` below correctly stages a tracked-but-missing file as a deletion
+                }
+            }
+            for (const s of stamps)
+                writeStamp(root, s);
+            for (const se of specEntries)
+                appendEntry(root, se.stream, se.entry);
+            if (effortLine) {
+                appendEntry(root, effortLine.stream, JSON.parse(effortLine.line));
+            }
+            crashPoint(ctx.env, 'abandon-commit');
+            const r = stateCommit(root, [...files], subject);
+            if (r.ok)
+                for (const item of items)
+                    if (item.planId)
+                        removeWorktree(root, item.planId);
+            return r;
+        });
+    }
+    finally {
+        lockR.value();
+    }
+}
+export function planItems(root, canon, plan, abandonSet, pairing) {
+    const planId = String(plan.meta.id);
+    const status = String(plan.meta.status);
+    if (status === 'done') {
+        return refuse([v('plan', 'already-done', planId, 'abandon targets unfinished plans — done plans are history')]);
+    }
+    const item = {
+        planStamp: prepareStamp(plan, 'abandoned', 'abandon'),
+        planId,
+    };
+    if (pairing === 'stamp-only')
+        return ok(item);
+    const effort = effortOf(root, planId);
+    const parentId = String(plan.meta.parent);
+    const paired = effort !== undefined && effortWrites(root, effort).has(parentId);
+    if (paired) {
+        const parent = findById(canon, parentId);
+        if (parent) {
+            const revertR = specRevertFor(root, canon, parent, String(plan.meta['derives-from']), abandonSet);
+            if (!revertR.ok)
+                return revertR;
+            item.revert = revertR.value;
+        }
+    }
+    return ok(item);
+}

package/dist/adopt.js

@@ -0,0 +1,42 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { splitDoc } from './fm.js';
+import { TRAILER, git, tryGit } from './gitio.js';
+import { readStream } from './journal.js';
+import { canonicalSha } from './sha.js';
+const hasTrailer = (root, sha) => git(root, 'show', '-s', '--format=%B', sha).split('\n').some((l) => l.trim() === TRAILER);
+const commitsTouching = (root, rel) => git(root, 'log', '--format=%H', '--', rel).split('\n').filter(Boolean);
+export function lastWitnessed(root, rel) {
+    for (const sha of commitsTouching(root, rel)) {
+        if (!hasTrailer(root, sha))
+            continue;
+        const raw = tryGit(root, 'show', `${sha}:${rel}`);
+        if (!raw.ok)
+            continue;
+        const doc = splitDoc(raw.out);
+        if (!doc.ok)
+            continue;
+        return { sha: canonicalSha(doc.value.meta, doc.value.body), criteria: doc.value.meta.criteria ?? null };
+    }
+    return undefined;
+}
+export function untrailedCommitsFor(root, rel) {
+    return commitsTouching(root, rel).filter((sha) => !hasTrailer(root, sha));
+}
+export function adoptedCommits(root) {
+    const out = new Set();
+    const dir = join(root, '.witness', 'journal');
+    if (!existsSync(dir))
+        return out;
+    for (const file of readdirSync(dir)) {
+        if (!file.endsWith('.jsonl'))
+            continue;
+        for (const entry of readStream(root, file.slice(0, -'.jsonl'.length))) {
+            if (entry.t !== 'adopt' || !Array.isArray(entry.commits))
+                continue;
+            for (const sha of entry.commits)
+                out.add(sha);
+        }
+    }
+    return out;
+}

package/dist/allowlist.js

@@ -0,0 +1,29 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+const allowPath = (root) => join(root, '.witness', 'allow.json');
+function load(root) {
+    if (!existsSync(allowPath(root)))
+        return [];
+    try {
+        const parsed = JSON.parse(readFileSync(allowPath(root), 'utf8'));
+        return Array.isArray(parsed.commands) ? parsed.commands : [];
+    }
+    catch {
+        return [];
+    }
+}
+export async function ensureTrusted(root, ctx, cmd) {
+    if (ctx.env.WITNESS_TRUST_CMDS === '1')
+        return 'trusted';
+    const commands = load(root);
+    if (commands.includes(cmd))
+        return 'trusted';
+    if (!ctx.isTTY)
+        return 'blocked';
+    const answer = await ctx.ask(`witness wants to run: ${cmd}\ntrust this command? saves to .witness/allow.json (gitignored) [y/N]`);
+    if (!answer.trim().toLowerCase().startsWith('y'))
+        return 'declined';
+    mkdirSync(join(root, '.witness'), { recursive: true });
+    writeFileSync(allowPath(root), JSON.stringify({ commands: [...commands, cmd] }, null, 2));
+    return 'trusted';
+}

package/dist/bin.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import { createInterface } from 'node:readline/promises';
+import { EXIT, main } from './cli.js';
+import { renderRefusal, v } from './refusal.js';
+const ctx = {
+    cwd: process.cwd(),
+    env: process.env,
+    isTTY: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+    out: (l) => process.stdout.write(l + '\n'),
+    err: (l) => process.stderr.write(l + '\n'),
+    ask: async (q) => {
+        const rl = createInterface({ input: process.stdin, output: process.stderr });
+        try {
+            return await rl.question(q + ' ');
+        }
+        finally {
+            rl.close();
+        }
+    },
+};
+// A verb that throws is a bug, but a stack trace is not a refusal: the engine file
+// renders exit 2/3 as a refusal it can act on, and anything else reads as a crash the
+// session has no vocabulary for. `init --agent` is the first path that touches paths
+// the repo is entitled to refuse (git commit --only on an ignored pathspec throws out
+// of gitio.ts:6); every other verb gets the same protection for free.
+try {
+    process.exit(await main(ctx, process.argv.slice(2)));
+}
+catch (e) {
+    renderRefusal([v('witness', 'unexpected-error', String(e.message).slice(0, 200), 'a bug — re-run with the same arguments and report this line')]).forEach((l) => process.stderr.write(`${l}\n`));
+    process.exit(EXIT.REFUSED);
+}