@juzser/blacksmith 0.3.0 → 0.4.0

package/.claude/agents/auditor.md

@@ -5,6 +5,9 @@ model: sonnet
 effort: high
 tools: Read, Grep, Glob, Bash
 maxTurns: 15
+hooks:
+  Stop:
+    - hooks: [{type: command, command: "[ -f \"$CLAUDE_PROJECT_DIR/.claude/hooks/judge-stop.sh\" ] && \"$CLAUDE_PROJECT_DIR/.claude/hooks/judge-stop.sh\" || exit 0"}]
 ---
 
 # Auditor

package/.claude/agents/grader.md

@@ -5,6 +5,9 @@ model: sonnet
 effort: low
 tools: Read, Grep, Glob, Bash
 maxTurns: 15
+hooks:
+  Stop:
+    - hooks: [{type: command, command: "[ -f \"$CLAUDE_PROJECT_DIR/.claude/hooks/judge-stop.sh\" ] && \"$CLAUDE_PROJECT_DIR/.claude/hooks/judge-stop.sh\" || exit 0"}]
 ---
 
 # Grader
@@ -43,7 +46,9 @@ edit does not save a round-trip, it costs the whole one.
   rubric — nothing broader.
 - Bounce back to the worker with specific, itemized gaps (not vibes).
 - **Max 2 rounds.** After that, pass whatever exists through to the gates —
-  the gates, not the grader, decide final pass/fail.
+  the gates, not the grader, decide final pass/fail. The re-scope path after a
+  round-2 `fail` is `.claude/skills/bs/dispatch.md`'s "Round counting and
+  escalation" — read it there rather than here.
 - Grader never edits code and never talks to the operator.
 - **Never compact your context** (`budgets.yml` `context_window`,
   `narrowing_roles`). You grade evidence rather than build on it; a
@@ -101,10 +106,12 @@ harness counts the tokens; the dispatcher stamps them.
 {"status": "done", "overall": "fail", "round": 2, "artifact_path": "state/results/<task-id>.grader-r2.json"}
 ```
 
-Two rounds is a hard stop, not a suggestion. A `fail` at round 2 goes back to
-the planner for re-scoping; you do not open round 3, and you do not soften the
-verdict to avoid the stop. The schema caps `round` at 2, so a round-3 file
-does not quietly pass the gate — it blocks it as invalid.
+Two rounds is a hard stop, not a suggestion. A `fail` at round 2 is re-scoped
+through dispatch.md's "Round counting and escalation" (plan propose/approve a
+successor task id, then `worktree create --from`); you do not open round 3 on
+this id, and you do not soften the verdict to avoid the stop. The schema caps
+`round` at 2, so a round-3 file does not quietly pass the gate — it blocks it
+as invalid.
 
 ## What the gate does with this file
 

package/.claude/agents/reviewer.md

@@ -5,6 +5,9 @@ model: sonnet
 effort: medium
 tools: Read, Grep, Glob, Bash
 maxTurns: 15
+hooks:
+  Stop:
+    - hooks: [{type: command, command: "[ -f \"$CLAUDE_PROJECT_DIR/.claude/hooks/judge-stop.sh\" ] && \"$CLAUDE_PROJECT_DIR/.claude/hooks/judge-stop.sh\" || exit 0"}]
 ---
 
 # Reviewer

package/.claude/agents/security-reviewer.md

@@ -5,6 +5,9 @@ model: sonnet
 effort: high
 tools: Read, Grep, Glob, Bash
 maxTurns: 15
+hooks:
+  Stop:
+    - hooks: [{type: command, command: "[ -f \"$CLAUDE_PROJECT_DIR/.claude/hooks/judge-stop.sh\" ] && \"$CLAUDE_PROJECT_DIR/.claude/hooks/judge-stop.sh\" || exit 0"}]
 ---
 
 # Security Reviewer

package/.claude/agents/spec-reviewer.md

@@ -5,6 +5,9 @@ model: sonnet
 effort: high
 tools: Read, Grep, Glob, Bash
 maxTurns: 15
+hooks:
+  Stop:
+    - hooks: [{type: command, command: "[ -f \"$CLAUDE_PROJECT_DIR/.claude/hooks/judge-stop.sh\" ] && \"$CLAUDE_PROJECT_DIR/.claude/hooks/judge-stop.sh\" || exit 0"}]
 ---
 
 # Spec Reviewer

package/.claude/agents/verifier.md

@@ -5,6 +5,9 @@ model: opus
 effort: xhigh
 tools: Read, Grep, Glob, Bash
 maxTurns: 15
+hooks:
+  Stop:
+    - hooks: [{type: command, command: "[ -f \"$CLAUDE_PROJECT_DIR/.claude/hooks/judge-stop.sh\" ] && \"$CLAUDE_PROJECT_DIR/.claude/hooks/judge-stop.sh\" || exit 0"}]
 ---
 
 # Verifier

package/.claude/skills/bs/audit.md

@@ -254,8 +254,15 @@ is already gone closes with `verified: false` and no refusal.
 The epic is now an ordinary roadmap milestone: run `/bs plan` on it
 ([`plan.md`](plan.md)), then `/bs run`. When that run reaches its epic-close
 step, it runs
-`smith audit resolve <project-dir> --epic <epic-id> --session <session-id> --causal-parent <event-id>`,
-which appends `fixed` for every finding the epic carried — repeatable, and
-`audit.unknown-epic` if the id was never cut from this store. That is the
-only step of an audit that runs outside this playbook, and it is why the
-store, not this transcript, is where a finding's life is kept.
+`smith audit resolve <project-dir> --epic <epic-id> --session <session-id> --causal-parent <event-id> [--specs-dir <dir>]`,
+which reads the epic's newest plan and appends `fixed` only for a carried
+finding some task in it still claims — the rest come back `deferred`, still
+`accepted`, because the plan scoped them out on purpose. Repeatable;
+`audit.unknown-epic` if the id was never cut from this store, `audit.no-plan`
+if no plan can be found (refuses rather than guess). The default search is
+the work root's specs dir; when this project's plans live elsewhere, pass
+`--specs-dir` naming the same specs dir the epic was run from. `--except
+<fp[,fp...]>` forces specific fingerprints into `deferred` even when a task
+claims them. That is the only step of an audit that runs outside this
+playbook, and it is why the store, not this transcript, is where a finding's
+life is kept.

package/.claude/skills/bs/dispatch.md

@@ -25,6 +25,16 @@ it. `smith agents sync` may have rewritten it locally from
 `SMITH_MAXTURNS_<ROLE>` (an uncommitted, per-box edit), and Claude Code
 enforces what the file says. A sync reaches only agents spawned after it.
 
+State it on its own line, verbatim — `Turn budget: 40` — and, on a judge
+dispatch, the declared-artifact line below verbatim too. `smith dispatch
+lint <prompt-file> --role <role> --task <id> --session <id>` reads a
+composed prompt back and checks both against the template and the ledger,
+before the agent ever runs. It fails closed: a number that does not match
+the template — higher (the promise-more-than-the-template mistake above) or
+lower — a missing turn-budget line, a template it cannot read at all, and a
+judge prompt missing or mismatching its artifact line are each a lint
+failure, not a maybe.
+
 ## Splice the compiled lessons into every prompt (agent-interviews.md N-9, P9-2)
 
 Before you dispatch, run
@@ -151,10 +161,30 @@ memory of its previous attempt and will happily report round 1 forever.
   reason). An unlogged escalation is a cost you cannot attribute later — and
   `model_tier` alone cannot even tell you *which* frontier model you escalated
   to, since opus and fable share the tier.
-- **The grader's 2-round cap is a hard stop, not a ladder rung.** At a round-2
-  `fail` the task goes back to the planner for re-scoping. Do not re-dispatch
-  the grader, and do not escalate the *grader* — the gates decide pass/fail,
-  and a third grading round only buys a more expensive opinion.
+- **The grader's 2-round cap is a hard stop, not a ladder rung.** At a
+  round-2 `fail` the operator re-scopes through a concrete, logged path, not
+  a bare re-dispatch:
+  1. `smith plan propose` with a `supersede` pairing the failing task id to a
+     new one (`PlanChanges.supersede`, spec.ts's `amendPlan`) — the operator
+     approves the re-scoping, this command only records the proposal.
+  2. `smith plan approve` the proposed version. This is what writes the
+     `successors{old->new}` pairing (spec.ts's `taskSuccessors`) that
+     everything below checks against.
+  3. `smith worktree create --from <old-task-id> --session <id> ...` to cut
+     the successor's branch from the predecessor's HEAD instead of
+     integration — refused as `worktree.not-a-successor` unless step 2 logged
+     that exact pairing.
+  4. Rerun wave steps 5-7 (dispatch, review, gate) under the new task id. The
+     grader starts that id at round 1 — the ledger's round counter is per
+     `(task_id, role)`, and a new id has never opened a round.
+  5. Gate with `--plan` naming the new plan version.
+
+  A same-id re-dispatch of round 3 is never legal, superseded or not: the cap
+  binds the id, and a kept-id supersede (same task_id, new claims/criteria)
+  does not reset the round either — only a **new** task id starts a fresh
+  ledger. Do not re-dispatch the grader on the old id, and do not escalate the
+  *grader* — the gates decide pass/fail, and a third grading round on the same
+  id only buys a more expensive opinion.
 - **Never escalate a judge to break a tie with another judge.** That is what
   the cross-check quorum is for (`crosscheck.yml`); a bigger critic is still
   one critic.
@@ -324,6 +354,12 @@ true one on the record. `--no-findings` records an operator
 *attestation* rather than a review — use it only for a judge that ran outside
 the factory; a judge that genuinely found nothing writes `[]` and reports.
 
+Tell the judge the exact path on its own line, verbatim —
+`Declared artifact: /abs/path/<task-id>.reviewer.json` — the spelling `smith
+dispatch lint` checks the composed prompt against once the dispatch above
+has landed in the ledger. Missing, relative, or a path that does not match
+what `--artifact` declared are each a lint failure, not a maybe.
+
 ## Dispatching the security-reviewer (agent-interviews.md N-7)
 
 Do not eyeball the path list — ask:

package/.claude/skills/bs/plan.md

@@ -44,7 +44,26 @@ there means "not looked at", not "looked at and clean".
    — a *different model* than the planner's, per its own frontmatter — to
    hunt spec gaps/ambiguities/missing-nonfunctional clauses
    (`docs/standards/agent-constraints.md` "planner"; `severity.yml`: most
-   spec gaps land S2, blocking sign-off).
+   spec gaps land S2, blocking sign-off). Name the review focus in the
+   dispatch itself, as a short list of at most six items, so findings come
+   back tagged to one of them:
+
+   1. Claims and dependency edges, cross-checked against
+      `smith claims impact`.
+   2. TDD-ability -- a named failing test per task, before its code.
+   3. Nonfunctional and security clauses.
+   4. Budget and diff-cap fit.
+   5. Acceptance-criterion coverage -- every epic criterion maps to a task.
+   6. From round 2 on, only the previous round's findings plus any task
+      that changed since then.
+
+   When `size.small` reads true on the draft (`smith wave schedule` or
+   `smith plan ingest`'s `parallelism.size`, run against the draft plan
+   file), recommend effort tier `small` -- single-pass spec review -- to
+   the operator unless a security trigger floors it first, and say why in
+   the same message: a plan that cannot spread past a few tasks and a
+   handful of claim paths does not need a second review round to find what
+   one pass already covers.
 4. Planner fixes flagged issues; repeat 2–3 until the spec-reviewer has
    nothing S1/S2 left — or exactly once when `profile.specReviewRounds` is
    `single-pass` (`small`), where the planner fixes what came back and
@@ -127,6 +146,11 @@ there means "not looked at", not "looked at and clean".
    decide whether to re-slice, and say which you chose when you present the
    plan.
 
+   The same JSON also carries `size` -- `{tasks, claims, small}` over live
+   tasks only -- the block `plan ingest` prints again under `parallelism`
+   at step 7; `small` is true at or under 3 live tasks and 10 distinct
+   claim paths, and this is where the step 3 tier read gets confirmed.
+
    Beside the schedule, the read that names what it only counts:
 
    ```bash
@@ -163,6 +187,14 @@ there means "not looked at", not "looked at and clean".
    UI check found behind two epics. It is idempotent, so run it again on a
    resumed session; read `added` and `edges` back, and say so when either is
    0 on a plan that has tasks or edges.
+
+   Read `parallelism.widest` back from that same output, too. `parallel_with`
+   underneath it is claims-and-edges only -- import-graph crossings stay
+   `wave schedule --repo`'s job, not this key's -- so it can only ever name
+   a width that job would not contradict. A `widest` of 1 on a
+   plan of two or more tasks means every task the wave loop will ever run
+   sits behind some claim or edge that serializes it: flag that to the
+   operator now, before a run discovers it as a stalled wave.
 8. If this epic opens a new roadmap milestone, add it to
    `factory/specs/roadmap.md` (planner-maintained, architecture §12) — a
    roadmap change is itself a scope change and needs the same operator nod.

package/.claude/skills/bs/run.md

@@ -123,8 +123,9 @@ under it, which is the wrong `--state-dir`, or a wave session opened without
 done; a green gate on serialized work is exactly the outcome the two
 playbooks are written to prevent.
 
-11. Repeat until every task in the live plan version is
-    `completed`/`superseded`/`waived`. Dispatch the **`planner`** again for
+11. Repeat until every task in the live plan version is `completed`/`waived`,
+    or `superseded` by a successor that is itself terminal-OK (recursively —
+    a successor chain counts too). Dispatch the **`planner`** again for
     the epic verdict against acceptance criteria — gaps found → a NEW
     `plan-v(n+1)` with inferred tasks (never a live-graph mutation,
     architecture §12), auto-scheduled at confidence ≥0.8 else parked for an
@@ -292,9 +293,14 @@ playbooks are written to prevent.
     yourself** — closing over a hold is the operator's call; ask for it and
     quote the blockers. If the epic was cut by `/bs audit`
     ([`audit.md`](audit.md) step 10), follow the close with
-    `smith audit resolve <project-dir> --epic <epic> --session <session-id> --causal-parent <event-id>`
-    so every finding the epic carried is marked `fixed` in the project's
-    audit store — the store, not the epic, is where a finding's life ends.
+    `smith audit resolve <project-dir> --epic <epic> --session <session-id> --causal-parent <event-id> [--specs-dir <dir>]`
+    so every finding this plan still claims is marked `fixed` in the
+    project's audit store — the rest come back `deferred`, left exactly as
+    they were, because the plan scoped them out on purpose. The store, not
+    the epic, is where a finding's life ends. `resolve` reads the epic's
+    newest plan from the work root's specs dir by default; when this
+    project's plans live elsewhere, pass `--specs-dir` naming the same specs
+    dir the epic was run from, or it refuses rather than guess.
 17. Open **one integration PR per epic** with the scribe-written body
     (`/bs report`'s playbook, [`report.md`](report.md)) — screenshots, test
     results, reviewer verdict, waivers granted, timeline link. The head is

package/.claude/skills/bs/wave.md

@@ -147,6 +147,28 @@ one thing this playbook never asks you to.
    carries `keeps_exports`, restate the promise in the dispatch in one line:
    the file list, and "keep every existing export's name and declaration;
    adding is fine".
+
+   Once every coder of the wave has been dispatched — this fan-out has gone
+   out for every admitted task — audit the wave's own parallelism while it
+   can still be corrected: `smith wave audit --session <id> --epic <epic>`.
+   `wave check` is the step-1 gate that certified, before any dispatch, that
+   these tasks could run together; `wave audit` reads the log back after
+   dispatch and says whether they did.
+   It is a read, so it costs nothing against "No lockstep barrier" above and
+   waits for no task. Read the `verdict` field (`WAVE_VERDICTS`,
+   `waveConcurrency.ts`), not only the exit code — `partial` also exits 0:
+   - `serialized` or `partial` — the wave is not running the width it was
+     admitted at, and steps 5–7 have not gone out yet, so it can still be
+     fixed: dispatch every remaining phase of this wave as one message of
+     parallel calls, per "One message, many dispatches" above, and record
+     the verdict as an operator-visible event — `error-logged` with error
+     `contract.constraint-decay` (`taxonomy.yml`): the wave-runner stopped
+     honoring that section's standing constraint.
+   - `unobserved` — the log holds no dispatch for any task this wave
+     admitted. That is a defect in the log, not in how the wave ran; record
+     it the same way, as `error-logged` with error `execution.env-failure`.
+   - `parallel` or `single` — nothing further; the wave ran as wide as it
+     was admitted.
 5. Dispatch **`tester`** (`.claude/agents/tester.md`) for missing unit
    coverage and epic-level e2e/screenshots.
    - Then the **uiux visual pass**, but only when all three hold: the task
@@ -164,7 +186,8 @@ one thing this playbook never asks you to.
    runs; it never decides pass/fail itself. At one round the grader scores
    once and a failed criterion is the coder's bounce, not a re-grade. Its result file is an **input to
    step 7**, not a note to the operator: pass it as `--grader` or the rubric
-   gates nothing (D-34).
+   gates nothing (D-34). A round-2 `fail` re-scopes via dispatch.md's "Round
+   counting and escalation", not a round 3 on this id.
 7. Run the gate pipeline:
    `smith gate run <task-id> --worktree <dir> --checks checks.json --result
    result.json --grader state/results/<task-id>.grader-r<round>.json
@@ -238,8 +261,18 @@ one thing this playbook never asks you to.
    — see "Round counting and escalation" above. Then have the log check
    you: `smith escalation check <session-id> --task <task-id>`, which
    exits 1 if the rung you just climbed is not evidenced.
-10. Gate outcome `pass`/`pass-with-waivers-pending` → before admitting,
-    ask what the diff did to everyone outside the claims, and whether it
+10. Gate outcome `pass`/`pass-with-waivers-pending` → before admitting, audit
+    the wave's own parallelism: `smith wave audit --session <id> --epic
+    <epic>`. It reads the log back and says whether the tasks admitted
+    together actually ran together — `parallel` when every admitted task was
+    in flight at once, `partial` when two or more overlapped but never all,
+    `serialized` when work is recorded but no two tasks ever overlapped,
+    `single` when the wave admitted one task (nothing to be parallel about),
+    and `unobserved` when the wave was admitted and the log shows no work for
+    any of its tasks. Exit 1 on `serialized`, exit 2 on `unobserved` — either
+    is a fact for the wave-loop's hand-back, not a reason to hold the merge:
+    report the verdict and keep going to admission. Then ask what the diff
+    did to everyone outside the claims, and whether it
     kept what the spec promised:
     `smith claims impact <worktree-dir> <spec.json>`. Exit 1 means a
     `proven` break — this task removed an export a file outside its claims
@@ -271,6 +304,10 @@ one thing this playbook never asks you to.
     auto-resolve a semantic conflict silently (`worktree.yml`
     `conflict_resolution_ladder`).
 
+    An `integration-dirty` outcome names a `worktree` holding
+    `smith/<epic>/integration` with uncommitted tracked changes (`dirty`):
+    commit or stash those there, then re-run `smith queue run`.
+
     Once the wave is merged, check the epic's spend — `smith budget alarm
     <session-id> [--epic <epic>]`. Exit 1 means either the epic crossed
     `alarm_ratio` (re-plan the remaining work to fit, or ask the operator —

package/README.md

@@ -391,7 +391,7 @@ runbook is written; the hosted UI stays deferred. Beside the phases, `/bs audit`
 is built: an existing project can be read on four axes and one epic cut from
 what you accept.
 
-The CLI is on npm as `@juzser/blacksmith`, at `0.3.0` — two binaries,
+The CLI is on npm as `@juzser/blacksmith`, at `0.4.0` — two binaries,
 `smith` and `smith-run`, the second (since `0.2.0`) being what runs a
 rendered turn on a `cli` harness such as Codex. `0.1.1` was the first version that ran beside
 you and knew it was a package, rather than out of the clone-shaped install

package/factory/orchestrator/dist/agentsSync.js

@@ -54,6 +54,29 @@ function findMaxTurns(text, file) {
 function withMaxTurns(text, site, value) {
     return `${text.slice(0, site.from)}${value}${text.slice(site.to)}`;
 }
+/**
+ * The template's current `maxTurns:`, read fresh from disk — never cached,
+ * because `smith agents sync` may have rewritten the file since the caller
+ * last looked. Unlike `findMaxTurns`, this never throws: a role with no
+ * template, or a template with no `maxTurns:` line, is "cannot verify" for a
+ * caller like dispatchLint.ts, not a hard failure.
+ */
+export function readTemplateMaxTurns(agentsDir, role) {
+    const file = path.join(agentsDir, `${role}.md`);
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        return findMaxTurns(text, file).value;
+    }
+    catch {
+        return undefined;
+    }
+}
 function positiveInt(name, raw) {
     const value = /^[0-9]+$/.test(raw) ? Number(raw) : Number.NaN;
     if (!Number.isSafeInteger(value) || value <= 0) {

package/factory/orchestrator/dist/audit.js

@@ -32,11 +32,15 @@
 import { randomBytes } from 'node:crypto';
 import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, } from 'node:fs';
 import path from 'node:path';
+import { resolveFindingOwner } from './claims.js';
 import { SmithError } from './errors.js';
 import { appendEvent } from './events.js';
 import { computeFingerprint, normalizeFilePath } from './findings.js';
 import { runGit } from './git.js';
 import { checkWorktreeImmutable, fingerprintWorktree, } from './immutability.js';
+import { isFactoryCheckout, SPECS_ACTIVE_DIR } from './paths.js';
+import { latestPlanVersion, loadPlan, planClaimedTasks, } from './plan.js';
+import { defaultKindFor, FACTORY_PROJECT } from './roadmap.js';
 import { loadTaxonomy } from './taxonomy.js';
 export class AuditError extends SmithError {
 }
@@ -251,11 +255,31 @@ export function foldAuditStore(lines, opts = {}) {
  * The fingerprints an axis may not raise again. This is the whole of the
  * dedupe half of §3.1 — `audit record` drops what this names and appends the
  * rest.
+ *
+ * Each suppressing finding contributes two fingerprints, not one. Its
+ * stored `finding.fingerprint` is whatever `computeFingerprint` produced
+ * *when the line was written* — widening that normalizer (issue #178) does
+ * not rewrite `findings.jsonl`, so a decline recorded before a normalizer
+ * fix keeps its old hash forever. The raised line still carries its own
+ * `file_path`/`axis`/`summary`, so recomputing the fingerprint with today's
+ * normalizer costs nothing and lets a pre-existing decline suppress a
+ * re-raise that only differs in what the new normalizer now strips — no
+ * store rewrite, no migration. When the stored hash and the recomputed one
+ * already agree (the common case), the second `add` is a no-op.
  */
 export function suppressedFingerprints(lines, opts = {}) {
-    return new Set(foldAuditStore(lines, opts)
-        .filter((finding) => finding.suppressesReraise)
-        .map((finding) => finding.fingerprint));
+    const set = new Set();
+    for (const finding of foldAuditStore(lines, opts)) {
+        if (!finding.suppressesReraise)
+            continue;
+        set.add(finding.fingerprint);
+        set.add(computeFingerprint({
+            filePath: finding.file_path,
+            category: finding.axis,
+            summary: finding.summary,
+        }));
+    }
+    return set;
 }
 function clusterOf(filePath, findings) {
     const members = findings.filter((finding) => finding.status !== 'merged');
@@ -398,6 +422,39 @@ function mintAuditId(now) {
     const day = now.toISOString().slice(0, 10).replaceAll('-', '');
     return `${day}-${randomBytes(4).toString('hex')}`;
 }
+/**
+ * The name an audit calls `project` by, everywhere one is needed: the
+ * event's `project` field, the cut milestone's `- project:` line and goal
+ * sentence, and the cut spec's Project line.
+ *
+ * `path.basename(project)` names every OTHER project correctly, but this
+ * clone's own directory is not always named FACTORY_PROJECT
+ * (`black-smith`) -- roadmap.ts's own note documents the real `black-smith`/
+ * `blacksmith` siblings this factory was built beside -- so a self-audit that
+ * used the basename wrote a name `collectProjects()` (projects.ts) had never
+ * seen, sent it looking for a checkout under this clone's own parent, and it
+ * found this very clone: registered a second time as a foreign, non-self ref
+ * that `--no-self` could not filter. Comparing against REPO_ROOT, resolved
+ * the same way `unwatchedProjects` (projects.ts) already does, is what tells
+ * "this clone, filed under its own directory name" from "a project that is
+ * genuinely named that".
+ */
+export function auditedProjectName(project) {
+    return isFactoryCheckout(project) ? FACTORY_PROJECT : path.basename(project);
+}
+/**
+ * The `- kind:` a cut milestone declares alongside auditedProjectName's
+ * `- project:` line. roadmap.ts's own parser fixes the two together
+ * (`roadmap.factory-kind-fixed`): a milestone naming FACTORY_PROJECT must be
+ * kind "factory", never "product". A cut that named a self-audit
+ * FACTORY_PROJECT but still wrote a hard-coded "product" kind would stamp a
+ * milestone that fails to parse the moment `loadRoadmap()` reads it back, so
+ * this feeds auditedProjectName's own answer through roadmap.ts's
+ * defaultKindFor rather than re-deriving it separately.
+ */
+export function auditedProjectKind(project) {
+    return defaultKindFor(auditedProjectName(project));
+}
 /**
  * The audit's events are ordinary events on the operator's session, stamped
  * with the project's name so the multi-project timeline can tell whose audit
@@ -412,7 +469,7 @@ function emit(eventType, project, ctx, opts, payload) {
         event_type: eventType,
         plan_version: ctx.planVersion,
         causal_parent: ctx.causalParent,
-        project: path.basename(project),
+        project: auditedProjectName(project),
         payload,
     }, opts);
 }
@@ -635,7 +692,7 @@ function cite(finding) {
 function renderMilestone(input, project, findings) {
     const audits = auditIdsOf(findings);
     const goal = [
-        `Cut from audit ${audits.join(', ')} of \`${path.basename(project)}\` (${findings.length} accepted finding${findings.length === 1 ? '' : 's'}: ${severityCounts(findings)}).`,
+        `Cut from audit ${audits.join(', ')} of \`${auditedProjectName(project)}\` (${findings.length} accepted finding${findings.length === 1 ? '' : 's'}: ${severityCounts(findings)}).`,
         'Each finding below is one acceptance criterion; the plan decides the tasks.',
         ...findings.map((finding) => `${cite(finding)}.`),
     ].join(' ');
@@ -644,8 +701,8 @@ function renderMilestone(input, project, findings) {
         `- id: ${input.epicId}`,
         '- status: planned',
         `- epics: [${input.epicId}]`,
-        `- project: ${path.basename(project)}`,
-        '- kind: product',
+        `- project: ${auditedProjectName(project)}`,
+        `- kind: ${auditedProjectKind(project)}`,
         `- goal: ${goal}`,
         '',
     ].join('\n');
@@ -673,9 +730,9 @@ function renderSpec(input, project, findings) {
         `# Epic spec — \`${input.epicId}\``,
         '',
         `- **Epic id** — \`${input.epicId}\``,
-        `- **Project** — \`${path.basename(project)}\` at \`${project}\`, and every worktree is placed beside that clone (\`AGENTS.md\` "Worktrees").`,
+        `- **Project** — \`${auditedProjectName(project)}\` at \`${project}\`, and every worktree is placed beside that clone (\`AGENTS.md\` "Worktrees").`,
         `- **Roadmap milestone** — \`${input.epicId}\` in \`factory/specs/roadmap.md\`.`,
-        `- **Provenance** — cut by \`smith audit cut\` from audit ${audits.join(', ')} (${findings.length} accepted finding${findings.length === 1 ? '' : 's'}: ${severityCounts(findings)}). Each finding carries this epic id in \`.blacksmith/findings.jsonl\`; \`smith audit resolve\` marks them fixed when the epic closes.`,
+        `- **Provenance** — cut by \`smith audit cut\` from audit ${audits.join(', ')} (${findings.length} accepted finding${findings.length === 1 ? '' : 's'}: ${severityCounts(findings)}). Each finding carries this epic id in \`.blacksmith/findings.jsonl\`; \`smith audit resolve\` marks fixed only the ones a task in this plan still claims, and leaves the rest \`deferred\`.`,
         '',
         '## What this epic is',
         '',
@@ -734,24 +791,83 @@ export async function cutAudit(projectDir, input, ctx, opts = {}) {
     };
 }
 /**
- * `audit resolve <project-dir> --epic <epic-id>`. Appends a `fixed` line for
- * every finding the epic carried. Called from `/bs run`'s epic-close step, so
- * it is repeatable; an epic no finding carries is refused, because the likely
- * cause is a typo and a silent no-op would leave every finding open.
+ * The epic's newest plan, however `resolveOpts` asks for it found. Refuses
+ * rather than guesses: `resolveAudit` must never treat "I could not find a
+ * plan" as "nothing is claimed", because that reading marks every carried
+ * finding fixed.
+ */
+function resolveEpicPlan(epicId, resolveOpts) {
+    if (resolveOpts.plan !== undefined)
+        return resolveOpts.plan;
+    const planOpts = resolveOpts.planOpts ?? {};
+    const version = latestPlanVersion(epicId, planOpts);
+    if (version === null) {
+        const searchedDir = path.join(planOpts.specsDir ?? SPECS_ACTIVE_DIR, epicId);
+        throw new AuditError('audit.no-plan', `no plan found for epic ${epicId}: \`audit resolve\` only marks a finding fixed when some plan task claims its file, so a missing plan cannot be treated as an empty one. Searched ${searchedDir}. If this epic's plans live elsewhere, pass --specs-dir <dir> naming the directory they live in, or --plan <plan.json> to point at one directly.`, { epic: epicId });
+    }
+    return loadPlan(epicId, version, planOpts);
+}
+/**
+ * `--except` entries against the epic's carried fingerprints, full or a
+ * unique prefix — the same latitude other audit verbs give a fingerprint
+ * argument. A value that matches nothing is refused as a likely typo (same
+ * spirit as `audit.unknown-epic`); one whose prefix matches more than one
+ * carried fingerprint is refused rather than guessed.
+ */
+function matchExceptFingerprints(except, carried, epicId) {
+    const known = carried.map((finding) => finding.fingerprint);
+    const matched = new Set();
+    for (const value of except) {
+        if (known.includes(value)) {
+            matched.add(value);
+            continue;
+        }
+        const candidates = known.filter((fingerprint) => fingerprint.startsWith(value));
+        if (candidates.length === 1) {
+            matched.add(candidates[0]);
+            continue;
+        }
+        if (candidates.length > 1) {
+            throw new AuditError('audit.ambiguous-except', `--except ${value} matches ${candidates.length} findings epic ${epicId} carries: ${candidates.join(', ')}`, { epic: epicId, value, candidates });
+        }
+        throw new AuditError('audit.unknown-finding', `--except ${value} matches no finding epic ${epicId} carries`, { epic: epicId, value });
+    }
+    return matched;
+}
+/**
+ * `audit resolve <project-dir> --epic <epic-id>`. Appends a `fixed` line only
+ * for a carried finding some task in the epic's newest plan still claims
+ * (`resolveFindingOwner`, D-41/P9-24) — an operator who scoped the plan
+ * narrower than the audit deferred the rest on purpose, and marking them
+ * fixed anyway would erase that choice. Unclaimed findings stay exactly as
+ * they were and come back in `deferred`; `--except` forces specific
+ * fingerprints there even when a task claims them. Called from `/bs run`'s
+ * epic-close step, so it is repeatable; an epic no finding carries is
+ * refused, because the likely cause is a typo and a silent no-op would leave
+ * every finding open. A plan that cannot be found is refused too
+ * (`audit.no-plan`): being unsure must never mark anything fixed.
  */
-export async function resolveAudit(projectDir, epicId, ctx, opts = {}) {
+export async function resolveAudit(projectDir, epicId, ctx, opts = {}, resolveOpts = {}) {
     const project = path.resolve(projectDir);
     const carried = foldAuditStore(readAuditStore(project)).filter((finding) => finding.epic === epicId);
     if (carried.length === 0) {
         throw new AuditError('audit.unknown-epic', `no finding in ${auditStorePath(project)} carries epic ${epicId}: was it cut with \`smith audit cut\`?`, { epic: epicId });
     }
     const open = carried.filter((finding) => finding.status !== 'fixed');
+    const plan = resolveEpicPlan(epicId, resolveOpts);
+    const claimedTasks = planClaimedTasks(plan);
+    const except = matchExceptFingerprints(resolveOpts.except ?? [], carried, epicId);
+    const toFix = open.filter((finding) => !except.has(finding.fingerprint) &&
+        resolveFindingOwner(finding.file_path, claimedTasks).owner !== 'unclaimed');
+    const toFixFingerprints = new Set(toFix.map((finding) => finding.fingerprint));
+    const deferred = open.filter((finding) => !toFixFingerprints.has(finding.fingerprint));
     const stored = await emit('audit-resolved', project, ctx, opts, {
         epic: epicId,
-        fixed: open.map((finding) => finding.fingerprint),
+        fixed: toFix.map((finding) => finding.fingerprint),
+        deferred: deferred.map((finding) => finding.fingerprint),
     });
     const ts = new Date().toISOString();
-    appendAuditLines(project, open.map((finding) => ({
+    appendAuditLines(project, toFix.map((finding) => ({
         fingerprint: finding.fingerprint,
         status: 'fixed',
         ts,
@@ -761,10 +877,11 @@ export async function resolveAudit(projectDir, epicId, ctx, opts = {}) {
     })));
     return {
         epic: epicId,
-        fixed: open.map((finding) => finding.fingerprint),
+        fixed: toFix.map((finding) => finding.fingerprint),
         already: carried
             .filter((finding) => finding.status === 'fixed')
             .map((finding) => finding.fingerprint),
+        deferred: deferred.map((finding) => finding.fingerprint),
         event_id: stored.event_id,
     };
 }

package/factory/orchestrator/dist/autonomy.js

@@ -79,11 +79,15 @@ function securityFields(proposal, ctx) {
         case 'growth-review-due':
             return [];
         case 'error-report':
-            // Refused ahead of the keyword match; listed so the switch stays exhaustive.
+            // Refused ahead of the keyword match (see classify() below); listed so
+            // the switch stays exhaustive. proposal.project is only ever null when
+            // errorIssues.ts's fail-closed fold could not resolve one, which this
+            // branch never actually returns for -- see classify()'s early
+            // 'tracker-write-never-auto' refusal for every 'error-report' kind.
             return [
                 { field: 'task ref', value: proposal.taskRef },
                 { field: 'error class', value: proposal.errorClass },
-                { field: 'project', value: proposal.project },
+                { field: 'project', value: proposal.project ?? '(unresolved)' },
             ];
     }
 }