@monte3l/groundwork 0.0.0

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

@@ -0,0 +1,129 @@
+---
+paths:
+  - "**/tests/**"
+  - "**/*.test.ts"
+---
+
+# Testing rules (`tests/**`, `*.test.ts`)
+
+> This file is the terse checklist that auto-loads when you edit a test.
+
+- **Assert the named behavior, not a proxy** — not `length > 0`, and not
+  merely that the call "doesn't throw". A positive and a negative claim
+  BOTH met by nothing happening need the positive one asserted explicitly
+  too.
+- **A test that claims to guard something must be mutation-tested before you
+  believe it guards anything** — delete the guard clause, invert the flag,
+  drop a wrapper, and confirm the test fails.
+- **A surviving mutant is a question, not automatically a defect — and a
+  mutation that never applied is not a survivor at all.** An _equivalent_
+  mutant (both branches agree on every reachable input under a
+  runtime-enforced invariant) needs a note, not a new test; verify a
+  scripted mutation actually changed the file before trusting a "survivor".
+- **A check whose two sides come from ONE source can never fail** — a fake
+  store that ECHOES the value under test passes either way. Pin at least
+  one side by hand.
+- **A mutation-tested guard can go vacuous LATER** — it proves teeth only at
+  the moment you run it. When a change adds a consumer of a signal a test
+  observes INDIRECTLY (a property read, a call count), re-mutate the tests
+  watching it.
+- **Never make a test double wait by counting event-loop turns** — a
+  `setImmediate` retry-N-times loop is a latency guess passing locally and
+  failing under CI load. Anchor the emit to a structural guarantee instead.
+- **Rebuild before trusting a cross-package result.** If tests resolve a
+  sibling package through its build output rather than its source, run the
+  build first — a stale `dist/` fails tests in an untouched package after an
+  export changes, and a `src/` edit never reaches a consumer's suite until
+  rebuilt.
+- **A test naming a precedence, ordering, or "every X" guarantee must make
+  every arm reachable in its own setup** — exactly right yet prove nothing
+  if the discriminating precondition never fires. Enumerate the set
+  (`test.each`), not one member of it.
+- **Never mock the behavior the test exists to validate** — a stub echoing
+  back the outcome under question asserts the stub, not the code, while
+  still reading as coverage. Exercise the real collaborator at least once.
+- **No network; real filesystem only inside a per-test `mkdtemp` sandbox**,
+  torn down in the same test. An integration-test directory that genuinely
+  needs the real network is the one deliberate exception — mark it clearly
+  and keep it out of the default unit run.
+- **A type-only `expectTypeOf` test still executes its expression at
+  runtime** — if it invokes a fallible async method, resolve the mock to a
+  valid value first, or a rejecting un-awaited promise surfaces despite the
+  type assertion passing.
+- **A gate failing outside your change's blast radius is presumed
+  pre-existing until disambiguated** — `git diff origin/main -- <path>`
+  settles it in seconds. Not licence to retry blind: an unexplained green
+  re-run is itself a flake to diagnose and file.
+- **Mock an SDK package the same way once it mixes class and data
+  exports** — a plain `vi.mock("pkg", () => ({...}))` object literal
+  silently omits unlisted exports, harmless for a type-only import but
+  fatal once a value import (a data-only enum) resolves to `undefined` at
+  module-load time. Default to an `importOriginal`-preserving async factory.
+- **A dynamic-`import()`-only step module can mock with a plain `const
+stepMock = vi.fn()`; once production code adds a _static_ import from that
+  module, move the mock to `vi.hoisted(() => vi.fn())`** — a plain `const`
+  initializes after `vi.mock` calls are hoisted.
+- **Mock a port with generic methods by inference, not `extends`** — a
+  generic method (`select<Value>(...)`) can't be mocked via `interface Mock
+extends Port { ... }` (TS2430). Let the factory return the inferred
+  `vi.fn()` object instead.
+- **Test-first, not test-after** — write tests from the documented contract,
+  watch them fail for the right reason, then implement — don't backfill a
+  test that just mirrors code you already wrote.
+- **Justify intentional `eslint-disable` on the error channel** — a test
+  proving normalization throws non-`Error` values on purpose, tripping
+  `only-throw-error`. Disable narrowly with a `--` rationale:
+
+```ts
+// eslint-disable-next-line @typescript-eslint/only-throw-error -- intentional non-Error to verify the unknown channel
+throw "a string";
+```
+
+- **Assemble a secret-shaped fixture at runtime, never as a single source
+  literal**, if this repo runs a secret scanner over source text —
+  concatenate two substrings instead of writing the shape whole.
+
+### Test-tooling gotchas
+
+- **`not.toHaveProperty` cannot prove own-key absence** — chai falls back to
+  `"key" in Object(obj)` and walks the prototype chain. Assert
+  `Object.hasOwn(result, "f")` instead, and restore a polluted prototype in
+  an **unconditional** `afterEach` (`Reflect.deleteProperty`,
+  `configurable: true`).
+- **Runtime-green ≠ typecheck-green** — Vitest transforms without
+  type-checking, so run `pnpm typecheck` as its own gate on every test file
+  you touch.
+- **`pnpm build` is a distinct gate from `pnpm typecheck`, not a slower
+  version of it** — `isolatedDeclarations` (the `tsconfig.build.json`
+  project only) makes an additive `as const satisfies` pass `typecheck` and
+  fail `build` with TS9010. Any exported-type change needs both.
+- **A test that deliberately avoids importing from `src` can strand an
+  export and fail `pnpm knip`** — keep both a hand-authored table and an
+  import for projection identity. `knip` is not gated in `pre-push` by
+  default — run it yourself after touching any export.
+- **eslint runs in-loop** (prettier → eslint → typecheck → vitest) —
+  resolve findings as you write, don't defer to a later `pnpm lint` pass.
+- **Thread `now` as an injectable parameter on a time-dependent guard**
+  rather than defaulting to `Date.now()` inside it — a sibling function's
+  fixed-timestamp fixtures are the tell.
+- **Read coverage from `coverage/coverage-final.json`, not the
+  `pnpm test:coverage` text table.** The v8 text reporter omits files that
+  are 100% on every metric, so an absent file in the table is not an
+  uncovered file.
+- **A fix round adding branches isn't done until the _gated_ run passes** —
+  per-file thresholds run only under `test:coverage`, never a scoped
+  `vitest` call. Trace the gap from `coverage-final.json`'s uncovered-line
+  list and cover any new ternary's non-`Error` arm in the same edit.
+- **A suite failing while a spoke fan-out is running may be contention, not
+  a regression — re-run it alone first.**
+- Use `pnpm exec vitest`; a bare `npx vitest` can fail to resolve
+  `@vitest/coverage-v8` under pnpm.
+- **Brace void-union handler bodies** — a handler typed `void |
+Promise<void>` whose arrow body returns a value fails typecheck (TS2322);
+  the leniency applies only to a return type of _exactly_ `void`. Wrap the
+  body: `() => { arr.push(v); }`.
+- **Never explicitly parameterize `vi.spyOn<T, S>`'s return type** — an
+  explicit type argument resolves against the first overload regardless of
+  which one the call matches, failing a method spy with a `never`-constraint
+  error though the runtime call is correct. Let TypeScript infer it from the
+  `return` statement instead.

package/templates/core/.claude/settings.json

@@ -0,0 +1,111 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/inject-decision-gate.mjs\"",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-git-push-signed.mjs\"",
+            "timeout": 30
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-double-background.mjs\"",
+            "timeout": 30
+          }
+        ]
+      },
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-js-extension.mjs\"",
+            "timeout": 30
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-no-commonjs.mjs\"",
+            "timeout": 30
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-protected-paths.mjs\"",
+            "timeout": 30
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-branch-isolation.mjs\"",
+            "timeout": 30
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-hub-src-writes.mjs\"",
+            "timeout": 30
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-secret-writes.mjs\"",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/post-edit-verify.mjs\"",
+            "if": "Write(*.ts)",
+            "timeout": 180
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/post-edit-verify.mjs\"",
+            "if": "Edit(*.ts)",
+            "timeout": 180
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/post-edit-verify.mjs\"",
+            "if": "Write(*.mts)",
+            "timeout": 180
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/post-edit-verify.mjs\"",
+            "if": "Edit(*.mts)",
+            "timeout": 180
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/post-edit-verify.mjs\"",
+            "if": "Write(*.cts)",
+            "timeout": 180
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/post-edit-verify.mjs\"",
+            "if": "Edit(*.cts)",
+            "timeout": 180
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/core/.claude/skills/creating-prs/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: creating-prs
+description: >-
+  Verify quality gates, push the branch, open a PR with a Conventional Commit
+  title and body from commit history, then decide and execute its merge
+  path. Use for /creating-prs, "open a PR", "create a pull request", "ship
+  this for review", "get this merged", or after finishing a fix. Requires gh
+  CLI auth.
+---
+
+# creating-prs
+
+Takes a branch with committed work from "ready" to "opened, gated, and
+merged (or left for human review)". Assumes `starting-work` already put you
+on the right branch.
+
+## Steps
+
+### 1 — Preflight
+
+Confirm you're not on `main` and the tree is clean (`git status --porcelain`
+empty, or everything intentionally staged). If dirty, resolve before
+continuing — an uncommitted file left behind silently ships in the next
+commit on this branch.
+
+### 2 — Resync with `origin/main`
+
+```bash
+git fetch origin
+git rebase origin/main
+```
+
+A branch that has drifted from `main` over a long session risks a conflict
+surfacing at merge time instead of now, when it's cheaper to resolve.
+
+### 3 — Run the full quality gate
+
+```bash
+pnpm verify
+```
+
+This is the one command that reproduces what CI runs. Fix everything it
+reports before pushing — a red `pnpm verify` becomes a red CI run and a
+round-trip that costs more than fixing it now.
+
+### 4 — Pre-push review (optional but recommended)
+
+For anything beyond a trivial change, dispatch `code-reviewer` (and
+`silent-failure-hunter` if the diff has error-handling paths) over the diff
+before pushing. Catching a Must-fix here is strictly cheaper than catching
+it after a human reviewer has already looked.
+
+### 5 — Push
+
+```bash
+git push -u origin <branch>
+```
+
+Never `git push --force` a shared branch — if history was rewritten
+(a rebase), use `--force-with-lease` and only when you're certain no one
+else has pushed to this branch.
+
+### 6 — Gather commits since `main`
+
+```bash
+git log origin/main..HEAD --oneline
+```
+
+This is the raw material for the PR title and body — read every commit
+message, don't just count them.
+
+### 7 — Title
+
+A Conventional Commit–shaped title summarizing the PR as a whole (not just
+the first commit): `<type>: <subject>`, same rules as an individual commit
+subject (imperative, ≤70 chars, lowercase after the colon). If the PR
+contains a `feat!:` commit, the title carries `!` too.
+
+### 8 — Body
+
+Structure:
+
+```
+## Summary
+<1-3 sentences: what this PR does and why>
+
+## Changes
+- <bullet per meaningfully distinct change, not per commit>
+
+## Semver impact
+<one sentence: what changed in the public surface, or "none">
+
+## Test plan
+<how this was verified: `pnpm verify` passing, plus anything manual>
+```
+
+### 9 — Submit
+
+```bash
+gh pr create --title "<title>" --body "$(cat <<'EOF'
+<body>
+EOF
+)"
+```
+
+### 10 — Confirm mergeability
+
+```bash
+gh pr view --json mergeable,mergeStateStatus
+```
+
+If `mergeable: "CONFLICTING"`, resolve the conflict before proceeding to the
+next step — don't arm auto-merge on a PR that can't merge.
+
+### 11 — Decide the merge path
+
+- **CI is required and passing, and the change is low-risk** (docs, a
+  mechanical chore, a well-reviewed small fix): arm auto-merge
+  (`gh pr merge --auto --squash`) and move on — `finishing-work` picks up
+  once it actually merges.
+- **The change is substantive** (a new public symbol, a behavior change, a
+  breaking change): leave the PR open for human review. Report the PR URL
+  and stop here.
+- **CI is still running and the change is low-risk**: arm auto-merge anyway
+  — it fires the moment checks pass, no need to poll.
+
+## Notes
+
+- Use the `gh` CLI for every GitHub operation in this skill (issue/PR reads,
+  mutations, checks) rather than the raw REST API.
+- If the project has a PR template (`.github/pull_request_template.md`),
+  read it first and follow its structure instead of the generic shape above.

package/templates/core/.claude/skills/finishing-work/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: finishing-work
+description: >-
+  Runs the post-merge close-out tail creating-prs doesn't: verifies the PR
+  actually merged, returns to main and pulls, deletes the merged local
+  branches, prunes stale remote refs, and prompts for a work log. Use for
+  /finishing-work, "clean up after this PR", "the PR merged, wrap this up",
+  "delete the merged branches", "prune stale remote refs", or when a merged
+  branch or stale refs linger -- even when it sounds like a one-line git
+  command, because deleting a branch that never merged loses work and this
+  skill checks first. GitHub stance: gh CLI.
+---
+
+# finishing-work
+
+`creating-prs` ends with "decide the merge path" — it owns the merge itself,
+but nothing checks whether that merge actually happened, let alone cleans up
+afterward. Left undone, that residue accumulates silently: a stale local
+branch, stale remote-tracking refs, an orphaned dispatch journal in the
+scratchpad. This skill is that missing owner.
+
+## Steps
+
+### 1 — Confirm the PR actually merged
+
+Don't assume "the user said it merged" is enough — verify:
+
+```bash
+gh pr view --json state,mergedAt,headRefName,baseRefName
+```
+
+- `state: "MERGED"` with a non-null `mergedAt` → proceed.
+- `state: "OPEN"` → stop; the merge decision hasn't been made yet. Point back
+  at `creating-prs`'s merge-path step.
+- `state: "CLOSED"` with a null `mergedAt` → stop; the PR was closed without
+  merging. Ask whether the branch should still be cleaned up (abandoned work)
+  or left alone.
+
+Record `headRefName` — every later step operates on this branch, not
+whatever the user typed.
+
+### 2 — Return to `main` and pull
+
+```bash
+git checkout main
+git pull
+```
+
+Skip this if already on `main` with nothing to pull.
+
+### 3 — Delete the merged branch
+
+**Before removing anything, confirm no backgrounded command (a `git push`,
+a verify run, or similar) is still running against the branch you're about
+to delete.** Once a PR has GitHub auto-merge armed, a `git push` updating it
+after opening is racing the merge, not safely queued behind it. If a
+follow-up commit must land in the _same_ PR, verify the push landed and the
+PR still shows it as HEAD _before_ proceeding, or accept it may need a
+follow-up PR instead.
+
+Squash-merged branch commits are never ancestors of `main`, so "the PR
+merged" does not mean every commit on the branch landed. Run `git log
+<branch> ^origin/main --oneline` before any branch-deleting cleanup — a
+non-empty result is a commit about to be abandoned, not noise.
+
+```bash
+git branch -d <headRefName>
+```
+
+If `git branch -d` refuses (not merged into its base by ancestry — expected
+after a squash merge), don't force-delete without asking: confirm the merge
+really landed via `gh pr view` above, then use `git branch -D <headRefName>`
+only with the user's go-ahead.
+
+### 4 — Prune stale remote-tracking refs
+
+```bash
+git fetch --prune
+```
+
+Cheap and safe regardless of the branch outcome above — clears the
+`[deleted]` marker for this and any other already-merged branch's remote
+ref.
+
+### 5 — Work log check
+
+If the project keeps work logs (check whether a `docs/logs/` directory or
+equivalent convention exists), apply a substance test, not a commit-type
+filter: skip silently for a mechanical merge with no narrative (a dependency
+bump, a formatting sweep). Otherwise, ask whether one should be written now
+before moving on — real-time context degrades fast once the session that did
+the work is gone.
+
+**If a log is written here, commit and land it immediately** (its own small
+`docs:` commit via `writing-commits`) before moving on to any other task,
+rather than leaving it as an uncommitted file. **"Commit it" does not mean
+commit directly to `main`** — branch first (`git switch -c docs/<slug>-log`),
+commit there, push, and open a PR, even for a trivial docs-only change, if
+the project requires a PR for every change to `main`.
+
+### 6 — Orphaned journal sweep
+
+Check the scratchpad directory for any writer-spoke dispatch journal older
+than the current task that has no corresponding open work — ask before
+deleting, since a file from a different, still-in-progress task can look
+identical to a genuine orphan.
+
+### 7 — Report
+
+One-line summary: branch deleted (or kept, with why), refs pruned, work log
+present/written/skipped, journals swept/left.
+
+## Notes
+
+This skill is read-and-confirm heavy by design — every destructive step
+(branch delete, journal delete) asks first rather than assuming. A cautious,
+always-asks tail beats no tail at all.

package/templates/core/.claude/skills/harness-guidance/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: harness-guidance
+description: >-
+  Dual-mode Claude Code harness guidance skill. `research` mode answers a
+  single Claude Code / Anthropic-guidance question from official sources
+  only (anthropic.com, claude.com, code.claude.com, docs.claude.com, the
+  Claude Code CHANGELOG). `refresh` mode sweeps this project's whole
+  `.claude/` surface — settings, hooks, agents, skills, rules — against a
+  living tracker and produces a remediation plan. Use for
+  /harness-guidance, "what does Anthropic recommend for X", "is our harness
+  up to date with Anthropic", "model pins current". Not how this project's
+  harness is wired today — that's CLAUDE.md and the `.claude/` files
+  themselves.
+---
+
+# harness-guidance
+
+One skill, two modes, sharing one allowlist
+(`references/official-sources.md`) so they can't drift apart. Pick the mode
+from how you were invoked: a specific question → `research`; a periodic or
+`/customize`-driven sweep → `refresh`.
+
+**Must only run in the main (hub) agent, never inside a subagent** — it ends
+in `EnterPlanMode` (refresh) or dispatches other agents (either mode), which
+a subagent cannot do (`disallowedTools: Agent`).
+
+**No files are written by this skill itself** in research mode by default;
+refresh mode writes to exactly one file, the tracker, in Step 5.
+
+## Authority (read this before either mode)
+
+This skill has authority over the **whole `.claude/` surface** —
+`settings.json` and its hook wiring, every hook, every agent (frontmatter,
+model tiering, tool grants), every skill, every rule, and the emitted
+`CLAUDE.md`. It is **not** kind-scoped the way the interview's other answers
+are: the harness a project needs does not vary by whether it's a library or
+a frontend app, with one deliberate exception below. An interview-derived
+emphasis (from `/customize`'s kind-to-facet table) tells this skill which
+facet to research **most deeply**, never which facets it may or may not
+touch.
+
+**The one kind-keyed exception:** a `frontend`/web-app project's reviewer
+patterns genuinely differ (visual verification of a UI is a real, distinct
+concern) — every other facet below is identical regardless of project kind.
+
+## Research mode
+
+1. **Scope the topic.** Read the topic from the invocation or the
+   surrounding task; at most **one** clarifying question, otherwise infer
+   and proceed. Derive **3–5 orthogonal facets** — one per Explore agent.
+   Derive a kebab-case slug for the optional Step 5 snapshot.
+2. **Fan out.** Read `references/official-sources.md` first, then spawn
+   **all agents in a single message**. Each brief carries: one facet; the
+   allowlist + GitHub caveat pasted verbatim; today's date; "do not stop at
+   the first matching source — fetch every distinct one"; "reject any
+   non-allowlisted domain outright and say so"; "you hold no write tool —
+   findings travel only in your response"; the findings format below; and a
+   ~8,000-character (~2,000-token) return cap. Always `subagent_type:
+"Explore"`, breadth `"very thorough"`.
+
+   Findings format, one block per source:
+
+   ```
+   SOURCE: <URL>
+   CLAIM: <the specific claim, quoted or tightly paraphrased>
+   CONFLICT-WITH: <another SOURCE, if this claim contradicts it — omit if none>
+   ```
+
+3. **Aggregate & synthesize.** Read every agent's full inline findings —
+   digests are for triage, not synthesis. Assign `S1, S2, …` deduping; merge
+   agreement into single consensus points tagged with all supporting ids;
+   flag contradictions — current docs outrank an older blog post; a
+   model-specific guide outranks a general one.
+4. **Ask a clarifying question only if genuinely needed** — only when two
+   current, equally authoritative sources conflict in a way that changes the
+   invoking task.
+5. **Offer an optional snapshot.** Default is inline-only. On explicit
+   confirmation, write `docs/research/harness/<topic-slug>.md`, assembled
+   from Step 2's findings + Step 3's synthesis (not re-fetched), with a `>
+**Provenance** —` header naming today's date and the sources consulted.
+
+## Refresh mode
+
+1. **Read the tracker & establish anchors.** Read
+   `docs/research/harness-refresh.md`, its header
+   `<!-- harness-refresh: last-verified=<date> claude-code-version=<version> -->`.
+   Missing tracker/facet → first run, `NEW` only. Then read the allowlist
+   file; state today's date; derive a run directory
+   `<scratchpad>/harness-refresh-<date>/`.
+2. **Build the delta.** `WebFetch` the Claude Code CHANGELOG, extract
+   entries newer than the recorded version. An unreachable source is a
+   coverage gap, not a blocker. Pass this delta into all five briefs below
+   — it is not a sixth facet.
+3. **Fan out five fixed facets in one message** — fixed, not derived per
+   run, so sweeps stay comparable and the tracker stays diffable:
+
+   | Facet id                     | Emitted surface it validates                                         |
+   | ---------------------------- | -------------------------------------------------------------------- |
+   | `models-tiering`             | agent frontmatter `model`/`effort` fields                            |
+   | `cc-features-settings`       | `settings.json` shape, permissions, hook event coverage              |
+   | `agent-subagent-design`      | the 5 agents, tool grants, `disallowedTools`, the hub-and-spoke loop |
+   | `skills-context-engineering` | the skills, frontmatter, description length                          |
+   | `hooks-lifecycle`            | the 10 hooks, event names, matchers, the exit-code contract          |
+
+   Each brief carries: the facet row, Step 2's delta, the tracker's prior
+   claims for that facet, the allowlist + GitHub caveat + date anchor, the
+   exact filename to write (`<run-dir>/<facet-id>.md`), and this verdict
+   format per claim:
+
+   ```
+   CLAIM: <the tracker's prior claim, or "NEW" if none existed>
+   VERDICT: UNCHANGED | CHANGED | GONE
+   NOW: <the current official position>
+   REPO-IMPACT: <which emitted file(s) this affects, or "none">
+   ```
+
+   Return value: **write the full file, return only a compact digest**
+   (counts per verdict + every non-"none" REPO-IMPACT line + the file path).
+
+4. **Aggregate.** Read every scratchpad file in full. Four buckets:
+   confirmed drift with repo impact (verify each against the cited file
+   itself before trusting it — an agent can misread a page), guidance
+   changes with no impact, dead/moved URLs, coverage gaps.
+5. **Update the tracker in place** (not a new dated file) — this skill's
+   only write outside plan mode. Bump the header date + version, update
+   every checked claim's text/URL/date, add `NEW` sources, update the
+   outstanding-drift table.
+6. **`EnterPlanMode`** with a remediation plan, one section per
+   confirmed-drift item. No drift → skip plan mode, report a clean sweep,
+   still update the tracker.
+
+## Why this exists, separately from "how is our harness wired"
+
+Research mode answers "what does Anthropic recommend for X." Nothing else in
+the baseline asks the inverse — "is what's already built still what
+Anthropic currently recommends" — because a locally-passing `check:agents`/
+`check:hooks`-style check only verifies internal consistency, never freshness
+against the outside world. A retired model pin or a deprecated hook pattern
+passes every internal-consistency check cleanly; only a live sweep against
+Anthropic's own current docs surfaces it.