@monte3l/groundwork 1.0.0-rc.5 → 1.0.0-rc.7

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 (46) hide show
  1. package/README.md +20 -5
  2. package/dist/inventory.d.ts +1 -1
  3. package/dist/inventory.js +5 -2
  4. package/dist/report.js +74 -10
  5. package/dist/survey/survey-harness.d.ts +10 -2
  6. package/dist/survey/survey-harness.js +90 -4
  7. package/dist/survey/survey-shape.js +6 -3
  8. package/dist/survey/survey-toolchain.js +7 -9
  9. package/dist/survey/types.d.ts +33 -0
  10. package/dist/toolchain/grade.js +6 -7
  11. package/dist/toolchain/rules.d.ts +5 -3
  12. package/dist/toolchain/rules.js +6 -4
  13. package/package.json +1 -1
  14. package/plugin/skills/customize/SKILL.md +40 -5
  15. package/plugin/skills/customize/step-0-reconcile.md +10 -6
  16. package/plugin/skills/customize/step-3-round-1.md +12 -11
  17. package/plugin/src/domain-map.ts +3 -3
  18. package/plugin/src/kind-facet-map.ts +39 -9
  19. package/plugin/src/pack-map.ts +5 -3
  20. package/plugin/src/plugin-map.ts +29 -7
  21. package/templates/core/.claude/hooks/guard-hub-src-writes.mjs +7 -12
  22. package/templates/core/.claude/rules/agent-dispatch.md +12 -7
  23. package/templates/core/.claude/rules/src.md +7 -4
  24. package/templates/core/.claude/rules/tests.md +2 -2
  25. package/templates/core/.claude/skills/finishing-work/SKILL.md +4 -3
  26. package/templates/core/CLAUDE.md +28 -15
  27. package/templates/core/README.md +15 -3
  28. package/templates/core/bin/lib/toolchain-rules.mjs +17 -9
  29. package/templates/core/bin/lint-commit.mjs +215 -10
  30. package/templates/packs/README.md +19 -13
  31. package/templates/packs/github/files/.github/workflows/claude-pr-review.yml +2 -3
  32. package/templates/packs/github/files/.github/workflows/claude.yml +4 -7
  33. package/templates/packs/github/pack.json +1 -1
  34. package/templates/packs/harness-extras/files/.claude/hooks/guard-readonly-bash.mjs +3 -5
  35. package/templates/packs/harness-extras/pack.json +1 -1
  36. package/templates/packs/publishing/files/.github/workflows/release.yml +22 -36
  37. package/templates/packs/publishing/files/bin/lib/npm-publish-args.mjs +26 -18
  38. package/templates/packs/publishing/files/bin/lib/read-tarball-manifest.mjs +114 -0
  39. package/templates/packs/publishing/files/bin/npm-stage-publish.mjs +214 -0
  40. package/templates/packs/publishing/files/bin/pnpm-publish-shim.mjs +22 -18
  41. package/templates/packs/publishing/files/tools/release/package.json +10 -0
  42. package/templates/packs/publishing/pack.json +2 -2
  43. package/templates/packs/supply-chain/files/.github/workflows/scorecard.yml +4 -2
  44. package/templates/packs/supply-chain/pack.json +2 -2
  45. package/templates/packs/worktrees/pack.json +1 -1
  46. package/templates/packs/publishing/files/.github/release-tools/package.json +0 -9
@@ -9,16 +9,35 @@
9
9
  *
10
10
  * Usage: `lint-commit.mjs --edit <path-to-commit-msg-file>` (lefthook's
11
11
  * `commit-msg` hook contract) or `lint-commit.mjs <message>` directly.
12
+ * An empty message (direct mode with no arguments) is accepted by commitlint
13
+ * itself, so it passes here unless an enforced `trailer-exists` rule rejects
14
+ * it. git runs the `commit-msg` hook before it rejects an empty message, and
15
+ * `--allow-empty-message` lets one through, so `--edit` mode can see one too.
16
+ *
17
+ * When the config enables `trailer-exists` as an error (severity 2), the
18
+ * trailer, with a non-empty value, is also required on every message
19
+ * commitlint's default ignores skip (merge, revert, `fixup!`, `squash!`,
20
+ * `amend!`, semver release subjects): a local merge or revert needs
21
+ * `git merge --signoff` / `git revert --signoff` too. This wrapper
22
+ * deliberately does not honour commitlint's own `ignores`/`defaultIgnores`
23
+ * config keys: the first lint uses commitlint's built-in default ignores,
24
+ * and the trailer re-check always runs with them off.
25
+ *
26
+ * Every failure -- an unreadable or missing `--edit` file, a missing or
27
+ * unparseable `commitlint.config.js` or one that defines no rules, a
28
+ * forbidden trailer, a rule violation,
29
+ * a thrown error from commitlint, or a missing `git` (which `trailer-exists`
30
+ * shells out to) -- prints `✗`-prefixed line(s) to stderr (one per problem)
31
+ * and exits 1, never a stack trace.
12
32
  */
13
33
  import process from "node:process";
34
+ import { spawnSync } from "node:child_process";
14
35
  import { readFileSync } from "node:fs";
15
36
  import load from "@commitlint/load";
16
37
  import lint from "@commitlint/lint";
17
38
 
18
39
  const args = process.argv.slice(2);
19
40
  const editIndex = args.indexOf("--edit");
20
- const message =
21
- editIndex === -1 ? args.join(" ") : readFileSync(args[editIndex + 1], "utf8");
22
41
 
23
42
  const FORBIDDEN_TRAILER = /^Claude-(?!Session:)[A-Za-z-]*:/m;
24
43
 
@@ -26,18 +45,166 @@ function validateForbiddenTrailers(text) {
26
45
  return !FORBIDDEN_TRAILER.test(text) && !/^Claude-Session:/m.test(text);
27
46
  }
28
47
 
29
- const config = await load({}, { file: "commitlint.config.js" });
30
- const result = await lint(
31
- message,
32
- config.rules,
33
- config.parserPreset ? { parserOpts: config.parserPreset.parserOpts } : {},
34
- );
48
+ /**
49
+ * Prints one `✗` line to stderr and exits 1.
50
+ */
51
+ function fail(text) {
52
+ console.error(`✗ ${text}`);
53
+ process.exit(1);
54
+ }
55
+
56
+ /**
57
+ * The first non-empty line of an error's message, so one failure prints as
58
+ * one `✗` line even when commitlint throws a multi-line message.
59
+ */
60
+ function reason(error) {
61
+ const text = error instanceof Error ? error.message : String(error);
62
+ return (
63
+ text
64
+ .split(/\r?\n/)
65
+ .map((line) => line.trim())
66
+ .find((line) => line !== "") ?? text
67
+ );
68
+ }
69
+
70
+ /**
71
+ * Whether a thrown error is a failure to run `git` (which commitlint's
72
+ * `trailer-exists` shells out to), as opposed to a config or rule error.
73
+ * commitlint does not check its spawn result, so a missing `git` surfaces as
74
+ * an unrelated `TypeError`; probing `git --version` settles it directly.
75
+ */
76
+ function isGitFailure(error) {
77
+ const code =
78
+ typeof error === "object" && error !== null ? error.code : undefined;
79
+ if (code === "ENOENT") return true;
80
+ if (/\bgit\b/.test(error instanceof Error ? error.message : String(error))) {
81
+ return true;
82
+ }
83
+ const probe = spawnSync("git", ["--version"], { stdio: "ignore" });
84
+ return probe.error !== undefined || probe.status !== 0;
85
+ }
86
+
87
+ /**
88
+ * The failure text for an error thrown by commitlint's `lint`: the git hint
89
+ * only when `git` itself could not run, else the plain reason.
90
+ */
91
+ function lintFailureText(error, gitContext) {
92
+ return isGitFailure(error)
93
+ ? `${gitContext}: ${reason(error)}`
94
+ : `could not lint the commit message: ${reason(error)}`;
95
+ }
96
+
97
+ /**
98
+ * The commit message: the `--edit` file's content, else the joined args.
99
+ * A missing path or an unreadable file is reported through `fail`.
100
+ */
101
+ function readMessage() {
102
+ if (editIndex === -1) return args.join(" ");
103
+ const path = args[editIndex + 1];
104
+ // fail() exits the process; it never returns.
105
+ if (path === undefined) fail("--edit needs a path");
106
+ try {
107
+ return readFileSync(path, "utf8");
108
+ } catch (error) {
109
+ fail(`could not read the commit message file ${path}: ${reason(error)}`);
110
+ }
111
+ }
112
+
113
+ const message = readMessage();
114
+
115
+ /**
116
+ * The loaded config's `trailer-exists` entry when it is an enforced
117
+ * requirement (severity 2, not `never`), else `undefined`. Severity 1 is a
118
+ * commitlint warning and never blocks a commit.
119
+ */
120
+ function enforcedTrailerRule(rules) {
121
+ const entry = rules?.["trailer-exists"];
122
+ if (!Array.isArray(entry)) return undefined;
123
+ const [severity, applicable] = entry;
124
+ return severity === 2 && applicable !== "never" ? entry : undefined;
125
+ }
126
+
127
+ /**
128
+ * The configured trailer name with any trailing `:` stripped, so
129
+ * `Signed-off-by` and `Signed-off-by:` mean the same trailer. Empty when the
130
+ * rule names no trailer.
131
+ */
132
+ function trailerKey(value) {
133
+ return String(value ?? "")
134
+ .trim()
135
+ .replace(/:$/, "")
136
+ .trim();
137
+ }
138
+
139
+ /**
140
+ * Whether the message's trailer block (as `git interpret-trailers --parse`
141
+ * reads it, the same parse commitlint's `trailer-exists` uses) holds a
142
+ * `key:` trailer with a non-empty value. commitlint only checks the prefix,
143
+ * so an empty `Signed-off-by:` would otherwise pass. Throws when `git` cannot
144
+ * be run or exits non-zero; the caller reports that and exits 1.
145
+ */
146
+ function hasNonEmptyTrailer(text, key) {
147
+ const parsed = spawnSync("git", ["interpret-trailers", "--parse"], {
148
+ input: text,
149
+ encoding: "utf8",
150
+ });
151
+ if (parsed.error !== undefined) throw parsed.error;
152
+ if (parsed.status !== 0) {
153
+ throw new Error(
154
+ parsed.stderr.trim() || `exited with status ${String(parsed.status)}`,
155
+ );
156
+ }
157
+ const prefix = `${key}:`;
158
+ return parsed.stdout
159
+ .split(/\r?\n/)
160
+ .some(
161
+ (line) =>
162
+ line.startsWith(prefix) && line.slice(prefix.length).trim() !== "",
163
+ );
164
+ }
165
+
166
+ const IGNORED_KINDS =
167
+ "merge, revert, fixup!, squash!, amend!, semver release subjects";
168
+
169
+ function missingTrailerText(key, qualifier) {
170
+ const name = key === "" ? "a trailer" : `a ${qualifier}\`${key}:\` trailer`;
171
+ const hint = /^signed-off-by$/i.test(key) ? ": use `-s`/`--signoff`" : "";
172
+ return `message must have ${name}, including every message commitlint's default ignores skip (${IGNORED_KINDS})${hint}`;
173
+ }
174
+
175
+ let config;
176
+ try {
177
+ config = await load({}, { file: "commitlint.config.js" });
178
+ } catch (error) {
179
+ fail(`could not load commitlint.config.js: ${reason(error)}`);
180
+ }
181
+ // @commitlint/cli rejects an empty rule set the same way: a config whose
182
+ // `extends` resolved to nothing would otherwise pass every message.
183
+ if (Object.keys(config.rules ?? {}).length === 0) {
184
+ fail(
185
+ "commitlint.config.js loaded but defines no rules (check its `extends`)",
186
+ );
187
+ }
188
+ const parserOptions = config.parserPreset
189
+ ? { parserOpts: config.parserPreset.parserOpts }
190
+ : {};
191
+
192
+ let result;
193
+ try {
194
+ result = await lint(message, config.rules, parserOptions);
195
+ } catch (error) {
196
+ fail(
197
+ lintFailureText(
198
+ error,
199
+ "could not lint the commit message (commitlint's trailer-exists runs git interpret-trailers; is git on PATH?)",
200
+ ),
201
+ );
202
+ }
35
203
 
36
204
  if (!validateForbiddenTrailers(message)) {
37
- console.error(
205
+ fail(
38
206
  "commit message carries a forbidden Claude-* trailer (only Co-Authored-By: is allowed)",
39
207
  );
40
- process.exit(1);
41
208
  }
42
209
 
43
210
  if (!result.valid) {
@@ -47,4 +214,42 @@ if (!result.valid) {
47
214
  process.exit(1);
48
215
  }
49
216
 
217
+ // commitlint's default ignores skip merge/revert/fixup!/squash!/amend! and
218
+ // semver release messages entirely, trailer-exists included. Re-run just that
219
+ // rule with the ignores off so an enforced trailer is required on every
220
+ // message. Only reached when the first lint passed, so a failure is never
221
+ // reported twice.
222
+ const trailerRule = enforcedTrailerRule(config.rules);
223
+ if (trailerRule !== undefined) {
224
+ const key = trailerKey(trailerRule[2]);
225
+ let trailerResult;
226
+ try {
227
+ trailerResult = await lint(
228
+ message,
229
+ { "trailer-exists": trailerRule },
230
+ { defaultIgnores: false, ...parserOptions },
231
+ );
232
+ } catch (error) {
233
+ fail(
234
+ lintFailureText(
235
+ error,
236
+ "could not read commit trailers (git interpret-trailers failed)",
237
+ ),
238
+ );
239
+ }
240
+ if (!trailerResult.valid) fail(missingTrailerText(key, ""));
241
+ // An empty configured value leaves the decision to commitlint's own rule.
242
+ if (key !== "") {
243
+ let present;
244
+ try {
245
+ present = hasNonEmptyTrailer(message, key);
246
+ } catch (error) {
247
+ fail(
248
+ `could not read commit trailers (git interpret-trailers failed): ${reason(error)}`,
249
+ );
250
+ }
251
+ if (!present) fail(missingTrailerText(key, "non-empty "));
252
+ }
253
+ }
254
+
50
255
  console.log("✓ commit message is a valid Conventional Commit");
@@ -11,7 +11,7 @@ kinds and shouldn't tax every bootstrap by default.
11
11
 
12
12
  ```
13
13
  templates/packs/<name>/
14
- ├── pack.json # manifest: budget, requires, wiring
14
+ ├── pack.json # manifest: see "pack.json fields" below
15
15
  └── files/ # the pack's own file tree, mirroring the project root
16
16
  # exactly as templates/core/ does -- emitted the same way
17
17
  ```
@@ -45,15 +45,19 @@ already enumerate groups rather than individual steps.
45
45
  `pack.json` fields:
46
46
 
47
47
  - `schemaVersion` — currently `1`.
48
- - `modes` — `["fresh"]` and/or `["fresh", "adopt"]`. "Adopt-capable" means
49
- an artifact has no dependency on the baseline's exact file layout (an
50
- agent, most hooks), so it's safe to install into an already-existing
51
- project's own layout. A gate that assumes a specific source layout isn't
52
- adopt-capable -- it should say so honestly in `adoptNotes` instead of
53
- claiming `adopt`.
48
+ - `modes` — `["fresh"]` and/or `["fresh", "adopt"]`. By convention,
49
+ "adopt-capable" means an artifact has no dependency on the baseline's exact
50
+ file layout (an agent, most hooks), so it is safe to install into an
51
+ existing project. Nothing enforces this: adopt mode stages every pack
52
+ whatever its `modes`, and fresh mode refuses a pack that does not list
53
+ `fresh`. A pack whose artifacts
54
+ assume a layout can still list `adopt` (`quality` does: its gate assumes a
55
+ flat `src/` and `tests/`); it must then say what to adjust in `adoptNotes`,
56
+ which `/customize` surfaces before installing.
54
57
  - `budget` — the pack's cap deltas (`agents`/`skills`/`hooks`/`workflows`/
55
- `scripts`), checked against `templates/core`'s own counts by a structural
56
- test, never against `templates/core` + every other pack.
58
+ `scripts`), checked by `caps.test.ts` against what the pack's own `files/` tree
59
+ contains. The test does not compare it to `templates/core`'s counts or to
60
+ the sum of any other packs.
57
61
  - `requires.paths` — baseline files a pack artifact imports (e.g.
58
62
  `bin/lib/agent-roster.mjs`). Checked at install time in fresh mode; a
59
63
  missing requirement is a hard install error, not a silent partial install.
@@ -63,8 +67,10 @@ already enumerate groups rather than individual steps.
63
67
  - `wiring.settingsTopLevel` — top-level `.claude/settings.json` keys that
64
68
  aren't hook registrations (`statusLine`, `subagentStatusLine`, …), planted
65
69
  whole. A key the project already defines with a different value is a hard
66
- install error, never an overwrite; `hooks` is refused here, since it
67
- belongs in `wiring.settings`. Optional.
70
+ install error, never an overwrite; a `hooks` key is refused when the fragment is
71
+ merged (`mergeSettingsTopLevel` in `merge-json.ts`; `loadPack` does not
72
+ check it), since hooks belong in `wiring.settings`. In adopt mode
73
+ `/customize` performs the merge by hand. Optional.
68
74
  - `wiring.packageScripts` — `package.json` script additions. Most packs need
69
75
  none: a gate registers directly as `["node", "bin/check-x.mjs"]` in
70
76
  `wiring.verifySteps`, not as a `pnpm` script.
@@ -102,6 +108,6 @@ already enumerate groups rather than individual steps.
102
108
  | `harness-extras` | Claude Code session ergonomics: the compaction-handoff hook pair, a read-only Bash guard, and a five-row status line (session, model, context, quota, work) plus a per-subagent row renderer. The only pack that sets top-level settings keys (`statusLine`, `subagentStatusLine`). |
103
109
  | `quality` | Two language-level review aids: a per-file size ratchet gate (`check-file-budget.mjs`, a `build`-group verify step) and a read-only `type-design-analyzer` agent. No hooks, no settings. Adopt-capable and recommended for every project kind. |
104
110
  | `github` | GitHub-hosted collaboration: Anthropic's official Claude Code GitHub Action wired for `@claude` mention-mode, a second Action that posts an automated Claude review comment on every PR, and three `gh`-CLI skills — `reviewing-dependabot-prs`, `triaging-scan-alerts`, `watching-pr-checks`. No hooks, no gate. The two workflows need an auth secret this pack cannot create; see its `adoptNotes`. |
105
- | `publishing` | A release pipeline: `release.yml` (changesets version-PR / staged, provenance-attested npm publish via trusted publishing), `check-publish-version.mjs`, `check-dts-deps.mjs`, `check-license-headers.mjs` and a `REUSE.toml` template. Fresh mode only — see "Install path" below and its `adoptNotes`. |
106
- | `supply-chain` | Secret scanning (`gitleaks.yml` with a `.gitleaks.toml`) and an OpenSSF Scorecard run (`scorecard.yml`) for any project on GitHub, published or not. A pure file drop of two read-only workflows: no hooks, no settings, no scripts, no gate. Adopt-capable and recommended for every project kind. |
111
+ | `publishing` | A release pipeline: `release.yml` (changesets version-PR / staged, provenance-attested npm publish via trusted publishing), `check-publish-version.mjs`, `check-dts-deps.mjs`, `check-license-headers.mjs` and a `REUSE.toml` template. Fresh mode only; see "The wiring contract" above and its `adoptNotes`. |
112
+ | `supply-chain` | Secret scanning (`gitleaks.yml` with a `.gitleaks.toml`) and an OpenSSF Scorecard run (`scorecard.yml`) for any project on GitHub, published or not. A pure file drop of two workflows (read-only apart from the Scorecard job's `security-events` and `id-token` write): no hooks, no settings, no scripts, no gate. Adopt-capable and recommended for every project kind. |
107
113
  | `worktrees` | Enforces that all src/tests development happens inside an isolated git worktree, on any branch, for any caller: a `working-in-worktrees` skill (start/status/sync/finish/fan-out), a `SessionStart` hook that installs dependencies into a freshly created worktree, a `PreToolUse` guard stricter than the baseline's own `guard-branch-isolation.mjs`/`guard-hub-src-writes.mjs`, a `repair-core-bare.mjs` hook (`SessionStart`, and `PostToolUse` after `EnterWorktree`/`ExitWorktree`/`Agent`) that resets the `core.bare = true` Claude Code's worktree tools are reported to leave in a normal repo's shared config, and a `.worktreeinclude` copying `.env`/`.env.local`/`.env.*.local` into every worktree Claude Code creates. Changes the day-to-day workflow, not just a nicety — see its `adoptNotes`. |
@@ -46,9 +46,8 @@ name: Claude PR Review
46
46
  # bot-authored and fork PRs explicitly below, rather than relying on
47
47
  # anthropics/claude-code-action's own internal bot/permission checks
48
48
  # (docs/security.md) -- that way a Dependabot or fork PR never starts a run
49
- # that would just fail on missing secrets. Runs but fails cleanly on an auth
50
- # error until the one-time setup described in claude.yml's comments is done
51
- # by hand.
49
+ # that would just fail on missing secrets. This workflow needs one of the
50
+ # auth methods described in claude.yml's comments, set up by hand once.
52
51
  on:
53
52
  pull_request:
54
53
  types: [opened, synchronize, ready_for_review, reopened]
@@ -12,8 +12,7 @@ name: Claude Code
12
12
  # https://github.com/anthropics/claude-code-action/blob/main/examples/pr-review-comprehensive.yml
13
13
  #
14
14
  # This workflow needs one of the three auth methods below (Option 1 is
15
- # active by default) -- until one is configured it fails cleanly on an
16
- # @claude mention (an auth error, not a crash or a silent no-op).
15
+ # active by default).
17
16
  on:
18
17
  issue_comment:
19
18
  types: [created]
@@ -33,11 +32,9 @@ jobs:
33
32
  # `@claude` text match alone would let an outside commenter trigger a job
34
33
  # holding `contents: write` and your auth secret. Each branch below also
35
34
  # requires the `author_association` of the comment's, review's or
36
- # issue's author to be OWNER, MEMBER or COLLABORATOR. Two consequences:
37
- # an org member whose membership is private can surface as CONTRIBUTOR
38
- # and be skipped, and on `issues` the check is on the issue's author, not
39
- # on whoever assigned it, so assigning an outsider's issue does not start
40
- # a run.
35
+ # issue's author to be OWNER, MEMBER or COLLABORATOR. On `issues` the
36
+ # check is on the issue's author, not on whoever assigned it, so
37
+ # assigning an outsider's issue does not start a run.
41
38
  if: |
42
39
  (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude') && contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.comment.author_association)) ||
43
40
  (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude') && contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.comment.author_association)) ||
@@ -15,5 +15,5 @@
15
15
  "packageScripts": {},
16
16
  "verifySteps": []
17
17
  },
18
- "adoptNotes": "claude.yml only reacts to @claude mentions from a repository owner, member or collaborator (author_association), so an outside commenter on a public repository cannot start a job that holds contents: write and your auth secret; an org member with private membership may surface as CONTRIBUTOR and be skipped. It also commits through the GitHub API (use_commit_signing) so a signed-commits ruleset accepts its work. Both workflows need one thing this pack cannot verify or install: an ANTHROPIC_API_KEY repository secret (the active default), or a CLAUDE_CODE_OAUTH_TOKEN from a Claude subscription, or a Workload Identity Federation setup in the Anthropic Console -- see the comments in .github/workflows/claude.yml for all three. Until one is configured, either workflow runs and fails cleanly (an auth error in the run log, not a crash and not a silent no-op): claude.yml on an @claude mention, claude-pr-review.yml on the next PR open/push. An adopted project that already has its own .github/workflows/claude.yml or claude-pr-review.yml surfaces as an ordinary file conflict -- keep the existing one if it's already configured for that project's own auth choice, since this pack's version would just overwrite a working setup with its own generic defaults. triaging-scan-alerts reads code-scanning alerts, and nothing in the baseline or this pack produces them: turn on GitHub's CodeQL default setup for the repository (Settings > Code security), or install the `supply-chain` pack, whose scorecard.yml uploads SARIF, otherwise the skill's first call returns \"code scanning is not enabled\" and reports nothing. The other two skills have no such dependency: they install anywhere a .claude/ directory exists and need only `gh` CLI auth (already required by every other gh-CLI-based skill this baseline ships). watching-pr-checks' handoff to /triaging-ci degrades gracefully if the project doesn't have that skill installed -- it still reports the real failure, just without the handoff."
18
+ "adoptNotes": "claude.yml only reacts to @claude mentions from a repository owner, member or collaborator (author_association), so an outside commenter on a public repository cannot start a job that holds contents: write and your auth secret. It also commits through the GitHub API (use_commit_signing) so a signed-commits ruleset accepts its work. Both workflows need one thing this pack cannot verify or install: an ANTHROPIC_API_KEY repository secret (the active default), or a CLAUDE_CODE_OAUTH_TOKEN from a Claude subscription, or a Workload Identity Federation setup in the Anthropic Console -- see the comments in .github/workflows/claude.yml for all three. An adopted project that already has its own .github/workflows/claude.yml or claude-pr-review.yml surfaces as an ordinary file conflict -- keep the existing one if it's already configured for that project's own auth choice, since this pack's version would just overwrite a working setup with its own generic defaults. triaging-scan-alerts reads code-scanning alerts, and nothing in the baseline or this pack produces them: turn on GitHub's CodeQL default setup for the repository (Settings > Code security), or install the `supply-chain` pack, whose scorecard.yml uploads SARIF, otherwise the skill's first call returns \"code scanning is not enabled\" and reports nothing. The other two skills have no such dependency: they install anywhere a .claude/ directory exists and need only `gh` CLI auth (already required by every other gh-CLI-based skill this baseline ships). watching-pr-checks' handoff to /triaging-ci degrades gracefully if the project doesn't have that skill installed -- it still reports the real failure, just without the handoff."
19
19
  }
@@ -21,11 +21,9 @@
21
21
  *
22
22
  * Scope: only tool calls made from inside one of those read-only subagents
23
23
  * are checked -- identified via the hook payload's `agent_type` field
24
- * (present when `PreToolUse` fires inside a subagent context, and also in a
25
- * main session started with `claude --agent <name>`; absent for an ordinary
26
- * hub's own Bash calls, which this hook does not restrict). Keeping the
27
- * read-only restriction on a `--agent <read-only agent>` main session is
28
- * fail-safe -- it only refuses more -- so no `agent_id` check is needed here.
24
+ * (a call with no `agent_type` is not restricted). Applying the read-only
25
+ * restriction whenever `agent_type` names a read-only agent is fail-safe --
26
+ * it only refuses more -- so no `agent_id` check is needed here.
29
27
  *
30
28
  * Design tradeoff, matching every sibling guard hook's fail-open
31
29
  * philosophy: this is a DENYLIST of known-mutating patterns, not a strict
@@ -66,5 +66,5 @@
66
66
  "packageScripts": {},
67
67
  "verifySteps": []
68
68
  },
69
- "adoptNotes": "The statusline and compaction hooks install anywhere a .claude/ directory exists, but guard-readonly-bash.mjs imports ../../bin/lib/agent-roster.mjs (the baseline's list of writer spokes) -- copy that file alongside it in an adopted project, or skip that one hook. The PreCompact hook writes tmp/compact-handoff-<session_id>.json under the git worktree the session runs in (from the hook payload's cwd, since CLAUDE_PROJECT_DIR does not follow a session into a linked worktree) -- fresh mode's baseline .gitignore already lists tmp/ unconditionally, but an adopted project's own .gitignore was never touched by adopt mode, so add tmp/ there too before this pack's hooks run, or the handoff artifact can end up committed. The statusline scripts read only the stdin payload, .git/HEAD (via node:fs, never a git subprocess) and process.availableMemory()/os.totalmem(), so they install anywhere a .claude/ directory exists -- no dependency on the baseline's file layout. The one real adopt risk is the two top-level settings keys: a project that already defines statusLine or subagentStatusLine collides, and its existing value must be shown and decided on, never overwritten -- if either is already set, skip that key and the three statusline scripts, and install the rest of this pack (the hooks) normally rather than failing the whole install. A .claude/settings.local.json or the user's own ~/.claude/settings.json statusLine also shadows the project one -- check both before concluding the pack is wired. rate_limits.spend_limit and prompt_cache need Claude Code v2.1.251+, and the per-subagent model/contextWindowSize/effort fields need v2.1.205+/v2.1.214+, and the agentType label a row falls back to when a subagent has no name needs v2.1.293+; each renders only when present, so an older Claude Code degrades to fewer segments rather than breaking. The scripts behave the same on macOS and Linux; the memory segment uses process.availableMemory() (Node 22+), and on macOS with an older Node it is hidden rather than shown from os.freemem(), which undercounts there. Below roughly 40 columns the layout drops segments by priority rather than wrapping. The size-ratchet gate and the type-design-analyzer agent that used to ship here are now the separate `quality` pack."
69
+ "adoptNotes": "The statusline and compaction hooks install anywhere a .claude/ directory exists, but guard-readonly-bash.mjs imports ../../bin/lib/agent-roster.mjs (the baseline's list of writer spokes) -- copy that file alongside it in an adopted project, or skip that one hook. The PreCompact hook writes tmp/compact-handoff-<session_id>.json under the git worktree the session runs in (from the hook payload's cwd, since CLAUDE_PROJECT_DIR does not follow a session into a linked worktree) -- fresh mode's baseline .gitignore already lists tmp/ unconditionally, but an adopted project's own .gitignore was never touched by adopt mode, so add tmp/ there too before this pack's hooks run, or the handoff artifact can end up committed. The statusline scripts read only the stdin payload, .git/HEAD (via node:fs, never a git subprocess) and process.availableMemory()/os.totalmem(), so they install anywhere a .claude/ directory exists -- no dependency on the baseline's file layout. The one real adopt risk is the two top-level settings keys: a project that already defines statusLine or subagentStatusLine collides, and its existing value must be shown and decided on, never overwritten -- if either is already set, skip that key and the three statusline scripts, and install the rest of this pack (the hooks) normally rather than failing the whole install. A statusLine in .claude/settings.local.json (or one passed with --settings) also shadows the project one; the user's own ~/.claude/settings.json ranks lower and does not -- check those before concluding the pack is wired. rate_limits.spend_limit and prompt_cache need Claude Code v2.1.251+, and the per-subagent model/contextWindowSize/effort fields need v2.1.205+/v2.1.214+, and the agentType label a row falls back to when a subagent has no name needs v2.1.293+; each renders only when present, so an older Claude Code degrades to fewer segments rather than breaking. The scripts behave the same on macOS and Linux; the memory segment uses process.availableMemory() (Node 22+), and on macOS with an older Node it is hidden rather than shown from os.freemem(), which undercounts there. Below roughly 40 columns the layout drops segments by priority rather than wrapping. The size-ratchet gate and the type-design-analyzer agent that used to ship here are now the separate `quality` pack."
70
70
  }
@@ -29,7 +29,7 @@ name: Release
29
29
  # pnpm shim below, with `--ignore-scripts`. `pack` holds nothing beyond
30
30
  # `contents: read`.
31
31
  #
32
- # "Staged" publish (vs. a "direct" one) means `npm stage publish` uploads the
32
+ # "Staged" publish (vs. a "direct" one) means a staged publish uploads the
33
33
  # tarball and creates the version, but it isn't installable yet until a
34
34
  # maintainer separately approves it with 2FA (`npm stage approve`) -- npm's
35
35
  # own stronger default over a direct `npm publish`, which would make the
@@ -162,7 +162,7 @@ jobs:
162
162
  needs: pack
163
163
  runs-on: ubuntu-latest
164
164
  timeout-minutes: 15
165
- # Gates the git tag, the GitHub Release, and `npm stage publish` behind a
165
+ # Gates the git tag, the GitHub Release, and the staged publish behind a
166
166
  # required reviewer -- without this, all three already exist by the time
167
167
  # a maintainer even sees there's a staged version to approve with
168
168
  # `npm stage approve`. The environment (created once, by hand, via
@@ -185,28 +185,22 @@ jobs:
185
185
  package-manager-cache: false
186
186
  # Only the changesets CLI is needed here, not any package's lifecycle scripts.
187
187
  - run: pnpm install --frozen-lockfile --ignore-scripts
188
- # `npm stage publish` needs npm >= 11.15.0. The pinned npm (12.2.0)
189
- # declares engines Node ^22.22.2 || ^24.15.0 || >=26. .node-version's
190
- # `24` meets that on GitHub-hosted runners, whose cached 24.x is recent;
191
- # a self-hosted runner with an older cached 24.x does not. Pinned to an
192
- # exact version, not a range or `latest`: this job holds the OIDC token,
193
- # and an unpinned package-manager install is exactly what OpenSSF
194
- # Scorecard's Pinned-Dependencies check flags. `.github/release-tools/`
195
- # pins the exact tarball via its committed lockfile's integrity hash, and
196
- # `npm ci` verifies the install against it -- bumping the pin is then
197
- # a normal reviewed PR (a lockfile diff), not a hand-edited version
198
- # string.
199
- - run: npm ci --ignore-scripts --prefix .github/release-tools
200
- - run: echo "$GITHUB_WORKSPACE/.github/release-tools/node_modules/.bin" >> "$GITHUB_PATH"
188
+ # Staged publishing goes through libnpmpublish (npm's own publish
189
+ # library, bin/npm-stage-publish.mjs), not the npm CLI: the CLI bundles
190
+ # its own dependencies, which no override can patch. Pinned to exact
191
+ # versions, not a range or `latest`: this job holds the OIDC token, and
192
+ # an unpinned package install is exactly what OpenSSF Scorecard's
193
+ # Pinned-Dependencies check flags. `tools/release/` pins every tarball
194
+ # via its committed lockfile's integrity hash, and `npm ci` verifies the
195
+ # install against it -- bumping the pin is then a normal reviewed PR (a
196
+ # lockfile diff), not a hand-edited version string.
197
+ - run: npm ci --ignore-scripts --prefix tools/release
201
198
  # changesets publishes through `pnpm publish` in a pnpm-managed
202
- # project, and pnpm 12's native publish is rejected by npmjs.com's OIDC
203
- # exchange (403 "OIDC permission denied"). This puts a `pnpm` ahead of
204
- # the real one that forwards everything except `publish`, which goes
205
- # to `npm stage publish` instead (see bin/pnpm-publish-shim.mjs -- the
206
- # trusted publisher only allows staged publishing, npm's own default
207
- # since 2026-09-03; a direct `npm publish` gets the same 403 for a
208
- # different reason). Remove both once pnpm's own publish authenticates.
209
- - name: Route publish through the npm CLI
199
+ # project. This puts a `pnpm` ahead of the real one that forwards
200
+ # everything except `publish`, which goes to a staged publish
201
+ # instead (see bin/pnpm-publish-shim.mjs -- the trusted publisher only
202
+ # allows staged publishing, npm's own default since 2026-09-03).
203
+ - name: Route publish through the staged publisher
210
204
  run: |
211
205
  shim_dir="$RUNNER_TEMP/pnpm-shim"
212
206
  mkdir -p "$shim_dir"
@@ -216,6 +210,8 @@ jobs:
216
210
  echo "$shim_dir" >> "$GITHUB_PATH"
217
211
  - uses: changesets/action/publish@ae32849d5ba541f9ae29e40e22a623bc13562f51 # v2
218
212
  id: publish
213
+ env:
214
+ RELEASE_TOOLS_DIR: ${{ github.workspace }}/tools/release
219
215
  with:
220
216
  pack-dir-artifact-id: ${{ needs.pack.outputs.pack-dir-artifact-id }}
221
217
  # npm provenance alone already meets most supply-chain "signed
@@ -226,12 +222,12 @@ jobs:
226
222
  # rebuilt), attested, and attached. `if:` guards all three on
227
223
  # `publish` actually having published -- `select-mode` only decides
228
224
  # the job should run, not that a version was new.
229
- # `continue-on-error: true` on all three: `npm stage publish` has
225
+ # `continue-on-error: true` on all three: the staged publish has
230
226
  # already succeeded by this point, so a failure here (a transient
231
227
  # download error, say) must never fail the whole job and leave a
232
228
  # staged, tagged, unreleased version behind -- this block is
233
- # best-effort supplementary evidence, the same status as the
234
- # "List pending stages" step below.
229
+ # best-effort supplementary evidence. (The stage id to approve is
230
+ # printed, and added to the job summary, by the publish step itself.)
235
231
  - name: Fetch the packed tarball back out of the pack job's artifact
236
232
  if: steps.publish.outputs.published == 'true'
237
233
  continue-on-error: true
@@ -283,13 +279,3 @@ jobs:
283
279
  fi
284
280
  gh release upload "$tag" \
285
281
  "$tarball" --clobber --repo "${{ github.repository }}"
286
- # Staging succeeds unattended; going live needs a maintainer's 2FA
287
- # (`npm stage approve <id>`, on the CLI or npmjs.com -- never
288
- # automatable, by design). Best-effort convenience only: this job
289
- # never logs in with a token (it publishes purely via the OIDC
290
- # exchange scoped to the publish call itself), so `npm stage list` may
291
- # print nothing useful -- `|| true` means that possibility never fails
292
- # the job.
293
- - name: List pending stages (best effort)
294
- if: always()
295
- run: npm stage list --package "$(node -p "require('./package.json').name")" || true
@@ -3,8 +3,8 @@
3
3
  // SPDX-License-Identifier: NOASSERTION
4
4
 
5
5
  /**
6
- * Translates the one `pnpm publish` invocation changesets makes for a packed
7
- * tarball into the equivalent `npm stage publish`, for `pnpm-publish-shim.mjs`.
6
+ * Parses the one `pnpm publish` invocation changesets makes for a packed
7
+ * tarball, for `pnpm-publish-shim.mjs` and `npm-stage-publish.mjs`.
8
8
  *
9
9
  * Changesets runs (see its `lib/pnpm.ts`):
10
10
  * pnpm publish <tarball> [--json] --access <a> --tag <t> --no-git-checks [--otp <c>]
@@ -13,25 +13,24 @@
13
13
  * is refused rather than guessed at: if changesets ever starts passing a flag
14
14
  * this does not understand, publishing must stop, not silently do something else.
15
15
  *
16
- * Staged, not direct: a trusted publisher created since 2026-09-03 defaults to
17
- * `npm stage publish` only, npm's own default (and explicit recommendation) --
18
- * a maintainer must separately run `npm stage approve <id>` (2FA, never
19
- * automatable) before a staged version actually goes live. `npm stage publish`
20
- * accepts the same `--access`/`--tag`/`--otp`/`--provenance` flags as
21
- * `npm publish` ("parity with npm publish" per npm's own CLI reference); the
22
- * command itself is `npm stage publish`, not a flag on `npm publish`.
16
+ * Staged, not direct: a trusted publisher created since 2026-09-03 only allows a
17
+ * staged publish -- a maintainer must separately run `npm stage approve <id>`
18
+ * (2FA, never automatable) before a staged version actually goes live.
23
19
  */
24
20
 
25
21
  const DROPPED = new Set(["--json", "--no-git-checks"]);
26
22
  const WITH_VALUE = new Set(["--access", "--tag", "--otp"]);
27
23
 
28
24
  /**
25
+ * Splits the arguments after `pnpm publish` into the tarball and the
26
+ * `[flag, value]` pairs changesets passes, refusing anything else.
27
+ *
29
28
  * @param {string[]} args the arguments following `pnpm publish`
30
- * @returns {string[]} the argument vector for `npm stage publish`
29
+ * @returns {{ tarball: string, pairs: [string, string][] }}
31
30
  */
32
- export function toNpmStagePublishArgs(args) {
31
+ function scanPublishArgs(args) {
33
32
  let tarball;
34
- const flags = [];
33
+ const pairs = [];
35
34
 
36
35
  for (let i = 0; i < args.length; i += 1) {
37
36
  const arg = args[i];
@@ -42,7 +41,7 @@ export function toNpmStagePublishArgs(args) {
42
41
  if (value === undefined || value.startsWith("--")) {
43
42
  throw new Error(`${arg} needs a value`);
44
43
  }
45
- flags.push(arg, value);
44
+ pairs.push([arg, value]);
46
45
  i += 1;
47
46
  continue;
48
47
  }
@@ -61,12 +60,21 @@ export function toNpmStagePublishArgs(args) {
61
60
  "no tarball given: this shim only publishes packed tarballs (changesets' --from-pack-dir mode)",
62
61
  );
63
62
  }
63
+ return { tarball, pairs };
64
+ }
64
65
 
65
- // Provenance is requested explicitly rather than relied on: npm's automatic
66
- // attestation for trusted publishing has been reported not to engage without it.
67
- // "stage", "publish" are two separate words (the npm-stage subcommand), not
68
- // "stage-publish" or a flag -- see npm's own CLI reference for npm-stage.
69
- return ["stage", "publish", tarball, ...flags, "--provenance"];
66
+ /**
67
+ * Parses the one `pnpm publish` invocation changesets makes, as named values
68
+ * for `npm-stage-publish.mjs` (which calls libnpmpublish instead of the npm CLI).
69
+ *
70
+ * @param {string[]} args the arguments following `pnpm publish`
71
+ * @returns {{ tarball: string, access?: string, tag?: string, otp?: string }}
72
+ */
73
+ export function parsePublishArgs(args) {
74
+ const { tarball, pairs } = scanPublishArgs(args);
75
+ const out = { tarball };
76
+ for (const [flag, value] of pairs) out[flag.slice(2)] = value;
77
+ return out;
70
78
  }
71
79
 
72
80
  /**