@monte3l/groundwork 0.1.0-next.1 → 1.0.0-rc.3

package/plugin/skills/customize/SKILL.md

@@ -53,9 +53,173 @@ may or may not touch.
 
 ## Step 0 — Reconcile (adopt mode only)
 
-1. Look for `.groundwork/inventory.json`. **Absent → this is a fresh
-   bootstrap; skip straight to Step 1.** Everything below this step applies
-   only when it exists.
+1. Look for `.groundwork/inventory.json`.
+   - **Absent, and no `.groundwork/` directory either → this is a fresh
+     bootstrap; skip straight to Step 1.** Everything below this step applies
+     only when an inventory exists.
+   - **Absent, but `.groundwork/` exists → a previous CLI adopt run did not
+     complete** (the CLI deletes the old inventory before it stages anything
+     and writes the new one last, so no inventory beside a `.groundwork/`
+     directory means the run died part-way). **Stop. Never fall through to
+     the fresh flow** -- that would run fresh-mode tailoring on an
+     established project. Tell the user: "`.groundwork/` is incomplete: a
+     previous adopt run did not finish, or `inventory.json` was removed.
+     If this project was never adopted (it was bootstrapped fresh), delete
+     `.groundwork/` and run `/customize` again. Otherwise re-run
+     `npx @monte3l/groundwork@rc .` and then run `/customize` again."
+     Change nothing.
+   - **Present, but not valid JSON, or its `schemaVersion` is not an integer
+     of at least 1 → stop and change nothing.** Tell the user: "`.groundwork/inventory.json`
+     is not valid JSON or has no usable `schemaVersion`. Re-run
+     `npx @monte3l/groundwork@rc .` and then run `/customize` again."
+
+   **Check `inventory.schemaVersion` before reading anything else.** This
+   skill understands schema versions **1 through 5** (the highest it knows is
+   5). If `schemaVersion` is **higher than 5**, the CLI that wrote it is newer
+   than this plugin: **stop and change nothing**, do not interpret the
+   inventory (a newer schema may have renamed or repurposed fields, and a
+   confident misreading is worse than none), and tell the user to update the
+   plugin and re-run `/customize`. Say which update applies to the copy
+   that is running. For the plugin install, run `/plugin update`. For a
+   project-local copy in `.claude/skills/customize/`, `/plugin update` does
+   not touch it, and re-running the CLI alone does not either: the CLI
+   never overwrites a copy that differs (nor removes any other entry the
+   project owns there, nor writes through a symlinked `.claude`), it writes a
+   fresh one to `.groundwork/customize/`, which Claude Code does not load. So delete
+   that directory first (this discards any local edits the project made to
+   its copy) and then re-run `npx @monte3l/groundwork@rc .`. A
+   copy in `.groundwork/customize/` is refreshed by re-running the CLI. What
+   each version added:
+
+   | `schemaVersion` | Adds                                                                                                                                                                                                                                                                                                                      | If absent                                                                                                                        |
+   | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+   | 1               | the survey, `conflicts`                                                                                                                                                                                                                                                                                                   | (the floor)                                                                                                                      |
+   | 2               | `packs`                                                                                                                                                                                                                                                                                                                   | no packs to offer; skip the pack question                                                                                        |
+   | 3               | `harnessGrade`, `harnessConformance`                                                                                                                                                                                                                                                                                      | skip the harness-grade starting point                                                                                            |
+   | 4               | `toolchainGrade`, `toolchainConformance`                                                                                                                                                                                                                                                                                  | skip the toolchain-grade starting point                                                                                          |
+   | 5               | `stagedBaseline` (`{ dir, suffix, files }`): the baseline additions staged at `.groundwork/baseline/`, each as `{ path, staged, sha256 }`; `stagedPacks` (per pack: `{ name, dir, suffix, manifest, files }`): every pack staged at `.groundwork/packs/<name>/`, its manifest and each file as `{ path, staged, sha256 }` | schema 1-4 only: read baseline additions from `inventory.templateRoot`; packs use the unsuffixed copy under `.groundwork/packs/` |
+
+   **For a schema 5 inventory only: verify the staged baseline now, before
+   anything is offered to the user.** A schema 1-4 inventory has no
+   `stagedBaseline`: skip this whole block (every bullet below, including
+   its stop list) and use the `inventory.templateRoot` fallback in Round 1.
+   The inventory lives in the project tree and is untrusted input, so check
+   it before trusting any entry:
+
+   - `stagedBaseline.dir` must equal `.groundwork/baseline` exactly, and
+     `stagedBaseline.suffix` must equal `.staged` exactly. Take both values
+     from this list, not from the inventory: a `dir` of `.` with an empty
+     `suffix` would make you "verify" live project files.
+   - For every entry of `inventory.stagedBaseline.files`, require
+     `staged === path + ".staged"`, and require `path` to be relative, free
+     of any `..` segment, and not absolute. Reject the entry if `path` is
+     `""` or `"."`. Reject it too if `path` contains a `\` or a `:` (a
+     Windows `..\..` or `C:foo` would slip past the other checks). Reject a
+     duplicate `path` or a duplicate `staged` among the entries. These fields
+     use `/` separators on every platform: `conflicts[].relPath`,
+     `packs[].fileConflicts[].relPath`, `stagedBaseline.dir`,
+     `stagedBaseline.files[].path` and its `.staged` name, `stagedPacks[].dir`,
+     `stagedPacks[].files[].path` and `stagedPacks[].files[].staged`. Other paths in
+     the inventory are not normalized: `templateRoot` and `targetDir` are
+     absolute native paths, as are the survey's tsconfig chain entries.
+   - The `absent` conflicts in `inventory.conflicts` and the paths in
+     `stagedBaseline.files` must name the same set of files. If they
+     disagree (an `absent` conflict with no staged entry, or a staged entry
+     that is not an `absent` conflict), that is a mismatch: stop, with the
+     same message as a hash mismatch, before anything is offered or approved.
+   - Read each staged file at `.groundwork/baseline/<staged>` **once**.
+     It must exist, and the SHA-256 of its **raw bytes** (no end-of-line
+     normalization, no decoding) must equal the entry's `sha256`. Compute it
+     with, for example, this one-liner (it targets a POSIX shell or Git Bash,
+     not `cmd.exe` or an old PowerShell), passing the file as a single quoted
+     argument in place of `<file>`:
+     `node -e 'process.stdout.write(require("crypto").createHash("sha256").update(require("fs").readFileSync(process.argv[1])).digest("hex"))' <file>`
+     Keep those same bytes for the install in Round 1 (substitute tokens into
+     them) rather than reading the file a second time.
+   - **Staged packs, in the same block.** For every entry of
+     `inventory.stagedPacks`:
+     - `dir` must equal `.groundwork/packs/<name>`, built from the entry's
+       own `name`, and `suffix` must equal `.staged`. Take both from this
+       list, not from the inventory.
+     - `name` must be a single path segment: not empty, not `.` or `..`, and
+       free of `/`, `\` and `:`. Reject a duplicate pack `name`.
+     - `manifest.path` must equal `pack.json` and `manifest.staged` must
+       equal `pack.json.staged`.
+     - For every entry of its `files`, require `staged === path + ".staged"`,
+       and apply the same path checks as the staged baseline's files above
+       (relative, no `..` segment, not absolute, not `""` or `"."`, no `\` or
+       `:`). Reject a duplicate `path` or a duplicate `staged` among one
+       pack's files.
+     - The pack names in `inventory.packs` and in `inventory.stagedPacks`
+       must be the same set, and for each pack its `fileConflicts[].relPath`
+       set must equal its `files[].path` set.
+     - Read the staged manifest at `<dir>/pack.json.staged` and each staged
+       file at `<dir>/files/<staged>` once, and apply the SHA-256 check above
+       to the raw bytes of each. Keep the bytes Step 0.1 read (hash-checked
+       when a command could run): Round 1's install and the prototype-key
+       check in Step 0.4(c) use them, with no second read.
+   - **No shell tool available.** If a Bash or other command-running tool is
+     available, compute the hash as above. If you cannot run a command, do
+     not work around it: write no scratch script; while verifying, make no
+     `Write` or `Edit` outside `.groundwork/` (Round 1's confirmed installs are
+     not part of verification), dispatch no subagent to look for a shell, and
+     search for a command tool at most once. Skip only the SHA-256
+     comparison. Run every other check in this block with the file tools
+     (`Read`, `Glob`, `Grep`): the files exist, `staged === path + ".staged"`,
+     the paths are relative with no `..`, `\` or `:`, no duplicates, `dir`
+     and `suffix` exact, the `absent` conflicts and `stagedBaseline.files`
+     name the same set, and no extra staged file exists: list the staged
+     files with the `Glob` pattern `.groundwork/baseline/**/*.staged` and
+     compare with `stagedBaseline.files`. A `Glob` can skip hidden paths
+     (most staged files are dot-paths), honour an ignore file or truncate a
+     long list, so a result shorter than `stagedBaseline.files.length`, or
+     that looks truncated, is undetermined: report it in the Step 0.4 summary
+     and continue, since every listed entry's existence is already checked
+     one by one; only an extra `*.staged` file, one whose path is not in
+     `stagedBaseline.files`, stops the run. Run the same structural checks
+     for `inventory.stagedPacks`: each pack's `<dir>/pack.json.staged` and
+     every `<dir>/files/<staged>` exists, `staged === path + ".staged"` with
+     paths that are relative and free of `..`, `\` and `:`, no duplicates,
+     `name`, `dir`, `suffix`, `manifest.path` and `manifest.staged` exact,
+     the pack names in `inventory.packs` and `inventory.stagedPacks` the
+     same set, and each pack's `fileConflicts[].relPath` and `files[].path`
+     the same set. List each pack's staged files with the `Glob` pattern
+     `.groundwork/packs/**/*.staged` (the same hidden-path and
+     truncation caveats apply) and compare with every listed manifest and
+     file: an extra `*.staged` file at any depth under `.groundwork/packs/` that is neither a listed manifest nor a listed file stops the run. This is a partial no-shell
+     substitute for what the hash proves, and it is not tamper-resistance.
+     Then spend no further turns on verification and go on to the deep
+     read. State this plainly at the top of your first message to the user (the Step 0.4 summary, not a
+     separate earlier stop), and ask whether to continue or stop in that
+     same confirmation: the SHA-256 check was skipped because no command
+     could be run; a passing check would only have proven that the staging
+     is complete and matches the inventory, not that the files are
+     untampered; and which structural checks you did verify instead. Also
+     record the skip in `.groundwork/adoption-report.md` when you write the
+     findings back in Step 0.3. A structural failure, including an extra staged file, still stops, exactly as the stop list below says.
+   - An empty `files` list is legitimate (nothing was missing from the
+     project) and creates no `.groundwork/baseline/` directory; that alone is
+     not a failure.
+   - **For a schema 5 inventory, a `stagedBaseline` that is missing, not an
+     object, or whose `files` is not an array also stops the run** (a
+     `files: {}` is not an empty list); so does a `stagedPacks` that is
+     missing or not an array, or a pack entry that is not an object or whose
+     `files` is not an array. **Any invalid entry, missing file or hash mismatch (including a
+     wrong `dir` or `suffix`), any duplicate `staged` or `path` or pack `name`, any
+     `absent` conflicts and `stagedBaseline.files` that do not name the same
+     set, any pack whose names or file paths disagree with `inventory.packs`, and
+     (no-shell path) an extra `*.staged` file not named in
+     `stagedBaseline.files`, a pack's `files` or a pack's manifest
+     means stop -- all of Round 1, including conflicts and packs -- and
+     change nothing.** This is the single stop list for the staged baseline and the staged packs.
+     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 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).
+   - What a passing check proves: the staging is complete and matches the
+     inventory. It does **not** prove the files are untampered -- anyone who
+     can edit the staged files can edit the inventory's hashes too.
+
+   An inventory with `schemaVersion` below 5 has no staged copy; its
+   approved additions are read from `inventory.templateRoot` (see Round 1).
+
 2. **The deep read.** The CLI's survey is an index, not an interpretation —
    it flagged what it found but could not parse (`needsReading: true` on
    git-hook config, workflow files; anything in `survey.undetermined`) and
@@ -95,7 +259,9 @@ may or may not touch.
 3. **Write the findings back** into `.groundwork/adoption-report.md`,
    replacing the CLI's index-level sections ("a `lefthook.yml` exists")
    with semantic ones ("pre-push runs lint and typecheck; tests do not
-   gate").
+   gate"). If the no-shell bullet in step 1 applied, carry its skip note
+   into the rewritten report: this step replaces the report's sections, so
+   a note written earlier would be dropped.
 4. **Confirm.** Give a short summary in chat, then ask **one**
    `AskUserQuestion` covering: (a) _did this miss anything about your
    project?_ — the free-text option is the point of this question, not a
@@ -114,8 +280,26 @@ may or may not touch.
    dropped. This is index-level evidence from the CLI, not a kind-based
    judgment — see Step 3's note on revisiting it once the interview confirms
    the project's kind.
+
+   The same question also carries (d) if the no-shell bullet applied: say the
+   SHA-256 check was skipped, what a passing check would have proven,
+   which checks ran instead and any undetermined result, and
+   ask whether to continue or stop.
+
+   Before offering any pack, check each staged `.groundwork/packs/<name>/pack.json.staged` (the bytes Step 0.1 read, hash-checked when a command could run; not a fresh read):
+   if `__proto__`, `constructor` or `prototype` is a key of its `wiring.settings`
+   (hook event names), `wiring.settingsTopLevel` or `wiring.packageScripts`
+   (script names), stop. The project tree is untrusted, and the CLI refuses such a
+   pack before staging it, so a staged manifest carrying one was edited after
+   staging. Name the pack, the field and the key, tell the user to delete
+   `.groundwork/` and re-run the CLI, and offer nothing from this run. Change nothing.
+   For a schema 1-4 inventory (the layout of the CLI releases before the `.staged` convention) there is no `.staged` copy and no hash: read the unsuffixed `.groundwork/packs/<name>/pack.json` (not hash-verified) and run this same prototype-key check on it.
+
 5. **Record the confirmed decisions** to `.groundwork/adoption-decisions.json`
    so a compacted or resumed session doesn't silently lose them and re-ask.
+   A CLI re-run deletes this file along with the old inventory, because its
+   decisions were made against the previous staging; a decisions file found
+   beside a fresh inventory therefore belongs to this inventory.
 
 ## Step 1 — Interview
 
@@ -206,25 +390,53 @@ CI, husky locally, whatever it is), not to `lefthook.yml`/`ci.yml` by name.
 Concretely, adopt-mode Round 1 applies exactly three things, all already
 confirmed in Step 0.4:
 
-- The **approved additions** — files `templates/core` (at
-  `inventory.templateRoot`) would add that the project doesn't have and the
-  user approved adding.
+- The **approved additions** — files `templates/core` would add that the
+  project doesn't have and the user approved adding. For a schema 5 inventory, install them from the staged copy Step 0.1 already verified,
+  using the bytes you read then (Step 0.1 also already checked that the
+  staged files match the `absent` conflicts). Write them to the project at `path` (the
+  `.staged` suffix stripped, never to the staged name), filling in the
+  `__KEY__` tokens with the project's real values as you copy, same as
+  staged packs. Only a **schema 1-4** inventory has no staged copy and reads
+  additions from `inventory.templateRoot`; if that path no longer exists (a
+  pruned `npx` cache, a deleted temp checkout), say so and ask for a CLI
+  re-run rather than guessing at the baseline's contents.
 - The **approved conflict resolutions** — for each divergent file the user
   decided on, apply that decision (keep theirs / take groundwork's / merge
   the named keys).
 - The **approved packs** — installed from `.groundwork/packs/<name>/` (the
-  CLI's staged, self-contained copy — never `inventory.templateRoot`, which
-  may not exist by the time this runs). Before installing, call
+  CLI's staged, self-contained copy of inert `.staged` files — never
+  `inventory.templateRoot`, which may not exist by the time this runs). Before installing, call
   `recommendPacks(answers)` from `pack-map.ts` (alongside this file, same
   copy mechanism as `kind-facet-map.ts`) with the now-confirmed
-  `InterviewAnswers` and compare its verdict against Step 0.4's decision. For
-  both shipped packs this never disagrees (neither recommendation varies by
-  kind), but a future kind-scoped pack might — if it does, surface the
-  conflict rather than silently overriding the user's Step 0.4 answer,
-  mirroring Step 4's "the one exception" rule for guidance findings. To
-  install: copy `.groundwork/packs/<name>/files/` into the project (respecting
-  any approved per-file conflict decision the same way the baseline's own
-  additions are applied), then translate `pack.json`'s `wiring` by hand
+  `InterviewAnswers` and compare its verdict against Step 0.4's decision.
+  `harness-extras`, `github`, `supply-chain`, `quality`, and `worktrees`
+  never disagree (none of the five's recommendation varies by kind or
+  answer -- `worktrees` is always `recommended: false`, since it changes the
+  day-to-day workflow rather than adding a nicety, and the other four are
+  always `recommended: true`), but `publishing`'s does (recommended for
+  `library`/`cli`, not for `frontend`/`service`) — if the comparison surfaces a real
+  conflict there or for any future kind-scoped pack, raise it rather than
+  silently overriding the user's Step 0.4 answer, mirroring Step 4's "the
+  one exception" rule for guidance findings. Before installing, check the
+  pack's own `modes`: a pack whose `modes` doesn't include `"adopt"` (today,
+  `publishing` — its release flow encodes decisions too project-specific to
+  apply blind) is never auto-installed here even if staged and approved;
+  instead, state in Step 6 that it needs a manual install (point at `.groundwork/packs/<name>/` and the pack's own `adoptNotes`, and say to strip the `.staged` suffix from every name when copying by hand and to replace every `__KEY__` token with the project's real value) and stop
+  there for that pack. Before merging any staged `pack.json.staged` wiring, repeat
+  the prototype-key check from Step 0.4(c): if a key of `wiring.settings`,
+  `wiring.settingsTopLevel` or `wiring.packageScripts` is `__proto__`,
+  `constructor` or `prototype`, stop the same way and change nothing. For an
+  adopt-capable pack, install each file from
+  `.groundwork/packs/<name>/files/<path>.staged`, using the bytes Step 0.1 read (hash-checked when a command could run), and write it to the project at `path` (the `.staged` suffix
+  stripped, never to the staged name), filling in the `__KEY__` tokens with
+  the project's real values as you copy (respecting any approved per-file
+  conflict decision the same way the baseline's own additions are applied).
+  For a schema 1-4 inventory, install each file from the unsuffixed
+  `.groundwork/packs/<name>/files/<path>` instead (no `.staged` suffix to strip,
+  not hash-verified; token substitution still applies).
+  Then, for either schema, translate `pack.json`'s `wiring` by hand, reading it
+  from `pack.json.staged` (the bytes Step 0.1 read) for a schema 5 inventory and
+  from the unsuffixed `pack.json` for schema 1-4,
   against what Step 0.2's deep read already found — a `.claude/settings.json`
   hook fragment merges the same way the baseline's own hook entries would;
   `wiring.settingsTopLevel` is a set of top-level keys (e.g. `statusLine`)
@@ -233,7 +445,13 @@ confirmed in Step 0.4:
   `mergeSettingsTopLevel` treats a differing value as a hard error and this
   hand-applied path must not be laxer than the automated one (also check
   `.claude/settings.local.json` and the user's `~/.claude/settings.json`,
-  either of which can shadow a project `statusLine`);
+  either of which can shadow a project `statusLine`). For `harness-extras`
+  specifically, a `statusLine`/`subagentStatusLine` collision is never a
+  reason to fail the whole pack install: skip just those two settings keys
+  and the three statusline scripts (`statusline.mjs`, `statusline-layout.mjs`,
+  `subagent-statusline.mjs`) and install the pack's other artifacts (the
+  compaction-handoff hooks and `guard-readonly-bash`) normally, stating the
+  skip plainly in Step 6;
   `wiring.verifySteps` becomes a step in whatever this project's real gate
   runner is (a `package.json` script plus a line in its `lefthook.yml`/
   `.husky/pre-push`/CI workflow, written by hand to match its actual shape)
@@ -241,6 +459,49 @@ confirmed in Step 0.4:
   other artifacts and state plainly in Step 6 that the gate was not wired,
   rather than inventing a runner the project never asked for.
 
+**Plugins (both modes), after packs are settled above.** Build a
+`PluginRecommendationContext`: `chosenPacks` is whatever the packs decision
+just above actually landed on (fresh: what `--pack` installed at bootstrap
+time, detectable from the installed files -- e.g. `.changeset/config.json`
+means `publishing`, `.github/workflows/claude-pr-review.yml` means `github`
+(the only marker `plugin-map.ts` actually reads; `harness-extras` has no
+plugin that varies by its presence, so it needs no marker here); adopt: the
+packs Step 0.4(c) confirmed, revised by this step's own `recommendPacks`
+comparison if it changed anything); `hasCustomSkills` is `false` for a fresh
+bootstrap (nothing has authored a skill yet) and, for adopt mode, whatever
+Step 0's survey found beyond the baseline's own known skill names and any
+already-installed pack's skills (e.g. the `github` pack's three). Call
+`recommendPlugins(answers, context)` from `plugin-map.ts`
+(alongside this file, same copy mechanism as `pack-map.ts`) with the
+now-confirmed `InterviewAnswers`, and ask **one** `AskUserQuestion`
+(multi-select) offering all seven, pre-selected per each entry's
+`recommended` boolean with its `because` shown as the evidence -- same
+"visible reasoning" principle as every other inference in this skill.
+
+Write every confirmed `true` entry into `.claude/settings.json`'s
+`enabledPlugins` (`{"<id>": true}` per entry, e.g.
+`"context7@claude-plugins-official": true`) -- additive and entry-by-entry,
+same discipline as the CLI's own `mergeSettingsHooks` (which owns the
+`hooks` block entry-by-entry, as opposed to `mergeSettingsTopLevel`'s
+whole-key-at-a-time semantics): never remove or flip an entry the project
+already sets explicitly (an existing `false` is a decision the user made,
+not an oversight to correct), and never touch `.claude/settings.local.json`
+or the user's own `~/.claude/settings.json` scope. `claude-plugins-official`
+is a built-in marketplace, so no `extraKnownMarketplaces` entry is needed
+for any of the seven.
+
+**Committing this entry does not install the plugin for anyone.** A
+project-scope `enabledPlugins: true` with no local install produces no
+folder-trust auto-prompt -- Claude Code's `/plugin` Errors tab instead shows
+"enabled in project settings but isn't installed here" until someone runs
+the install by hand. So for every newly-`true` entry, print the exact
+follow-up command in Step 6's report: `claude plugin install <id> --scope
+project` (or `/plugin install <id>` inside a running session) -- the user,
+and every collaborator who pulls this change, still has to run it once. Do
+the same for each recommendation's `prerequisites` (the
+`typescript-language-server` binary, Python 3.8+) -- print them as
+follow-ups, never attempt to install them.
+
 Nothing else is touched. A project file the user didn't approve a change to
 stays exactly as it was.
 
@@ -263,6 +524,12 @@ Step 2's plan to decide which facet gets the deepest attention this run,
 not which facets it's allowed to touch — and enters plan mode with a
 remediation plan if it finds drift.
 
+Also offer `typescript-guidance`'s `gaps` mode here, for gaps rather than
+drift — what TypeScript-ecosystem tooling the project is missing entirely, as
+opposed to either sweep's "is what's already configured still current." It
+is not a third mandatory sweep: run it only if the user wants a tooling-gap
+pass alongside the two refreshes.
+
 **In adopt mode**, a sweep's domain is the project's real files, classified
 by `domain-map.ts`'s `classifyPath` (the same module and glob lists that
 guard the emitted baseline — broadened to cover common non-baseline
@@ -303,3 +570,10 @@ the CLI's report missed (if anything), which conflicts were resolved and
 how, any domain-map coverage gap Step 4 surfaced, and **which packs were
 installed and what each wired** (or, for a pack whose gate had no runner to
 attach to, that it was skipped and why).
+
+Also list **which plugins were enabled** (each newly-`true`
+`enabledPlugins` entry, with the exact `claude plugin install <id> --scope
+project` follow-up command it still needs) and which were offered but
+declined, plus any prerequisite named against an enabled plugin
+(`typescript-language-server` on `PATH`, Python 3.8+) as a follow-up the
+user still has to satisfy.

package/plugin/src/domain-map.ts

@@ -1,13 +1,26 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
+
 /**
- * Which files each guidance sweep is responsible for. Used two ways:
- * against the emitted baseline, to confirm neither sweep has a blind spot
- * in `templates/core` before reporting a clean run (unit-tested directly
- * against the real tree in `tests/domain-map.test.ts`, so a new template
- * file added later can't silently fall outside both domains without a test
- * noticing); and in adopt mode, to classify a real pre-existing project's
- * files, which is why the glob lists also cover common non-baseline
- * equivalents (`.eslintrc.*`, `jest.config.*`, `.husky/**`, ...) alongside
- * the baseline's own exact filenames.
+ * Which files each guidance sweep is responsible for. A "guidance sweep" is
+ * the live research pass `/customize` runs over official upstream sources for
+ * one domain: `typescript-guidance` sweeps the TypeScript toolchain against
+ * official TypeScript sources, and `harness-guidance` sweeps the Claude Code
+ * harness against official Anthropic sources. Each sweep covers a fixed set of
+ * "facets" (research topics within its domain, such as `compiler-config-flags`
+ * or `hooks-lifecycle`); the interview's project "kind" (a `ProjectKind`: the
+ * archetype -- library, cli, frontend or service -- the project is classified
+ * as) only changes which facets get the most emphasis, never which files a
+ * sweep owns. This module answers the file-ownership question.
+ *
+ * Used two ways: against the emitted baseline, to confirm neither sweep has a
+ * blind spot in `templates/core` before reporting a clean run (unit-tested
+ * directly against the real tree in `tests/domain-map.test.ts`, so a new
+ * template file added later can't silently fall outside both domains without
+ * a test noticing); and in adopt mode, to classify a real pre-existing
+ * project's files, which is why the glob lists also cover common
+ * non-baseline equivalents (`.eslintrc.*`, `jest.config.*`, `.husky/**`,
+ * ...) alongside the baseline's own exact filenames.
  */
 
 /** Simple glob support: `**` matches any sequence (including `/`), `*` matches within a segment. */
@@ -28,7 +41,7 @@ export function matchesAnyGlob(
   return globs.some((glob) => globToRegExp(glob).test(path));
 }
 
-/** Every TypeScript-facing file `typescript-guidance` is responsible for. */
+/** Every TypeScript-facing file the `typescript-guidance` sweep is responsible for. */
 export const TYPESCRIPT_DOMAIN_GLOBS = [
   "tsconfig*.json",
   "**/tsconfig*.json",
@@ -60,6 +73,11 @@ export const TYPESCRIPT_DOMAIN_GLOBS = [
   "bin/lib/*.mjs",
   "bin/lib/*.json",
   ".github/workflows/*.yml",
+  ".github/dependabot.yml",
+  ".github/release-tools/**",
+  ".changeset/**",
+  ".gitleaks.toml",
+  "REUSE.toml",
   "docs/research/typescript-refresh.md",
   "src/**",
   "tests/**",
@@ -69,16 +87,22 @@ export const TYPESCRIPT_DOMAIN_GLOBS = [
  * Harness-grader files that live under `bin/`. `bin/*.mjs` and
  * `bin/lib/*.mjs` are typescript-domain globs, so without this list the
  * grader's own rules would be swept by `typescript-guidance` -- wrong,
- * because they encode Claude Code harness guidance. Consulted before the
- * typescript list in `classifyPath`.
+ * because they encode Claude Code harness guidance. The Claude Code Action
+ * workflows (`claude.yml`, and the `github` pack's automated-review
+ * `claude-pr-review.yml`) are here for the same reason against
+ * `.github/workflows/*.yml`: their trigger, action pin and model choice are
+ * Anthropic guidance, not toolchain. Consulted before the typescript list in
+ * `classifyPath`.
  */
 export const HARNESS_OVERRIDE_GLOBS = [
   "bin/check-harness.mjs",
   "bin/lib/harness-rules.mjs",
   "bin/lib/frontmatter.mjs",
+  ".github/workflows/claude.yml",
+  ".github/workflows/claude-pr-review.yml",
 ] as const;
 
-/** Every `.claude/`-facing file `harness-guidance` is responsible for. */
+/** Every `.claude/`-facing file the `harness-guidance` sweep is responsible for. */
 export const HARNESS_DOMAIN_GLOBS = [
   ".claude/settings.json",
   ".claude/settings.local.json",
@@ -90,11 +114,12 @@ export const HARNESS_DOMAIN_GLOBS = [
   ".claude/commands/**",
   ".claude-plugin/**",
   ".mcp.json",
+  ".worktreeinclude",
   "CLAUDE.md",
   "docs/research/harness-refresh.md",
 ] as const;
 
-/** Files neither sweep governs by design -- not a gap, an explicit exclusion. */
+/** Files neither guidance sweep governs by design -- not a gap, an explicit exclusion. */
 export const NEUTRAL_GLOBS = [
   "README.md",
   ".gitignore",

package/plugin/src/index.ts

@@ -1,4 +1,8 @@
-/** Public surface of `@m3l-groundwork/plugin`: the /customize skill's deterministic backing data. */
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
+
+/** Public surface of `@monte3l/groundwork-plugin`: the /customize skill's deterministic backing data. */
 export * from "./kind-facet-map.js";
 export * from "./domain-map.js";
 export * from "./pack-map.js";
+export * from "./plugin-map.js";

package/plugin/src/kind-facet-map.ts

@@ -1,14 +1,31 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
+
 /**
- * The kind-to-facet table `/customize` reads to plan its guidance-pass
- * research priority. A stored, unit-tested module -- not a judgment made
- * afresh each run -- so the same interview answers always produce the same
- * facet plan.
+ * The kind-to-facet table `/customize` reads to plan its guidance-sweep
+ * research priority. Three terms recur throughout this file:
+ *
+ * - A "kind" is a `ProjectKind`: the project archetype the interview
+ *   classifies the project as (library, cli, frontend or service).
+ * - A "guidance sweep" is the live research pass `/customize` runs over
+ *   official TypeScript and Anthropic sources, once per domain (TypeScript
+ *   toolchain, Claude Code harness).
+ * - A "facet" is one fixed research topic within a domain -- for example
+ *   `compiler-config-flags` is a TypeScript facet and `hooks-lifecycle` is a
+ *   harness facet. A guidance sweep always covers every facet of its domain,
+ *   whether or not the interview emphasized it.
+ *
+ * This table is a stored, unit-tested module -- not a judgment made afresh
+ * each run -- so the same interview answers always produce the same facet
+ * plan.
  *
- * Scope note (load-bearing): this table scopes research PRIORITY only. Both
- * guidance skills (templates/core/.claude/skills/typescript-guidance and harness-guidance)
- * retain full authority to amend anything in their domain regardless of what
+ * Scope note (load-bearing): this table scopes research PRIORITY only. It
+ * decides which facets get the most emphasis, never what a guidance sweep
+ * is allowed to touch. Both guidance skills
+ * (templates/core/.claude/skills/typescript-guidance and harness-guidance)
+ * retain full authority to amend anything in their domain, regardless of what
  * this table emphasizes -- see their SKILL.md "Authority" sections. A facet
- * with low priority here still gets swept; it just isn't the one a dedicated
+ * with low priority here still gets swept. It just isn't the one a dedicated
  * research agent digs into deepest.
  */