@juzser/blacksmith 0.3.0 → 0.5.0

package/factory/orchestrator/dist/paths.js

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { readEnv } from './env.js';
 // factory/orchestrator/src/paths.ts -> repo root is three levels up.
 const here = path.dirname(fileURLToPath(import.meta.url));
 /**
@@ -11,6 +12,16 @@ const here = path.dirname(fileURLToPath(import.meta.url));
  * assets ships in the tarball. `packaging.test.ts` holds that claim.
  */
 export const REPO_ROOT = path.resolve(here, '..', '..', '..');
+/**
+ * Is `dir` this factory's own checkout, resolved rather than compared raw so
+ * a trailing slash or a relative path names the same answer. `audit.ts`
+ * (`auditedProjectName`) and `projects.ts` (`unwatchedProjects`) both need to
+ * tell "this clone, filed under its own directory name" from "a project that
+ * is genuinely named that" and used to each spell the comparison themselves.
+ */
+export function isFactoryCheckout(dir) {
+    return path.resolve(dir) === path.resolve(REPO_ROOT);
+}
 /**
  * Is this module running out of the blacksmith clone, or out of an installed
  * copy of the package?
@@ -19,7 +30,7 @@ export const REPO_ROOT = path.resolve(here, '..', '..', '..');
  * `package.json#files` could not ship it if it tried. A linked worktree spells
  * it as a file rather than a directory, which `existsSync` reads either way.
  */
-const IS_CLONE = existsSync(path.join(REPO_ROOT, '.git'));
+export const IS_CLONE = existsSync(path.join(REPO_ROOT, '.git'));
 /**
  * Where the work root goes when the CLI is not standing in a clone.
  *
@@ -36,9 +47,10 @@ const WORK_DIR_NAME = '.blacksmith';
  *
  * Pure, and exported for the test: the constants below call it once at module
  * load, but the install case can only be stated by a test that passes its own
- * roots in. `env.SMITH_HOME` wins outright; otherwise a clone keeps writing
- * into itself, and an install writes beside the operator instead of into
- * `node_modules/@juzser/blacksmith`, which the next `npm i` replaces wholesale.
+ * roots in. `BS_HOME` (or its legacy `SMITH_HOME` fallback) wins outright;
+ * otherwise a clone keeps writing into itself, and an install writes beside
+ * the operator instead of into `node_modules/@juzser/blacksmith`, which the
+ * next `npm i` replaces wholesale.
  *
  * The layout *under* the root is identical in both cases on purpose. A path
  * like `state/events/<session>.jsonl` is spelled in runbooks, in agent
@@ -46,9 +58,10 @@ const WORK_DIR_NAME = '.blacksmith';
  * if only the anchor moves.
  */
 export function resolveWorkRoot(repoRoot, cwd, env, isClone) {
-    const declared = env.SMITH_HOME?.trim();
-    // An empty `SMITH_HOME=` is how an unset variable gets spelled by accident in
-    // a shell profile or a CI matrix; resolved literally it would mean cwd.
+    const declared = readEnv(env, 'BS_HOME')?.trim();
+    // An empty `BS_HOME=`/`SMITH_HOME=` is how an unset variable gets spelled by
+    // accident in a shell profile or a CI matrix; resolved literally it would
+    // mean cwd.
     if (declared)
         return path.resolve(cwd, declared);
     return isClone ? repoRoot : path.join(cwd, WORK_DIR_NAME);

package/factory/orchestrator/dist/plan.js

@@ -1,26 +1,22 @@
 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';
 import { compileSchemas, validateRecord, } from './schemas.js';
+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/
@@ -103,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
@@ -133,6 +147,122 @@ export function loadPlan(epicId, version, opts = {}) {
     }
     return JSON.parse(readFileSync(filePath, 'utf8'));
 }
+/**
+ * A task ref's project, read off its own epic's latest plan version -- the
+ * D-246 precedent (`db/projector.ts`'s `planProjectResolver`, for the board)
+ * restated here so `errorIssues.ts` can answer the same question without
+ * importing anything database-shaped (`test/cliBoot.test.ts` pins `cli.ts`'s
+ * built module graph off drizzle/sqlite entirely, and `cli.ts` statically
+ * imports the error-issue reporter).
+ *
+ * Never throws and never guesses: an id with no epic segment, an epic with
+ * no plan on disk, and an unreadable or unparseable plan file all answer
+ * `null` alike, on purpose -- "cannot tell" and "the plan has no project" are
+ * the same non-answer to a caller that must never turn either one into this
+ * factory's own name. Answers cache by epic id for the resolver's lifetime,
+ * since one `issues report` run reads the same epic's plan for every row
+ * that epic contributed.
+ */
+export function planProjectResolverForTaskRef(opts = {}) {
+    const cache = new Map();
+    return (taskRef) => {
+        const epicId = epicOfTaskId(taskRef);
+        if (epicId === null)
+            return null;
+        const cached = cache.get(epicId);
+        if (cached !== undefined)
+            return cached;
+        let project = null;
+        try {
+            const version = latestPlanVersion(epicId, opts);
+            if (version !== null)
+                project = loadPlan(epicId, version, opts).project ?? null;
+        }
+        catch {
+            // Unreadable or unparseable plan file: no answer, not a crash.
+        }
+        cache.set(epicId, project);
+        return project;
+    };
+}
+/**
+ * Whether `opts.specsDir` names THIS checkout's own specs/active tree --
+ * absent (so `planFilePath`/`latestPlanVersion` fall back to
+ * `SPECS_ACTIVE_DIR` themselves) or an explicit path that resolves to the
+ * same directory. Only then is a plan found there, naming no project,
+ * evidence of "self": `--specs-dir` is also how a caller points this
+ * resolver at a DIFFERENT checkout's specs tree entirely -- `issueInputs`'s
+ * own doc comment names "the daemon's own event log and a target checkout's
+ * specs tree" as an intended use -- and a plan found THERE naming no project
+ * is that other project's own silence, not this factory's (S2-b).
+ */
+function isSelfSpecsDir(opts) {
+    return opts.specsDir === undefined || path.resolve(opts.specsDir) === SPECS_ACTIVE_DIR;
+}
+/**
+ * The self-fallback half of `planProjectResolverForTaskRefOrSelf`, on its
+ * own: a plan found on disk for the epic that simply declares no `project`
+ * field IS this factory's own project, by construction -- only this
+ * checkout's own epics have a plan under `specs/active` at all, so finding
+ * one there is itself the "self" signal a foreign epic's plan (which lives
+ * in the foreign project's own specs tree, never this one) can never
+ * produce. An epic with no plan on disk anywhere, or a bare ref with no
+ * epic segment, answers `null` -- "cannot tell whose project this is" --
+ * because plan.ts must not be the module that hardcodes this factory's
+ * name; the caller supplies it.
+ *
+ * That "only this checkout's own epics" premise holds only while `opts`
+ * actually points at this checkout's own specs/active tree
+ * (`isSelfSpecsDir`, S2-b): a caller that redirected `--specs-dir` at some
+ * OTHER checkout's specs tree gets no self-fallback at all, `null` only,
+ * because a plan found there naming no project is that other checkout's own
+ * silence, not this factory's.
+ *
+ * Exported as its own resolver, separate from `planProjectResolverForTaskRef`
+ * (S2-c): production callers (`cli.ts`'s `issueInputs`) hand the two to
+ * `withSessionFallback`/`foldErrorEvents` as DISTINCT tiers -- the strict
+ * resolver first, then a session's own unanimous stamp, and only then this
+ * guess -- so a session-mate's real stamp naming a different project
+ * outranks this weakest signal rather than losing to it, which is what
+ * happened when the two were folded into one resolver and tried together as
+ * a single first tier.
+ */
+export function planSelfFallbackForTaskRef(selfProject, opts = {}) {
+    const selfEligible = isSelfSpecsDir(opts);
+    const hasPlanCache = new Map();
+    return (taskRef) => {
+        if (!selfEligible)
+            return null;
+        const epicId = epicOfTaskId(taskRef);
+        if (epicId === null)
+            return null;
+        let hasPlan = hasPlanCache.get(epicId);
+        if (hasPlan === undefined) {
+            hasPlan = latestPlanVersion(epicId, opts) !== null;
+            hasPlanCache.set(epicId, hasPlan);
+        }
+        return hasPlan ? selfProject : null;
+    };
+}
+/**
+ * `planProjectResolverForTaskRef` composed with `planSelfFallbackForTaskRef`
+ * as a single resolver, direct answer first and self-fallback second, for
+ * callers that want the OLD combined behavior (both tiers tried back to
+ * back, with nothing -- such as a session stamp -- able to sit between
+ * them). Kept for callers that do not need the S2-c tier split; `cli.ts`'s
+ * `issueInputs` no longer uses this, it hands the two halves to
+ * `withSessionFallback` separately instead.
+ */
+export function planProjectResolverForTaskRefOrSelf(selfProject, opts = {}) {
+    const resolve = planProjectResolverForTaskRef(opts);
+    const selfFallback = planSelfFallbackForTaskRef(selfProject, opts);
+    return (taskRef) => {
+        const direct = resolve(taskRef);
+        if (direct !== null)
+            return direct;
+        return selfFallback(taskRef);
+    };
+}
 /**
  * Reduce an `output_schema_ref` to the name the compiled schema set knows it
  * by. `compileSchemas` keys on filename-minus-`.schema.json`, so a path, a
@@ -172,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
@@ -256,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`,
@@ -268,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
@@ -408,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 = [];
@@ -422,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:
@@ -435,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 } : {}),
     };
@@ -464,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;
 }
@@ -479,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')
@@ -509,6 +853,19 @@ export function livePlanTasks(plan) {
     }
     return live;
 }
+/**
+ * The plan's tasks in the shape `resolveFindingOwner` reads: only the live
+ * (D-126) ones, and only the `claims` field ownership resolution needs. This
+ * is `livePlanTasks` restated as claims rather than full specs, so a caller
+ * asking "does some task in this plan still claim that file?" (`audit
+ * resolve`) gets the same live/superseded rule `epic verdict` does, not the
+ * raw `plan.tasks` array that also holds every amendment left behind.
+ */
+export function planClaimedTasks(plan) {
+    return livePlanTasks(plan)
+        .filter((task) => Array.isArray(task.claims))
+        .map((task) => ({ task_id: task.task_id, claims: task.claims }));
+}
 /**
  * What makes two records the same *spec*: everything except the version stamp
  * and the workflow status. `nextVersion` rewrites `plan_version` on every
@@ -536,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));
@@ -544,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)) {
@@ -562,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,
     });