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

package/templates/packs/README.md

@@ -18,24 +18,33 @@ templates/packs/<name>/
 
 ## The wiring contract
 
-**A pack never edits YAML or JavaScript.** It may add files under `files/`,
-and may extend three JSON files the baseline already reads at runtime:
+**A pack never edits YAML or JavaScript.** It may add files under `files/`.
+**A pack also can't ship a `.claude/rules/*.md` file**: the harness grader's
+structural `claudemd-refs` rule fails on any rule `CLAUDE.md` doesn't name
+by path, and a pack has no way to edit `CLAUDE.md` (that's not one of the
+three JSON files below either). If a pack needs to state a project-wide
+policy, put it in the body of a skill it ships instead — see the `worktrees`
+pack's `working-in-worktrees` skill for the pattern.
+It may also extend three JSON files the baseline already reads at runtime:
 `.claude/settings.json` (hook registrations, and top-level harness settings
 such as `statusLine`), `package.json` (`scripts`), and
-`bin/lib/verify-steps.packs.json` (gate steps, keyed to one of the five
-fixed verify groups `templates/core/bin/lib/verify-steps.mjs` defines —
-`format`/`lint`/`typecheck`/`build`/`test`). A gate registered this way runs
+`bin/lib/verify-steps.packs.json`. That last file holds gate steps, each
+keyed to one of the five fixed verify groups
+`templates/core/bin/lib/verify-steps.mjs` defines —
+`format`/`lint`/`typecheck`/`build`/`test`. A gate registered this way runs
 under `pnpm verify`, every `lefthook.yml` `pre-push` lane, and every
-`.github/workflows/ci.yml` job automatically, because all three already
-enumerate groups rather than individual steps.
+`.github/workflows/ci.yml` job automatically. That works because all three
+already enumerate groups rather than individual steps.
 
 `pack.json` fields:
 
 - `schemaVersion` — currently `1`.
-- `modes` — `["fresh"]` and/or `["fresh", "adopt"]`. Only artifacts with no
-  dependency on the baseline's exact file layout (an agent, most hooks) are
-  safely adopt-capable; a gate that assumes a specific source layout should
-  say so honestly in `adoptNotes` instead of claiming `adopt`.
+- `modes` — `["fresh"]` and/or `["fresh", "adopt"]`. "Adopt-capable" means
+  an artifact has no dependency on the baseline's exact file layout (an
+  agent, most hooks), so it's safe to install into an already-existing
+  project's own layout. A gate that assumes a specific source layout isn't
+  adopt-capable -- it should say so honestly in `adoptNotes` instead of
+  claiming `adopt`.
 - `budget` — the pack's cap deltas (`agents`/`skills`/`hooks`/`workflows`/
   `scripts`), checked against `templates/core`'s own counts by a structural
   test, never against `templates/core` + every other pack.
@@ -56,6 +65,15 @@ enumerate groups rather than individual steps.
 - `wiring.verifySteps` — entries appended to `bin/lib/verify-steps.packs.json`.
 - `adoptNotes` — free text surfaced verbatim in `/customize`'s Step 0
   confirmation round when the pack applies to an adopted project.
+- `setupSteps` — the exact commands a user must run in the new project after
+  the pack is installed and before the first `pnpm verify`, or verify fails
+  (for example, `publishing` needs `@changesets/cli` added, since a pack can
+  never edit `dependencies`). A non-empty array of single-line, non-empty
+  strings; `loadPack` rejects anything else. Fresh mode prints every installed
+  pack's steps in one block after its `ready` line. Adopt mode neither prints
+  them nor adds them to the inventory (the staged `pack.json` still carries the
+  field verbatim): a pack that is adopt-capable and needs setup says so in
+  `adoptNotes`. Optional.
 
 ## Install path
 
@@ -63,19 +81,21 @@ enumerate groups rather than individual steps.
   repeatable) — it wrote the baseline moments ago, so there's no uncertainty
   to defer.
 - **Adopt mode**: the CLI never installs a pack. It surveys which packs
-  apply and stages their payload at `.groundwork/packs/<name>/`;
-  `/customize`'s Step 0 confirms and Round 1 installs, translating
-  `wiring.verifySteps`/`wiring.settings` against the project's _real_ gate
-  runner and hook config — read for real by that point, not guessed at
-  offline.
+  apply and stages their payload at `.groundwork/packs/<name>/`. Later,
+  `/customize` confirms the install in **Step 0** (its first, up-front
+  confirmation round, before any file is written) and performs it in
+  **Round 1** (the first pass of deterministic edits that follows). That
+  installation translates `wiring.verifySteps`/`wiring.settings` against
+  the project's _real_ gate runner and hook config — read for real by that
+  point, not guessed at offline.
 
 ## Available packs
 
-| Pack             | Contents                                                                                                                                                                                                                                                            |
-| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `harness-extras` | A type-design-analyzer agent, the compaction-handoff hook pair, a read-only Bash guard, and a per-file size ratchet gate — the four artifacts the original baseline build cut purely to hold its caps.                                                              |
-| `statusline`     | A five-row Claude Code status line (session, model, context, quota, work) plus a per-subagent row renderer, both width-fit to the terminal. Registers top-level `statusLine`/`subagentStatusLine` settings, no hooks and no gate. Runs the same on macOS and Linux. |
-
-`github-ops` (dependabot/scan-alert triage skills) and `publishing` (a
-release workflow + npm-publish gates) are documented follow-ups, not yet
-built — see root `CLAUDE.md`'s Known gaps.
+| Pack             | Contents                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `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`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `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`.                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `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`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `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`. |

package/templates/packs/github/files/.claude/skills/reviewing-dependabot-prs/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: reviewing-dependabot-prs
+description: >-
+  Reviews every open Dependabot pull request, classifies each by semver bump
+  level and CI check status, and proposes merge/hold/close per PR -- then
+  acts only on the batch the user confirms, never a PR the user didn't
+  approve. Use for /reviewing-dependabot-prs, "review the dependabot PRs",
+  "triage dependency updates", or when several Dependabot PRs have
+  accumulated. GitHub stance: gh CLI.
+---
+
+Triage every open Dependabot pull request in this repository: classify each
+by how risky its bump is and whether its checks are green, propose an
+action per PR, then act only on the batch the user actually confirms. This
+skill never merges or closes a PR the user hasn't approved, and never
+guesses at a version bump's safety from the checks alone -- a major bump is
+always held for a human look, checks or no checks.
+
+## Steps
+
+### 1 — List every open Dependabot PR
+
+```bash
+gh pr list --search "author:app/dependabot" --state open --limit 100 --json \
+  number,title,headRefName,isDraft,mergeable,statusCheckRollup
+```
+
+`--limit 100` avoids `gh pr list`'s 30-result default silently truncating a
+large backlog. If this returns nothing, report that there is nothing to
+triage and stop.
+
+### 2 — Classify each PR's bump level
+
+Dependabot's own titles follow `Bump <package> from <old> to <new>` (or
+`Bump <package> in <dir> from <old> to <new>` for a monorepo/directory-scoped
+config) -- but a project with a `commit-message.prefix` in its
+`dependabot.yml` gets a prefixed, often-lowercased title instead, e.g.
+`chore(deps): bump <package> from <old> to <new>`. Match case-insensitively
+and allow an optional prefix before `bump`, then parse `<old>`/`<new>` and
+compare them as semver:
+
+- **major**: the leftmost _non-zero_ version segment differs (not simply
+  the first segment -- under semver a `0.x` package treats its second
+  segment as breaking, so `0.3.0 -> 0.4.0` is major, not minor). A major
+  bump is a breaking-change risk by definition, regardless of check status.
+- **minor**/**patch**: lower risk, but still gated on checks (next step).
+- **unparseable** (a non-semver ecosystem, a grouped-update PR covering
+  several packages, or a title that doesn't match the pattern even with the
+  prefix/case allowance above): mark it **unknown** and never guess a risk
+  level for it -- always propose _hold_ for a human look, and say why
+  parsing failed.
+
+### 3 — Classify each PR's check status and mergeability
+
+`statusCheckRollup` mixes two entry shapes: a GitHub Actions **check run**
+(carries `conclusion`) and a third-party **commit status** (carries `state`
+instead -- no `conclusion` field at all). Read whichever field the entry
+actually has, and reduce the whole set to one of:
+
+- **green**: every entry's `conclusion` is `SUCCESS`, `NEUTRAL`, or
+  `SKIPPED` (not a failure), or its `state` is `SUCCESS`.
+- **red**: at least one entry's `conclusion` is `FAILURE`, `CANCELLED`,
+  `TIMED_OUT`, `ACTION_REQUIRED`, `STARTUP_FAILURE`, or `STALE`, or its
+  `state` is `FAILURE`/`ERROR`.
+- **pending**: at least one entry is still queued/in-progress (`conclusion`
+  absent, or `state: PENDING`) and none are red.
+- **no checks configured**: `statusCheckRollup` is empty -- this is _not_
+  the same as green; propose **hold** and say the repository has no CI
+  configured for this PR, rather than treating silence as success.
+
+Also read `mergeable`: a PR reported as `CONFLICTING` is never proposed for
+merge regardless of bump level or check status. A draft PR (`isDraft:
+true`) is never proposed for merge either.
+
+### 4 — Propose an action per PR
+
+| Bump level          | Checks    | Mergeable        | Draft | Proposal                                              |
+| ------------------- | --------- | ---------------- | ----- | ----------------------------------------------------- |
+| patch/minor         | green     | yes              | no    | **merge**                                             |
+| patch/minor         | red       | any              | no    | **hold** -- name the failing check                    |
+| patch/minor         | pending   | any              | no    | **hold** -- checks still running, re-check later      |
+| patch/minor         | no checks | any              | no    | **hold** -- no CI configured, needs a human look      |
+| any                 | any       | no (conflicting) | any   | **hold** -- merge conflict, needs a rebase/human look |
+| major               | any       | any              | no    | **hold** -- breaking-change risk, needs a human read  |
+| unknown/unparseable | any       | any              | any   | **hold** -- couldn't classify the bump safely         |
+| any                 | any       | any              | yes   | **skip** -- draft PR                                  |
+
+For a **held** PR whose changelog or release notes look clearly abandoned,
+irrelevant, or superseded by a newer PR for the same package, note **close**
+as an alternative to raise with the user in the next step -- this skill
+never closes a PR on its own initiative, only on explicit confirmation.
+
+### 5 — Present the report and confirm the batch
+
+Show one table: PR number, title, bump level, check status, mergeable,
+proposed action. Then ask the user which of the **merge**-proposed PRs to
+actually merge, and separately whether any **held** PR should instead be
+**closed** -- offer "all of them", a subset by number, or none for each.
+Never treat silence or a general "looks good" as consent to act; get an
+explicit list or an explicit "yes, all of them" for merges, and a separate
+explicit confirmation for any close.
+
+### 6 — Act only on the confirmed batch
+
+For each confirmed merge:
+
+```bash
+gh pr merge <number> --squash --auto
+```
+
+Prefer `--squash` (the common convention for a Dependabot PR), but if `gh`
+rejects it (squash merges disabled by the repository, or "Allow auto-merge"
+itself is off -- GitHub's own default), fall back to whichever merge method
+the repository actually allows (`--merge`/`--rebase`, or drop `--auto` and
+report that the PR is ready but must be merged by hand) rather than treating
+the rejection as this skill's own failure. `--auto` arms auto-merge rather
+than forcing an immediate merge -- if the repository's branch protection
+requires checks or reviews, the merge still waits for those; this skill does
+not bypass a repository's own merge rules. If `gh pr merge` reports the PR
+isn't mergeable (a conflict, a newly-failed check since step 1), report that
+PR's failure and continue with the rest of the batch rather than aborting it.
+
+For each confirmed close:
+
+```bash
+gh pr close <number> --comment "<one-line reason from step 4>"
+```
+
+### 7 — Report outcomes
+
+Summarize what was merged, what's queued behind `--auto`, what was closed,
+and what was held or skipped, with a one-line reason for every held/skipped/
+closed PR.

package/templates/packs/github/files/.claude/skills/triaging-scan-alerts/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: triaging-scan-alerts
+description: >-
+  Fetches this repository's open code-scanning alerts via gh api, groups
+  them by tool and severity, and maps each to its file:line -- the output
+  is a triage report and options only, it never edits code. Use for
+  /triaging-scan-alerts, "review the scan alerts", "what does CodeQL flag",
+  "triage the security findings", or after a code-scanning workflow run.
+  GitHub stance: gh CLI.
+---
+
+Fetch every open code-scanning alert for this repository, group it by
+which tool raised it and how severe it is, and map each to the exact
+file and line it points at. This skill produces a report and a set of
+options per alert -- it never edits code, dismisses an alert, or opens a
+PR on its own.
+
+## Steps
+
+### 1 — Fetch open alerts
+
+```bash
+gh api 'repos/{owner}/{repo}/code-scanning/alerts?state=open' \
+  --paginate \
+  -q '.[] | {number, tool: .tool.name, severity: .rule.security_severity_level // .rule.severity, rule: .rule.id, path: .most_recent_instance.location.path, line: .most_recent_instance.location.start_line, description: .rule.description}'
+```
+
+(`state=open` is in the query string, not a `-f` field -- `gh api` switches
+to `POST` the moment any `-f`/`-F` field is passed without an explicit
+`--method GET`, which would break this list call. The whole path is single-
+quoted because `?` is a glob character in zsh -- macOS's default shell --
+and an unquoted one there fails with "no matches found" before `gh` runs.)
+
+Use the current repository (`gh` infers `{owner}/{repo}` from the working
+directory's remote when the placeholders are left as-is). If the endpoint
+returns a 404 or a permissions error, code scanning may not be enabled on
+this repository -- report that plainly rather than treating it as "no
+alerts".
+
+### 2 — Group by tool and severity
+
+Group the results by `tool` (CodeQL, a third-party SARIF uploader, etc.)
+first, then by `severity` within each tool (`critical`/`high`/`medium`/
+`low`, or the tool's own scale if it doesn't use those exact words --
+report the tool's own label rather than forcing it into one of the four).
+
+### 3 — Map each alert to file:line
+
+Every alert in the fetched output already carries `path`/`line` from its
+most recent instance -- present these verbatim (`path:line`) so the user
+can jump straight to the code. If `path`/`line` is absent (some
+alert-generating tools don't localize to a line), say so rather than
+inventing a location.
+
+### 4 — Present the report
+
+One table per tool, ordered severity-first: alert number, rule id, one-line
+description, `path:line`, severity. Note the total open-alert count at the
+top.
+
+### 5 — Offer options per alert -- never act automatically
+
+For each alert, describe (not perform) the realistic options:
+
+- **fix now**: a one-line description of what the fix would look like, if
+  obvious from the rule/description -- this skill still does not make the
+  edit itself; the option is to hand it to a code-writing task.
+- **dismiss as false positive** / **won't fix** / **used in tests**: the
+  three reasons GitHub's own dismissal UI accepts, named but not run:
+  ```bash
+  gh api -X PATCH repos/{owner}/{repo}/code-scanning/alerts/{number} \
+    -f state=dismissed -f "dismissed_reason=false positive"
+  ```
+  (swap the quoted value for `won't fix` or `used in tests` -- each contains
+  a space or apostrophe, so it must stay quoted as one shell argument).
+- **needs a human decision**: for anything ambiguous (a finding in
+  generated code, a suppressed pattern that might be intentional).
+
+Ask the user which option applies before running any dismissal command --
+this skill's own default is to report, not to close anything out.
+
+### 6 — Note the adjacent alert surfaces this skill doesn't cover
+
+Dependabot alerts (`gh api repos/{owner}/{repo}/dependabot/alerts`) and
+secret-scanning alerts (`gh api repos/{owner}/{repo}/secret-scanning/alerts`)
+are separate GitHub endpoints from code-scanning -- if the user asks about
+either, say so and fetch that endpoint too rather than assuming this
+skill's code-scanning report already covers it.

package/templates/packs/github/files/.claude/skills/watching-pr-checks/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: watching-pr-checks
+description: >-
+  Checks a pull request's CI status via gh pr checks: reports ready-to-merge
+  and asks before merging on green, or reads the real failing job log and
+  hands off to /triaging-ci on red -- never guesses at a failure from the
+  check name alone. Use for /watching-pr-checks, "check this PR's status",
+  "is this PR ready to merge", "did CI pass on my PR". GitHub stance: gh
+  CLI.
+---
+
+Check one pull request's CI status and act on what the checks actually
+say, rather than assuming green or guessing at a failure. This is a
+single check, not a polling loop -- if checks are still running, report
+that plainly and let the user decide whether to ask again later or wait.
+
+## Steps
+
+### 1 — Resolve the PR
+
+If the user gave an explicit PR number or URL, use it. Otherwise, resolve
+the PR for the current branch:
+
+```bash
+gh pr view --json number,headRefName,state
+```
+
+If there is no PR for the current branch, or its `state` isn't `OPEN` (a
+merged or closed PR still resolves by branch name), say so and stop --
+there is nothing to watch.
+
+### 2 — Check status
+
+```bash
+gh pr checks <number> --json name,bucket,link,workflow
+```
+
+`bucket` (not `conclusion` -- `gh pr checks --json` has no `conclusion`
+field) is the ready-made summary each check reduces to: `pass`, `fail`,
+`pending`, `skipping`, or `cancel`. Reduce the whole set to one of:
+
+- **all green**: every check's `bucket` is `pass` or `skipping`.
+- **still running**: at least one `pending` and none `fail`/`cancel`.
+- **failed**: at least one `fail` or `cancel`.
+- **no checks configured**: the list is empty -- report this plainly rather
+  than treating it as either green or failed; there is nothing to watch
+  until the repository has CI wired up for this PR.
+
+### 3a — All green
+
+Report the PR is ready to merge, name every check that passed, and ask the
+user before merging -- never merge without that confirmation, even when
+every check is green:
+
+```bash
+gh pr merge <number> --squash --auto
+```
+
+If `gh` rejects `--squash --auto` (squash merges disabled, or "Allow
+auto-merge" itself is off -- GitHub's own default), fall back to whichever
+merge method the repository actually allows, or drop `--auto` and report
+that the PR is ready but must be merged by hand -- don't report the
+rejection as this skill's own failure. (`--auto` respects any
+branch-protection requirement still pending -- see
+`reviewing-dependabot-prs`'s step 6 for the same reasoning if that skill is
+also installed.)
+
+### 3b — Still running
+
+Report which checks are still pending and which have already passed. Do
+not guess at the eventual outcome. Suggest the user re-invoke this skill
+in a few minutes, or -- if the calling session supports scheduling a
+recurring check -- offer to check again automatically rather than blocking
+on a manual re-ask.
+
+### 3c — Failed
+
+Do not report the failure from the check's name alone -- pull the actual
+job log before describing what went wrong. The failing check's `workflow`
+field distinguishes a GitHub Actions run (has a log `gh run view` can read)
+from a third-party check (a status-only integration with no run to fetch):
+
+```bash
+gh run view <run-id> --log-failed
+```
+
+(`<run-id>` comes from the failing check's `link`, a
+`.../actions/runs/<run-id>/job/...` URL -- a check with no such `link`, or
+whose `workflow` is empty, is from an external app; report its `link` and
+that no log is available to read rather than guessing at why it failed.)
+Once the real failure is in hand, hand off to `/triaging-ci` (if the
+project has it installed) to map the failure to its root cause and present
+fix options -- this skill's own job ends at "here's what actually failed
+and why," not at proposing or applying a fix.