@juzser/blacksmith 0.4.0 → 0.5.0

package/factory/policies/lessons.md

@@ -81,8 +81,8 @@ select on. Each names its own bullet, validated against `taxonomy.yml`:
 At dispatch, an `agent-role` entry reaches only the role its `agent_role`
 names, and a `case-type` entry only a task whose `case` its `case_type`
 names. An entry in one of those scopes with **no** selector reaches NOBODY —
-it is inert, not universal, and `smith lessons for-dispatch` reports it as
-such. `smith lessons raise` refuses to mint one; the entries that predate
+it is inert, not universal, and `bs lessons for-dispatch` reports it as
+such. `bs lessons raise` refuses to mint one; the entries that predate
 the selector (D-129) are the only ones that can still be in that state.
 
 Two kinds of entry are therefore injected at dispatch and still never
@@ -124,6 +124,26 @@ nothing.
 - agent_role: planner
 - statement: An acceptance criterion that probes a script running under 'set -e' must name the outer exit status it expects, never an echo the script prints afterwards: errexit ends the script at the first failing command, so a line printed after it is unreachable and the grader can only mark the wording, not the property.
 
+### lesson-raised-3aaf982e84ac: A file-length delta criterion must state whether the doc comments att...
+
+- lesson_id: lesson-raised-3aaf982e84ac
+- finding_category: correctness
+- agent_role: planner
+- statement: A file-length delta criterion must state whether the doc comments attached to the moved symbols move with them, and its window must be calibrated on that same choice; a window measured with comments included and silent about it fails a coder who leaves the comments behind.
+
+### lesson-raised-d478f9d6ea0b: Name an extraction task's scope as a symbol list, not a line range, a...
+
+- lesson_id: lesson-raised-d478f9d6ea0b
+- finding_category: correctness
+- agent_role: planner
+- statement: Name an extraction task's scope as a symbol list, not a line range, and derive its length window from the symbols that move; a window calibrated on a span that is wider than the enumerated symbols rewards the over-broad move and rejects the correct one, and a text-preserving destructure hides the difference from every other criterion.
+
+### bs-audit-3-scribe-cites-event-ids: A PR body or timeline summary cites events by event id (<session>#<n>...
+
+- lesson_id: bs-audit-3-scribe-cites-event-ids
+- agent_role: scribe
+- statement: A PR body or timeline summary cites events by event id (<session>#<n>, where n is the zero-based line index of the log), never by a line number of the log file, and states no number the event log does not carry: coverage percentages, turn caps, round reasons and provider counts included. The orchestrator checks every cited id against the log before the body is published.
+
 ## claim-path
 
 ### lesson-raised-3b5746704cfc: A function that computes a filesystem path and hands it to a child pr...
@@ -654,6 +674,37 @@ _(none yet)_
 - lesson_id: lesson-raised-3a400ca69b5e
 - statement: When two verbs are compared for cost, check when each one runs before concluding: the cheaper one may run after the very gate it was meant to save.
 
+### lesson-raised-44a58c2a7c7a: When checking a length-delta criterion, classify every line in the mo...
+
+- lesson_id: lesson-raised-44a58c2a7c7a
+- finding_category: correctness
+- statement: When checking a length-delta criterion, classify every line in the moved region as code, comment or blank and count them; never derive a line count by subtracting line numbers, because the span between two anchors includes whatever else lives there.
+
+### lesson-raised-394329488a2d: SMITH_EPIC_CAP_TOKENS in the gitignored .env overrides the epic cap i...
+
+- lesson_id: lesson-raised-394329488a2d
+- statement: SMITH_EPIC_CAP_TOKENS in the gitignored .env overrides the epic cap in budgets.yml, so the committed cap is not the enforced one; read budget alarm's capTokens and budgetEnvOverrides for the live cap, never budgets.yml.
+
+### lesson-raised-add2171a83a1: On a plan whose tasks are all origin user, the plan-quorum triggers a...
+
+- lesson_id: lesson-raised-add2171a83a1
+- statement: On a plan whose tasks are all origin user, the plan-quorum triggers are mechanically silent - trigger 1 sums declared budgets, not measured spend, and trigger 3's per-task arm only reads non-user origins - so the only live trigger is the orchestrator's own --confidence self-report; report it honestly below 0.8 when the draft needed repair rounds.
+
+### lesson-raised-be27b49f1d19: budget alarm reports unverifiable when dispatches for roles without a...
+
+- lesson_id: lesson-raised-be27b49f1d19
+- statement: budget alarm reports unverifiable when dispatches for roles without an attribution path (auditor, security-reviewer) are in the log, and the planner role has no per-role cap, so a planner overrun is only visible against the epic cap.
+
+### bs-audit-3-gate-timeout-under-load: Size a test-gate check's timeout for a loaded machine, not a quiet on...
+
+- lesson_id: bs-audit-3-gate-timeout-under-load
+- statement: Size a test-gate check's timeout for a loaded machine, not a quiet one: a suite that runs in about 200 s bare can be killed at a 300 s default with no output while another build shares the CPUs. When a check dies at its timeout with no test output, read machine load before blaming the code, log it as an env failure, and raise that check's timeout_ms through the per-check override; never drop or narrow the check to get it under the limit.
+
+### lesson-dream-vam-audit-7-2026-09-28-135: Every judge or worker dispatch brief names the JSON Schema its result...
+
+- lesson_id: lesson-dream-vam-audit-7-2026-09-28-135
+- statement: Every judge or worker dispatch brief names the JSON Schema its result file must satisfy: the full result envelope (task_id, agent, provider, model_tier, token_usage), the verdict at .structured_output, and the schema's own keys; the orchestrator schema-checks the file as soon as the agent returns, before gate run.
+
 ## security
 
 _(none yet)_

package/factory/policies/scheduler.yml

@@ -1,7 +1,7 @@
 # Blacksmith — scheduler policy
 #
 # Knobs for `factory/orchestrator/src/scheduler.ts` (architecture §12
-# "Recheck scheduling" + "Scheduled growth passes"; `smith scheduler run`).
+# "Recheck scheduling" + "Scheduled growth passes"; `bs scheduler run`).
 # A deterministic pass over the event log that only ever emits PROPOSAL
 # events — it never dispatches an agent or widens scope on its own.
 
@@ -50,7 +50,7 @@ lessons:
 autonomy:
   # Who says yes to what this pass proposes. The scheduler decides WHAT is
   # due; this block decides what may proceed without an operator tick, and
-  # `smith scheduler admit` (src/autonomy.ts) applies it. That command still
+  # `bs scheduler admit` (src/autonomy.ts) applies it. That command still
   # enacts nothing — it prints the classification so it can be read and
   # argued with before anything moves.
   #
@@ -71,7 +71,7 @@ autonomy:
   # or the enable marker classifies operator and never reaches the merge at
   # all. The loop may merge what it builds; it may not merge what bounds it.
   #
-  # None of those six is enforced by code yet, because `smith loop` does not
+  # None of those six is enforced by code yet, because `bs loop` does not
   # exist yet. Until it does, this block's `enabled: true` still only governs
   # dispatch, and the merge is performed by whoever is driving the session.
   enabled: true
@@ -82,7 +82,7 @@ autonomy:
   # says. The list is a ceiling, never a floor.
   #
   # `error-report` — the daemon proposing that an error the log holds with
-  # no `issue-reported` event be filed (`smith issues report`) — is left out
+  # no `issue-reported` event be filed (`bs issues report`) — is left out
   # on purpose, and listing it would not change that either. Filing writes
   # to an external issue tracker under an authenticated `gh` token whose
   # scope includes `repo`, and this block's standing decision is that

package/factory/policies/sensitive-paths.yml

@@ -13,7 +13,7 @@
 # a task can claim `src/auth/**` without writing the word "auth" anywhere in
 # its clauses, and that is exactly the task worth catching.
 #
-# HOST: `smith security triggers --task <spec.json>` reads this file and
+# HOST: `bs security triggers --task <spec.json>` reads this file and
 # returns the triggers that fired, with the claim and the glob that fired each
 # one (factory/orchestrator/src/security.ts, punch list P9-4). The dispatcher
 # in `.claude/skills/bs/dispatch.md` runs that verb rather than eyeballing the

package/factory/policies/severity.yml

@@ -31,6 +31,14 @@ levels:
       - a11y WCAG AA failure
       - new flaky test introduced by the task
       - behavioral-drift touching a core flow
+      - >
+          serious visual defect against the uiux spec or the project's design
+          system: a spec'd layout broken, or content clipped/overflowing, at
+          a required viewport; an interactive target below the project's
+          declared touch-target minimum (fall back to the WCAG 2.2 target
+          size minimum only when the project declares none); a required
+          state (empty, error, loading) missing (contrast: see a11y WCAG AA
+          above)
     on_trigger: >
       bounce to coder on the same branch; after 2 failed rounds, escalate
       model tier (mid -> frontier, budgets.yml); after 3, escalate to
@@ -40,7 +48,11 @@ levels:
     blocks_merge: false
     semantics: waivable — batched to operator at epic end
     classes:
-      - visual regression vs the uiux spec
+      - >
+          minor visual deviation from the uiux spec: spacing, color or type a
+          few px or a shade off a design-system token — not a broken layout,
+          clipped content, a missing required state, or a touch-target/
+          contrast failure below WCAG AA (those are S2-major, above)
       - performance regression > 20%
       - over-engineering (default severity — see rule below)
       - behavioral-drift not touching a core flow

package/factory/policies/stack.yml

@@ -2,7 +2,7 @@
 #
 # What the operator answered when they installed this clone (INSTALL.md
 # Step 6, "The stack interview"). Read by `factory/orchestrator/src/stack.ts`
-# via `smith stack show`, and through it by the scaffolder and by every agent
+# via `bs stack show`, and through it by the scaffolder and by every agent
 # that needs to know what this operator builds with.
 #
 # This file used to be a document. `docs/standards/stack.md` shipped one
@@ -13,20 +13,20 @@
 # question would otherwise put words in the operator's mouth.
 #
 # Not every answer is executable. The shipped templates implement a subset —
-# `smith stack check` prints which of your answers they honour and which are
-# recorded for the agents to read but not built into `smith new`. Nothing here
-# silently pretends: an answer the templates cannot honour makes `smith new`
+# `bs stack check` prints which of your answers they honour and which are
+# recorded for the agents to read but not built into `bs new`. Nothing here
+# silently pretends: an answer the templates cannot honour makes `bs new`
 # refuse rather than scaffold something else.
 
 # ── Language ────────────────────────────────────────────────────────
 # What the coder writes. `typescript` is the only value the shipped templates
-# scaffold; any other value is recorded, and `smith new` refuses rather than
+# scaffold; any other value is recorded, and `bs new` refuses rather than
 # handing you a TypeScript project you did not ask for.
 language: typescript # typescript | javascript | python | go | rust | other
 
 # ── Frontend ────────────────────────────────────────────────────────
 # `none` is the default because most projects are not UI projects, and the
-# base template is a plain library. `smith new --ui` needs a value the
+# base template is a plain library. `bs new --ui` needs a value the
 # templates implement — today that is `vue` and nothing else.
 frontend: none # none | vue | react | svelte | solid | vite-vanilla | other
 

package/factory/policies/taxonomy.yml

@@ -77,6 +77,7 @@ gate_event:      [schema-check-result, artifact-check-result,
                   finding-raised, finding-reverified, finding-suppressed,
                   finding-transitioned, finding-reattributed,
                   severity-decisions, waiver-granted, waiver-denied,
+                  task-waiver-approved,
                   gate-outcome, issue-reported]
                   # schema-check-result — task Result vs result.schema.json
                   # artifact-check-result — every artifacts[].path in that
@@ -95,7 +96,7 @@ gate_event:      [schema-check-result, artifact-check-result,
                   #                       always logged, including when the
                   #                       project declares nothing to install
                   # judges-outstanding  — a judge this task dispatched through
-                  #                       `smith judge dispatch` never reported
+                  #                       `bs judge dispatch` never reported
                   #                       back, so the gate refuses to score an
                   #                       unknown: a missing `--evidence` reads
                   #                       identically whether the judge found
@@ -194,6 +195,11 @@ gate_event:      [schema-check-result, artifact-check-result,
                   #                       waiver-batch / log-only)
                   # waiver-granted/-denied — operator waiver-batch answer,
                   #                       keyed by finding fingerprint
+                  # task-waiver-approved — operator approval of one waived
+                  #                       task, keyed by task id and valid from
+                  #                       its plan_version on; what the
+                  #                       epic gate accepts in place of a
+                  #                       gate run
                   # gate-outcome        — the composed gate pipeline's
                   #                       final structured result
                   # issue-reported      — issueReporter.ts's record of one
@@ -219,10 +225,10 @@ error:
                  # (planner, scribe) wrote outside its declared write root
                  # (P9-3); shipped as a code before it was a class
                  # judge-mutation — a read-only judge moved the worktree it
-                 # was judging (P9-5, `smith worktree verify`)
+                 # was judging (P9-5, `bs worktree verify`)
                  # uncited-claim — a researcher finding with no citation, or a
                  # citation that is neither a repo path with a line number nor
-                 # a URL actually fetched (P9-6, `smith research check`)
+                 # a URL actually fetched (P9-6, `bs research check`)
                  # unsourced-recommendation — a brief's recommendation names no
                  # finding, or names one the brief does not carry, so what came
                  # from fetched text is invisible (P9-6)

package/factory/policies/worktree.yml

@@ -17,19 +17,24 @@ worktree:
   # Relative to whatever directory the project was handed as, never to this
   # clone: a project beside the repo keeps its worktrees beside the repo too.
   path_pattern: "<project-parent>/.wt/<project>/<task-id>"
-  branch_pattern: "smith/<epic>/<task-id>"
-  created_from: integration branch head (smith/<epic>/integration), fresh each time
+  # bs-rename, operator decision 2/3: bs/ is the current prefix for every new
+  # epic; one that already integrates on the legacy smith/ prefix keeps it
+  # for its whole life rather than switching mid-epic (integration_branch
+  # below).
+  branch_pattern: "bs/<epic>/<task-id>"
+  created_from: integration branch head (bs/<epic>/integration), fresh each time
   lifecycle: deleted after merge — a stale worktree is a bug
   one_worktree_per_task: true
 
 integration_branch:
-  # Phase-3 correction: a bare "smith/<epic>" ref cannot coexist with
-  # "smith/<epic>/<task-id>" refs — git's ref namespace is hierarchical, so a
+  # Phase-3 correction: a bare "bs/<epic>" ref cannot coexist with
+  # "bs/<epic>/<task-id>" refs — git's ref namespace is hierarchical, so a
   # leaf ref and a directory prefix of the same name conflict (D/F conflict,
   # confirmed against a real git repo while implementing worktree.ts). The
   # integration branch is therefore a sibling of task branches under the
-  # epic's ref prefix, not a leaf at "smith/<epic>" itself.
-  pattern: "smith/<epic>/integration"
+  # epic's ref prefix, not a leaf at "bs/<epic>" itself. An epic that already
+  # integrates on smith/<epic>/integration (legacy) keeps that prefix instead.
+  pattern: "bs/<epic>/integration"
   rule: workers never touch main/master; only the operator merges the
     integration PR into the target repo's main.
 
@@ -75,7 +80,8 @@ merge_queue:
   mode: serial
   order: dependency order (topological, per recorded edges)
   admission_steps:
-    - rebase task branch onto current smith/<epic>/integration head
+    - rebase task branch onto current integration branch head (bs/<epic>/integration,
+      or smith/<epic>/integration for a legacy epic)
     - run the cumulative regression gate (every previously merged task's
       tests in this epic, not just the incoming task)
     - admit on green; reject and bounce on red
@@ -90,6 +96,6 @@ merge_queue:
     enabled: true
     max_lines_per_layer: 200
     note: >
-      workers emit small stacked layers (within the 400-line task diff cap)
-      rather than monolithic diffs; the queue lands stacks in dependency
+      workers emit small stacked layers (within the task diff cap,
+      budgets.yml `task.coder.cap_diff_lines`) rather than monolithic diffs; the queue lands stacks in dependency
       order (GitHub native stacked PRs).

package/factory/specs/roadmap.md

@@ -25,13 +25,13 @@ Each milestone is a `## <name>` heading followed by bullet fields:
 `completed`), `goal` (optional, one sentence), `epics` (optional, `[]` when
 no epic has been mapped to this phase yet — the join yields zero tasks
 until an epic is tagged here), `project` (optional, defaults to
-`black-smith` — this clone), `kind` (optional — `factory` | `dogfood` |
+`blacksmith` — this clone), `kind` (optional — `factory` | `dogfood` |
 `product`), and `error_issues` (optional — `on` | `off`).
 
 `kind` describes the *project*, not the milestone, so one bullet anywhere in
 a project's milestones settles all of them; a second copy would only be a
-copy that drifts. It defaults to `factory` for `black-smith` and `product`
-for everything else, which is why a project registered by `smith new` needs
+copy that drifts. It defaults to `factory` for `blacksmith` and `product`
+for everything else, which is why a project registered by `bs new` needs
 no bullet at all. `dogfood` is the one value that must be written by hand:
 a project built to exercise the factory looks, in the data, exactly like a
 project built for its own sake — the difference is intent. The Roadmap page
@@ -180,7 +180,7 @@ all; write `- error_issues: off` by hand to opt a project's tracker out.
 - id: bs-audit-1
 - status: planned
 - epics: [bs-audit-1]
-- project: black-smith
+- project: blacksmith
 - kind: factory
 - goal: Cut from audit 20260925-f336f5e4 of `blacksmith` (7 accepted findings: 3 S2-major, 3 S3-minor, 1 S4-nit). Each finding below is one acceptance criterion; the plan decides the tasks. **d7c644db (S2-major, performance)** `factory/orchestrator/src/events.ts` — appendEvent() re-reads and re-JSON.parses the entire session event log on every single append (readEventsAtPath inside appendEventLocked), while holding both an in-process queue and a cross-process poll lock, so writing to a session log is O(n) per event and O(n^2) for a session of n events.. **0f3f9c23 (S3-minor, performance)** `factory/orchestrator/src/worktree.ts` — listStale() spawns one synchronous `git merge-base --is-ancestor` subprocess per worktree entry in a loop instead of a single batched check, so merge-queue/worktree cleanup cost scales linearly with subprocess spawns rather than with one git invocation.. **ae8cb69e (S2-major, architecture)** `factory/orchestrator/src/queue.ts` — The queue module shells out to git directly with execFileSync instead of going through git.ts, the module the codebase documents as the one place this factory shells out to git, so queue git failures bypass credential redaction and the structured GitCommandError type.. **fd03e000 (S3-minor, architecture)** `factory/orchestrator/src/diffstat.ts` — diffstat.ts calls execFileSync('git', ...) directly for rev-parse/diff/branch instead of through git.ts, duplicating the single git-invocation boundary the codebase declares for itself and losing that module's credential redaction and GitCommandError typing.. **160cc3d7 (S3-minor, architecture)** `factory/orchestrator/src/commit.ts` — commit.ts, which certifies whether a task's work is safe to integrate, runs its own execFileSync('git', ...) calls rather than routing through git.ts, so the one module the codebase names as the sole git entry point has at least two siblings that re-implement direct git shell-outs.. **07c5d1b0 (S2-major, code-quality)** `factory/orchestrator/src/claims.ts` — collectCommittedChanges, the collector behind postRunCheck (the claim-confinement check for a task worktree), runs `git diff --name-only` without `--no-renames`, so a rename that crosses a claim boundary is reported only by its destination path.. **ad9ea9ba (S4-nit, code-quality)** `factory/orchestrator/src/waveNext.ts` — The one-line helper nameList (ids.join(', ')) is duplicated verbatim in waveNext.ts and waveSchedule.ts rather than shared, so the two wave-scheduling files carry two independent copies of the same id-list formatting rule..
 
@@ -188,7 +188,7 @@ all; write `- error_issues: off` by hand to opt a project's tracker out.
 - id: bs-audit-2
 - status: planned
 - epics: [bs-audit-2]
-- project: black-smith
+- project: blacksmith
 - kind: factory
 - goal: Cut from audit 20260925-49bffa9b of `blacksmith` (5 accepted findings: 2 S2-major, 3 S3-minor). Each finding below is one acceptance criterion; the plan decides the tasks. **50acc356 (S3-minor, performance)** `factory/orchestrator/src/daemon.ts` — runTick() re-reads and re-JSON.parses every session's full .jsonl event log from disk on every daemon tick, with no incremental/fingerprint caching, so the daemon's per-tick cost grows linearly and unboundedly with the factory's total historical event volume.. **d50d4c1f (S3-minor, performance)** `ui/server/src/app.ts` — Every dashboard write route that omits an explicit causalParent (waivers apply-batch, lessons approve/reject/edit) triggers a full read-and-parse of that session's entire event log via resolveContext()/lessonContext() just to read the id of the last event.. **4c610e7c (S2-major, security)** `ui/server/src/app.ts` — The dashboard's write endpoints (waiver apply-batch, lesson approve/reject/edit) have no CSRF protection: there is no Origin/Referer check and Hono's `c.req.json()` parses the request body as JSON regardless of the Content-Type header, so a cross-origin `text/plain` form POST (a CORS-exempt 'simple request' that needs no preflight) is accepted and executed.. **1b8fe398 (S3-minor, architecture)** `.claude/skills/bs/wave.md` — The wave playbook's own loop (steps 2-10) never invokes the one instrument that measures whether a wave actually ran in parallel (auditWaveConcurrency/`smith wave check`, factory/orchestrator/src/waveConcurrency.ts), so the factory's central scaling claim goes unchecked for the entire time it could still be corrected.. **7ef3cd2f (S2-major, architecture)** `.claude/skills/bs/dispatch.md` — The one hard cap that bounds every subagent's work (`maxTurns`, enforced by the Claude Code harness itself) is transmitted into each dispatch prompt purely as prose the dispatching agent must copy correctly by hand from `.claude/agents/<role>.md` 'at dispatch time' — no module in factory/orchestrator/src validates that a dispatch's stated turn budget matches the template the harness will actually enforce, so the one enforcement path for this invariant is a human/LLM re-reading a file correctly every single time.. **Operator-added scope (2026-09-25, from GitHub research, ideas only)**: (6) a `SubagentStop` hook in the judge-class agent templates' frontmatter that blocks a judge from ending while its declared artifact file is absent — complements `agent-resume`, which handles the cap itself; (7) planning emits parallel width mechanically — at plan ingest, tasks with disjoint claims and no dependency edge are marked parallel and the plan's achievable width is reported, and a small epic takes a right-sized planning path with a bounded review focus. The per-task pipeline (no wave barrier) is deliberately out of scope until a pros/cons analysis is decided.
 
@@ -196,6 +196,6 @@ all; write `- error_issues: off` by hand to opt a project's tracker out.
 - id: bs-audit-3
 - status: planned
 - epics: [bs-audit-3]
-- project: black-smith
+- project: blacksmith
 - kind: factory
-- goal: Cut from audit 20260927-b61eaa7e of `black-smith` (2 accepted findings: 2 S3-minor). Each finding below is one acceptance criterion; the plan decides the tasks. **871ee8f7 (S3-minor, architecture)** `ui/server/src/app.ts` — lessonSession() builds its own drizzle query directly against the `lessons` schema table instead of going through db/queries.ts, the module the file's own header comment declares as the single 1:1 wrapper boundary between the UI and the projection.. **442cd7f2 (S3-minor, code-quality)** `factory/orchestrator/src/daemon.ts` — daemon.ts defines its own readJsonFile() that silently swallows any parse/read error and returns null, diverging from the fail-closed readJsonFile() in cli.ts that throws on malformed JSON, so a corrupted daemon lock/status/memory file is treated as absent rather than reported..
+- goal: Cut from audit 20260927-b61eaa7e of `blacksmith` (2 accepted findings: 2 S3-minor). Each finding below is one acceptance criterion; the plan decides the tasks. **871ee8f7 (S3-minor, architecture)** `ui/server/src/app.ts` — lessonSession() builds its own drizzle query directly against the `lessons` schema table instead of going through db/queries.ts, the module the file's own header comment declares as the single 1:1 wrapper boundary between the UI and the projection.. **442cd7f2 (S3-minor, code-quality)** `factory/orchestrator/src/daemon.ts` — daemon.ts defines its own readJsonFile() that silently swallows any parse/read error and returns null, diverging from the fail-closed readJsonFile() in cli.ts that throws on malformed JSON, so a corrupted daemon lock/status/memory file is treated as absent rather than reported..

package/factory/specs/schema/event.schema.json

@@ -3,7 +3,7 @@
   "$id": "https://black-smith.dev/schema/event.schema.json",
   "$comment": "Taxonomy-valued fields carry an x-taxonomy annotation naming the dimension in factory/policies/taxonomy.yml. The runtime validates those values against that file at write time; enums are never inlined here to avoid drift between the schema and the taxonomy (architecture §8).",
   "title": "Event",
-  "description": "One record in state/events/*.jsonl, the factory's durable execution substrate (architecture §7). Field names follow §7's record shape exactly: {ts, session_id, actor, event_type, task_id?, agent_id?, plan_version, causal_parent, payload}.",
+  "description": "One record in state/events/*.jsonl, the factory's durable execution substrate (architecture §7). Field names follow §7's record shape exactly: {ts, session_id, actor, event_type, task_id?, agent_id?, plan_version, causal_parent, payload, project?, cli_session_id?}.",
   "type": "object",
   "required": [
     "ts",
@@ -61,6 +61,13 @@
       "minLength": 1,
       "description": "Optional plain-string project identifier (Phase 6b, architecture §8) — NOT a closed taxonomy.yml vocabulary value, so no x-taxonomy annotation here. Absent on every event logged before Phase 6b; db/queries.ts's read helpers treat an absent/null project as the default 'black-smith'. That default is reached by absence, so \"\" would slip past it and name a project called nothing (D-244)."
     },
+    "cli_session_id": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "pattern": "^[0-9a-fA-F-]{8,64}$",
+      "description": "Optional — the CLI session that wrote the event, stamped by the writer from CLAUDE_CODE_SESSION_ID and absent outside one (and on every event logged before the stamp existed). Not part of the envelope: it never stands in for session_id or causal_parent (architecture §18 rule 8), and it is never turn or delegation evidence, since an epic session and its subagents can share one CLI session (rule 4). It only links a live CLI session to the factory sessions it drives."
+    },
     "edge": {
       "type": "object",
       "description": "Present only on edge-recorded events (architecture §7).",

package/factory/specs/schema/result.schema.json

@@ -46,14 +46,27 @@
       }
     },
     "token_usage": {
-      "type": "object",
-      "required": ["input_tokens", "output_tokens", "total_tokens"],
-      "properties": {
-        "input_tokens": { "type": "integer", "minimum": 0 },
-        "output_tokens": { "type": "integer", "minimum": 0 },
-        "total_tokens": { "type": "integer", "minimum": 0 }
-      },
-      "additionalProperties": false
+      "description": "Either a real count, stamped by the dispatcher off the harness's own measurement, or an honest admission that nothing could be measured — a dispatcher running inside an environment with no API onto a subagent's token spend (#220). The field stays required either way: only its shape may say 'not measured', its absence never may.",
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["input_tokens", "output_tokens", "total_tokens"],
+          "properties": {
+            "input_tokens": { "type": "integer", "minimum": 0 },
+            "output_tokens": { "type": "integer", "minimum": 0 },
+            "total_tokens": { "type": "integer", "minimum": 0 }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": ["measured"],
+          "properties": {
+            "measured": { "const": false }
+          },
+          "additionalProperties": false
+        }
+      ]
     },
     "agent": {
       "type": "string",

package/factory/specs/schema/task-spec.schema.json

@@ -129,10 +129,22 @@
       "type": "string",
       "description": "Optional plain-string project identifier (Phase 6b, architecture §8) — NOT a closed taxonomy.yml vocabulary value (projects open/close far more often than any §8 dimension). Absent tasks default to 'black-smith' in the projection layer."
     },
+    "title": {
+      "type": "string",
+      "description": "Optional human-facing short title for the task row (DS3); falls back to a humanized task_id slug when absent."
+    },
+    "summary": {
+      "type": "string",
+      "description": "Optional human-facing one-line summary for the task row (DS3)."
+    },
     "keeps_exports": {
       "type": "array",
       "items": { "type": "string" },
       "description": "Repo-relative file paths, each inside one of this task's own claims, whose existing exports this task keeps: no export removed, no export's declaration changed; adding exports is allowed. A symbol crossing whose producer promised the exporting file does not serialize the wave (impact.ts waveImpact); the promise is verified post-run by `smith claims impact <worktree> <spec.json>` against the diff."
+    },
+    "ui_affecting": {
+      "type": "boolean",
+      "description": "Optional. True when this task changes what a user sees (components, styles, templates, on-screen copy); false when it claims UI-extension paths without a visible change. Absent means false at the gate, but validatePlan errors when a task claims a UI-extension path (.tsx/.jsx/.vue/.svelte/.css/.scss/.sass/.less/.html) and this key is absent — set it explicitly (U2)."
     }
   },
   "additionalProperties": false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juzser/blacksmith",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "description": "Autonomous agent factory — loop runner and worktree engine.",
   "keywords": [
@@ -33,8 +33,11 @@
   },
   "packageManager": "pnpm@9.3.0",
   "bin": {
+    "bs": "factory/orchestrator/dist/cli.js",
+    "bs-run": "factory/orchestrator/dist/run-cli.js",
     "smith": "factory/orchestrator/dist/cli.js",
-    "smith-run": "factory/orchestrator/dist/run-cli.js"
+    "smith-run": "factory/orchestrator/dist/run-cli.js",
+    "bs-prompt-hook": "factory/orchestrator/dist/promptHook.js"
   },
   "files": [
     "factory/orchestrator/dist",
@@ -75,26 +78,27 @@
     "ajv": "8.20.0",
     "ajv-formats": "3.0.1",
     "better-sqlite3": "13.0.3",
-    "drizzle-orm": "0.45.2",
+    "drizzle-orm": "0.45.3",
     "picomatch": "4.0.7",
     "yaml": "2.9.1"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.14",
-    "@hono/node-server": "2.1.1",
+    "@biomejs/biome": "2.5.15",
+    "@floating-ui/dom": "1.8.0",
+    "@hono/node-server": "2.1.3",
+    "@lucide/vue": "1.50.0",
     "@playwright/test": "1.63.0",
     "@tailwindcss/vite": "4.3.3",
     "@types/better-sqlite3": "9.6.0",
-    "@types/node": "26.6.1",
+    "@types/node": "26.6.4",
     "@vitejs/plugin-vue": "6.0.9",
-    "@vitest/coverage-v8": "5.0.1",
-    "@vue-flow/core": "1.48.2",
-    "drizzle-kit": "0.31.10",
-    "hono": "4.13.8",
+    "@vitest/coverage-v8": "5.0.3",
+    "drizzle-kit": "0.31.11",
+    "hono": "4.13.12",
     "tailwindcss": "4.3.3",
     "typescript": "7.0.2",
-    "vite": "8.3.0",
-    "vitest": "5.0.1",
+    "vite": "8.3.2",
+    "vitest": "5.0.3",
     "vue": "3.5.43",
     "vue-router": "5.3.1"
   }

package/.claude/agents/uiux.md

@@ -1,133 +0,0 @@
----
-name: uiux
-description: Writes a UI spec grounded in the project's design system before any UI-affecting task is coded, and runs the post-test visual pass against the tester's screenshots. Use pre-code on any epic with a UI-affecting acceptance criterion, and after tests when a UI task has both a spec and screenshots.
-model: sonnet
-effort: medium
-tools: Read, Grep, Glob, Bash
-maxTurns: 15
----
-
-# UI/UX
-
-Build-tier (architecture §4, §10): produces an implementation-ready UI spec
-grounded in whatever design system the project actually has, before a coder
-touches UI code. You spec; you do not implement.
-
-**Which design system is a fact you look up, not one you assume.**
-`factory/policies/stack.yml` holds the answer this operator gave at install
-(`design_system`, `design_system_source`), and `smith stack show` prints it.
-A project scaffolded with a named kit carries it vendored at `design/`; a
-project answered `design_system: none` has no kit, and that is a complete
-answer — spec against the project's own existing components and tokens
-instead, and say in the spec that you did.
-
-## You never modify the worktree
-
-<!-- BEGIN SHARED:read-only-judge-rule -->
-You hold `Bash`, so "read-only" is a discipline you keep, not a wall that
-holds you. `Bash` is there to run the suite, `git diff`, `rg` — and the same
-tool writes files just as easily. So the rule is explicit rather than implied:
-**no edit, no `git add`/`commit`/`checkout`/`stash`/`restore`, no `>` or `>>`
-into a repo path, no formatter, no package install, no `git config`.**
-<!-- END SHARED:read-only-judge-rule -->
-
-Not even the component swap that would take one line: write it into the spec
-and the coder lands it under a claim and a gate.
-
-<!-- BEGIN SHARED:read-only-judge-guard -->
-The only path you write is your own output artifact under `state/results/`,
-which lives outside the worktree.
-
-This is checked, not trusted: the dispatcher fingerprints the worktree before
-you start and re-checks it after you return (`smith worktree verify`). A tree
-that moved — new file, edited file, staged change, commit, branch switch —
-discards your result and re-runs the pass on a clean worktree, so the one-line
-edit does not save a round-trip, it costs the whole one.
-<!-- END SHARED:read-only-judge-guard -->
-
-## Constraints (agent-interviews.md: uiux)
-
-- Fidelity: **component-level** — name components and layout, the coder fills
-  in exact markup. Name specific tokens/spacings only where the design
-  deviates from the design system's defaults.
-- Ground every recommendation in something that exists on disk: the vendored
-  kit at `design/` when the project has one, otherwise the components and
-  tokens the project already ships. Never invent a new pattern without
-  flagging it as a deviation needing planner sign-off.
-- Screenshot spec you write must match the tester's contract: desktop +
-  mobile (390px), light + dark, max 4 shots per feature.
-- Pre-code research + uiux together share <=15% of the epic budget
-  (`budgets.yml`) — this is a spec, not an exploration.
-- Auto-compact at 60% of your context window (`budgets.yml`
-  `context_window`): keep the acceptance criteria, the components already
-  chosen and why, and open deviations; drop the kit source you read to get
-  there. Needing a compaction means you are exploring, not speccing.
-
-## Mission
-
-Two triggers, and you are told which one you are on.
-
-**Pre-code spec (the default).** Read the acceptance criteria and any
-referenced design intent, then produce a spec the coder can implement without
-re-deriving component choices: layout, component names, states
-(empty/loading/error), responsive behavior, and a11y notes (WCAG AA is an
-`S2-major` review gate downstream).
-
-**Post-test visual pass.** Dispatched only when all three hold: the task is
-UI-affecting, the tester's screenshots exist as artifacts, and a uiux spec was
-written for this task. Miss any one and the pass is skipped, not faked — a
-verdict on screenshots that do not exist is worse than no verdict.
-
-On a visual pass you read **the spec and the images, nothing else**. Not the
-diff, not the components, not the test code. The whole point is a judgment
-made the way a user's eye makes it: if the rendered screen matches the spec,
-the implementation is right regardless of how it reads, and if it does not,
-elegant code does not save it. Reading the diff is how you end up reviewing
-intent instead of result — and the reviewer already covers intent.
-
-<!-- LESSONS:stack-wide -->
-<!-- LESSONS:case-type -->
-
-## Output contract
-
-Two parts, both mandatory.
-
-**1. Write the full spec** to `state/results/<task-id>.json` — an object with
-exactly these three keys:
-
-- `run_status` — `done` if the spec is complete, `dead` if the acceptance
-  criteria do not describe a UI surface you can spec
-- `structured_output` — for a pre-code spec: `{components: [{component,
-  role, notes}], states, responsive, a11y_notes, deviations}` — `component`
-  is the kit's name for it when the project has a kit, otherwise the
-  project's own. For a post-test
-  visual pass: `{pass: true | false, screenshots_reviewed: [path],
-  deviations: [{screenshot, expected, observed}]}`
-- `artifacts` — `[{type, path, description?}]`: the written spec. It still
-  belongs under the epic's spec directory — that is where the coder reads it —
-  but the gate only opens paths under `state/artifacts/<task-id>/`, so put a
-  copy there and declare that one, relative (`ui-spec.md`), naming the
-  spec-dir location in `description`
-
-**Never set `task_id`, `agent`, `provider`, `model_tier` or `token_usage`.**
-The dispatcher owns those five and merges them in before validating the file
-against `factory/specs/schema/result.schema.json`, which is
-`additionalProperties: false`.
-
-<!-- BEGIN SHARED:token-usage -->
-`token_usage` is on that list for a reason of its own: you cannot read your
-own meter. Whatever you write there is a guess wearing a measurement's
-clothes, and it lands in the only per-task cost signal the epic has. The
-harness counts the tokens; the dispatcher stamps them.
-<!-- END SHARED:token-usage -->
-
-**2. Return one line** as your final message — this JSON and nothing else:
-
-```
-{"status": "done", "artifact_path": "state/results/<task-id>.json"}
-```
-
-Every `deviation` names the component it departs from and why the spec needs
-the departure. "Custom" without that sentence is how a design system erodes
-one task at a time — and a project with no design system is not exempt, it is
-the one where the erosion has nothing to push back.