@juzser/blacksmith 0.3.0 → 0.5.0

package/factory/orchestrator/dist/epicBudget.js

@@ -0,0 +1,93 @@
+// budgets.yml sized for one epic's effort tier.
+//
+// budgets.ts cannot read a plan or effort.yml's resolution itself — plan.ts
+// imports it, and effort.ts imports plan.ts — so the step from "a plan" or
+// "an epic id seen in the event log" to "the policy for that epic's tier"
+// lives here, one level up. Every budget reader that knows its plan goes
+// through `budgetTierForPlan`: the tier a budget is sized for is the tier the
+// epic RUNS at, after effort.yml's security floor, not the plan's raw ask.
+import { loadBudgetPolicy, resolveBudgetTier } from './budgets.js';
+import { loadCrosscheckPolicy } from './crosscheck.js';
+import { loadEffortPolicy, resolveEffort } from './effort.js';
+import { BUDGETS_POLICY_PATH } from './paths.js';
+import { isEffortTier, latestPlanVersion, loadPlan, } from './plan.js';
+/**
+ * An epic id is a directory name under the specs dir. One read out of the
+ * event log is data, not a path: anything that is not a plain name is treated
+ * as "no plan found" rather than joined onto a filesystem path.
+ */
+const PLAIN_EPIC_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/**
+ * The effort tier `plan` is budgeted at: effort.ts `resolveEffort(...).effective`,
+ * so a `small` plan whose live tasks trip a crosscheck.yml security trigger is
+ * budgeted at effort.yml's `security_floor`, exactly the tier it runs at.
+ *
+ * A budget reader must not fail a run over a policy it only consults: when
+ * effort.yml or crosscheck.yml cannot be read, or the plan's tasks cannot be
+ * walked, the tier falls back to the plan's own `effort`, else effort.yml's
+ * `default_tier` (which budgets.ts refuses to guess when that is broken too).
+ */
+export function budgetTierForPlan(plan, opts = {}) {
+    let effortPolicy;
+    try {
+        effortPolicy = loadEffortPolicy(opts.effortPolicyFile);
+    }
+    catch {
+        return resolveBudgetTier(plan?.effort, opts.effortPolicyFile);
+    }
+    if (plan === null || plan === undefined)
+        return effortPolicy.defaultTier;
+    try {
+        const securityPolicy = opts.securityPolicy ?? loadCrosscheckPolicy(opts.crosscheckPolicyFile).planQuorum;
+        return resolveEffort(effortPolicy, securityPolicy, { plan }).effective;
+    }
+    catch {
+        return isEffortTier(plan.effort) ? plan.effort : effortPolicy.defaultTier;
+    }
+}
+/** budgets.yml sized for `plan`'s effective tier (see `budgetTierForPlan`). */
+export function budgetPolicyForPlan(plan, opts = {}) {
+    return loadBudgetPolicy(opts.policyFile, opts.env ?? process.env, budgetTierForPlan(plan, opts));
+}
+/**
+ * The epic's latest plan, or undefined when there is no plan to read — a log
+ * from another project, an epic planned outside this specs dir, an unreadable
+ * file. undefined sizes the budget at effort.yml's `default_tier`, which is
+ * what every reader did before tiers existed.
+ */
+export function latestPlan(epicId, planOpts = {}) {
+    if (!PLAIN_EPIC_ID.test(epicId) || epicId.includes('..'))
+        return undefined;
+    try {
+        const version = latestPlanVersion(epicId, planOpts);
+        return version === null ? undefined : loadPlan(epicId, version, planOpts);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * A lookup from epic id to that epic's budget policy, each tier loaded once.
+ * Env overrides apply per tier (`<NAME>_<TIER>` before `<NAME>`), so two
+ * epics of different tiers can be judged against different caps in one
+ * report.
+ */
+export function epicBudgetPolicies(opts = {}) {
+    const policyFile = opts.policyFile ?? BUDGETS_POLICY_PATH;
+    const env = opts.env ?? process.env;
+    const byTier = new Map();
+    const byEpic = new Map();
+    return (epicId) => {
+        const cached = byEpic.get(epicId);
+        if (cached !== undefined)
+            return cached;
+        const tier = budgetTierForPlan(latestPlan(epicId, opts.planOpts), opts);
+        let policy = byTier.get(tier);
+        if (policy === undefined) {
+            policy = loadBudgetPolicy(policyFile, env, tier);
+            byTier.set(tier, policy);
+        }
+        byEpic.set(epicId, policy);
+        return policy;
+    };
+}

package/factory/orchestrator/dist/epicWidth.js

@@ -1,4 +1,4 @@
-import { UNOBSERVED_HINT, WAVE_VERDICTS, zeroedCounts, } from './waveConcurrency.js';
+import { UNLINKED_HINT, UNOBSERVED_HINT, WAVE_VERDICTS, zeroedCounts, } from './waveConcurrency.js';
 /**
  * Does this factory build in parallel, or has every epic it closed been narrow?
  *
@@ -55,9 +55,9 @@ export const ALL_VERDICTS = [...WAVE_VERDICTS, ...EPIC_ONLY_VERDICTS];
  * opposite states of knowledge, and a factory that has never measured itself
  * must not be able to read as a healthy one.
  */
-export const UNMEASURED_HINT = 'No close read here carried a width. Either these epics were closed before `smith epic close` ' +
-    'recorded one, or the closes were written by hand — close a current epic with `smith epic ' +
-    'close`, or read a live log back with `smith wave audit --session <id>`.';
+export const UNMEASURED_HINT = 'No close read here carried a width. Either these epics were closed before `bs epic close` ' +
+    'recorded one, or the closes were written by hand — close a current epic with `bs epic ' +
+    'close`, or read a live log back with `bs wave audit --session <id>`.';
 /** Nothing was recorded, or nothing readable was. */
 function blank(verdict, problem) {
     return {
@@ -66,6 +66,7 @@ function blank(verdict, problem) {
         byVerdict: zeroedCounts(WAVE_VERDICTS),
         widest: { declared: 0, observed: 0 },
         unobserved: [],
+        unlinked: [],
         problem,
     };
 }
@@ -148,6 +149,9 @@ function widthOf(payload) {
         unobserved: Array.isArray(record.unobserved)
             ? record.unobserved.filter((id) => typeof id === 'string')
             : [],
+        unlinked: Array.isArray(record.unlinked)
+            ? record.unlinked.filter((id) => typeof id === 'string')
+            : [],
         problem,
     };
 }
@@ -220,6 +224,9 @@ export function summariseEpicWidth(events) {
     const unobserved = epics
         .filter((e) => e.byVerdict.unobserved > 0 || e.unobserved.length > 0)
         .map((e) => e.epicId);
+    const unlinked = epics
+        .filter((e) => e.byVerdict.unlinked > 0 || e.unlinked.length > 0)
+        .map((e) => e.epicId);
     const unmeasured = epics
         .filter((e) => e.verdict === 'unmeasured' || e.verdict === 'unreadable')
         .map((e) => e.epicId);
@@ -236,8 +243,18 @@ export function summariseEpicWidth(events) {
         },
         serialized,
         unobserved,
+        unlinked,
         unmeasured,
-        hint: unobserved.length > 0 ? UNOBSERVED_HINT : judged ? '' : UNMEASURED_HINT,
+        // `unlinked` names real work, so it earns a hint pointing the operator at
+        // it but never the exit code `unobserved` carries -- that code is reserved
+        // for "nothing was judged", and here something plainly was.
+        hint: unobserved.length > 0
+            ? UNOBSERVED_HINT
+            : unlinked.length > 0
+                ? UNLINKED_HINT
+                : judged
+                    ? ''
+                    : UNMEASURED_HINT,
         exitCode: serialized.length > 0 ? 1 : unobserved.length > 0 || !judged ? 2 : 0,
     };
 }

package/factory/orchestrator/dist/errorIssues.js

@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto';
 import { isLaterEvent } from './eventOrder.js';
+import { normalizeProjectName } from './projectName.js';
 /** A `Record` over every `GateBlockedReason`, not a switch with a default: a reason missing from `GateBlockedReason` fails to compile here. */
 const GATE_BLOCKED_ERROR_CLASSES = {
     'schema-invalid': 'gate.blocked.schema-invalid',
@@ -7,6 +8,10 @@ const GATE_BLOCKED_ERROR_CLASSES = {
     'not-committed': 'gate.blocked.not-committed',
     'deps-missing': 'gate.blocked.deps-missing',
     'judges-outstanding': 'gate.blocked.judges-outstanding',
+    'uiux-spec-missing': 'gate.blocked.uiux-spec-missing',
+    'screenshots-missing': 'gate.blocked.screenshots-missing',
+    'screenshots-stale': 'gate.blocked.screenshots-stale',
+    'uiux-visual-missing': 'gate.blocked.uiux-visual-missing',
     'grader-invalid': 'gate.blocked.grader-invalid',
     'grader-fail': 'gate.blocked.grader-fail',
     'tests-failed': 'gate.blocked.tests-failed',
@@ -20,6 +25,10 @@ const BLOCKING_SEVERITY = 'S2-major';
 const GATE_OUTCOME_EVENT_TYPE = 'gate-outcome';
 const ERROR_LOGGED_EVENT_TYPE = 'error-logged';
 const TASK_ADDED_EVENT_TYPE = 'task-added';
+/** `agents-registry.ts`'s `DISPATCH_EVENT_TYPE`, hand-restated rather than
+ * imported -- this module's only imports are `node:crypto` and two local,
+ * type-only siblings, on purpose (see the file banner). */
+const DISPATCH_DECISION_EVENT_TYPE = 'dispatch_decision';
 /**
  * Source 2: `task_status: failed` is set in exactly one place in the whole
  * projector, `db/projector.ts`'s `case 'task-added'` arm copying
@@ -29,8 +38,6 @@ const TASK_ADDED_EVENT_TYPE = 'task-added';
  * carries no failure discriminator beyond that.
  */
 const TASK_FAILED_ERROR_CLASS = 'task.failed';
-/** Default project for an event stamped with none (events.ts's documented convention; the writer never sets it, only read helpers default it). */
-const DEFAULT_PROJECT = 'black-smith';
 function asString(value) {
     return typeof value === 'string' && value.length > 0 ? value : undefined;
 }
@@ -118,20 +125,159 @@ const CANDIDATE_READERS = Object.freeze({
  * would be reported outside the window the operator asked about.
  */
 export const ISSUE_CANDIDATE_EVENT_TYPES = new Set(Object.keys(CANDIDATE_READERS));
+/** The row's task ref, off the envelope first and the payload second -- the same two places every `CandidateReader` above already looks. */
+function candidateTaskRef(record) {
+    const payload = (record.payload ?? {});
+    return asString(record.task_id) ?? asString(payload.task_ref);
+}
+/**
+ * Event types allowed to stamp a session's project for
+ * `sessionProjectStamps` below: the issue candidates themselves, plus
+ * `task-added` and `dispatch_decision` rows recording where a task was
+ * planned or dispatched. Deliberately excludes `issue-reported` and every
+ * other reporter-authored row -- those carry this module's own *guess* at a
+ * row's project (see `appendIssueReported` in `issueReporter.ts`), not an
+ * independent origin stamp, so folding them back in here would let one run's
+ * guess leak into the next run's resolution of an unrelated, unstamped row
+ * in the same session.
+ */
+const ORIGIN_STAMP_EVENT_TYPES = new Set([
+    ...ISSUE_CANDIDATE_EVENT_TYPES,
+    DISPATCH_DECISION_EVENT_TYPE,
+]);
+/**
+ * The session's project, from its origin-stamped rows only -- and only when
+ * every one of them agrees. Real sessions mix dozens of stamped rows with
+ * unstamped ones (evidence: a foreign project's session stamps some events
+ * and not others); a unanimous stamped sibling in the same session is strong
+ * evidence for an unstamped one. A session whose origin stamps disagree
+ * tells us nothing safe to guess, so it answers unresolved rather than
+ * picking whichever stamp happened to come first.
+ */
+function sessionProjectStamps(events) {
+    const bySession = new Map();
+    for (const { record } of events) {
+        if (!ORIGIN_STAMP_EVENT_TYPES.has(record.event_type))
+            continue;
+        const stamped = asString(record.project);
+        if (stamped === undefined)
+            continue;
+        const project = normalizeProjectName(stamped);
+        const seen = bySession.get(record.session_id);
+        if (seen)
+            seen.add(project);
+        else
+            bySession.set(record.session_id, new Set([project]));
+    }
+    const stamps = new Map();
+    for (const [sessionId, projects] of bySession) {
+        if (projects.size !== 1)
+            continue;
+        const [project] = projects;
+        if (project !== undefined)
+            stamps.set(sessionId, project);
+    }
+    return stamps;
+}
+function taskAddedKey(sessionId, taskId) {
+    return `${sessionId}\u0000${taskId}`;
+}
+/** `task-added`'s own `payload.epic_id`, keyed by session and task id, so a bare ref (no epic segment) can still be widened to `<epic>/<ref>` before asking the resolver. */
+function taskAddedEpicIds(events) {
+    const out = new Map();
+    for (const { record } of events) {
+        if (record.event_type !== TASK_ADDED_EVENT_TYPE)
+            continue;
+        const taskId = asString(record.task_id);
+        const epicId = asString(record.payload?.epic_id);
+        if (taskId !== undefined && epicId !== undefined) {
+            out.set(taskAddedKey(record.session_id, taskId), epicId);
+        }
+    }
+    return out;
+}
+/**
+ * Widens a per-epic `ResolveProjectForTaskRef` into a `RowProjectResolver`
+ * with three session-scoped fallbacks a single task ref cannot answer alone,
+ * tried strictly in this order (S2-c):
+ *
+ * 1. `resolveProject`, the strict/direct resolver -- a bare ref (no epic
+ *    segment) tried again as `<epic>/<ref>` using the same session's own
+ *    `task-added` row when the bare ref alone cannot answer.
+ * 2. The session stamp: the ONE project every origin-stamped row in the same
+ *    session agrees on (`sessionProjectStamps`), when unanimous.
+ * 3. `selfFallback`, tried last and only when neither of the above could
+ *    answer -- same widening as step 1.
+ *
+ * Self-fallback sits last on purpose: it is "no plan says otherwise, and a
+ * plan exists locally for this epic, so guess this factory's own name" --
+ * the weakest of the three signals. A session's OWN unanimous stamp naming a
+ * DIFFERENT project is stronger evidence than that guess, and must not be
+ * overridden by it just because the same session also has an unrelated,
+ * unstamped row whose epic happens to have a local, unlabeled plan. Before
+ * this order existed, the self-fallback was folded into `resolveProject`
+ * itself (step 1) and so always outran the session stamp.
+ *
+ * Exported so `issueReporter.ts`'s `priorOpenReports` can apply the identical
+ * fallback to the same event snapshot.
+ */
+export function withSessionFallback(events, resolveProject, selfFallback = () => null) {
+    const stamps = sessionProjectStamps(events);
+    const epicIds = taskAddedEpicIds(events);
+    const tryResolve = (resolve, taskRef, sessionId) => {
+        if (taskRef === undefined)
+            return null;
+        const direct = resolve(taskRef);
+        if (direct !== null)
+            return direct;
+        if (sessionId === undefined)
+            return null;
+        const epicId = epicIds.get(taskAddedKey(sessionId, taskRef));
+        if (epicId === undefined)
+            return null;
+        return resolve(`${epicId}/${taskRef}`);
+    };
+    return (taskRef, sessionId) => {
+        const direct = tryResolve(resolveProject, taskRef, sessionId);
+        if (direct !== null)
+            return direct;
+        if (sessionId !== undefined) {
+            const stamp = stamps.get(sessionId);
+            if (stamp !== undefined)
+                return stamp;
+        }
+        return tryResolve(selfFallback, taskRef, sessionId);
+    };
+}
 /** One event to a `Candidate`, or `'ignore'` when no source claims its event type at all. */
-function toCandidate(event) {
+function toCandidate(event, resolveRow) {
     const { record } = event;
     const read = CANDIDATE_READERS[record.event_type];
     if (!read)
         return 'ignore';
+    const stamped = asString(record.project);
+    const taskRef = candidateTaskRef(record);
+    const sessionId = asString(record.session_id);
+    const project = stamped === undefined ? resolveRow(taskRef, sessionId) : normalizeProjectName(stamped);
     return read(event, {
         payload: record.payload ?? {},
-        project: asString(record.project) ?? DEFAULT_PROJECT,
-        sessionId: asString(record.session_id),
+        project,
+        sessionId,
         planVersion: asNumber(record.plan_version) ?? null,
         ts: asString(record.ts),
     });
 }
+/**
+ * A row whose project cannot be resolved at all still needs a stable
+ * fingerprint-grouping key -- otherwise two unrelated foreign projects'
+ * rows sharing `(source, error_class, task_ref)` would incorrectly group
+ * together and leak one row's session/epic/severity metadata onto the
+ * other's report, inside this factory's own private log (both rows are
+ * always skipped before anything is filed publicly, but the log itself
+ * should stay correct). `task_ref` alone already disambiguates in practice
+ * (refs are namespaced by epic id), so a single fixed sentinel is enough.
+ */
+const UNRESOLVED_PROJECT_FINGERPRINT_KEY = '\u0000unresolved-project\u0000';
 /**
  * The first 16 hex characters of a SHA-256 over the NUL-joined tuple
  * `project`, `source`, `error_class`, `task_ref`. Deliberately excludes
@@ -140,27 +286,52 @@ function toCandidate(event) {
  * and including any of them would open one issue per round instead of one.
  */
 function computeFingerprint(project, source, errorClass, taskRef) {
-    const material = [project, source, errorClass, taskRef].join('\0');
+    const material = [
+        project ?? UNRESOLVED_PROJECT_FINGERPRINT_KEY,
+        source,
+        errorClass,
+        taskRef,
+    ].join('\0');
     return createHash('sha256').update(material).digest('hex').slice(0, 16);
 }
 /**
  * Fold a stored event sequence into reportable errors. Pure: two calls with
  * identical input return byte-identical output. `now` is threaded in rather
  * than read off the clock; nothing in this contract branches on it yet.
+ *
+ * `resolveProject` and `selfFallback` both default to "no answer" so the
+ * ~50 existing call sites across this module's own tests and
+ * `issueReporter.ts`'s need no change. An unstamped row still unresolved
+ * after `withSessionFallback`'s three fallbacks reports `project: null`
+ * rather than this factory's own name -- `isProjectEnabled` is never asked
+ * about a row it cannot identify, and the decision to skip filing it
+ * belongs to `issueReporter.ts`, the one caller that goes on to call `gh`.
+ *
+ * `scopeEvents` defaults to `events` itself -- the session-stamp/`task-added`
+ * maps `withSessionFallback` builds read the same rows this fold iterates,
+ * same as before this parameter existed. A caller that narrows `events` to a
+ * candidate WINDOW (`cli.ts`'s `--epic`/`--since`) passes the full, unscoped
+ * lineage here instead (S3), so a session-mate's stamp sitting outside that
+ * window still counts as evidence for a row inside it -- scoping which rows
+ * get REPORTED must not also scope which rows get CONSULTED, or the same
+ * unstamped row resolves to a different project (and hashes a different
+ * fingerprint, S1-b) depending on whether the caller happened to pass
+ * `--epic`.
  */
-export function foldErrorEvents(events, now, isProjectEnabled) {
+export function foldErrorEvents(events, now, isProjectEnabled, resolveProject = () => null, selfFallback = () => null, scopeEvents = events) {
     void now;
+    const resolveRow = withSessionFallback(scopeEvents, resolveProject, selfFallback);
     const candidates = [];
     let skipped = 0;
     for (const event of events) {
-        const outcome = toCandidate(event);
+        const outcome = toCandidate(event, resolveRow);
         if (outcome === 'ignore')
             continue;
         if (outcome === null) {
             skipped += 1;
             continue;
         }
-        if (!isProjectEnabled(outcome.project))
+        if (outcome.project !== null && !isProjectEnabled(outcome.project))
             continue;
         candidates.push(outcome);
     }
@@ -204,7 +375,7 @@ function fingerprintLine(fingerprint) {
 }
 /** The local, read-only command an operator runs to see the detail this body/comment deliberately omit. */
 function smithEventCommand(sessionId) {
-    return `smith event tail ${sessionId} --lineage`;
+    return `bs event tail ${sessionId} --lineage`;
 }
 /** Builds a body-renderer input record from a folded report -- the record's key set is the allowlist; nothing else can reach `renderBody`. */
 export function toIssueBodyFields(report) {
@@ -245,7 +416,7 @@ export function renderBody(fields) {
         `Session: ${fields.session_id}`,
         `Epic: ${fields.epic_id ?? '(none)'}`,
         `Plan version: ${fields.plan_version ?? '(unknown)'}`,
-        `Project: ${fields.project}`,
+        `Project: ${fields.project ?? '(unknown)'}`,
         `Source: ${fields.source}`,
         fingerprintLine(fields.fingerprint),
         '',

package/factory/orchestrator/dist/escalation.js

@@ -3,8 +3,8 @@ import { bareTaskId, epicOfTaskId, isQualifiedTaskId, taskIdsMatch } from './tas
 /**
  * Roles whose dispatch constitutes a new round on the task.
  *
- * The split follows budgets.yml: `task.judges` names spec-reviewer, reviewer,
- * verifier and grader, and `context_window.narrowing_roles` adds
+ * The split follows budgets.yml: its judges (spec-reviewer, reviewer, verifier,
+ * grader) read a diff, and `context_window.narrowing_roles` adds
  * security-reviewer and merger — those roles read a diff, they do not produce
  * the one the gate scores. planner/researcher/scribe produce no task diff
  * either. What is left is what a "round" means: someone built again.