@juzser/blacksmith 0.1.0

package/factory/policies/lessons.md

@@ -0,0 +1,239 @@
+# Compiled Lessons
+
+> Generated, committed file. This is the compiled output of the approved
+> lesson queue — the operator approves candidates in the UI (Lessons page,
+> architecture §10); the scribe compiles approvals here, sectioned by scope.
+> Never hand-edit an entry's content directly; edit the source lesson and
+> recompile, so `valid_from`/`superseded_by`/provenance stay accurate.
+
+## Schema
+
+Every entry below is one lesson (`factory/specs/schema/lesson.schema.json`):
+
+- **Typed, one type per entry, never mixed** — `lesson_type`: `fact` (stable
+  truth about a repo/stack, e.g. "D1 lacks X"), `event` (dated occurrence,
+  e.g. "epic-7 hit deadlock via Y"), or `rule` (imperative, checkable
+  principle, e.g. "never edit lockfiles in workers").
+- **Principle-level only** (`lesson_level: principle`) — instance-level
+  transcripts are rejected at the novelty gate before reaching this file;
+  naive experience accumulation measurably degrades agents (architecture §9,
+  §17).
+- **Bi-temporal fields**: `valid_from` (when the lesson took effect) and
+  `superseded_by` (the lesson_id that replaced it, or null) — a lesson is
+  never deleted or silently edited, only superseded or `invalidated` with a
+  pointer to the invalidating event.
+- **Provenance**: `provenance_event_ids` — the event-log entries that
+  produced the lesson, so every entry here is traceable back to a decision
+  checkpoint or logged error, never asserted from nowhere.
+- **Injection is step-wise, not global preamble**: each entry's `lesson_scope`
+  (`agent-role` | `claim-path` | `case-type` | `stack-wide` | `security`)
+  determines where it is surfaced — e.g. a coder gets claim-path-scoped rules
+  at dispatch, a merger gets integration rules at queue time. Standing
+  architectural constraints are re-asserted in every task contract, never
+  stated once per epic (constraint-decay countermeasure).
+
+Entries are grouped by `lesson_scope` below; a scope with no approved lesson
+renders as an empty section rather than disappearing, so the set of scopes
+this file can carry is visible whether or not anything occupies them.
+
+### Same-mistake entry format (Phase 4, `factory/orchestrator/src/severity.ts`)
+
+The severity gate's same-mistake escalation (architecture §9.7, §11) parses
+this file's compiled entries at gate time — match = a `rule`-typed entry's
+scope covers the file the new finding touches AND its `finding_category`
+equals the new finding's category. So the scribe compiles each `rule` entry
+as a level-3 heading followed by a flat `key: value` bullet list, terminated
+by the next heading or end of file (a blank line does NOT end the entry —
+see the multi-line `statement` below, whose continuation line is indented
+and gets folded back onto the bullet it follows), e.g.:
+
+```
+### Never hand-edit a lockfile in a worker
+
+- lesson_id: lesson-2026-08-01-003
+- finding_category: maintainability
+- claim_path: **/pnpm-lock.yaml
+- statement: Lockfiles are regenerable and regenerated by the merge queue;
+  a worker editing one directly is always a mistake, not a judgment call.
+```
+
+`claim_path` is a glob (matched with `picomatch`, same engine as
+`claims.ts`); required for `claim-path`-scoped entries, and treated as
+`**` (covers every file) for `stack-wide`- and `security`-scoped entries
+where it is omitted. `agent-role`/`case-type`-scoped entries do not
+participate in this per-file match (no file to check against) and are parsed
+but never matched by `severity.ts` — they exist here for prompt injection
+only.
+
+### Every scope carries its own selector
+
+Three of the five scopes are *selectors*, and a selector needs something to
+select on. Each names its own bullet, validated against `taxonomy.yml`:
+
+| scope | selector bullet | taxonomy dimension |
+| --- | --- | --- |
+| `claim-path` | `claim_path` | — (a glob) |
+| `agent-role` | `agent_role` | `agent` |
+| `case-type` | `case_type` | `case` |
+| `stack-wide` | none — applies to every dispatch | — |
+| `security` | none — cross-role by design | — |
+
+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
+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
+escalate anything — by design, not by accident:
+
+- an `agent-role`- or `case-type`-scoped entry, per the paragraph above; and
+- **any entry with no `finding_category`**, whatever its scope — the match
+  above is an equality against the new finding's category, so an entry naming
+  no category is skipped before its claim path is ever consulted.
+
+A broad principle usually belongs in the second kind. An entry that pairs a
+category with `claim_path: **` escalates *every* repeat finding of that
+category anywhere in the repo — a gate that fires on everything distinguishes
+nothing.
+
+## agent-role
+
+### lesson-raised-8c05427c2840: A check that silently borrows its tools from the inspector is measuri...
+
+- lesson_id: lesson-raised-8c05427c2840
+- agent_role: grader
+- statement: A check that silently borrows its tools from the inspector is measuring the inspector.
+
+### lesson-dream-dogfood-demo-rpg-1-40: A judge's output contract fixes where the verdict sits as strictly as...
+
+- lesson_id: lesson-dream-dogfood-demo-rpg-1-40
+- agent_role: grader
+- statement: A judge's output contract fixes where the verdict sits as strictly as what it says: a correct verdict at the wrong key is read as no verdict at all.
+
+## claim-path
+
+### lesson-raised-3b5746704cfc: A function that computes a filesystem path and hands it to a child pr...
+
+- lesson_id: lesson-raised-3b5746704cfc
+- claim_path: **
+- statement: A function that computes a filesystem path and hands it to a child process running with a different cwd must resolve it to absolute first.
+
+### lesson-raised-8460b7c5cd04: A `**/name*/**` glob matches a directory, never a file of that name.
+
+- lesson_id: lesson-raised-8460b7c5cd04
+- claim_path: **
+- statement: A `**/name*/**` glob matches a directory, never a file of that name.
+
+### lesson-raised-a8ca3a355263: An identifier that is parsed rather than passed will eventually be pa...
+
+- lesson_id: lesson-raised-a8ca3a355263
+- claim_path: **
+- statement: An identifier that is parsed rather than passed will eventually be parsed by two functions that disagree, and the disagreement surfaces at the join — the last step, and the most expensive place to find it.
+
+### lesson-raised-fe5cf8b630fe: A wrapper that collapses a child's exit signal into an exit code has ...
+
+- lesson_id: lesson-raised-fe5cf8b630fe
+- claim_path: **
+- statement: A wrapper that collapses a child's exit signal into an exit code has deleted the only evidence that distinguishes a crash from a failure, and every diagnosis downstream of it will be about the wrong subsystem.
+
+## case-type
+
+_(none yet)_
+
+## stack-wide
+
+### lesson-raised-53d48e95c31f: Measured spend is a floor, not a total; a check that treats it as a t...
+
+- lesson_id: lesson-raised-53d48e95c31f
+- statement: Measured spend is a floor, not a total; a check that treats it as a total reports "under budget" most confidently on exactly the runs whose unrecorded half is what blew the budget.
+
+### lesson-raised-8a3f8df1fc0e: A differential acceptance criterion must state what the failing outpu...
+
+- lesson_id: lesson-raised-8a3f8df1fc0e
+- statement: A differential acceptance criterion must state what the failing output says under the hypothesis and under the null; if the two are the same text, the criterion is vacuous.
+
+### lesson-raised-cbdae7931913: A constraint stated only in a prompt is a request; if the plan writes...
+
+- lesson_id: lesson-raised-cbdae7931913
+- statement: A constraint stated only in a prompt is a request; if the plan writes it down like a limit, something has to be able to say no.
+
+### lesson-raised-f6b72d19c070: When one stage verifies state A and the next ships state B, the pipel...
+
+- lesson_id: lesson-raised-f6b72d19c070
+- statement: When one stage verifies state A and the next ships state B, the pipeline is correct only by coincidence.
+
+### lesson-raised-c60ff6d8cd89: A supervisor that cannot tell silence from assent will eventually mis...
+
+- lesson_id: lesson-raised-c60ff6d8cd89
+- statement: A supervisor that cannot tell silence from assent will eventually mistake a corpse for a quorum.
+
+### lesson-raised-c599f971488d: Never ask a component for a fact it has no instrument to measure; it ...
+
+- lesson_id: lesson-raised-c599f971488d
+- statement: Never ask a component for a fact it has no instrument to measure; it will not refuse, it will estimate, and the estimate will look exactly like data.
+
+### lesson-raised-e0befb1eb07f: A controlled vocabulary that is referenced but never shown is a vocab...
+
+- lesson_id: lesson-raised-e0befb1eb07f
+- statement: A controlled vocabulary that is referenced but never shown is a vocabulary the writer will reinvent.
+
+### lesson-raised-26ace63a7a67: Plan immutability is a promise to the builder, not to reality; a syst...
+
+- lesson_id: lesson-raised-26ace63a7a67
+- statement: Plan immutability is a promise to the builder, not to reality; a system that can only blame the builder will deadlock the moment the plan is what is wrong.
+
+### lesson-raised-4b7fa22305e5: Two features that each refuse to guess can still deadlock, because re...
+
+- lesson_id: lesson-raised-4b7fa22305e5
+- statement: Two features that each refuse to guess can still deadlock, because refusing is not the same as agreeing on who decides; a system that mints work in one component and validates it in another must share one answer to "does this task exist", not two correct ones.
+
+### lesson-dream-dogfood-demo-rpg-1-31: Producing a file and delivering it are separate acts: the artifact ch...
+
+- lesson_id: lesson-dream-dogfood-demo-rpg-1-31
+- statement: Producing a file and delivering it are separate acts: the artifact check resolves every declared path under the task's artifact home, so a Result that names a file living only in the worktree is indistinguishable from one that produced nothing.
+
+### lesson-dream-dogfood-demo-rpg-1-182: An acceptance criterion that has already been graded is a record of w...
+
+- lesson_id: lesson-dream-dogfood-demo-rpg-1-182
+- statement: An acceptance criterion that has already been graded is a record of what was checked, so a defect in its wording is corrected by an appended note, never by superseding the text the grader actually read.
+
+### lesson-raised-7c35d8a04a94: A command that creates an obligation must be validated against the co...
+
+- lesson_id: lesson-raised-7c35d8a04a94
+- statement: A command that creates an obligation must be validated against the command that discharges it for the same role, or accepting the registration is a deadlock rather than a contract.
+
+### lesson-raised-5111dfe40703: Judges may run concurrently against one worktree only while all of th...
+
+- lesson_id: lesson-raised-5111dfe40703
+- statement: Judges may run concurrently against one worktree only while all of them are read-only; the moment any probe must write, the whole set must be serialized, because the isolation protocol is per-judge and assumes no overlap.
+
+### lesson-raised-3bd5fc1b8057: A worktree verifier that compares before and after cannot see an edit...
+
+- lesson_id: lesson-raised-3bd5fc1b8057
+- statement: A worktree verifier that compares before and after cannot see an edit that was reverted in between, so a clean verdict is evidence about the endpoints and never evidence that a concurrent reader saw a clean tree.
+
+### lesson-raised-039f35d42340: A result produced during a contaminated window may be readmitted only...
+
+- lesson_id: lesson-raised-039f35d42340
+- statement: A result produced during a contaminated window may be readmitted only if its evidence axis is disjoint from every mutated path and each claim is re-verified against committed git objects rather than the working tree.
+
+### lesson-raised-576ea7016b55: A dispatch prompt that spells out schema field names becomes a second...
+
+- lesson_id: lesson-raised-576ea7016b55
+- statement: A dispatch prompt that spells out schema field names becomes a second, drifting copy of the schema, and the agent will faithfully emit the names it was given rather than the ones the validator knows.
+
+### lesson-raised-818285deeda6: A missing required field must fail at the boundary with an error that...
+
+- lesson_id: lesson-raised-818285deeda6
+- statement: A missing required field must fail at the boundary with an error that names it; passed downstream it surfaces as an unhandled TypeError inside a helper that never knew which field was absent.
+
+### lesson-raised-b8db8efe922d: An agent that owes a file should write it before refining it: the dec...
+
+- lesson_id: lesson-raised-b8db8efe922d
+- statement: An agent that owes a file should write it before refining it: the declared-artifact check catches an agent that ended on an intention only after the tokens are spent, and if that agent could write to shared state, only after the damage has spread.
+
+## security
+
+_(none yet)_

package/factory/policies/scheduler.yml

@@ -0,0 +1,90 @@
+# Blacksmith — scheduler policy
+#
+# Knobs for `factory/orchestrator/src/scheduler.ts` (architecture §12
+# "Recheck scheduling" + "Scheduled growth passes"; `smith 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.
+
+recheck:
+  # architecture §12: "re-open a recheck task when (a) N later merges touch
+  # its claim paths, (b) T days elapse, or (c) its confidence score at
+  # completion was below a threshold."
+  merge_threshold: 5 # (a) N later merges touching the same claim paths
+  days_elapsed: 14 # (b) T days since the feature completed
+  confidence_threshold: 0.6 # (c) completion confidence below this triggers a recheck
+
+maintenance:
+  # agent-constraints.md "planner / Growth passes": maintenance-pass
+  # proposals may auto-schedule at high confidence; product-growth never
+  # does. Confidence here is scheduler.ts's own deterministic heuristic
+  # (major-version bumps present -> lower confidence), not a model verdict.
+  auto_schedule_confidence: 0.8
+  major_bump_confidence: 0.5
+  minor_or_patch_confidence: 0.9
+
+growth:
+  # architecture §12 "product-growth pass": the scheduler only emits the
+  # growth-review-due TRIGGER event on this cadence — the planner session
+  # is the one that reads the living spec/analytics and proposes scope, and
+  # that proposal always waits for an operator tick regardless of confidence.
+  cadence_days: 30
+
+lessons:
+  # architecture §9.3 novelty gate: cheap deterministic similarity
+  # (normalized word-shingle Jaccard) against existing candidate + approved
+  # lesson statements. >= this score is "clearly redundant" -> auto
+  # novelty-rejected, no LLM call. Below it, Phase 7 queues the candidate as
+  # novel; the "uncertain -> one LLM merge step" middle tier architecture §9
+  # describes (SAGE) is a documented future upgrade, not built here.
+  novelty_jaccard_threshold: 0.8
+  shingle_size: 3
+  # Correct that threshold for how long the two statements are before
+  # comparing them (P9-35 (a)). A statement has n-s+1 shingles, and changing
+  # one word destroys s of them, so nothing shorter than ~29 words can score
+  # 0.8 against its own near-copy: at a fixed bar, restating a shorter lesson
+  # with one word changed read as a new lesson. Set false for one bar per
+  # pair; below 2*shingle_size+1 words the correction stands aside either way,
+  # because there a one-word edit and a coincidence score the same.
+  novelty_length_aware: true
+
+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
+  # enacts nothing — it prints the classification so it can be read and
+  # argued with before anything moves.
+  #
+  # The operator's standing decision, 2026-09-02: auto-dispatch with a
+  # whitelist. Rechecks and maintenance may run themselves; growth review
+  # and anything touching a security surface always wait; PRs are still
+  # merged by a person, which is the backstop that makes this safe to widen.
+  enabled: true
+
+  # Nothing outside this list is ever auto-dispatched, and listing
+  # `growth-review-due` would not change that: architecture §12 keeps scope
+  # with the operator unconditionally, so autonomy.ts denies it whatever this
+  # says. The list is a ceiling, never a floor.
+  auto_dispatch_kinds: [recheck, maintenance]
+
+  # Rechecks are whitelisted BY REASON, and this is the one knob in the file
+  # that is easy to get backwards. A RecheckProposal's `confidence` is the
+  # COMPLETED TASK's confidence, and a low one is why the recheck exists at
+  # all — gating rechecks on confidence the way maintenance is gated would
+  # hold back precisely the rechecks worth running. So:
+  #   merge-threshold  — N later merges touched its claims; re-running the
+  #                      same checks against moved ground is routine.
+  #   time-elapsed     — T days passed; likewise routine.
+  #   low-confidence   — the work itself was uncertain when it completed.
+  #                      Left out: that is a judgement about quality, and it
+  #                      is the operator who should read it first.
+  # One unlisted reason holds the whole proposal — a recheck is dispatched
+  # once and carries every reason with it.
+  auto_dispatch_recheck_reasons: [merge-threshold, time-elapsed]
+
+  # Maintenance only. Matches maintenance.auto_schedule_confidence above,
+  # repeated rather than imported for the same reason crosscheck.yml repeats
+  # its own copy: "auto-schedulable" and "may run unattended" are allowed to
+  # diverge later, and the day they do, one of them moving must not move the
+  # other by accident. scheduler.ts scores a major-version bump at 0.5
+  # precisely so a person reads it.
+  confidence_floor: 0.8

package/factory/policies/sensitive-paths.yml

@@ -0,0 +1,148 @@
+# Sensitive claim paths — the security-reviewer's dispatch trigger.
+#
+# The security-reviewer is conditional dispatch only (agent-constraints.md:
+# security-reviewer). Trigger 1 of its three is "the task's claims intersect
+# sensitive paths", and until this file existed that intersection was a
+# judgment call made fresh on every dispatch — which is the same as saying
+# some tasks got a security review because the dispatcher happened to
+# recognise the path, and others did not (agent-interviews.md N-7).
+#
+# Scope note: this file is about *paths*. crosscheck.yml's `security_keywords`
+# is about *nonfunctional clause text* and gates plan quorum, not
+# security-reviewer dispatch. Two different questions, deliberately two lists —
+# 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
+# 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
+# list. Match semantics live with the host; the two rules worth knowing before
+# editing globs below are stated inline.
+
+version: 1
+
+# Matched against a task spec's `claims[]` globs, not against the diff: the
+# review is dispatched before the diff is judged, and a claim is the earliest
+# honest signal that a task is allowed to touch one of these paths.
+#
+# Match semantics: a task fires the trigger when any of its claims *overlaps*
+# any glob here — not when it is contained by one. A claim of `src/**` overlaps
+# `src/auth/**` and must fire, even though it is the wider pattern.
+# Containment-only matching is the failure mode where a broadly scoped task
+# escapes the review that a narrowly scoped one gets. The direct consequence:
+# an open-ended `<dir>/**` claim fires most of the directory globs below,
+# because such a task really could add `<dir>/auth/session.ts` tomorrow.
+#
+# Every directory entry (`**/auth/**`) needs a file-level sibling
+# (`**/*auth*.{ts,...}`), because half the real world puts the whole concern in
+# one file: `src/parse.ts`, not `src/parse/index.ts`. Measured on a real epic,
+# the directory-only version of this list scored one hit for six tasks, and the
+# one hit was the wrong one (dogfood-envkit-findings.md D-25).
+globs:
+  # Authentication, authorization, session handling. `*auth*` also catches
+  # `oauth`, and `authors.ts` in a blog — firing on a false friend costs one
+  # review; missing `src/auth.ts` costs the review that mattered.
+  - "**/auth/**"
+  - "**/authn/**"
+  - "**/authz/**"
+  - "**/*auth*.{ts,tsx,js,jsx,py,go,rs,rb,java}"
+  - "**/session/**"
+  - "**/*session*.{ts,tsx,js,jsx,py,go,rs,rb,java}"
+  - "**/middleware/**"
+  - "**/*middleware*.{ts,tsx,js,jsx,py,go,rs,rb,java}"
+  - "**/guard*/**"
+  - "**/*guard*.{ts,tsx,js,jsx,py,go,rs,rb,java}"
+  - "**/permission*/**"
+  - "**/*permission*.{ts,tsx,js,jsx,py,go,rs,rb,java}"
+  - "**/*rbac*"
+
+  # Secrets, keys, credentials, and the config surfaces that carry them.
+  - "**/secret*/**"
+  - "**/*secret*.{ts,tsx,js,jsx,py,go,rs,rb,java}"
+  - "**/credential*/**"
+  - "**/*credential*.{ts,tsx,js,jsx,py,go,rs,rb,java}"
+  - "**/*.env*" # matched with dot:true, so a bare `.env` fires
+  - "**/config/secrets*"
+  - "**/keys/**"
+  - "**/*keystore*"
+
+  # Cryptography — including "helpers" wrapping a library, which is where the
+  # mistakes actually live.
+  - "**/crypto/**"
+  - "**/*crypt*.{ts,tsx,js,jsx,py,go,rs,rb,java}"
+  - "**/*hash*.{ts,tsx,js,jsx,py,go,rs,rb,java}"
+  - "**/*signature*"
+  - "**/*jwt*"
+
+  # Input parsing and deserialization — the untrusted-data boundary.
+  # `*parse*`, not `*parser*`: the file that exists is `src/parse.ts`.
+  - "**/parse*/**"
+  - "**/*parse*.{ts,tsx,js,jsx,py,go,rs,rb,java}"
+  - "**/serializ*/**"
+  - "**/deserializ*/**"
+  - "**/*serializ*.{ts,tsx,js,jsx,py,go,rs,rb,java}" # also catches deserialize*
+  - "**/upload*/**"
+  - "**/*upload*.{ts,tsx,js,jsx,py,go,rs,rb,java}"
+  - "**/sanitiz*/**"
+  - "**/*sanitiz*.{ts,tsx,js,jsx,py,go,rs,rb,java}"
+  - "**/validat*/**"
+  - "**/*validat*.{ts,tsx,js,jsx,py,go,rs,rb,java}"
+
+  # Network boundary — anything that accepts or originates a request.
+  - "**/api/**"
+  - "**/routes/**"
+  - "**/*route*.{ts,tsx,js,jsx,py,go,rs,rb,java}"
+  - "**/handlers/**"
+  - "**/*handler*.{ts,tsx,js,jsx,py,go,rs,rb,java}"
+  - "**/controllers/**"
+  - "**/*controller*.{ts,tsx,js,jsx,py,go,rs,rb,java}"
+  - "**/graphql/**"
+  - "**/*graphql*"
+  - "**/webhook*/**"
+  - "**/*webhook*.{ts,tsx,js,jsx,py,go,rs,rb,java}"
+  - "**/cors*"
+
+  # Data access — injection surface and the blast radius of a bad query.
+  - "**/migrations/**"
+  - "**/*migration*.{ts,tsx,js,jsx,py,go,rs,rb,java,sql}"
+  - "**/*.sql"
+  - "**/db/**"
+  - "**/repositor*/**"
+  - "**/*repositor*.{ts,tsx,js,jsx,py,go,rs,rb,java}"
+
+  # Process and supply-chain boundary. Lockfiles are listed three ways because
+  # `**/*.lock` alone misses `pnpm-lock.yaml` and `package-lock.json` — the
+  # lockfiles a JS project actually has.
+  - "**/Dockerfile*"
+  - "**/.github/workflows/**"
+  - "**/*.lock"
+  - "**/*.lockb"
+  - "**/*lock*.{yaml,json}"
+  - "**/package.json" # a dependency bump is a supply-chain event; kept whole until a host can read the diff
+  - "**/scripts/**"
+
+# Paths that match a glob above but are not worth a security review. Kept
+# short on purpose: every entry here is a hole, and a long exclusion list is
+# how a trigger quietly stops firing.
+#
+# Exclusions are checked after globs and are *containment*, not overlap: a
+# claim is silenced only when it lies entirely inside one of these. Overlap
+# would let `**/*.test.ts` silence `src/**`, which is the same escape hatch the
+# match semantics above exist to close.
+exclude:
+  - "**/*.test.{ts,tsx,js,jsx,py,go,rs,rb,java}"
+  - "**/*.spec.{ts,tsx,js,jsx,py,go,rs,rb,java}"
+  - "**/__tests__/**"
+  - "**/*.md"
+  - "**/*.snap"
+
+# The other two triggers, recorded here so the whole dispatch condition reads
+# from one file even though only the first is path-based.
+other_triggers:
+  # taxonomy.yml `case` vocabulary, matched against the task spec's own `case`
+  # — the only place a case is recorded today. Read under the older
+  # `epic_cases` spelling too.
+  cases: [infra]
+  epic_tags: [security] # a security-tagged epic reviews every task; operator-supplied, nothing in the schema carries tags yet
+  scheduled_recheck: true # scheduler.yml may re-open a sensitive claim path

package/factory/policies/severity.yml

@@ -0,0 +1,83 @@
+# Blacksmith — severity policy
+#
+# S1..S4 gate rules (architecture §11, agent-constraints.md "reviewer /
+# verifier", guardrails.md). Severity values themselves are taxonomy-owned
+# (factory/policies/taxonomy.yml: severity) — this file defines what each
+# value *does* at the gate, not the vocabulary.
+
+levels:
+  S1-stop-the-line:
+    blocks_merge: true
+    semantics: stop-the-line
+    classes:
+      # guardrails.md: violations are S1 unless stated otherwise
+      - repo corruption
+      - secret leak
+      - guardrail breach (push to main/master, force-push, history rewrite
+        on a shared branch, merge to main by the factory, destructive git ops
+        outside a worktree, deploy without operator approval, autonomous
+        outbound send)
+      - out-of-claim edit that touches a guardrail-protected file
+    on_trigger: >
+      stop the run immediately; no bounded retry; operator notified
+      synchronously (not batched).
+
+  S2-major:
+    blocks_merge: true
+    semantics: hard block, bounce to coder on the same branch
+    classes:
+      - security / data-loss
+      - broken core flow
+      - a11y WCAG AA failure
+      - new flaky test introduced by the task
+      - behavioral-drift touching a core flow
+    on_trigger: >
+      bounce to coder on the same branch; after 2 failed rounds, escalate
+      model tier (sonnet -> opus, budgets.yml); after 3, escalate to
+      operator.
+
+  S3-minor:
+    blocks_merge: false
+    semantics: waivable — batched to operator at epic end
+    classes:
+      - visual regression vs the uiux spec
+      - performance regression > 20%
+      - over-engineering (default severity — see rule below)
+      - behavioral-drift not touching a core flow
+      - everything minor-but-real that doesn't meet an S2 class
+    on_trigger: >
+      does not block; queued into a single batched waiver question at epic
+      end ("ignore these?"). Waiver answers are stored by finding
+      fingerprint, keyed for reuse — the same finding is never asked twice,
+      and waived findings are suppressed in future reviews of the same code.
+
+  S4-nit:
+    blocks_merge: false
+    semantics: logged, never asked
+    classes:
+      - style/naming nits the project's linter does not catch
+    on_trigger: log only; no operator interaction.
+
+rules:
+  over_engineering_default: S3
+  over_engineering_note: >
+    Enforced by the reviewer's over-engineering lens per agent-constraints.md
+    coder effort discipline (YAGNI). Findings surface as S3 with a proposed
+    simplification, waiver-batched like any other S3.
+  same_mistake_escalation: >
+    A finding matching an approved lesson (finding_status match against
+    factory/policies/lessons.md by claim path / case type) is auto-escalated
+    one severity level and tagged judgment.same-mistake — including
+    over-engineering S3 -> S2 once a matching lesson is approved.
+  waiver_semantics: >
+    Only S3/S4 findings are ever waived. S1/S2 cannot be waived; they must be
+    fixed or the task returns through the escalation ladder
+    (budgets.yml: escalation_ladder). A waiver is keyed by finding
+    fingerprint (finding.schema.json) and, once granted, suppresses that
+    exact fingerprint in future reviews of the same code — it is never
+    re-asked.
+  block_semantics: >
+    "Blocks merge" means the merge-queue gate rejects the task's admission
+    into smith/<epic>/integration until the finding's finding_status reaches
+    fix-verified (fix landed and re-passed the gate) or, for S3/S4, waived.
+    A review firing without uptake is not a closed finding.

package/factory/policies/stack.yml

@@ -0,0 +1,60 @@
+# Blacksmith — stack answers
+#
+# 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
+# that needs to know what this operator builds with.
+#
+# This file used to be a document. `docs/standards/stack.md` shipped one
+# operator's 2026-08-03 answers — Vue, Cloudflare, Drizzle, a private design
+# system — written as if they were the product, and every clone of a public
+# repo inherited them. They are answers, so they live here as data, and the
+# defaults below are the ones that assume least: `none` wherever an unanswered
+# 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`
+# 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
+# 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
+# templates implement — today that is `vue` and nothing else.
+frontend: none # none | vue | react | svelte | solid | vite-vanilla | other
+
+# The design system a UI project builds against. `none` means the project owns
+# its own components, which is what a new project has on day one, and what the
+# uiux agent grounds its specs in when there is nothing else to ground them in.
+#
+# Naming one changes two things: the uiux agent is told to spec against it
+# instead of inventing patterns, and `design_system_source` (if set) is
+# vendor-copied into each scaffolded UI project. Vendored, never referenced
+# from an external repo — a design system you cannot build offline is a
+# dependency on someone else's uptime.
+design_system: none # none | <name>
+design_system_source: '' # path to a directory to vendor into <project>/design/, or empty
+
+# The utility layer under the components.
+styling: plain-css # plain-css | tailwind | css-modules | vanilla-extract | other
+
+# ── Backend / runtime ───────────────────────────────────────────────
+backend: none # none | node | deno | bun | cloudflare-workers | other
+database: none # none | sqlite | postgres | mysql | d1 | other
+orm: none # none | drizzle | prisma | kysely | other
+
+# ── Repo shape + tooling ────────────────────────────────────────────
+package_manager: pnpm # pnpm | npm | yarn | bun
+repo_shape: single # single | monorepo
+lint: biome # biome | eslint-prettier | none
+test_unit: vitest # vitest | jest | node-test | none
+test_e2e: playwright # playwright | cypress | none
+ci: github-actions # github-actions | gitlab-ci | circleci | none
+hosting: unspecified # free text — where this operator deploys, or `unspecified`