@monte3l/groundwork 0.0.0

package/templates/core/vitest.config.ts

@@ -0,0 +1,32 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    pool: "forks",
+    include: ["**/tests/**/*.test.ts", "**/*.test.ts"],
+    exclude: ["**/dist/**", "**/node_modules/**"],
+    coverage: {
+      provider: "v8",
+      include: ["src/**/*.ts"],
+      // No "**/index.ts" exclusion here (unlike a multi-module library
+      // barrel pattern): a fresh scaffold's index.ts IS its real content,
+      // so excluding it would make this gate measure nothing at all.
+      exclude: ["**/*.d.ts"],
+      // json emits coverage-final.json: the v8 text table hides files that
+      // are 100% on every metric, so the JSON is the authoritative
+      // per-file record when investigating a suspected gap.
+      reporter: ["text", "html", "json"],
+      thresholds: {
+        // Scaffold-appropriate starting floor. Raise these to the project's
+        // own measured floor once real coverage exists (perFile means every
+        // file must individually clear each threshold, not just the
+        // aggregate) -- never lower a threshold to make a red gate pass.
+        lines: 80,
+        functions: 80,
+        branches: 80,
+        statements: 80,
+        perFile: true,
+      },
+    },
+  },
+});

package/templates/packs/README.md

@@ -0,0 +1,81 @@
+# templates/packs/
+
+Optional add-on bundles, installed **on top of** `templates/core` rather
+than folded into it. A pack exists for one of two reasons: an artifact was
+generically useful but cut from the baseline purely to hold its hard caps
+(≤5 agents, ≤8 skills, ≤10 hooks, ≤3 CI workflows, ≤12 root scripts —
+`templates/core`'s own `CLAUDE.md`), or it applies to only some project
+kinds and shouldn't tax every bootstrap by default.
+
+## Layout
+
+```
+templates/packs/<name>/
+├── pack.json      # manifest: budget, requires, wiring
+└── files/         # the pack's own file tree, mirroring the project root
+                    # exactly as templates/core/ does -- emitted the same way
+```
+
+## The wiring contract
+
+**A pack never edits YAML or JavaScript.** It may add files under `files/`,
+and may extend three JSON files the baseline already reads at runtime:
+`.claude/settings.json` (hook registrations, and top-level harness settings
+such as `statusLine`), `package.json` (`scripts`), and
+`bin/lib/verify-steps.packs.json` (gate steps, keyed to one of the five
+fixed verify groups `templates/core/bin/lib/verify-steps.mjs` defines —
+`format`/`lint`/`typecheck`/`build`/`test`). A gate registered this way runs
+under `pnpm verify`, every `lefthook.yml` `pre-push` lane, and every
+`.github/workflows/ci.yml` job automatically, because all three already
+enumerate groups rather than individual steps.
+
+`pack.json` fields:
+
+- `schemaVersion` — currently `1`.
+- `modes` — `["fresh"]` and/or `["fresh", "adopt"]`. Only artifacts with no
+  dependency on the baseline's exact file layout (an agent, most hooks) are
+  safely adopt-capable; a gate that assumes a specific source layout should
+  say so honestly in `adoptNotes` instead of claiming `adopt`.
+- `budget` — the pack's cap deltas (`agents`/`skills`/`hooks`/`workflows`/
+  `scripts`), checked against `templates/core`'s own counts by a structural
+  test, never against `templates/core` + every other pack.
+- `requires.paths` — baseline files a pack artifact imports (e.g.
+  `bin/lib/agent-roster.mjs`). Checked at install time in fresh mode; a
+  missing requirement is a hard install error, not a silent partial install.
+- `wiring.settings` — a `.claude/settings.json` hook fragment, merged
+  append-only and idempotently. Omit it, or leave it `{}`, for a pack that
+  registers no hooks.
+- `wiring.settingsTopLevel` — top-level `.claude/settings.json` keys that
+  aren't hook registrations (`statusLine`, `subagentStatusLine`, …), planted
+  whole. A key the project already defines with a different value is a hard
+  install error, never an overwrite; `hooks` is refused here, since it
+  belongs in `wiring.settings`. Optional.
+- `wiring.packageScripts` — `package.json` script additions. Most packs need
+  none: a gate registers directly as `["node", "bin/check-x.mjs"]` in
+  `wiring.verifySteps`, not as a `pnpm` script.
+- `wiring.verifySteps` — entries appended to `bin/lib/verify-steps.packs.json`.
+- `adoptNotes` — free text surfaced verbatim in `/customize`'s Step 0
+  confirmation round when the pack applies to an adopted project.
+
+## Install path
+
+- **Fresh mode**: the CLI installs a pack directly (`--pack <name>`,
+  repeatable) — it wrote the baseline moments ago, so there's no uncertainty
+  to defer.
+- **Adopt mode**: the CLI never installs a pack. It surveys which packs
+  apply and stages their payload at `.groundwork/packs/<name>/`;
+  `/customize`'s Step 0 confirms and Round 1 installs, translating
+  `wiring.verifySteps`/`wiring.settings` against the project's _real_ gate
+  runner and hook config — read for real by that point, not guessed at
+  offline.
+
+## Available packs
+
+| Pack             | Contents                                                                                                                                                                                                                                                            |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `harness-extras` | A type-design-analyzer agent, the compaction-handoff hook pair, a read-only Bash guard, and a per-file size ratchet gate — the four artifacts the original baseline build cut purely to hold its caps.                                                              |
+| `statusline`     | A five-row Claude Code status line (session, model, context, quota, work) plus a per-subagent row renderer, both width-fit to the terminal. Registers top-level `statusLine`/`subagentStatusLine` settings, no hooks and no gate. Runs the same on macOS and Linux. |
+
+`github-ops` (dependabot/scan-alert triage skills) and `publishing` (a
+release workflow + npm-publish gates) are documented follow-ups, not yet
+built — see root `CLAUDE.md`'s Known gaps.

package/templates/packs/harness-extras/files/.claude/agents/type-design-analyzer.md

@@ -0,0 +1,188 @@
+---
+name: type-design-analyzer
+description: Read-only type-design reviewer. Rates the type design quality of changed exports on four dimensions (encapsulation, invariant expression, invariant usefulness, invariant enforcement), each scored 1–10, and flags violations of strict-TS / branded-type / make-illegal-states-unrepresentable rules. Use after writing or changing any exported TypeScript types, interfaces, or function signatures. Complements code-reviewer (general structure/SOLID).
+tools: Read, Grep, Glob, Bash
+disallowedTools: Agent
+model: claude-opus-5
+effort: xhigh
+maxTurns: 40
+color: orange
+---
+
+You are a type-design reviewer for this project. You are read-only: review
+and report; **never edit**. In the hub-and-spoke pipeline you are a review
+spoke — you analyse the type design of code a _different_ agent wrote
+(`code-implementer`). That separation is the point: the author can't grade
+their own types.
+
+Start by reading the diff (`git diff`, or `git diff --staged`) and the
+changed files. Focus exclusively on type design of exported symbols. Ground
+every finding in the project's own coding rules and its `strict: true` /
+ESM invariants.
+
+## Five-step method
+
+For each changed export, work through these steps in order:
+
+1. **Identify invariants** — what must always be true about values of this
+   type? (e.g. "a `UserId` is always a non-empty string with a stable brand")
+2. **Check encapsulation** — are implementation details (internal fields,
+   sentinel values, index shapes) hidden from callers, or leaked into the
+   type?
+3. **Check invariant expression** — are the invariants expressed _in the
+   type system_ (branded types, discriminated unions, literal types) or
+   only in prose / runtime checks?
+4. **Check invariant usefulness** — does the type actually prevent wrong
+   usage at the call site, or does it collapse to `string` / `object` /
+   `unknown` at the boundary?
+5. **Check enforcement** — is correctness enforced at compile time (types)
+   or only at runtime (guards)? Prefer compile time; runtime is a fallback.
+
+## Four ratings
+
+After the five-step walk, assign a **1–10 score** to each dimension, with a
+one-sentence justification:
+
+| Dimension                 | What a high score looks like                                              |
+| ------------------------- | ------------------------------------------------------------------------- |
+| **Encapsulation**         | Callers see exactly what they need; no accidental exposure of internals   |
+| **Invariant expression**  | Invariants live in the type; impossible states are unrepresentable        |
+| **Invariant usefulness**  | The type catches real misuse at the call site; not trivially widened away |
+| **Invariant enforcement** | Violations are caught at compile time, not deferred to runtime            |
+
+Report each dimension as: `Dimension: N/10 — <one-sentence justification>`.
+
+## Project grounding
+
+- **No `any`** (use `unknown` and narrow); no non-null `!` in `src/`.
+- **Branded types** for semantic identifiers — every value that is "more
+  than a primitive" gets a brand so the type system catches mixups:
+
+```ts
+// the UserId pattern — replicate it for every domain id/key
+export type UserId = string & { readonly __brand: unique symbol };
+```
+
+- **Make illegal states unrepresentable** — prefer discriminated unions over
+  boolean flags that can disagree:
+
+```ts
+// flag — two booleans that can be mutually contradictory
+type State = { loading: boolean; error: boolean; data: unknown };
+// good — only valid combinations are representable
+type State =
+  | { status: "loading" }
+  | { status: "error"; error: Error }
+  | { status: "ready"; data: unknown };
+```
+
+- **`readonly`** on array/tuple fields; mutation should be opt-in, not the
+  default.
+- **Compile-time enforcement preferred over runtime.** A parse-then-validate
+  pattern (e.g. a schema library narrowing to a branded type) is fine; bare
+  `as BrandedType` casts are not — they bypass the invariant.
+- **The project's public entry points are the typed public contract**
+  (`package.json`'s `exports`/`main` field). Any type visible through those
+  entries is part of the semver surface — flag accidental re-exports of
+  internal shapes.
+
+## What findings look like
+
+Anchor each finding to a concrete contrast so the fix is obvious.
+
+**1 — Missing brand (invariant expression):**
+
+```ts
+// flag — any string can be passed; mixups are invisible to the compiler
+export type ConfigKey = string;
+export function get(key: ConfigKey): string { … }
+
+// good — brand prevents passing a raw string literal or a UserId
+export type ConfigKey = string & { readonly __brand: unique symbol };
+```
+
+**2 — Leaking internal sentinel (encapsulation):**
+
+```ts
+// flag — callers must know -1 means "not found"; internal detail leaks out
+export function indexOf(items: string[], target: string): number { … }
+// good — the type encodes the optionality; no sentinel
+export function indexOf(items: string[], target: string): number | undefined { … }
+```
+
+**3 — Boolean flags for mutually exclusive states (invariant expression):**
+
+```ts
+// flag — callers can observe { loading: true, error: true } which is nonsense
+export type PollState = { loading: boolean; error: boolean; data: unknown };
+// good — only valid combinations exist
+export type PollState =
+  | { status: "polling" }
+  | { status: "failed"; error: Error }
+  | { status: "done"; data: unknown };
+```
+
+**4 — `any` in a public signature (invariant usefulness):**
+
+```ts
+// flag — any annotation erases the caller's guarantee; nothing is checked
+export function transform(input: any): any { … }
+// good — narrow at the boundary; everything downstream is typed
+export function transform(input: unknown): TransformedResult {
+  if (!isValidInput(input)) throw new Error("invalid input");
+  …
+}
+```
+
+**5 — `as Brand` cast bypasses enforcement (invariant enforcement):**
+
+```ts
+// flag — the cast is a lie; the string is never validated
+function makeUserId(raw: string): UserId {
+  return raw as UserId;
+}
+// good — validation earns the brand
+function makeUserId(raw: string): UserId {
+  if (!UUID_PATTERN.test(raw)) throw new Error("invalid user id");
+  return raw as UserId; // safe: UUID_PATTERN is the invariant guard
+}
+```
+
+## Boundaries
+
+- Rate **type design only** — correctness bugs, naming, SRP violations, and
+  SOLID checks belong to `code-reviewer`; don't duplicate them.
+- Silent-failure / error-handling concerns belong to `silent-failure-
+hunter`; stay on types.
+
+## Output
+
+Rate each changed export with the four dimension scores. Group all type
+findings as **Must-fix**, **Should-fix**, **Nits**. Cap each section at its
+10 most severe findings, most-severe first (collapse a recurring issue class
+into one bullet rather than spilling past the cap). Cite `file:line` and the
+violated rule. End with a one-line verdict.
+
+**Scope discipline.** The dimension scores are the review; reserve
+**Must-fix** for a type that actually admits an illegal state or erases a
+caller guarantee (an `any`, a non-null `!`, an unearned `as Brand` cast).
+Don't push every sub-10 score into Must-fix — a 7/10 dimension with a
+defensible tradeoff is a **Nit**, not a defect — and don't demand invariants
+stricter than the documented contract needs.
+
+**Converge and report.** Once you've answered the checklist against the
+files you were given, stop — don't keep re-reading or re-verifying "just in
+case." Report what you found rather than chasing diminishing returns.
+
+**Bounded output (survive a turn limit).** A long findings report across
+many changed exports can itself run you out of turn budget mid-report.
+Return your report **inline in your response** — you hold no write tool and
+cannot write any file (this project's read-only Bash guard,
+`guard-readonly-bash.mjs`, blocks every shell write route regardless), so a
+scratchpad handoff is never an option here. If the diff touches many
+exports, keep the whole report within roughly 8,000 characters (~2,000
+tokens — the sub-agent output band Anthropic documents): the one-line
+verdict, the four dimension scores per export (these stay compact already),
+and the Must-fix list in full — these block the hub, never truncate them —
+and for Should-fix/Nits a count plus a one-line summary per item rather than
+every body.

package/templates/packs/harness-extras/files/.claude/hooks/guard-readonly-bash.mjs

@@ -0,0 +1,324 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse guard (Bash): restrict read-only spokes to non-mutating shell
+ * commands.
+ *
+ * Every reviewer/research spoke in `.claude/agents/*.md` declares itself
+ * read-only in its system prompt and may hold the `Bash` tool for
+ * legitimate reads (`git diff`, `pnpm lint`, coverage files, `grep`), but
+ * nothing structurally stops one from running a mutating shell command
+ * instead. This hook closes that gap at the point a subagent's Bash call
+ * actually runs.
+ *
+ * The read-only roster is derived here, not hardcoded: every defined agent
+ * under `.claude/agents/*.md` whose frontmatter `name` is not in
+ * `WRITER_SPOKES` (`bin/lib/agent-roster.mjs` -- the same source
+ * `guard-hub-src-writes.mjs` uses) counts as read-only, so the two
+ * enforcement points can't drift apart on who's authorized to write what.
+ *
+ * Scope: only tool calls made from inside one of those read-only subagents
+ * are checked -- identified via the hook payload's `agent_type` field
+ * (present when `PreToolUse` fires inside a subagent context; absent for
+ * the hub's own Bash calls, which this hook does not restrict).
+ *
+ * Design tradeoff, matching every sibling guard hook's fail-open
+ * philosophy: this is a DENYLIST of known-mutating patterns, not a strict
+ * allowlist. A stricter allowlist would be more airtight but would also
+ * block legitimate read commands this hook's author didn't anticipate (a
+ * false positive wedges a reviewer's diagnostic work; a false negative
+ * merely defers to code review, which remains the authoritative backstop).
+ * Extend MUTATING_PATTERNS as new gaps are found rather than flipping to an
+ * allowlist.
+ */
+import process from "node:process";
+import { existsSync, readdirSync, readFileSync, realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { WRITER_SPOKES } from "../../bin/lib/agent-roster.mjs";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "../..");
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+/** Extract the YAML frontmatter block's `name:` field, or `undefined`. */
+function frontmatterName(filePath) {
+  const content = readFileSync(filePath, "utf8");
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (match === null) return undefined;
+  const nameLine = match[1].split("\n").find((line) => /^name:\s*/.test(line));
+  return nameLine?.replace(/^name:\s*/, "").trim();
+}
+
+/**
+ * Every defined agent under `agentsDir` (`.claude/agents/*.md`) whose
+ * frontmatter `name` is not in `WRITER_SPOKES`.
+ *
+ * @param {string} agentsDir absolute path to `.claude/agents/`
+ * @returns {Set<string>}
+ */
+export function readOnlyAgentNames(agentsDir) {
+  const names = new Set();
+  if (!existsSync(agentsDir)) return names;
+  for (const entry of readdirSync(agentsDir, { withFileTypes: true })) {
+    if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+    const name = frontmatterName(join(agentsDir, entry.name));
+    if (name !== undefined && !WRITER_SPOKES.has(name)) names.add(name);
+  }
+  return names;
+}
+
+/**
+ * Segment a shell command on `&&`/`||`/single `|`/`;`/newline chain operators.
+ * A `|` immediately preceded by `>` is the clobber-redirect operator (`>|`),
+ * not a pipe, so it must not split -- otherwise `echo x >| file` gets
+ * chopped into "echo x >" and "file", hiding the redirect from the
+ * write-detection regex in classifyBashCommand.
+ */
+function segments(command) {
+  return command.split(/&&|\|\||(?<!>)\||;|\n/).map((s) => s.trim());
+}
+
+/** Strip a leading path (e.g. `/usr/bin/rm` -> `rm`) for verb comparison. */
+function baseName(token) {
+  const parts = token.split(/[/\\]/);
+  return parts[parts.length - 1];
+}
+
+// Global/wrapper flags -- per verb -- that consume the FOLLOWING token as
+// their value, so the walk to find the subcommand must skip both. Without
+// this, `git -C /tmp commit` or `pnpm --dir ./foo add lodash` resolve `sub`
+// to the flag's *value* ("/tmp", "./foo") instead of the real subcommand,
+// defeating MUTATING_SUBCOMMANDS entirely (a `--flag=value` inline form
+// needs no entry here -- the value stays on the same token, which
+// parseSegment already skips as "starts with -").
+const FLAGS_WITH_VALUE = {
+  git: new Set([
+    "-c",
+    "-C",
+    "--git-dir",
+    "--work-tree",
+    "--namespace",
+    "--exec-path",
+  ]),
+  pnpm: new Set(["-C", "--dir", "--filter", "--filter-prod"]),
+  npm: new Set(["-C", "--prefix"]),
+};
+
+/**
+ * The command verb and (for multi-word CLIs) subcommand of one shell
+ * segment, skipping leading `VAR=value` environment assignments and any
+ * global flags (per FLAGS_WITH_VALUE) that appear before the subcommand.
+ *
+ * @param {string} segment
+ * @returns {{ verb: string, sub: string | undefined, tokens: string[] }}
+ */
+function parseSegment(segment) {
+  const tokens = segment.split(/\s+/).filter(Boolean);
+  let i = 0;
+  while (i < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[i])) i++;
+  if (tokens[i] === undefined) return { verb: "", sub: undefined, tokens: [] };
+
+  const verb = baseName(tokens[i]);
+  const valueFlags = FLAGS_WITH_VALUE[verb] ?? new Set();
+  let sub;
+  let j = i + 1;
+  while (j < tokens.length) {
+    const t = tokens[j];
+    if (valueFlags.has(t)) {
+      j += 2; // skip the flag AND its value token
+      continue;
+    }
+    if (t.startsWith("-")) {
+      j += 1; // a flag that doesn't consume a following value
+      continue;
+    }
+    sub = t;
+    break;
+  }
+  return { verb, sub, tokens: tokens.slice(i) };
+}
+
+// Mutating subcommands per top-level verb (e.g. "git" -> "commit"). A verb
+// that's always mutating regardless of subcommand belongs in
+// MUTATING_VERBS below instead.
+const MUTATING_SUBCOMMANDS = {
+  git: new Set([
+    "add",
+    "commit",
+    "push",
+    "merge",
+    "rebase",
+    "cherry-pick",
+    "reset",
+    "checkout",
+    "switch",
+    "branch",
+    "tag",
+    "clean",
+    "apply",
+    "am",
+    "revert",
+    "restore",
+    "gc",
+    "worktree", // add/remove mutate the tree layout
+    "config",
+    "stash", // push/pop/drop/apply mutate the working tree; `stash list` is
+    // read-only but the false positive here is cheap -- use `git stash
+    // list` sparingly from a read-only spoke, or defer to the hub.
+  ]),
+  pnpm: new Set([
+    "add",
+    "remove",
+    "rm",
+    "publish",
+    "version",
+    "link",
+    "unlink",
+  ]),
+  npm: new Set([
+    "install",
+    "i",
+    "add",
+    "remove",
+    "rm",
+    "uninstall",
+    "publish",
+    "version",
+    "link",
+    "unlink",
+  ]),
+};
+
+// Verbs that mutate the filesystem regardless of subcommand.
+const MUTATING_VERBS = new Set([
+  "rm",
+  "mv",
+  "cp",
+  "mkdir",
+  "rmdir",
+  "touch",
+  "chmod",
+  "chown",
+  "truncate",
+  "dd",
+  "tee",
+]);
+
+/**
+ * Classify a shell command as blocked (mutating) or allowed for a read-only
+ * spoke. Denylist-based -- see the module header for the design tradeoff.
+ *
+ * @param {string} command
+ * @returns {{ blocked: boolean, reason?: string }}
+ */
+export function classifyBashCommand(command) {
+  if (typeof command !== "string" || command.trim().length === 0) {
+    return { blocked: false };
+  }
+
+  for (const segment of segments(command)) {
+    if (segment.length === 0) continue;
+
+    // Write-redirection to a real file (not a discard target). No digit
+    // lookbehind: `1>file`/`2>file` are ordinary fd-prefixed writes, not fd
+    // duplication -- `2>&1` is excluded below because its target starts
+    // with `&`, which the target class already rejects. Global flag: a
+    // segment can carry more than one redirect (`cmd > /dev/null > real`),
+    // and a decoy discard target must not short-circuit the scan past a
+    // real one that follows it.
+    for (const redirect of segment.matchAll(/(>{1,2}\|?)\s*([^\s&|;]+)/g)) {
+      if (
+        !/^(\/dev\/null|nul)$/i.test(redirect[2].replace(/^["']|["']$/g, ""))
+      ) {
+        return {
+          blocked: true,
+          reason: `writes to "${redirect[2]}" via shell redirection ("${redirect[0]}")`,
+        };
+      }
+    }
+
+    const { verb, sub, tokens } = parseSegment(segment);
+    if (verb.length === 0) continue;
+
+    if (MUTATING_VERBS.has(verb)) {
+      return { blocked: true, reason: `runs "${verb}", a mutating command` };
+    }
+
+    if (
+      verb === "sed" &&
+      tokens.some((t) => t === "-i" || t.startsWith("-i"))
+    ) {
+      return { blocked: true, reason: `runs "sed -i" (in-place edit)` };
+    }
+
+    const mutatingSubs = MUTATING_SUBCOMMANDS[verb];
+    if (
+      mutatingSubs !== undefined &&
+      sub !== undefined &&
+      mutatingSubs.has(sub)
+    ) {
+      return {
+        blocked: true,
+        reason: `runs "${verb} ${sub}", a mutating subcommand`,
+      };
+    }
+  }
+
+  return { blocked: false };
+}
+
+// Deliberately inlined in every hook rather than shared: this pack's hook
+// budget is exactly its three hooks, so a helper module would cost a slot.
+// `import.meta.url` is symlink-resolved but `process.argv[1]` is not, so
+// comparing them directly is false under any symlinked path and the body would
+// never run -- exit 0.
+function isEntryPoint() {
+  try {
+    return realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+}
+
+// Only run when invoked directly, not when imported for testing.
+if (isEntryPoint()) {
+  const raw = await readStdin();
+  let input;
+  try {
+    input = JSON.parse(raw);
+  } catch {
+    process.exit(0);
+  }
+
+  const agentType = input.agent_type;
+  if (typeof agentType !== "string" || agentType.length === 0) process.exit(0);
+
+  let readOnly;
+  try {
+    readOnly = readOnlyAgentNames(join(root, ".claude/agents"));
+  } catch {
+    process.exit(0); // can't determine the roster -> defer, don't wedge
+  }
+  if (!readOnly.has(agentType)) process.exit(0);
+
+  const command = input.tool_input?.command;
+  const verdict = classifyBashCommand(
+    typeof command === "string" ? command : "",
+  );
+  if (!verdict.blocked) process.exit(0);
+
+  process.stderr.write(`\
+[guard-readonly-bash] Blocked: the "${agentType}" spoke is read-only, but this
+command ${verdict.reason}.
+
+Read-only spokes may inspect the repo but never mutate it -- that separation
+is structural (CLAUDE.md § Agent Operating Model). If this command is
+genuinely needed, hand the mutation back to the hub or to a writer spoke
+(code-implementer / test-author) instead of running it here.
+`);
+  process.exit(2);
+}