@monte3l/groundwork 1.0.0-rc.8 → 1.0.1

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.
package/README.md CHANGED
@@ -25,10 +25,9 @@ copy of the `/customize` skill at `.claude/skills/customize/`, or at
25
25
  `.groundwork/customize/` when something already there blocks it.
26
26
 
27
27
  ```bash
28
- # currently a 1.0.0 release candidate, shipping on the `rc` dist-tag
29
- npx @monte3l/groundwork@rc my-new-project
30
- npx @monte3l/groundwork@rc my-new-project --pack harness-extras
31
- npx @monte3l/groundwork@rc ../existing-project
28
+ npx @monte3l/groundwork my-new-project
29
+ npx @monte3l/groundwork my-new-project --pack harness-extras
30
+ npx @monte3l/groundwork ../existing-project
32
31
  ```
33
32
 
34
33
  Requires Node 24+. No prompts, and no network call beyond the `pnpm install` a
package/dist/main.d.ts CHANGED
@@ -18,7 +18,7 @@ export interface CliOptions {
18
18
  *
19
19
  * @example
20
20
  * ```sh
21
- * npx @monte3l/groundwork@next ./my-app --bogus
21
+ * npx @monte3l/groundwork ./my-app --bogus
22
22
  * # stderr: unrecognized option: --bogus (followed by the usage text)
23
23
  * echo $? # 2 -- a runtime failure exits 1 instead
24
24
  * ```
package/dist/main.js CHANGED
@@ -92,7 +92,7 @@ const BOOLEAN_FLAGS = new Set([
92
92
  *
93
93
  * @example
94
94
  * ```sh
95
- * npx @monte3l/groundwork@next ./my-app --bogus
95
+ * npx @monte3l/groundwork ./my-app --bogus
96
96
  * # stderr: unrecognized option: --bogus (followed by the usage text)
97
97
  * echo $? # 2 -- a runtime failure exits 1 instead
98
98
  * ```
@@ -474,25 +474,44 @@ const STALE_FILE_NAMES = [
474
474
  "inventory.json",
475
475
  "adoption-report.md",
476
476
  "adoption-decisions.json",
477
+ "customization-report.md",
477
478
  ];
479
+ const DECISIONS_CAVEAT = "adoption-decisions.json held the decisions /customize recorded";
480
+ const CUSTOMIZATION_CAVEAT = "customization-report.md held the report /customize wrote";
481
+ /**
482
+ * The "a re-run does not recreate it" caveat for whichever of the two
483
+ * `/customize`-written files were removed: empty when neither was, one
484
+ * clause when one was, and a single combined clause when both were.
485
+ */
486
+ function notRecreatedCaveat(removed) {
487
+ const decisions = removed.includes("adoption-decisions.json");
488
+ const customization = removed.includes("customization-report.md");
489
+ if (decisions && customization) {
490
+ return ` -- ${DECISIONS_CAVEAT}, and ${CUSTOMIZATION_CAVEAT}; a re-run recreates neither`;
491
+ }
492
+ if (decisions) {
493
+ return ` -- ${DECISIONS_CAVEAT}, which a re-run does not recreate`;
494
+ }
495
+ if (customization) {
496
+ return ` -- ${CUSTOMIZATION_CAVEAT}, which a re-run does not recreate`;
497
+ }
498
+ return "";
499
+ }
478
500
  /**
479
501
  * Which previous `.groundwork/` files a failed run actually removed, worded
480
502
  * for a message: only those in `removed` are named, and the decisions file
481
- * carries its "a re-run does not recreate it" caveat only when it is one of
482
- * them.
503
+ * and the customization report each carry their "a re-run does not recreate
504
+ * it" caveat only when they are among them.
483
505
  */
484
506
  function describeRemoved(removed) {
485
507
  if (removed.length === 0) {
486
- return "no previous .groundwork/ inventory, report or decisions file was removed";
508
+ return "no previous .groundwork/ inventory, adoption report, decisions file or customization report was removed";
487
509
  }
488
510
  const names = removed.length === 1
489
511
  ? removed.join("")
490
512
  : `${removed.slice(0, -1).join(", ")} and ${removed.slice(-1).join("")}`;
491
513
  const verb = removed.length === 1 ? "was" : "were";
492
- const decisionsCaveat = removed.includes("adoption-decisions.json")
493
- ? " -- adoption-decisions.json held the decisions /customize recorded, which a re-run does not recreate"
494
- : "";
495
- return `the previous .groundwork/${names} ${verb} removed${decisionsCaveat}`;
514
+ return `the previous .groundwork/${names} ${verb} removed${notRecreatedCaveat(removed)}`;
496
515
  }
497
516
  /**
498
517
  * A failure after `runAdopt`'s point of no return. The message embeds the
@@ -583,7 +602,7 @@ function groundworkReportNextStep(result) {
583
602
  * already deleted, so nothing reads the gap as a completed run.
584
603
  *
585
604
  * Checked before anything under `.groundwork/` is deleted or written, in
586
- * this order: the three stale-file paths are scope-checked against
605
+ * this order: the four stale-file paths are scope-checked against
587
606
  * {@link assertAdoptWriteScope}; every pack is loaded and validated by
588
607
  * `loadPack` and surveyed (`planConflicts`, `observeWiring`); the pack
589
608
  * staging plan (`planPackStaging`) and the baseline staging plan
@@ -598,8 +617,9 @@ function groundworkReportNextStep(result) {
598
617
  * directory throws with the previous `.groundwork/` untouched.
599
618
  *
600
619
  * **The point of no return** is the first deletion of a stale
601
- * `inventory.json`/`adoption-report.md`/`adoption-decisions.json` (in that
602
- * order), which follows those checks; which of the three existed is
620
+ * `inventory.json`/`adoption-report.md`/`adoption-decisions.json`/
621
+ * `customization-report.md` (in that order), which follows those checks;
622
+ * which of the four existed is
603
623
  * recorded just before. After the deletions, packs and the baseline are
604
624
  * staged from the plans already computed (their trees are not walked
605
625
  * again), the harness and toolchain are graded, the `/customize` skill is
@@ -610,8 +630,9 @@ function groundworkReportNextStep(result) {
610
630
  * rename). A failure in any of those steps -- a failed deletion included --
611
631
  * is rethrown as an `Error` with the failure as `cause` and its message
612
632
  * embedded, naming only the previous files that existed and were actually
613
- * removed (and, when `adoption-decisions.json` is among them, that it held
614
- * the decisions `/customize` recorded, which a re-run does not recreate),
633
+ * removed (and, when `adoption-decisions.json` or `customization-report.md`
634
+ * is among them, that it held the decisions or the report `/customize`
635
+ * wrote, which a re-run does not recreate),
615
636
  * and saying to fix the cause and re-run the CLI -- once, even when the
616
637
  * cause's own message already says so. An `AssertionError` (a broken
617
638
  * write-scope or containment invariant, a bug a re-run cannot fix) keeps
@@ -686,11 +707,12 @@ function runAdopt(options, detection) {
686
707
  let nextStep;
687
708
  try {
688
709
  // The point of no return: the first deletion. A previous run's
689
- // inventory/report -- and the decisions /customize recorded against
690
- // them -- must not survive a run that fails part-way: /customize would
691
- // read them as describing the new staging. All three go before anything
692
- // is staged; inventory/report are rewritten only at the end, and the
693
- // decisions file only by /customize. Inside the wrapping, so a failed
710
+ // inventory/report -- and the decisions and customization report
711
+ // /customize wrote against them -- must not survive a run that fails
712
+ // part-way: /customize would read them as describing the new staging.
713
+ // All four go before anything is staged; inventory/report are rewritten
714
+ // only at the end, and the decisions file and customization report only
715
+ // by /customize. Inside the wrapping, so a failed
694
716
  // deletion reports which files are already gone. Every path is removed,
695
717
  // not just the pre-existing ones: existsSync follows symlinks, so a
696
718
  // dangling one must still go before the report's "wx" write below.
package/dist/packs.js CHANGED
@@ -228,6 +228,94 @@ function writeVerifyStepsPacksJson(path, steps) {
228
228
  lines.push("]");
229
229
  writeFileSync(path, lines.join("\n") + "\n");
230
230
  }
231
+ const SETTINGS_PRINT_WIDTH = 80;
232
+ const SETTINGS_MAX_DEPTH = 64;
233
+ function isJsonScalar(value) {
234
+ return (value === null ||
235
+ typeof value === "string" ||
236
+ typeof value === "number" ||
237
+ typeof value === "boolean");
238
+ }
239
+ function stringifyScalar(value) {
240
+ const text = JSON.stringify(value);
241
+ if (typeof text !== "string") {
242
+ throw new Error(`settings.json value ${String(value)} is not serializable`);
243
+ }
244
+ return text;
245
+ }
246
+ /**
247
+ * Prints `value` at `indent` (in spaces). `prefix` is what precedes the value
248
+ * on its first line (indent plus any `"key": `) and `suffix` what follows its
249
+ * last (a trailing comma or nothing) -- both count toward the one-line fit
250
+ * check for an all-scalar array. Width is measured in UTF-16 code units
251
+ * (`.length`), not Prettier's display width, so a line holding CJK or other
252
+ * wide characters can stay collapsed where Prettier would expand it. See
253
+ * {@link writeSettingsJson} for the shapes this reproduces and the known
254
+ * divergences.
255
+ */
256
+ function printSettingsValue(value, indent, prefix, suffix, depth) {
257
+ if (depth > SETTINGS_MAX_DEPTH) {
258
+ throw new Error(`settings.json nests deeper than ${String(SETTINGS_MAX_DEPTH)} levels`);
259
+ }
260
+ if (isJsonScalar(value))
261
+ return stringifyScalar(value);
262
+ const pad = " ".repeat(indent + 2);
263
+ const close = " ".repeat(indent);
264
+ if (Array.isArray(value)) {
265
+ const items = value;
266
+ if (items.length === 0)
267
+ return "[]";
268
+ if (items.every(isJsonScalar)) {
269
+ const flat = `[${items.map(stringifyScalar).join(", ")}]`;
270
+ if ((prefix + flat + suffix).length <= SETTINGS_PRINT_WIDTH)
271
+ return flat;
272
+ }
273
+ const lines = items.map((item, index) => {
274
+ const comma = index < items.length - 1 ? "," : "";
275
+ return `${pad}${printSettingsValue(item, indent + 2, pad, comma, depth + 1)}${comma}`;
276
+ });
277
+ return `[\n${lines.join("\n")}\n${close}]`;
278
+ }
279
+ if (typeof value === "object") {
280
+ // Match JSON.stringify: an own key whose value is undefined is omitted.
281
+ const entries = Object.entries(value).filter(([, v]) => v !== undefined);
282
+ if (entries.length === 0)
283
+ return "{}";
284
+ const lines = entries.map(([key, v], index) => {
285
+ const comma = index < entries.length - 1 ? "," : "";
286
+ const head = `${pad}${stringifyScalar(key)}: `;
287
+ return `${head}${printSettingsValue(v, indent + 2, head, comma, depth + 1)}${comma}`;
288
+ });
289
+ return `{\n${lines.join("\n")}\n${close}}`;
290
+ }
291
+ throw new Error(`settings.json holds a non-JSON ${typeof value} value`);
292
+ }
293
+ /**
294
+ * Serializes `.claude/settings.json` so it matches Prettier's JSON output
295
+ * for the shapes a Claude Code settings file holds -- objects, arrays of
296
+ * objects, and arrays of strings: 2-space indent, objects one key per line
297
+ * (`{}` when empty), an array of objects expanded one element per line
298
+ * (`[]` when empty), and an array of only scalars kept on one line --
299
+ * `["a", "b"]` -- when that whole line, indent and key and any trailing
300
+ * comma included, fits in 80 columns, else expanded one per line.
301
+ * `JSON.stringify(value, null, 2)` always expands arrays, so a short
302
+ * `permissions.deny` list written through `writeJson` fails
303
+ * `prettier --check` after every pack install. Key order is preserved.
304
+ *
305
+ * This is not a general JSON formatter. It throws on a non-JSON value or
306
+ * nesting past a fixed depth, and it diverges from Prettier in ways no
307
+ * settings file reaches today: an array containing arrays or empty objects
308
+ * is always expanded (Prettier collapses it when it fits); a wide numeric
309
+ * array prints one number per line (Prettier fills several per line); width
310
+ * is measured with `.length` code units rather than Prettier's display
311
+ * width, so CJK or other wide characters can collapse a line Prettier would
312
+ * expand; and numbers use `JSON.stringify`'s form (`1e+21`, where Prettier
313
+ * keeps `1e21`).
314
+ */
315
+ function writeSettingsJson(path, value) {
316
+ mkdirSync(dirname(path), { recursive: true });
317
+ writeFileSync(path, `${printSettingsValue(value, 0, "", "", 0)}\n`);
318
+ }
231
319
  /**
232
320
  * Installs one pack into a target directory that already has the baseline
233
321
  * emitted (fresh mode only). Copies `files/` via the existing `emitTemplate`
@@ -254,7 +342,7 @@ export function installPack(pack, targetDir, tokens) {
254
342
  settings = mergeSettingsHooks(settings, manifest.wiring.settings);
255
343
  }
256
344
  settings = mergeSettingsTopLevel(settings, manifest.wiring.settingsTopLevel ?? {});
257
- writeJson(settingsPath, settings);
345
+ writeSettingsJson(settingsPath, settings);
258
346
  if (Object.keys(manifest.wiring.packageScripts).length > 0) {
259
347
  const pkgPath = join(targetDir, "package.json");
260
348
  const pkg = readJsonOrThrow(pkgPath);
package/dist/report.js CHANGED
@@ -363,21 +363,17 @@ function renderUndeterminedSection(inventory) {
363
363
  */
364
364
  function renderStagedFilesNote(stagedBaseline, stagedPacks) {
365
365
  const parts = [];
366
- const dirs = [];
367
366
  if (stagedBaseline.files.length > 0) {
368
367
  parts.push(`the baseline files staged under \`${stagedBaseline.dir}/\``);
369
- dirs.push(stagedBaseline.dir);
370
368
  }
371
369
  if (stagedPacks.length > 0) {
372
370
  parts.push(`the ${stagedPacks.length} pack(s) staged under \`${STAGED_PACKS_DIR}/\` ` +
373
371
  `(each pack's \`${STAGED_PACK_MANIFEST}\` included)`);
374
- dirs.push(STAGED_PACKS_DIR);
375
372
  }
376
373
  const subject = parts.join(" and ");
377
374
  if (subject === "") {
378
375
  return [];
379
376
  }
380
- const ignoreLines = dirs.map((dir) => `\`${dir}/\``).join(" and a ");
381
377
  return [
382
378
  `${subject.charAt(0).toUpperCase()}${subject.slice(1)} are inert copies, never ` +
383
379
  `installed: each carries a \`${STAGED_SUFFIX}\` suffix so no tool in this ` +
@@ -385,8 +381,8 @@ function renderStagedFilesNote(stagedBaseline, stagedPacks) {
385
381
  `confirm it. Decide whether to commit or ignore those \`${STAGED_SUFFIX}\` ` +
386
382
  "files before your next commit: they are verbatim template copies, so " +
387
383
  "a strict license-header check, or any gate that runs over every " +
388
- `tracked file, may flag them. To keep them out of git, add a ` +
389
- `${ignoreLines} line to \`.gitignore\`.`,
384
+ "tracked file, may flag them. The `.groundwork/*` line in the " +
385
+ "`.gitignore` recommendation below keeps them out of git.",
390
386
  "",
391
387
  ];
392
388
  }
@@ -464,10 +460,22 @@ export function renderReport(inventory, nextStep) {
464
460
  "is the point where it's caught.",
465
461
  "",
466
462
  ...renderStagedFilesNote(inventory.stagedBaseline, inventory.stagedPacks),
467
- "`.groundwork/` itself was not added to this project's `.gitignore` -- " +
468
- "that choice is yours. It's disposable (regenerate it any time by " +
469
- "re-running the CLI), so most projects gitignore it; some prefer to " +
470
- "commit it as a record of what the adoption found.",
463
+ "`.groundwork/` itself was not added to this project's `.gitignore`. " +
464
+ "We recommend tracking this report (and `customization-report.md`, " +
465
+ "once `/customize` has written it) as a record of the adoption, and " +
466
+ "ignoring the rest, which is disposable -- regenerate it any time by " +
467
+ "re-running the CLI:",
468
+ "",
469
+ "```gitignore",
470
+ ".groundwork/*",
471
+ "!.groundwork/adoption-report.md",
472
+ "!.groundwork/customization-report.md",
473
+ "```",
474
+ "",
475
+ "`/customize` asks about this at the end of its run. With this rule a " +
476
+ "clone of the project holds the two reports but no " +
477
+ "`.groundwork/inventory.json`, so on such a clone re-run the CLI " +
478
+ "(`npx @monte3l/groundwork .`) and then run `/customize`.",
471
479
  "",
472
480
  ];
473
481
  return sections.join("\n");
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@monte3l/groundwork",
3
- "version": "1.0.0-rc.8",
3
+ "version": "1.0.1",
4
4
  "description": "CLI that writes a TypeScript toolchain and Claude Code setup into an empty directory, or -- against an existing project -- read-only surveys it and reports the differences. No prompts, and no network access beyond the package install.",
5
5
  "keywords": [
6
6
  "typescript",
@@ -59,20 +59,26 @@ procedure, and a compacted session keeps only the start of this file.
59
59
 
60
60
  In outline:
61
61
 
62
- 1. Look for `.groundwork/inventory.json`. No `.groundwork/` at all means a
63
- fresh bootstrap: skip to Step 1. A `.groundwork/` with no inventory means an
64
- interrupted CLI run, and an unreadable inventory is invalid: in both cases
62
+ 1. Look for `.groundwork/inventory.json`. No `.groundwork/` at all usually
63
+ means a fresh bootstrap: skip to Step 1, unless `git rev-list -n1 HEAD`
64
+ shows the repository has commits (the folder may be gitignored), in which
65
+ case ask first. A `.groundwork/` holding only tracked report files is a
66
+ clone of an adopted project: re-run the CLI. Any other `.groundwork/` with
67
+ no inventory means an interrupted CLI run, and an unreadable inventory is invalid: in both cases
65
68
  stop and change nothing, and never treat the project as a fresh bootstrap.
66
69
  2. **The deep read.** The CLI's survey is an index, not an interpretation:
67
70
  read the real files it flagged `needsReading`, and reconcile its facts
68
71
  against the repository.
69
- 3. **Write the findings back** into `.groundwork/adoption-report.md`.
72
+ 3. **Write the findings back** into `.groundwork/adoption-report.md`,
73
+ replacing the CLI's sections by heading (the table in step 0.3 says which
74
+ are replaced and which are kept), and refresh it after Rounds 1 and 2.
70
75
  4. **Confirm** the additions, the conflict resolutions and which packs to
71
76
  install, in one `AskUserQuestion` round. Nothing is written to a project
72
77
  file before this.
73
78
  5. **Record the confirmed decisions** to `.groundwork/adoption-decisions.json`
74
- so a compacted or resumed session does not re-ask them. After a compaction,
75
- read that file first.
79
+ so a compacted or resumed session does not re-ask them. Update it after
80
+ every later step, record a dismissed question as dismissed, and after a
81
+ compaction read that file first and never re-ask a recorded decision.
76
82
 
77
83
  ## Step 1 — Interview
78
84
 
@@ -109,6 +115,10 @@ never names a `ProjectKind` itself (the type lives in this plugin's
109
115
  happens once, here, visibly, with its reasoning attached — not buried in an
110
116
  offline heuristic no one reviews.
111
117
 
118
+ A question the user dismisses is not an answer. Apply its default, record the
119
+ entry (adopt mode) as `"dismissed"` with that default as the fallback, and report it in
120
+ Step 7 under "Assumed, not answered".
121
+
112
122
  Packs are **not** re-asked here — Step 0.4 already collected that decision
113
123
  (adopt mode) or the CLI already installed at bootstrap time via `--pack`
114
124
  (fresh mode, nothing left to ask). Step 3 below is where a confirmed kind can
@@ -183,6 +193,12 @@ final summary every place the findings disagreed with what Round 0/1
183
193
  shipped — that disagreement list is the feature: it's the evidence the
184
194
  baseline had gone stale.
185
195
 
196
+ **A finding that changes hook behaviour** (a guard failing closed, a new
197
+ deny rule, a widened matcher) is not applied silently in either direction. In
198
+ adopt mode, collect those into one `AskUserQuestion` (apply or defer),
199
+ record each answer under `round2` in the decisions file, and put a deferred
200
+ one in the tracker's pending remediation.
201
+
186
202
  **The one exception.** Where a finding would undo an **explicit interview
187
203
  answer** from Step 1 — the user said tests must not gate `pre-push`,
188
204
  guidance says they should — surface the conflict and leave the user's
@@ -242,3 +258,30 @@ declined, plus any prerequisite named against an enabled plugin
242
258
  (e.g. `typescript-language-server` on `PATH`, or the Python version a
243
259
  plugin's `prerequisites` names) as a follow-up the
244
260
  user still has to satisfy.
261
+
262
+ **Write the report to a file as well (adopt mode only).** Save the same report
263
+ to `.groundwork/customization-report.md`, so a reviewer can read it without
264
+ asking for the chat. Include which conflicts were resolved and which packs
265
+ were installed, anything in `round1.dropped` with its reason, a **Needs a
266
+ human read** list (every file in `round1.mechanicallyRetargeted`, plus any
267
+ retargeted gate reported as not exercised), an **Assumed, not answered** list
268
+ (each `"dismissed"` interview entry and the fallback used), and a skipped
269
+ `guard-readonly-bash` with its reason. Rewrite the adoption report's
270
+ `## Next step` to point at this file. Never write it in fresh mode: a
271
+ `.groundwork/` directory with no inventory reads as an interrupted adopt run.
272
+
273
+ **Adopt mode only: ask once about `.gitignore`.** The CLI never edits the
274
+ project's `.gitignore`. Recommend tracking the two reports and ignoring the
275
+ rest of `.groundwork/` (the inventory holds absolute machine paths, the
276
+ staged copies are bulky, and the decisions file is only valid beside its own
277
+ inventory):
278
+
279
+ ```gitignore
280
+ .groundwork/*
281
+ !.groundwork/adoption-report.md
282
+ !.groundwork/customization-report.md
283
+ ```
284
+
285
+ Add it only if the user agrees. Say that a teammate's clone then holds the
286
+ two reports but no `.groundwork/inventory.json`, which Step 0.1 recognizes as a
287
+ clone and answers with the re-run advice.
@@ -13,9 +13,29 @@ Contents:
13
13
  ## Step 0 — Reconcile (adopt mode only)
14
14
 
15
15
  1. Look for `.groundwork/inventory.json`.
16
- - **Absent, and no `.groundwork/` directory either → this is a fresh
16
+ - **Absent, and no `.groundwork/` directory either → usually a fresh
17
17
  bootstrap; skip straight to Step 1.** Everything below this step applies
18
- only when an inventory exists.
18
+ only when an inventory exists. **One guard first:** an adopted project
19
+ may gitignore `.groundwork/`, so a clone can lack the directory. Run
20
+ `git rev-list -n1 HEAD` in the project. Empty output, or a non-zero exit
21
+ (no commits, or not a git repository at all, which is what the CLI's fresh
22
+ mode leaves behind), keeps the fresh path. A commit means the project
23
+ already has history, so ask once with `AskUserQuestion`: "fresh
24
+ bootstrap" or "an adopted project whose `.groundwork/` is missing". The
25
+ second answer stops with the re-run advice below and changes nothing.
26
+ Never apply fresh-mode tailoring to an established codebase on the
27
+ strength of a missing directory alone.
28
+ - **Absent, but `.groundwork/` holds only tracked report files → a clone
29
+ of an adopted project.** The recommended `.gitignore` (Step 7) tracks
30
+ `adoption-report.md` and `customization-report.md` and ignores the
31
+ rest, so a clone has a `.groundwork/` with those reports and no
32
+ inventory, no `baseline/` and no `packs/`. Confirm with
33
+ `git ls-files .groundwork` (it lists the files present). This is not an
34
+ interrupted run. Stop, change nothing, and tell the user: "This clone has
35
+ the adoption reports but not the inventory, which is deliberately not
36
+ committed. Re-run `npx @monte3l/groundwork .` and then run `/customize`
37
+ again. The re-run deletes the tracked `.groundwork/customization-report.md`
38
+ from your working tree; `git restore` brings it back if you want it."
19
39
  - **Absent, but `.groundwork/` exists → a previous CLI adopt run did not
20
40
  complete** (the CLI deletes the old inventory before it stages anything
21
41
  and writes the new one last, so no inventory beside a `.groundwork/`
@@ -25,12 +45,12 @@ Contents:
25
45
  previous adopt run did not finish, or `inventory.json` was removed.
26
46
  If this project was never adopted (it was bootstrapped fresh), delete
27
47
  `.groundwork/` and run `/customize` again. Otherwise re-run
28
- `npx @monte3l/groundwork@rc .` and then run `/customize` again."
48
+ `npx @monte3l/groundwork .` and then run `/customize` again."
29
49
  Change nothing.
30
50
  - **Present, but not valid JSON, or its `schemaVersion` is not an integer
31
51
  of at least 1 → stop and change nothing.** Tell the user: "`.groundwork/inventory.json`
32
52
  is not valid JSON or has no usable `schemaVersion`. Re-run
33
- `npx @monte3l/groundwork@rc .` and then run `/customize` again."
53
+ `npx @monte3l/groundwork .` and then run `/customize` again."
34
54
 
35
55
  **Check `inventory.schemaVersion` before reading anything else.** This
36
56
  skill understands schema versions **1 through 6** (the highest it knows is
@@ -46,7 +66,7 @@ Contents:
46
66
  project owns there, nor writes through a symlinked `.claude`), it writes a
47
67
  fresh one to `.groundwork/customize/`, which Claude Code does not load. So delete
48
68
  that directory first (this discards any local edits the project made to
49
- its copy) and then re-run `npx @monte3l/groundwork@rc .`. A
69
+ its copy) and then re-run `npx @monte3l/groundwork .`. A
50
70
  copy in `.groundwork/customize/` is refreshed by re-running the CLI. What
51
71
  each version added:
52
72
 
@@ -172,7 +192,7 @@ Contents:
172
192
  `stagedBaseline.files`, a pack's `files` or a pack's manifest
173
193
  means stop -- all of Round 1, including conflicts and packs -- and
174
194
  change nothing.** This is the single stop list for the staged baseline and the staged packs.
175
- Tell the user: "The staged baseline in `.groundwork/baseline/` or a staged pack in `.groundwork/packs/` is incomplete or does not match `.groundwork/inventory.json` (<the first entry that failed and why>). Re-run `npx @monte3l/groundwork@rc .` and then run `/customize` again." **Never fall back to `inventory.templateRoot` for a schema 5 or later inventory, packs included:** that fallback exists for a schema 1-4 inventory only, and only for the baseline additions (a schema 1-4 inventory's packs are read from their unsuffixed copy, see Step 0.4(c) and Round 1).
195
+ Tell the user: "The staged baseline in `.groundwork/baseline/` or a staged pack in `.groundwork/packs/` is incomplete or does not match `.groundwork/inventory.json` (<the first entry that failed and why>). Re-run `npx @monte3l/groundwork .` and then run `/customize` again." **Never fall back to `inventory.templateRoot` for a schema 5 or later inventory, packs included:** that fallback exists for a schema 1-4 inventory only, and only for the baseline additions (a schema 1-4 inventory's packs are read from their unsuffixed copy, see Step 0.4(c) and Round 1).
176
196
  - What a passing check proves: the staging is complete and matches the
177
197
  inventory. It does **not** prove the files are untampered -- anyone who
178
198
  can edit the staged files can edit the inventory's hashes too.
@@ -222,9 +242,31 @@ Contents:
222
242
  3. **Write the findings back** into `.groundwork/adoption-report.md`,
223
243
  replacing the CLI's index-level sections ("a `lefthook.yml` exists")
224
244
  with semantic ones ("pre-push runs lint and typecheck; tests do not
225
- gate"). If the no-shell bullet in step 1 applied, carry its skip note
226
- into the rewritten report: this step replaces the report's sections, so
227
- a note written earlier would be dropped.
245
+ gate"). Do it by heading, never by prepending a new section above the
246
+ old ones: a report that keeps both contradicts itself once Round 1 runs.
247
+ Every `##` heading the CLI emits has exactly one fate:
248
+
249
+ | Heading | Fate |
250
+ | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
251
+ | `## Codebase shape` | Replace now with what the deep read established (what is unresolved stays listed, what it explained goes) |
252
+ | `## Toolchain enforcement in effect` | Replace now ("pre-push runs lint and typecheck; tests do not gate") |
253
+ | `## Existing Claude Code harness` | Replace now with the real wiring, then rewrite again after Round 1 so it states the installed harness |
254
+ | `## Human-facing docs & guidelines` | Replace now with what the docs actually say |
255
+ | `## Could not be determined` | Replace now: drop each item the deep read resolved, keep the rest |
256
+ | `## Toolchain grade` | Keep verbatim: deterministic CLI facts |
257
+ | `## Harness grade` | Keep verbatim: deterministic CLI facts |
258
+ | `## Available packs` | Keep verbatim: deterministic CLI facts |
259
+ | `## Baseline caps after a merge (approximate)` | Rewrite after Round 1 with the real post-install counts |
260
+ | `## What groundwork would change` | Rewrite after Round 1 as "What groundwork changed": resolutions applied, files added, packs installed, planned installs dropped and why |
261
+ | `## Next step` | Rewrite in Step 7 to point at `.groundwork/customization-report.md` |
262
+
263
+ Refresh the report again at the end of Round 1 and Round 2, so no section
264
+ survives that says "none", "would be added" or "run `/customize`" about
265
+ something that already happened. If the no-shell bullet in step 1
266
+ applied, carry its skip note into the rewritten report: this step
267
+ replaces the report's sections, so a note written earlier would be
268
+ dropped.
269
+
228
270
  4. **Confirm.** Give a short summary in chat, then ask **one**
229
271
  `AskUserQuestion` covering: (a) _did this miss anything about your
230
272
  project?_ — the free-text option is the point of this question, not a
@@ -263,3 +305,61 @@ Contents:
263
305
  A CLI re-run deletes this file along with the old inventory, because its
264
306
  decisions were made against the previous staging; a decisions file found
265
307
  beside a fresh inventory therefore belongs to this inventory.
308
+
309
+ Write the file as soon as Step 0.4 is answered, then update it after each
310
+ later step, never only at the end. Its full shape:
311
+
312
+ ```json
313
+ {
314
+ "schemaVersion": 1,
315
+ "decidedAt": "2026-01-01T00:00:00Z",
316
+ "progress": { "lastCompletedStep": "step-0.4" },
317
+ "step0": {
318
+ "additions": ["<path>"],
319
+ "conflicts": [{ "path": "<path>", "resolution": "keep|take|merge" }],
320
+ "packs": ["<name>"],
321
+ "missedNotes": "<the user's free text, or empty>"
322
+ },
323
+ "interview": {
324
+ "kind": { "value": "library", "status": "confirmed", "fallback": null }
325
+ },
326
+ "agentsKept": ["Explore"],
327
+ "plugins": { "enabled": ["<id>"], "declined": ["<id>"] },
328
+ "round1": {
329
+ "installed": ["<path>"],
330
+ "dropped": [{ "path": "<path>", "reason": "<why>" }],
331
+ "mechanicallyRetargeted": ["<path>"]
332
+ },
333
+ "round2": {
334
+ "applied": ["<finding>"],
335
+ "deferred": [{ "finding": "<finding>", "reason": "<why>" }]
336
+ }
337
+ }
338
+ ```
339
+
340
+ - `progress.lastCompletedStep` is `step-0.4`, `step-1`, `step-3`,
341
+ `step-3-plugins`, `step-4` or `step-6`, set after that step finishes.
342
+ - `interview` holds one entry per Step 1 question. `status` is
343
+ `"confirmed"`, `"corrected"` or `"dismissed"`. A question the user
344
+ dismissed without answering is recorded as `"dismissed"` with the
345
+ default actually used in `fallback`, never as an answer. Step 7 lists it
346
+ under "Assumed, not answered".
347
+ - `agentsKept` and `plugins` are written when Step 1 and Round 1's plugin
348
+ question are answered.
349
+ - `round1.dropped` records every planned install Round 1 did not carry out
350
+ (a guard whose subject does not exist in this project, for instance) with
351
+ the reason. `round1.mechanicallyRetargeted` is Step 3's "needs a human
352
+ read" list.
353
+ - `round2` records each finding applied and each deferred. A finding that
354
+ changes how a hook behaves (making a guard fail closed, a new deny rule, a
355
+ widened matcher) is collected into one `AskUserQuestion` (apply or
356
+ defer), and the answer is recorded here. A deferred one also goes into
357
+ the tracker's pending remediation, so a later sweep does not re-decide it
358
+ silently.
359
+
360
+ **After a compaction or resume, read this file first and never re-ask a
361
+ decision whose entry is already recorded.** Resume at the step after
362
+ `progress.lastCompletedStep`, but always re-run Step 0.1's validity and
363
+ integrity checks first (they are cheap and idempotent), because the project
364
+ can change between sessions. Only a `"dismissed"` entry may be asked
365
+ again.
@@ -103,7 +103,11 @@ confirmed in Step 0.4:
103
103
  and the three statusline scripts (`statusline.mjs`, `statusline-layout.mjs`,
104
104
  `subagent-statusline.mjs`) and install the pack's other artifacts (the
105
105
  compaction-handoff hooks and `guard-readonly-bash`) normally, stating the
106
- skip plainly in Step 7;
106
+ skip plainly in Step 7. `guard-readonly-bash.mjs` imports
107
+ `bin/lib/agent-roster.mjs`: when the project keeps no agents and that file is
108
+ not being installed, skip that one hook too (the pack's `adoptNotes` allow
109
+ it), record it in `round1.dropped` and say in Step 7 that it was skipped and
110
+ why;
107
111
  `wiring.verifySteps` becomes a step in whatever this project's real gate
108
112
  runner is (a `package.json` script plus a line in its `lefthook.yml`/
109
113
  `.husky/pre-push`/CI workflow, written by hand to match its actual shape)
@@ -111,6 +115,29 @@ confirmed in Step 0.4:
111
115
  other artifacts and state plainly in Step 7 that the gate was not wired,
112
116
  rather than inventing a runner the project never asked for.
113
117
 
118
+ **Retarget what you installed (adopt mode).** A staged skill, agent, rule or
119
+ hook still speaks the baseline's tooling. For every one you install, rewrite
120
+ each package-manager command to the project's own (`survey.shape.packageManager`;
121
+ a `package.json` script of the same purpose wins over a guessed command) and
122
+ each path to the project's real source and test directories. A project with
123
+ no package manager and no `package.json` gets its real gate in place of the
124
+ command, or the command is removed and Step 7 says the project has none.
125
+ Class every file you touched as one of two:
126
+
127
+ - **Tailored**: you rewrote the prose to fit the project.
128
+ - **Mechanically retargeted**: only the commands and paths were swapped, so
129
+ the surrounding prose may still read oddly.
130
+
131
+ Record the mechanically retargeted files in `round1.mechanicallyRetargeted` and print it in
132
+ Step 7 under **Needs a human read**. Files under a guidance skill's
133
+ `references/` document upstream tools, so they keep their `pnpm` text: name
134
+ that exception in the report instead of editing them. Finally run each
135
+ retargeted gate command (`post-edit-verify`'s formatter, linter and type
136
+ check, for instance) once against the project's real files. When one cannot
137
+ run, because dependencies are not installed for example, report it as **not
138
+ exercised** with the reason, never as working. A planned install you drop for
139
+ any reason goes into `round1.dropped` with that reason.
140
+
114
141
  **Plugins (both modes), after packs are settled above.** Build a
115
142
  `PluginRecommendationContext`: `chosenPacks` is whatever the packs decision
116
143
  just above actually landed on (fresh: what `--pack` installed at bootstrap
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: code-implementer
3
3
  description: Writer spoke for the TDD build pipeline. Given a contract and a set of failing tests, writes the minimal src/** implementation to make those tests pass, then refactors while green. Use during the GREEN phase of TDD. It writes implementation only — it never writes tests and never reviews code.
4
- tools: Read, Write, Edit, Grep, Glob, Bash, mcp__context7__resolve-library-id, mcp__context7__query-docs
4
+ tools: Read, Write, Edit, Grep, Glob, Bash, mcp__context7__resolve-library-id, mcp__context7__query-docs, mcp__plugin_context7_context7__resolve-library-id, mcp__plugin_context7_context7__query-docs
5
5
  disallowedTools: Agent
6
6
  mcpServers: [context7]
7
7
  model: claude-opus-5-5
@@ -102,8 +102,11 @@ that to the hub rather than absorbing it silently.
102
102
 
103
103
  ## Consulting context7 for library behavioral semantics
104
104
 
105
- You hold a scoped grant to `mcp__context7__resolve-library-id` and
106
- `mcp__context7__query-docs`. Use them when you need a third-party
105
+ You hold a scoped grant to `resolve-library-id` and `query-docs` under both
106
+ names Claude Code can give the server: `mcp__context7__*` when context7 is a
107
+ project or user MCP server, and `mcp__plugin_context7_context7__*` when it
108
+ comes from the `context7` plugin (a plugin's server is namespaced
109
+ `plugin:<plugin>:<server>`). Use them when you need a third-party
107
110
  dependency's _behavioral_ semantics that a `.d.ts` file cannot express:
108
111
  retry/backoff behavior, terminal-state classification, pagination contracts,
109
112
  or which error a call throws under a specific condition. Resolve the library
@@ -26,6 +26,16 @@ contract (a documented behavior, an interface to satisfy):
26
26
  parallel over the diff. Must-fix findings route back to
27
27
  `code-implementer` and the loop repeats until clean.
28
28
 
29
+ **Spokes do not nest, and their `permissionMode` is not a safety property.**
30
+ Claude Code lets a subagent spawn its own, three layers deep by default
31
+ (`CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`); every spoke here sets
32
+ `disallowedTools: Agent`, which is what keeps the roster flat. A session in
33
+ auto, `acceptEdits` or `bypassPermissions` mode overrides a spoke's
34
+ `permissionMode` (the field applies only under `default`, `dontAsk` or
35
+ `plan`), so `acceptEdits` on the writer spokes is often inert. The PreToolUse
36
+ guards bound a spoke, not `permissionMode`. Source:
37
+ [sub-agents](https://code.claude.com/docs/en/sub-agents).
38
+
29
39
  ## Dispatch sizing
30
40
 
31
41
  - **Decompose before you dispatch.** Scale the dispatch to task complexity —
@@ -1,5 +1,8 @@
1
1
  {
2
2
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
3
+ "permissions": {
4
+ "deny": ["Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)"]
5
+ },
3
6
  "hooks": {
4
7
  "UserPromptSubmit": [
5
8
  {
@@ -29,6 +32,7 @@
29
32
  {
30
33
  "type": "command",
31
34
  "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-hub-src-writes.mjs\"",
35
+ "onFailure": "block",
32
36
  "timeout": 30
33
37
  }
34
38
  ]
@@ -49,21 +53,25 @@
49
53
  {
50
54
  "type": "command",
51
55
  "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-protected-paths.mjs\"",
56
+ "onFailure": "block",
52
57
  "timeout": 30
53
58
  },
54
59
  {
55
60
  "type": "command",
56
61
  "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-branch-isolation.mjs\"",
62
+ "onFailure": "block",
57
63
  "timeout": 30
58
64
  },
59
65
  {
60
66
  "type": "command",
61
67
  "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-hub-src-writes.mjs\"",
68
+ "onFailure": "block",
62
69
  "timeout": 30
63
70
  },
64
71
  {
65
72
  "type": "command",
66
73
  "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-secret-writes.mjs\"",
74
+ "onFailure": "block",
67
75
  "timeout": 30
68
76
  }
69
77
  ]
@@ -28,8 +28,10 @@ faster — and say in the answer that a full `refresh` sweep is available if
28
28
  the question turns out to implicate more than the one facet asked about.
29
29
 
30
30
  **Must only run in the main (hub) agent, never inside a subagent** — it ends
31
- in `EnterPlanMode` (refresh) or dispatches other agents (either mode), which
32
- a subagent cannot do (`disallowedTools: Agent`).
31
+ in `EnterPlanMode` (refresh) or dispatches other agents (either mode), which a
32
+ spoke cannot do: every spoke sets `disallowedTools: Agent`, and Claude Code otherwise
33
+ lets a subagent spawn its own, three layers deep by default
34
+ (`CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`).
33
35
 
34
36
  **No files are written by this skill itself** in research mode by default;
35
37
  refresh mode writes to exactly one file, the tracker, in Step 5.
@@ -96,7 +98,11 @@ concern) — every other facet below is identical regardless of project kind.
96
98
  `<scratchpad>/harness-refresh-<date>/`.
97
99
  2. **Build the delta.** `WebFetch` the Claude Code CHANGELOG, extract
98
100
  entries newer than the recorded version. An unreachable source is a
99
- coverage gap, not a blocker. Pass this delta into all five briefs below
101
+ coverage gap, not a blocker. With an `unset` tracker there is no recorded
102
+ version to start from, so the delta has no lower bound: read as far back as
103
+ the fetch returns, and write the oldest version you actually read into the
104
+ tracker as a coverage note (`changelog read back to <version>`), never
105
+ implying full coverage of anything older. Pass this delta into all five briefs below
100
106
  — it is not a sixth facet.
101
107
  3. **Fan out five fixed facets in one message** — fixed, not derived per
102
108
  run, so sweeps stay comparable and the tracker stays diffable:
@@ -40,7 +40,8 @@ than the one facet asked about.
40
40
  **Must only run in the main (hub) agent, never inside a subagent** — it ends
41
41
  in `EnterPlanMode` (refresh) or an `AskUserQuestion` (research or refresh,
42
42
  occasionally), and every mode launches parallel `Explore` research agents,
43
- none of which a subagent can do (`disallowedTools: Agent` on every spoke).
43
+ none of which a spoke can do (`disallowedTools: Agent` on every spoke; Claude Code
44
+ otherwise allows nesting three layers deep, `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`).
44
45
 
45
46
  **No files are written by this skill itself** in research mode by default;
46
47
  refresh mode writes to exactly one file, the tracker, in Step 5; `gaps` mode
@@ -120,6 +121,15 @@ conflict-resolution machinery for an existing value.
120
121
  check against, not restate. Missing tracker/facet → first run, `NEW`
121
122
  only. Then read the allowlist file; state today's date; derive a run
122
123
  directory `<scratchpad>/ts-refresh-<date>/`.
124
+
125
+ **A project with no TypeScript toolchain gets no sweep.** When the project
126
+ has no `typescript` entry in `dependencies` or `devDependencies` and no
127
+ `tsconfig*.json`, say so, write nothing else, and set the tracker header to
128
+ `last-verified=n/a typescript-version=n/a reason=no-typescript-toolchain`.
129
+ `unset` means "not run yet" and invites a first sweep; `n/a` says there is
130
+ nothing to sweep. A later run re-checks the condition before honouring `n/a`:
131
+ once a TypeScript toolchain appears, treat the tracker as a first run.
132
+
123
133
  2. **Build the delta.** `WebFetch` the devblog index and
124
134
  `github.com/microsoft/TypeScript/releases`; extract entries newer than
125
135
  the recorded version. An unreachable source is a coverage gap, not a
@@ -29,6 +29,16 @@ Plus **the official docs of a tool the project's interview actually
29
29
  selected** for bundling, if one was chosen and isn't already covered above
30
30
  (a specific bundler's own docs).
31
31
 
32
+ Plus **the official docs of any test runner, linter, formatter or type-test
33
+ tool the project itself lists under `devDependencies`** that isn't covered
34
+ above (`ava`, `xo`, Playwright and `expect-type` are the cases that prompted
35
+ this). That tool's own documentation is owner-normative **for that tool
36
+ only**: take its domain from the `homepage` field of its installed
37
+ `package.json` (no network needed), never from a search result, pass it as one
38
+ extra `allowed_domains` entry for that area, and record it in the tracker's
39
+ Sources. A tool with no installed `homepage`, or one hosted on a general
40
+ code-hosting or blogging domain, stays a coverage gap rather than a source.
41
+
32
42
  One of the fixed domains is **path-scoped within a domain
33
43
  `typescript-guidance` also uses, for a different path**:
34
44
 
@@ -131,6 +131,30 @@ one. Check `/plugin` for installed mods alongside `/status`.
131
131
  writer spoke only with both present, so a call carrying `agent_type` but no
132
132
  `agent_id` is treated as the hub and is blocked.
133
133
 
134
+ **Four guards block when they crash, and a secrets deny rule ships in
135
+ `settings.json`.** `guard-secret-writes`, `guard-hub-src-writes`,
136
+ `guard-branch-isolation` and `guard-protected-paths` carry
137
+ `"onFailure": "block"` (Claude Code 2.1.295 or later). By default a hook that
138
+ crashes or times out lets the call through; with this key it is blocked. It
139
+ applies only to a failure the hook does not handle itself: each guard still
140
+ catches bad input and exits 0 on purpose, so the key covers a load error, a
141
+ missing `node` or the 30-second timeout. Because `guard-hub-src-writes` is also
142
+ registered on `Bash`, a missing `node` or a timed-out scan blocks every `Bash`
143
+ call until it is fixed (run the command yourself with the `!` prefix to get
144
+ past it). The style guards and `guard-git-push-signed` stay fail-open on
145
+ purpose: the push guard has its own command parser and the remote's
146
+ signed-commit rule is the authoritative layer. `permissions.deny` blocks
147
+ `Read(./.env)`, `Read(./.env.*)` and `Read(./secrets/**)`, which also covers
148
+ `cat`, `head` and `tail` on those files in `Bash`. It does not cover `grep -r`
149
+ or a script that opens the file itself, and nothing else in this baseline does.
150
+
151
+ **A spoke's `permissionMode` can be overridden.** A session in auto,
152
+ `acceptEdits` or `bypassPermissions` mode overrides a spoke's `permissionMode`
153
+ (the field applies only when the session is in `default`, `dontAsk` or
154
+ `plan`), so treat the hooks, not `permissionMode`, as what bounds a spoke.
155
+ Claude Code also lets a subagent spawn subagents three layers deep by default;
156
+ `disallowedTools: Agent` on every spoke is what keeps this roster flat.
157
+
134
158
  Full dispatch-sizing and recovery guidance: `.claude/rules/agent-dispatch.md`
135
159
  (auto-loads when editing `.claude/skills/**` or `.claude/agents/**`).
136
160