@juzser/blacksmith 0.3.0 → 0.5.0

package/factory/orchestrator/dist/spec.js

@@ -6,8 +6,14 @@ import {
 // since D-127 that is reachable only once the amendment's task ids land, so
 // a guard here that asked about the terminal status would be asking about a
 // transition this module never attempts.
-AMEND_PENDING_STATUS, findingScope, LEGAL_TRANSITIONS, listFindings, mintFindings, raiseFinding, SPEC_FINDING_SCOPE, transition, } from './findings.js';
-import { diffPlans, draftNextVersion, livePlanTasks, nextVersion, planRefTaskId, validatePlan, } from './plan.js';
+AMEND_PENDING_STATUS, findingScope, LEGAL_TRANSITIONS, listFindings, mintFindings, 
+// #221: the vocabulary for "still awaiting something" this codebase already
+// has one of — the same set epic.ts's close gate and `smith crossfind run`
+// read. Reused here rather than re-deriving "open" from LEGAL_TRANSITIONS a
+// second time.
+OPEN_FINDING_STATUSES, raiseFinding, SPEC_FINDING_SCOPE, transition, } from './findings.js';
+import { bareTaskId, diffPlans, draftNextVersion, livePlanTasks, nextVersion, PlanError, planRefTaskId, resolveTaskId, validatePlan, } from './plan.js';
+import { readAddedTasks, supersededStubFromLog } from './taskEvents.js';
 import { RESERVED_TASK_ID } from './worktree.js';
 /**
  * P9-9/D-33. Every judge in this factory returns findings against a diff, and
@@ -68,6 +74,131 @@ export function latestSpecReview(events, epicId) {
     }
     return latest;
 }
+/**
+ * Old task id -> the replacement that superseded it, folded across every
+ * `plan-version-created` event this epic has (D-<successor-chain>). Not a
+ * last-wins fold like `latestSpecReview`: a task superseded in v2 and its own
+ * successor superseded again in v4 contributes two independent entries to
+ * the same map, and epic.ts's `resolveSupersededRow` walks the chain — each
+ * amendment only ever needs to know its own one hop.
+ *
+ * Only the rename-supersede case is ever present here: `amendPlan` records a
+ * pairing only when the replacement's `task_id` differs from the id it
+ * replaces (the same-id case needs no successor — the fold's own row already
+ * carries the work forward under the id everyone already has).
+ *
+ * Events on the log from before this field shipped carry no `successors` key
+ * at all — only the plan `diff` `amendPlan` has always written. For exactly
+ * that shape (no `successors` key, present or absent notwithstanding), fall
+ * back to inferring the pairing from `diff.superseded`/`diff.added`, but only
+ * when it is completely unambiguous: one id on each side, and they differ.
+ * Any other shape (0 or ≥2 ids on either side, a missing/malformed diff)
+ * infers nothing — the same fail-closed answer an unreadable `successors`
+ * gets. A present `successors` — even an explicit `{}` — always wins over
+ * inference; the fallback only ever runs when the key is absent entirely.
+ */
+export function taskSuccessors(events, epicId) {
+    const successors = new Map();
+    for (const event of events) {
+        if (event.record.event_type !== PLAN_AMENDED_EVENT)
+            continue;
+        const payload = event.record.payload;
+        if (payload.epic_id !== epicId)
+            continue;
+        const entries = payload.successors;
+        if (entries !== undefined) {
+            if (entries === null || typeof entries !== 'object')
+                continue;
+            for (const [oldId, newId] of Object.entries(entries)) {
+                if (typeof newId === 'string')
+                    successors.set(oldId, newId);
+            }
+            continue;
+        }
+        // Legacy fallback (no `successors` key at all) — see doc comment above.
+        const diff = payload.diff;
+        if (diff === null || typeof diff !== 'object')
+            continue;
+        const supersededIds = diff.superseded;
+        const addedIds = diff.added;
+        if (!Array.isArray(supersededIds) || !Array.isArray(addedIds))
+            continue;
+        if (supersededIds.length !== 1 || addedIds.length !== 1)
+            continue;
+        const [oldId] = supersededIds;
+        const [newId] = addedIds;
+        if (typeof oldId === 'string' && typeof newId === 'string' && oldId !== newId) {
+            successors.set(oldId, newId);
+        }
+    }
+    return successors;
+}
+/**
+ * Walks `taskSuccessors`' one-hop map forward from `from` and returns the
+ * ordered bare hop ids from the one right after `from` through `target`
+ * inclusive — or `undefined` if `target` never turns up on that chain.
+ * `worktree create --from` (cli.ts's `worktree.not-a-successor` guard) used
+ * to ask `successors.get(from)` alone, which only ever names the *direct*
+ * successor: a plan amended twice before the intermediate successor is ever
+ * cut — A superseded by B in v6, B superseded by C in v7, B never cut —
+ * leaves `taskSuccessors` with two independent one-hop entries (A -> B,
+ * B -> C) and no direct A -> C entry at all, so cutting C `--from A` was
+ * refused despite the log naming C as A's transitive successor.
+ *
+ * Every hop the walk passes through on the way to `target` comes back too,
+ * not just the yes/no answer: `createTaskWorktree` (worktree.ts) branches
+ * `--from`'s target directly off `from`'s own branch, so if some *hop in
+ * between* was already cut as its own branch, skipping straight from `from`
+ * to `target` silently drops that hop's commits. Answering that needs git
+ * state this module deliberately never touches, so the walk hands its own
+ * intermediate hops back and leaves the git-aware check — and which hop to
+ * refuse on — to the caller (cli.ts's guard, paired with worktree.ts's
+ * branch-existence check).
+ *
+ * Keys are normalized to their bare form once (`successors` entries can be
+ * bare or `${epicId}/${id}` at any hop, D-46/P9-29), so each hop after that
+ * is one lookup against the normalized map — the same "check both
+ * spellings" a single-hop lookup did, done once instead of re-derived every
+ * hop. A cycle — a successor id already visited — stops the walk and
+ * reports no match, the same fail-closed answer as a chain that simply runs
+ * out; a malformed log must never spin.
+ *
+ * Directional only: this walks forward from `from`, value to value, never a
+ * hop's key. A `target` that is a predecessor of `from` is therefore never
+ * found, however far back it sits — `--from` claims a task's own future, not
+ * its past.
+ */
+export function successorChainPath(epicId, from, target, successors) {
+    const bareSuccessors = new Map([...successors].map(([oldId, newId]) => [bareTaskId(epicId, oldId), newId]));
+    const targetBare = bareTaskId(epicId, target);
+    const visited = new Set([bareTaskId(epicId, from)]);
+    let currentId = bareTaskId(epicId, from);
+    const path = [];
+    for (;;) {
+        const nextId = bareSuccessors.get(currentId);
+        if (nextId === undefined)
+            return undefined;
+        const nextBare = bareTaskId(epicId, nextId);
+        path.push(nextBare);
+        if (nextBare === targetBare)
+            return path;
+        if (visited.has(nextBare))
+            return undefined;
+        visited.add(nextBare);
+        currentId = nextBare;
+    }
+}
+/**
+ * Answers whether `target` sits anywhere on `from`'s forward successor
+ * chain — not only at the first hop. A thin boolean wrapper over
+ * `successorChainPath`; callers that also need to know *which* hops sit
+ * between `from` and `target` (cli.ts's `worktree create --from` guard, to
+ * refuse skipping past a hop already cut as its own branch) want that
+ * function directly instead.
+ */
+export function isTaskInSuccessorChain(epicId, from, target, successors) {
+    return successorChainPath(epicId, from, target, successors) !== undefined;
+}
 /**
  * The epic gate refusing to certify a spec nobody re-read once the code
  * existed. Mirrors integrationBlockers exactly, including the fail-closed
@@ -95,11 +226,26 @@ export function latestSpecReview(events, epicId) {
  * a required parameter for the reason `integration` and `mcp` are required on
  * summarizeEpic — a defaulted one is a forgotten argument that manufactures a
  * green.
+ *
+ * `effort` is the one legal way an epic reaches this gate with no review on
+ * record at all: `.claude/skills/bs/run.md` step 13 lets tier `small` skip
+ * the closing review while the plan is still v1 — never amended, so never
+ * shown a defect a review would have caught. That is not a second escape
+ * hatch grown here; it is that rule, read. The skip is narrow on purpose: it
+ * only ever waives an *absent* review. A plan at v2+, or a plan version this
+ * function cannot read, still blocks regardless of tier, and a review that
+ * IS on record is still walked through every staleness check below even
+ * under `small` — the tier says "you may have skipped it," never "you may
+ * trust it once stale." Like `planVersion`, `effort` is a required parameter
+ * for the same reason: a defaulted one would silently reinstate the escape
+ * hatch this function has never had.
  */
-export function specReviewBlockers(epicId, status, planVersion) {
-    const branch = `smith/${epicId}/${RESERVED_TASK_ID}`;
-    const { review, headSha } = status;
+export function specReviewBlockers(epicId, status, planVersion, effort) {
+    const { review, headSha, branch } = status;
     if (review === null) {
+        if (effort.closingSpecReview === 'when-plan-amended' && planVersion === 1) {
+            return [];
+        }
         return [
             `Epic "${epicId}" has no closing spec review on record: nothing re-read the plan against the code that now exists. A spec review run before the code was written cannot see the defects the code reveals (D-33).`,
         ];
@@ -190,6 +336,7 @@ export async function recordSpecReview(input, ctx, opts = {}) {
                 : { reviewed_by_provider: input.reviewedByProvider }),
             finding_ids: findingIds,
             finding_count: findingIds.length,
+            ...(input.noFindings === true ? { attested_by: 'operator' } : {}),
         },
     }, opts);
     return {
@@ -202,6 +349,55 @@ export async function recordSpecReview(input, ctx, opts = {}) {
         ts: stored.record.ts,
     };
 }
+/**
+ * Resolve every `changes.supersede` key to the task it names, before anything
+ * is drafted: the plan's own task, or one only the epic's log added.
+ *
+ * A key the plan does not list used to match nothing in `draftNextVersion` and
+ * its replacement was appended anyway, so a follow-up the gate minted (a
+ * `task-added` and no plan record) stayed live beside the task meant to
+ * replace it, and a typo did the same. The key now goes through
+ * `resolveTaskId` with the log's ids as `alsoKnown`, so a bare and a qualified
+ * spelling both work and a key naming nothing is `plan.unknown-task`, refused
+ * before a plan file exists. A key resolving to a plan task is rewritten to
+ * that task's own id. A key resolving to a log-only task yields the dead
+ * record `draftNextVersion` carries for it (`supersededStubFromLog`).
+ *
+ * The log is read lineage-wide and narrowed to this epic, the way the
+ * follow-up splice in `wave next` narrows it: another epic's row is not a
+ * task of this plan.
+ *
+ * Exported for `proposeSpecChange`, whose pre-check drafts the same version
+ * approval will cut: a draft built from unresolved keys would record a diff
+ * that approval then contradicts.
+ */
+export async function resolveSupersedeKeys(plan, changes, ctx, opts) {
+    const supersede = changes.supersede;
+    // A shape no map-shaped read can make is `draftNextVersion`'s to refuse,
+    // with its own message.
+    if (typeof supersede !== 'object' || supersede === null || Array.isArray(supersede)) {
+        return { changes, loggedStubs: [] };
+    }
+    const keys = Object.keys(supersede);
+    if (keys.length === 0)
+        return { changes, loggedStubs: [] };
+    const logged = (await readAddedTasks({ sessionId: ctx.sessionId }, opts)).filter((t) => t.epicId === plan.epic_id);
+    const planIds = new Set(plan.tasks.map((t) => t.task_id));
+    const resolved = {};
+    const loggedStubs = new Map();
+    for (const [key, replacement] of Object.entries(supersede)) {
+        const id = resolveTaskId(plan, key, logged.map((t) => t.taskId));
+        if (id in resolved) {
+            throw new PlanError('plan.ambiguous-task', `changes.supersede names "${id}" twice (as "${key}" and under another spelling); one task is superseded once.`, { epicId: plan.epic_id, version: plan.version, typed: key, candidates: [id] });
+        }
+        resolved[id] = replacement;
+        const added = planIds.has(id) ? undefined : logged.find((t) => t.taskId === id);
+        if (added !== undefined) {
+            loggedStubs.set(id, supersededStubFromLog(added, plan.epic_id, plan.version + 1));
+        }
+    }
+    return { changes: { ...changes, supersede: resolved }, loggedStubs: [...loggedStubs.values()] };
+}
 /**
  * The one legitimate way to change an immutable plan.
  *
@@ -273,7 +469,8 @@ export async function amendPlan(input, ctx, opts = {}) {
     // `draftNextVersion` is for: "everything validates before anything acts"
     // only holds if this check can run before a plan file exists, and nothing in
     // this codebase deletes a plan file (D-127).
-    const draft = draftNextVersion(plan, input.changes ?? {});
+    const { changes, loggedStubs } = await resolveSupersedeKeys(plan, input.changes ?? {}, ctx, opts);
+    const draft = draftNextVersion(plan, changes, loggedStubs);
     // D-21: a malformed `--changes` file can still produce a draft that reads
     // fine structurally (every entry a plain object with a string task_id) but
     // fails the plan's own schema/taxonomy rules — the exact check `smith plan
@@ -281,9 +478,9 @@ export async function amendPlan(input, ctx, opts = {}) {
     // schema-invalid version written to disk is unrecoverable; refusing it here,
     // before the write, is what closes that loop rather than leaving `smith
     // plan validate` to reject the file this tool just produced.
-    const draftValidation = validatePlan(draft, opts);
+    const draftValidation = validatePlan(draft, { ...opts, previous: plan });
     if (!draftValidation.valid) {
-        throw new SpecError('plan.amendment-invalid-draft', `Refusing to amend plan "${epicId}" v${plan.version}: v${draft.version} would fail its own validation (the same check \`smith plan validate\` runs), so nothing was written. ${draftValidation.errors
+        throw new SpecError('plan.amendment-invalid-draft', `Refusing to amend plan "${epicId}" v${plan.version}: v${draft.version} would fail its own validation (the same check \`bs plan validate\` runs), so nothing was written. ${draftValidation.errors
             .map((e) => `${e.path}: ${e.message}`)
             .join(' ')}`, { epicId, version: plan.version, nextVersion: draft.version, errors: draftValidation.errors });
     }
@@ -304,9 +501,12 @@ export async function amendPlan(input, ctx, opts = {}) {
     // replacement is in `added`, so the obligation survives the rename; keeping
     // the dead id too would make the finding undischargeable, which is the
     // failure this whole defect is about, reached from the other side.
+    // `added` goes through the same filter: `diffPlans` already reports an id
+    // that arrives dead (a log-only task's stub) as superseded, and the filter
+    // keeps any dead id from becoming an obligation or covering a named site.
     const live = new Set(livePlanTasks(draft).map((t) => t.task_id));
     const obligations = [
-        ...new Set([...diff.added, ...diff.superseded.filter((id) => live.has(id))]),
+        ...new Set([...diff.added, ...diff.superseded].filter((id) => live.has(id))),
     ];
     if (obligations.length === 0) {
         const shape = diff.removed.length > 0
@@ -339,12 +539,43 @@ export async function amendPlan(input, ctx, opts = {}) {
         .filter((t) => obligated.has(t.task_id) && Array.isArray(t.claims))
         .flatMap((t) => t.claims);
     const unclaimedSites = namedSites.filter((s) => !claims.some((c) => claimCoversPath(c, s)));
+    // #221: every open finding this amendment does not cite, but whose id or
+    // fingerprint shows up in an added or superseded task's objective text —
+    // the tell that someone meant to carry it and did not name it in
+    // `findingIds`. `cited` is deliberately excluded: a finding already in
+    // `findingIds` is being discharged, not merely mentioned in passing, and a
+    // finding that is not open needs no warning because nothing is waiting on
+    // it. Read-only, computed off `all` (already fetched above) and the draft's
+    // own changes — nothing here can fail, so it costs nothing to compute
+    // before the guards below start writing.
+    const citedIds = new Set(findingIds);
+    const openUncited = all.filter((f) => OPEN_FINDING_STATUSES.has(f.finding_status) && !citedIds.has(f.finding_id));
+    const changedSpecs = [
+        ...(changes.added ?? []),
+        ...Object.values(changes.supersede ?? {}),
+    ];
+    const changedObjectives = changedSpecs
+        .map((spec) => spec.objective)
+        .filter((objective) => typeof objective === 'string');
+    const warnings = openUncited
+        .filter((finding) => changedObjectives.some((objective) => objective.includes(finding.finding_id) || objective.includes(finding.fingerprint)))
+        .map((finding) => `${finding.finding_id} is open (${finding.finding_status}) and is named in this amendment's objective text, but is not in --findings; it will stay open unless a later amendment cites it.`);
     // Validation is done; from here the version exists and the record has to
     // catch up to it, so nothing below is allowed to be conditional. The write
     // goes through `nextVersion` rather than from `draft`: `draftNextVersion` is
     // pure, so the two agree by construction, and there stays exactly one
     // function in this codebase that puts a plan version on disk.
-    const amended = nextVersion(plan, input.changes ?? {}, opts);
+    const amended = nextVersion(plan, changes, opts, loggedStubs);
+    // Old id -> replacement id, for the rename-supersede case only: a same-id
+    // supersede needs no pairing (the row already carries the work forward
+    // under the id everyone has). epic.ts's resolveSupersededRow/summarizeEpic
+    // is the reader — this is the one place an old task_id and its replacement
+    // are ever paired (PlanChanges.supersede), so it is recorded here or lost.
+    const successors = {};
+    for (const [oldId, replacement] of Object.entries(changes.supersede ?? {})) {
+        if (replacement.task_id !== oldId)
+            successors[oldId] = replacement.task_id;
+    }
     await appendEvent({
         session_id: ctx.sessionId,
         actor: ctx.actor ?? 'system',
@@ -364,13 +595,16 @@ export async function amendPlan(input, ctx, opts = {}) {
             sites: namedSites,
             sites_unclaimed: unclaimedSites,
             diff,
+            successors,
         },
     }, opts);
+    let lastEventId = '';
     for (const finding of cited) {
-        await transition(finding.finding_id, AMEND_PENDING_STATUS, ctx, opts, {
+        const transitioned = await transition(finding.finding_id, AMEND_PENDING_STATUS, ctx, opts, {
             amendsTaskIds: obligations,
             amendsPlanVersion: amended.version,
         });
+        lastEventId = transitioned.event_id;
     }
-    return { plan: amended, diff, sitesUnclaimed: unclaimedSites };
+    return { plan: amended, diff, sitesUnclaimed: unclaimedSites, warnings, event_id: lastEventId };
 }

package/factory/orchestrator/dist/specChange.js

@@ -3,7 +3,7 @@ import { appendEvent, readLineageEvents } from './events.js';
 import { listFindings, mintFindings, raiseFinding, transition, } from './findings.js';
 import { diffPlans, draftNextVersion, latestPlanVersion, livePlanTasks, validatePlan, } from './plan.js';
 import { compileSchemas, validateRecord } from './schemas.js';
-import { amendPlan } from './spec.js';
+import { amendPlan, resolveSupersedeKeys } from './spec.js';
 import { loadTaxonomy } from './taxonomy.js';
 /**
  * The worker half of a living spec.
@@ -121,21 +121,24 @@ export async function proposeSpecChange(input, ctx, opts = {}) {
     // The same check `amendPlan` runs on its own draft (D-21), one step earlier.
     // Plans are immutable and nothing deletes one, so the cost of finding this
     // out after the write is unrecoverable; the cost of finding it out here is a
-    // refusal the worker can still answer.
-    const draft = draftNextVersion(plan, request.changes ?? {});
-    const validation = validatePlan(draft, opts);
+    // refusal the worker can still answer. The supersede keys resolve first, as
+    // `amendPlan` resolves them, so a key naming a task only the log added
+    // drafts the same version — and records the same diff — approval will.
+    const { changes, loggedStubs } = await resolveSupersedeKeys(plan, request.changes ?? {}, ctx, opts);
+    const draft = draftNextVersion(plan, changes, loggedStubs);
+    const validation = validatePlan(draft, { ...opts, previous: plan });
     if (!validation.valid) {
         throw new SpecChangeError('spec-change.proposal-invalid-draft', `Refusing a spec change proposal against ${criterionRef}: v${draft.version} would fail its own validation, so it could never be approved. ${validation.errors.map((e) => `${e.path}: ${e.message}`).join(' ')}`, { taskId, criterionRef, errors: validation.errors });
     }
     const diff = diffPlans(plan, draft);
-    // Mirrors `amendPlan`'s obligation rule: added tasks, plus superseded ones
-    // that are still live in the draft. A proposal that obligates nothing would
-    // be approved into a finding that discharges the instant it is parked — an
+    // Mirrors `amendPlan`'s obligation rule: added and superseded tasks that are
+    // still live in the draft. A proposal that obligates nothing would be
+    // approved into a finding that discharges the instant it is parked — an
     // amendment nobody has to build, which is another way of saying no
     // amendment at all.
     const live = new Set(livePlanTasks(draft).map((t) => t.task_id));
     const obligations = [
-        ...new Set([...diff.added, ...diff.superseded.filter((id) => live.has(id))]),
+        ...new Set([...diff.added, ...diff.superseded].filter((id) => live.has(id))),
     ];
     if (obligations.length === 0) {
         throw new SpecChangeError('spec-change.proposal-without-obligation', `Refusing a spec change proposal against ${criterionRef}: the diff adds no task and supersedes no live one, so approving it would obligate nobody to build anything. Say which task's spec changes.`, { taskId, criterionRef, diff });
@@ -328,7 +331,7 @@ async function requireProposal(proposalId, opts, ctx) {
     const listed = await listSpecChanges(ctx.sessionId, {}, opts);
     const found = listed.find((p) => p.proposalId === proposalId);
     if (found === undefined) {
-        throw new SpecChangeError('spec-change.unknown-proposal', `No spec change proposal "${proposalId}" on this session's lineage. \`smith plan proposals\` lists what is there.`, { proposalId, sessionId: ctx.sessionId });
+        throw new SpecChangeError('spec-change.unknown-proposal', `No spec change proposal "${proposalId}" on this session's lineage. \`bs plan proposals\` lists what is there.`, { proposalId, sessionId: ctx.sessionId });
     }
     return found;
 }
@@ -417,6 +420,7 @@ export async function approveSpecChange(input, ctx, opts = {}) {
         plan: amendment.plan,
         diff: amendment.diff,
         sitesUnclaimed: amendment.sitesUnclaimed,
+        event_id: stored.event_id,
     };
 }
 /**

package/factory/orchestrator/dist/stack.js

@@ -167,7 +167,7 @@ function reportFor(field, value, source) {
                 field,
                 value,
                 support: 'refused',
-                note: `\`smith new\` refuses: factory/scaffold/base is TypeScript, and scaffolding it under a ${value} answer would hand you a project you did not ask for.`,
+                note: `\`bs new\` refuses: factory/scaffold/base is TypeScript, and scaffolding it under a ${value} answer would hand you a project you did not ask for.`,
             };
     }
     if (field === 'frontend') {
@@ -176,7 +176,7 @@ function reportFor(field, value, source) {
                 field,
                 value,
                 support: 'honoured',
-                note: '`smith new --ui` refuses until this names a framework.',
+                note: '`bs new --ui` refuses until this names a framework.',
             };
         }
         return value === 'vue'
@@ -185,7 +185,7 @@ function reportFor(field, value, source) {
                 field,
                 value,
                 support: 'refused',
-                note: `\`smith new --ui\` refuses: the UI template is Vue, and there is no ${value} template to layer instead.`,
+                note: `\`bs new --ui\` refuses: the UI template is Vue, and there is no ${value} template to layer instead.`,
             };
     }
     if (field === 'styling') {
@@ -202,7 +202,7 @@ function reportFor(field, value, source) {
                 field,
                 value,
                 support: 'refused',
-                note: `\`smith new --ui\` refuses: the UI template wires plain CSS or Tailwind, not ${value}.`,
+                note: `\`bs new --ui\` refuses: the UI template wires plain CSS or Tailwind, not ${value}.`,
             };
     }
     if (field === 'design_system') {
@@ -242,7 +242,7 @@ function reportFor(field, value, source) {
                 field,
                 value,
                 support: 'refused',
-                note: `design_system_source ${source} does not exist, so \`smith new --ui\` would vendor nothing while claiming ${value}.`,
+                note: `design_system_source ${source} does not exist, so \`bs new --ui\` would vendor nothing while claiming ${value}.`,
             };
     }
     const hardcoded = HARDCODED[field];
@@ -258,7 +258,7 @@ function reportFor(field, value, source) {
                 field,
                 value,
                 support: 'recorded',
-                note: `The templates hardcode ${hardcoded.value} in ${hardcoded.where}. The agents read ${value}; \`smith new\` still scaffolds ${hardcoded.value}.`,
+                note: `The templates hardcode ${hardcoded.value} in ${hardcoded.where}. The agents read ${value}; \`bs new\` still scaffolds ${hardcoded.value}.`,
             };
     }
     return {

package/factory/orchestrator/dist/storeRoot.js

@@ -0,0 +1,90 @@
+/**
+ * Where a project's Blacksmith store lives, found from a working directory.
+ *
+ * Shared by the dashboard's store registry and the orchestrator's own tools, so
+ * "is this checkout a store" has one answer. Read-only: nothing here creates or
+ * writes a file.
+ */
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import path from 'node:path';
+const isDir = (p) => {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+};
+const realOr = (p) => {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+};
+/**
+ * Where a `.git` file (a linked worktree) really leads: the main clone, but
+ * only when that clone's `.git/worktrees/<name>` exists as a directory and is
+ * the very place the pointer names. A pointer is text anyone can write, so it
+ * is not trusted on its own; otherwise the worktree itself is the top.
+ */
+export function mainCloneOf(dotGitFile, dir) {
+    try {
+        const gitdir = /^gitdir:\s*(.+)$/m.exec(readFileSync(dotGitFile, 'utf8'))?.[1]?.trim();
+        if (!gitdir)
+            return dir;
+        const target = path.resolve(dir, gitdir);
+        const marker = `${path.sep}.git${path.sep}worktrees${path.sep}`;
+        const at = target.indexOf(marker);
+        if (at <= 0)
+            return dir;
+        const top = target.slice(0, at);
+        const name = target.slice(at + marker.length);
+        if (name === '' || name.includes(path.sep))
+            return dir;
+        const entry = path.join(top, '.git', 'worktrees', name);
+        if (!isDir(path.join(top, '.git')) || !isDir(entry))
+            return dir;
+        return realpathSync(entry) === realpathSync(target) ? top : dir;
+    }
+    catch {
+        // Unreadable or dangling pointer: treat the worktree itself as the top.
+        return dir;
+    }
+}
+/**
+ * The git toplevel above `start`, or null. A `.git` directory marks a clone; a
+ * `.git` file (a linked worktree) is followed to the main clone, because the
+ * state home belongs to the project, not to one checkout of it.
+ */
+export function gitTop(start) {
+    let dir = path.resolve(start);
+    for (;;) {
+        const dotGit = path.join(dir, '.git');
+        if (isDir(dotGit))
+            return dir;
+        if (existsSync(dotGit))
+            return mainCloneOf(dotGit, dir);
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/**
+ * A real store marker: `state/events` is a directory that lives inside `root`,
+ * not a file and not a link leading out of the tree.
+ */
+export function hasEvents(root) {
+    const events = path.join(root, 'state', 'events');
+    return isDir(events) && realOr(events) === path.join(realOr(root), 'state', 'events');
+}
+/** `<top>/.blacksmith` first (a BS_HOME layout), else `<top>` itself (a clone). */
+export function storeRootAt(top) {
+    for (const root of [path.join(top, '.blacksmith'), top]) {
+        if (hasEvents(root))
+            return { root, label: path.basename(top) };
+    }
+    return null;
+}