@monte3l/groundwork 1.0.0-rc.5 → 1.0.0-rc.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +20 -5
- package/dist/inventory.d.ts +1 -1
- package/dist/inventory.js +5 -2
- package/dist/report.js +74 -10
- package/dist/survey/survey-harness.d.ts +10 -2
- package/dist/survey/survey-harness.js +90 -4
- package/dist/survey/survey-shape.js +6 -3
- package/dist/survey/survey-toolchain.js +7 -9
- package/dist/survey/types.d.ts +33 -0
- package/dist/toolchain/grade.js +6 -7
- package/dist/toolchain/rules.d.ts +5 -3
- package/dist/toolchain/rules.js +6 -4
- package/package.json +1 -1
- package/plugin/skills/customize/SKILL.md +40 -5
- package/plugin/skills/customize/step-0-reconcile.md +10 -6
- package/plugin/skills/customize/step-3-round-1.md +12 -11
- package/plugin/src/domain-map.ts +2 -2
- package/plugin/src/kind-facet-map.ts +39 -9
- package/plugin/src/pack-map.ts +5 -3
- package/plugin/src/plugin-map.ts +29 -7
- package/templates/core/.claude/hooks/guard-hub-src-writes.mjs +7 -12
- package/templates/core/.claude/rules/agent-dispatch.md +12 -7
- package/templates/core/.claude/rules/src.md +7 -4
- package/templates/core/.claude/rules/tests.md +2 -2
- package/templates/core/.claude/skills/finishing-work/SKILL.md +4 -3
- package/templates/core/CLAUDE.md +28 -15
- package/templates/core/README.md +15 -3
- package/templates/core/bin/lib/toolchain-rules.mjs +17 -9
- package/templates/core/bin/lint-commit.mjs +215 -10
- package/templates/packs/README.md +19 -13
- package/templates/packs/github/files/.github/workflows/claude-pr-review.yml +2 -3
- package/templates/packs/github/files/.github/workflows/claude.yml +4 -7
- package/templates/packs/github/pack.json +1 -1
- package/templates/packs/harness-extras/files/.claude/hooks/guard-readonly-bash.mjs +3 -5
- package/templates/packs/harness-extras/pack.json +1 -1
- package/templates/packs/publishing/files/.github/workflows/release.yml +4 -7
- package/templates/packs/publishing/files/bin/pnpm-publish-shim.mjs +4 -14
- package/templates/packs/supply-chain/files/.github/workflows/scorecard.yml +4 -2
- package/templates/packs/supply-chain/pack.json +2 -2
- package/templates/packs/worktrees/pack.json +1 -1
|
@@ -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
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
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
|
-
|
|
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:
|
|
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"]`.
|
|
49
|
-
an artifact has no dependency on the baseline's exact
|
|
50
|
-
agent, most hooks), so it
|
|
51
|
-
project
|
|
52
|
-
|
|
53
|
-
|
|
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
|
|
56
|
-
test
|
|
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
|
|
67
|
-
|
|
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
|
|
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
|
|
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.
|
|
50
|
-
#
|
|
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)
|
|
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.
|
|
37
|
-
#
|
|
38
|
-
#
|
|
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
|
|
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
|
-
* (
|
|
25
|
-
*
|
|
26
|
-
*
|
|
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
|
|
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
|
}
|
|
@@ -199,13 +199,10 @@ jobs:
|
|
|
199
199
|
- run: npm ci --ignore-scripts --prefix .github/release-tools
|
|
200
200
|
- run: echo "$GITHUB_WORKSPACE/.github/release-tools/node_modules/.bin" >> "$GITHUB_PATH"
|
|
201
201
|
# changesets publishes through `pnpm publish` in a pnpm-managed
|
|
202
|
-
# project
|
|
203
|
-
#
|
|
204
|
-
#
|
|
205
|
-
#
|
|
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.
|
|
202
|
+
# project. This puts a `pnpm` ahead of the real one that forwards
|
|
203
|
+
# everything except `publish`, which goes to `npm stage publish`
|
|
204
|
+
# instead (see bin/pnpm-publish-shim.mjs -- the trusted publisher only
|
|
205
|
+
# allows staged publishing, npm's own default since 2026-09-03).
|
|
209
206
|
- name: Route publish through the npm CLI
|
|
210
207
|
run: |
|
|
211
208
|
shim_dir="$RUNNER_TEMP/pnpm-shim"
|
|
@@ -9,18 +9,10 @@
|
|
|
9
9
|
*
|
|
10
10
|
* ## Why it exists
|
|
11
11
|
*
|
|
12
|
-
*
|
|
13
|
-
*
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
* for a correctly configured trusted publisher. The npm CLI's exchange
|
|
17
|
-
* works.
|
|
18
|
-
* 2. It can't be a direct `npm publish` either: a trusted publisher created
|
|
19
|
-
* since 2026-09-03 defaults to `npm stage publish` only, npm's own
|
|
20
|
-
* explicit recommendation (see this pack's adoptNotes). A direct
|
|
21
|
-
* `npm publish` gets the exact same 403 "OIDC permission denied" as the
|
|
22
|
-
* pnpm case, for an unrelated reason: the token exchange succeeds, but
|
|
23
|
-
* the registry refuses the specific action.
|
|
12
|
+
* `changeset publish` in a pnpm-managed project publishes through
|
|
13
|
+
* `pnpm publish`. A trusted publisher created since 2026-09-03 defaults to
|
|
14
|
+
* `npm stage publish` only, npm's own explicit recommendation (see this
|
|
15
|
+
* pack's adoptNotes), so the publish is rerouted to `npm stage publish`.
|
|
24
16
|
*
|
|
25
17
|
* ## What it translates
|
|
26
18
|
*
|
|
@@ -42,8 +34,6 @@
|
|
|
42
34
|
*
|
|
43
35
|
* `PNPM_SHIM_DIR` names this shim's own directory so it can be dropped from
|
|
44
36
|
* PATH when looking for the real pnpm (otherwise it would find itself).
|
|
45
|
-
* Delete this, and the workflow step that installs it, once pnpm's publish
|
|
46
|
-
* authenticates against npmjs.com.
|
|
47
37
|
*/
|
|
48
38
|
import process from "node:process";
|
|
49
39
|
import { spawnSync } from "node:child_process";
|
|
@@ -5,8 +5,10 @@ name: Scorecard
|
|
|
5
5
|
# signed releases, and similar checks) and can publish a badge from the
|
|
6
6
|
# result. It runs weekly, on every push to the release branch, and on
|
|
7
7
|
# manual dispatch -- not on every PR, since supply-chain posture doesn't
|
|
8
|
-
# change per-commit the way tests do.
|
|
9
|
-
#
|
|
8
|
+
# change per-commit the way tests do. It never writes to the repository's
|
|
9
|
+
# contents, but the analysis job holds security-events: write (to upload
|
|
10
|
+
# SARIF) and id-token: write (to publish results); the workflow-level
|
|
11
|
+
# default is read-all.
|
|
10
12
|
on:
|
|
11
13
|
push:
|
|
12
14
|
branches: [main]
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"schemaVersion": 1,
|
|
3
3
|
"name": "supply-chain",
|
|
4
|
-
"description": "Secret scanning and an OpenSSF Scorecard run for any project hosted on GitHub, published or not: gitleaks.yml (gitleaks/gitleaks-action on push, pull request, weekly and manual dispatch) with a .gitleaks.toml, and scorecard.yml (ossf/scorecard-action, weekly, results published as code-scanning alerts). Pure file drop: no hooks, no settings, no scripts, no verify step.
|
|
4
|
+
"description": "Secret scanning and an OpenSSF Scorecard run for any project hosted on GitHub, published or not: gitleaks.yml (gitleaks/gitleaks-action on push, pull request, weekly and manual dispatch) with a .gitleaks.toml, and scorecard.yml (ossf/scorecard-action, weekly, results published as code-scanning alerts). Pure file drop: no hooks, no settings, no scripts, no verify step. gitleaks.yml is read-only; scorecard.yml's analysis job holds security-events: write and id-token: write (the scorecard action's documented minimum). Neither is a required check by default.",
|
|
5
5
|
"modes": ["fresh", "adopt"],
|
|
6
6
|
"budget": {
|
|
7
7
|
"agents": 0,
|
|
@@ -15,5 +15,5 @@
|
|
|
15
15
|
"packageScripts": {},
|
|
16
16
|
"verifySteps": []
|
|
17
17
|
},
|
|
18
|
-
"adoptNotes": "An adopted project that already has its own .github/workflows/gitleaks.yml or scorecard.yml surfaces as an ordinary file conflict -- keep the existing one if it already works, since this pack's version would just replace a configured setup with its generic defaults. gitleaks.yml needs a free GITLEAKS_LICENSE repo secret for an organization-owned repository (gitleaks-action's own requirement); scorecard.yml assumes a public repository (`publish_results: true` needs one) -- set it `false` for a private repo.
|
|
18
|
+
"adoptNotes": "An adopted project that already has its own .github/workflows/gitleaks.yml or scorecard.yml surfaces as an ordinary file conflict -- keep the existing one if it already works, since this pack's version would just replace a configured setup with its generic defaults. gitleaks.yml needs a free GITLEAKS_LICENSE repo secret for an organization-owned repository (gitleaks-action's own requirement); scorecard.yml assumes a public repository (`publish_results: true` needs one) -- set it `false` for a private repo. gitleaks.yml is read-only and scorecard.yml holds security-events: write and id-token: write in its analysis job; neither is a required check by default, so add either to branch protection once it has a clean run. The SPDX/REUSE license-header gate is not part of this pack: it lives in the fresh-only `publishing` pack, because it fails an established project's `pnpm verify` until a one-time backfill touches every file. The two workflows ship without an SPDX header on purpose (a header would carry a project-name token that stays literal in an adopt-mode install); a project that also installs `publishing` gets the headers from that pack's `check-license-headers.mjs --fix` backfill."
|
|
19
19
|
}
|
|
@@ -60,5 +60,5 @@
|
|
|
60
60
|
"packageScripts": {},
|
|
61
61
|
"verifySteps": []
|
|
62
62
|
},
|
|
63
|
-
"adoptNotes": "ensure-worktree-deps.mjs runs `pnpm install --frozen-lockfile --prefer-offline` automatically the first time a session starts inside a freshly created worktree with no node_modules yet -- this runs every dependency's lifecycle scripts the same way any `pnpm install` does, limited only by whatever `allowBuilds`/`onlyBuiltDependencies` policy the project's own pnpm config already sets (see typescript-guidance's pnpm supply-chain coverage if none is set). If the
|
|
63
|
+
"adoptNotes": "ensure-worktree-deps.mjs runs `pnpm install --frozen-lockfile --prefer-offline` automatically the first time a session starts inside a freshly created worktree with no node_modules yet -- this runs every dependency's lifecycle scripts the same way any `pnpm install` does, limited only by whatever `allowBuilds`/`onlyBuiltDependencies` policy the project's own pnpm config already sets (see typescript-guidance's pnpm supply-chain coverage if none is set). If node_modules in the worktree is a symlink (the usual result of `worktree.symlinkDirectories: [\"node_modules\"]` in .claude/settings.json, which this hook never reads), the hook detects the symlink and skips -- installing there would mutate the main checkout's own node_modules through the symlink. guard-worktree-only.mjs blocks every src/tests write outside a linked worktree under .claude/worktrees/, on any branch, for any caller (hub or writer spoke) -- this is stricter than guard-branch-isolation.mjs (which only blocks on main) and guard-hub-src-writes.mjs (which blocks the hub and any non-writer subagent); confirm the team actually wants every change routed through a worktree before installing this pack, since it changes the day-to-day workflow, not just adds a nicety. `.claude/worktrees/` should already be gitignored (the baseline's own .gitignore covers this); if adopting into a project with a hand-rolled .gitignore that doesn't, add it before installing. repair-core-bare.mjs resets `core.bare = true` to `false` in a non-bare repo's shared .git/config at session start and after EnterWorktree/ExitWorktree/Agent calls: Claude Code's worktree tools have been reported to leave it set (anthropics/claude-code#58345, #69802: user bug reports, both since closed as not planned, so whether it still reproduces is unconfirmed), which breaks `git status` in the main checkout. It only acts on a provably non-bare repository (its common git dir is named .git and contains an index), never on a genuine bare repo -- including a bare clone stored in a directory called .git -- and reports a failed repair on stdout rather than silently."
|
|
64
64
|
}
|