@monte3l/groundwork 0.0.0

package/templates/core/.claude/hooks/inject-decision-gate.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+/**
+ * UserPromptSubmit: when a prompt looks like change-work, inject a short
+ * decision-gate reminder as additional context.
+ *
+ * This is the only UserPromptSubmit hook in the baseline and the only one
+ * that *injects* context (every other hook communicates via stderr + exit
+ * code). It surfaces the decisions the `starting-work` skill formalizes --
+ * branch and PR target -- up front, so isolation is chosen deliberately
+ * instead of being discovered when `guard-branch-isolation.mjs` blocks a
+ * src/test write on `main`.
+ *
+ * It is advisory: it emits `additionalContext` and exits 0. It never blocks.
+ * The heuristic is deliberately loose (inject on any change-intent verb,
+ * stay quiet on obvious reads) -- a spurious reminder is cheap; a missed one
+ * costs a mid-task branch scramble.
+ */
+import process from "node:process";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { execFileSync } from "node:child_process";
+
+// Verbs that signal the user is about to change the tree, not just ask about it.
+const CHANGE_INTENT =
+  /\b(implement|build|add|create|write|fix|refactor|scaffold|rename|migrate|wire up|delete|remove|update|change|edit|generate)\b/i;
+// Strong read-only openers; if the prompt is one of these and carries no change
+// verb, stay quiet.
+const READ_ONLY_OPENER =
+  /^\s*(what|why|how|when|where|which|who|explain|describe|show|list|read|find|search|look|review|audit|is|are|does|can|should|could)\b/i;
+
+/** Current branch, or "" if git isn't available. "HEAD" means detached. */
+function currentBranch() {
+  try {
+    return execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+      encoding: "utf8",
+    }).trim();
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Heuristic: does this prompt look like it will change the tree (vs. a read)?
+ *
+ * @param {string} prompt
+ * @returns {boolean}
+ */
+export function looksLikeChangeWork(prompt) {
+  if (typeof prompt !== "string" || prompt.trim().length === 0) return false;
+  if (!CHANGE_INTENT.test(prompt)) return false;
+  if (
+    READ_ONLY_OPENER.test(prompt) &&
+    !/^\s*\S+\s+(the|this|a|an)\b/i.test(prompt)
+  )
+    return false;
+  return true;
+}
+
+/**
+ * Build the decision-gate reminder text for the current branch.
+ *
+ * @param {string} branch  current branch ("main", "HEAD" for detached, "" for no repo)
+ * @returns {string}
+ */
+export function buildContext(branch) {
+  const onMain = branch === "main" || branch === "HEAD" || branch === "";
+  const branchLine =
+    branch === ""
+      ? "not a git repo"
+      : branch === "HEAD"
+        ? "detached HEAD"
+        : `on \`${branch}\``;
+  return [
+    "Decision gate (before editing code/tests) -- currently " +
+      `${branchLine}. Settle these first, ideally via the \`starting-work\` skill:`,
+    "  • Branch -- `feat/<slug>` or `fix/<slug>` off `main` (never `main`" +
+      (onMain ? ", and you appear to be on/at `main` now" : "") +
+      ").",
+    "  • PR -- any `src/`/`tests/` change lands via PR, never a direct commit to `main`.",
+    "  • Push -- `origin <branch>`, not `origin main`.",
+    "guard-branch-isolation.mjs will block src/test writes on `main`, so branch first.",
+  ].join("\n");
+}
+
+// Deliberately inlined in every hook rather than shared: caps.ts counts
+// .claude/hooks/*.mjs files against a hard limit, so a helper module would
+// cost a hook 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
+// guard body would never run -- exit 0, i.e. fail open.
+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 chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  let input;
+  try {
+    input = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+  } catch {
+    process.exit(0);
+  }
+
+  if (!looksLikeChangeWork(input.prompt ?? "")) process.exit(0);
+
+  const output = {
+    hookSpecificOutput: {
+      hookEventName: "UserPromptSubmit",
+      additionalContext: buildContext(currentBranch()),
+    },
+  };
+  process.stdout.write(JSON.stringify(output));
+  process.exit(0);
+}

package/templates/core/.claude/hooks/post-edit-verify.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+/**
+ * PostToolUse verify (Write|Edit): fast in-loop feedback on TypeScript edits.
+ *
+ * Lefthook + CI already gate at commit/push time, but that feedback arrives
+ * late. After an edit to a `.ts`/`.mts`/`.cts` file under `src/` or `tests/`
+ * (at the project root, or nested under any `packages/<pkg>/`), this runs
+ * checks scoped to the owning package so the signal is immediate without
+ * paying the whole-project cost:
+ *
+ *   1. prettier --write   (auto-format the edited file)
+ *   2. eslint              (lint the edited file; flat config from repo root)
+ *   3. package typecheck   (`pnpm -C <pkg> typecheck`)
+ *   4. vitest related      (only the tests that import the edited file)
+ *   5. eslint tests/       (only when a src/ file is edited -- catches stale
+ *                           eslint-disable directives that went unused after
+ *                           the implementation landed; skipped silently if
+ *                           tests/ doesn't exist)
+ *
+ * eslint runs in-loop (not just at the hub's `pnpm lint` gate) so eslint-only
+ * failures surface here, not a round later.
+ *
+ * On any failure it exits 2 with a concise stderr summary, which Claude Code
+ * surfaces back to the model as advisory feedback. The edit has already been
+ * applied -- this is a nudge, not a hard gate.
+ */
+import process from "node:process";
+import path from "node:path";
+import fs from "node:fs";
+import { spawnSync } from "node:child_process";
+import { isProtectedPath } from "../../bin/lib/protected-paths.mjs";
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+const projectDir = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+
+const raw = await readStdin();
+let input;
+try {
+  input = JSON.parse(raw);
+} catch {
+  process.exit(0);
+}
+
+const filePath = input.tool_input?.file_path;
+if (typeof filePath !== "string" || filePath.length === 0) process.exit(0);
+
+const abs = path.isAbsolute(filePath)
+  ? filePath
+  : path.resolve(projectDir, filePath);
+const rel = path.relative(projectDir, abs).split(path.sep).join("/");
+
+// Only TypeScript sources; never generated declarations or the hooks themselves.
+if (!/\.(ts|mts|cts)$/.test(rel) || /\.d\.ts$/.test(rel)) process.exit(0);
+if (
+  rel.startsWith("..") ||
+  rel.includes("node_modules/") ||
+  /(^|\/)dist\//.test(rel) ||
+  rel.startsWith(".claude/")
+) {
+  process.exit(0);
+}
+
+if (!isProtectedPath(rel)) process.exit(0);
+
+// Walk up to the nearest package.json = the owning package root (the
+// project root itself in a flat single-package layout).
+function findPackageDir(startDir) {
+  let dir = startDir;
+  while (dir.startsWith(projectDir)) {
+    if (fs.existsSync(path.join(dir, "package.json"))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return undefined;
+}
+
+const pkgDir = findPackageDir(path.dirname(abs));
+if (pkgDir === undefined) process.exit(0);
+
+function run(cmd, args) {
+  const res = spawnSync(cmd, args, {
+    cwd: projectDir,
+    encoding: "utf8",
+    env: process.env,
+  });
+  // If the tool can't even be spawned (e.g. pnpm missing), skip silently
+  // rather than emit a misleading failure.
+  if (res.error) return undefined;
+  return res;
+}
+
+const failures = [];
+
+// 1. Format the edited file (best-effort; a parse error is itself signal).
+const fmt = run("pnpm", ["exec", "prettier", "--write", abs]);
+if (fmt && fmt.status !== 0) {
+  failures.push(`prettier:\n${(fmt.stderr || fmt.stdout || "").trim()}`);
+}
+
+// 2. Lint the edited file (single file; flat config resolves from repo root
+//    and honours its own `ignores`, so no per-package wrapper is needed).
+//    Report-only (no --fix) so the root cause is addressed, not masked.
+const lint = run("pnpm", ["exec", "eslint", abs]);
+if (lint && lint.status !== 0) {
+  failures.push(`eslint:\n${(lint.stdout || lint.stderr || "").trim()}`);
+}
+
+// 3. Type-check the owning package.
+const tc = run("pnpm", ["-C", pkgDir, "typecheck"]);
+if (tc && tc.status !== 0) {
+  failures.push(`typecheck:\n${(tc.stdout || tc.stderr || "").trim()}`);
+}
+
+// 4. Run only the tests related to the edited file.
+const vt = run("pnpm", ["exec", "vitest", "related", abs, "--run"]);
+if (vt && vt.status !== 0) {
+  failures.push(`vitest related:\n${(vt.stdout || vt.stderr || "").trim()}`);
+}
+
+// 5. When a src/ file is implemented/updated, also lint the package's tests/
+//    directory to surface stale eslint-disable directives that became unused
+//    once the implementation landed.
+if (/(^|\/)src\//.test(rel)) {
+  const testsDir = path.join(pkgDir, "tests");
+  if (fs.existsSync(testsDir)) {
+    const testLint = run("pnpm", ["exec", "eslint", testsDir]);
+    if (testLint && testLint.status !== 0) {
+      failures.push(
+        `eslint (tests/ -- scanned because a src/ file was edited; fix the file(s) listed below):\n${(testLint.stdout || testLint.stderr || "").trim()}`,
+      );
+    }
+  }
+}
+
+if (failures.length > 0) {
+  process.stderr.write(
+    `post-edit-verify found issues in \`${rel}\` (package: ` +
+      `${path.relative(projectDir, pkgDir) || "."}). Address these before ` +
+      `moving on:\n\n${failures.join("\n\n")}\n`,
+  );
+  process.exit(2);
+}
+
+process.exit(0);

package/templates/core/.claude/rules/agent-dispatch.md

@@ -0,0 +1,121 @@
+---
+paths:
+  - ".claude/skills/**"
+  - ".claude/agents/**"
+---
+
+# Subagent dispatch rules (hub-and-spoke TDD loop, truncation prevention & recovery)
+
+> The terse checklist consulted when dispatching or resuming a spoke. No
+> natural path-glob covers "dispatching a subagent," so this rule is also
+> referenced from CLAUDE.md's Agent Operating Model section.
+
+## The loop
+
+Hub-and-spoke: the hub plans and dispatches, and never writes `src/`/test
+code itself — enforced by `guard-hub-src-writes.mjs` and
+`disallowedTools: Agent` on every spoke. For a piece of work with a clear
+contract (a documented behavior, an interface to satisfy):
+
+1. `test-author` writes failing tests from the contract (RED) and confirms
+   they fail for the right reason.
+2. `code-implementer` makes them pass with the minimal correct implementation,
+   then refactors while green (GREEN).
+3. Read-only reviewers (`code-reviewer` always; `silent-failure-hunter` when
+   the change has try/catch, async/await, or retry/poll logic) run in
+   parallel over the diff. Must-fix findings route back to
+   `code-implementer` and the loop repeats until clean.
+
+## Dispatch sizing
+
+- **Decompose before you dispatch.** Scale the dispatch to task complexity —
+  a module spanning many files gets split into bounded sub-dispatches up
+  front, not handed to one spoke as an indivisible turn. A single-file test
+  suite over ~40 tests, or a fix round over ~5 findings, splits into
+  checkpointed batches the same way. Hand a spoke an explicit file list
+  **and** a byte/file-count budget, measured before dispatch; a spoke told
+  the ceiling shrinks the file instead of ratcheting the baseline.
+- **Size a FIX round by file, not by finding count.** Regroup findings by
+  file — one spoke per file (or tight file group), every finding for that
+  file in one prompt — so each spoke loads one file's context. This also
+  removes write conflicts, so spokes can run concurrently.
+- **Bound review-spoke INPUT scope too, not just output.** Give each review
+  spoke a tight per-spoke file list (2–5 files) and split a review dispatch
+  by concern once the diff exceeds ~3–4 files or a few hundred lines. Every
+  review-spoke prompt also carries a **converge and report** instruction —
+  stop once its checklist is answered rather than re-verifying indefinitely.
+- **Pre-resolve the facts a writer would otherwise discover, not just its
+  output scope.** Discovery, not writing, is what exhausts a turn budget.
+  Resolve the exact fixture contents, a collaborator's return shape, and the
+  precise `file:line` anchors yourself before dispatch, so the spoke's first
+  tool call is a write, not a search.
+- **Two independent review lenses landing on the same line is signal, not
+  redundancy.** Treat a convergent finding as confirmed and fix it — never
+  discount the second report as a duplicate of the first.
+- **Re-review every substantive fix round, bounded.** Must-fix fixes are new
+  writer code with no reviewer between them and the commit. Dispatch a
+  focused confirmation pass — the reviewer(s) whose findings drove the fixes,
+  scoped to the changed files only — before declaring the review loop
+  closed.
+- **Don't raise the turn-limit as the fix.** More context/turns is not free
+  — accuracy degrades as token count grows. Scoping, journaling, and pacing
+  are the preferred levers.
+
+## Journaling & recovery
+
+- **Hand writer spokes (`test-author`, `code-implementer`) an explicit
+  journal path** in the dispatch prompt.
+- **Never trust a "final" report at face value.** A mid-thought fragment is
+  the signature of a truncated turn, not a benign quirk — verify on-disk
+  state yourself (the spoke's journal, `git status`/`git diff`, re-run
+  typecheck/lint/test/coverage) before deciding what's actually done.
+- **A spoke's scratchpad journal doesn't survive a session-level restart,
+  but its git-worktree edits do.** After a harness/process restart
+  mid-dispatch, check `git status`/`git diff` **in the worktree the spoke
+  ran in**, not this repo's own root — the edits may already be there even
+  with no journal left to read.
+- **A coherent-looking report can still be wrong — a separate failure mode
+  from truncation.** Re-verify a fix round's completion (re-read the diff,
+  re-run the gates) regardless of how confident the report reads.
+- **Resume the SAME spoke via a follow-up message**, never a fresh
+  dispatch — a fresh agent has no memory of the prior exploration and
+  restarts the whole budget from zero. Hand it a punch-list, not a recap.
+- **Verification can conclude "no resume needed."** A truncated return whose
+  artifacts are already on disk (files written, gates green when you run
+  them yourself) needs no resume at all — re-running the verification
+  battery from the hub is cheaper. Reserve resumes for truncations where the
+  work itself is genuinely unfinished.
+
+## Boundaries
+
+- **Review spokes return a bounded digest**, not an open-ended report — the
+  full report travels back inline in the response, capped at roughly 8,000
+  characters (~2,000 tokens). No review spoke writes a scratchpad file.
+- **Plan mode propagates its read-only restriction to every subagent it
+  dispatches** — not just the ones already read-only by design. A writer
+  spoke dispatched while plan mode is active loses write access too. If a
+  design depends on a subagent writing a file, verify with `git status`/`ls`
+  after the dispatch rather than trusting the return value's success claim.
+- **A `SubagentStop`/`PreToolUse` hook flagging a dispatch is a prompt to
+  verify, not a replacement for verifying.** Treat its stderr reminder as a
+  signal to check state yourself.
+- **A templated dispatch prompt needs a per-target assumption check, not
+  just a per-target file-list check.** Verify the template's implicit
+  assumptions against each target's own docs/tests before dispatch, not
+  just the file scope — a defect here can be semantically wrong but
+  syntactically valid, passing typecheck/lint/build clean.
+- **Make barrel/index wiring its own numbered, separately-verified step in
+  any multi-file dispatch.** It's the step most often left for last, so it's
+  the step truncation most often lands on — a missing re-export line passes
+  the suite green while nothing in the new module is actually reachable.
+
+## Before wiring a new hook or workflow script
+
+- **Run it against known-good input before wiring it, not only against the
+  failure cases it was built from.** An advisory hook that fires on every
+  event of a type must be proven **quiet** on that type's normal output; one
+  that cries wolf trains the reader to ignore it, which is worse than not
+  shipping it.
+- **A live end-to-end run on a small real input is the acceptance test for a
+  script — static gates and review passes cannot see runtime behavior.**
+  Review reads a hook or workflow script; nothing else runs it.

package/templates/core/.claude/rules/refactoring.md

@@ -0,0 +1,52 @@
+---
+paths:
+  - "src/**"
+  - "**/tests/**"
+  - "**/*.test.ts"
+---
+
+# Refactoring rules (source & tests)
+
+> This file is the terse checklist that auto-loads when you change existing code.
+
+Refactoring changes internal structure **without changing observable behavior**.
+It is not feature, performance, or behavior work — those are separate commits.
+
+- **Test safety net first.** A passing suite must exist before you refactor; if the
+  area lacks tests, **add characterization tests** capturing current behavior first.
+- **State the goal.** Name the problem you are removing (duplication, complexity,
+  naming, weak types). No identified problem → no refactor.
+- **Small isolated steps**, each one focused operation, **committed individually**
+  with a `refactor:` commit. Rerun the full suite after each
+  step; a failure is a regression — revert before continuing.
+- **Opportunistic / Boy-Scout:** leave touched code better than you found it, and
+  do a preparatory refactor first when it makes the change you came to do simpler —
+  but **keep it bounded** (don't chase one cleanup into a rewrite) and in its own
+  commit, separate from the feature/fix.
+- **A refactor MUST NOT** add features, change observable behavior, add a
+  dependency, or change a public interface unless that is the explicit purpose.
+- **Semver hazard:** changing an exported signature or the `exports` map is a
+  breaking change, not a free refactor — keep the public surface stable or plan
+  the major bump. New capability surfaces through the existing barrel/entry
+  point, never a new subpath added casually.
+- **Tests are production code:** rename a test when its behavior is renamed, delete
+  tests that no longer assert a contract, refactor a shared fixture once (not every
+  caller), and update a mock target the moment the impl's I/O primitive changes (a
+  stale mock silently intercepts nothing).
+- **Moving code out from under a test can leave it vacuous with no gate
+  catching it.** Extracting or relocating the behavior a test exercises,
+  without re-deriving what the test still actually reaches, can leave it
+  green while asserting nothing real — and a fixture edited to match the new
+  code is not automatically a test of the behavior that changed; confirm it
+  still fails when the new behavior is wrong, not just that it passes when
+  the code is right.
+- **A full test-file rewrite must name what it must NOT touch.** A general
+  instruction ("don't drop tests for unchanged functions") is easy to satisfy
+  partially in a large rewrite without anyone noticing which specific cases got
+  lost — enumerate the functions whose existing coverage must survive
+  untouched, not just restate the rule.
+- **Removing a lint suppression cannot be its own commit.** `reportUnusedDisableDirectives:
+"error"` (`eslint.config.js`) makes a stale `eslint-disable-next-line` a lint error
+  the instant the finding it suppressed no longer fires — so the change that
+  clears the underlying issue and the deletion of its suppression comment must
+  land in the same commit, never split across two.

package/templates/core/.claude/rules/src.md

@@ -0,0 +1,114 @@
+---
+paths:
+  - "src/**"
+---
+
+# Source rules (`src/**`)
+
+> This file is the terse checklist that auto-loads when you edit source.
+> Base standards — TypeScript strictness, ESM `.js` imports, named exports,
+> exporting a type next to its value, `readonly`/`const`, `interface` vs
+> `type`, exhaustive `switch`, TSDoc on every export — live in CLAUDE.md and
+> `eslint.config.js`; this file adds what those don't already say.
+
+- **Don't pass `undefined` to an optional property.** Under
+  `exactOptionalPropertyTypes`, an optional target field (`default?: number`)
+  rejects an explicit `undefined` (TS2379). When forwarding optional caller
+  options into a strict target, **omit the key** with a conditional spread —
+  `...(v !== undefined ? { k: v } : {})` — never `{ k: someValue | undefined }`.
+- **Guard reads and writes together when mutating a property on an object you
+  don't own — verify success by reading it back, never by the absence of a
+  throw.** The property can be an accessor whose getter itself throws, the
+  object can be frozen/sealed/non-extensible, or a setter can silently no-op.
+  Wrap the read AND the write in one `try`/`catch`, and after a non-throwing
+  assignment compare `object.property === value` before reporting success.
+- **Never export error-constructor options interfaces.** Callers _catch_
+  errors, they don't construct them.
+- **Discriminate a swallow by error `code`, not class.** When one error class
+  carries several `code`s, `catch (e) { if (e instanceof X) skip }` drops the
+  very failures the codes distinguish. Narrow the skip to the specific benign
+  `code` and **re-throw** the rest.
+- **Guard the parse step, not just the read and the validation around it.**
+  A read-then-`JSON.parse`-then-validate sequence needs the same typed-error
+  treatment on all three steps. Do **not** chain a raw `SyntaxError` as
+  `cause` when the file may hold sensitive content — Node embeds a snippet of
+  the malformed content in the message, and the cause chain carries it
+  forward to a log/stderr sink.
+- **Fail loud on caller/config errors; stay lenient only on external data.**
+  Validate caller- and config-supplied input at the public boundary and throw
+  a typed error on violation. Reserve tolerant handling (skip / default /
+  warn) for data you don't control (file contents, network payloads).
+- **Narrow a `try`/`catch` to just the fallible call, never the
+  post-processing.** Wrapping response-mapping inside the same `try` as an
+  async SDK/IO call mislabels a future local bug in the mapping as an upstream
+  failure. Assign the awaited result inside `try`/`catch`, build the return
+  value after the `catch` block resolves.
+- **Co-locate by a shared value, not by shared code.** When two independent
+  mechanisms must agree on a derived path/id/name, give ONE owner the raw
+  value and have both derive the result through a single shared helper —
+  never let each capture its own copy and re-derive independently, which
+  drifts silently.
+- **Never put a bare URL in TSDoc.** Reference sibling modules with `{@link
+Symbol}` or a backticked relative path. Nothing validates link targets, so an
+  invented host survives review by eye — grep new source for `http` before
+  committing.
+- **`Object.hasOwn(record, field)`, not `record[field] !== undefined`, when
+  reading a field off untrusted or partially-trusted input.** Bracket access
+  walks the prototype chain, so a record with no own `field` (e.g. one
+  literally named `"__proto__"`) can silently resolve an inherited — or,
+  under prototype pollution, attacker-controlled — value instead of the
+  "absent" the caller expects.
+- **Validate a local copy, never the property expression — `Object.hasOwn`
+  guards _presence_, not _stability_.** Each mention of `x.f` is a **separate
+  read**, and an accessor may answer differently every time:
+  ```ts
+  // BAD — three reads; the value returned is not the value validated
+  const bad = typeof e.n === "number" && Number.isFinite(e.n) ? e.n : null;
+  // GOOD — one read
+  const raw: unknown = e.n;
+  const good = typeof raw === "number" && Number.isFinite(raw) ? raw : null;
+  ```
+- **A cast across a serialization boundary hides the PROTOTYPE, not just the
+  shape.** A stream that rebuilds nodes with a null prototype can answer
+  `Array.isArray === true` while the array has no `.slice`. Re-hydrate with
+  `structuredClone` first, never `JSON.parse(JSON.stringify(...))`, which
+  also turns `-0` into `0` behind the narrowing layer.
+- **Allowlist, never denylist, for a redaction or sanitization boundary.**
+  Enumerate the fields you keep; drop everything else. A pattern that tries
+  to _recognize_ what is unsafe (a regex over URLs, key-name heuristics) is a
+  denylist against unbounded input and does not converge. Where the input is
+  genuinely free text, say "best effort" in the TSDoc and reclassify the
+  artifact instead of promising a guarantee.
+- **Every caller-supplied value crossing the public boundary is validated
+  once, at the boundary — including depth and recursion bounds — and that
+  validation's guarantee must hold all the way to where the value is used.**
+  Two hazards: **(1) never validate a caller value and then let something
+  else re-read it** — a non-idempotent getter, a non-enumerable own `toJSON`
+  invisible to `Object.keys` but applied by the serializer. Do the traversal
+  **once**: validate and project into a fresh structure, then derive the
+  downstream artifact from the projection, never the original. **(2) an
+  unbounded recursion or loop over caller-supplied structure is itself
+  unvalidated input**, even when every individual read is guarded — depth
+  and iteration count need their own explicit ceiling, checked before
+  recursing, not discovered as a bare `RangeError`/stack overflow at runtime.
+- **`JSON.stringify` is typed `string` but returns `undefined`** — for a bare
+  `undefined`, a function, a symbol, or an object whose `toJSON()` returns
+  one. A template literal launders that into the text `"undefined"`, which
+  writes and hashes cleanly and parses as nothing. Assert it is a string
+  before measuring, writing, or digesting it.
+- **A TSDoc sentence asserting a security or correctness property is a claim
+  to verify, not prose to write.** After the last contract change of a task,
+  re-read every guarantee sentence against the code, not against the plan. A
+  "never surfaced to the caller"-style claim needs a **per-channel** audit: a
+  resolved value and a thrown error's `cause`/`message` are separate
+  observable channels, and a claim proven true for one can still be false
+  for the other.
+- **"Additive" is about construction, not just consumption.** Before calling
+  an added field on an options/context type additive, grep the whole repo —
+  tests included — for hand-construction of that type. A **required** field
+  added to any type that a caller or a test fake _constructs_ is
+  source-breaking, even when production code only ever _receives_ it.
+- **Trust the CLI gate over the IDE/LSP.** Editor diagnostics lag and
+  misreport against the project `tsconfig`. A passing `pnpm typecheck` /
+  `pnpm lint` is the source of truth — don't chase a red squiggle the CLI
+  says is clean.