@juzser/blacksmith 0.4.0 → 0.5.0

package/factory/orchestrator/dist/plan.js

@@ -1,7 +1,9 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
 import { unreadTaskBudgetFields } from './budgets.js';
 import { claimCoversPath } from './claims.js';
+import { EFFORT_TIERS, isEffortTier } from './effortTiers.js';
 import { SmithError } from './errors.js';
 import { topoSort } from './graph.js';
 import { SPECS_ACTIVE_DIR } from './paths.js';
@@ -10,18 +12,11 @@ import { epicOfTaskId } from './taskId.js';
 import { loadTaxonomy, TaxonomyError, validateRequiredDimensions, } from './taxonomy.js';
 export class PlanError extends SmithError {
 }
-/**
- * How much judgment an epic buys, cheapest first — factory/policies/effort.yml
- * declares what each tier means; this is only the closed list of names, kept
- * here beside the `PlanFile.effort` field it types. effort.ts is the semantic
- * owner and re-exports these; it cannot own the list itself, because plan.ts
- * would then have to import it to validate a plan and effort.ts already
- * (transitively) imports plan.ts.
- */
-export const EFFORT_TIERS = ['small', 'medium', 'huge'];
-export function isEffortTier(value) {
-    return typeof value === 'string' && EFFORT_TIERS.includes(value);
-}
+// The closed list of effort tier names, re-exported beside the
+// `PlanFile.effort` field it types. It lives in the leaf module
+// effortTiers.ts because budgets.ts sizes its caps by it too, and plan.ts
+// already imports budgets.ts.
+export { EFFORT_TIERS, isEffortTier };
 /**
  * Pseudo task-id ref for a PLAN-level (not task-level) event: planQuorum.ts's
  * runPlanQuorum() stamps it onto the dispatch_decision/judge-verdict/
@@ -104,6 +99,24 @@ function planFilePath(epicId, version, opts) {
     const dir = opts.specsDir ?? SPECS_ACTIVE_DIR;
     return path.join(dir, epicId, `plan-v${version}.json`);
 }
+/**
+ * The specs dir implied by a plan file's own location on disk -- the inverse
+ * of `planFilePath`: `<specsDir>/<epicId>/plan-vN.json` names `<specsDir>` as
+ * its grandparent, when the plan sits in that shape at all. `null` when it
+ * does not (a flat fixture, or a directory that merely happens to share the
+ * epic's version number), because a plan filed anywhere else names no specs
+ * dir a caller should guess at.
+ *
+ * `cli.ts`'s `plan amend` handler is the only caller (#219): unlike every
+ * other reader of `--specs-dir`, amend WRITES the version it derives a path
+ * for, so falling back to `SPECS_ACTIVE_DIR` when the plan being amended
+ * already lives somewhere else plants the new version in the wrong tree
+ * entirely -- beside no other version of the plan it just amended.
+ */
+export function impliedSpecsDir(planPath, epicId) {
+    const dir = path.dirname(path.resolve(planPath));
+    return path.basename(dir) === epicId ? path.dirname(dir) : null;
+}
 const PLAN_FILE_PATTERN = /^plan-v(\d+)\.json$/;
 /**
  * The highest plan version written for an epic, or null when the epic has no
@@ -289,6 +302,105 @@ function describeAllowed(err) {
  * of what an edge must carry, which could then drift from taxonomy.yml's.
  */
 const GLOB_CHARS = /[*?[{]/;
+/** Extensions that make a claimed path a UI-visible surface (U2 D3). */
+const UI_EXTENSION_RE = /\.(tsx|jsx|vue|svelte|css|scss|sass|less|html)$/i;
+/**
+ * Whether a task spec is flagged as changing what a user sees. An absent
+ * `ui_affecting` means false at the gate (U2 D3) — work already running must
+ * not be blocked by a flag it predates.
+ */
+export function isUiAffecting(spec) {
+    return spec.ui_affecting === true;
+}
+/**
+ * `plan.ui-flag-missing`: a task that claims a UI-extension path must say,
+ * one way or the other, whether it is UI-affecting. An absent flag reads as
+ * false everywhere else in the factory (U2 D3), but silently reading false
+ * here would let a visibly UI-shaped task skip the uiux judge turn by
+ * omission rather than by a reviewed `ui_affecting: false`. Only the
+ * absence of the key is an error; an explicit `false` passes.
+ */
+function uiFlagMissing(t) {
+    if (t.ui_affecting !== undefined)
+        return [];
+    const claims = Array.isArray(t.claims)
+        ? t.claims.filter((c) => typeof c === 'string')
+        : [];
+    const firstMatch = claims.find((c) => UI_EXTENSION_RE.test(c));
+    if (firstMatch === undefined)
+        return [];
+    return [
+        {
+            path: '/ui_affecting',
+            message: `Task "${t.task_id}" claims UI-extension path "${firstMatch}" but has no ui_affecting flag (plan.ui-flag-missing). Set ui_affecting: true or false explicitly.`,
+        },
+    ];
+}
+/**
+ * Order-insensitive structural equality for the plain-JSON-shaped values a
+ * task record is made of (strings, numbers, booleans, null, arrays, plain
+ * objects). Arrays compare positionally — `claims` order is meaningful — and
+ * objects compare by key set and value, regardless of key order, since a
+ * record rebuilt via `{ ...t, ... }` and one authored by hand may list the
+ * same fields in different orders without differing in content.
+ */
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((v, i) => deepEqual(v, b[i]));
+    }
+    if (isPlainObject(a) || isPlainObject(b)) {
+        if (!isPlainObject(a) || !isPlainObject(b))
+            return false;
+        const aKeys = Object.keys(a);
+        const bKeys = Object.keys(b);
+        if (aKeys.length !== bKeys.length)
+            return false;
+        return aKeys.every((k) => Object.hasOwn(b, k) && deepEqual(a[k], b[k]));
+    }
+    return false;
+}
+/**
+ * Whether `t` is exempt from `plan.ui-flag-missing` because the previous
+ * plan version already carried this exact task_id with no `ui_affecting` key,
+ * as a verbatim carry-forward. The operator's binding decision (S2 fix round
+ * 2): work already in flight must not be blocked by a flag that predates it,
+ * so a task `draftNextVersion` carries forward unchanged is grandfathered
+ * rather than stamped `ui_affecting: false` — that would claim a decision
+ * nobody made.
+ *
+ * "Unchanged" means the whole record, not just `claims`: `draftNextVersion`
+ * rewrites only `plan_version` (every carried task) and `task_status` (the
+ * dead `superseded` record a supersede leaves behind) — so a record that
+ * matches the previous one on every other field is something the plan editor
+ * itself carried forward, never content a human or a supersede replacement
+ * wrote. A supersede replacement that keeps the old task_id (D-121) writes
+ * new content under that id — a changed description or deps included, even
+ * when the claims happen to match (S1 fix round 3) — so it fails this
+ * comparison and still needs the flag.
+ *
+ * A task_id can hold several rows (dead `superseded` records plus the live
+ * one), so a row is exempt when ANY previous row of that id matches it. A
+ * supersede replacement that restores the exact content of an existing row
+ * is therefore exempt too: that content already stood unflagged.
+ *
+ * `added` tasks and v1 tasks have no previous record to match, so they are
+ * never exempt.
+ */
+function isGrandfatheredUiFlag(t, previous) {
+    if (previous === undefined)
+        return false;
+    const { plan_version: _pv2, task_status: _ts2, ...rest } = t;
+    return previous.tasks.some((prevTask) => {
+        if (prevTask.task_id !== t.task_id || prevTask.ui_affecting !== undefined)
+            return false;
+        const { plan_version: _pv1, task_status: _ts1, ...prevRest } = prevTask;
+        return deepEqual(prevRest, rest);
+    });
+}
 /**
  * A `keeps_exports` promise is a file the task swears to keep the exports of,
  * and the post-run verifier reads it back against the task's diff. Three
@@ -373,6 +485,11 @@ export function validatePlan(plan, opts = {}) {
         for (const issue of unkeptPromises(t, result.valid ? [] : result.errors)) {
             errors.push({ path: `/tasks/${t.task_id}${issue.path}`, message: issue.message });
         }
+        if (!isGrandfatheredUiFlag(t, opts.previous)) {
+            for (const issue of uiFlagMissing(t)) {
+                errors.push({ path: `/tasks/${t.task_id}${issue.path}`, message: issue.message });
+            }
+        }
         if (t.plan_version !== plan.version) {
             errors.push({
                 path: `/tasks/${t.task_id}/plan_version`,
@@ -385,7 +502,7 @@ export function validatePlan(plan, opts = {}) {
         for (const field of unreadTaskBudgetFields(budget)) {
             errors.push({
                 path: `/tasks/${t.task_id}/budget/${field}`,
-                message: `Budget field "${field}" has no mechanical reader: nothing in the factory can enforce it per task, so declaring it here states a limit the task will never be held to. The turn ceiling is the role template's maxTurns (.claude/agents/<role>.md), enforced by the harness per role; the dispatch prompt restates that number (agent-interviews.md M-4, corrected 2026-09-11).`,
+                message: `Budget field "${field}" has no mechanical reader: nothing in the factory can enforce it per task, so declaring it here states a limit the task will never be held to. The turn ceiling is the role template's maxTurns (.claude/agents/bs-<role>.md), enforced by the harness per role; the dispatch prompt restates that number (agent-interviews.md M-4, corrected 2026-09-11).`,
             });
         }
         // D-7: the ref is what result.schema.json defers structured_output's shape
@@ -525,7 +642,72 @@ function readAddedList(epicId, version, added) {
     });
     return added;
 }
-export function draftNextVersion(prev, changes) {
+/**
+ * The replacement and added records a draft lands, at most one live record
+ * under any id. `liveSpec` reads the last live record under an id, so a second
+ * one fails nothing: it quietly wins, and ingest sees one task where the
+ * author wrote two.
+ *
+ * Several supersede keys folding into one task is the legitimate way to name
+ * one id twice. Their replacements are identical, so one copy is carried.
+ * Anything else that lands a second live record is refused: two keys with
+ * different records under one id, or a replacement or added id that a carried
+ * task still holds live, that a replacement already declares, or that an
+ * earlier added entry declares. Dead records may share an id freely; a task
+ * superseded under its own id (D-121) already leaves one of each.
+ */
+function oneLiveRecordPerId(prev, version, carried, supersede, addedList) {
+    const refuse = (taskId, why, details) => new PlanError('plan.duplicate-live-task', `Refusing to draft plan "${prev.epic_id}" v${version}: ${why}`, { epicId: prev.epic_id, version, taskId, ...details });
+    const ownId = (taskId) => `Give the new task an id of its own, or supersede "${taskId}" in the same amendment.`;
+    const liveCarried = new Set(carried.filter((t) => t.task_status !== 'superseded').map((t) => t.task_id));
+    const replacements = [];
+    const keyOf = new Map();
+    for (const [key, t] of Object.entries(supersede)) {
+        const record = { ...t, plan_version: version };
+        const firstKey = keyOf.get(record.task_id);
+        if (firstKey === undefined) {
+            if (liveCarried.has(record.task_id)) {
+                throw refuse(record.task_id, `changes.supersede["${key}"] replaces into "${record.task_id}", which v${prev.version} still holds live and this amendment does not supersede. ${ownId(record.task_id)}`, { key });
+            }
+            keyOf.set(record.task_id, key);
+            replacements.push(record);
+            continue;
+        }
+        const first = replacements.find((r) => r.task_id === record.task_id);
+        if (!isDeepStrictEqual(first, record)) {
+            throw refuse(record.task_id, `changes.supersede["${firstKey}"] and changes.supersede["${key}"] both replace into "${record.task_id}" with different records. Keys fold into one task only when they carry the same replacement.`, { keys: [firstKey, key] });
+        }
+    }
+    const added = [];
+    const addedAt = new Map();
+    addedList.forEach((t, index) => {
+        const where = liveCarried.has(t.task_id)
+            ? `v${prev.version} still holds it live. ${ownId(t.task_id)}`
+            : keyOf.has(t.task_id)
+                ? `changes.supersede["${keyOf.get(t.task_id)}"] already replaces into it. Give the new task an id of its own.`
+                : addedAt.has(t.task_id)
+                    ? `changes.added[${addedAt.get(t.task_id)}] already declares it. Give the new task an id of its own.`
+                    : undefined;
+        if (where !== undefined) {
+            throw refuse(t.task_id, `changes.added[${index}] declares "${t.task_id}", and ${where}`, {
+                index,
+            });
+        }
+        addedAt.set(t.task_id, index);
+        added.push({ ...t, plan_version: version });
+    });
+    return { replacements, added };
+}
+export function draftNextVersion(prev, changes, 
+/**
+ * Dead records for tasks the plan never listed — ones only the event log
+ * added — that `changes.supersede` retires. Built by the caller from the
+ * log (`supersededStubFromLog`), because this function does no I/O. Each
+ * must already be `superseded` at the new version; they are carried beside
+ * the plan's own records so ingest has something to emit
+ * `task-superseded` from.
+ */
+loggedStubs = []) {
     const newVersion = prev.version + 1;
     const supersede = readSupersedeMap(prev.epic_id, newVersion, changes.supersede);
     const carried = [];
@@ -539,11 +721,8 @@ export function draftNextVersion(prev, changes) {
         }
         carried.push({ ...t, plan_version: newVersion });
     }
-    const replacements = Object.values(supersede).map((t) => ({ ...t, plan_version: newVersion }));
-    const added = readAddedList(prev.epic_id, newVersion, changes.added).map((t) => ({
-        ...t,
-        plan_version: newVersion,
-    }));
+    carried.push(...loggedStubs);
+    const { replacements, added } = oneLiveRecordPerId(prev, newVersion, carried, supersede, readAddedList(prev.epic_id, newVersion, changes.added));
     const tasks = [...carried, ...replacements, ...added];
     // An edge may only name a task this version declares -- `validatePlan`'s own
     // rule. Dropping a completed task from the live backlog is what breaks it:
@@ -552,21 +731,69 @@ export function draftNextVersion(prev, changes) {
     // no longer mentions. Plans are immutable and nothing deletes one, so that
     // left no way out.
     //
-    // Dropping the edge loses nothing: the only ids that leave are completed and
-    // not superseded, so the ordering constraint is already discharged, and a
-    // superseded task is carried forward (as `superseded`) and keeps its edges.
-    // Applied to the CARRIED edges only -- an edge this amendment adds is
-    // something the author wrote, and deleting it silently would answer a typo
-    // with a plan that no longer says what they asked for. `validatePlan` names
-    // that one instead.
+    // Dropping the edge loses nothing: the only ids that leave outright are
+    // completed and not superseded, so the ordering constraint is already
+    // discharged. Applied to the CARRIED edges only -- an edge this amendment
+    // adds is something the author wrote, and deleting it silently would answer
+    // a typo with a plan that no longer says what they asked for. `validatePlan`
+    // names that one instead.
+    //
+    // A superseded task is carried forward too (as `superseded`), which used to
+    // read as "so it keeps its edges" -- true only when the replacement keeps
+    // the old task_id (D-121's usual case; the id maps to itself below). A
+    // supersede that changes the id moves the *work* to the new id, but the old
+    // one stays in `tasks` only as a dead record: `livePlanTasks` (and so
+    // `computeNextWave`'s done set, waveNext.ts) drops it, so it can never
+    // become terminal. An edge still naming it would defer its dependent
+    // forever -- `dependency-pending` on an id nothing will ever finish. Moving
+    // both ends of a carried edge through the old-id -> replacement-id map
+    // before the declared-check is what keeps the dependency resolvable under
+    // its new name instead of quietly wedging it (#234).
     const declared = new Set(tasks.map((t) => t.task_id));
-    const carriedEdges = prev.edges.filter((e) => declared.has(e.task) && declared.has(e.dependsOn));
+    const rewireTo = new Map();
+    for (const [oldId, replacement] of Object.entries(supersede)) {
+        if (replacement.task_id !== oldId)
+            rewireTo.set(oldId, replacement.task_id);
+    }
+    const rewire = (id) => rewireTo.get(id) ?? id;
+    // taskEvents.ts's `edgeKey` (see its doc comment at edgesAlreadyRecorded)
+    // treats task+dependsOn+edge_type as the triple that identifies an edge: an
+    // `artifact` handoff and a `claim-order` handoff between the same two tasks
+    // are two different claims and both belong in the log as two events. Not
+    // reused directly -- taskEvents.ts imports plan.ts, so importing back would
+    // make a cycle -- but the dedup below has to match its shape or it silently
+    // merges two edges that the rest of the system has always kept distinct.
+    const edgeKey = (task, dependsOn, edgeType) => `${task}\u0000${dependsOn}\u0000${edgeType}`;
+    const newEdges = changes.newEdges ?? [];
+    const newEdgeKeys = new Set(newEdges.map((e) => edgeKey(e.task, e.dependsOn, e.edge_type)));
+    const seenCarried = new Set();
+    const carriedEdges = [];
+    for (const e of prev.edges) {
+        const rewiredTask = rewire(e.task);
+        const rewiredDependsOn = rewire(e.dependsOn);
+        if (!declared.has(rewiredTask) || !declared.has(rewiredDependsOn))
+            continue;
+        if (rewiredTask === rewiredDependsOn)
+            continue; // rewiring both ends onto the same replacement is not a dependency
+        const key = edgeKey(rewiredTask, rewiredDependsOn, e.edge_type);
+        // An edge this amendment adds wins over a carried edge rewired onto the
+        // same (task, dependsOn, edge_type) triple, and a rewire that collapses
+        // two carried edges onto the same triple keeps only the first -- either
+        // way, no duplicate. Two edges on the same pair with different edge_type
+        // are not a duplicate at all (edgeKey's triple, not just the pair).
+        if (newEdgeKeys.has(key) || seenCarried.has(key))
+            continue;
+        seenCarried.add(key);
+        carriedEdges.push(rewiredTask === e.task && rewiredDependsOn === e.dependsOn
+            ? e
+            : { ...e, task: rewiredTask, dependsOn: rewiredDependsOn });
+    }
     return {
         epic_id: prev.epic_id,
         version: newVersion,
         status: 'active',
         tasks,
-        edges: [...carriedEdges, ...(changes.newEdges ?? [])],
+        edges: [...carriedEdges, ...newEdges],
         ...(prev.project ? { project: prev.project } : {}),
         ...(prev.effort ? { effort: prev.effort } : {}),
     };
@@ -581,8 +808,8 @@ export function draftNextVersion(prev, changes) {
  * is not: a caller that could write half of a version could write a version
  * no event explains.
  */
-export function nextVersion(prev, changes, opts = {}) {
-    const newPlan = draftNextVersion(prev, changes);
+export function nextVersion(prev, changes, opts = {}, loggedStubs = []) {
+    const newPlan = draftNextVersion(prev, changes, loggedStubs);
     writePlanFile(newPlan, opts);
     return newPlan;
 }
@@ -596,7 +823,7 @@ export function nextVersion(prev, changes, opts = {}) {
  * dead copies are set aside. Indexing the whole task list into a Map by id
  * silently answers with whichever record happened to be written last.
  */
-function liveSpec(plan, id) {
+export function liveSpec(plan, id) {
     let found;
     for (const t of plan.tasks) {
         if (t.task_id === id && t.task_status !== 'superseded')
@@ -666,6 +893,12 @@ function specSignature(t) {
  * keyed by task_id and a replacement that keeps its id — the shape every real
  * amendment has used — leaves the plan holding a dead record and a live one
  * under the same key.
+ *
+ * An id new to B is `added` only if B holds it live. One that arrives already
+ * dead is a task B retired without A ever recording it — a task only the event
+ * log added, which `draftNextVersion` carries as a superseded stub — so it is
+ * `superseded`, after the ids A knew. Reading it as added would make a dead
+ * record look like new work to land.
  */
 export function diffPlans(vA, vB) {
     const aIds = new Set(vA.tasks.map((t) => t.task_id));
@@ -674,9 +907,11 @@ export function diffPlans(vA, vB) {
     const superseded = [];
     const carried = [];
     const removed = [];
+    const deadOnArrival = [];
     for (const id of bIds) {
-        if (!aIds.has(id))
-            added.push(id);
+        if (aIds.has(id))
+            continue;
+        (liveSpec(vB, id) === undefined ? deadOnArrival : added).push(id);
     }
     for (const id of aIds) {
         if (!bIds.has(id)) {
@@ -692,5 +927,6 @@ export function diffPlans(vA, vB) {
             : liveB !== undefined && specSignature(liveA) === specSignature(liveB);
         (same ? carried : superseded).push(id);
     }
+    superseded.push(...deadOnArrival);
     return { added, removed, superseded, carried };
 }

package/factory/orchestrator/dist/planQuorum.js

@@ -1,5 +1,5 @@
-import { loadBudgetPolicy } from './budgets.js';
 import { loadCrosscheckPolicy, } from './crosscheck.js';
+import { budgetPolicyForPlan } from './epicBudget.js';
 import { appendEvent } from './events.js';
 import { livePlanTasks, loadPlan, PlanError, planRefTaskId, } from './plan.js';
 import { enabledExternalProviders, nativeProviderName, runQuorumCase, } from './quorum.js';
@@ -329,7 +329,10 @@ export async function runPlanQuorum(input, ctx, opts = {}) {
         });
     }
     const policy = input.crosscheck?.policy ?? loadCrosscheckPolicy();
-    const epicCapTokens = input.epicCapTokens ?? loadBudgetPolicy().epic.capTokens;
+    // The cap for the tier this plan runs at: its own `effort` after the
+    // security floor (default_tier when it names none).
+    const epicCapTokens = input.epicCapTokens ??
+        budgetPolicyForPlan(plan, { securityPolicy: policy.planQuorum }).epic.capTokens;
     const triggers = evaluatePlanQuorumTriggers(plan, policy.planQuorum, epicCapTokens, {
         plannerConfidence: input.plannerConfidence,
     });