@juzser/blacksmith 0.1.0

package/factory/orchestrator/dist/gh.js

@@ -0,0 +1,146 @@
+// Pure core, part two: WHICH repository a project belongs to, WHETHER `gh`
+// can be used, and WHAT argv the three `gh` commands this epic runs would
+// be. Nothing here spawns `gh` -- every test asserts on the argv that WOULD
+// have been run.
+//
+// SECURITY: never interpolates untrusted text into a command, never sets
+// `shell: true`, never logs a URL without `redactCredentials`, never
+// reads/stores/prints a token. `readOriginUrl` hands back credentials
+// intact; this module extracts only host and slug.
+//
+// Issue bodies travel by `--body-file <temp file>`, not inline `--body` or
+// stdin: keeps gh's own flag parsing and argv-length limits out of scope,
+// and keeps the runner's `(cmd, args) => result` signature free of stdin.
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { GitCommandError, readOriginUrl, redactCredentials } from './git.js';
+const HTTPS_RE = /^https?:\/\/(?:[^/@]+@)?([^/]+)\/([^/]+)\/([^/]+?)(?:\.git)?\/?$/;
+const SSH_URL_RE = /^ssh:\/\/git@([^/]+)\/([^/]+)\/([^/]+?)(?:\.git)?$/;
+const SCP_RE = /^git@([^:]+):([^/]+)\/([^/]+?)(?:\.git)?$/;
+function parseRemote(url) {
+    for (const re of [HTTPS_RE, SSH_URL_RE, SCP_RE]) {
+        const m = url.match(re);
+        if (m)
+            return { host: m[1] ?? '', owner: m[2] ?? '', repo: m[3] ?? '' };
+    }
+    return null;
+}
+/**
+ * Turns a git remote URL into an `owner/repo` slug. Parses the https, scp-
+ * style and `ssh://` forms, including an https URL carrying userinfo
+ * credentials -- the credentials are never part of the returned value. A
+ * host that is not `github.com` is refused, not guessed.
+ */
+export function slugFromRemoteUrl(url) {
+    const parsed = parseRemote(url);
+    const safeUrl = redactCredentials(url);
+    if (!parsed) {
+        return { reason: 'unparseable-remote', detail: `cannot parse remote URL: ${safeUrl}` };
+    }
+    if (parsed.host !== 'github.com') {
+        return {
+            reason: 'non-github-host',
+            detail: `remote host "${parsed.host}" is not github.com: ${safeUrl}`,
+        };
+    }
+    return { slug: `${parsed.owner}/${parsed.repo}` };
+}
+/**
+ * Which repository the git checkout at `dir` belongs to. Classifies a
+ * `GitCommandError` from `readOriginUrl` into `not-a-repo` or `no-origin`
+ * before handing a resolved URL to `slugFromRemoteUrl`; any other error is
+ * a programming or environment fault and is rethrown, not mis-filed.
+ */
+export function resolveRepoAtDir(dir) {
+    let url;
+    try {
+        url = readOriginUrl(dir);
+    }
+    catch (err) {
+        if (err instanceof GitCommandError) {
+            if (/not a git repository/i.test(err.stderr)) {
+                return { reason: 'not-a-repo', detail: `${dir} is not a git repository` };
+            }
+            return { reason: 'no-origin', detail: `${dir} has no "origin" remote` };
+        }
+        throw err;
+    }
+    return slugFromRemoteUrl(url);
+}
+/**
+ * Which repository a named project belongs to, answered from a register
+ * handed in -- never a name lookup under `PROJECTS_DIR`/`WORKSPACES_DIR` and
+ * never a fallback to this process's own directory (projects.ts: this
+ * clone's parent can hold an unrelated checkout with an unrelated remote).
+ * A project the register does not name is refused as `no-checkout`, never
+ * answered with another project's slug.
+ */
+export function resolveProjectRepo(project, register) {
+    const entry = register.find((r) => r.name === project);
+    if (!entry) {
+        return { reason: 'no-checkout', detail: `no checkout registered for project "${project}"` };
+    }
+    return resolveRepoAtDir(entry.dir);
+}
+/** Not reachable from the test suite: every test in gh.test.ts passes a stub. */
+function defaultRunner(cmd, args) {
+    try {
+        const stdout = execFileSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+        return { status: 0, stdout, stderr: '' };
+    }
+    catch (err) {
+        const e = err;
+        const status = typeof e.status === 'number' ? e.status : null;
+        const spawnError = typeof e.code === 'string' ? e.code : undefined;
+        return {
+            status,
+            stdout: e.stdout ?? '',
+            stderr: redactCredentials(e.stderr ?? ''),
+            spawnError,
+        };
+    }
+}
+/** Classifies `gh` availability by driving `gh auth status` through the injected runner. */
+export function classifyGh(runner = defaultRunner) {
+    const result = runner('gh', ['auth', 'status']);
+    if (result.spawnError !== undefined) {
+        return { outcome: 'missing', reason: `gh could not be run (${result.spawnError})` };
+    }
+    if (result.status === 0) {
+        return { outcome: 'ready' };
+    }
+    const said = `${result.stdout}\n${result.stderr}`.toLowerCase();
+    if (said.includes('not logged') || said.includes('auth login')) {
+        return {
+            outcome: 'unauthenticated',
+            reason: result.stderr.trim() || result.stdout.trim(),
+        };
+    }
+    return { outcome: 'unknown', reason: `gh auth status exited ${String(result.status)}` };
+}
+/**
+ * Writes `body` to a fresh temp file and returns its path, for `--body-file`.
+ * The body never becomes an argv element, so "no element of argv contains a
+ * composed shell fragment" holds by construction.
+ */
+function writeBodyFile(body) {
+    const dir = mkdtempSync(path.join(tmpdir(), 'smith-gh-body-'));
+    const file = path.join(dir, 'body.md');
+    writeFileSync(file, body, 'utf8');
+    return file;
+}
+/** Pure builder: the argv for `gh issue create`. Spawns nothing. */
+export function buildCreateIssueArgv(repo, title, body) {
+    return ['issue', 'create', '--repo', repo, '--title', title, '--body-file', writeBodyFile(body)];
+}
+/** Pure builder: the argv for `gh issue list` restricted to open issues matching `query`. */
+export function buildSearchIssuesArgv(repo, query) {
+    return ['issue', 'list', '--repo', repo, '--state', 'open', '--search', query];
+}
+/** Pure builder: the argv for `gh issue comment`. Spawns nothing. */
+export function buildCommentArgv(repo, issueNumber, body) {
+    const file = writeBodyFile(body);
+    return ['issue', 'comment', String(issueNumber), '--repo', repo, '--body-file', file];
+}

package/factory/orchestrator/dist/git.js

@@ -0,0 +1,87 @@
+import { execFileSync } from 'node:child_process';
+import { SmithError } from './errors.js';
+/**
+ * The one place this factory shells out to git.
+ *
+ * P9-16(b)/D-24. `execFileSync` sends the child's stderr to the PARENT's
+ * stderr unless `stdio` is given explicitly — the default is documented as
+ * `'pipe'`, but stderr is inherited on top of it. Every module that had its
+ * own two-line `git()` helper therefore printed git's chatter straight onto
+ * the operator's terminal: `fatal: ref refs/remotes/origin/HEAD is not a
+ * symbolic ref` for every project without a remote (which is every project
+ * `smith new` creates), `Preparing worktree (new branch ...)` on each
+ * dispatch, `warning: You appear to have cloned an empty repository.` The
+ * factory speaks JSON on stdout; anything else on the terminal reads as a
+ * failure that isn't one.
+ *
+ * Silencing a channel must not delete what was on it, which is the D-47
+ * mistake one layer down. So stderr is captured and folded into the thrown
+ * error: the operator sees nothing while git succeeds, and sees git's own
+ * words the moment it doesn't.
+ *
+ * stdin is `'ignore'` rather than `'pipe'`: a git that decides to prompt —
+ * for a credential, for an editor — would otherwise wait forever on input
+ * that no unattended agent is going to type.
+ */
+export class GitCommandError extends SmithError {
+    /** git's own stderr, credential-redacted. Empty when it said nothing. */
+    stderr;
+    /** Exit code, or null when git was killed by a signal or never started. */
+    status;
+    constructor(cwd, args, status, stderr) {
+        const said = stderr.trim();
+        const how = status === null ? 'did not exit normally' : `exit ${status}`;
+        super('git.command-failed', `git ${args.join(' ')} failed in ${cwd} (${how})` +
+            (said === '' ? ' and said nothing' : `: ${said}`), { cwd, args, status, stderr });
+        this.stderr = stderr;
+        this.status = status;
+    }
+}
+/** `https://user:token@host/…` → `https://user:***@host/…`, and the token-only form too. */
+export function redactCredentials(text) {
+    return text.replace(/([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)([^/\s@]+)@/g, (_match, scheme, userinfo) => {
+        const colon = userinfo.indexOf(':');
+        return colon === -1 ? `${scheme}***@` : `${scheme}${userinfo.slice(0, colon)}:***@`;
+    });
+}
+function exec(cwd, args) {
+    try {
+        return execFileSync('git', args, {
+            cwd,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+    }
+    catch (err) {
+        const e = err;
+        // A child that never spawned has no exit code; `code` carries the errno
+        // string instead, and that is the only thing worth reporting.
+        const status = typeof e.status === 'number' ? e.status : null;
+        const said = e.stderr ?? (typeof e.code === 'string' ? `git could not be run (${e.code})` : '');
+        throw new GitCommandError(cwd, args, status, redactCredentials(said));
+    }
+}
+/** Run git and return its stdout, trailing newline removed. Throws GitCommandError. */
+export function runGit(cwd, args) {
+    return exec(cwd, args).trim();
+}
+/**
+ * Same, byte-for-byte. For `-z` output, where the record separator is a NUL
+ * and the trailing one is part of the format rather than noise to trim.
+ */
+export function runGitRaw(cwd, args) {
+    return exec(cwd, args);
+}
+/**
+ * The `origin` remote's URL, exactly as git reports it — credentials and
+ * all, since redaction happens only on the error path inside `exec`. Throws
+ * `GitCommandError` when `cwd` is not a git repository at all, or when it is
+ * one but has no `origin` remote. This function does not tell those two
+ * apart: git's own stderr already differs ("not a git repository" versus "No
+ * such remote"), and the one caller that needs to classify it (`gh.ts`) reads
+ * that text itself rather than this file growing a second refusal taxonomy
+ * beside the one it already has (`GitCommandError`).
+ */
+export function readOriginUrl(cwd) {
+    return runGit(cwd, ['remote', 'get-url', 'origin']);
+}

package/factory/orchestrator/dist/goalCheck.js

@@ -0,0 +1,380 @@
+// Spec-vs-goal gate.
+//
+// Every other gate in this factory reads something the planner authored. The
+// schema check reads the plan's own shape, the grader reads the plan's own
+// acceptance criteria, the reviewer reads a diff against the plan, and the
+// closing spec review (spec.ts) re-reads the plan against the code. All of
+// them answer "does the work match the spec". None of them can answer "is the
+// spec the right spec" -- a plan that decomposes the wrong goal perfectly
+// passes every one of them, and the epic closes green having built the wrong
+// thing. That is the failure this module exists for.
+//
+// The reference text therefore has to come from outside the plan. It is the
+// `- goal:` line of the roadmap milestone that owns the epic (roadmap.ts,
+// `ownsEpic`) -- written by the operator before planning, and never rewritten
+// by the planner. The gate splits it into clauses mechanically and asks: for
+// each clause, which live plan task delivers it?
+//
+// Three properties keep this from being a rubber stamp:
+//
+//   1. The clause list is not the judge's to choose. `goalClauses()` splits
+//      the goal deterministically, and recordGoalCheck refuses a coverage map
+//      whose clauses are not exactly that list, in that order. A judge cannot
+//      make an epic green by declining to mention the clause it failed.
+//   2. `covered` has to name live plan task ids, and they are checked against
+//      the plan roster. "Yes, somewhere" is not an answer.
+//   3. `out-of-scope` has to carry a reason, and the reason is recorded in the
+//      event. A milestone that holds several epics has clauses that belong to
+//      the siblings, and a retrospective goal paragraph has sentences that are
+//      history rather than requirements -- both are legitimate, and both are
+//      now a written dismissal an operator can audit instead of a silent drop.
+//
+// An `uncovered` clause mints a spec-scoped finding, so the remedy is the one
+// the plan's immutability allows: `smith plan amend`, cutting a version that
+// covers it. It is deliberately not a task-scoped finding -- no coder's diff
+// can contain the fix.
+//
+// Fail-closed on a missing goal, unlike mcp.ts's MCP_SURFACE_NOT_REQUIRED.
+// An epic can legitimately owe no MCP surface; an epic that owes no statement
+// of what it was for is an epic nobody can say succeeded. Treating that as
+// "not required" would rebuild the exact hole roadmap.ts's ownsEpic() doc
+// already regrets in writing -- a gate that skipped every project silently
+// from the day it shipped -- so the blockers below name the one-line roadmap
+// edit that clears them.
+//
+// Dependency direction matches spec.ts: epic.ts imports from here, never the
+// reverse.
+import { createHash } from 'node:crypto';
+import { SmithError } from './errors.js';
+import { appendEvent } from './events.js';
+import { mintFindings, raiseFinding } from './findings.js';
+import { loadRoadmap, ownsEpic } from './roadmap.js';
+import { RESERVED_TASK_ID } from './worktree.js';
+export class GoalCheckError extends SmithError {
+}
+export const GOAL_CHECK_EVENT = 'goal-check-recorded';
+/**
+ * An uncovered clause is always S2-major, and the judge does not get to grade
+ * it. "This epic does not deliver a clause of the goal it exists for" is one
+ * kind of defect, not a spectrum, and a judge that scores the severity of its
+ * own finding is the self-assessment problem the tester isolation just
+ * removed from the test gate.
+ */
+export const UNCOVERED_SEVERITY = 'S2-major';
+/**
+ * `finding_category` has no `spec-gap` value -- the taxonomy keeps that
+ * vocabulary in the `error.spec` group, for errors rather than findings. The
+ * scope (`finding_scope: spec`, set by mintFindings' `spec` context) is what
+ * says this is about the plan; the category says what kind of wrong it is,
+ * and a plan that does not deliver its goal is not correct.
+ */
+const UNCOVERED_CATEGORY = 'correctness';
+export const CLAUSE_VERDICTS = ['covered', 'out-of-scope', 'uncovered'];
+/** No milestone owns this epic, or the one that does declares no goal. */
+export const EPIC_GOAL_UNDECLARED = Object.freeze({
+    milestoneId: null,
+    goal: null,
+    clauses: [],
+    digest: null,
+});
+/**
+ * Split a goal into the clauses a plan has to answer, deterministically.
+ *
+ * Sentence-level and nothing finer. Comma splitting is the tempting next step
+ * and it is unsafe -- "Test gate, reviewer/verifier chain, severity policy"
+ * and "the worktree, which the coder owns, is disposable" are the same shape
+ * to a splitter and opposite things to a reader. A goal author who wants a
+ * requirement graded on its own writes it as its own sentence.
+ *
+ * Paragraph breaks split too, so a goal written as a bulleted or multi-line
+ * block grades line by line even where the lines carry no full stop.
+ *
+ * No abbreviation table. "e.g." splits a clause in two, and both halves then
+ * have to be answered or dismissed in writing -- noisier than ideal, but the
+ * safe direction: this function can over-split, and must never drop text a
+ * requirement was hiding in.
+ */
+export function goalClauses(text) {
+    const clauses = [];
+    for (const line of text.split(/\r?\n/)) {
+        // A terminator ends a clause only where the next sentence visibly starts:
+        // an uppercase letter, a digit, a quote or a backtick. "v1.2" and
+        // "state/events/x.jsonl" stay whole.
+        for (const piece of line.split(/(?<=[.!?])\s+(?=[A-Z0-9"'`(])/)) {
+            const clause = piece.trim();
+            if (clause.length > 0)
+                clauses.push(clause);
+        }
+    }
+    return clauses;
+}
+/**
+ * Digest of the goal text, whitespace-normalized so rewrapping a roadmap
+ * paragraph does not invalidate a check while rewording it does.
+ */
+export function goalDigest(text) {
+    const material = text.replace(/\s+/g, ' ').trim();
+    return createHash('sha256').update(material).digest('hex').slice(0, 16);
+}
+/**
+ * Read the epic's goal off the roadmap. Mirrors resolveMcpSurface: the I/O
+ * lives here and in the CLI that calls it, so summarizeEpic stays a pure fold
+ * over values it was handed.
+ *
+ * A milestone with a `- goal:` line that is present but empty resolves the
+ * same as one with no line at all. Both are "nobody wrote down what this was
+ * for", and the remedy is identical.
+ */
+export function resolveEpicGoal(opts) {
+    const milestone = loadRoadmap(opts.roadmapPath).find((m) => ownsEpic(m, opts.epicId));
+    if (!milestone)
+        return EPIC_GOAL_UNDECLARED;
+    const goal = milestone.goal?.trim() ?? '';
+    if (goal.length === 0) {
+        return { milestoneId: milestone.milestoneId, goal: null, clauses: [], digest: null };
+    }
+    return {
+        milestoneId: milestone.milestoneId,
+        goal,
+        clauses: goalClauses(goal),
+        digest: goalDigest(goal),
+    };
+}
+/** Last-wins fold: a re-check supersedes its predecessor, it does not stack. */
+export function latestGoalCheck(events, epicId) {
+    let latest = null;
+    for (const event of events) {
+        if (event.record.event_type !== GOAL_CHECK_EVENT)
+            continue;
+        const payload = event.record.payload;
+        if (payload.epic_id !== epicId)
+            continue;
+        latest = {
+            epicId,
+            milestoneId: String(payload.milestone_id ?? ''),
+            planVersion: Number(payload.plan_version ?? 0),
+            goalDigest: String(payload.goal_digest ?? ''),
+            checkedBy: String(payload.checked_by ?? ''),
+            coverage: (payload.coverage ?? []),
+            findingIds: (payload.finding_ids ?? []),
+            eventId: event.event_id,
+            ts: event.record.ts,
+        };
+    }
+    return latest;
+}
+const ROADMAP_REMEDY = "Give the milestone that owns it a `- goal:` line in factory/specs/roadmap.md, or add the epic to an existing milestone's `- epics:` list.";
+/**
+ * The epic gate refusing to certify a plan nobody checked against the goal it
+ * was written from.
+ *
+ * Every check here is mechanical — a deterministic oracle over recorded
+ * values, decided before any judge's opinion enters. The judge's opinion is
+ * in the coverage map; these are the things it is not allowed to be wrong
+ * about.
+ *
+ * A check reads two things and so goes stale two ways, exactly as D-125 found
+ * for the spec review: the plan it graded and the goal it graded against. An
+ * amendment bumps the version; an operator sharpening a vague goal line bumps
+ * the digest. Neither may stand in for the other — the moment a goal is
+ * rewritten is the moment a plan is likeliest to no longer answer it.
+ *
+ * `livePlanTaskIds` is the plan's live roster. Coverage citing an id that is
+ * not on it is rejected here as well as at record time, because an event can
+ * also arrive by hand.
+ */
+export function goalCheckBlockers(epicId, status, planVersion, livePlanTaskIds) {
+    const { check, goal } = status;
+    if (goal.milestoneId === null) {
+        return [
+            `No roadmap milestone owns epic "${epicId}", so there is no goal to check its plan against — the spec could be wrong from the first line and every other gate would still pass. ${ROADMAP_REMEDY}`,
+        ];
+    }
+    if (goal.goal === null || goal.digest === null) {
+        return [
+            `Milestone "${goal.milestoneId}" owns epic "${epicId}" but declares no goal, so there is nothing to check its plan against. ${ROADMAP_REMEDY}`,
+        ];
+    }
+    if (check === null) {
+        return [
+            `Epic "${epicId}" has no spec-vs-goal check on record: nothing has asked whether its plan answers the goal milestone "${goal.milestoneId}" declares. Run \`smith epic goal-check --epic ${epicId}\`.`,
+        ];
+    }
+    if (check.goalDigest !== goal.digest) {
+        return [
+            `The spec-vs-goal check for "${epicId}" is stale: it read a goal that digests to ${check.goalDigest}, and milestone "${goal.milestoneId}" now declares one that digests to ${goal.digest}. The plan has been checked against a goal the roadmap no longer states.`,
+        ];
+    }
+    if (planVersion !== null) {
+        // latestGoalCheck reads a missing plan_version as 0, and "I did not record
+        // which plan I graded" is unverifiable rather than current — the same
+        // fail-closed call specReviewBlockers makes.
+        if (!Number.isInteger(check.planVersion) || check.planVersion < 1) {
+            return [
+                `The spec-vs-goal check for "${epicId}" records no plan version, so it cannot be shown to cover plan v${planVersion}.`,
+            ];
+        }
+        if (check.planVersion < planVersion) {
+            return [
+                `The spec-vs-goal check for "${epicId}" is stale: it graded plan v${check.planVersion}, and the epic's live plan is v${planVersion}. Whatever the amendment changed has been checked against no goal at all.`,
+            ];
+        }
+        if (check.planVersion > planVersion) {
+            return [
+                `The spec-vs-goal check for "${epicId}" records plan v${check.planVersion}, and the epic's live plan is v${planVersion}: the check names a version the repository does not have.`,
+            ];
+        }
+        const live = new Set(livePlanTaskIds);
+        const phantom = [
+            ...new Set(check.coverage.flatMap((entry) => entry.taskIds ?? []).filter((id) => !live.has(id))),
+        ];
+        if (phantom.length > 0) {
+            return [
+                `The spec-vs-goal check for "${epicId}" credits ${phantom.length === 1 ? 'a task' : 'tasks'} that plan v${planVersion} does not have: ${phantom.join(', ')}. A clause covered by a task that does not exist is a clause nothing delivers.`,
+            ];
+        }
+    }
+    // The clause list is the goal's, not the check's (see goalClauses). A record
+    // whose clauses have drifted from the goal's is answering a different
+    // question, whatever its verdicts say.
+    const recorded = check.coverage.map((entry) => entry.clause);
+    if (recorded.length !== goal.clauses.length || recorded.some((c, i) => c !== goal.clauses[i])) {
+        return [
+            `The spec-vs-goal check for "${epicId}" covers ${recorded.length} clause(s) and milestone "${goal.milestoneId}" declares ${goal.clauses.length}. The recorded check does not answer the goal as written.`,
+        ];
+    }
+    const uncovered = check.coverage.filter((entry) => entry.verdict === 'uncovered');
+    if (uncovered.length > 0) {
+        return [
+            `The spec-vs-goal check for "${epicId}" left ${uncovered.length} goal clause(s) uncovered by plan v${check.planVersion}: ${uncovered.map((entry) => JSON.stringify(entry.clause)).join('; ')}. Answer them with \`smith plan amend\` — no task diff can contain the fix.`,
+        ];
+    }
+    return [];
+}
+/**
+ * Run the spec-vs-goal check's bookkeeping: validate the judge's coverage map
+ * against the goal it claims to answer, mint every uncovered clause as a
+ * spec-scoped finding, and record that the check happened.
+ *
+ * Everything validates before anything acts, the way amendPlan does: a run
+ * that raises three findings and then rejects the fourth clause has already
+ * changed the log for a check that never completed.
+ *
+ * The event is written even when every clause is covered, for the reason
+ * recordSpecReview's is: "ran and was clean" and "never ran" are different
+ * facts, and a gate that only logged the first would make a silent skip
+ * indistinguishable from a pass.
+ */
+export async function recordGoalCheck(input, ctx, opts = {}) {
+    const { epicId, milestoneId, planVersion, checkedBy } = input;
+    const taskId = `${epicId}/${RESERVED_TASK_ID}`;
+    const expected = goalClauses(input.goal);
+    if (expected.length === 0) {
+        throw new GoalCheckError('goal-check.empty-goal', `Milestone "${milestoneId}" declares no goal text for "${epicId}", so there are no clauses to check.`, { epicId, milestoneId });
+    }
+    const recorded = input.coverage.map((entry) => entry.clause);
+    if (recorded.length !== expected.length || recorded.some((c, i) => c !== expected[i])) {
+        throw new GoalCheckError('goal-check.clause-mismatch', `The coverage map for "${epicId}" must carry one entry per goal clause, in order: ${expected.length} expected, ${recorded.length} given. The clause list is the goal's, not the check's.`, { epicId, expected, recorded });
+    }
+    const live = new Set(input.livePlanTaskIds);
+    input.coverage.forEach((entry, index) => {
+        // Verdict first, and against a runtime list rather than the union type:
+        // this input arrives as JSON from a judge, so the compiler's guarantee is
+        // about the callers it can see, not about the value that shows up.
+        if (!CLAUSE_VERDICTS.includes(entry.verdict)) {
+            throw new GoalCheckError('goal-check.unknown-verdict', `Clause ${index + 1} of "${epicId}" carries verdict "${entry.verdict}". Valid: ${CLAUSE_VERDICTS.join(', ')}.`, { epicId, index, verdict: entry.verdict });
+        }
+        if (entry.verdict === 'covered') {
+            const cited = entry.taskIds ?? [];
+            if (cited.length === 0) {
+                throw new GoalCheckError('goal-check.covered-without-task', `Clause ${index + 1} of "${epicId}" is marked covered and names no task. "Covered somewhere" is not an answer a plan can be graded on.`, { epicId, index, clause: entry.clause });
+            }
+            const phantom = cited.filter((id) => !live.has(id));
+            if (phantom.length > 0) {
+                throw new GoalCheckError('goal-check.unknown-task', `Clause ${index + 1} of "${epicId}" is covered by ${phantom.join(', ')}, which plan v${planVersion} does not have as a live task.`, { epicId, index, clause: entry.clause, taskIds: phantom });
+            }
+            return;
+        }
+        if (entry.verdict === 'out-of-scope' && (entry.reason ?? '').trim().length === 0) {
+            throw new GoalCheckError('goal-check.dismissal-without-reason', `Clause ${index + 1} of "${epicId}" is dismissed as out of scope with no reason. A dismissal an operator cannot audit is a clause silently dropped.`, { epicId, index, clause: entry.clause });
+        }
+    });
+    // Anchored at the plan file's repo-relative path, written out rather than
+    // derived from opts.specsDir: the path is fingerprint material, and a
+    // tmpdir-rooted one would make the same defect dedup differently on every
+    // machine. Carrying the version means a re-check of an amended plan raises
+    // its own finding — a distinct claim about a distinct immutable artifact.
+    const anchor = `factory/specs/active/${epicId}/plan-v${planVersion}.json`;
+    const evidence = [];
+    input.coverage.forEach((entry, index) => {
+        if (entry.verdict !== 'uncovered')
+            return;
+        evidence.push({
+            file_path: anchor,
+            finding_category: UNCOVERED_CATEGORY,
+            severity: UNCOVERED_SEVERITY,
+            criterion_ref: `goal:${milestoneId}#${index + 1}`,
+            summary: `Plan v${planVersion} delivers no clause of the epic goal: ${entry.clause}`,
+            failure_scenario: {
+                inputs: `Milestone "${milestoneId}" declares the goal clause: ${entry.clause}`,
+                expected: `Some live task of plan v${planVersion} delivers it.`,
+                actual: 'No task in the plan answers it, so every task gate can pass, the epic can close, and the clause is still undelivered.',
+            },
+        });
+    });
+    const drafts = mintFindings(evidence, {
+        taskId,
+        foundBy: checkedBy,
+        ...(input.checkedByProvider === undefined
+            ? {}
+            : { foundByProvider: input.checkedByProvider }),
+        spec: { planVersion },
+    }, opts);
+    const findingIds = [];
+    for (const draft of drafts) {
+        const raised = await raiseFinding(draft, ctx, opts);
+        // A suppressed raise (fingerprint already waived) logged its own
+        // finding-suppressed event and appended no finding; citing an id that was
+        // never raised would make this record unresolvable.
+        if (raised.suppressed)
+            continue;
+        findingIds.push(raised.finding.finding_id);
+    }
+    const coverage = input.coverage.map((entry) => ({ ...entry }));
+    const digest = goalDigest(input.goal);
+    const stored = await appendEvent({
+        session_id: ctx.sessionId,
+        actor: ctx.actor ?? 'system',
+        event_type: GOAL_CHECK_EVENT,
+        task_id: taskId,
+        plan_version: ctx.planVersion,
+        causal_parent: ctx.causalParent,
+        payload: {
+            epic_id: epicId,
+            milestone_id: milestoneId,
+            plan_version: planVersion,
+            goal_digest: digest,
+            checked_by: checkedBy,
+            ...(input.checkedByProvider === undefined
+                ? {}
+                : { checked_by_provider: input.checkedByProvider }),
+            coverage,
+            clause_count: coverage.length,
+            uncovered_count: coverage.filter((entry) => entry.verdict === 'uncovered').length,
+            out_of_scope_count: coverage.filter((entry) => entry.verdict === 'out-of-scope').length,
+            finding_ids: findingIds,
+            finding_count: findingIds.length,
+        },
+    }, opts);
+    return {
+        epicId,
+        milestoneId,
+        planVersion,
+        goalDigest: digest,
+        checkedBy,
+        coverage,
+        findingIds,
+        eventId: stored.event_id,
+        ts: stored.record.ts,
+    };
+}

package/factory/orchestrator/dist/graph.js

@@ -0,0 +1,61 @@
+export function topoSort(nodes, edges) {
+    const nodeSet = new Set(nodes);
+    const dependents = new Map(); // dependsOn -> [tasks waiting on it]
+    const inDegree = new Map();
+    for (const node of nodeSet) {
+        inDegree.set(node, 0);
+        dependents.set(node, []);
+    }
+    for (const edge of edges) {
+        if (!nodeSet.has(edge.task) || !nodeSet.has(edge.dependsOn))
+            continue;
+        dependents.get(edge.dependsOn)?.push(edge.task);
+        inDegree.set(edge.task, (inDegree.get(edge.task) ?? 0) + 1);
+    }
+    const ready = [...nodeSet].filter((n) => inDegree.get(n) === 0).sort();
+    const order = [];
+    while (ready.length > 0) {
+        ready.sort();
+        const next = ready.shift();
+        order.push(next);
+        for (const dependent of dependents.get(next) ?? []) {
+            const remaining = (inDegree.get(dependent) ?? 0) - 1;
+            inDegree.set(dependent, remaining);
+            if (remaining === 0)
+                ready.push(dependent);
+        }
+    }
+    if (order.length === nodeSet.size) {
+        return { ok: true, order };
+    }
+    const cycle = [...nodeSet].filter((n) => !order.includes(n)).sort();
+    return { ok: false, cycle };
+}
+/**
+ * Longest-path depth per node (Phase 6b, Flow page's wave bands —
+ * docs/standards/stack.md: "layered by longest-path depth... no separate
+ * layout library"). A node with no dependencies is wave 0; every other
+ * node's wave is `1 + max(wave of its dependencies)` — so a node is never
+ * drawn in an earlier band than something it depends on, and independent
+ * branches that happen to be the same length land in the same band
+ * (visually "these can run in parallel right now"). Cyclic input is
+ * rejected via topoSort() first — wave computation assumes acyclic input.
+ */
+export function waveLayers(nodes, edges) {
+    const topo = topoSort(nodes, edges);
+    const waves = new Map();
+    if (!topo.ok)
+        return waves; // cyclic — caller's problem to surface, not this function's
+    const dependsOnByTask = new Map();
+    for (const e of edges) {
+        const list = dependsOnByTask.get(e.task) ?? [];
+        list.push(e.dependsOn);
+        dependsOnByTask.set(e.task, list);
+    }
+    for (const node of topo.order) {
+        const deps = dependsOnByTask.get(node) ?? [];
+        const wave = deps.length === 0 ? 0 : Math.max(...deps.map((d) => (waves.get(d) ?? 0) + 1));
+        waves.set(node, wave);
+    }
+    return waves;
+}