@juzser/blacksmith 0.1.0

package/factory/policies/effort.yml

@@ -0,0 +1,142 @@
+# Effort tiers — how much judgment an epic buys.
+#
+# An internal tool and a payments rewrite do not deserve the same number of
+# judge calls, but until this file existed the factory had exactly one flow and
+# the only way to make a small epic cheap was to skip steps by hand and
+# remember which ones. That is the same failure mode sensitive-paths.yml was
+# written for: a decision made fresh every time is a decision made differently
+# every time. So the tiers are declared here and asked for, never recalled.
+#
+# HOST: `smith effort show --plan <plan.json>` reads this file plus the plan's
+# own `effort` field and returns the profile for that epic
+# (factory/orchestrator/src/effort.ts). `.claude/skills/bs/plan.md` and
+# `run.md` run that verb at the top of `/bs plan` and `/bs run` and obey the
+# answer, rather than eyeballing the table below.
+#
+# Scope note: the tier is per EPIC, not per project. It is chosen at `/bs plan`
+# time and stored on the plan file, so one project can run a `small` epic in
+# the morning and a `huge` one in the afternoon. `budgets.yml`'s
+# `effort_scaling:` block is the prose sibling of this file — it says fan-out
+# is a wall-clock optimisation; this says how much judgment each epic buys.
+#
+# THE INVARIANT THAT MAKES THIS SAFE: a tier scales judgment steps only. It
+# never touches a mechanical oracle or a guardrail — see `invariants:` at the
+# bottom, which the host returns alongside every profile so the list cannot be
+# quietly forgotten. A `small` tier that skipped tests would not be cheap, it
+# would be unverified, and the two are not the same thing.
+
+version: 1
+
+# The tier an epic gets when its plan file names none. `medium` and not `huge`:
+# an unstated tier is an unconsidered one, and the default should be the
+# ordinary case rather than the most expensive one. An epic that wants the full
+# flow says so.
+default_tier: medium
+
+# The lowest tier an epic may run at once its live tasks fire crosscheck.yml's
+# `plan_quorum` security triggers (`case: infra`, a security-sensitive
+# `agent_role`, or a `security_keywords` hit in a nonfunctional clause). An
+# internal tool that touches auth is not a small epic — the operator's tier is
+# a request, and this is the floor it is answered against. Raising a tier is
+# always allowed; the floor only ever raises.
+security_floor: medium
+
+# ── The tiers ───────────────────────────────────────────────────────
+#
+# Read top to bottom as a subtraction: `huge` is the flow as the `/bs`
+# playbooks (`.claude/skills/bs/`) write it today, unchanged; `medium` drops the
+# judgment steps that pay off least per call; `small` drops the pre-code
+# deliberation as well. Every knob below names a step that is a *judgment* —
+# an agent forming an opinion. Nothing mechanical appears here by construction.
+tiers:
+  huge:
+    summary: >
+      The full flow, exactly as the `/bs` playbooks write it. Large or important
+      projects, anything user-facing, anything whose failure is expensive.
+    # /bs run step 3 — dispatch `researcher` for a pre-code unknown.
+    pre_code_research: when-needed
+    # /bs run step 3 — dispatch `uiux` for a UI-affecting acceptance criterion.
+    # Already conditional today at every tier; stated at all three so the knob
+    # reads as a fact about the flow rather than an omission.
+    pre_code_uiux: when-ui-criterion
+    # /bs plan steps 3-4 — planner <-> spec-reviewer until nothing S1/S2 is left.
+    spec_review_rounds: until-clean
+    # /bs plan step 4 — `smith plan quorum` before operator sign-off.
+    plan_quorum: always
+    # /bs run step 6 — the grader's bounded rubric loop (agent-constraints.md
+    # caps it at 2; a tier may lower that number, never raise it).
+    grader_rounds: 2
+    # /bs run step 7 — which reviewer findings get the adversarial verifier
+    # pass before they cost the coder a round trip.
+    verifier_severities: [S1-stop-the-line, S2-major]
+    # ...plus this share of S3-minor findings, sampled. The 20% spot-check is
+    # what today's flow does; the lower tiers drop the sample, not the S1/S2
+    # mandate.
+    verifier_s3_spot_check_ratio: 0.2
+    # /bs run step 13 — the closing spec-reviewer against the assembled branch.
+    closing_spec_review: always
+
+  medium:
+    summary: >
+      The default. Ordinary product work: the adversarial passes that catch
+      real defects stay, the deliberation that mostly confirms is dropped.
+    pre_code_research: when-needed
+    pre_code_uiux: when-ui-criterion
+    spec_review_rounds: until-clean
+    # Down from `always`: the quorum computes its own triggers, so running it
+    # unconditionally buys an answer of "nothing fired" most of the time. At
+    # this tier it runs when crosscheck.yml says something fired.
+    plan_quorum: when-triggered
+    # Down from 2: round 2 exists for the rubric that moved. Below `huge`,
+    # one round scores and a second one is the coder's bounce instead.
+    grader_rounds: 1
+    verifier_severities: [S1-stop-the-line, S2-major]
+    # Down from 0.2: the S3 sample is a calibration measurement on the
+    # reviewer, not a defence of this epic's diff.
+    verifier_s3_spot_check_ratio: 0
+    closing_spec_review: always
+
+  small:
+    summary: >
+      Internal tools, scripts, one-file chores — work whose blast radius is
+      the operator's own afternoon. Fast, and still gated.
+    # Down from when-needed: at this size the coder reading the repo is the
+    # research brief. An epic that genuinely needs one is not a small epic.
+    pre_code_research: never
+    pre_code_uiux: when-ui-criterion
+    # Down from until-clean: one spec-review pass, findings surfaced to the
+    # operator with the spec at sign-off rather than looped on first.
+    spec_review_rounds: single-pass
+    plan_quorum: when-triggered
+    grader_rounds: 1
+    # Down from [S1, S2]: only a stop-the-line finding is worth an
+    # adversarial refute pass before it reaches the coder.
+    verifier_severities: [S1-stop-the-line]
+    verifier_s3_spot_check_ratio: 0
+    # Down from always: a closing spec review reads the spec against the code
+    # that now exists, which is worth a call when the spec moved. If the epic
+    # ran its whole plan without an amendment, it did not move.
+    closing_spec_review: when-plan-amended
+
+# ── What no tier may touch ──────────────────────────────────────────
+#
+# Returned verbatim by `smith effort show` next to every profile. These are
+# mechanical oracles and guardrails, not judgments: their cost is a command
+# exiting, not an agent thinking, so scaling them saves nothing and buys
+# nothing but a weaker claim about the result.
+invariants:
+  - the gate pipeline — schema check, grader verdict, tests, coverage
+    evidence, findings intake, severity decision (`smith gate run`)
+  - the root-level integration check on the assembled branch
+    (`smith integration check`)
+  - claim disjointness and worktree isolation (`smith wave check`,
+    `smith worktree create/fingerprint/verify`)
+  - the security-reviewer's conditional dispatch
+    (`smith security triggers`) — sensitive-paths.yml decides it, not a tier
+  - the operator's plan sign-off, which no tier may skip or infer
+  - the epic-final verdict and its mechanical holds (`smith epic verdict`,
+    `smith epic close`)
+  - the event log — every dispatch is still a `dispatch_decision` with a
+    causal parent, at every tier
+  - the escalation ladder after a blocked round (budgets.yml
+    `escalation_ladder`) — a cheap epic that fails twice still climbs

package/factory/policies/guardrails.yml

@@ -0,0 +1,306 @@
+# Blacksmith — guardrail enforcement policy
+#
+# docs/standards/guardrails.md is the contract; this file is the data half of
+# what enforces it. HOST: `smith policy check`/`smith policy hook`
+# (factory/orchestrator/src/policy.ts), and — via `dist/policyHook.js` —
+# `.claude/hooks/guard.sh`, the PreToolUse gate on every guarded tool call
+# an agent session makes.
+#
+# What this file is NOT: a place for matchers. Deciding whether a command
+# trips a rule is deliberately NOT expressed here as regex-in-YAML — the
+# matchers live in policy.ts, in TypeScript, where they have unit tests
+# (test/policy.test.ts). A rule whose matching logic is data instead of code
+# is a rule nobody can write a test against, and this is a deny gate: the one
+# place in the factory where "we changed it and nothing checked" is not an
+# acceptable failure mode. What belongs here is what an operator would
+# legitimately want to change without touching a matcher: branch names,
+# allowed roots, which commands count as a deploy, and the message an agent
+# sees when a rule fires.
+#
+# Every rule is S1 ("stop the line") per guardrails.md's preamble: these are
+# hard rules the factory enforces mechanically, not policy questions for the
+# gate to weigh. `reason` is the exact string `guard.sh` has printed since
+# Phase 2 — changing it here changes what an agent sees at the moment a
+# command is denied, so treat it as user-facing copy, not an internal note.
+# `reason_on_current_branch` exists only on the two rules (push, merge) that
+# have a second trigger — a *bare* `git push`/`git merge` while already
+# checked out on a protected branch, where the bash's message named the
+# branch the agent was standing on rather than the ref it typed. `{branch}`
+# in either reason is substituted — at every occurrence — with the branch
+# policy.ts resolved, not rendered literally.
+
+protected_branches:
+  # Literal branch names `push`/`merge` refuse as a destination or as the
+  # branch checked out for a bare push/merge (rule 1, rule 3). `patterns` is
+  # the shared per-epic integration branch shape, added to `names` for the
+  # history-rewrite rule only (rule 5) — worktree.yml's
+  # `integration_branch.pattern`: a leaf ref "smith/<epic>" cannot coexist
+  # with "smith/<epic>/<task-id>" refs in real git (D/F ref conflict), so the
+  # shape is "smith/<epic>/integration", never a bare "smith/<epic>".
+  names: [main, master]
+  patterns: ["smith/*/integration"]
+
+catch_up_remotes:
+  # rule 3's one exception: the remotes a protected branch is allowed to
+  # fast-forward *itself* to, as `git pull --ff-only <remote> <branch>` or
+  # `git merge --ff-only <remote>/<branch>`. Nothing lands that the remote
+  # does not already have, so the gate has nothing to protect.
+  #
+  # This vouches for a name, not a URL — `git remote add` and `git remote
+  # set-url` can point any name anywhere, and this gate reads the command
+  # line, not .git/config. So keep the list to remotes whose name means the
+  # same thing everywhere the factory runs. Omit the key entirely and you get
+  # [origin]; an empty list turns the exception off.
+  - origin
+
+destructive_removal:
+  # rule 6: a recursive-force `rm` is allowed only under one of these
+  # directories, matched by name at the top of whichever repository the
+  # command runs in — its cwd's git toplevel, not this clone. Inside a task
+  # worktree that is the worktree, which has neither, so nothing qualifies
+  # there (guardrails.md "Filesystem").
+  allowed_roots: [workspaces, state]
+
+deploy_commands:
+  # rule 4: command + subcommand pairs that require per-invocation operator
+  # approval (guardrails.md "Deploy + outbound"). Matched as `\b<command>\b
+  # .* \b<subcommand>\b` (any one of `subcommands`), the same looseness as
+  # every other rule here — see policy.ts's `checkDeployCommand`.
+  - { command: wrangler, subcommands: [deploy, publish] }
+  - { command: pages, subcommands: [publish] }
+
+rules:
+  - id: push-to-protected
+    severity: S1
+    reason: >-
+      push to main/master is never allowed from an agent session. Push a
+      side branch and open a PR.
+    reason_on_current_branch: >-
+      push to main/master is never allowed from an agent session (checked
+      out on {branch}).
+
+  - id: force-push
+    severity: S1
+    reason: >-
+      force-push (--force/-f/--force-with-lease) is never allowed from an
+      agent session, on any branch. A branch you have already pushed is
+      append-only here: add a commit. Rewriting history that is published
+      is an operator action.
+
+  - id: merge-into-protected
+    severity: S1
+    reason: >-
+      a merge lands on the branch you are standing on, never on the branch you
+      name, and that is never main/master in an agent session; the operator
+      merges integration PRs.
+    reason_on_current_branch: >-
+      a merge lands on the branch you are standing on and you are on {branch};
+      git pull is the same merge with a fetch in front. Check out a side branch
+      instead — merging main into a side branch to refresh it is allowed, and
+      is how you get a stale PR up to date. To catch {branch} itself up to the
+      remote, `git pull --ff-only origin {branch}` is allowed: it moves the
+      pointer and lands nothing the remote does not already have.
+
+  - id: deploy-command
+    severity: S1
+    reason: >-
+      deploy/publish commands require explicit operator approval; never
+      autonomous.
+
+  - id: history-rewrite-on-protected
+    severity: S1
+    reason: >-
+      history rewrite (rebase/amend/filter-branch) on protected branch
+      '{branch}' is never allowed.
+
+  - id: unbounded-rm
+    severity: S1
+    reason: >-
+      rm -rf is only allowed inside workspaces/ or state/.
+
+# ---------------------------------------------------------------------------
+# The judge sandbox
+# ---------------------------------------------------------------------------
+#
+# Everything above applies to every agent session. This block applies to one
+# additional condition: a `smith sandbox open` lease is active over the
+# directory the command will run in (factory/orchestrator/src/sandbox.ts).
+# The orchestrator opens a lease before handing a worktree to one of the six
+# read-only judge roles and closes it after.
+#
+# Why it exists: "judges are read-only" was, until now, a sentence in
+# .claude/agents/*.md plus a fingerprint comparison after the fact
+# (immutability.ts). The prose is not enforcement, and the fingerprint is a
+# detector — by the time it fires the write has already landed and the
+# verdict is already untrustworthy. It also cannot see the two things that
+# leave no git trace at all: a judge reaching the network, and a judge
+# writing outside its worktree. Judge roles hold `Read, Grep, Glob, Bash` and
+# no `Edit`/`Write`, so Bash is the only write path a judge has, and the
+# PreToolUse hook already sits on every Bash call — which is what makes
+# refusing up front possible rather than aspirational.
+#
+# What it is not: a container, a seccomp profile, or a read-only mount. A
+# command that writes through an interpreter (`python3 -c "open(...,'w')"`)
+# is invisible to a matcher, and always will be. `smith worktree verify`
+# stays in the pipeline behind this for exactly that reason. Both halves are
+# stated in docs/standards/guardrails.md; neither is sold as the other.
+#
+# The bias here is the opposite of the guard shim's. `guard.sh` answers `ask`
+# rather than `deny` when it cannot decide, because a hook that dead-ends
+# leaves the factory unrepairable from inside. A sandbox rule that
+# over-refuses costs a judge one command and shows the operator exactly which
+# one — nothing deadlocks, because the orchestrator holds the lease and the
+# work continues the moment it closes. So these matchers lean towards
+# refusing, and the lists below are deliberately generous.
+judge_sandbox:
+  # The roles this rule set is written for: the six that hold `Bash` and no
+  # `Edit`/`Write` (.claude/agents/*.md). `researcher` is deliberately absent
+  # — fetching is its job, and it is never leased. A lease is matched to a
+  # rule set by role, and a role named in neither list falls back to *this*
+  # one, so the list is the vocabulary `smith sandbox open --role` validates
+  # against rather than a gate of its own.
+  roles: [reviewer, verifier, spec-reviewer, security-reviewer, grader, uiux]
+
+  # The only paths a judge may write, repo-root-relative. Both are the
+  # judge's own output: `state/results/<task-id>.<role>.json` is the verdict
+  # artifact every judge template already names, and `state/artifacts/` is
+  # where a task's declared evidence lives (P9-22).
+  write_roots: [state/results, state/artifacts]
+
+  # Bare command words that reach the network. Matched in command position
+  # (start of a chain segment, or after whitespace) and followed by
+  # whitespace or end-of-segment, so `grep -r x src/nc/` does not read as
+  # `nc` — see policy.ts's `hasCommandWord`.
+  network_commands:
+    [curl, wget, nc, ncat, netcat, telnet, ssh, scp, sftp, rsync, ftp, gh, glab, http, httpie,
+     aria2c, npx, bunx, pnpx]
+
+  # Command + subcommand pairs that reach the network. `git fetch`/`remote`
+  # are here rather than under writes because their side effect is outbound,
+  # and an install subcommand is both a fetch and a mutation of the tree.
+  network_subcommands:
+    - { command: git, subcommands: [push, pull, fetch, clone, remote, submodule] }
+    - { command: npm, subcommands: [install, i, add, ci, update, publish, exec, link] }
+    - { command: pnpm, subcommands: [install, i, add, update, publish, dlx, link] }
+    - { command: yarn, subcommands: [install, add, upgrade, publish] }
+    - { command: bun, subcommands: [install, add, update, publish] }
+    - { command: pip, subcommands: [install, download, uninstall] }
+    - { command: pip3, subcommands: [install, download, uninstall] }
+    - { command: uv, subcommands: [add, sync, pip] }
+    - { command: brew, subcommands: [install, upgrade, update, tap] }
+    - { command: cargo, subcommands: [install, publish, add] }
+    - { command: go, subcommands: [get, install] }
+
+  # Write verbs whose arguments are all targets. Allowed when every non-flag
+  # argument resolves under a `write_roots` entry — `mkdir -p state/results`
+  # is a judge preparing to write its own verdict, and refusing it would
+  # refuse the one thing a judge is supposed to do.
+  target_write_commands: [tee, mkdir, touch]
+
+  # Write verbs refused outright inside a sandbox, no path check. A judge
+  # writes its verdict by redirecting into a write root; it has no business
+  # moving, copying, deleting, patching or chmod-ing anything, and the
+  # allowlist that would make `cp a b` decidable (which token is the target?)
+  # is more machinery than the single legitimate case is worth. `rm` is here
+  # even though the `unbounded-rm` rule above would permit `rm state/...`:
+  # inside a sandbox, `state/` holds other judges' verdicts and this judge's
+  # own lease.
+  refused_write_commands:
+    [rm, rmdir, mv, cp, ln, dd, truncate, shred, install, patch, chmod, chown, chgrp,
+     vi, vim, nano, emacs, ed, pico]
+
+  # git subcommands that mutate a worktree, the index, refs, or config.
+  # `git add`/`commit`/`checkout`/`stash`/`restore` are the five
+  # .claude/agents/reviewer.md already names in prose; the rest close the
+  # same door from the other side.
+  git_write_subcommands:
+    [add, commit, checkout, switch, restore, stash, apply, am, reset, clean, rm, mv,
+     cherry-pick, revert, rebase, merge, config, tag, worktree, notes, update-ref,
+     update-index, gc, prune]
+
+  rules:
+    - id: judge-network
+      severity: S1
+      reason: >-
+        a {role} judge session has no outbound access — no fetch, no remote
+        git, no package install. Judge what is in the worktree, and record
+        what you could not verify as a finding rather than going to get it.
+
+    - id: judge-write
+      severity: S1
+      reason: >-
+        a {role} judge session writes nothing but its own verdict. Redirect
+        into {write_roots}; every other write is refused while the sandbox is
+        open. If the code needs changing, that is a finding, not an edit.
+
+    - id: judge-sandbox-escape
+      severity: S1
+      reason: >-
+        a {role} judge cannot open, close or inspect its own sandbox lease —
+        the orchestrator that opened it closes it when the verdict is in.
+
+# ---------------------------------------------------------------------------
+# Roles that write, but not everywhere.
+#
+# The judge sandbox answers one question — "may this role write at all?" — and
+# for a judge the answer is no. A tester writes plenty. What it must not write
+# is the thing it is grading: a tester that can edit `src/` can make a failing
+# test pass by changing the implementation, which is the same self-marking the
+# fresh-context reviewer exists to prevent, arriving one gate earlier.
+#
+# So: the same lease machinery, a different rule set selected by role.
+#
+# Two differences from the judge rules follow from the role actually being
+# allowed to write. `git add`/`commit` stay allowed, because the tester's
+# output contract *requires* a commit on the task branch — only the git
+# subcommands that change tracked content without passing a path check are
+# refused. And `rm` is path-checked rather than refused outright, because
+# deleting a stale test is ordinary tester work.
+#
+# `judge-sandbox-escape` is not listed here because it is not role-dependent:
+# a lease its holder can lift is not a lease, whichever rule set the role
+# draws the rest of its bounds from.
+role_write_scopes:
+  scopes:
+    - role: tester
+      # Repo-root-relative globs (picomatch, posix separators). A directory
+      # counts as in scope when something inside it would be, so
+      # `mkdir -p factory/orchestrator/test/fixtures` is allowed.
+      write_globs:
+        - "**/*.test.ts"
+        - "**/*.test.tsx"
+        - "**/*.spec.ts"
+        - "**/*.spec.tsx"
+        - "**/test/**"
+        - "**/tests/**"
+        - "**/__tests__/**"
+        - "**/__snapshots__/**"
+        - "**/e2e/**"
+        - "state/results/**"
+        - "state/artifacts/**"
+
+      # Write verbs refused with no path check, for the reason the judge
+      # sandbox gives: deciding which token of `cp a b` is the target is more
+      # machinery than the legitimate cases justify — and this role holds
+      # `Edit` and `Write`, which *are* path-checked, as the better route to
+      # the same edit. `install` is absent on purpose: the tester runs the
+      # suite, and `npx playwright install chromium` is not the BSD `install`
+      # verb.
+      refused_commands:
+        [cp, mv, ln, dd, truncate, shred, patch, chmod, chown, chgrp,
+         vi, vim, nano, emacs, ed, pico]
+
+      # git subcommands that put tracked content back under the tester's
+      # control without passing a path check. `add`, `commit`, `switch`,
+      # `status` and `diff` are deliberately absent — the first two are the
+      # tester's output contract.
+      refused_git_subcommands: [apply, am, cherry-pick, revert, reset, clean, checkout, restore, stash]
+
+  rules:
+    - id: role-write-scope
+      severity: S1
+      reason: >-
+        a {role} session writes only {write_globs}. The implementation
+        belongs to the coder, and a test whose subject the tester may edit
+        is a test that grades itself. If the code is wrong, that is a
+        finding, not an edit.