@juzser/blacksmith 0.1.0

package/factory/orchestrator/dist/hookDecision.js

@@ -0,0 +1,106 @@
+// The PreToolUse decision, on its own, so that the hot path can hold it
+// without holding the rest of the orchestrator.
+//
+// `.claude/hooks/guard.sh` fires on every Bash/Write/Edit/MultiEdit/
+// NotebookEdit call an agent makes, which makes whatever it execs the most
+// frequently run code in this repo by orders of magnitude. It used to exec
+// `dist/cli.js policy hook`; cli.ts imports the whole orchestrator at module
+// scope, `db/projector.js` and so drizzle-orm among it, and that graph cost
+// ~1.3s to load in front of ~39ms of policy work — a database layer loaded
+// and thrown away once per guarded action. Splitting the decision out lets
+// `policyHook.ts` be an entry point whose imports are only what deciding
+// actually needs, while `cli.ts` keeps `smith policy hook` by calling the
+// same function rather than a second copy of it.
+import { detectCurrentBranch, detectRepoRoot, evaluateCommand, loadGuardrailPolicy, } from './policy.js';
+import { activeSandboxFor } from './sandbox.js';
+/**
+ * Reads one PreToolUse payload and answers with the envelope to print, or
+ * `null` to print nothing.
+ *
+ * Two outcomes, and the caller signals them apart by exit code:
+ *   - a reachable decision: exit 0, and either this envelope on stdout or
+ *     silence.
+ *   - could not reach a decision at all: a throw, left to propagate, which
+ *     the caller turns into a non-zero exit.
+ *
+ * A malformed payload takes the second path on purpose. guard.sh's own
+ * `extract_field` used to return '' on anything it could not parse, which
+ * read as "no tool_name" and let every rule fall through as a silent allow —
+ * invisibly, since a BSD-vs-GNU `sed` incompatibility meant this had been
+ * happening on every macOS run since Phase 2 (see guard.sh's header).
+ * "Cannot parse the input" and "nothing to inspect" must never look the same
+ * again: the first is failure, the second is a real allow, and only guard.sh's
+ * fail-closed handling of a non-zero exit may turn "failure" into a denial.
+ */
+export function decideHookPayload(raw, fallbackCwd) {
+    const payload = JSON.parse(raw);
+    const toolName = typeof payload.tool_name === 'string' ? payload.tool_name : '';
+    const command = typeof payload.tool_input?.command === 'string' ? payload.tool_input.command : '';
+    // A `Write`/`Edit`/`MultiEdit` payload carries no command; its target is
+    // `tool_input.file_path`, absolute. Bash was the only tool worth inspecting
+    // while every leased role was a judge, since judges hold no file tools and a
+    // shell was their only write path. A tester holds both, so watching only
+    // Bash would leave the rule to be routed around with the tool the role was
+    // handed. Same shape as `command`: a missing or non-string field reads as
+    // absent, never as a guess.
+    const filePath = typeof payload.tool_input?.file_path === 'string' ? payload.tool_input.file_path : null;
+    // Branch and repo root come from where the command would actually run, which
+    // the PreToolUse payload carries as `cwd`. Resolving them from this binary's
+    // own checkout instead would be wrong in the case this factory spends most of
+    // its time in: guard.sh always execs the main clone's dist, while the session
+    // issuing the command is usually inside a per-task git worktree on a
+    // different branch. That gap is not academic — `git rebase` on
+    // smith/<epic>/integration is a rule-5 denial, and the merge queue performs
+    // rebases from a worktree standing on exactly that branch while the main
+    // clone stands elsewhere. The old bash hook got this right for free by
+    // running `git rev-parse` in its own inherited cwd; the port has to ask for
+    // it. `fallbackCwd` covers a payload without the field (a hand-driven
+    // invocation, or an older client), and a cwd outside any repo resolves to
+    // ''/null, which denies an out-of-bounds removal rather than allowing it.
+    const cwd = typeof payload.cwd === 'string' && payload.cwd !== '' ? payload.cwd : fallbackCwd;
+    const context = {
+        toolName,
+        command,
+        branch: detectCurrentBranch(cwd),
+        repoRoot: detectRepoRoot(cwd),
+        // Resolved from the same `cwd`, and for the same reason: the lease is keyed
+        // by the worktree a judge was handed, and `cwd` is the only thing in a
+        // PreToolUse payload that says where the command will run. No lease is the
+        // ordinary case and costs one directory read.
+        sandbox: activeSandboxFor(cwd),
+        filePath,
+    };
+    const decision = evaluateCommand(context, loadGuardrailPolicy());
+    if (decision.allowed) {
+        // Allow prints NOTHING, on purpose, and this is not a cosmetic choice.
+        // Claude Code reads an explicit `permissionDecision: "allow"` from a hook
+        // as "skip the permission system for this call" — it outranks the
+        // operator's own `permissions.deny` list and suppresses the approval
+        // prompt. A guard hook that emitted it on every command it did not
+        // recognise would therefore not be a guard at all: it would be a blanket
+        // auto-approver for everything outside guardrails.yml's rules, which is a
+        // strictly wider grant than the hook it replaces ever had. Empty stdout is
+        // the protocol's "no opinion, carry on with the normal permission flow",
+        // which is exactly what this layer means when no rule fires. The exit code
+        // still separates "no opinion" (0, silent) from "could not decide"
+        // (non-zero, which guard.sh turns into a deny), so silence here is never
+        // load-bearing the way the old hook's was.
+        return null;
+    }
+    // guard.sh only ever surfaced one reason: each rule block()ed and exited
+    // immediately on its own match, sequentially, so the first rule in guard.sh's
+    // 1-6 order to fire is the only one an agent ever saw. evaluateCommand's
+    // checks array preserves that same order, so violations[0] reproduces
+    // guard.sh's exact visible behaviour even though evaluateCommand (policy
+    // check's diagnostic output) reports every rule that tripped, not just the
+    // first.
+    const first = decision.violations[0];
+    const reason = first ? first.reason : 'guardrails.yml denied this command.';
+    return {
+        hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'deny',
+            permissionDecisionReason: `BLOCKED: ${reason}`,
+        },
+    };
+}

package/factory/orchestrator/dist/immutability.js

@@ -0,0 +1,171 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { SmithError } from './errors.js';
+import { runGit as git, runGitRaw } from './git.js';
+export class ImmutabilityError extends SmithError {
+}
+/** The taxonomy class raised when a judge moved the worktree it was judging. */
+export const JUDGE_MUTATION_CODE = 'contract.judge-mutation';
+const PORCELAIN_STATUS_WIDTH = 3; // "XY " — two status chars plus the separator
+const HASH_LENGTH = 12;
+const GONE = 'gone';
+const HEAD_PATH = 'HEAD';
+function assertGitWorktree(worktreeDir) {
+    try {
+        git(worktreeDir, ['rev-parse', '--is-inside-work-tree']);
+    }
+    catch (err) {
+        throw new ImmutabilityError('immutability.not-a-git-worktree', `${worktreeDir} is not a git worktree: ${err instanceof Error ? err.message : String(err)}`, { worktreeDir });
+    }
+}
+function headSha(worktreeDir) {
+    try {
+        return git(worktreeDir, ['rev-parse', 'HEAD']);
+    }
+    catch {
+        return null; // unborn branch — a worktree with no commits yet
+    }
+}
+function currentBranch(worktreeDir) {
+    try {
+        return git(worktreeDir, ['branch', '--show-current']) || null; // empty when detached
+    }
+    catch {
+        return null;
+    }
+}
+function hashFile(worktreeDir, relPath) {
+    try {
+        return createHash('sha256')
+            .update(readFileSync(path.join(worktreeDir, relPath)))
+            .digest('hex')
+            .slice(0, HASH_LENGTH);
+    }
+    catch {
+        return null; // deleted, a directory, or unreadable — all "no bytes here"
+    }
+}
+/**
+ * Every path git currently reports as dirty or untracked, `-z`-parsed so
+ * spaces and newlines in filenames survive. Renames and copies emit two
+ * fields (destination then source); both are recorded, since a judge that
+ * renamed a file moved two paths.
+ */
+function statusEntries(worktreeDir) {
+    const output = runGitRaw(worktreeDir, [
+        'status',
+        '--porcelain=v1',
+        '-z',
+        '--untracked-files=all',
+    ]);
+    const fields = output.split('\0');
+    const entries = {};
+    for (let i = 0; i < fields.length; i++) {
+        const field = fields[i];
+        if (field.length <= PORCELAIN_STATUS_WIDTH)
+            continue;
+        const status = field.slice(0, 2);
+        const target = field.slice(PORCELAIN_STATUS_WIDTH);
+        entries[target] = { status, hash: hashFile(worktreeDir, target) };
+        if (status.startsWith('R') || status.startsWith('C')) {
+            const source = fields[i + 1];
+            if (source)
+                entries[source] = { status, hash: hashFile(worktreeDir, source) };
+            i++;
+        }
+    }
+    return entries;
+}
+/**
+ * The state a judge must hand back untouched: HEAD, the checked-out branch,
+ * and every dirty/untracked path with a hash of its bytes.
+ *
+ * Two deliberate choices, both load-bearing:
+ *
+ * 1. **Content hashes, not just the status list.** Six roles (reviewer,
+ *    verifier, grader, spec-reviewer, security-reviewer, uiux) are read-only
+ *    in prose and hold `Bash` in fact (agent-interviews.md N-10), so the
+ *    guarantee needs a check. A status-only fingerprint has a hole exactly
+ *    where it matters: the coder leaves `src/parse.ts` dirty, the judge edits
+ *    it again, and the porcelain line reads `" M src/parse.ts"` both times.
+ *    The hash closes it.
+ * 2. **No `--ignored`.** Judges run the suite — that is what `Bash` is for —
+ *    and running it writes `node_modules/`, `dist/`, coverage caches. A guard
+ *    that fired on those would be turned off within a day. Widening
+ *    `.gitignore` is not an escape hatch: that edit is itself a tracked-file
+ *    change, and ignore rules never apply to already-tracked files.
+ *
+ * The remaining hole is honest and small: an edit reverted byte-for-byte
+ * before the judge exits is invisible to any before/after comparison.
+ */
+export function fingerprintWorktree(worktreeDir) {
+    assertGitWorktree(worktreeDir);
+    return {
+        head: headSha(worktreeDir),
+        branch: currentBranch(worktreeDir),
+        entries: statusEntries(worktreeDir),
+    };
+}
+function describe(entry) {
+    return `${entry.status} ${entry.hash ?? GONE}`;
+}
+function assertFingerprint(value) {
+    if (value === null ||
+        typeof value !== 'object' ||
+        typeof value.entries !== 'object' ||
+        value.entries === null ||
+        !('head' in value)) {
+        throw new ImmutabilityError('immutability.invalid-fingerprint', 'The before-fingerprint is not a WorktreeFingerprint ({ head, branch, entries }).', { received: value === null ? 'null' : typeof value });
+    }
+}
+/**
+ * Compare the worktree as it stands now against the fingerprint taken before
+ * a judge ran. Any difference is a violation: the judge is not the coder, and
+ * the one path it may write is its own artifact under `state/results/`, which
+ * lives outside the worktree.
+ */
+export function checkWorktreeImmutable(worktreeDir, before) {
+    assertFingerprint(before);
+    const after = fingerprintWorktree(worktreeDir);
+    const drift = [];
+    if (before.head !== after.head) {
+        drift.push({ kind: 'head-moved', path: HEAD_PATH, before: before.head, after: after.head });
+    }
+    if (before.branch !== after.branch) {
+        drift.push({
+            kind: 'branch-switched',
+            path: HEAD_PATH,
+            before: before.branch,
+            after: after.branch,
+        });
+    }
+    for (const key of [
+        ...new Set([...Object.keys(before.entries), ...Object.keys(after.entries)]),
+    ].sort()) {
+        const wasEntry = before.entries[key];
+        const isEntry = after.entries[key];
+        if (!wasEntry && isEntry) {
+            drift.push({ kind: 'dirtied', path: key, before: null, after: describe(isEntry) });
+        }
+        else if (wasEntry && !isEntry) {
+            drift.push({ kind: 'reverted', path: key, before: describe(wasEntry), after: null });
+        }
+        else if (wasEntry && isEntry && describe(wasEntry) !== describe(isEntry)) {
+            drift.push({
+                kind: 'modified',
+                path: key,
+                before: describe(wasEntry),
+                after: describe(isEntry),
+            });
+        }
+    }
+    const unchanged = drift.length === 0;
+    return {
+        unchanged,
+        drift,
+        violation: unchanged
+            ? null
+            : { error: JUDGE_MUTATION_CODE, paths: [...new Set(drift.map((d) => d.path))] },
+    };
+}

package/factory/orchestrator/dist/impact.js

@@ -0,0 +1,280 @@
+/**
+ * What a path claim cannot say, said here.
+ *
+ * `claims.ts` answers "did two tasks write the same file". That question has a
+ * blind spot with a name: task A changes `parse()`'s signature in `src/a.ts`,
+ * task B calls `parse()` from `src/b.ts`, the two claim lists are disjoint,
+ * every gate is green, and integration is where the factory finds out. The
+ * conflict was never in a file — it lived on the edge between two files, which
+ * is exactly what `symbols.ts` reads.
+ *
+ * Two checks, and the difference between them is the difference between a risk
+ * and a fact:
+ *
+ * - `waveImpact` runs BEFORE dispatch, over declarations. It can only see that
+ *   two tasks in one wave sit on either end of a compile-time edge. That is a
+ *   reason to order them, not evidence that anything is wrong, so it reports
+ *   `coupled` and stops the wave from running them in parallel.
+ * - `exportImpact` runs AFTER the work, over a diff. Here an export that was
+ *   removed while a file outside the claims still imports it is not a risk —
+ *   it is a break, and it is provable. A changed signature is weaker: this
+ *   module reads text, not types, so it says `possible` and means it.
+ *
+ * Holes are reported, never fatal. The scanner has blind spots (a `.vue` file,
+ * an unterminated literal), and failing a wave for the scanner's limits would
+ * teach operators to reach for the override — which costs more than the check
+ * was ever worth.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { extname, join } from 'node:path';
+import { claimCoversPath, integrationBranchFor } from './claims.js';
+import { runGit } from './git.js';
+import { DEFAULT_SOURCE_EXTENSIONS, parseModuleFacts, } from './symbols.js';
+/**
+ * File -> the task that claims it. First claim wins: a file claimed twice is an
+ * overlap, and `validateWave` already refuses that wave for its own reasons.
+ */
+function ownersOf(files, tasks) {
+    const owner = new Map();
+    for (const task of tasks) {
+        for (const file of files) {
+            if (owner.has(file))
+                continue;
+            if (task.claims.some((claim) => claimCoversPath(claim, file)))
+                owner.set(file, task.task_id);
+        }
+    }
+    return owner;
+}
+export function waveImpact(graph, tasks) {
+    // Unreadable files are absent from `modules` but still claimable, and a task
+    // that claims one has matched a real file — it is the reading that failed.
+    const known = [...graph.modules.keys(), ...graph.unanalyzed].sort();
+    const owner = ownersOf(known, tasks);
+    const claimed = new Set(owner.values());
+    const crossings = new Map();
+    const exposure = new Map();
+    for (const [exportedBy, edges] of graph.dependents) {
+        const producer = owner.get(exportedBy);
+        if (producer === undefined)
+            continue;
+        for (const edge of edges) {
+            const consumer = owner.get(edge.from);
+            if (consumer === undefined) {
+                const key = `${producer} ${exportedBy} ${edge.from}`;
+                const seen = exposure.get(key);
+                if (seen === undefined) {
+                    exposure.set(key, {
+                        producer,
+                        exportedBy,
+                        importedBy: edge.from,
+                        names: new Set(edge.names),
+                    });
+                }
+                else {
+                    for (const name of edge.names)
+                        seen.names.add(name);
+                }
+                continue;
+            }
+            if (consumer === producer)
+                continue;
+            const key = `${producer} ${consumer} ${exportedBy} ${edge.from}`;
+            const seen = crossings.get(key);
+            if (seen === undefined) {
+                crossings.set(key, {
+                    producer,
+                    consumer,
+                    exportedBy,
+                    importedBy: edge.from,
+                    symbols: new Set(edge.names),
+                    typeOnly: edge.typeOnly,
+                    dynamic: edge.dynamic,
+                });
+            }
+            else {
+                for (const name of edge.names)
+                    seen.symbols.add(name);
+                // One value import is enough to make the coupling a value coupling.
+                seen.typeOnly = seen.typeOnly && edge.typeOnly;
+                seen.dynamic = seen.dynamic && edge.dynamic;
+            }
+        }
+    }
+    const orderedCrossings = [...crossings.values()]
+        .map((c) => ({
+        producer: c.producer,
+        consumer: c.consumer,
+        exportedBy: c.exportedBy,
+        importedBy: c.importedBy,
+        symbols: [...c.symbols].sort(),
+        typeOnly: c.typeOnly,
+        dynamic: c.dynamic,
+    }))
+        .sort((a, b) => a.producer.localeCompare(b.producer) ||
+        a.consumer.localeCompare(b.consumer) ||
+        a.exportedBy.localeCompare(b.exportedBy) ||
+        a.importedBy.localeCompare(b.importedBy));
+    const orderedExposure = [...exposure.values()]
+        .map((e) => ({
+        producer: e.producer,
+        exportedBy: e.exportedBy,
+        importedBy: e.importedBy,
+        symbols: [...e.names].sort(),
+    }))
+        .sort((a, b) => a.producer.localeCompare(b.producer) ||
+        a.exportedBy.localeCompare(b.exportedBy) ||
+        a.importedBy.localeCompare(b.importedBy));
+    const claimsWithoutFiles = tasks
+        .filter((task) => !claimed.has(task.task_id))
+        .map((task) => task.task_id);
+    const unanalyzed = graph.unanalyzed.filter((file) => owner.has(file));
+    const unresolved = graph.unresolved.filter((entry) => owner.has(entry.from));
+    const hasHoles = unanalyzed.length > 0 || unresolved.length > 0;
+    const status = orderedCrossings.length > 0 ? 'coupled' : hasHoles ? 'unverifiable' : 'clean';
+    return {
+        status,
+        ok: status !== 'coupled',
+        crossings: orderedCrossings,
+        exposure: orderedExposure,
+        claimsWithoutFiles,
+        unanalyzed,
+        unresolved,
+        detail: describeWave(status, orderedCrossings, orderedExposure, unanalyzed.length + unresolved.length),
+    };
+}
+function describeWave(status, crossings, exposure, holes) {
+    const parts = [];
+    if (status === 'coupled') {
+        const pairs = new Set(crossings.map((c) => `${c.producer}/${c.consumer}`));
+        parts.push(`${crossings.length} symbol crossing(s) across ${pairs.size} task pair(s): run them in order, not in parallel.`);
+    }
+    else if (status === 'unverifiable') {
+        parts.push('No crossing found, but the graph has holes over this wave - treat the result as partial.');
+    }
+    else {
+        parts.push('No task in this wave imports a symbol another task in this wave exports.');
+    }
+    if (exposure.length > 0) {
+        parts.push(`${exposure.length} file(s) outside the wave import from claimed files.`);
+    }
+    if (holes > 0)
+        parts.push(`${holes} unreadable or unresolved edge(s) over claimed files.`);
+    return parts.join(' ');
+}
+/**
+ * The classifier half (P9-3): two texts in, a diff out. Knows nothing about
+ * git, which is what lets the wave gate, the merge queue and a test all ask it
+ * the same question.
+ */
+export function diffExports(before, after, file) {
+    const b = parseModuleFacts(before, file);
+    const a = parseModuleFacts(after, file);
+    if (b.unterminated || a.unterminated) {
+        return { file, removed: [], added: [], signatureChanged: [], unverifiable: true };
+    }
+    const afterNames = new Set(a.exports);
+    const beforeNames = new Set(b.exports);
+    return {
+        file,
+        removed: b.exports.filter((name) => !afterNames.has(name)),
+        added: a.exports.filter((name) => !beforeNames.has(name)),
+        signatureChanged: b.exports.filter((name) => afterNames.has(name) && b.exportSignatures.get(name) !== a.exportSignatures.get(name)),
+        unverifiable: false,
+    };
+}
+/** A namespace import consumes whatever the module exports, named or not. */
+function consumes(names, symbol) {
+    return names.includes('*') || names.includes(symbol);
+}
+/**
+ * Whose files broke. `claims` is the acting task's own claim list: an importer
+ * the task already owns is not a break, because the same task is free to fix
+ * it in the same diff — and usually has.
+ */
+export function exportImpact(graph, diffs, claims) {
+    const breaks = [];
+    const unverifiable = [];
+    for (const diff of diffs) {
+        if (diff.unverifiable) {
+            unverifiable.push(diff.file);
+            continue;
+        }
+        if (diff.removed.length === 0 && diff.signatureChanged.length === 0)
+            continue;
+        for (const edge of graph.dependents.get(diff.file) ?? []) {
+            if (claims.some((claim) => claimCoversPath(claim, edge.from)))
+                continue;
+            const gone = diff.removed.filter((symbol) => consumes(edge.names, symbol));
+            const moved = diff.signatureChanged.filter((symbol) => consumes(edge.names, symbol));
+            if (gone.length > 0) {
+                breaks.push({
+                    severity: 'proven',
+                    reason: 'removed',
+                    exportedBy: diff.file,
+                    importedBy: edge.from,
+                    symbols: gone,
+                });
+            }
+            if (moved.length > 0) {
+                breaks.push({
+                    severity: 'possible',
+                    reason: 'signature-changed',
+                    exportedBy: diff.file,
+                    importedBy: edge.from,
+                    symbols: moved,
+                });
+            }
+        }
+    }
+    breaks.sort((a, b) => (a.severity === b.severity ? 0 : a.severity === 'proven' ? -1 : 1) ||
+        a.exportedBy.localeCompare(b.exportedBy) ||
+        a.importedBy.localeCompare(b.importedBy));
+    const proven = breaks.filter((entry) => entry.severity === 'proven').length;
+    const possible = breaks.length - proven;
+    const parts = [];
+    if (proven > 0)
+        parts.push(`${proven} importer(s) outside the claims lost a symbol they use.`);
+    if (possible > 0) {
+        parts.push(`${possible} importer(s) use a symbol whose declaration changed shape.`);
+    }
+    if (proven === 0 && possible === 0) {
+        parts.push('No importer outside the claims depends on what moved.');
+    }
+    if (unverifiable.length > 0)
+        parts.push(`Unreadable, so unchecked: ${unverifiable.join(', ')}.`);
+    return { ok: proven === 0, breaks, detail: parts.join(' ') };
+}
+/**
+ * The collector half (P9-3): read both sides of each changed file out of git.
+ *
+ * `ls-tree` before `show` on purpose — a file added on this branch is absent
+ * from the integration branch, and asking `show` for it would raise an error
+ * that means "new file", which is not an error at all.
+ */
+export function collectExportDiffs(worktreeDir, changedFiles) {
+    const integrationBranch = integrationBranchFor(worktreeDir);
+    const diffs = [];
+    for (const file of changedFiles) {
+        if (!DEFAULT_SOURCE_EXTENSIONS.includes(extname(file)))
+            continue;
+        const listed = runGit(worktreeDir, [
+            'ls-tree',
+            '-r',
+            '--name-only',
+            integrationBranch,
+            '--',
+            file,
+        ]);
+        const before = listed === '' ? '' : runGit(worktreeDir, ['show', `${integrationBranch}:${file}`]);
+        const absolute = join(worktreeDir, file);
+        const after = existsSync(absolute) ? readFileSync(absolute, 'utf8') : '';
+        if (before === '' && after === '')
+            continue;
+        const diff = diffExports(before, after, file);
+        const moved = diff.removed.length > 0 || diff.added.length > 0 || diff.signatureChanged.length > 0;
+        if (diff.unverifiable || moved)
+            diffs.push(diff);
+    }
+    return diffs;
+}