@juzser/blacksmith 0.1.0

package/factory/policies/taxonomy.yml

@@ -0,0 +1,340 @@
+# Blacksmith — controlled vocabulary (taxonomy)
+#
+# Machine-readable source of truth. Mirrors docs/specs/black-smith-architecture.md
+# §8 value-for-value; if they diverge, that is a bug — fix both in the same PR.
+#
+# Closed, versioned, multi-dimension controlled vocabulary. Every event, task,
+# error, finding, and lesson carries tags from these dimensions; the event
+# logger rejects unknown tags at write time so analytics stay aggregatable
+# across months of runs. Changing the taxonomy is a PR that bumps `version` —
+# never a runtime write. Analytics may group only by taxonomy dimensions.
+
+version: 9
+
+# ── Work classification ─────────────────────────────────────────────
+case:      [feature, bugfix, refactor, research, spec-review, recheck,
+            chore, infra]
+origin:    [user, inferred, recheck, lesson, escalation]
+            # user      — operator asked for it
+            # inferred  — planner added it to protect acceptance criteria
+            # recheck   — scheduler re-opened a completed feature
+            # lesson    — an approved lesson demanded follow-up work
+            # escalation— created by the escalation ladder (e.g. re-scope)
+
+# ── Actors ──────────────────────────────────────────────────────────
+agent:     [planner, spec-reviewer, researcher, coder, tester, grader,
+            reviewer, verifier, security-reviewer, merger, scribe, uiux,
+            wave-runner, auditor]
+            # wave-runner — the only role delegation.yml grants `Agent`: it
+            #   runs one wave of .claude/skills/bs/wave.md in its own session
+            # auditor — one axis of `/bs audit` (performance, code-quality or
+            #   architecture); the security axis dispatches security-reviewer
+
+provider:  [claude, codex, deepseek]
+model_tier: [frontier, mid, small]        # fable/opus · sonnet · haiku
+
+# ── Lifecycle (three distinct state machines — never conflated) ─────
+task_status: [todo, ready, in-progress, grading, reviewing, merging,
+              blocked, completed, waived, failed, escalated, superseded]
+              # superseded — replaced by a task in a newer plan version
+plan_status: [draft, in-review, active, superseded]   # plans are immutable
+run_status:  [queued, running, done, dead]            # one worker run
+
+# ── Graph (event-log first-class, §7) ───────────────────────────────
+edge_type:       [artifact, claim-order, spec-clause, regression-test,
+                  research-brief]
+                  # artifact       — T consumes an output S produced
+                  # claim-order    — serialized because claims overlapped
+                  # spec-clause    — T implements a specific spec clause
+                  # regression-test— T must keep S's tests green
+                  # research-brief — T depends on a researcher brief
+edge_provenance: [observed, declared, inferred]
+                  # observed — runner saw the handoff happen
+                  # declared — spec stated it up front
+                  # inferred — reconstructed after the fact (lowest trust)
+graph_event:     [plan-version-created, plan-version-superseded,
+                  task-added, task-split, task-superseded, edge-recorded,
+                  wave-admitted, wave-merged,
+                  spec-change-proposed, spec-change-decided]
+                  # spec-change-proposed — a worker hit a wrong assumption and
+                  #                      returned a spec diff. Data, not a
+                  #                      command: no plan file moves (D-33)
+                  # spec-change-decided  — the operator approved or rejected
+                  #                      one. Approval is what calls the
+                  #                      amendment; the version is still cut
+                  #                      by `plan amend` alone
+
+# ── Gates (event-log first-class, §11 — added Phase 4) ───────────────
+gate_event:      [schema-check-result, artifact-check-result,
+                  commit-check-result, deps-check-result,
+                  judges-outstanding, grader-verdict, budget-check-result,
+                  testgate-result, coverage-evidence, integration-check,
+                  spec-review-recorded, goal-check-recorded, quorum-decision,
+                  finding-raised, finding-reverified, finding-suppressed,
+                  finding-transitioned, finding-reattributed,
+                  severity-decisions, waiver-granted, waiver-denied,
+                  gate-outcome]
+                  # schema-check-result — task Result vs result.schema.json
+                  # artifact-check-result — every artifacts[].path in that
+                  #                       Result, resolved against the task's
+                  #                       home under state/artifacts/ and
+                  #                       checked to exist. Emitted even when
+                  #                       the task declared none: a check that
+                  #                       only speaks up when it has something
+                  #                       to say is indistinguishable, later,
+                  #                       from a check that never ran (P9-22)
+                  # commit-check-result — is there a commit here to score? the
+                  #                       worktree is clean and its branch is
+                  #                       ahead of the base (D-30, P9-8)
+                  # deps-check-result   — the worktree owns the toolchain its
+                  #                       checks are about to run (P9-16d);
+                  #                       always logged, including when the
+                  #                       project declares nothing to install
+                  # judges-outstanding  — a judge this task dispatched through
+                  #                       `smith judge dispatch` never reported
+                  #                       back, so the gate refuses to score an
+                  #                       unknown: a missing `--evidence` reads
+                  #                       identically whether the judge found
+                  #                       nothing or died mid-turn. Names each
+                  #                       owed role/round. A task that
+                  #                       dispatched no judges is unaffected —
+                  #                       this refuses only where there is a
+                  #                       promise on record (D-31/D-20, P9-11)
+                  # grader-verdict      — the grader's rubric result vs
+                  #                       grader-verdict.schema.json, and
+                  #                       whether the acceptance criteria were
+                  #                       met. Runs BEFORE the test gate: a
+                  #                       not-met rubric bounces the diff
+                  #                       whatever the suite says (D-34)
+                  # budget-check-result — declared caps vs measured spend:
+                  #                       token_usage off the Result, authored
+                  #                       diff lines off git. Recorded, never
+                  #                       blocking, and emitted even when the
+                  #                       plan declared no budget or the diff
+                  #                       could not be measured — "not-declared"
+                  #                       and "unmeasurable" are outcomes, not
+                  #                       silence (P9-18). "unmeasuredFiles"
+                  #                       names the counted paths git gave no
+                  #                       lines for, so a cap that passed on a
+                  #                       binary file's zero is auditable
+                  #                       (D-157)
+                  # testgate-result     — check-command run (test gate)
+                  # coverage-evidence   — the numbers behind the green: which
+                  #                       subject files the coverage summary
+                  #                       actually measured, and whether it is
+                  #                       complete. Emitted after the tests
+                  #                       pass and before the findings are
+                  #                       judged, because a green run that
+                  #                       cannot name a number for the file the
+                  #                       acceptance criterion is about has not
+                  #                       answered it (D-40, P9-25)
+                  # integration-check   — the check suite run at the PROJECT
+                  #                       ROOT against smith/<epic>/integration,
+                  #                       pinned to the head sha it covers.
+                  #                       Every other gate event above is a
+                  #                       claim about a task worktree; this is
+                  #                       the only one about the assembled
+                  #                       branch, and epic verdict holds
+                  #                       without a current passing one (D-42)
+                  # spec-review-recorded— a spec-reviewer dispatch finished,
+                  #                       pinned to the head sha it read.
+                  #                       Recorded even when it found nothing,
+                  #                       so "ran and was clean" is
+                  #                       distinguishable from "never ran"
+                  # goal-check-recorded — the epic's plan was checked against
+                  #                       the goal its roadmap milestone
+                  #                       declares, clause by clause. The one
+                  #                       gate whose reference text the planner
+                  #                       did not author, so a plan that is
+                  #                       internally consistent but answers the
+                  #                       wrong question still fails it.
+                  #                       Carries the goal digest it read, so a
+                  #                       reworded goal invalidates the check
+                  #                       the same way a new plan version does
+                  # quorum-decision     — one cross-provider quorum case closed:
+                  #                       who voted, on what, and whether the
+                  #                       finding survived. Emitted exactly once
+                  #                       per case, including when the case
+                  #                       could not be decided — an
+                  #                       `insufficient-providers` outcome is a
+                  #                       recorded fact, not an absent one. Runs
+                  #                       over findings at the task gate
+                  #                       (gate.ts) and over plan-cut and
+                  #                       epic-close verdicts (planQuorum.ts,
+                  #                       epic.ts)
+                  # finding-raised      — a new finding entered the log
+                  # finding-reverified  — a human re-read an open finding
+                  #                       against the current code. Not a
+                  #                       finding_status change: `confirmed`
+                  #                       cannot be re-entered and `refuted`
+                  #                       means the finding was wrong, so
+                  #                       "still reproduces" needs an event of
+                  #                       its own. It re-dates the finding's
+                  #                       evidence, which is what clears the
+                  #                       stale-evidence bar on a waiver grant
+                  #                       once a wave has merged over its file
+                  #                       (P9-15)
+                  # finding-suppressed  — raise attempt matched a waived
+                  #                       fingerprint; logged, not appended
+                  #                       as a duplicate raised finding
+                  # finding-transitioned— finding_status state change
+                  # finding-reattributed— the finding moved to the task that
+                  #                       owns the file, or to a follow-up task
+                  #                       minted for it when nobody open could
+                  #                       take it. Without this event the log
+                  #                       shows a finding sitting under a task
+                  #                       that was never gated, and no trace of
+                  #                       how it got there (attribution.ts)
+                  # severity-decisions  — gate.ts's per-finding severity
+                  #                       verdicts for one task (block /
+                  #                       waiver-batch / log-only)
+                  # waiver-granted/-denied — operator waiver-batch answer,
+                  #                       keyed by finding fingerprint
+                  # gate-outcome        — the composed gate pipeline's
+                  #                       final structured result
+
+# ── Errors: grouped two-level classes (always logged as group.class) ─
+error:
+  spec:         [spec-gap, spec-ambiguity, spec-conflict,
+                 missing-nonfunctional]
+                 # missing-nonfunctional — security/validation/authz clause
+                 # absent from the contract (implicit clauses get dropped)
+  contract:     [schema-violation, claim-violation, constraint-decay,
+                 write-root-violation, judge-mutation, uncited-claim,
+                 unsourced-recommendation, uncommitted-work]
+                 # constraint-decay — agent stopped honoring a standing
+                 # architectural constraint mid-epic
+                 # write-root-violation — a role that works outside a worktree
+                 # (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`)
+                 # 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`)
+                 # 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)
+                 # uncommitted-work — a task reported done with work still in
+                 # the working tree, or with a branch head no further along
+                 # than the base it was cut from; the gate scored a worktree
+                 # the queue would have merged as a no-op (D-30, P9-8)
+  execution:    [test-failure, regression, flaky-test, tool-failure,
+                 env-failure]
+                 # regression — previously-passing behavior broken (the
+                 # dominant multi-round failure mode)
+  integration:  [merge-conflict-textual, merge-conflict-semantic,
+                 stack-misorder]
+                 # semantic — textually clean merge, broken behavior
+  economy:      [budget-exceeded, diff-cap-exceeded, over-engineering,
+                 context-overrun]
+  judgment:     [hallucination, false-positive-finding, missed-finding,
+                 reward-hacking, same-mistake, provider-disagreement]
+                 # reward-hacking — letter of the tests, spirit of nothing
+  coordination: [deadlock, livelock, starvation]
+  memory:       [lesson-contamination, lesson-stale, poisoning-suspected]
+
+# ── Review ──────────────────────────────────────────────────────────
+finding_category: [correctness, security, a11y, performance, visual-design,
+                   behavioral-drift, test-coverage, over-engineering,
+                   maintainability]
+                   # visual-design — the rendered result departs from the
+                   # uiux spec. Named for the spec, not for a design system:
+                   # which one a project uses is an install-time answer in
+                   # factory/policies/stack.yml, and `none` is one of them.
+                   # behavioral-drift — changed input validation / error
+                   # handling relative to surrounding code; invisible to
+                   # static metrics, the measured driver of agent-code debt
+finding_scope:    [diff, spec]
+                   # diff — the code is wrong; the fix belongs in a task diff
+                   # spec — the code is right and the PLAN is wrong. Routed to
+                   # the planner and the operator, never to the task gate:
+                   # blocking a diff that cannot legally contain the fix is
+                   # the D-33 deadlock. A finding written before this
+                   # dimension existed carries no scope and reads as `diff`.
+finding_status:   [raised, refuted, confirmed, fix-pending, fix-landed,
+                   fix-verified, waived, expired, amend-pending, amended]
+                   # closes only at fix-verified, waived or amended — a review
+                   # that fired without uptake is not a closed finding
+                   # amended — a spec finding whose criterion moved in a new
+                   # plan version. Spec-scoped only, and the one exit for an
+                   # S1/S2 spec finding, which is categorically unwaivable
+                   # amend-pending — that plan version has been cut and cites
+                   # the finding, but the task ids the amendment added or
+                   # superseded have not landed yet. A spec finding's
+                   # `fix-pending`, and reachable only from raised/confirmed.
+                   # Without it `amended` was reachable at plan-write time, so
+                   # the unwaivable class closed on a sentence (D-127)
+severity:         [S1-stop-the-line, S2-major, S3-minor, S4-nit]
+                   # S1 — repo corruption, secret leak, guardrail breach
+                   # S2 — blocks merge (security/data-loss, broken core
+                   #      flow, a11y AA failure, new flaky test)
+                   # S3 — real but waivable; batched to operator at epic end
+                   # S4 — nits the project's linter misses; logged, never asked
+
+# ── Lessons / memory (typed — one type per entry, never mixed) ──────
+lesson_type:   [fact, event, rule]
+                # fact  — stable truth about a repo/stack ("D1 lacks X")
+                # event — dated occurrence ("epic-7 hit deadlock via Y")
+                # rule  — imperative, checkable principle ("never edit
+                #         lockfiles in workers")
+lesson_level:  [principle]     # instance-level (transcript) entries are
+                               # rejected at the gate — they cause
+                               # capability collapse when accumulated
+lesson_status: [candidate, novelty-rejected, pending-approval, approved,
+                superseded, invalidated]
+lesson_scope:  [agent-role, claim-path, case-type, stack-wide, security]
+                               # `security` cuts across roles: coder, reviewer
+                               # and security-reviewer all want the same auth
+                               # lesson, so it is not an agent-role lesson
+
+# ── Dimension rules (§8 "Dimension rules", normative) ────────────────
+# 1. Required dimensions per record type (validated at write):
+#      task     -> case + origin + task_status
+#      dispatch -> agent + provider + model_tier + model
+#                  `model` is the concrete model id, presence-checked only,
+#                  NOT a closed dimension: model names change monthly and a
+#                  frozen enum would reject next month's model or, worse,
+#                  get the field dropped instead. The tier alone can't
+#                  answer "did the critic run on the finder's model?" —
+#                  opus and fable are both `frontier` (P9-23).
+#      error    -> error(group.class) + severity + task ref
+#      finding  -> finding_category + severity + finding_status
+#      lesson   -> lesson_type + lesson_level + lesson_status + lesson_scope
+#                  + provenance event ids
+#      edge     -> edge_type + edge_provenance
+# 2. One value per dimension — a record needing two values is two records
+#    or a wrongly-cut dimension; fix the taxonomy by PR, don't overload tags.
+# 3. Renames are supersessions — a value is never deleted or renamed in
+#    place; it's marked deprecated in this file with a `superseded_by`, so
+#    old events stay queryable.
+rules:
+  required_dimensions:
+    task:
+      - case
+      - origin
+      - task_status
+    dispatch:
+      - agent
+      - provider
+      - model_tier
+      - model
+    error:
+      - error
+      - severity
+      - task_ref
+    finding:
+      - finding_category
+      - severity
+      - finding_status
+    lesson:
+      - lesson_type
+      - lesson_level
+      - lesson_status
+      - lesson_scope
+      - provenance_event_ids
+    edge:
+      - edge_type
+      - edge_provenance
+  one_value_per_dimension: true
+  renames_are_supersessions: true

package/factory/policies/worktree.yml

@@ -0,0 +1,95 @@
+# Blacksmith — worktree + merge-queue policy
+#
+# architecture §5 "Worktree partitioning (no overlap, no conflicts)".
+# Conflicts are prevented at planning time, not resolved at merge time.
+
+worktree:
+  # D-42 correction (phase 9): worktrees live OUTSIDE the project root, as a
+  # sibling of it. They used to be at "<project>/wt/<task-id>" — inside
+  # the root — and each one is a full checkout carrying the project's
+  # own tool config. A tool that walks down from the project root therefore
+  # found N+1 root configs and refused to run: the envkit epic's `pnpm lint`
+  # exited 1 at the integration root without reading a source file, while all
+  # six per-task lint gates were green (from inside a worktree, the siblings
+  # are not descendants, so no task gate could see it). A sibling path is one
+  # no root-walking tool can reach without climbing up, which retires the
+  # class rather than the one tool.
+  # 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
+  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
+  # 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"
+  rule: workers never touch main/master; only the operator merges the
+    integration PR into the target repo's main.
+
+claims:
+  disjointness_required: true
+  computed_from: static analysis (import/dependency graph) over the target
+    repo, cut along low-cohesion lines (community detection) — never
+    assigned from epic text alone.
+  overlap_handling: >
+    tasks with overlapping claims are never scheduled concurrently; they
+    get a dependency edge (edge_type: claim-order) and run serially instead.
+  enforcement: >
+    a post-run check diffs the worktree against its declared claims;
+    out-of-claim edits fail the gate (error contract.claim-violation,
+    severity S3 unless the edit touches a guardrail-protected file, then S1)
+    and bounce back to the coder.
+
+serialize_always_globs:
+  # shared-file hotspots (architecture §5.5) — any task touching these is
+  # never scheduled concurrently with another such task.
+  globs:
+    # Every lockfile, not just the two this repo happens to write: on a
+    # yarn or bun project the file two tasks collide over is theirs.
+    - "**/pnpm-lock.yaml"
+    - "**/package-lock.json"
+    - "**/yarn.lock"
+    - "**/bun.lock"
+    - "**/bun.lockb"
+    - "**/*.generated.*"
+    - "**/dist/**"
+    - "db/migrations/**"
+    - "src/routes/**/index.ts"     # route registries
+    - "src/types/**"               # shared types (hub files)
+    - "src/config/**"              # shared config (hub files)
+    - "tests/fixtures/**"          # shared fixtures (hub files)
+  note: >
+    Hub files are structurally central (types, config, shared fixtures,
+    route registries) and are never split across concurrent tasks — single
+    owner, or regenerated by the merge queue (regenerable files like
+    lockfiles are never hand-edited by workers).
+
+merge_queue:
+  mode: serial
+  order: dependency order (topological, per recorded edges)
+  admission_steps:
+    - rebase task branch onto current smith/<epic>/integration head
+    - 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
+  conflict_resolution_ladder:
+    - step: automatic rebase attempt
+    - step: dispatch merger agent with both diffs + both task specs
+    - step: >
+        escalate to operator with a side-by-side when merger confidence is
+        low or both sides changed the same logic — never auto-resolve a
+        semantic conflict silently
+  stacked_layers:
+    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
+      order (GitHub native stacked PRs).

package/factory/scaffold/base/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    # `setup` is the branch this project's first commit lands on, and the first
+    # one pushed; naming only `main` meant this workflow could not fire at all
+    # on a fresh project, because a fresh project has no main yet. Both are
+    # named so CI covers the whole life of the repo, not just the half after
+    # the first merge.
+    branches: [main, setup]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      # --frozen-lockfile is safe here: the install runs before the first
+      # commit, so pnpm-lock.yaml is already in it.
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run lint
+      - run: pnpm run typecheck
+      - run: pnpm run typecheck:test
+      # Runs the suite AND enforces the coverage floor vitest.config.ts
+      # declares — a separate `pnpm run test` step would only pay for the suite
+      # twice, and leaving coverage out is how a declared floor ends up enforced
+      # by nothing at all.
+      - run: pnpm run test:coverage
+      - run: pnpm run build

package/factory/scaffold/base/.gitignore.tmpl

@@ -0,0 +1,11 @@
+# dependencies / build
+node_modules/
+dist/
+.wrangler/
+coverage/
+
+# local env + editor
+.env
+.env.*
+.DS_Store
+*.log

package/factory/scaffold/base/AGENTS.md

@@ -0,0 +1,33 @@
+# __PROJECT_NAME__ — Agent Router
+
+Thin router (progressive disclosure) — read detail files on demand, do not
+preload this repo's whole context.
+
+## Stack
+
+TypeScript, `strict: true`. pnpm. Biome (lint + format). Vitest (unit tests).
+GitHub Actions CI runs lint + typecheck + test + build on every PR
+(`.github/workflows/ci.yml`).
+
+## Layout
+
+| Path | What |
+|---|---|
+| `src/` | Application code |
+| `test/` | Vitest unit tests, mirrors `src/` |
+
+## Rules
+
+- **TDD.** A failing test exists before the implementation that makes it
+  pass — no production code without one.
+- **Strict YAGNI.** Build exactly what the task spec asks for; no unspecced
+  abstractions, config options, or drive-by refactors.
+- **Language.** Code, comments, and commits are English.
+- **Commits.** Subject <=72 chars, imperative, why-focused.
+
+## Gate
+
+Every change clears the same five steps CI runs, and clears them locally
+first: `pnpm run lint`, `pnpm run typecheck`, `pnpm run typecheck:test`,
+`pnpm run test:coverage`, `pnpm run build`. Green here or it is not ready to
+propose.

package/factory/scaffold/base/README.md

@@ -0,0 +1,25 @@
+# __PROJECT_NAME__
+
+## Getting started
+
+```sh
+pnpm install
+pnpm test
+```
+
+## Checks
+
+| Command | What it answers |
+| --- | --- |
+| `pnpm run lint` | Does it meet the style and correctness rules Biome enforces? |
+| `pnpm run typecheck` | Does `src/` typecheck under `strict: true`? |
+| `pnpm run typecheck:test` | Does `test/` typecheck too? |
+| `pnpm run test:coverage` | Does the suite pass, and clear the coverage floor? |
+| `pnpm run build` | Does it compile? |
+
+CI runs all five on every pull request. Run them locally first — see
+[`AGENTS.md`](AGENTS.md) for the conventions this project holds itself to.
+
+---
+
+Built by blacksmith

package/factory/scaffold/base/biome.json.tmpl

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.5.6/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "includes": ["*.ts", "src/**/*.ts", "test/**/*.ts", "!dist"]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 100
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "preset": "recommended"
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single",
+      "semicolons": "always",
+      "trailingCommas": "all"
+    }
+  }
+}

package/factory/scaffold/base/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit",
+    "typecheck:test": "tsc -p tsconfig.test.json",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "lint": "biome check ."
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@biomejs/biome": "2.5.6",
+    "@types/node": "26.1.2",
+    "@vitest/coverage-v8": "4.1.10",
+    "typescript": "7.0.2",
+    "vitest": "4.1.10"
+  }
+}

package/factory/scaffold/base/pnpm-workspace.yaml.tmpl

@@ -0,0 +1,16 @@
+# This project is its own pnpm workspace root, and says so on purpose.
+#
+# pnpm finds a workspace by walking UP from the current directory until it
+# hits a `pnpm-workspace.yaml`. A checkout that sits anywhere below another
+# workspace root inherits it: that root's lockfile gets rewritten, this
+# project's dependencies get linked into that root's `node_modules`, and
+# every check afterwards measures a toolchain this project does not own. A
+# root above with no `packages` is worse still — the same walk kills
+# `pnpm install` outright with ERR_PNPM_INVALID_WORKSPACE_CONFIGURATION
+# before it resolves a single dependency.
+#
+# `.` is the whole list: one package, this one. It stays correct wherever the
+# checkout ends up, including on its own remote with nothing above it.
+# Add entries here if this project ever grows a monorepo of its own.
+packages:
+  - '.'

package/factory/scaffold/base/src/index.ts

@@ -0,0 +1,4 @@
+/** Scaffold stub — replace with the project's first real module. */
+export function ping(): string {
+  return 'pong';
+}

package/factory/scaffold/base/test/index.test.ts

@@ -0,0 +1,8 @@
+import { describe, expect, it } from 'vitest';
+import { ping } from '../src/index.js';
+
+describe('ping', () => {
+  it('returns pong', () => {
+    expect(ping()).toBe('pong');
+  });
+});

package/factory/scaffold/base/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "esModuleInterop": true,
+    "declaration": true,
+    "sourceMap": false,
+    "rootDir": "src",
+    "outDir": "dist",
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"]
+}