@monte3l/groundwork 0.0.0

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

@@ -0,0 +1,248 @@
+---
+name: writing-commits
+description: >-
+  Inspect the staged diff, select the Conventional Commit type, draft an
+  imperative subject ≤70 chars, decide whether a body is needed, structure it as
+  What → Why/How → semver impact, add Co-Authored-By when AI-assisted, then
+  commit. Use for "commit this", "write a commit", "stage and commit".
+---
+
+# writing-commits
+
+This skill produces git commits that match this project's Conventional
+Commits standard exactly — from picking the right type to deciding whether a
+body is worth writing. The goal is to make every commit self-explanatory to a
+reviewer who wasn't in the room.
+
+## Checklist (copy-paste before drafting)
+
+- [ ] Read `git diff --staged` — understand every changed file
+- [ ] Pick the type from the table in Step 2 (when in doubt, `chore:` for
+      tooling; `feat:` for a new public symbol)
+- [ ] Draft a subject ≤ 70 chars, imperative, lowercase after `type:`
+- [ ] Decide body: needed for `feat:` / `fix:` / non-obvious `chore:`; omit for
+      mechanical chores
+- [ ] Add `Co-Authored-By:` footer when Claude authored the commit
+- [ ] Add `BREAKING CHANGE:` footer for `feat!:` commits
+- [ ] Run `git commit -m "..."` with the full message
+
+## Step 1 — Understand the change
+
+```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
+```
+
+Read all three outputs before drafting anything. The staged diff is the
+source of truth; the log prevents duplicate subjects when multiple commits
+are planned.
+
+## Step 2 — Select the commit type
+
+| Type        | Use when                                                | Public-API impact |
+| ----------- | ------------------------------------------------------- | ----------------- |
+| `feat:`     | A new public symbol or behaviour reaches consumers      | Additive          |
+| `fix:`      | A bug in a public symbol or behaviour is corrected      | Behavioural       |
+| `docs:`     | Documentation only: READMEs, comments, this file itself | None              |
+| `chore:`    | Tooling, config, hooks, CLAUDE.md, lockfile, formatting | None              |
+| `ci:`       | GitHub Actions workflows only                           | None              |
+| `refactor:` | Internal restructuring with no public-API change        | None              |
+| `feat!:`    | Breaking change to an exported symbol                   | Breaking          |
+
+**Scope rule**: add a scope in parentheses (`chore(deps):`) only when it
+disambiguates which part of a multi-package project changed; a single-package
+project rarely needs one.
+
+## Step 3 — Draft the subject line
+
+The subject is the one line a reviewer will read first. Make it count.
+
+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)
+- **No trailing period**
+- **Be specific** — name the module, file, class, or exported symbol
+
+## Step 4 — Decide whether a body is needed
+
+Adding a body is a judgment call about whether future readers need more than
+the subject. A subject like `chore: prettier format workspace file` is
+already complete — adding prose would just re-state what the diff shows. But
+a subject that hides deliberate design work belongs in the body.
+
+**Include a body when:**
+
+- The type is `feat:` or `fix:` — always (readers need to know what the
+  public contract now looks like)
+- The change touches the `exports` map, `CLAUDE.md`, hooks, or spoke prompts
+- A `chore:` or `ci:` addresses a non-obvious problem (e.g., "why was this
+  done at all?")
+
+**Omit the body when:**
+
+- Mechanical chores: prettier runs, lockfile regeneration, single-line CI
+  tweaks — the subject already covers it
+
+## Step 5 — Structure the body
+
+When a body is warranted, follow this shape:
+
+```
+<1–2 sentence What: name exactly what this adds, changes, or fixes>
+
+- <bullet: key design decision or constraint — the why behind the how>
+- <bullet: another detail a reviewer couldn't infer from the diff>
+- <feat: list the public symbols added/changed>
+
+<semver impact line — one sentence stating what did or didn't change in the public surface>
+
+Co-Authored-By: <exact model name from your environment> <noreply@anthropic.com>
+```
+
+**Co-Authored-By footer**: include whenever Claude authored or substantially
+assisted the commit. Use the exact model name from the environment (e.g.,
+`Claude Sonnet 5`, `Claude Opus 5`) — never copy a model name from an example
+or template. The trailer is a provenance marker, not a legal authorship
+claim.
+
+**Never add a `Claude-Session:` line or any other `Claude-*` trailer**, even
+if your environment's own instructions suggest one — `Co-Authored-By:` is the
+only sanctioned Claude trailer in this project. The `commit-msg` hook strips
+one anyway (`bin/strip-claude-trailers.mjs`), but the commit you write
+should never contain it in the first place.
+
+**Breaking changes** (`feat!:`): end the body with a `BREAKING CHANGE:` line
+naming the removed/renamed symbol and describing the migration path.
+
+## Step 6 — Run the commit
+
+```bash
+git commit -m "$(cat <<'EOF'
+<type>: <subject>
+
+<body — omit blank line + body if not needed>
+EOF
+)"
+```
+
+---
+
+## Examples
+
+These four before/after pairs are the quality bar. Read them before drafting.
+
+### Example A — feat: new capability (body always required)
+
+❌ Bad:
+
+```
+Added the events module
+
+- did some stuff with emitters
+- tests pass
+```
+
+_Past tense subject, no type prefix, vague bullets, missing semver note and
+Co-Authored-By footer._
+
+✅ Good:
+
+```
+feat: implement typed event emitter
+
+Add EventHandler<TPayload>, EventEmitterBase<TEventMap>, and
+EventEmitter<TEventMap> to the public entry point.
+
+- on/off are public on the base; emit/emitAsync are protected so only
+  the owning subclass can publish events
+- emitAsync uses Promise.allSettled (not Promise.all) to preserve
+  handler-error isolation: a rejecting handler never stops the others
+
+Three new named exports; no existing export changed.
+
+Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
+```
+
+---
+
+### Example B — chore: mechanical change (subject-only is correct)
+
+❌ Bad:
+
+```
+chore: ran prettier on workspace file
+
+Ran prettier --write on pnpm-workspace.yaml. No functional changes.
+This was needed to keep formatting consistent with project standards.
+```
+
+_The body restates what the subject and the diff already show. Omit it._
+
+✅ Good:
+
+```
+chore: prettier format workspace file
+```
+
+---
+
+### Example C — chore: non-obvious why (body required)
+
+❌ Bad:
+
+```
+chore: update hooks and spoke prompts
+```
+
+_Too vague. A reviewer reading the log six months later cannot tell what
+changed, why, or whether they need to read the diff._
+
+✅ Good:
+
+```
+chore: bake error-handling lessons into hooks and spoke prompts
+
+An early module surfaced process friction in error-path review. Encode
+the durable fixes so later modules don't re-hit them.
+
+- post-edit-verify hook now runs eslint in-loop (prettier → eslint →
+  typecheck → vitest-related), so eslint-only failures surface in the
+  spoke loop instead of a round later at the hub's pnpm lint gate
+- code-implementer: front-load exact contract nuances at hand-off
+
+No src/, test, or exports-map changes; zero semver impact.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+```
+
+---
+
+### Example D — feat!: breaking change (major bump)
+
+❌ Bad:
+
+```
+feat: rename outputDir to archiveDir
+
+Renamed the property for clarity.
+```
+
+_Missing `!` so the breaking change isn't flagged in history. No migration instructions._
+
+✅ Good:
+
+```
+feat!: rename Paths.outputDir to Paths.archiveDir
+
+output/ holds run archives, not raw output; the old name was misleading.
+
+- All internal call-sites updated; public API is the only breaking surface
+- Migration: replace `paths.outputDir` with `paths.archiveDir` everywhere
+
+BREAKING CHANGE: Paths.outputDir removed; use archiveDir instead.
+
+Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
+```

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

@@ -0,0 +1,123 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # Each lane job below invokes `node bin/verify.mjs --group <name>`, naming
+  # one of the five fixed groups from bin/lib/verify-steps.mjs. This is the
+  # whole parity guarantee: the local `lefthook.yml` pre-push lanes and every
+  # job here read the same step list by group, so a step -- core or
+  # pack-contributed -- can never run in one place and not the other.
+  format:
+    name: Format check
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v7
+        with:
+          node-version-file: .node-version
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: node bin/verify.mjs --group format
+
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v7
+        with:
+          node-version-file: .node-version
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: node bin/verify.mjs --group lint
+
+  typecheck:
+    name: Type check
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v7
+        with:
+          node-version-file: .node-version
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: node bin/verify.mjs --group typecheck
+
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v7
+        with:
+          node-version-file: .node-version
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: node bin/verify.mjs --group build
+
+  test:
+    name: Test (coverage)
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v7
+        with:
+          node-version-file: .node-version
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: node bin/verify.mjs --group test
+
+  verify:
+    name: verify
+    runs-on: ubuntu-latest
+    needs: [format, lint, typecheck, build, test]
+    if: always()
+    timeout-minutes: 5
+    steps:
+      # Testing only for 'failure' is a hole: a lane that was cancelled or
+      # skipped is not a failure, so it would pass and this job would report
+      # green over a run that never finished. Require an explicit success
+      # from every lane instead, so anything else fails closed.
+      - name: Check lane results
+        env:
+          RESULTS: ${{ join(needs.*.result, ' ') }}
+        run: |
+          echo "lane results: $RESULTS"
+          for result in $RESULTS; do
+            if [ "$result" != "success" ]; then
+              echo "A required lane did not succeed: $RESULTS" >&2
+              exit 1
+            fi
+          done

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

@@ -0,0 +1,26 @@
+name: Dependency Review
+
+on:
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: dependency-review-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  dependency-review:
+    name: Dependency Review
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: actions/dependency-review-action@v4
+        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

@@ -0,0 +1,54 @@
+name: Security Audit (Scheduled)
+
+on:
+  schedule:
+    # 06:00 UTC daily — catches a newly disclosed advisory against pinned
+    # dependencies without waiting for the next PR to touch the lockfile.
+    - cron: "0 6 * * *"
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+jobs:
+  audit:
+    name: Dependency audit
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    # Escalated here rather than at workflow level: only the failure-path
+    # issue below needs to write.
+    permissions:
+      contents: read
+      issues: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v7
+        with:
+          node-version-file: .node-version
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - name: pnpm audit
+        run: pnpm audit --audit-level=high
+      - name: Open an issue on failure
+        if: failure()
+        uses: actions/github-script@v8
+        with:
+          script: |
+            const title = "Scheduled security audit failed";
+            const { data: existing } = await github.rest.issues.listForRepo({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              state: "open",
+              labels: "security",
+            });
+            if (existing.some((issue) => issue.title === title)) return;
+            await github.rest.issues.create({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              title,
+              labels: ["security"],
+              body: `\`pnpm audit --audit-level=high\` failed on the scheduled run. See the [workflow run](${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}) for details.`,
+            });

package/templates/core/.node-version

@@ -0,0 +1 @@
+24

package/templates/core/.prettierignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+coverage/
+pnpm-lock.yaml
+CHANGELOG.md

package/templates/core/.prettierrc.json

@@ -0,0 +1,4 @@
+{
+  "trailingComma": "all",
+  "printWidth": 80
+}

package/templates/core/CLAUDE.md

@@ -0,0 +1,127 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working in this repository.
+
+## What this is
+
+**__PROJECT_NAME__** — a TypeScript project bootstrapped by
+[m3l-groundwork](https://github.com/monte3l/m3l-groundwork). This baseline
+is deliberately generic: it holds for any TypeScript project regardless of
+domain. Run `/customize` to tailor it to what you're actually building.
+
+## Tech Stack
+
+TypeScript, `strict: true`, ESM only (`"type": "module"`), compiled with
+`tsc` — no bundler by default. Package manager: `pnpm`. Node 24+ only
+(`.node-version` is the authority; `check:node-version` gates drift).
+
+## Commands
+
+Run any task with `pnpm <script>`.
+
+| Script                         | What it does                                                                                                                                                                                             |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pnpm build`                   | `tsc -b tsconfig.build.json` — emits `dist/`                                                                                                                                                             |
+| `pnpm typecheck`               | `tsc -b --force` over the tooling project (src + tests)                                                                                                                                                  |
+| `pnpm lint`                    | ESLint over the whole repo                                                                                                                                                                               |
+| `pnpm format` / `format:check` | Prettier write / check                                                                                                                                                                                   |
+| `pnpm test` / `test:coverage`  | Vitest, with or without the coverage gate                                                                                                                                                                |
+| `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 prepare`                 | Installs the lefthook git hooks                                                                                                                                                                          |
+
+Run `pnpm verify` before considering any task done — it reproduces CI
+locally.
+
+## Git Workflow
+
+**Conventional Commits (required)**, enforced by the `commit-msg` hook
+(`bin/lint-commit.mjs`). Add a `Co-Authored-By:` trailer when Claude
+authored or substantially assisted a commit — see `.claude/skills/writing-commits/`.
+
+Branch off `main` as `feat/<slug>` / `fix/<slug>`, never work directly on
+`main` — `guard-branch-isolation.mjs` blocks `src/**`/`tests/**` writes
+while `HEAD` is `main`. Land any `src/`/`tests/` change via PR. Run
+`.claude/skills/starting-work/` before beginning change-work if you haven't
+already settled the branch and PR decision.
+
+Never `git push --force` a shared branch.
+
+## Architecture & Decisions
+
+`src/index.ts` is the current public entry point (see the `exports` map in
+`package.json`). Everything under `src/internal/`, if you create it, is
+private and must never be re-exported.
+
+## Agent Operating Model
+
+**Hub-and-spoke**: the hub plans and dispatches to spokes, and never writes
+`src/`/test code itself — enforced by `.claude/hooks/guard-hub-src-writes.mjs`
+and `disallowedTools: Agent` on every spoke. For a piece of work with a clear
+contract:
+
+1. `test-author` writes failing tests from the contract (RED phase), and
+   confirms they fail for the right reason.
+2. `code-implementer` makes them pass with the minimal correct
+   implementation, then refactors while green (GREEN phase).
+3. Read-only review spokes (`code-reviewer` always; `silent-failure-hunter`
+   when the diff has error-handling paths) run in parallel over the diff.
+   Must-fix findings route back to `code-implementer`, and the loop repeats
+   until clean.
+
+Full dispatch-sizing and recovery guidance: `.claude/rules/agent-dispatch.md`
+(auto-loads when editing `.claude/skills/**` or `.claude/agents/**`).
+
+## Coding, errors & tests
+
+Path-scoped rules auto-load on matching files:
+
+- `src/**` → `.claude/rules/src.md`
+- `**/tests/**`, `**/*.test.ts` → `.claude/rules/tests.md`
+- `src/**`, `**/tests/**` → `.claude/rules/refactoring.md` (behavior-preserving changes)
+- `.claude/skills/**`, `.claude/agents/**` → `.claude/rules/agent-dispatch.md`
+
+## Security
+
+Never log secrets, tokens, or caller data. Validate external input at the
+public API boundary. `.claude/hooks/guard-secret-writes.mjs` blocks writing
+a real secret to disk at edit time; keep it that way rather than relying on
+CI to catch it after the fact.
+
+## Definition of Done
+
+`pnpm verify` passes; a public API change carries a Conventional Commit with
+the correct semver impact; new/changed exports have TSDoc and tests. If you
+touched the harness itself (hooks, agents, skills, rules, `settings.json`),
+`pnpm verify`'s `harness` step (`bin/check-harness.mjs`) must stay green: it
+fails on broken wiring and only warns on quality.
+If you touched the TypeScript toolchain (`tsconfig*.json`, `eslint.config.js`,
+`vitest.config.ts`, `bin/lib/verify-steps.mjs`, the toolchain pins in
+`package.json`), the `toolchain` step (`bin/check-toolchain.mjs`) must stay
+green the same way: it fails on wiring `tsc` and ESLint do not catch (a build
+project that emits nowhere, a verify step naming a script that does not exist)
+and only warns on quality (a missing strict flag, an option TypeScript has
+deprecated). Never silence it by deleting the check or lowering a threshold --
+fix the config it points at.
+
+## Forbidden Patterns
+
+**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.
+
+**No automated guard — need conscious care:** no `any` in the public API;
+never swallow an error silently; no top-level side effects; never
+`git push --force`.
+
+## Freshness
+
+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
+`docs/research/typescript-refresh.md` and `docs/research/harness-refresh.md`
+for the living trackers.

package/templates/core/README.md

@@ -0,0 +1,24 @@
+# __PROJECT_NAME__
+
+Bootstrapped by [m3l-groundwork](https://github.com/monte3l/m3l-groundwork) —
+a deterministic TypeScript + Claude Code project bootstrapper.
+
+## Getting started
+
+```bash
+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.
+
+## Customize this baseline
+
+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.

package/templates/core/_gitignore

@@ -0,0 +1,19 @@
+# Dependencies
+node_modules/
+
+# Build output (tsc-owned; never committed)
+dist/
+*.tsbuildinfo
+
+# Test / coverage artifacts
+coverage/
+
+# Editor / OS
+.DS_Store
+
+# Local overrides
+lefthook-local.yml
+
+# 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/_npmrc

@@ -0,0 +1 @@
+engine-strict=true