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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. package/README.md +20 -5
  2. package/dist/customize-paths.d.ts +51 -15
  3. package/dist/customize-paths.js +32 -13
  4. package/dist/fs-guard.d.ts +2 -2
  5. package/dist/harness/rules.d.ts +2 -1
  6. package/dist/harness/rules.js +3 -1
  7. package/dist/inventory.d.ts +1 -1
  8. package/dist/inventory.js +5 -2
  9. package/dist/plugin.d.ts +12 -12
  10. package/dist/plugin.js +34 -26
  11. package/dist/report.js +74 -10
  12. package/dist/survey/survey-harness.d.ts +10 -2
  13. package/dist/survey/survey-harness.js +90 -4
  14. package/dist/survey/survey-shape.js +6 -3
  15. package/dist/survey/survey-toolchain.js +7 -9
  16. package/dist/survey/types.d.ts +33 -0
  17. package/dist/toolchain/grade.js +6 -7
  18. package/dist/toolchain/rules.d.ts +5 -3
  19. package/dist/toolchain/rules.js +6 -4
  20. package/package.json +1 -1
  21. package/plugin/skills/customize/SKILL.md +73 -408
  22. package/plugin/skills/customize/step-0-reconcile.md +265 -0
  23. package/plugin/skills/customize/step-3-round-1.md +171 -0
  24. package/plugin/src/domain-map.ts +2 -2
  25. package/plugin/src/kind-facet-map.ts +39 -9
  26. package/plugin/src/pack-map.ts +5 -3
  27. package/plugin/src/plugin-map.ts +154 -11
  28. package/templates/core/.claude/agents/Explore.md +1 -1
  29. package/templates/core/.claude/hooks/guard-hub-src-writes.mjs +7 -12
  30. package/templates/core/.claude/hooks/guard-no-commonjs.mjs +3 -2
  31. package/templates/core/.claude/hooks/inject-decision-gate.mjs +7 -7
  32. package/templates/core/.claude/rules/agent-dispatch.md +12 -7
  33. package/templates/core/.claude/rules/src.md +7 -4
  34. package/templates/core/.claude/rules/tests.md +2 -2
  35. package/templates/core/.claude/skills/finishing-work/SKILL.md +4 -3
  36. package/templates/core/.claude/skills/triaging-ci/SKILL.md +2 -2
  37. package/templates/core/.claude/skills/writing-commits/SKILL.md +4 -4
  38. package/templates/core/.prettierignore +1 -0
  39. package/templates/core/CLAUDE.md +28 -15
  40. package/templates/core/README.md +15 -3
  41. package/templates/core/_gitignore +1 -0
  42. package/templates/core/bin/check-exports.mjs +5 -3
  43. package/templates/core/bin/lib/harness-rules.mjs +3 -1
  44. package/templates/core/bin/lib/toolchain-rules.mjs +17 -9
  45. package/templates/core/bin/lint-commit.mjs +215 -10
  46. package/templates/core/tsconfig.base.json +10 -6
  47. package/templates/packs/README.md +25 -13
  48. package/templates/packs/github/files/.github/workflows/claude-pr-review.yml +3 -4
  49. package/templates/packs/github/files/.github/workflows/claude.yml +5 -8
  50. package/templates/packs/github/pack.json +1 -1
  51. package/templates/packs/harness-extras/files/.claude/hooks/guard-readonly-bash.mjs +3 -5
  52. package/templates/packs/harness-extras/files/.claude/hooks/subagent-statusline.mjs +29 -14
  53. package/templates/packs/harness-extras/pack.json +1 -1
  54. package/templates/packs/publishing/files/.github/workflows/release.yml +4 -7
  55. package/templates/packs/publishing/files/bin/pnpm-publish-shim.mjs +4 -14
  56. package/templates/packs/publishing/pack.json +1 -1
  57. package/templates/packs/quality/files/.claude/agents/type-design-analyzer.md +1 -1
  58. package/templates/packs/quality/pack.json +1 -1
  59. package/templates/packs/supply-chain/files/.github/workflows/scorecard.yml +4 -2
  60. package/templates/packs/supply-chain/pack.json +2 -2
  61. package/templates/packs/worktrees/pack.json +1 -1
@@ -9,6 +9,32 @@
9
9
  * `pack-map.ts` applies to `templates/packs/` bundles. A stored, unit-tested
10
10
  * module rather than a judgment made afresh each run, so the same interview
11
11
  * answers and context always produce the same recommendation.
12
+ *
13
+ * `plugin-dev` is offered only for the `plugin` kind (a repo that authors a
14
+ * Claude Code plugin) and is then appended last; for every other kind it is
15
+ * absent rather than listed as not recommended, so the ten-entry list
16
+ * `/customize` offers in fixed batches keeps its order. m3l-groundwork itself
17
+ * enables it, since it authors the `/customize` plugin.
18
+ *
19
+ * Evaluated and deliberately not offered, recorded so they are not proposed
20
+ * again:
21
+ *
22
+ * - `code-review` -- duplicates the built-in `/code-review` and the optional
23
+ * `github` pack's PR-review Action.
24
+ * - `code-simplifier` -- duplicates the built-in `/simplify`; its
25
+ * unrestricted-tools agent is blocked by the baseline's hub-and-spoke
26
+ * write guard on `src/`/`tests/` anyway.
27
+ * - `feature-dev` -- duplicates plan mode, `starting-work` and the TDD loop;
28
+ * its `code-reviewer` competes with the baseline's.
29
+ * - `pr-review-toolkit` -- overlaps the baseline's `code-reviewer` and
30
+ * `silent-failure-hunter` and the optional `quality` pack's
31
+ * `type-design-analyzer`.
32
+ * - `hookify` -- runs `python3` on every tool call, and keeps its rules in
33
+ * gitignored `.local.md` files that bypass the graded, committed hooks and
34
+ * the hook cap.
35
+ * - `remember` -- third-party under a source-available license that forbids
36
+ * modification and redistribution; it sends transcripts to `claude -p`,
37
+ * writes `.remember/`, and can push memory to a remote.
12
38
  */
13
39
  import type { InterviewAnswers } from "./kind-facet-map.js";
14
40
 
@@ -29,12 +55,18 @@ export interface PluginRecommendation {
29
55
 
30
56
  /**
31
57
  * What `/customize` knows beyond the interview answers by the time it
32
- * recommends plugins: which packs the user chose, and whether the project
33
- * authors its own skills. Both are optional; an absent field reads as "no".
58
+ * recommends plugins: which packs the user chose, whether the project
59
+ * authors its own skills, and which packages it depends on. All are
60
+ * optional; an absent field reads as "no" (or "none").
34
61
  */
35
62
  export interface PluginRecommendationContext {
36
63
  readonly chosenPacks?: readonly string[];
37
64
  readonly hasCustomSkills?: boolean;
65
+ /**
66
+ * Package names from the project's `package.json` `dependencies` and
67
+ * `devDependencies` combined. Absent reads as none.
68
+ */
69
+ readonly dependencies?: readonly string[];
38
70
  }
39
71
 
40
72
  function pluginId(name: string): string {
@@ -163,10 +195,80 @@ function recommendSecurityGuidance(
163
195
  };
164
196
  }
165
197
 
198
+ /**
199
+ * `claude-security` is the on-demand counterpart to `security-guidance`: it
200
+ * runs only when invoked, so unlike that plugin's per-turn Stop-hook LLM
201
+ * review it costs nothing while idle, and is pre-selected for every project.
202
+ */
203
+ function recommendClaudeSecurity(): PluginRecommendation {
204
+ return {
205
+ id: pluginId("claude-security"),
206
+ recommended: true,
207
+ because:
208
+ "it runs on demand -- only when invoked -- so it costs nothing while " +
209
+ "idle, unlike security-guidance's Stop-hook LLM review on every " +
210
+ "turn. When run it scans the repo or a diff, challenges each finding " +
211
+ "before reporting it, and can draft patches. Its post-push scan tip " +
212
+ "can be turned off with CLAUDE_SECURITY_SCAN_TIP=off.",
213
+ prerequisites: ["Python 3.9+ on PATH"],
214
+ };
215
+ }
216
+
217
+ function dependsOn(
218
+ context: PluginRecommendationContext | undefined,
219
+ packageName: string,
220
+ ): boolean {
221
+ return context?.dependencies?.includes(packageName) ?? false;
222
+ }
223
+
224
+ /**
225
+ * `agent-sdk-dev` scaffolds and verifies Claude Agent SDK applications, so it
226
+ * is pre-selected only when the project depends on
227
+ * `@anthropic-ai/claude-agent-sdk`.
228
+ */
229
+ function recommendAgentSdkDev(
230
+ context: PluginRecommendationContext | undefined,
231
+ ): PluginRecommendation {
232
+ const recommended = dependsOn(context, "@anthropic-ai/claude-agent-sdk");
233
+ return {
234
+ id: pluginId("agent-sdk-dev"),
235
+ recommended,
236
+ because: recommended
237
+ ? "the project depends on @anthropic-ai/claude-agent-sdk, and this " +
238
+ "plugin scaffolds new SDK apps (/new-sdk-app) and verifies existing " +
239
+ "ones against the SDK's current guidance."
240
+ : "only useful to a project that builds on the Claude Agent SDK; " +
241
+ "@anthropic-ai/claude-agent-sdk is not among this project's " +
242
+ "dependencies.",
243
+ };
244
+ }
245
+
246
+ /**
247
+ * `mcp-server-dev` carries skills for building MCP servers and MCP apps and
248
+ * for MCPB packaging, so it is pre-selected only when the project depends on
249
+ * `@modelcontextprotocol/sdk`.
250
+ */
251
+ function recommendMcpServerDev(
252
+ context: PluginRecommendationContext | undefined,
253
+ ): PluginRecommendation {
254
+ const recommended = dependsOn(context, "@modelcontextprotocol/sdk");
255
+ return {
256
+ id: pluginId("mcp-server-dev"),
257
+ recommended,
258
+ because: recommended
259
+ ? "the project depends on @modelcontextprotocol/sdk, and this plugin " +
260
+ "brings skills for building MCP servers and MCP apps and for " +
261
+ "packaging them as MCPB bundles."
262
+ : "only useful to a project that builds on the MCP SDK; " +
263
+ "@modelcontextprotocol/sdk is not among this project's " +
264
+ "dependencies.",
265
+ };
266
+ }
267
+
166
268
  /**
167
269
  * `skill-creator` scaffolds, evaluates and iterates on skills. The baseline's
168
- * own skills are maintained by this repo, not by the project, so it only
169
- * pays for itself in a project that writes skills of its own.
270
+ * own skills are maintained upstream by m3l-groundwork, not by the project,
271
+ * so it only pays for itself in a project that writes skills of its own.
170
272
  */
171
273
  function recommendSkillCreator(
172
274
  context: PluginRecommendationContext | undefined,
@@ -211,26 +313,67 @@ function recommendClaudeCodeSetup(): PluginRecommendation {
211
313
  };
212
314
  }
213
315
 
316
+ /**
317
+ * `plugin-dev` carries the skills and agents for building a Claude Code
318
+ * plugin itself -- manifests, hooks, commands, skills, MCP wiring -- so it is
319
+ * pre-selected for the `plugin` kind, the only kind that authors one.
320
+ */
321
+ function recommendPluginDev(): PluginRecommendation {
322
+ return {
323
+ id: pluginId("plugin-dev"),
324
+ recommended: true,
325
+ because:
326
+ "this project authors a Claude Code plugin, and plugin-dev brings " +
327
+ "guidance and validation for exactly that: the plugin manifest, " +
328
+ "hooks, commands, skills, agents and MCP server wiring, plus the " +
329
+ "marketplace entry it ships through.",
330
+ };
331
+ }
332
+
214
333
  /**
215
334
  * Every built-in marketplace plugin's recommendation for the given interview
216
- * answers and context, always the same seven in the same order: `context7`,
217
- * `typescript-lsp` and `claude-md-management` unconditionally; `github` when
218
- * the `github` pack was chosen; `security-guidance` for a `service` or a
219
- * `thorough` CI depth; `skill-creator` when the project has its own skills;
220
- * `claude-code-setup` never. A pure function -- identical inputs always
221
- * produce an equal result.
335
+ * answers and context: always the same ten in the same order, plus an
336
+ * eleventh, `plugin-dev`, appended last for the `plugin` kind only.
337
+ * Pre-selected unconditionally: `context7`, `typescript-lsp`,
338
+ * `claude-md-management` and `claude-security`. Conditionally: `github` when the `github` pack was
339
+ * chosen; `security-guidance` for a `service` or a `thorough` CI depth;
340
+ * `skill-creator` when the project has its own skills; `agent-sdk-dev` and
341
+ * `mcp-server-dev` when the project depends on the Claude Agent SDK or the
342
+ * MCP SDK respectively. Never: `claude-code-setup`. A pure function --
343
+ * identical inputs always produce an equal result.
344
+ *
345
+ * @example
346
+ * ```ts
347
+ * import { recommendPlugins } from "./plugin-map.js";
348
+ *
349
+ * const recommendations = recommendPlugins(
350
+ * {
351
+ * kind: "service",
352
+ * runtime: "node",
353
+ * testsMandatory: true,
354
+ * ciDepth: "standard",
355
+ * keepAgents: ["code-reviewer"],
356
+ * },
357
+ * { chosenPacks: ["github"], dependencies: ["@modelcontextprotocol/sdk"] },
358
+ * );
359
+ * const preselected = recommendations.filter((r) => r.recommended);
360
+ * ```
222
361
  */
223
362
  export function recommendPlugins(
224
363
  answers: InterviewAnswers,
225
364
  context?: PluginRecommendationContext,
226
365
  ): PluginRecommendation[] {
227
- return [
366
+ const fixed = [
228
367
  recommendContext7(),
229
368
  recommendTypescriptLsp(),
230
369
  recommendClaudeMdManagement(),
231
370
  recommendGithub(context),
232
371
  recommendSecurityGuidance(answers),
372
+ recommendClaudeSecurity(),
233
373
  recommendSkillCreator(context),
234
374
  recommendClaudeCodeSetup(),
375
+ recommendAgentSdkDev(context),
376
+ recommendMcpServerDev(context),
235
377
  ];
378
+ return answers.kind === "plugin" ? [...fixed, recommendPluginDev()] : fixed;
236
379
  }
@@ -3,7 +3,7 @@ name: Explore
3
3
  description: Fast read-only search agent for locating and understanding code. Use it to find files by pattern (e.g. "src/components/**/*.tsx"), grep for symbols or keywords (e.g. "API endpoints"), answer "where is X defined / which files reference Y," or read a bounded set of files in full when the caller says so. Do NOT use it for code review, design-doc auditing, or open-ended cross-file consistency judgment across the whole repo — those need a specialized reviewer. When calling, specify search breadth ("quick" for a single targeted lookup, "medium" for moderate exploration, "very thorough" to search across multiple locations and naming conventions) and say explicitly if the task requires reading matched files in full rather than excerpting them.
4
4
  tools: Read, Grep, Glob, Bash, WebSearch, WebFetch
5
5
  disallowedTools: Agent
6
- model: claude-haiku-4-5
6
+ model: claude-haiku-5-5
7
7
  maxTurns: 40
8
8
  color: cyan
9
9
  ---
@@ -12,13 +12,10 @@
12
12
  * guard alone is bypassed by a Bash command that writes the same file
13
13
  * (`cat > src/a.ts <<EOF`, `sed -i`, `cp`, a `python -c` one-liner).
14
14
  *
15
- * The seam: the PreToolUse payload carries a top-level `agent_type` field
16
- * both when the tool call fires inside a subagent AND in a main session
17
- * started with `claude --agent <name>`, while `agent_id` is sent ONLY when
18
- * the call fires inside a subagent. A spoke is therefore identified by both
19
- * fields together: a call naming a writer in `agent_type` but carrying no
20
- * non-blank string `agent_id` is the hub itself running as `--agent`, not a
21
- * dispatched spoke, and is treated as the hub.
15
+ * The seam: this guard requires both the top-level `agent_type` and
16
+ * `agent_id` payload fields to count a call as a writer spoke: a call naming
17
+ * a writer in `agent_type` but carrying no non-blank string `agent_id` is
18
+ * treated as the hub.
22
19
  *
23
20
  * The decision: block when BOTH conditions hold:
24
21
  * (a) the target path is a guarded source/test path, AND
@@ -1808,11 +1805,9 @@ function isEntryPoint() {
1808
1805
  }
1809
1806
 
1810
1807
  // The agent_type the pure decision functions should see: the payload's own
1811
- // only when a string `agent_id` that is non-empty after `.trim()` proves the
1812
- // call fires inside a subagent; otherwise (absent, non-string, empty or
1813
- // whitespace-only) undefined, i.e. the hub. `agent_type` alone is not
1814
- // enough -- a `claude --agent code-implementer` main session sends it too
1815
- // (see the header's "The seam").
1808
+ // only when a string `agent_id` that is non-empty after `.trim()` is present;
1809
+ // otherwise (absent, non-string, empty or whitespace-only) undefined, i.e. the
1810
+ // hub. A call counts as a spoke only with both fields.
1816
1811
  function spokeAgentType(input) {
1817
1812
  return typeof input.agent_id === "string" && input.agent_id.trim() !== ""
1818
1813
  ? input.agent_type
@@ -97,8 +97,9 @@ if (isEntryPoint()) {
97
97
  process.stderr.write(
98
98
  `Blocked: CommonJS construct(s) found (this project is ESM only):\n` +
99
99
  hits.map((h) => ` - ${h}`).join("\n") +
100
- `\nUse ESM equivalents: import/export, import.meta.url, ` +
101
- `fileURLToPath(import.meta.url).\n`,
100
+ `\nUse ESM equivalents: import/export, import.meta.dirname and ` +
101
+ `import.meta.filename (stable on Node 24+) in place of __dirname and ` +
102
+ `__filename, or fileURLToPath(import.meta.url).\n`,
102
103
  );
103
104
  process.exit(2);
104
105
  }
@@ -73,13 +73,13 @@ export function buildContext(branch) {
73
73
  : `on \`${branch}\``;
74
74
  return [
75
75
  "Decision gate (before editing code/tests) -- currently " +
76
- `${branchLine}. Settle these first, ideally via the \`starting-work\` skill:`,
77
- " • Branch -- `feat/<slug>` or `fix/<slug>` off `main` (never `main`" +
78
- (onMain ? ", and you appear to be on/at `main` now" : "") +
79
- ").",
80
- " • PR -- any `src/`/`tests/` change lands via PR, never a direct commit to `main`.",
81
- " • Push -- `origin <branch>`, not `origin main`.",
82
- "guard-branch-isolation.mjs will block src/test writes on `main`, so branch first.",
76
+ `${branchLine}. These decisions come first, ideally via the \`starting-work\` skill:`,
77
+ " • Branch -- a `feat/<slug>` or `fix/<slug>` branch off `main`, not `main` itself" +
78
+ (onMain ? "; HEAD may be on/at `main` now" : "") +
79
+ ".",
80
+ " • PR -- any `src/`/`tests/` change lands via a PR, not a direct commit to `main`.",
81
+ " • Push -- the target is `origin <branch>`, not `origin main`.",
82
+ "guard-branch-isolation.mjs blocks src/test writes while HEAD is on `main`.",
83
83
  ].join("\n");
84
84
  }
85
85
 
@@ -91,11 +91,16 @@ contract (a documented behavior, an interface to satisfy):
91
91
  - **Review spokes return a bounded digest**, not an open-ended report — the
92
92
  full report travels back inline in the response, capped at roughly 8,000
93
93
  characters (~2,000 tokens). No review spoke writes a scratchpad file.
94
- - **Plan mode propagates its read-only restriction to every subagent it
95
- dispatches** — not just the ones already read-only by design. A writer
96
- spoke dispatched while plan mode is active loses write access too. If a
97
- design depends on a subagent writing a file, verify with `git status`/`ls`
98
- after the dispatch rather than trusting the return value's success claim.
94
+ - **Do not assume plan mode makes a dispatched subagent read-only.** A
95
+ live probe on Claude Code 2.1.296 (2026-10-11) dispatched `test-author` and
96
+ a `general-purpose` agent from a session in plan mode, each told to write
97
+ one file outside the repo: both writes succeeded. Anthropic's
98
+ [subagent docs](https://code.claude.com/docs/en/sub-agents.md) say a
99
+ subagent that sets its own `permissionMode` keeps it, and our writer
100
+ spokes set `acceptEdits`. The main session itself may still decline to
101
+ dispatch a writer in plan mode. If a design depends on a subagent writing
102
+ or not writing a file, verify with `git status`/`ls` after the dispatch
103
+ rather than trusting the return value's success claim.
99
104
  - **A `SubagentStop`/`PreToolUse` hook flagging a dispatch is a prompt to
100
105
  verify, not a replacement for verifying.** Treat its stderr reminder as a
101
106
  signal to check state yourself.
@@ -104,8 +109,8 @@ contract (a documented behavior, an interface to satisfy):
104
109
  `guard-branch-isolation.mjs` let a top-level `src/`/`tests/` write through
105
110
  unblocked, check `/status`'s "Setting sources" line for a managed source
106
111
  before debugging the hook script itself -- a managed `allowManagedHooksOnly`
107
- policy (CLAUDE.md's "Agent Operating Model") disables project hooks
108
- outright, with no repo-visible signal that it's active.
112
+ policy (CLAUDE.md's "Agent Operating Model") means only managed hooks
113
+ run, with no repo-visible signal that it's active.
109
114
  - **A templated dispatch prompt needs a per-target assumption check, not
110
115
  just a per-target file-list check.** Verify the template's implicit
111
116
  assumptions against each target's own docs/tests before dispatch, not
@@ -6,10 +6,13 @@ paths:
6
6
  # Source rules (`src/**`)
7
7
 
8
8
  > This file is the terse checklist that auto-loads when you edit source.
9
- > Base standards — TypeScript strictness, ESM `.js` imports, named exports,
10
- > exporting a type next to its value, `readonly`/`const`, `interface` vs
11
- > `type`, exhaustive `switch`, TSDoc on every export — live in CLAUDE.md and
12
- > `eslint.config.js`; this file adds what those don't already say.
9
+ > Enforced by tooling: `strict` and ESM `.js` imports (`tsconfig.base.json`,
10
+ > `module: nodenext`), named exports only (`import-x/no-default-export`),
11
+ > exhaustive `switch` (`switch-exhaustiveness-check`), `const` over `let`/`var`
12
+ > (`prefer-const`, `no-var`), and TSDoc syntax (`tsdoc/syntax`, a warning).
13
+ > Conventions only, no rule checks them: exporting a type next to its value,
14
+ > `readonly`, `interface` vs `type`, and TSDoc on every export. This file
15
+ > adds what those don't already say.
13
16
 
14
17
  - **Don't pass `undefined` to an optional property.** Under
15
18
  `exactOptionalPropertyTypes`, an optional target field (`default?: number`)
@@ -116,8 +116,8 @@ throw "a string";
116
116
  list and cover any new ternary's non-`Error` arm in the same edit.
117
117
  - **A suite failing while a spoke fan-out is running may be contention, not
118
118
  a regression — re-run it alone first.**
119
- - Use `pnpm exec vitest`; a bare `npx vitest` can fail to resolve
120
- `@vitest/coverage-v8` under pnpm.
119
+ - Use `pnpm exec vitest`, not a bare `npx vitest`, so the project's own
120
+ pinned binary runs.
121
121
  - **Brace void-union handler bodies** — a handler typed `void |
122
122
  Promise<void>` whose arrow body returns a value fails typecheck (TS2322);
123
123
  the leniency applies only to a return type of _exactly_ `void`. Wrap the
@@ -142,9 +142,10 @@ the work is gone.
142
142
  **If a log is written here, commit and land it immediately** (its own small
143
143
  `docs:` commit via `writing-commits`) before moving on to any other task,
144
144
  rather than leaving it as an uncommitted file. **"Commit it" does not mean
145
- commit directly to `main`** — branch first (`git switch -c docs/<slug>-log`),
146
- commit there, push, and open a PR, even for a trivial docs-only change, if
147
- the project requires a PR for every change to `main`.
145
+ commit directly to `main`** when the project requires a PR for every change to
146
+ `main`: in that case branch first (`git switch -c docs/<slug>-log`), commit
147
+ there, push, and open a PR, even for a trivial docs-only change. Only if the
148
+ project allows direct pushes to `main` is the PR step skipped.
148
149
 
149
150
  ### 7 — Orphaned journal sweep
150
151
 
@@ -4,8 +4,8 @@ description: >-
4
4
  Diagnose a CI failure via gh CLI: resolve the failing run, fetch logs, map the
5
5
  failure to its pipeline step, report root cause plus the exact local repro
6
6
  command, and present 3-5 fix options. Use for /triaging-ci, "why did CI fail",
7
- "CI is failing", "debug the CI run", or a specific run ID/URL. GitHub stance:
8
- gh CLI.
7
+ "CI is failing", "the build is red", "find the root cause of a failing
8
+ build", "debug the CI run", or a specific run ID/URL. GitHub stance: gh CLI.
9
9
  ---
10
10
 
11
11
  Diagnose why a GitHub Actions CI run failed by fetching its logs via `gh` and
@@ -104,7 +104,7 @@ Co-Authored-By: <exact model name from your environment> <noreply@anthropic.com>
104
104
 
105
105
  **Co-Authored-By footer**: include whenever Claude authored or substantially
106
106
  assisted the commit. Use the exact model name from the environment (e.g.,
107
- `Claude Sonnet 5`, `Claude Opus 5`) — never copy a model name from an example
107
+ `Claude Sonnet 5.5`, `Claude Opus 5.5`) — never copy a model name from an example
108
108
  or template. The trailer is a provenance marker, not a legal authorship
109
109
  claim.
110
110
 
@@ -163,7 +163,7 @@ EventEmitter<TEventMap> to the public entry point.
163
163
 
164
164
  Three new named exports; no existing export changed.
165
165
 
166
- Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
166
+ Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
167
167
  ```
168
168
 
169
169
  ---
@@ -215,7 +215,7 @@ the durable fixes so later modules don't re-hit them.
215
215
 
216
216
  No src/, test, or exports-map changes; zero semver impact.
217
217
 
218
- Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
218
+ Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
219
219
  ```
220
220
 
221
221
  ---
@@ -244,5 +244,5 @@ output/ holds run archives, not raw output; the old name was misleading.
244
244
 
245
245
  BREAKING CHANGE: Paths.outputDir removed; use archiveDir instead.
246
246
 
247
- Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
247
+ Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
248
248
  ```
@@ -1,6 +1,7 @@
1
1
  node_modules/
2
2
  dist/
3
3
  coverage/
4
+ .vitest/
4
5
  pnpm-lock.yaml
5
6
  CHANGELOG.md
6
7
  # A worktree the harness creates (see .gitignore) is a full, independent
@@ -38,7 +38,8 @@ locally.
38
38
  ## Git Workflow
39
39
 
40
40
  **Conventional Commits (required)**, enforced by the `commit-msg` hook
41
- (`bin/lint-commit.mjs`). Add a `Co-Authored-By:` trailer when Claude
41
+ (`bin/lint-commit.mjs`, run after `bin/strip-claude-trailers.mjs` removes
42
+ harness-injected `Claude-*` trailers). Add a `Co-Authored-By:` trailer when Claude
42
43
  authored or substantially assisted a commit — see `.claude/skills/writing-commits/`.
43
44
 
44
45
  Branch off `main` as `feat/<slug>` / `fix/<slug>`, never work directly on
@@ -52,8 +53,9 @@ Never `git push --force` a shared branch.
52
53
  ## Architecture & Decisions
53
54
 
54
55
  `src/index.ts` is the current public entry point (see the `exports` map in
55
- `package.json`). Everything under `src/internal/`, if you create it, is
56
- private and must never be re-exported.
56
+ `package.json`). By convention, anything under `src/internal/` (if you create
57
+ it) is private and is not re-exported from the entry point; no lint rule
58
+ enforces this, so review for it.
57
59
 
58
60
  ## Agent Operating Model
59
61
 
@@ -71,6 +73,19 @@ contract:
71
73
  Must-fix findings route back to `code-implementer`, and the loop repeats
72
74
  until clean.
73
75
 
76
+ Also shipped: `.claude/agents/Explore.md`, a fast read-only search agent for
77
+ locating files and symbols.
78
+
79
+ Skills, each in `.claude/skills/<name>/`:
80
+
81
+ - `starting-work` — pre-work gate: picks the branch and whether a PR is needed.
82
+ - `writing-commits` — drafts a Conventional Commit from the staged diff.
83
+ - `creating-prs` — verifies gates, pushes, opens the PR and picks a merge path.
84
+ - `triaging-ci` — diagnoses a failed CI run and proposes fixes.
85
+ - `finishing-work` — post-merge cleanup: branches, refs, work log.
86
+ - `typescript-guidance` / `harness-guidance` — live research and refresh
87
+ sweeps (see Freshness).
88
+
74
89
  **The guard also screens `Bash`, but only conservatively.** The same hook
75
90
  runs on every `Bash` call and blocks a command that visibly writes into
76
91
  `src/` or `tests/` (redirects, `tee`, `sed -i`, `cp`/`mv` into them, a
@@ -90,9 +105,9 @@ silently disable it.** Managed settings (a `managed-settings.json` file, an
90
105
  MDM policy, or a claude.ai-console-managed remote policy) take precedence
91
106
  over every file this baseline installs, with no project-level override, and
92
107
  two managed-only keys -- `allowManagedHooksOnly` and
93
- `allowManagedPermissionRulesOnly` -- make Claude Code skip this project's
94
- own `.claude/settings.json` hooks and permission rules entirely rather than
95
- merge with them (see
108
+ `allowManagedPermissionRulesOnly` -- mean that only managed hooks run
109
+ (`allowManagedHooksOnly`) and only managed permission rules apply
110
+ (`allowManagedPermissionRulesOnly`) (see
96
111
  [Claude Code's managed-settings docs](https://code.claude.com/docs/en/managed-settings)).
97
112
  Nothing in this project can detect or gate against that from inside the
98
113
  repo -- the managed file lives outside any working tree, at an OS-level
@@ -112,11 +127,9 @@ only after the last mod calls `next` (see the
112
127
  Only managed-settings hooks outrank a mod, and nothing in the repo can detect
113
128
  one. Check `/plugin` for installed mods alongside `/status`.
114
129
 
115
- **The guard keys on `agent_id` as well as `agent_type`.** Claude Code sends
116
- `agent_type` both inside a subagent and in a main session started with
117
- `--agent <name>`; only a call inside a subagent also carries `agent_id`. A
118
- call counts as a writer spoke only with both present, so a hub launched as
119
- `claude --agent code-implementer` is still the hub and is blocked.
130
+ **The guard keys on `agent_id` as well as `agent_type`.** A call counts as a
131
+ writer spoke only with both present, so a call carrying `agent_type` but no
132
+ `agent_id` is treated as the hub and is blocked.
120
133
 
121
134
  Full dispatch-sizing and recovery guidance: `.claude/rules/agent-dispatch.md`
122
135
  (auto-loads when editing `.claude/skills/**` or `.claude/agents/**`).
@@ -144,10 +157,10 @@ the correct semver impact; new/changed exports have TSDoc and tests. If you
144
157
  touched the harness itself (hooks, agents, skills, rules, `settings.json`),
145
158
  `pnpm verify`'s `harness` step (`bin/check-harness.mjs`) must stay green: it
146
159
  fails on broken wiring and only warns on quality.
147
- If you touched the TypeScript toolchain (`tsconfig*.json`, `eslint.config.js`,
148
- `vitest.config.ts`, `bin/lib/verify-steps.mjs`, the toolchain pins in
149
- `package.json`), the `toolchain` step (`bin/check-toolchain.mjs`) must stay
150
- green the same way: it fails on wiring `tsc` and ESLint do not catch (a build
160
+ The `toolchain` step (`bin/check-toolchain.mjs`) runs on every
161
+ `pnpm verify`, and must stay green when you touch the TypeScript toolchain
162
+ (`tsconfig*.json`, `eslint.config.js`, `vitest.config.ts`,
163
+ `bin/lib/verify-steps.mjs`, the toolchain pins in `package.json`) the same way: it fails on wiring `tsc` and ESLint do not catch (a build
151
164
  project that emits nowhere, a verify step naming a script that does not exist)
152
165
  and only warns on quality (a missing strict flag, an option TypeScript has
153
166
  deprecated). Never silence it by deleting the check or lowering a threshold --
@@ -19,11 +19,23 @@ pnpm install
19
19
  pnpm verify
20
20
  ```
21
21
 
22
- `pnpm verify` runs the same checks CI runs — format, lint, typecheck, build,
23
- and test with coverage — in one command, so you can catch a failure locally
24
- before pushing. See `CLAUDE.md` for the full command reference and this
22
+ `pnpm verify` runs the same checks CI runs, in one command, so you can catch
23
+ a failure locally before pushing. In order: format check, lint, the Claude
24
+ Code harness grader, the TypeScript toolchain grader, knip (unused code and
25
+ dependencies), typecheck, build, tests with coverage, a package-exports check,
26
+ and a Node version pin check. See `CLAUDE.md` for the full command reference and this
25
27
  project's conventions.
26
28
 
29
+ ## Notable files
30
+
31
+ - `.github/dependabot.yml` — weekly Dependabot updates for the GitHub Actions
32
+ pinned in `.github/workflows/` (npm updates are left off by default).
33
+ - `pnpm-workspace.yaml` — pnpm's install-script approval list (`allowBuilds`),
34
+ which pnpm 10+ reads from here rather than from `package.json`.
35
+ - `bin/strip-claude-trailers.mjs` — run by the `commit-msg` hook in
36
+ `lefthook.yml` before commit linting; strips harness-injected `Claude-*`
37
+ trailers and leaves `Co-Authored-By:` alone.
38
+
27
39
  ## Tailor it to your project
28
40
 
29
41
  This baseline is frozen at the moment it was generated, and deliberately
@@ -7,6 +7,7 @@ dist/
7
7
 
8
8
  # Test / coverage artifacts
9
9
  coverage/
10
+ .vitest/
10
11
 
11
12
  # Editor / OS
12
13
  .DS_Store
@@ -79,9 +79,11 @@ try {
79
79
  // This project is ESM-only by design (no CommonJS -- see
80
80
  // guard-no-commonjs.mjs); attw's default node16-from-CJS check
81
81
  // flags exactly the interop this package intentionally doesn't
82
- // support. Ignoring this one rule is attw's own documented
83
- // escape hatch for a deliberately ESM-only package, not a
84
- // suppression of a real problem.
82
+ // support. Ignoring this one rule (`--ignore-rules`) is a narrow
83
+ // suppression of that known interop gap, not of a real problem. attw's
84
+ // documented ESM-only mechanism is the broader `--profile esm-only`,
85
+ // which ignores every CJS-mode resolution failure; this keeps the
86
+ // narrower rule on purpose so other CJS-side problems still surface.
85
87
  "--ignore-rules",
86
88
  "cjs-resolves-to-esm",
87
89
  ],
@@ -19,7 +19,8 @@ import { fieldList, fieldText, parseFrontmatter } from "./frontmatter.mjs";
19
19
  * Model ids and aliases the rubric accepts: the current ids and aliases, plus
20
20
  * ids that were once listed here, kept until Anthropic deprecates them. The
21
21
  * ids follow Anthropic's models overview and model-deprecations pages
22
- * (retrieved 2026-10-01). A legacy id that was never listed here is
22
+ * (retrieved 2026-10-08): Haiku 5.5 (released 2026-10-07) is current, and
23
+ * Haiku 4.5 is legacy but still active. A legacy id that was never listed here is
23
24
  * deliberately not added, so the rule keeps nudging pins toward current
24
25
  * models. Bump alongside a harness-guidance refresh sweep.
25
26
  * @public Not imported anywhere else in this project -- exported only for
@@ -36,6 +37,7 @@ export const CURRENT_MODELS = [
36
37
  "claude-sonnet-5",
37
38
  "claude-sonnet-5-5",
38
39
  "claude-fable-5-1",
40
+ "claude-haiku-5-5",
39
41
  "claude-haiku-4-5",
40
42
  "claude-haiku-4-5-20251001",
41
43
  ];
@@ -26,8 +26,11 @@ import { readFileSync, readdirSync, statSync } from "node:fs";
26
26
  import { dirname, isAbsolute, join, relative, resolve } from "node:path";
27
27
 
28
28
  /**
29
- * Options TypeScript 6.0 deprecated. `removedIn` is the major that drops them
30
- * (`outFile` and `moduleResolution: classic` already went in 6.0).
29
+ * Options TypeScript 6.0 deprecated. `removedIn` is the major that drops them.
30
+ * `outFile` and `moduleResolution: classic` are `removedIn: 6` because the
31
+ * TypeScript 6.0 release notes call them removed; `tsc` 6.0.3 itself still
32
+ * accepts both behind `ignoreDeprecations: "6.0"` and warns that they stop
33
+ * functioning in 7.0.
31
34
  * https://www.typescriptlang.org/docs/handbook/release-notes/typescript-6-0.html
32
35
  * @public Not imported anywhere else in this project -- exported only for
33
36
  * m3l-groundwork's own upstream parity check (see the file header above).
@@ -649,12 +652,17 @@ function loadSnapshot(root) {
649
652
  packageRead.ok && isRecord(packageRead.value)
650
653
  ? packageRead.value
651
654
  : undefined;
652
- const scripts = {};
653
- if (pkg !== undefined && isRecord(pkg.scripts)) {
654
- for (const [name, cmd] of Object.entries(pkg.scripts)) {
655
- if (typeof cmd === "string") scripts[name] = cmd;
656
- }
657
- }
655
+ // Object.fromEntries, not `scripts[name] = cmd` on a `{}`: assignment to
656
+ // `__proto__` hits the prototype setter and silently drops a script of that
657
+ // name, while fromEntries defines every key as an own data property.
658
+ const scripts =
659
+ pkg !== undefined && isRecord(pkg.scripts)
660
+ ? Object.fromEntries(
661
+ Object.entries(pkg.scripts).filter(
662
+ ([, cmd]) => typeof cmd === "string",
663
+ ),
664
+ )
665
+ : {};
658
666
 
659
667
  const tsconfigFiles = new Map();
660
668
  const tsconfigLinks = [];
@@ -899,7 +907,7 @@ const gateWiring = {
899
907
  const script = first === "run" ? second : first;
900
908
  if (script !== undefined && !PNPM_BUILTINS.has(script)) {
901
909
  checked += 1;
902
- if (scripts[script] === undefined) {
910
+ if (!Object.hasOwn(scripts, script)) {
903
911
  failures.push({
904
912
  subject: `${stepsFile} step "${step.id}"`,
905
913
  message: `runs \`pnpm ${script}\`, but package.json has no "${script}" script`,