@juzser/blacksmith 0.2.0 → 0.4.0

package/factory/orchestrator/dist/epic.js

@@ -3,14 +3,15 @@ import { loadCrosscheckPolicy } from './crosscheck.js';
 import { foldTasks } from './db/projector.js';
 import { SmithError } from './errors.js';
 import { appendEvent, readEvents, readLineageEvents, } from './events.js';
-import { AMEND_PENDING_STATUS, AMENDED_STATUS, describeMalformedTaskId, foldFindingsDetailed, isNonEmptyString, OPEN_FINDING_STATUSES, transition, } from './findings.js';
+import { AMEND_PENDING_STATUS, AMENDED_STATUS, DISCRETIONARY_FINDING_STATUSES, describeMalformedTaskId, foldFindingsDetailed, isNonEmptyString, OPEN_FINDING_STATUSES, transition, } from './findings.js';
 import { goalCheckBlockers, latestGoalCheck, } from './goalCheck.js';
 import { latestIntegrationCheck } from './integration.js';
 import { mcpBlockers } from './mcp.js';
 import { bareTaskId, latestPlanVersion, livePlanTasks, loadPlan } from './plan.js';
 import { enabledExternalProviders, nativeProviderName, runQuorumCase, } from './quorum.js';
-import { latestSpecReview, specReviewBlockers } from './spec.js';
-import { auditWaveConcurrency } from './waveConcurrency.js';
+import { latestSpecReview, specReviewBlockers, taskSuccessors, } from './spec.js';
+import { TERMINAL_OK_TASK_STATUSES } from './taskStatus.js';
+import { auditWaveConcurrency, WAVE_VERDICTS, zeroedCounts, } from './waveConcurrency.js';
 import { RESERVED_TASK_ID } from './worktree.js';
 /**
  * Third quorum_triggers host (factory/policies/crosscheck.yml): "epic-level
@@ -44,17 +45,92 @@ import { RESERVED_TASK_ID } from './worktree.js';
  *     is whatever it would have been with no externals at all (`go`, since
  *     mechanical readiness already held).
  */
-const TERMINAL_OK_TASK_STATUSES = new Set(['completed', 'waived']);
 /** The terminal-OK status that is a decision rather than a completion (D-120). */
 const WAIVED_TASK_STATUS = 'waived';
 /**
- * Statuses that close a finding by DECIDING rather than by showing a fix
- * (D-120). Disjoint from OPEN_FINDING_STATUSES by construction — a finding is
- * open, earned-closed (`fix-verified`, `refuted`, `expired`), or one of these.
- * The gate does not block on them, which is precisely why the judge is told:
- * what nothing blocks on is what nobody re-reads.
+ * A task a re-plan (`plan amend`) replaced with a successor task cut under a
+ * later plan version. `TERMINAL_TASK_STATUSES` (taskStatus.ts) already counts
+ * this as over; it is deliberately NOT in `TERMINAL_OK_TASK_STATUSES`, because
+ * "over" is not the same as "well" — the work only actually landed if the
+ * successor did. `resolveSupersededRow` below is what asks that question.
  */
-const DISCRETIONARY_FINDING_STATUSES = new Set(['waived', AMENDED_STATUS]);
+const SUPERSEDED_TASK_STATUS = 'superseded';
+/**
+ * Follows a superseded task to whatever eventually carries its work, walking
+ * a possibly multi-hop chain (a successor can itself be superseded by a
+ * later amendment). Returns the first row in the chain that is not itself
+ * superseded, or `undefined` when the chain is missing a hop, names a task
+ * with no fold record, or cycles back on itself — every one of those reads
+ * as "no successor to vouch for this", the fail-closed answer.
+ *
+ * `successors` is folded off the event log (spec.ts's `taskSuccessors`), so
+ * its keys and values are whatever `plan-version-created` recorded — not
+ * necessarily bare (D-46/P9-29) — hence comparing through `bareTaskId` at
+ * every hop rather than assuming the map is pre-normalized.
+ */
+function resolveSupersededRow(epicId, taskId, tasks, successors) {
+    const bareSuccessors = new Map([...successors].map(([from, to]) => [bareTaskId(epicId, from), to]));
+    const visited = new Set([bareTaskId(epicId, taskId)]);
+    let currentId = bareTaskId(epicId, taskId);
+    for (;;) {
+        const nextId = bareSuccessors.get(currentId);
+        if (nextId === undefined)
+            return undefined;
+        const nextBare = bareTaskId(epicId, nextId);
+        if (visited.has(nextBare))
+            return undefined;
+        visited.add(nextBare);
+        const row = tasks.find((t) => bareTaskId(epicId, t.taskId) === nextBare);
+        if (row === undefined)
+            return undefined;
+        if (row.taskStatus !== SUPERSEDED_TASK_STATUS)
+            return row;
+        currentId = nextBare;
+    }
+}
+/**
+ * The `origin` taskEvents.ts's `emitFollowUpTask` stamps on a follow-up task:
+ * one minted for a finding no open task could own, rather than one a plan cut.
+ */
+const FOLLOW_UP_TASK_ORIGIN = 'escalation';
+/** The finding status that is the operator's decision not to fix (D-120). */
+const WAIVED_FINDING_STATUS = 'waived';
+/**
+ * Whether a follow-up task's whole reason to exist has been waived away. A
+ * follow-up is minted `todo` to own findings, and no event ever moves it to
+ * `waived` — the projector has no such write — so without this the operator
+ * waiving the only finding it owns (bs-audit-2's `followup-9a8f6ac7`) left the
+ * task holding the epic verdict forever, with nothing left to do and no verb
+ * that could say so.
+ *
+ * Deliberately narrow, the same reader-side shape as the superseded-successor
+ * rule above:
+ *   - only origin `escalation`: a planned task's `todo` is a claim about work
+ *     its spec still owes, which waiving a finding raised against it does not
+ *     discharge;
+ *   - at least one attributed finding: a follow-up that owns nothing is not
+ *     "all waived", it is unexplained, and absence must not vote yes (D-126);
+ *   - every attributed finding `waived`: one still open, or closed any other
+ *     way (a fix verified by a gate the task never ran), still blocks.
+ *
+ * Attribution is `finding.task_id`. A finding routed to a follow-up is raised
+ * under it (attribution.ts's `reattributeFinding` re-mints the id before the
+ * raise), so `finding-reattributed` needs no second reading here. Ids compare
+ * bare (D-46/P9-29).
+ *
+ * Returns the findings that discharge the follow-up, or null on every branch
+ * the rule refuses, so the quorum prompt can NAME them instead of re-deriving
+ * the rule a second way.
+ */
+function clearedFollowUpFindings(epicId, row, findings) {
+    if (row.origin !== FOLLOW_UP_TASK_ORIGIN)
+        return null;
+    const bare = bareTaskId(epicId, row.taskId);
+    const owned = findings.filter((f) => bareTaskId(epicId, f.task_id) === bare);
+    return owned.length > 0 && owned.every((f) => f.finding_status === WAIVED_FINDING_STATUS)
+        ? owned
+        : null;
+}
 const GATE_OUTCOME_EVENT = 'gate-outcome';
 const TASK_RESULT_EVENT = 'task-result-recorded';
 /**
@@ -82,13 +158,6 @@ export function withGateEvidence(tasks, events, epicId) {
         return { ...t, gate: { gateOutcome: gated.has(bare), resultRecorded: recorded.has(bare) } };
     });
 }
-const WAVE_VERDICTS = [
-    'parallel',
-    'partial',
-    'serialized',
-    'single',
-    'unobserved',
-];
 /**
  * Reduce one epic's waves to the fact a close records. Pure, and separate from
  * `summariseWaveConcurrency` on purpose: that one scores an operator's audit
@@ -96,7 +165,7 @@ const WAVE_VERDICTS = [
  * single epic with no verdict of its own to render.
  */
 export function summariseEpicConcurrency(waves) {
-    const verdicts = Object.fromEntries(WAVE_VERDICTS.map((v) => [v, 0]));
+    const verdicts = zeroedCounts(WAVE_VERDICTS);
     for (const wave of waves)
         verdicts[wave.verdict] += 1;
     return {
@@ -113,7 +182,7 @@ export function summariseEpicConcurrency(waves) {
 /** Nothing the log could be folded into a width, and why. */
 const UNREADABLE_CONCURRENCY = (problem) => ({
     waves: 0,
-    verdicts: Object.fromEntries(WAVE_VERDICTS.map((v) => [v, 0])),
+    verdicts: zeroedCounts(WAVE_VERDICTS),
     widest: { declared: 0, observed: 0 },
     unobserved: [],
     problem,
@@ -174,15 +243,16 @@ function integrationBlockers(epicId, integration) {
  * Pure readiness check, no I/O: given the epic's own task rows (foldTasks()
  * output, already filtered to this epic) and its findings (listFindings()
  * output), decide whether the epic is mechanically ready to open its
- * integration PR. "Terminal-OK" mirrors db/queries.ts's
- * MILESTONE_COMPLETE_TASK_STATUSES precedent (completed, waived) — a
- * superseded/failed/escalated/blocked/in-progress/etc. task is not one of
- * those, so it blocks. "Open" finding mirrors db/queries.ts's
- * OPEN_FINDING_STATUSES precedent (raised, confirmed, fix-pending,
- * fix-landed, amend-pending) — a finding only stops being open at
- * fix-verified, waived, or amended. `amend-pending` is the D-127 case: the
- * amendment is written but the tasks it names have not landed, so it is open
- * here until they do, and only then does closeEpic take it to `amended`.
+ * integration PR. "Terminal-OK" is taskStatus.ts's exported
+ * TERMINAL_OK_TASK_STATUSES (completed, waived) — a task at superseded,
+ * failed, escalated, blocked, in-progress or anything else is not one of
+ * those, so it blocks. "Open" finding is findings.ts's
+ * OPEN_FINDING_STATUSES, which reads the statuses LEGAL_TRANSITIONS still has
+ * a move out of rather than listing them — a finding stops being open when
+ * the table has nowhere left to take it, or at `waived`, which is a decision.
+ * `amend-pending` is the D-127 case: the amendment is written but the tasks it
+ * names have not landed, so it is open here until they do, and only then does
+ * closeEpic take it to `amended`.
  *
  * `integration` is REQUIRED, deliberately. An optional parameter defaulting
  * to "no check needed" would recreate the exact hole D-42/P9-26 closes: the
@@ -232,12 +302,43 @@ function integrationBlockers(epicId, integration) {
  * dropped so it can never be read as "it ran fine". It contributes nothing to
  * `blockers` — see {@link EpicConcurrency}.
  */
-export function summarizeEpic(epicId, tasks, findings, integration, mcp, specReview, goalCheck, plan = null, quarantined = [], concurrency = null) {
+export function summarizeEpic(epicId, tasks, findings, integration, mcp, specReview, goalCheck, plan = null, quarantined = [], concurrency = null, 
+/**
+ * Old task id -> the successor that superseded it (spec.ts's
+ * `taskSuccessors`, folded off every `plan-version-created` event this
+ * epic has). Defaults to empty: a caller that never threads it gets
+ * exactly today's behavior — every superseded task blocks, same as before
+ * this parameter existed.
+ */
+successors = new Map()) {
     const taskSummaries = tasks.map((t) => ({
         taskId: t.taskId,
         taskStatus: t.taskStatus,
     }));
-    const nonTerminal = taskSummaries.filter((t) => !TERMINAL_OK_TASK_STATUSES.has(t.taskStatus));
+    // A superseded task is terminal (taskStatus.ts's TERMINAL_TASK_STATUSES)
+    // but not terminal-OK by itself — it reads terminal-OK only when the
+    // successor that replaced it does, recursively (run.md's "completed/
+    // superseded/waived" is this rule, not a second one). A follow-up task whose
+    // every finding was waived reads terminal-OK too — clearedFollowUpFindings()
+    // — and is collected below so the prompt can explain the row it clears.
+    const clearedFollowUps = [];
+    const nonTerminal = taskSummaries.filter((t, i) => {
+        if (TERMINAL_OK_TASK_STATUSES.has(t.taskStatus))
+            return false;
+        if (t.taskStatus !== SUPERSEDED_TASK_STATUS) {
+            const cleared = clearedFollowUpFindings(epicId, tasks[i], findings);
+            if (cleared === null)
+                return true;
+            clearedFollowUps.push({
+                taskId: t.taskId,
+                taskStatus: t.taskStatus,
+                waivedFindingIds: cleared.map((f) => f.finding_id),
+            });
+            return false;
+        }
+        const successor = resolveSupersededRow(epicId, t.taskId, tasks, successors);
+        return successor === undefined || !TERMINAL_OK_TASK_STATUSES.has(successor.taskStatus);
+    });
     // D-138: only tasks claimed done are asked for evidence. One still in flight
     // has not been gated yet and already blocks for not being terminal-OK —
     // repeating it here would make an in-progress task read like a forged one.
@@ -318,13 +419,35 @@ export function summarizeEpic(epicId, tasks, findings, integration, mcp, specRev
             : wellFormedObligationIds.filter((id) => {
                 const bare = bareTaskId(epicId, id);
                 const row = tasks.find((t) => bareTaskId(epicId, t.taskId) === bare);
-                const landed = row !== undefined &&
-                    TERMINAL_OK_TASK_STATUSES.has(row.taskStatus) &&
+                // An obligation named a task a LATER, separate amendment went on
+                // to supersede: the stored amends_task_ids is never rewritten
+                // (repairObligation refuses to renegotiate a well-formed
+                // obligation), so the id is resolved through its successor here,
+                // at evaluation time, instead. Only the LANDED-AT version comes
+                // from the successor row; the evidence transition() eventually
+                // re-checks (outstandingObligations, findings.ts) bare-compares
+                // AmendmentDischarge.taskId against the obligation's own
+                // amends_task_ids, so the taskId offered as proof has to stay the
+                // originally-named id (`row.taskId`) or that revalidation would
+                // never find a match and would refuse the discharge outright —
+                // the id is resolved for landing-status purposes only, never for
+                // the identity the obligation is matched by. The original row
+                // stands in unchanged (byte-identical to before this existed)
+                // whenever it was never superseded, or its chain does not
+                // resolve.
+                const evidenceRow = row !== undefined && row.taskStatus === SUPERSEDED_TASK_STATUS
+                    ? (resolveSupersededRow(epicId, row.taskId, tasks, successors) ?? row)
+                    : row;
+                const landed = evidenceRow !== undefined &&
+                    TERMINAL_OK_TASK_STATUSES.has(evidenceRow.taskStatus) &&
                     version !== undefined &&
-                    row.planVersion !== null &&
-                    row.planVersion >= version;
-                if (landed && row.planVersion !== null)
-                    satisfiedBy.push({ taskId: row.taskId, planVersion: row.planVersion });
+                    evidenceRow.planVersion !== null &&
+                    evidenceRow.planVersion >= version;
+                if (landed && evidenceRow.planVersion !== null && row !== undefined)
+                    satisfiedBy.push({
+                        taskId: row.taskId,
+                        planVersion: evidenceRow.planVersion,
+                    });
                 return !landed;
             });
         if (malformedObligations.length === 0 && outstanding !== null && outstanding.length === 0) {
@@ -362,7 +485,17 @@ export function summarizeEpic(epicId, tasks, findings, integration, mcp, specRev
         ...(taskSummaries.length === 0
             ? [`Epic "${epicId}" has no tasks in the event log — nothing to integrate.`]
             : []),
-        ...nonTerminal.map((t) => `Task "${t.taskId}" is not terminal-OK (status: ${t.taskStatus}).`),
+        ...nonTerminal.map((t) => {
+            const row = tasks.find((r) => r.taskId === t.taskId);
+            if (row?.origin === FOLLOW_UP_TASK_ORIGIN && t.taskStatus !== SUPERSEDED_TASK_STATUS)
+                return `Task "${t.taskId}" is a follow-up (origin: escalation) and is not terminal-OK (status: ${t.taskStatus}). Complete it, or waive every finding attributed to it — it clears once it owns at least one finding and all of them are waived.`;
+            if (t.taskStatus !== SUPERSEDED_TASK_STATUS)
+                return `Task "${t.taskId}" is not terminal-OK (status: ${t.taskStatus}).`;
+            const successor = resolveSupersededRow(epicId, t.taskId, tasks, successors);
+            return successor === undefined
+                ? `Task "${t.taskId}" is superseded but has no successor recorded in the log — it cannot be counted terminal-OK.`
+                : `Task "${t.taskId}" is superseded by "${successor.taskId}", which is not terminal-OK (status: ${successor.taskStatus}).`;
+        }),
         ...undispatchedTasks.map((t) => `Task "${t.taskId}" is in plan v${plan?.version} but has no events in the log — nothing records it as dispatched, let alone done (plan status: ${t.taskStatus}).`),
         ...ungated.map((t) => t.gate.gateOutcome
             ? `Task "${t.taskId}" is recorded ${t.taskStatus} and has a gate-outcome, but no task-result-recorded for it exists in the log. \`gate run\` writes both for the task it grades, so this outcome was written by hand — it is a claim, not a gate.`
@@ -392,6 +525,7 @@ export function summarizeEpic(epicId, tasks, findings, integration, mcp, specRev
         undispatchedTasks,
         ungatedTasks,
         waivedTasks: taskSummaries.filter((t) => t.taskStatus === WAIVED_TASK_STATUS),
+        clearedFollowUps,
         openFindings,
         discretionaryFindings,
         satisfiedAmendments,
@@ -469,8 +603,21 @@ function mcpVerdict(mcp) {
  * and the exit code are the refutable part; the output is not.
  */
 export function epicVerdictJudgeRequest(summary, budget) {
+    // Keyed by taskId: a row in here is one clearedFollowUpFindings() cleared,
+    // so the roster line below can say so instead of printing the raw `todo`
+    // beside `Tasks not yet terminal-OK: 0` with nothing to explain the gap —
+    // the exact contradiction both external judges refuted in bs-audit-2.
+    const clearedFollowUpsByTaskId = new Map(summary.clearedFollowUps.map((c) => [c.taskId, c]));
     const taskLines = summary.tasks.length > 0
-        ? summary.tasks.map((t) => `  ${t.taskId}: ${t.taskStatus}`).join('\n')
+        ? summary.tasks
+            .map((t) => {
+            const cleared = clearedFollowUpsByTaskId.get(t.taskId);
+            return cleared === undefined
+                ? `  ${t.taskId}: ${t.taskStatus}`
+                : `  ${t.taskId}: ${t.taskStatus} — follow-up (origin: escalation) cleared by rule: ` +
+                    `every attributed finding waived (${cleared.waivedFindingIds.join(', ')}); counted terminal-OK`;
+        })
+            .join('\n')
         : '  (no tasks)';
     // The plan's side of the roster, stated separately: these ids have no events
     // at all, so their status is what the plan claims, not what happened (D-126).
@@ -592,6 +739,8 @@ export function epicVerdictJudgeRequest(summary, budget) {
         'Discretionary closures — decided by a person, not shown by the machine:',
         `Tasks waived rather than completed: ${summary.waivedTasks.length}`,
         ...listOr(summary.waivedTasks.map((t) => `  ${t.taskId}`)),
+        `Follow-ups cleared by waiving every finding they own: ${summary.clearedFollowUps.length}`,
+        ...listOr(summary.clearedFollowUps.map((c) => `  ${c.taskId} — waived findings: ${c.waivedFindingIds.join(', ')}`)),
         `Findings closed by waiver or amendment: ${summary.discretionaryFindings.length}`,
         ...listOr(summary.discretionaryFindings.map(findingLine)),
         `Amendments this close will discharge: ${summary.satisfiedAmendments.length}`,
@@ -731,7 +880,11 @@ export async function runEpicVerdict(input, ctx, opts = {}) {
     // Off the same lineage `events` every other fact here came from — the
     // wave record is in that log already, so measuring width costs this call
     // no second read and no second command anyone has to remember to type.
-    readEpicConcurrency(events, input.epicId));
+    readEpicConcurrency(events, input.epicId), 
+    // Same lineage read again, no second I/O: which superseded task ids this
+    // epic's amendments paired with a replacement, so a chain of them can
+    // resolve to whatever is actually carrying the work now.
+    taskSuccessors(events, input.epicId));
     // Step 1 — mechanical_oracles_first, literally: a deterministic blocker is
     // final. Zero judge calls, zero events (read-only projection).
     if (!summary.mechanicallyReady) {

package/factory/orchestrator/dist/epicWidth.js

@@ -1,4 +1,4 @@
-import { UNOBSERVED_HINT } from './waveConcurrency.js';
+import { UNOBSERVED_HINT, WAVE_VERDICTS, zeroedCounts, } from './waveConcurrency.js';
 /**
  * Does this factory build in parallel, or has every epic it closed been narrow?
  *
@@ -28,20 +28,25 @@ import { UNOBSERVED_HINT } from './waveConcurrency.js';
  *    confidently as a factory of three hundred.
  */
 const CLOSED_EVENT_TYPE = 'epic-closed';
-/** The verdicts an epic can be graded on, widest first — see {@link gradeOf}. */
-const BEST_FIRST = [
-    'parallel',
-    'partial',
-    'serialized',
-    'single',
-    'unobserved',
-];
-const ALL_VERDICTS = [
-    ...BEST_FIRST,
-    'unwaved',
-    'unmeasured',
-    'unreadable',
-];
+/**
+ * The three an epic can be graded that no single wave can carry, because they
+ * are facts about the close rather than about a wave. Kept apart from the five
+ * so the union below is the two rosters joined, and the five stay owned by the
+ * module that mints them.
+ */
+const EPIC_ONLY_VERDICTS = ['unwaved', 'unmeasured', 'unreadable'];
+/**
+ * Every verdict an epic can be graded, widest first, and the roster the
+ * histogram's buckets are made of.
+ *
+ * The five come from the module that mints them rather than being restated
+ * here. That is the whole coupling this file turns on: `epic.ts` WRITES the
+ * width into the close and this file VALIDATES it on read — `countsFrom`
+ * rejects a record missing any of the five outright — so two hand-written
+ * copies of one list were two halves of a contract with nothing holding them
+ * to each other.
+ */
+export const ALL_VERDICTS = [...WAVE_VERDICTS, ...EPIC_ONLY_VERDICTS];
 /**
  * Said when no close carried a width anybody could read.
  *
@@ -58,7 +63,7 @@ function blank(verdict, problem) {
     return {
         verdict,
         waves: 0,
-        byVerdict: Object.fromEntries(BEST_FIRST.map((v) => [v, 0])),
+        byVerdict: zeroedCounts(WAVE_VERDICTS),
         widest: { declared: 0, observed: 0 },
         unobserved: [],
         problem,
@@ -68,8 +73,8 @@ function countsFrom(raw) {
     if (typeof raw !== 'object' || raw === null)
         return null;
     const source = raw;
-    const counts = {};
-    for (const verdict of BEST_FIRST) {
+    const counts = zeroedCounts(WAVE_VERDICTS);
+    for (const verdict of WAVE_VERDICTS) {
         const n = source[verdict];
         // A missing key is not read as zero. The close projects all five even at
         // zero (D-126), so an absent one means this is not a width record at all,
@@ -102,7 +107,7 @@ function widthFrom(raw) {
 function gradeOf(counts, waves) {
     if (waves === 0)
         return 'unwaved';
-    for (const verdict of BEST_FIRST)
+    for (const verdict of WAVE_VERDICTS)
         if (counts[verdict] > 0)
             return verdict;
     // Unreachable: every wave carries one of the five. Reported rather than
@@ -208,7 +213,7 @@ export function summariseEpicWidth(events) {
     const epics = readClosedEpicWidths(events).sort((a, b) => a.closedAt === b.closedAt
         ? a.epicId.localeCompare(b.epicId)
         : b.closedAt.localeCompare(a.closedAt));
-    const verdicts = Object.fromEntries(ALL_VERDICTS.map((v) => [v, 0]));
+    const verdicts = zeroedCounts(ALL_VERDICTS);
     for (const epic of epics)
         verdicts[epic.verdict] += 1;
     const serialized = epics.filter((e) => e.byVerdict.serialized > 0).map((e) => e.epicId);