@popovych.co/witness 0.4.0

package/dist/needs.js

@@ -0,0 +1,34 @@
+import { execSync } from 'node:child_process';
+import { ensureTrusted } from './allowlist.js';
+export async function evaluateNeeds(root, ctx, needs) {
+    const out = [];
+    for (const raw of needs) {
+        const n = raw;
+        if (typeof n.env === 'string') {
+            const set = Boolean(ctx.env[n.env]);
+            out.push({ label: n.env, kind: 'env', status: set ? 'ok' : 'unmet', detail: set ? 'set' : 'env var unset' });
+        }
+        else if (typeof n.manual === 'string') {
+            const done = n.satisfied === true;
+            out.push({ label: n.manual, kind: 'manual', status: done ? 'ok' : 'unmet', detail: done ? 'satisfied' : 'flip via witness satisfy' });
+        }
+        else if (typeof n.cmd === 'string') {
+            const trust = await ensureTrusted(root, ctx, n.cmd);
+            if (trust !== 'trusted') {
+                out.push({
+                    label: n.cmd, kind: 'cmd', status: trust,
+                    detail: trust === 'blocked' ? 'untrusted in non-TTY — allow interactively or set WITNESS_TRUST_CMDS=1' : 'trust declined',
+                });
+                continue;
+            }
+            try {
+                execSync(n.cmd, { cwd: root, stdio: 'ignore' });
+                out.push({ label: n.cmd, kind: 'cmd', status: 'ok', detail: 'exit 0' });
+            }
+            catch {
+                out.push({ label: n.cmd, kind: 'cmd', status: 'unmet', detail: 'nonzero exit' });
+            }
+        }
+    }
+    return out;
+}

package/dist/opener.js

@@ -0,0 +1,38 @@
+import { spawnSync, spawn } from 'node:child_process';
+// Platform default openers. `start` is a cmd builtin, hence the shell wrapper.
+function platformOpener() {
+    if (process.platform === 'darwin')
+        return ['open'];
+    if (process.platform === 'win32')
+        return ['cmd', '/c', 'start', ''];
+    return ['xdg-open'];
+}
+// win32 has no `sh`, so a POSIX probe there would report every opener missing and
+// make approve permanently unreachable. `where` is the cmd equivalent.
+function resolves(cmd) {
+    const probe = process.platform === 'win32'
+        ? spawnSync('where', [cmd], { encoding: 'utf8' })
+        : spawnSync('sh', ['-c', `command -v ${cmd}`], { encoding: 'utf8' });
+    return probe.status === 0;
+}
+// Show a file to the human. Returns the resolved command alongside the outcome so the
+// caller can journal WHAT was run — a degenerate opener (`WITNESS_OPENER=/usr/bin/true`)
+// then reads as a degenerate opener in the record instead of as a human looking at a
+// screen. `WITNESS_OPENER` overrides the binary: test seam, and the real escape hatch
+// for nonstandard desktops, so it accepts a bare name off PATH as well as a path.
+export function openArtifact(env, absPath) {
+    const argv = env.WITNESS_OPENER ? [env.WITNESS_OPENER] : platformOpener();
+    const [cmd, ...pre] = argv;
+    // Probe before spawning: a detached spawn reports ENOENT asynchronously, and the
+    // caller needs the outcome synchronously to journal it in the same transaction.
+    if (!resolves(cmd))
+        return { outcome: 'failed', command: cmd };
+    try {
+        const child = spawn(cmd, [...pre, absPath], { detached: true, stdio: 'ignore' });
+        child.unref();
+        return { outcome: 'spawned', command: cmd };
+    }
+    catch {
+        return { outcome: 'failed', command: cmd };
+    }
+}

package/dist/pin.js

@@ -0,0 +1,28 @@
+import { ok, refuse, v } from './refusal.js';
+// Pi's native --thinking vocabulary. One grammar for every harness: pi renders it
+// natively; claude-code maps non-off levels through CLAUDE_THINKING_BUDGET.
+export const THINKING_LEVELS = ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'];
+// claude has no --thinking flag; non-off levels render as the documented
+// MAX_THINKING_TOKENS env var. Budgets are pinned constants: the raw pin string is in
+// the verdict-cache key, so a level change re-rolls verdicts; a budget-table change
+// ships as a new witness version, which is also in the key.
+export const CLAUDE_THINKING_BUDGET = {
+    minimal: 1024, low: 4096, medium: 8192, high: 16384, xhigh: 32768, max: 63999,
+};
+// Grammar: [provider/]model[:thinking]. First '/' splits provider; last ':' after the
+// slash splits thinking — model ids themselves never contain ':' in any catalog we ship.
+export function parsePin(field, raw) {
+    const slash = raw.indexOf('/');
+    const provider = slash > 0 ? raw.slice(0, slash) : undefined;
+    const rest = slash >= 0 ? raw.slice(slash + 1) : raw;
+    const colon = rest.lastIndexOf(':');
+    const model = colon >= 0 ? rest.slice(0, colon) : rest;
+    const level = colon >= 0 ? rest.slice(colon + 1) : 'off';
+    if (model === '' || (slash >= 0 && provider === undefined)) {
+        return refuse([v(field, 'pin-malformed', raw, '[provider/]model[:thinking]')]);
+    }
+    if (!THINKING_LEVELS.includes(level)) {
+        return refuse([v(field, 'unknown-thinking-level', level, THINKING_LEVELS.join(' | '))]);
+    }
+    return ok({ provider, model, thinking: level });
+}

package/dist/probe.js

@@ -0,0 +1,14 @@
+import { execFileSync } from 'node:child_process';
+// Revision 3. The old form passed no `env`, so it silently answered about process.env
+// while reviewer.ts:113 spawns `claude` with `env: ctx.env` — two different questions,
+// one answer. It also made the finding untestable: helpers.ts runs main() in-process,
+// so a test can control ctx.env and nothing else.
+export function probe(cmd, args, env) {
+    try {
+        execFileSync(cmd, args, { stdio: 'ignore', env: env });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/refusal.js

@@ -0,0 +1,16 @@
+import { rows } from './toon.js';
+export function ok(value) {
+    return { ok: true, value };
+}
+export function refuse(violations) {
+    return { ok: false, violations };
+}
+export function v(field, rule, got, want) {
+    return { field, rule, got, want };
+}
+export function renderRefusal(violations) {
+    return [
+        ...rows('refused', ['field', 'rule', 'got', 'want'], violations),
+        'help: fix each row and re-run — rows are structured for self-repair',
+    ];
+}

package/dist/reviewed.js

@@ -0,0 +1,69 @@
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { canonicalJson, canonicalSha } from './sha.js';
+import { effortAbandoned, effortStreams, latestRecap, readStream } from './journal.js';
+import { findById } from './scan.js';
+export function worktreeTreeSha(root) {
+    const tmp = mkdtempSync(join(tmpdir(), 'witness-idx-'));
+    const env = { ...process.env, GIT_INDEX_FILE: join(tmp, 'index') };
+    try {
+        execFileSync('git', ['add', '-A'], { cwd: root, env });
+        return execFileSync('git', ['write-tree'], { cwd: root, env, encoding: 'utf8' }).trim();
+    }
+    finally {
+        rmSync(tmp, { recursive: true, force: true });
+    }
+}
+export function effortWrites(root, effort) {
+    const out = new Map();
+    for (const e of readStream(root, effort)) {
+        if (e.t !== 'write')
+            continue;
+        const w = e;
+        out.set(w.artifact, { sha: w.sha, covers: w.covers, created: w.created });
+    }
+    return out;
+}
+export function effortSpecs(root, canon, effort) {
+    const docs = [];
+    for (const id of effortWrites(root, effort).keys()) {
+        const doc = findById(canon, id);
+        if (doc && doc.meta.type === 'spec')
+            docs.push(doc);
+    }
+    return docs.sort((a, b) => String(a.meta.id).localeCompare(String(b.meta.id)));
+}
+export function effortOf(root, artifactId) {
+    const hits = [];
+    for (const effort of effortStreams(root)) {
+        const entries = readStream(root, effort);
+        if (entries.some((e) => e.t === 'write' && e.artifact === artifactId)) {
+            hits.push({ effort, abandoned: effortAbandoned(entries) });
+        }
+    }
+    hits.sort((a, b) => a.abandoned === b.abandoned ? a.effort.localeCompare(b.effort) : a.abandoned ? 1 : -1);
+    return hits[0]?.effort;
+}
+function sha256(parts) {
+    const h = createHash('sha256');
+    for (const p of parts)
+        h.update(p);
+    return h.digest('hex');
+}
+export function effortReviewedSha(root, canon, effort) {
+    const recap = latestRecap(root, effort);
+    const docs = effortSpecs(root, canon, effort);
+    const lines = docs
+        .map((d) => `${String(d.meta.id)}:${canonicalSha(d.meta, d.body)}`)
+        .sort();
+    return { sha: sha256([canonicalJson(recap ?? {}), '\n', lines.join('\n')]), docs };
+}
+export function planPairSha(plan, parent) {
+    return sha256([
+        `${String(plan.meta.id)}:${canonicalSha(plan.meta, plan.body)}\n`,
+        `${String(parent.meta.id)}:${canonicalSha(parent.meta, parent.body)}`,
+    ]);
+}

package/dist/reviewer.js

@@ -0,0 +1,133 @@
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { validatePin } from './harness.js';
+import { ok, refuse, v } from './refusal.js';
+export const PROMPT_NAMES = [
+    'slicing-critic', 'plan-critic', 'code-reviewer', 'silent-failure-hunter',
+    'type-design', 'pr-test', 'drift-reviewer', 'design-critic', 'design-reviewer',
+];
+export function promptsDir() {
+    return join(dirname(fileURLToPath(import.meta.url)), '..', 'prompts');
+}
+export function resolvePrompt(name) {
+    const path = join(promptsDir(), `${name}.md`);
+    if (!existsSync(path)) {
+        return refuse([v('reviewers', 'unknown-reviewer', name, `a lens file at prompts/${name}.md (shipped: ${PROMPT_NAMES.join(' ')})`)]);
+    }
+    return ok({ name, contents: readFileSync(path, 'utf8') });
+}
+// docs.<key> → which lenses at which gates consume it. The design-stage plan
+// extends this map (design → design-critic / design-reviewer); keys here must
+// stay in lockstep with DOC_KEYS in config.ts — no key without a consumer.
+const DOC_CONSUMERS = {
+    conventions: { lenses: ['code-reviewer'], gates: ['implement', 'ship'] },
+    design: { lenses: ['design-critic', 'design-reviewer'], gates: ['design', 'implement'] },
+};
+export function docKeysFor(gate, lens) {
+    return Object.entries(DOC_CONSUMERS)
+        .filter(([, c]) => c.lenses.includes(lens) && c.gates.includes(gate))
+        .map(([k]) => k);
+}
+export function loadLensDocs(root, paths) {
+    const docs = [];
+    const violations = [];
+    for (const p of paths) {
+        const abs = join(root, p);
+        if (!existsSync(abs)) {
+            violations.push(v('docs', 'doc-missing', p, 'an existing file — gates inject configured docs fail-closed; fix the path or restore the file'));
+            continue;
+        }
+        docs.push({ path: p, contents: readFileSync(abs, 'utf8') });
+    }
+    return violations.length ? refuse(violations) : ok(docs);
+}
+export function docsBlock(docs) {
+    if (docs.length === 0)
+        return '';
+    return `## Repo conventions (injected from docs config)\n\n${docs.map((d) => `### ${d.path}\n\n${d.contents}`).join('\n\n')}\n\n`;
+}
+// Row 83: settled content policies, injected into every battery for the plan. The
+// contradiction channel is reviewer self-report — deterministic semantic matching of a
+// freeform finding against a pin is not honestly implementable, so the schema carries it.
+export function pinsBlock(pins) {
+    if (pins.length === 0)
+        return '';
+    return `## Settled policy pins (human decisions — do not re-litigate)\n\n` +
+        `The human has pinned these content policies for this plan. They are settled: a finding that merely disagrees with a pin is not a finding. If a defect you must report can only be fixed by violating a pin, report it AND set \`"contradicts_pin": <pin number>\` on that finding — the gate escalates the conflict to the human. Where pins conflict, the later pin wins.\n\n` +
+        pins.map((p) => `${p.ordinal}. ${p.text}`).join('\n') + '\n\n';
+}
+export function promptsSha(lenses, extra) {
+    const h = createHash('sha256');
+    for (const l of [...lenses].sort((a, b) => a.name.localeCompare(b.name))) {
+        h.update(`lens ${l.name} ${l.contents.length}\n`);
+        h.update(l.contents);
+        h.update('\n');
+        // injected docs are part of what the reviewer read — an edited doc is a
+        // different reviewer, exactly like an edited lens (verdict-cache key)
+        for (const d of l.docs ?? []) {
+            h.update(`doc ${d.path} ${d.contents.length}\n`);
+            h.update(d.contents);
+            h.update('\n');
+        }
+    }
+    // policy pins are part of what every reviewer read — a changed pin-set re-arms review
+    if (extra !== undefined && extra !== '') {
+        h.update(`pins ${extra.length}\n`);
+        h.update(extra);
+        h.update('\n');
+    }
+    return h.digest('hex');
+}
+const REVIEWER_TIMEOUT_MS = 600_000;
+// One stalled call must not cost a whole run: a full calibration battery is ~200
+// invocations over hours, and treating a transient stall as fatal throws away every
+// sample already paid for. Retries are bounded so a genuinely wedged binary still ends.
+const TIMEOUT_RETRIES = 2;
+export function invokeReviewer(ctx, harness, opts) {
+    let pin;
+    if (opts.model !== undefined) {
+        const pinR = validatePin(harness, 'gates.model', opts.model);
+        if (!pinR.ok)
+            return refuse(pinR.violations);
+        pin = pinR.value;
+    }
+    const { cmd, args, env } = harness.reviewer.spawn(pin);
+    const timeout = Number(ctx.env.WITNESS_REVIEWER_TIMEOUT_MS) || REVIEWER_TIMEOUT_MS;
+    for (let attempt = 0;; attempt += 1) {
+        const r = spawnSync(cmd, args, {
+            cwd: opts.cwd,
+            env: { ...ctx.env, ...env },
+            input: opts.prompt,
+            encoding: 'utf8',
+            timeout,
+            maxBuffer: 64 * 1024 * 1024,
+        });
+        if (r.error) {
+            // A stall is NOT the missing-binary case. Reporting it as one sent the last
+            // reader hunting a PATH problem on a machine where the reviewer answered in 6s.
+            if (r.error.code === 'ETIMEDOUT') {
+                if (attempt < TIMEOUT_RETRIES)
+                    continue;
+                return refuse([v(cmd, 'reviewer-timeout', `no response in ${timeout}ms after ${attempt + 1} attempts`, 'a reviewer that answers within the timeout — raise WITNESS_REVIEWER_TIMEOUT_MS if the model is simply slow')]);
+            }
+            return refuse([v(cmd, 'reviewer-invocation', String(r.error.message), `a runnable ${cmd} binary on PATH — gates invoke reviewers headlessly; witness check probes this`)]);
+        }
+        if (r.status !== 0) {
+            return refuse([v(cmd, 'reviewer-invocation', `exit ${String(r.status)}: ${(r.stderr ?? '').slice(0, 200)}`, `${cmd} print mode exiting 0`)]);
+        }
+        return harness.reviewer.parseEnvelope(r.stdout);
+    }
+}
+export function parseVerdictText(text) {
+    const fenced = /```(?:json)?\s*\n([\s\S]*?)\n\s*```/.exec(text);
+    const body = (fenced ? fenced[1] ?? '' : text).trim();
+    try {
+        return ok(JSON.parse(body));
+    }
+    catch {
+        return refuse([v('verdict', 'verdict-unparseable', body.slice(0, 120), 'a JSON object {coverage, findings} and nothing else')]);
+    }
+}

package/dist/rounds.js

@@ -0,0 +1,112 @@
+const isRun = (e, gate) => e !== undefined && e.t === 'gate-run' && e.gate === gate;
+const isDecision = (e, gate) => e !== undefined && e.t === 'human-decision' && e.gate === gate;
+export function keyOf(run) {
+    const { reviewed_sha, gate, prompts_sha, model, witness } = run;
+    return { reviewed_sha, gate, prompts_sha, model, witness, harness: run.harness ?? 'claude-code' };
+}
+export function sameKey(a, b) {
+    return a.reviewed_sha === b.reviewed_sha && a.gate === b.gate &&
+        a.prompts_sha === b.prompts_sha && a.model === b.model && a.witness === b.witness &&
+        a.harness === b.harness;
+}
+export function gateRuns(entries, gate) {
+    return entries.filter((e) => isRun(e, gate));
+}
+export function lastGateRun(entries, gate) {
+    for (let i = entries.length - 1; i >= 0; i--) {
+        if (isRun(entries[i], gate))
+            return entries[i];
+    }
+    return undefined;
+}
+export const ROUND_BOUND = 3;
+// a "reset" opens a fresh round budget: human approve, a passed run, or a
+// revise-upstream (the plan itself changes — a new plan version is a new game;
+// upstream churn is bounded by the upstream gate's own bound)
+function lastResetIndex(entries, gate) {
+    for (let i = entries.length - 1; i >= 0; i--) {
+        const e = entries[i];
+        if (isDecision(e, gate)) {
+            const d = e.decision;
+            if (d === 'approve' || d === 'revise-upstream')
+                return i;
+        }
+        if (isRun(e, gate) && e.outcome === 'passed')
+            return i;
+    }
+    return -1;
+}
+export function roundsSinceApprove(entries, gate) {
+    const since = lastResetIndex(entries, gate);
+    let n = 0;
+    for (let i = since + 1; i < entries.length; i++) {
+        const e = entries[i];
+        // malformed = the battery failed to emit a legal verdict — witness's
+        // failure, not the artifact's; it never spends the human's budget
+        if (isRun(e, gate) && e.outcome !== 'malformed')
+            n++;
+    }
+    return n;
+}
+export function boundReached(entries, gate) {
+    return roundsSinceApprove(entries, gate) >= ROUND_BOUND;
+}
+export function pendingDecision(entries, gate) {
+    for (let i = entries.length - 1; i >= 0; i--) {
+        const e = entries[i];
+        if (isDecision(e, gate))
+            return undefined;
+        if (isRun(e, gate)) {
+            const run = e;
+            return run.outcome === 'passed' ? undefined : run;
+        }
+    }
+    return undefined;
+}
+// A decision carrying `caused_by` is a REOPEN — another gate's `--revise --upstream`
+// instructing this stage to re-author. It is not a disposition of the run above it and
+// can never settle it. Discharged by a later gate-run OR a later human-decision for the
+// same gate: `--approve` is a legitimate answer to a reopen ("looked, the canon was
+// right"), and requiring a run would strand the human at `changed-nothing`, which
+// appends nothing and would loop forever (D67's livelock shape).
+export function openReopen(entries, gate) {
+    for (let i = entries.length - 1; i >= 0; i--) {
+        const e = entries[i];
+        if (isRun(e, gate))
+            return undefined;
+        if (isDecision(e, gate)) {
+            const d = e;
+            if (d.caused_by !== undefined)
+                return d;
+            return undefined;
+        }
+    }
+    return undefined;
+}
+export function appendKind(entries, gate, key) {
+    let lastRunIdx = -1;
+    for (let i = entries.length - 1; i >= 0; i--) {
+        if (isRun(entries[i], gate)) {
+            lastRunIdx = i;
+            break;
+        }
+    }
+    if (lastRunIdx >= 0) {
+        const last = entries[lastRunIdx];
+        if (sameKey(keyOf(last), key)) {
+            const revised = entries.slice(lastRunIdx + 1).some((e) => isDecision(e, gate) &&
+                ['revise', 'revise-upstream'].includes(e.decision));
+            return revised ? { kind: 'changed-nothing', entry: last } : { kind: 'resume', entry: last };
+        }
+    }
+    for (let i = lastRunIdx - 1; i >= 0; i--) {
+        const e = entries[i];
+        if (!isRun(e, gate))
+            continue;
+        const run = e;
+        if (run.outcome !== 'malformed' && run.verdicts && sameKey(keyOf(run), key)) {
+            return { kind: 'cached', from: run };
+        }
+    }
+    return { kind: 'fresh' };
+}

package/dist/runner.js

@@ -0,0 +1,73 @@
+import { execSync } from 'node:child_process';
+import { rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { ensureTrusted } from './allowlist.js';
+import { mergeReports, reportFiles } from './junit.js';
+import { ok, refuse, v } from './refusal.js';
+export function runnerConfig(cfg) {
+    const crit = (cfg.raw.criteria ?? {});
+    const runner = crit.runner;
+    if (typeof runner !== 'string' || runner.length === 0) {
+        return refuse([v('criteria.runner', 'required', String(runner ?? 'absent'), 'a filtered template containing {id}, or full-suite')]);
+    }
+    if (runner === 'full-suite') {
+        const report = crit.report;
+        if (typeof report !== 'string') {
+            return refuse([v('criteria.report', 'required', 'absent', 'junit:<glob> — full-suite mode reads merged junit reports')]);
+        }
+        if (!report.startsWith('junit:')) {
+            return refuse([v('criteria.report', 'report-format', report, 'junit:<glob> (only junit is supported)')]);
+        }
+        const ship = (cfg.raw.ship ?? {});
+        if (typeof ship.test !== 'string' || ship.test.length === 0) {
+            return refuse([v('ship.test', 'required', 'absent', 'the suite command full-suite mode executes')]);
+        }
+        return ok({ mode: 'full-suite', reportGlob: report.slice('junit:'.length), suiteCmd: ship.test });
+    }
+    if (!runner.includes('{id}')) {
+        return refuse([v('criteria.runner', 'no-id-placeholder', runner, 'template must interpolate {id} (or use full-suite)')]);
+    }
+    const report = crit.report;
+    if (report !== undefined) {
+        if (typeof report !== 'string' || !report.startsWith('junit:')) {
+            return refuse([v('criteria.report', 'report-format', String(report), 'junit:<glob> (only junit is supported)')]);
+        }
+        return ok({ mode: 'filtered', template: runner, reportGlob: report.slice('junit:'.length) });
+    }
+    return ok({ mode: 'filtered', template: runner });
+}
+export function criteriaExcludes(cfg) {
+    const crit = (cfg.raw.criteria ?? {});
+    const extra = Array.isArray(crit.exclude) ? crit.exclude.filter((g) => typeof g === 'string') : [];
+    return [`${cfg.paths.specs}/**`, `${cfg.paths.plans}/**`, '.witness/**', ...extra];
+}
+export function execCommand(runRoot, ctx, cmd) {
+    try {
+        const out = execSync(cmd, { cwd: runRoot, env: ctx.env, stdio: 'pipe' });
+        return { exitZero: true, output: String(out).slice(-4000) };
+    }
+    catch (e) {
+        const err = e;
+        return { exitZero: false, output: `${String(err.stdout ?? '')}${String(err.stderr ?? '')}`.slice(-4000) };
+    }
+}
+export async function runFiltered(runRoot, ctx, template, specId, trustRoot = runRoot) {
+    const trust = await ensureTrusted(trustRoot, ctx, template);
+    if (trust !== 'trusted') {
+        return refuse([v('criteria.runner', `untrusted-${trust}`, template, trust === 'blocked' ? 'allow interactively or set WITNESS_TRUST_CMDS=1' : 'trust was declined')]);
+    }
+    return ok(execCommand(runRoot, ctx, template.replaceAll('{id}', specId)));
+}
+export async function runFullSuite(runRoot, ctx, rc, trustRoot = runRoot) {
+    const trust = await ensureTrusted(trustRoot, ctx, rc.suiteCmd);
+    if (trust !== 'trusted') {
+        return refuse([v('ship.test', `untrusted-${trust}`, rc.suiteCmd, trust === 'blocked' ? 'allow interactively or set WITNESS_TRUST_CMDS=1' : 'trust was declined')]);
+    }
+    for (const f of reportFiles(runRoot, rc.reportGlob))
+        rmSync(join(runRoot, f));
+    const run = execCommand(runRoot, ctx, rc.suiteCmd);
+    const merged = mergeReports(runRoot, rc.reportGlob);
+    if (!merged.ok)
+        return merged;
+    return ok({ run, tests: merged.value });
+}

package/dist/scan.js

@@ -0,0 +1,67 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { canonPaths } from './config.js';
+import { readDoc } from './fm.js';
+import { validateDoc } from './schemas.js';
+export function loadCanon(root) {
+    const docs = [];
+    const errors = [];
+    const paths = canonPaths(root);
+    for (const dir of [paths.specs, paths.plans]) {
+        const base = join(root, dir);
+        if (!existsSync(base))
+            continue;
+        for (const f of readdirSync(base, { recursive: true, encoding: 'utf8' })) {
+            if (!f.endsWith('.md'))
+                continue;
+            const rel = `${dir}/${f}`;
+            const parsed = readDoc(join(root, rel));
+            if (!parsed.ok) {
+                errors.push(...parsed.violations.map((x) => ({ ...x, field: `${rel}: ${x.field}` })));
+                continue;
+            }
+            docs.push({
+                rel,
+                meta: parsed.value.meta,
+                body: parsed.value.body,
+                violations: validateDoc(parsed.value.meta, parsed.value.body),
+            });
+        }
+    }
+    return { docs, errors, paths };
+}
+export function findById(canon, id) {
+    return canon.docs.find((d) => d.meta.id === id);
+}
+export function findCycle(canon, extra) {
+    const deps = new Map();
+    for (const d of canon.docs) {
+        deps.set(String(d.meta.id), Array.isArray(d.meta.depends) ? d.meta.depends : []);
+    }
+    if (extra)
+        deps.set(extra.id, extra.depends);
+    const state = new Map();
+    const stack = [];
+    const visit = (n) => {
+        if (state.get(n) === 2)
+            return undefined;
+        if (state.get(n) === 1)
+            return [...stack.slice(stack.indexOf(n)), n];
+        state.set(n, 1);
+        stack.push(n);
+        for (const d of deps.get(n) ?? []) {
+            const cycle = visit(d);
+            if (cycle)
+                return cycle;
+        }
+        stack.pop();
+        state.set(n, 2);
+        return undefined;
+    };
+    for (const n of deps.keys()) {
+        const cycle = visit(n);
+        if (cycle)
+            return cycle;
+    }
+    return undefined;
+}