@popovych.co/witness 0.4.0

package/dist/cli.js

@@ -0,0 +1,98 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { configPath } from './config.js';
+import { primaryRoot } from './gitio.js';
+export const EXIT = { OK: 0, FINDINGS: 1, REFUSED: 2, BLOCKED: 3 };
+const VERBS = {
+    recover: () => import('./verbs/recover.js'),
+    init: () => import('./verbs/init.js'),
+    recap: () => import('./verbs/recap.js'),
+    write: () => import('./verbs/write.js'),
+    diff: () => import('./verbs/diff.js'),
+    check: () => import('./verbs/check.js'),
+    index: () => import('./verbs/index-verb.js'),
+    satisfy: () => import('./verbs/satisfy.js'),
+    log: () => import('./verbs/log.js'),
+    'test-evidence': () => import('./verbs/evidence.js'),
+    'verify-red': () => import('./verbs/evidence.js').then((m) => ({ run: m.runVerifyRed })),
+    'dispatch-report': () => import('./verbs/dispatch.js'),
+    adopt: () => import('./verbs/adopt.js'),
+    gate: () => import('./verbs/gate.js'),
+    decide: () => import('./verbs/decide.js'),
+    design: () => import('./verbs/design.js'),
+    start: () => import('./verbs/start.js'),
+    clean: () => import('./verbs/clean.js'),
+    ship: () => import('./verbs/ship.js'),
+    next: () => import('./verbs/next.js'),
+    abandon: () => import('./verbs/abandon.js'),
+    rename: () => import('./verbs/rename.js'),
+    sync: () => import('./verbs/sync.js'),
+    calibrate: () => import('./verbs/calibrate.js'),
+};
+// answered centrally so no verb can crash on --help (several parse argv
+// strictly); each line mirrors the verb's own usage refusal where one exists
+const VERB_USAGE = {
+    abandon: 'witness abandon <plan-id | effort-slug>',
+    adopt: 'witness adopt <specs/... | plans/...>.md',
+    calibrate: 'witness calibrate <exact-model-id> [--suite all|reviewers|skills] [--only <name>] [--samples <n>] [--publish]',
+    check: 'witness check',
+    clean: 'witness clean',
+    decide: 'witness decide <gate> <target> --approve|--revise|--stop [--override] [--note <t>] [--upstream <artifact|effort>] [--pin <policy>]… [--show]',
+    design: 'witness design <spec-id> --file <html> | --reconfirm | --open',
+    diff: 'witness diff <spec-id>',
+    'dispatch-report': 'witness dispatch-report <plan-id> --steps-assigned <n> --steps-completed <n> [--tokens <n>] [--tool-uses <n>] [--duration-ms <n>]',
+    gate: 'witness gate <decompose|plan|implement|ship|design> <target> [--fresh] [--manual]',
+    index: 'witness index',
+    init: 'witness init [--agent claude-code|pi|auto]',
+    log: 'witness log <stream> [--all] [--lineage]',
+    next: 'witness next',
+    recap: 'witness recap --file <recap.json> [--amend]',
+    recover: 'witness recover [--complete | --rollback]',
+    rename: 'witness rename <old-id> <new-id>',
+    satisfy: 'witness satisfy <doc-id> --need <text | index>',
+    ship: 'witness ship <plan-id>',
+    start: 'witness start <plan-id>',
+    sync: 'witness sync',
+    'test-evidence': 'witness test-evidence <plan-id> --phase red|green',
+    'verify-red': 'witness verify-red <plan-id> [--base <ref>]',
+};
+export function version() {
+    const pkg = JSON.parse(readFileSync(join(new URL('.', import.meta.url).pathname, '..', 'package.json'), 'utf8'));
+    return pkg.version;
+}
+export function usage() {
+    return [
+        'witness — spec-led pipeline: specs are state, plans are motion',
+        'usage: witness <verb> [flags]',
+        `verbs: ${Object.keys(VERBS).sort().join(' · ') || '(landing slice by slice)'}`,
+        'help: witness <verb> --help',
+    ].join('\n');
+}
+export async function main(ctx, argv) {
+    const [verb, ...rest] = argv;
+    if (verb === '--version' || verb === '-v') {
+        ctx.out(version());
+        return EXIT.OK;
+    }
+    if (!verb || verb === 'help' || verb === '--help') {
+        if (!verb) {
+            const rootRes = primaryRoot(ctx.cwd);
+            if (rootRes.ok && existsSync(configPath(rootRes.value))) {
+                return (await import('./verbs/dashboard.js')).run(ctx, []);
+            }
+        }
+        ctx.out(usage());
+        return EXIT.OK;
+    }
+    const load = VERBS[verb];
+    if (load && (rest.includes('--help') || rest.includes('-h'))) {
+        ctx.out(`usage: ${VERB_USAGE[verb] ?? `witness ${verb} [flags]`}`);
+        return EXIT.OK;
+    }
+    if (!load) {
+        ctx.err(`unknown verb: ${verb}`);
+        ctx.err(usage());
+        return EXIT.REFUSED;
+    }
+    return (await load()).run(ctx, rest);
+}

package/dist/config.js

@@ -0,0 +1,155 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { ok, refuse, v } from './refusal.js';
+export const SCHEMA_VERSION = 1;
+export const DEFAULT_PATHS = { specs: 'specs', plans: 'plans', designs: 'designs' };
+export const DOC_KEYS = ['conventions', 'design'];
+export function resolvePaths(raw) {
+    const conf = (raw.paths ?? {});
+    const violations = [];
+    const pick = (key) => {
+        const val = conf[key];
+        if (val === undefined)
+            return DEFAULT_PATHS[key];
+        if (typeof val !== 'string' || val === '') {
+            violations.push(v(`paths.${key}`, 'invalid', String(val), 'a repo-relative directory'));
+            return DEFAULT_PATHS[key];
+        }
+        const norm = val.replace(/\/+$/, '');
+        if (isAbsolute(norm) || norm.split('/').some((seg) => seg === '' || seg === '.' || seg === '..')) {
+            violations.push(v(`paths.${key}`, 'invalid', norm, 'a repo-relative directory without . or .. segments'));
+            return DEFAULT_PATHS[key];
+        }
+        if (norm === '.witness' || norm.startsWith('.witness/')) {
+            violations.push(v(`paths.${key}`, 'reserved', norm, 'a directory outside .witness/'));
+            return DEFAULT_PATHS[key];
+        }
+        return norm;
+    };
+    const specs = pick('specs');
+    const plans = pick('plans');
+    const designs = pick('designs');
+    if (violations.length === 0) {
+        const roots = [['specs', specs], ['plans', plans], ['designs', designs]];
+        for (let i = 0; i < roots.length; i++) {
+            for (let j = i + 1; j < roots.length; j++) {
+                const [ka, a] = roots[i];
+                const [kb, b] = roots[j];
+                if (a === b) {
+                    violations.push(v('paths', 'overlap', `${ka}=${kb}=${a}`, 'distinct specs, plans and designs directories'));
+                }
+                else if (a.startsWith(`${b}/`) || b.startsWith(`${a}/`)) {
+                    violations.push(v('paths', 'nested', `${a} vs ${b}`, 'directories that do not contain each other (scans are recursive)'));
+                }
+            }
+        }
+    }
+    return violations.length ? refuse(violations) : ok({ specs, plans, designs });
+}
+export function resolveDocs(raw) {
+    const conf = raw.docs;
+    if (conf === undefined)
+        return ok({});
+    if (typeof conf !== 'object' || conf === null || Array.isArray(conf)) {
+        return refuse([v('docs', 'invalid', String(conf), 'a map of doc keys to path lists')]);
+    }
+    const violations = [];
+    const out = {};
+    for (const [key, val] of Object.entries(conf)) {
+        if (!DOC_KEYS.includes(key)) {
+            violations.push(v(`docs.${key}`, 'unknown-doc-key', key, `a key with a shipped consumer (${DOC_KEYS.join(' | ')})`));
+            continue;
+        }
+        if (!Array.isArray(val) || val.length === 0 || !val.every((x) => typeof x === 'string' && x !== '')) {
+            violations.push(v(`docs.${key}`, 'invalid', JSON.stringify(val), 'a non-empty list of repo-relative file paths'));
+            continue;
+        }
+        const paths = [];
+        for (const p of val) {
+            const norm = p.replace(/\/+$/, '');
+            if (isAbsolute(norm) || norm.split('/').some((seg) => seg === '' || seg === '.' || seg === '..')) {
+                violations.push(v(`docs.${key}`, 'invalid', norm, 'a repo-relative file path without . or .. segments'));
+                continue;
+            }
+            if (norm === '.witness' || norm.startsWith('.witness/')) {
+                violations.push(v(`docs.${key}`, 'reserved', norm, 'a path outside .witness/'));
+                continue;
+            }
+            paths.push(norm);
+        }
+        out[key] = paths;
+    }
+    return violations.length ? refuse(violations) : ok(out);
+}
+export const DEFAULT_STEPS_PER_DISPATCH = 3;
+export function resolveImplement(raw) {
+    const conf = raw.implement;
+    if (conf === undefined)
+        return ok({ stepsPerDispatch: DEFAULT_STEPS_PER_DISPATCH });
+    if (typeof conf !== 'object' || conf === null || Array.isArray(conf)) {
+        return refuse([v('implement', 'invalid', String(conf), 'a map of implement-stage settings')]);
+    }
+    const val = conf.stepsPerDispatch;
+    if (val === undefined)
+        return ok({ stepsPerDispatch: DEFAULT_STEPS_PER_DISPATCH });
+    if (typeof val !== 'number' || !Number.isInteger(val) || val < 1) {
+        return refuse([v('implement.stepsPerDispatch', 'invalid', String(val), 'an integer >= 1 — steps handed to each fresh implement agent')]);
+    }
+    return ok({ stepsPerDispatch: val });
+}
+// Lenient path resolution for callers without a loaded Config (canon scan, git
+// state scoping): a missing or broken config falls back to the defaults — the
+// verbs own the refusal messaging via loadConfig, which validates paths strictly.
+export function canonPaths(root) {
+    const p = configPath(root);
+    if (!existsSync(p))
+        return DEFAULT_PATHS;
+    try {
+        const raw = (parseYaml(readFileSync(p, 'utf8')) ?? {});
+        const resolved = resolvePaths(raw);
+        return resolved.ok ? resolved.value : DEFAULT_PATHS;
+    }
+    catch {
+        return DEFAULT_PATHS;
+    }
+}
+export const configPath = (root) => join(root, 'witness.config.yaml');
+export function loadConfig(root) {
+    const p = configPath(root);
+    if (!existsSync(p)) {
+        return refuse([v('witness.config.yaml', 'missing', 'no config at repo root', 'run witness init')]);
+    }
+    let raw;
+    try {
+        raw = parseYaml(readFileSync(p, 'utf8'));
+    }
+    catch (e) {
+        return refuse([v('witness.config.yaml', 'yaml-parse', String(e.message).slice(0, 120), 'valid YAML')]);
+    }
+    const obj = (raw ?? {});
+    const schema = obj.schema;
+    if (typeof schema !== 'number' || !Number.isInteger(schema)) {
+        return refuse([v('schema', 'required', String(schema ?? 'absent'), 'integer schema version')]);
+    }
+    if (schema > SCHEMA_VERSION) {
+        return refuse([v('schema', 'newer-than-cli', String(schema), `<=${SCHEMA_VERSION} — upgrade witness`)]);
+    }
+    const paths = resolvePaths(obj);
+    if (!paths.ok)
+        return refuse(paths.violations);
+    const docs = resolveDocs(obj);
+    if (!docs.ok)
+        return refuse(docs.violations);
+    const implement = resolveImplement(obj);
+    if (!implement.ok)
+        return refuse(implement.violations);
+    return ok({
+        schema,
+        raw: obj,
+        paths: paths.value,
+        docs: docs.value,
+        implement: implement.value,
+        warning: schema < SCHEMA_VERSION ? `schema ${schema} < ${SCHEMA_VERSION} — run witness migrate (reserved)` : undefined,
+    });
+}

package/dist/criteria.js

@@ -0,0 +1,85 @@
+import { ensureTrusted } from './allowlist.js';
+import { loadConfig } from './config.js';
+import { matchesTag, sourceTags } from './matcher.js';
+import { ok } from './refusal.js';
+import { criteriaExcludes, execCommand, runFiltered, runFullSuite, runnerConfig } from './runner.js';
+import { canonicalSha } from './sha.js';
+export async function runCriteria(runRoot, ctx, doc, opts = {}) {
+    const trustRoot = opts.trustRoot ?? runRoot;
+    const cfg = loadConfig(runRoot);
+    if (!cfg.ok)
+        return cfg;
+    const rcRes = runnerConfig(cfg.value);
+    if (!rcRes.ok)
+        return rcRes;
+    const rc = rcRes.value;
+    const id = String(doc.meta.id);
+    const list = (Array.isArray(doc.meta.criteria) ? doc.meta.criteria : []);
+    let suite = opts.suite;
+    let suiteProblem;
+    if (rc.mode === 'full-suite' && suite === undefined && list.some((c) => typeof c.test === 'string')) {
+        const res = await runFullSuite(runRoot, ctx, rc, trustRoot);
+        if (res.ok)
+            suite = res.value.tests;
+        else
+            suiteProblem = res.violations.map((x) => `${x.rule}: ${x.field}`).join('; ');
+    }
+    const src = rc.mode === 'filtered'
+        ? sourceTags(runRoot, criteriaExcludes(cfg.value))
+        : undefined;
+    const criteria = [];
+    for (const c of list) {
+        const cid = String(c.id);
+        if (typeof c.test === 'string') {
+            if (rc.mode === 'full-suite') {
+                if (!suite) {
+                    criteria.push({ id: cid, kind: 'test', ok: false, detail: suiteProblem ?? 'suite did not run' });
+                    continue;
+                }
+                const mine = suite.filter((t) => matchesTag(t.name, id));
+                const passed = mine.filter((t) => t.status === 'passed').length;
+                const failed = mine.filter((t) => t.status === 'failed').length;
+                criteria.push({
+                    id: cid, kind: 'test', ok: passed > 0 && failed === 0,
+                    detail: `${mine.length} tagged · ${passed} passed · ${failed} failed`,
+                });
+            }
+            else {
+                const run = await runFiltered(runRoot, ctx, rc.template, id, trustRoot);
+                const count = src?.counts.get(id) ?? 0;
+                if (!run.ok) {
+                    criteria.push({ id: cid, kind: 'test', ok: false, detail: run.violations.map((x) => x.rule).join('; ') });
+                }
+                else if (count === 0) {
+                    criteria.push({ id: cid, kind: 'test', ok: false, detail: 'no tagged test found in source (grep side)' });
+                }
+                else {
+                    criteria.push({
+                        id: cid, kind: 'test', ok: run.value.exitZero,
+                        detail: `filtered run ${run.value.exitZero ? 'exit 0' : 'nonzero'} · ${count} tagged in source`,
+                    });
+                }
+            }
+        }
+        else if (typeof c.cmd === 'string') {
+            const trust = await ensureTrusted(trustRoot, ctx, c.cmd);
+            if (trust !== 'trusted') {
+                criteria.push({ id: cid, kind: 'cmd', ok: false, detail: `untrusted-${trust} — allow interactively or set WITNESS_TRUST_CMDS=1` });
+                continue;
+            }
+            const run = execCommand(runRoot, ctx, c.cmd);
+            criteria.push({ id: cid, kind: 'cmd', ok: run.exitZero, detail: run.exitZero ? 'exit 0' : 'nonzero exit' });
+        }
+    }
+    const tagCount = rc.mode === 'full-suite'
+        ? (suite ?? []).filter((t) => matchesTag(t.name, id)).length
+        : (src?.counts.get(id) ?? 0);
+    return ok({
+        spec: id,
+        sha: canonicalSha(doc.meta, doc.body),
+        ok: criteria.length > 0 && criteria.every((c) => c.ok),
+        mode: rc.mode,
+        tagCount,
+        criteria,
+    });
+}

package/dist/design.js

@@ -0,0 +1,104 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { latestRecap, readStream } from './journal.js';
+import { v } from './refusal.js';
+import { effortOf } from './reviewed.js';
+import { canonicalSha } from './sha.js';
+export function elementIds(html) {
+    const ids = [];
+    const re = /\bid\s*=\s*["']([^"']+)["']/g;
+    let m;
+    while ((m = re.exec(html)) !== null)
+        ids.push(m[1].trim());
+    return ids;
+}
+// A design artifact is a portable, self-contained mockup: it must render with no
+// network, and it must expose id-attributed sections so the design-critic can anchor
+// findings to concrete parts of the screen (the anchor grammar's targets).
+const EXTERNAL_REFS = [
+    [/<script[^>]*\bsrc\s*=/i, 'external <script src> — inline the script'],
+    [/<link[^>]*\bhref\s*=\s*["'](?:https?:)?\/\//i, 'external <link href> — inline the stylesheet'],
+    [/<img[^>]*\bsrc\s*=\s*["'](?:https?:)?\/\//i, 'external <img src> — embed as a data: URI'],
+    [/<[^>]*\bsrcset\s*=\s*["'][^"']*(?:https?:)?\/\//i, 'external srcset — embed as data: URIs'],
+    [/url\(\s*["']?(?:https?:)?\/\//i, 'external url() in CSS — embed the asset'],
+];
+export function validateDesignArtifact(html) {
+    const out = [];
+    for (const [re, why] of EXTERNAL_REFS) {
+        if (re.test(html)) {
+            out.push(v('artifact', 'external-ref', why, 'a self-contained artifact — no external resource refs'));
+            break;
+        }
+    }
+    const ids = elementIds(html);
+    const unique = new Set(ids);
+    if (unique.size !== ids.length) {
+        out.push(v('artifact', 'duplicate-id', `${ids.length} ids, ${unique.size} unique`, 'unique id attributes — anchors must be unambiguous'));
+    }
+    if (unique.size < 2) {
+        out.push(v('artifact', 'template', `${unique.size} id-attributed element(s)`, '>=2 id-attributed sections — the design-critic anchors to element ids'));
+    }
+    if (!/<!doctype html/i.test(html) && !/<html[\s>]/i.test(html) && !/<body[\s>]/i.test(html)) {
+        out.push(v('artifact', 'not-html', html.slice(0, 40), 'an HTML document (<!doctype html> / <html> / <body>)'));
+    }
+    return out;
+}
+export function htmlSha(html) {
+    return createHash('sha256').update(html.replace(/\s+$/, '') + '\n').digest('hex');
+}
+export function designPairSha(html, spec) {
+    return createHash('sha256')
+        .update(`design:${htmlSha(html)}\n`)
+        .update(`spec:${canonicalSha(spec.meta, spec.body)}`)
+        .digest('hex');
+}
+export function designRel(paths, specId) {
+    return `${paths.designs}/${specId}.html`;
+}
+export function designStamp(spec) {
+    const s = spec.meta.design;
+    if (!s || typeof s.sha !== 'string' || typeof s.spec !== 'string')
+        return undefined;
+    return { sha: s.sha, spec: s.spec };
+}
+// The single home for "this ui spec owes a design": a ui-flagged spec in a
+// feature-class effort whose design stamp is missing or stale (designed against
+// older content). fix/chore efforts never arm it (Q2). next/dashboard/check/gate
+// all consult this — never re-derive the rule.
+export function designPending(root, spec) {
+    if (spec.meta.type !== 'spec' || spec.meta.ui !== true)
+        return false;
+    const effort = effortOf(root, String(spec.meta.id));
+    if (!effort)
+        return false;
+    if (latestRecap(root, effort)?.class !== 'feature')
+        return false;
+    const stamp = designStamp(spec);
+    return !stamp || stamp.spec !== canonicalSha(spec.meta, spec.body);
+}
+// Is an artifact authored for the CURRENT spec content already on disk (a design-write
+// entry whose `spec` sha equals the current canonical sha)? Distinguishes "authored,
+// awaiting gate" from "amended since the last artifact" — routing keys on this instead
+// of file existence, so an amendment (stale artifact) correctly re-enters the design skill.
+export function designArtifactCurrent(root, spec) {
+    const cur = canonicalSha(spec.meta, spec.body);
+    return readStream(root, String(spec.meta.id)).some((e) => e.t === 'design-write' && e.spec === cur);
+}
+// Pure half: has a human been shown THESE exact bytes? Sha-keyed, because a re-authored
+// artifact is a different thing to look at — the same discipline that makes a re-captured
+// screenshot invalidate its predecessor's witnessed sha (D71).
+export function designShown(entries, sha) {
+    return entries.some((e) => e.t === 'design-shown' && e.sha === sha);
+}
+// The single home for "this artifact is registered but nobody has been shown it".
+// Returns the unwitnessed sha, or undefined when there is nothing to see (no artifact)
+// or a design-shown entry already covers the current bytes. gate/decide/next all consult
+// this — never re-derive the rule.
+export function designUnseen(root, paths, specId) {
+    const abs = join(root, designRel(paths, specId));
+    if (!existsSync(abs))
+        return undefined;
+    const sha = htmlSha(readFileSync(abs, 'utf8'));
+    return designShown(readStream(root, specId), sha) ? undefined : sha;
+}