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

package/templates/core/.claude/skills/typescript-guidance/references/tooling-sources.md

@@ -0,0 +1,113 @@
+# Upstream tooling sources -- the allowlist
+
+The sibling allowlist to `typescript-sources.md` in this same directory
+(reused directly for the TypeScript-owner tier, not duplicated). This file
+is `gaps` mode's ecosystem-tooling list and covers the TypeScript-adjacent
+tooling `research` and `refresh` don't sweep: the package manager, the lint
+runner's non-TypeScript-specific config, the test runner, the formatter,
+dependency hygiene, and Node's own release schedule.
+
+**A `gaps`-mode research brief passes the union of both files' domain lists**
+when an area touches TypeScript itself (the tsconfig/typed-linting areas
+always need `typescript-sources.md`'s list too); an area this file alone
+covers (pnpm settings, Node pinning) needs only this file's list. Each file's
+own GitHub caveat applies only to the GitHub paths it names regardless -- a
+path allowed by `typescript-sources.md`'s caveat is not automatically allowed
+by this file's caveat, and vice versa.
+
+## Domain allowlist
+
+Pass verbatim as `WebSearch`'s `allowed_domains`, alongside
+`typescript-guidance`'s own list when both are in scope for a given area:
+
+```
+pnpm.io, knip.dev, vitest.dev, eslint.org, prettier.io, docs.npmjs.com,
+nodejs.org
+```
+
+Plus **the official docs of a tool the project's interview actually
+selected** for bundling, if one was chosen and isn't already covered above
+(a specific bundler's own docs).
+
+One of the fixed domains is **path-scoped within a domain
+`typescript-guidance` also uses, for a different path**:
+
+- `nodejs.org` hosts the whole Node.js documentation site.
+  `typescript-guidance`'s own allowlist scopes it to `/api/typescript.html`
+  (the runtime type-stripping boundary). This file's own scope is
+  `/en/about/previous-releases` (the LTS/EOL schedule), for the
+  Node-version-pinning area only. Passing a bare `nodejs.org` to
+  `allowed_domains` allows both paths; treat a citation from any other
+  `nodejs.org` path as out of scope for either allowlist.
+
+## The tier
+
+Every domain here is **T1 by default** for its own tool -- owner-normative,
+the same standing `typescript-guidance`'s T1 gives `typescriptlang.org` for
+TypeScript itself. Most of these tools have exactly one canonical doc
+source, unlike TypeScript's ecosystem of adjacent linters/checkers, so most
+citations from this file carry `TIER: T1` in the findings format `research` mode defines (which `gaps`
+mode reuses).
+
+- `pnpm.io` -- pnpm's own CLI, workspace, and `.npmrc`/supply-chain-setting
+  reference.
+- `knip.dev` -- unused-dependency/unused-export tooling.
+- `vitest.dev` -- the default test runner this baseline ships. **Tier here
+  is T1**, for a different purpose than its T2 listing in
+  `typescript-sources.md`: that file's T2 covers auditing the config of a
+  test runner the interview has already selected (`research`/`refresh`);
+  this file's T1 covers recommending vitest be **added** to a project that
+  has no test runner configured at all yet (`gaps`). Once a runner is
+  selected and configured, further scrutiny of its config is
+  `research`/`refresh` territory at T2, not `gaps` mode's -- the same domain
+  carries two tier labels because the modes consult it for two different
+  purposes.
+- `eslint.org` -- ESLint's own core rules and flat-config reference (as
+  opposed to `typescript-eslint.io`, which stays `research`/`refresh`'s
+  territory for typed-linting presets specifically).
+- `prettier.io` -- formatting.
+- `docs.npmjs.com` -- npm-the-registry conventions (`package.json` fields,
+  `engines`, publishing) as distinct from any one package manager's CLI.
+- `nodejs.org/en/about/previous-releases` -- the LTS/EOL schedule, for the
+  Node-version-pinning area. See the path-scope note above.
+
+**Explicitly out of scope**, named so an agent that finds one drops it
+rather than substituting it for missing coverage:
+
+- A package manager's or tool's community wiki, forum post, or blog
+  aggregator (as opposed to its own docs site).
+- An individual author's blog post about a tool, however highly ranked.
+- `github.com/tsconfig/bases` and similar community-consensus
+  repositories -- consensus, not an owner's own word.
+
+## GitHub caveat
+
+`allowed_domains` filters by domain, not path, so a bare `github.com`
+allowance would let through any repo. Agents researching an area covered by
+this file may include `github.com` and `raw.githubusercontent.com` in their
+search domains, but must **only cite or fetch URLs under**:
+
+- `changesets/changesets` (release automation)
+- `typescript-eslint/typescript-eslint` (only for the release-compatibility
+  question -- "does this typescript-eslint version support this TypeScript
+  version" -- the rule semantics themselves stay `typescript-guidance`'s
+  T2 territory via `typescript-eslint.io`)
+- `nodejs/Release` (the machine-readable Node release schedule, cross-checked
+  against `nodejs.org/en/about/previous-releases`)
+
+Drop any other GitHub result, however highly ranked, the same as
+`typescript-guidance`'s own caveat requires.
+
+## Coverage discipline
+
+Reject any non-allowlisted domain outright and say so in the report, rather
+than substituting a community blog, an individual author's material, or a
+Stack Overflow answer for missing coverage. A facet that turns up no
+qualifying source is itself a reportable coverage gap, not a reason to lower
+the bar -- see `SKILL.md`'s Gaps mode, step 2.
+
+## Current-date anchor
+
+Every research brief must state today's date explicitly, the same discipline
+`typescript-guidance` applies -- a `retrieved <date>` stamp otherwise depends
+on the spoke inferring the date itself, which is unreliable.

package/templates/core/.claude/skills/writing-commits/SKILL.md

@@ -31,7 +31,7 @@ reviewer who wasn't in the room.
 ```bash
 git diff --staged          # the files about to be committed
 git diff                   # unstaged context (reference only)
-git log main...HEAD --oneline  # commits already on this branch
+git log main..HEAD --oneline  # commits already on this branch
 ```
 
 Read all three outputs before drafting anything. The staged diff is the
@@ -62,7 +62,7 @@ Rules enforced by commitlint:
 
 - **Imperative present tense** — "implement", "add", "fix", not "implemented"
 - **All lowercase** after `type:` — never `Feat:` or `feat: Add`
-- **≤ 70 characters** (hard limit — commitlint will reject longer subjects)
+- **≤ 70 characters** (this skill's own target; commitlint's `config-conventional` only rejects headers over 100)
 - **No trailing period**
 - **Be specific** — name the module, file, class, or exported symbol
 

package/templates/core/.github/dependabot.yml

@@ -0,0 +1,18 @@
+version: 2
+
+updates:
+  # Keeps the action majors in .github/workflows/ from going stale. Every
+  # `uses:` line is pinned by commit SHA (not a floating tag), so Dependabot
+  # opening a PR to move the pin forward is what keeps that pinning
+  # affordable to maintain -- the same mechanism it would use for a floating
+  # tag, closing the "a compromised upstream tag" gap a floating `@vN`
+  # doesn't. npm updates are deliberately not enabled here -- add them later
+  # with `groups:` batching if the project wants it.
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "ci"
+    labels:
+      - "dependencies"

package/templates/core/.github/workflows/ci.yml

@@ -24,11 +24,11 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           persist-credentials: false
-      - uses: pnpm/action-setup@v4
-      - uses: actions/setup-node@v7
+      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
         with:
           node-version-file: .node-version
           cache: pnpm
@@ -40,11 +40,11 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           persist-credentials: false
-      - uses: pnpm/action-setup@v4
-      - uses: actions/setup-node@v7
+      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
         with:
           node-version-file: .node-version
           cache: pnpm
@@ -56,11 +56,11 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           persist-credentials: false
-      - uses: pnpm/action-setup@v4
-      - uses: actions/setup-node@v7
+      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
         with:
           node-version-file: .node-version
           cache: pnpm
@@ -72,11 +72,11 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           persist-credentials: false
-      - uses: pnpm/action-setup@v4
-      - uses: actions/setup-node@v7
+      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
         with:
           node-version-file: .node-version
           cache: pnpm
@@ -88,11 +88,11 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 15
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           persist-credentials: false
-      - uses: pnpm/action-setup@v4
-      - uses: actions/setup-node@v7
+      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
         with:
           node-version-file: .node-version
           cache: pnpm

package/templates/core/.github/workflows/dependency-review.yml

@@ -17,10 +17,10 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           persist-credentials: false
-      - uses: actions/dependency-review-action@v4
+      - uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294 # v5
         with:
           fail-on-severity: high
           allow-licenses: MIT, MIT-0, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC, 0BSD, CC0-1.0, Unlicense, CC-BY-4.0

package/templates/core/.github/workflows/security-audit.yml

@@ -10,6 +10,12 @@ on:
 permissions:
   contents: read
 
+# A manual dispatch overlapping the daily run would otherwise race to open
+# the same failure issue.
+concurrency:
+  group: security-audit
+  cancel-in-progress: false
+
 jobs:
   audit:
     name: Dependency audit
@@ -21,11 +27,11 @@ jobs:
       contents: read
       issues: write
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
           persist-credentials: false
-      - uses: pnpm/action-setup@v4
-      - uses: actions/setup-node@v7
+      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
         with:
           node-version-file: .node-version
           cache: pnpm
@@ -34,7 +40,7 @@ jobs:
         run: pnpm audit --audit-level=high
       - name: Open an issue on failure
         if: failure()
-        uses: actions/github-script@v8
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
         with:
           script: |
             const title = "Scheduled security audit failed";

package/templates/core/.prettierignore

@@ -3,3 +3,7 @@ dist/
 coverage/
 pnpm-lock.yaml
 CHANGELOG.md
+# A worktree the harness creates (see .gitignore) is a full, independent
+# checkout under here -- without this, prettier double-visits (and can fail
+# on) that copy's own in-progress state, which is a different session's WIP.
+.claude/worktrees/

package/templates/core/CLAUDE.md

@@ -29,7 +29,7 @@ Run any task with `pnpm <script>`.
 | `pnpm knip`                    | Unused-dependency / unused-export hygiene; a `verify` step. `knip.json` ignores `@commitlint/config-conventional` and `@commitlint/types`, which are loaded by a string and a JSDoc type knip cannot see |
 | `pnpm check:exports`           | publint + are-the-types-wrong against a packed tarball                                                                                                                                                   |
 | `pnpm check:node-version`      | `.node-version` is authoritative; forbids a hardcoded pin in CI                                                                                                                                          |
-| `pnpm verify`                  | Every gate above, in the same order CI runs them                                                                                                                                                         |
+| `pnpm verify`                  | Every gate above plus the `harness`/`toolchain` graders, in `verify-steps.mjs` order; CI runs them as five parallel group lanes                                                                          |
 | `pnpm prepare`                 | Installs the lefthook git hooks                                                                                                                                                                          |
 
 Run `pnpm verify` before considering any task done — it reproduces CI
@@ -71,6 +71,53 @@ contract:
    Must-fix findings route back to `code-implementer`, and the loop repeats
    until clean.
 
+**The guard also screens `Bash`, but only conservatively.** The same hook
+runs on every `Bash` call and blocks a command that visibly writes into
+`src/` or `tests/` (redirects, `tee`, `sed -i`, `cp`/`mv` into them, a
+`python`/`node`/`php` snippet that writes or deletes there, a copy, move or
+removal of a parent of `src/` such as `rsync -a /tmp/x/ ./` or `rm -rf .`, and
+similar) unless the caller is `test-author` or `code-implementer`. It cannot
+catch an indirect write -- an interpreter running a script from a project
+file, an `eval`, a computed path, a parent of the project root (`rm -rf ..`), a workspace container below the project root (`tools/packages/foo`), a build step, a formatter or fixer
+(`prettier --write`, `eslint --fix`), `git rm`/`git mv`, `find -exec`, `xargs` with a computed operand, `tar`/`curl -o`, a very long
+interpreter call (allowed with a stderr note) -- so hub-and-spoke remains a convention backed by a guard that raises the bar,
+not a proof. To override it deliberately, run the command yourself with the
+`!` prefix at the Claude Code prompt, or edit the hook's registration in
+`.claude/settings.json`.
+
+**A Claude Code Enterprise/managed deployment sits above this and can
+silently disable it.** Managed settings (a `managed-settings.json` file, an
+MDM policy, or a claude.ai-console-managed remote policy) take precedence
+over every file this baseline installs, with no project-level override, and
+two managed-only keys -- `allowManagedHooksOnly` and
+`allowManagedPermissionRulesOnly` -- make Claude Code skip this project's
+own `.claude/settings.json` hooks and permission rules entirely rather than
+merge with them (see
+[Claude Code's managed-settings docs](https://code.claude.com/docs/en/managed-settings)).
+Nothing in this project can detect or gate against that from inside the
+repo -- the managed file lives outside any working tree, at an OS-level
+path. Run `/status` on a machine you don't control before trusting
+`guard-hub-src-writes.mjs`/`guard-branch-isolation.mjs`: its "Setting
+sources" line names every active source, and if these hooks aren't among
+what's actually running, treat hub-and-spoke as an unenforced checklist
+until confirmed otherwise.
+
+**An installed Claude Code mod is a second silent override, below managed
+settings.** Per the
+[hooks guide](https://code.claude.com/docs/en/hooks-guide), a mod that
+handles `tool.check` "can approve a call that your `PreToolUse` hook blocked,
+unless the hook is in managed settings", and project `PreToolUse` hooks run
+only after the last mod calls `next` (see the
+[mods events reference](https://code.claude.com/docs/en/plugins/mods/events)).
+Only managed-settings hooks outrank a mod, and nothing in the repo can detect
+one. Check `/plugin` for installed mods alongside `/status`.
+
+**The guard keys on `agent_id` as well as `agent_type`.** Claude Code sends
+`agent_type` both inside a subagent and in a main session started with
+`--agent <name>`; only a call inside a subagent also carries `agent_id`. A
+call counts as a writer spoke only with both present, so a hub launched as
+`claude --agent code-implementer` is still the hub and is blocked.
+
 Full dispatch-sizing and recovery guidance: `.claude/rules/agent-dispatch.md`
 (auto-loads when editing `.claude/skills/**` or `.claude/agents/**`).
 
@@ -111,7 +158,9 @@ fix the config it points at.
 **Enforced at write time by hooks:** `any` implied by CommonJS constructs
 (`require`, `module.exports`, `__dirname`, `__filename`), a missing `.js`
 extension on a relative import, a hand-edit to `dist/` or `coverage/`, a
-write to `src/`/`tests/` while on `main`, a real secret written to disk.
+write to `src/`/`tests/` while on `main`, a real secret written to disk,
+an unsigned `git push` when `commit.gpgsign` is on, and a `run_in_background`
+Bash call stacked with a shell-level detach construct.
 
 **No automated guard — need conscious care:** no `any` in the public API;
 never swallow an error silently; no top-level side effects; never
@@ -122,6 +171,7 @@ never swallow an error silently; no top-level side effects; never
 This baseline is frozen at the moment `m3l-groundwork` last emitted it. Run
 `/customize`'s guidance pass — or `.claude/skills/typescript-guidance/` /
 `.claude/skills/harness-guidance/` directly in refresh mode — periodically
-to sweep the toolchain and harness against current upstream guidance. See
+to sweep the toolchain and harness against current upstream guidance; its
+`gaps` mode recommends tooling the project doesn't have yet. See
 `docs/research/typescript-refresh.md` and `docs/research/harness-refresh.md`
 for the living trackers.

package/templates/core/README.md

@@ -3,6 +3,15 @@
 Bootstrapped by [m3l-groundwork](https://github.com/monte3l/m3l-groundwork) —
 a deterministic TypeScript + Claude Code project bootstrapper.
 
+## What you just got
+
+A TypeScript project wired up with a strict compiler configuration, ESLint,
+Prettier, Vitest (with a coverage gate), and a Claude Code harness under
+`.claude/` — agents, skills, hooks, and rules that shape how Claude Code
+works in this repository. All of it is deliberately generic: a correct,
+working starting point for any TypeScript project, not yet specific to what
+__PROJECT_NAME__ actually does.
+
 ## Getting started
 
 ```bash
@@ -10,15 +19,26 @@ pnpm install
 pnpm verify
 ```
 
-`pnpm verify` runs the same checks CI runs: format, lint, typecheck, build,
-and test with coverage. See `CLAUDE.md` for the full command reference and
-the project's conventions.
+`pnpm verify` runs the same checks CI runs — format, lint, typecheck, build,
+and test with coverage — in one command, so you can catch a failure locally
+before pushing. See `CLAUDE.md` for the full command reference and this
+project's conventions.
+
+## Tailor it to your project
+
+This baseline is frozen at the moment it was generated, and deliberately
+generic until you adapt it. To tailor it to __PROJECT_NAME__:
+
+1. Open this repository in [Claude Code](https://claude.com/claude-code).
+2. Run the `/customize` slash command.
+3. Answer a short interview (project kind, runtime target, test strictness,
+   CI depth). Claude Code then tailors the baseline to your answers and
+   runs a live guidance pass against current official TypeScript and
+   Anthropic documentation, so the result reflects up-to-date recommended
+   practice rather than what was true when this baseline was generated.
 
-## Customize this baseline
+## Glossary
 
-This project shipped with a frozen, universal TypeScript + Claude Code
-baseline. Run `/customize` inside Claude Code to tailor it: answer a short
-interview (project kind, runtime target, test strictness, CI depth), then
-let the guidance pass validate the result against current official
-TypeScript and Anthropic guidance rather than what was true when the
-baseline was built.
+Run into an unfamiliar term in `CLAUDE.md`, this README, or the `.claude/`
+harness? See the upstream
+[glossary](https://github.com/monte3l/m3l-groundwork/blob/main/docs/glossary.md).

package/templates/core/_gitignore

@@ -14,6 +14,23 @@ coverage/
 # Local overrides
 lefthook-local.yml
 
+# A worktree the harness creates (`claude --worktree`, Agent tool
+# `isolation: "worktree"`, or `EnterWorktree`) lands under here as a full,
+# independent checkout -- including its own copy of every file this project
+# already scans. Without this, prettier/eslint/vitest all double-visit (and
+# can fail on) that copy's own in-progress state, which belongs to a
+# different session, not this project's tracked content.
+.claude/worktrees/
+
+# Never commit secrets. (Also relevant to worktrees: a project that adds a
+# `.worktreeinclude` file -- gitignore-syntax, Claude Code convention, see
+# code.claude.com/docs/en/worktrees -- can only carry a gitignored file like
+# this into a new worktree, never a tracked one, so it stays gitignored
+# regardless of whether that file exists here.)
+.env
+.env.local
+.env.*.local
+
 # Scratch state written by opt-in harness-extras pack hooks (e.g. the
 # compaction-handoff artifact) -- harmless if the pack isn't installed.
 tmp/

package/templates/core/bin/check-exports.mjs

@@ -2,11 +2,17 @@
 /**
  * Real packaging correctness: packs the target package (`--cwd <dir>`,
  * default the repo root) with `pnpm pack`, then runs publint and
- * are-the-types-wrong (attw) against the resulting tarball. Skips cleanly
- * (exit 0, one warning) when the target has no `exports` field -- a project
- * that isn't published doesn't need this gate, and `/customize` removes the
- * step entirely for non-library project kinds rather than leaving a
- * permanently-skipped one behind.
+ * are-the-types-wrong (attw) against the resulting tarball -- checking the
+ * actual published artifact, not just the source tree. publint checks that
+ * `package.json` (its `exports` map, `main`/`module`/`types` fields, and
+ * which files are actually included) resolves the way consumers and
+ * bundlers expect. attw checks that the package's TypeScript type
+ * declarations actually match what each entry point resolves to at runtime
+ * -- e.g. that an ESM import doesn't quietly get pointed at CommonJS-shaped
+ * types. Skips cleanly (exit 0, one warning) when the target has no
+ * `exports` field -- a project that isn't published doesn't need this gate,
+ * and `/customize` removes the step entirely for non-library project kinds
+ * rather than leaving a permanently-skipped one behind.
  */
 import process from "node:process";
 import { execFileSync } from "node:child_process";

package/templates/core/bin/lib/agent-roster.mjs

@@ -1,5 +1,5 @@
 /**
- * The writer-spoke roster: the only subagent names a PreToolUse[Write|Edit]
+ * The writer-spoke roster: the only subagent names a PreToolUse[Write|Edit|Bash]
  * hook trusts to write into a guarded `src/`/`tests/` path. Kept as one
  * small, static source so `guard-hub-src-writes.mjs` and this project's
  * `code-implementer`/`test-author` agent definitions can't silently drift

package/templates/core/bin/lib/frontmatter.mjs

@@ -5,8 +5,10 @@
  * list scalars. Not supported: nested mappings (recorded as an empty string
  * rather than misparsed), anchors, tags. Every string result is trimmed.
  *
- * This file is the emitted twin of m3l-groundwork's own
- * `packages/cli/src/harness/frontmatter.ts`; a parity test keeps them equal.
+ * Also used by m3l-groundwork's own adopt mode (the tool that generated this
+ * project's harness); if you're contributing a change back upstream, keep
+ * this file's behavior in sync with its source at
+ * `packages/cli/src/harness/frontmatter.ts` there.
  */
 
 const KEY_LINE = /^([A-Za-z_][\w-]*):(?:[ \t]+(.*))?$/;