@monte3l/groundwork 1.0.0-rc.2 → 1.0.0-rc.4

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

@@ -39,7 +39,37 @@ gh pr view --json state,mergedAt,headRefName,baseRefName
 Record `headRefName` — every later step operates on this branch, not
 whatever the user typed.
 
-### 2 — Return to `main` and pull
+### 2 — Check for a linked worktree
+
+`headRefName` may be checked out in a linked worktree (created by
+`claude --worktree`, the `EnterWorktree` tool, or `git worktree add`) rather
+than in the main checkout directly — check before assuming otherwise:
+
+```bash
+git worktree list --porcelain
+```
+
+If a worktree has `headRefName` checked out:
+
+- **If the session entered it via `EnterWorktree`/`--worktree` and is still
+  there**, use the `ExitWorktree` tool (keep, don't remove — removal happens
+  safely in Step 4, after the merge-ancestry check) to return to the main
+  checkout _first_. `git checkout main` below fails outright ("already used
+  by worktree") because `main` is already checked out in the main worktree —
+  git refuses to check out the same branch in two places at once, regardless
+  of which branch the other worktree happens to be on. (If the session
+  merely `cd`'d into a plain `git worktree add` checkout — no `EnterWorktree`
+  involved — `ExitWorktree` has nothing to exit; just `cd` back to the main
+  checkout instead.)
+  After `ExitWorktree`, run `git config core.bare`: Claude Code's worktree
+  tools have been reported to leave it `true` in a normal repository's shared
+  config (anthropics/claude-code#58345, #69802), which breaks `git status`
+  here. If it prints `true`, run `git config --local core.bare false` before
+  going on.
+- Otherwise, no action needed yet — just remember the worktree's path for
+  Step 4.
+
+### 3 — Return to `main` and pull
 
 ```bash
 git checkout main
@@ -48,7 +78,7 @@ git pull
 
 Skip this if already on `main` with nothing to pull.
 
-### 3 — Delete the merged branch
+### 4 — 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
@@ -63,6 +93,24 @@ 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.
 
+**If Step 2 found a linked worktree for this branch, remove it before
+deleting the branch** — `git branch -d`/`-D` refuses a branch that's still
+checked out anywhere. `status --porcelain` only reports tracked and
+untracked-but-not-ignored changes — it says nothing about a gitignored file
+that only exists in this worktree (a `.env`, an in-progress scratch file),
+so **confirm with the user before running `remove`**, the same as `unlock`,
+rather than treating an empty `status --porcelain` alone as proof there's
+nothing to lose:
+
+```bash
+git -C <worktree-path> status --porcelain   # must be empty; investigate first if not
+git worktree unlock <worktree-path>          # only if locked, and only after confirming with the user
+git worktree remove <worktree-path>          # confirm with the user first -- see above
+git worktree prune
+```
+
+Then delete the branch itself:
+
 ```bash
 git branch -d <headRefName>
 ```
@@ -72,7 +120,7 @@ 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
+### 5 — Prune stale remote-tracking refs
 
 ```bash
 git fetch --prune
@@ -82,7 +130,7 @@ 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
+### 6 — 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
@@ -98,20 +146,20 @@ 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
+### 7 — 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
+### 8 — Report
 
-One-line summary: branch deleted (or kept, with why), refs pruned, work log
-present/written/skipped, journals swept/left.
+One-line summary: worktree removed (if any), 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.
+(worktree unlock/removal, 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

@@ -17,8 +17,15 @@ description: >-
 
 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`.
+by what's actually being asked, not by surface phrasing: a question that
+names one setting, one hook, one agent, or one narrow facet of `.claude/` —
+even when phrased as "is X still current" — stays `research`, because
+there's one thing to look up and answer. A request that names no specific
+facet, that asks about the whole `.claude/` surface ("our harness", "are we
+behind"), or that's periodic/`/customize`-driven, is `refresh`. When
+genuinely torn between the two, default to `research` — it's cheaper and
+faster — and say in the answer that a full `refresh` sweep is available if
+the question turns out to implicate more than the one facet asked about.
 
 **Must only run in the main (hub) agent, never inside a subagent** — it ends
 in `EnterPlanMode` (refresh) or dispatches other agents (either mode), which
@@ -104,8 +111,7 @@ concern) — every other facet below is identical regardless of project kind.
 
    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:
+   facet id, and this verdict format per claim:
 
    ```
    CLAIM: <the tracker's prior claim, or "NEW" if none existed>
@@ -114,10 +120,13 @@ concern) — every other facet below is identical regardless of project kind.
    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).
+   Return value: **the full verdict list inline, inside the ~8,000-character
+   cap** -- `Explore` holds no write tool, so it cannot write a file. Put
+   every non-"none" REPO-IMPACT claim first so a truncation drops only
+   the no-impact ones. The hub saves each returned report to
+   `<run-dir>/<facet-id>.md` itself; that is what step 4 reads.
 
-4. **Aggregate.** Read every scratchpad file in full. Four buckets:
+4. **Aggregate.** Read every saved facet report 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.

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

@@ -76,6 +76,11 @@ surface the decisions still open.
 
 ### 5 — Act on the confirmed decisions
 
+If `.claude/skills/working-in-worktrees/` exists (an optional add-on, not
+part of this baseline), use its start mode for this step instead of a bare
+`git switch -c` — it gets the same branch, plus an isolated worktree and its
+own installed dependencies in one move. Otherwise:
+
 ```bash
 git switch -c feat/<slug>   # or fix/<slug>
 ```

package/templates/core/.claude/skills/triaging-ci/SKILL.md

@@ -70,14 +70,15 @@ the first failure, typically the last 50–100 lines before the run aborted.
 
 ### 3 — Map to the pipeline step
 
-`.github/workflows/ci.yml`'s lanes each run `node bin/verify.mjs --step <id>`
-against a step id from `bin/lib/verify-steps.mjs` — that file's `cmd` field
-IS the local reproduction command, so mapping a failing CI step to its local
-command is always: find the `## <step name>` line the log shows, match it to
-the step's `name` in `bin/lib/verify-steps.mjs`, and reproduce with that
-step's `cmd` array joined as a shell command (or just `node bin/verify.mjs
---step <id>` directly). The step name usually appears verbatim in the log
-lines (e.g. `Run pnpm lint` or `##[error]...`).
+`.github/workflows/ci.yml`'s lanes each run `node bin/verify.mjs --group <name>`
+(`format`, `lint`, `typecheck`, `build`, `test`); a group runs every step
+in it from `bin/lib/verify-steps.mjs`, and that file's `cmd` field IS the
+local reproduction command. Find the `▶ <step name> (<id>)` line the log
+prints just before the failure, then reproduce with `node bin/verify.mjs
+--step <id>` (or the step's `cmd` array joined as a shell command). If no
+`▶` line is visible, match the failing job's name to its group and run
+`node bin/verify.mjs --group <name>`. `--step` is for local debugging only
+and never appears in a workflow file.
 
 ### 4 — Report the diagnosis
 

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

@@ -1,34 +1,53 @@
 ---
 name: typescript-guidance
 description: >-
-  Dual-mode TypeScript guidance skill. `research` mode answers a single
+  Three-mode TypeScript guidance skill. `research` mode answers a single
   TypeScript/toolchain question from owner-normative upstream sources only
   (typescriptlang.org, the devblog, microsoft/TypeScript releases,
   nodejs.org type stripping, typescript-eslint.io, attw, publint). `refresh`
   mode sweeps this project's whole TypeScript-facing surface — tsconfig,
-  eslint, packaging, and the test config/approach — against a living
-  tracker and produces a remediation plan. Use for /typescript-guidance,
-  "what does the TypeScript team say about X", "are we behind on
-  TypeScript", "is our tsconfig still current", or before changing a
-  compiler flag. Not how this project's config is wired today — that's
-  CLAUDE.md and the config files themselves.
+  eslint, packaging, the test config/approach — against a living tracker and
+  produces a remediation plan. `gaps` mode profiles the toolchain offline,
+  then researches live before recommending tooling the project does NOT have
+  yet, each recommendation with a source fetched that run. Use for
+  /typescript-guidance, "what does the TypeScript team say about X", "are we
+  behind on TypeScript", "is our tsconfig still current", "what tooling are
+  we missing", or before changing a compiler flag. Not for a general Claude
+  Code automation review, and not how this project's config is wired today
+  — that's CLAUDE.md and the config files.
 ---
 
 # typescript-guidance
 
-One skill, two modes, sharing one allowlist
+One skill, three modes, sharing one allowlist
 (`references/typescript-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`.
+mode by what's actually being asked, not by surface phrasing. First, is the
+thing not configured at all? "What are we missing", "any gaps in our
+toolchain", "should we add typed linting" are `gaps` even when they name one
+tool, because absence decides it. Otherwise a question that names one flag,
+one setting, or one narrow facet — even when phrased as "is X still
+current" — stays `research`, because there's one thing to look up and
+answer. A request that names no specific facet, that asks
+about the whole TypeScript-facing surface ("our tsconfig", "our toolchain",
+"are we behind"), or that's periodic/`/customize`-driven, is `refresh`. A
+request about tooling the project **doesn't have at all** is `gaps`,
+whereas "X is configured, is it still right" is `research` or `refresh`,
+never `gaps`. When genuinely torn between `research` and `refresh`, default
+to `research` — it's cheaper and faster — and say in the answer that a full
+`refresh` sweep is available if the question turns out to implicate more
+than the one facet asked about.
 
 **Must only run in the main (hub) agent, never inside a subagent** — it ends
-in `EnterPlanMode` (refresh) or an `AskUserQuestion` (either mode,
-occasionally), neither of which a subagent can do.
+in `EnterPlanMode` (refresh) or an `AskUserQuestion` (research or refresh,
+occasionally), and every mode launches parallel `Explore` research agents,
+none of which a subagent can do (`disallowedTools: Agent` on every spoke).
 
 **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.
+refresh mode writes to exactly one file, the tracker, in Step 5; `gaps` mode
+never writes a file — it proposes, and hands any accepted recommendation to
+`starting-work` and the normal TDD pipeline.
 
-## Authority (read this before either mode)
+## Authority (read this before any mode)
 
 This skill has authority over **every TypeScript-facing file in the
 project** — `tsconfig.base.json`, `tsconfig.json`, `eslint.config.js`,
@@ -40,6 +59,17 @@ its config shape), `package.json`'s TypeScript-toolchain entries, packaging
 **most deeply**, never which facets it may or may not touch. A facet with
 low priority still gets swept; it just gets less dedicated attention per run.
 
+`gaps` mode never overlaps that authority. It covers what's **missing** — a
+flag, script, config block or package the project doesn't have configured at
+all. Drift in something that already exists is `research`'s or `refresh`'s
+question and is never re-answered under `gaps`; if a `gaps` profile turns out
+to be "configured but looks stale", say so and switch mode instead of
+writing a recommendation. Any compiler-flag or config change `gaps`
+proposes goes through `research` before it is implemented: `gaps`' live
+research is scoped to "does this exist, and what's the current recommended
+shape if we add it", and doesn't carry `research`'s full precedence and
+conflict-resolution machinery for an existing value.
+
 ## Research mode
 
 1. **Scope the topic.** Read the topic from the invocation or the
@@ -108,8 +138,7 @@ low priority still gets swept; it just gets less dedicated attention per run.
 
    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:
+   facet id, and this verdict format per claim:
 
    ```
    CLAIM: <the tracker's prior claim, or "NEW" if none existed>
@@ -118,10 +147,13 @@ low priority still gets swept; it just gets less dedicated attention per run.
    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).
+   Return value: **the full verdict list inline, inside the ~8,000-character
+   cap** -- `Explore` holds no write tool, so it cannot write a file. Put
+   every non-"none" REPO-IMPACT claim first so a truncation drops only
+   the no-impact ones. The hub saves each returned report to
+   `<run-dir>/<facet-id>.md` itself; that is what step 4 reads.
 
-4. **Aggregate.** Read every scratchpad file in full. Four buckets:
+4. **Aggregate.** Read every saved facet report 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.
@@ -133,6 +165,89 @@ low priority still gets swept; it just gets less dedicated attention per run.
    confirmed-drift item. No drift → skip plan mode, report a clean sweep,
    still update the tracker.
 
+## Gaps mode
+
+Recommends TypeScript-ecosystem **tooling the project doesn't have yet** and
+never rules on tooling it already has. Every recommendation is grounded on
+official guidance fetched **live**, in this run: cross-project compatibility
+state (a new TypeScript major before `typescript-eslint` supports it, a
+package-manager major dropping a setting) shifts on its own schedule, so
+anything baked into this file as a fixed answer would go stale within months.
+This mode ships no answers, only where to look and what to ask.
+
+1. **Profile (offline; no network calls).** Establish what the project
+   already has before researching anything:
+   - `package.json`'s `scripts`, `dependencies`, `devDependencies`, and
+     `pnpm-workspace.yaml` (workspaces, `catalog`/`catalogs`) if present;
+   - the resolved tsconfig chain — every `tsconfig*.json` following
+     `extends`, using `bin/lib/toolchain-rules.mjs`'s tsconfig-chain
+     resolution if it exists rather than re-deriving the rules by hand;
+   - lint/test/hygiene config — `eslint.config.*` (or `.eslintrc.*`),
+     `vitest.config.ts` (or another runner's), `knip.json`;
+   - existing gates — run `node bin/check-toolchain.mjs` if present, and
+     read `.groundwork/inventory.json` if present (its `toolchainGrade` and
+     `toolchainConformance` are exactly this profile, already computed);
+   - budget — count `.claude/agents/*.md`, `.claude/skills/*/`,
+     `.claude/hooks/*.{mjs,js}`, `.github/workflows/*.yml` and
+     `package.json`'s `scripts` keys if the project states a cap on any of
+     them (`CLAUDE.md`, or an adoption report's cap table): with no room
+     left, prefer a `verify-steps` gate over a new `package.json` script;
+   - verify-step wiring — `bin/lib/verify-steps.mjs` /
+     `bin/lib/verify-steps.packs.json`, or whatever gate runner exists.
+
+   Map every signal to the areas in `references/area-catalog.md`, which names
+   the signals to look for and the questions to research per area and holds
+   no answers of its own. An area with no signal at all (no monorepo hints,
+   no release workflow) still gets a light pass: "you have none of this,
+   here is what to consider" is itself a recommendation, not silence.
+
+2. **Research live (mandatory).** No recommendation reaches the report
+   without a source fetched in this run. Read `references/tooling-sources.md`
+   (the ecosystem-tooling allowlist) and `references/typescript-sources.md`
+   (the TypeScript-owner allowlist, reused rather than duplicated). Pick the
+   areas from `area-catalog.md` that the profile made relevant — or only the
+   one category the user named. **Launch all agents in a single message**,
+   always `subagent_type: "Explore"`, breadth `"very thorough"`, one per
+   relevant area. Each brief carries: that area's signals-and-questions
+   verbatim; both allowlists pasted verbatim, each with its own GitHub-path
+   caveat kept separate (a domain allowed by one file's caveat is not
+   automatically allowed by the other's); today's date; "reject any
+   non-allowlisted domain outright and say so, rather than substituting a
+   blog post or an individual author's material"; "you hold no write tool —
+   findings travel only in your response"; research mode's findings format
+   above; and an ~8,000-character (~2,000-token) return cap. Read every
+   agent's full inline findings. A failed or empty fetch for an area is a
+   **coverage gap**, reported as such — never dropped, never backfilled from
+   an unlisted source.
+3. **Report.** In this order:
+   - **Codebase profile** — a short summary of what step 1 found, so the
+     reader can see the recommendations are grounded in this project.
+   - **Recommendations** — 1–2 per relevant area (3–5 for a single area the
+     user named). Each gives: **Why** (the specific project signal, not
+     "generally good practice"), **What** (the concrete config block, script
+     or package to add), **Source** (the URL, fetched today, with its tier),
+     and **Cost** (cap impact, and whether it's a `verify-steps` gate or a
+     `package.json` script).
+   - **Unverified claims** — a signal step 2 could not verify against an
+     allowlisted source is named as "unverified — not recommended", not
+     omitted.
+   - **No web tools at all** (offline, sandboxed): report the profile alone,
+     say plainly that no live research ran, and recommend nothing — an
+     unverified recommendation is worse than none.
+   - **Hand-off** — point any accepted recommendation at `starting-work`
+     (branch first) and the normal test-author → code-implementer →
+     review-spoke pipeline. This mode never writes the change itself.
+
+**Recommendation discipline.** Never recommend adding a tool or preset that
+live research shows doesn't yet support the project's current toolchain
+version: recommending something that can't be installed against the
+already-pinned TypeScript is worse than recommending nothing, so name the
+incompatibility as a blocker instead. (Second-guessing a version the project
+already pinned is `research`'s territory, not this mode's.) When the
+project's scripts are at their cap, prefer a `verify-steps` gate
+(`["node", "bin/check-x.mjs"]`, no `package.json` script needed) over a new
+script.
+
 ## Why this exists, separately from "how is our config wired"
 
 Research mode answers "what does upstream say about X." Nothing else in the
@@ -140,4 +255,6 @@ baseline asks the inverse — "is what's already configured still what
 upstream recommends" — because every lint/typecheck/test gate is a closed
 loop checking the repo against its own prior decisions. A stale pin one
 major behind upstream passes every one of those gates cleanly; only a live
-sweep against the actual upstream surfaces it.
+sweep against the actual upstream surfaces it. For the same reason, a
+missing tool trips no gate at all — nothing fails when a check that was
+never installed doesn't run — which is what `gaps` mode is for.

package/templates/core/.claude/skills/typescript-guidance/references/area-catalog.md

@@ -0,0 +1,135 @@
+# Area catalog -- signals to detect, questions to research
+
+For each area: what to look for in `gaps` mode's step 1 (the signal), and what to ask a
+step 2 research agent (the question). **This file holds no answers** --
+an answer here would be exactly the kind of baked-in claim that goes stale
+within months. Pick the areas step 1's signals make relevant; don't
+research every area unconditionally on every run.
+
+## tsconfig flags and deprecations
+
+- **Signal**: the resolved tsconfig chain (step 1) is missing a
+  strict-family flag entirely, or sets no `target`/`lib` at all for the
+  project's actual runtime.
+- **Research**: what compiler options does the current TypeScript release
+  recommend adding for this project's runtime target (Node-only, browser,
+  both), for a tsconfig that doesn't set them yet? (Whether an option the
+  project already sets has since been deprecated, or an already-set
+  `target`/`lib` is now outdated, is drift in existing config --
+  `research`/`refresh`'s question, not `gaps` mode's; hand it off rather
+  than research it here.)
+
+## module resolution by project kind
+
+- **Signal**: no `moduleResolution` set anywhere in the resolved tsconfig
+  chain at all.
+- **Research**: what does the current TypeScript Modules reference recommend
+  for this project's actual shipping shape (published package vs. bundled
+  app vs. both), for a tsconfig that doesn't set one yet? (An already-set
+  `moduleResolution` that doesn't match what the project actually ships --
+  a package with an `exports` map on `node16`/`nodenext` that should be on
+  `bundler`, say -- is drift in existing config, `research`/`refresh`'s
+  question, not `gaps` mode's.)
+
+## typed linting
+
+- **Signal**: `eslint.config.js` has no `typescript-eslint` typed-linting
+  preset (`recommendedTypeChecked`/`strictTypeChecked`/`stylisticTypeChecked`)
+  configured at all.
+- **Research**: what does typescript-eslint's current documentation recommend
+  for a project with no typed linting yet -- and, since a recommendation to
+  add it must actually be installable, does the version that would be added
+  support the project's current TypeScript version? This is exactly the kind
+  of cross-project compatibility gap a stale skill answer would miss (a new
+  TypeScript major that `typescript-eslint` doesn't support yet, say).
+  (Whether an _already-pinned_
+  `typescript-eslint` version is stale or incompatible is drift in existing
+  config -- `research`/`refresh`'s question, not `gaps` mode's.)
+
+## testing
+
+- **Signal**: no test runner configured at all.
+- **Research**: what does the current official docs of a reasonable default
+  test runner recommend for a TypeScript project with none configured yet --
+  config shape, coverage tooling, and any TypeScript-specific caveat
+  (type-checking test files, `expectTypeOf`-style assertions)? (A runner that
+  already exists but has no coverage gate, or whose config no longer matches
+  its own current docs, is drift in existing config -- `research`/`refresh`'s
+  question via its `testing-language-features` facet, not `gaps` mode's.)
+
+## packaging and export validation
+
+- **Signal**: a published package (has a `bin` or `exports` field, isn't
+  `private: true`) with no `publint`/`arethetypeswrong` check wired into its
+  verify gate.
+- **Research**: what do `publint.dev` and `arethetypeswrong.github.io`
+  currently flag as common packaging mistakes, and is either tool's current
+  recommended invocation different from a bare CLI call (e.g. a config
+  flag this project should pass)?
+
+## dependency hygiene
+
+- **Signal**: no `knip` (or equivalent unused-export/unused-dependency
+  tool) configured at all.
+- **Research**: what does `knip.dev`'s current documentation recommend for
+  a project shaped like this one (workspaces, multiple entry points, a CLI
+  `bin`) that has no such tool yet? (An existing `knip.json` that looks stale
+  against the project's actual entry points is drift in existing config, not
+  absence -- `knip.json` is a `research`/`refresh` domain file; switch mode
+  rather than researching a fix here.)
+
+## pnpm supply-chain settings
+
+- **Signal**: `pnpm-workspace.yaml`/`.npmrc` has no supply-chain-hardening
+  setting configured at all -- no lifecycle-script allowlist, no
+  `packageManager` corepack pin in `package.json`, no audit setting.
+- **Research**: what supply-chain-hardening settings does the project's
+  actual pnpm major currently document (lifecycle-script allowlisting,
+  `minimumReleaseAge`, audit settings), for a project that has none
+  configured yet? (Whether an existing setting has since been renamed or
+  removed by a newer pnpm major -- a lifecycle-script allowlist key moving
+  to a different file, for example -- is drift in something already
+  configured, not absence; hand it to `research`/`refresh` rather than
+  research it here, since `pnpm-workspace.yaml` is one of its own domain
+  files.)
+
+## scripts and verify gates
+
+- **Signal**: a check this project runs by hand (or not at all) that a
+  comparable project would gate in CI -- a missing `check:exports`-equivalent
+  on a published package, no `pnpm verify`-shaped aggregator at all.
+- **Research**: n/a in the live-fetch sense (this is a project-structure
+  question, not an upstream-guidance one) -- but check whether the project's
+  gate runner shape (a package script vs. a dedicated
+  `bin/verify.mjs`-style aggregator) matches current tooling convention for
+  its ecosystem before recommending which shape to add.
+
+## monorepo and catalogs
+
+- **Signal**: multiple `package.json` files under one root with no
+  `pnpm-workspace.yaml`, or a workspace with repeated identical dependency
+  version pins across packages that pnpm's `catalog`/`catalogs` feature
+  exists to deduplicate.
+- **Research**: what does pnpm's current workspace/catalog documentation
+  recommend for this shape, and does the pinned pnpm major actually support
+  the catalog syntax being recommended?
+
+## Node version pinning
+
+- **Signal**: no Node version pin anywhere at all -- no `.node-version`, no
+  `.nvmrc`, no `engines.node`.
+- **Research**: what does `nodejs.org`'s current release schedule recommend
+  pinning to for a new project? (A disagreement between multiple existing
+  pins, or a pin that's already past its documented end-of-life, is drift in
+  something already configured -- `research`/`refresh`'s question, not
+  `gaps` mode's.)
+
+## release automation
+
+- **Signal**: a package that's published (not `private: true`) with no
+  automated release pipeline (no changesets, no equivalent version-bump
+  automation).
+- **Research**: what does `changesets/changesets`'s current documentation
+  recommend for this project's publishing shape (single package vs.
+  workspace)? If the project already has a release workflow, that is drift
+  in existing config, not a gap -- hand it to `research`/`refresh`.