@juzser/blacksmith 0.3.0 → 0.5.0

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
@@ -175,3 +175,27 @@ all; write `- error_issues: off` by hand to opt a project's tracker out.
 - status: planned
 - epics: []
 - goal: Stop spending judge calls on outputs that a free check could have rejected, and stop grading a capped output as though it were a finished one. Four pieces, independent enough to land separately. **Free critics ahead of paid judges**: an empty diff, a missing structured completion, and claims touched without a single test added are all decidable without a model, and each one currently reaches a judge that pays full price to say so. The OpenHands SDK runs exactly this tier first and classifies what it rejects as behaviour, infrastructure or unclear-request — a taxonomy worth having because "the agent failed" and "the environment failed" are different bugs with different owners, and today they land in the same place. **Grade a budget-capped output as worth less**: SWE-agent's reviewer discards out-of-range verdicts and tie-breaks on cost; here the sharper version is that an output produced by an agent that hit its turn cap is a partial output, and a judge that does not know that is being asked to grade a fragment as a whole — which is how a capped run earns a passing verdict for the third of the task it finished. **Submit-gating and an honest forfeit**: show the worker its own diff before it may report done, with a checklist that names the mistakes workers actually make — test files touched, debug output left, claims exceeded — and give it a structured way to give up. A forfeit is strictly more useful than a confident wrong answer: it costs one round instead of a judge round plus a verifier round plus a rework round, and it is information the lessons pass can learn from. **Budget as an admission check**: `min_budget_for_dispatch` per role, so a role is never dispatched into a budget that cannot finish it, and a ring-fenced judging reserve so a capped epic still gets graded rather than spending its last tokens on more coding. Two things stay open. **Whether a free critic may block or only warn** — a false rejection that costs a whole round is worse than the judge call it saved, so the first critics should probably warn while their precision is measured against `agent-bench`. **What a forfeit does to the escalation ladder** — `budgets.yml` already declares one, and a forfeit is either its first rung or a separate path, but it must not become a cheap exit an agent prefers to the work. Researched 2026-09-18 across SWE-agent and the OpenHands SDK.
+
+## Self-audit 1 — event-log append cost, rename-blind claim diffs, one git entry point
+- id: bs-audit-1
+- status: planned
+- epics: [bs-audit-1]
+- 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..
+
+## Audit 2: bounded judges, parallel feedback, dashboard origin guard
+- id: bs-audit-2
+- status: planned
+- epics: [bs-audit-2]
+- 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.
+
+## Self-audit 3: UI read boundary and fail-closed daemon state
+- id: bs-audit-3
+- status: planned
+- epics: [bs-audit-3]
+- project: blacksmith
+- kind: factory
+- 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.3.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.