@monte3l/groundwork: v1.2.0

1.2.0 (2026-11-05)

Features

• core: move the pinned Node to 26 (2a7dde1)
• core: move the pinned Node to 26 (f0682d4)

Bug Fixes

• deps: bump transitive zod to 4.6.7 for GHSA-mrhx-c7xc-m3w5 (c65c739)
• packs: pin claude-code-action to v1.0.268 and record the 2026-11-04 guidance refresh (cc28704)
• packs: pin claude-code-action to v1.0.268 and record the 2026-11-04 guidance refresh (d7b9287)

@monte3l/groundwork: v1.1.1

1.1.1 (2026-10-23)

Bug Fixes

• baseline: correct mod and fork wording in guard notes (2ad9935)
• baseline: correct the mod and fork wording in the emitted guard notes (896a712)
• deps: bump vitest to 5.0.5 for @vitest/mocker advisories (e9cb0fd)
• packs: cap claude.yml at 20 turns, fix stale changeset rules (#270) (c8e4d07)
• packs: pin claude-code-action to v1.0.258 in the claude-github pack (1bab275)

@monte3l/groundwork@1.1.0

Minor Changes

• #253 f47c0f3 Thanks @enri3l! - pack(frontend): new optional frontend pack for a project that builds UI, with a read-only ui-reviewer agent and a new-component skill. The agent does a static accessibility review of changed components, markup and styles against WCAG 2.2 at level AA (the animation criterion is AAA and is only ever a recommendation) and reports anything that needs a browser, a measurement or assistive technology as NOT CHECKED instead of guessing. It has only Read, Grep and Glob, so the dispatch prompt must name the files to review. The skill ships no framework templates: it mirrors an existing sibling component's conventions and routes the writing through test-author, code-implementer and ui-reviewer. /customize recommends the pack for the frontend kind only; install it with --pack frontend or from /customize.

• #254 87d8422 Thanks @enri3l! - pack(service): new optional service pack for a project that serves an API, with a read-only performance-analyzer agent and an api-doc skill. The agent does a static review of changed server code for blocking calls (the Node.js event-loop guide's list, applied only when the project runs Node), per-request cost and unbounded work, and reports anything that needs profiling or a load test as NOT CHECKED instead of guessing. It has only Read, Grep and Glob, so the dispatch prompt must name the files to review. The skill writes an OpenAPI description from the routes the code actually defines, using a template inside the skill, marks anything it cannot confirm as TODO and unverified, and adds no dependency. /customize recommends the pack for the service kind only; install it with --pack service or from /customize.

Patch Changes

• #258 010e0fd Thanks @enri3l! - pack(frontend, service): tighten the two review agents' static-review rules after a paid eval caught each breaking one. ui-reviewer no longer quotes a contrast ratio against a background the files never set (it must not assume white or any default, and reports the pair to measure as NOT CHECKED). performance-analyzer no longer describes a cost as slow, fast or large or gives a latency formula; it says what grows (round trips, bytes buffered, how long the event loop is blocked) and leaves how much to NOT CHECKED.

• #246 40f2907 Thanks @enri3l! - pack(claude-github): pin anthropics/claude-code-action at v1.0.254 in claude.yml and claude-pr-review.yml. The release only moves the bundled Claude Code from 2.1.303 to 2.1.304. A project that already installed the pack keeps its own pin.

• #250 cc6d620 Thanks @enri3l! - The baseline's permissions.deny now also blocks reading credentials.json and secrets.yaml at any depth, and editing pnpm-lock.yaml, package-lock.json, yarn.lock and the repository's .git/ directory. The edit rules are Edit(...) rules, which Claude Code applies to every built-in file-editing tool, so the package manager and git stay the only writers of those files. A subprocess such as pnpm install still rewrites the lock file, grep -r or a script that opens a denied file is not covered, and in a linked worktree .git is a file the .git/ rule does not match. A fresh project gets the entries. An adopted project with its own .claude/settings.json sees this as a settings.json conflict in /customize (keep, take or merge), and one without it gets the staged file; the CLI never edits an existing settings.json.

• #244 b03b131 Thanks @enri3l! - pack(harness-extras): guard-readonly-bash now judges a read-only agent's Bash command against an allowlist of read verbs instead of a denylist of mutating ones, because the denylist let real writes through. An off-list verb now blocks (awk, python, gh, curl, make, tar, ln, install, patch, rsync, a shell without -c, a verb built through expansion), as does an off-list git subcommand (fetch, archive, submodule update) or write flag (git diff --output, git grep -O), node -e or -p, sed -ni, sed --in-pl, sed scripts that use w or e, sed -f, sort -o, uniq in out, find -fprint, find -exec of an off-list command, and a command substitution that hides one (echo $(rm x)). The allowlist assumes the baseline's toolchain (pnpm, npm, eslint, prettier, tsc, vitest, knip, publint, attw): an adopted project on yarn, make, jest or biome should run its checks through a package.json script, since a read-only agent can no longer call those verbs directly. A script file run through node, pnpm <script> or npm run <script> is still not inspected, so the guard raises the bar and proves nothing. A project that already installed harness-extras keeps its copy of the hook untouched.

• #256 0efd47c Thanks @enri3l! - feat(baseline): scope what the baseline's skills may do. Seven core skills and six pack skills gain allowed-tools (read-only pre-approvals with no wildcard on git, and no gh api), disallowed-tools (Write, Edit, NotebookEdit on the three github-pack skills that only report or act through gh) and argument-hint. allowed-tools only skips the prompt and does not restrict, so every grant is a command that cannot write. starting-work also gains a read-only environment preflight that reports a Node version mismatch, a missing node_modules and missing git hooks, and never installs anything.

• #244 b03b131 Thanks @enri3l! - pack(quality): the type-design-analyzer agent no longer says the read-only Bash guard blocks every shell write route, since the guard is an allowlist that still does not inspect a script file run through node or a package script. A project that already installed the quality pack keeps its copy of the agent untouched.

• #257 20af585 Thanks @enri3l! - pack(worktrees): the working-in-worktrees skill's .env copy step no longer collides with the baseline's Read(./.env) deny rules. It copies with cp -n, never reads or prints a file, and if Claude Code denies the copy it stops and asks the owner to copy the files themselves instead of working around the block.

@monte3l/groundwork@1.0.5

Patch Changes

• #232 4fe7bff Thanks @enri3l! - Refresh the emitted baseline and packs against current Claude Code and TypeScript guidance. templates/core/CLAUDE.md is trimmed under the 200-line startup-warning target (the guard detail moved to agent-dispatch.md), the skill-description grader message now states the real limits, guard-worktree-only fails closed (onFailure: "block"), the claude-github pack's claude-code-action pin moves to v1.0.253, and a few config comments (consistent-type-imports, Vitest coverage, attw) are corrected. A project that already installed the worktrees pack should add "onFailure": "block" to its guard-worktree-only.mjs registration by hand, unless /customize installs the pack again, which now adds the missing key.

• #238 acbd2b9 Thanks @enri3l! - pack(claude-github): the Claude Code GitHub Action workflows (claude.yml and claude-pr-review.yml) move out of the github pack into a new claude-github pack, so the gh-CLI skills can be adopted without a workflow that needs an auth secret and spends API credits on every pull request. --pack github no longer emits either workflow; pass --pack github --pack claude-github for the previous set. /customize recommends claude-github for no project kind by default. A project that already installed github keeps its files untouched.

• #240 359c4d6 Thanks @enri3l! - pack(licensing): the SPDX/REUSE license-header gate (check-license-headers.mjs, its license-headers verify step and the REUSE.toml template) moves out of the publishing pack into a new fresh-only licensing pack, so a project can take the header gate without the npm release pipeline and the other way round. --pack publishing no longer emits the gate or REUSE.toml, and its one-time setup shrinks to pnpm add -D @changesets/cli; pass --pack publishing --pack licensing for the previous set, and run licensing's git add -A / --fix backfill. /customize recommends licensing for library and cli projects, like publishing. A project that already installed publishing keeps its files untouched.

• #239 0fe23b9 Thanks @enri3l! - pack(statusline): the Claude Code status line (statusLine, subagentStatusLine and their three scripts) moves out of the harness-extras pack into a new statusline pack, so a project that already has its own status line can take the compaction-handoff hooks and the read-only Bash guard without a settings collision. --pack harness-extras no longer plants either settings key; pass --pack harness-extras --pack statusline for the previous set. statusline is a live pack name again, so --pack statusline installs it instead of printing a rename hint to harness-extras. A project that already installed harness-extras keeps its files and settings untouched.

@monte3l/groundwork@1.0.4

Patch Changes

• #217 4c33e62 Thanks @enri3l! - The publishing pack's tools/release/package-lock.json is now shipped in the tarball (escaped as _package-lock.json); previously npm-family packing stripped it, so npm ci --ignore-scripts --prefix tools/release had no lockfile in a project bootstrapped with --pack publishing.

@monte3l/groundwork@1.0.3

Patch Changes

• #211 261149f Thanks @enri3l! - Refresh the README shown on npm so it matches the repository (adds the OpenSSF Baseline badge).

@monte3l/groundwork@1.0.2

Patch Changes

• #192 47d90fc Thanks @enri3l! - The npm page now shows the full repository README instead of a short summary, and the package description, homepage and keywords match the GitHub repository.

@monte3l/groundwork@1.0.1

Patch Changes

• #190 40cca6c Thanks @enri3l! - baseline: the emitted settings.json now blocks the call when one of its four invariant guards crashes or times out (guard-secret-writes, guard-hub-src-writes, guard-branch-isolation, guard-protected-paths carry "onFailure": "block", Claude Code 2.1.295 or later) and denies reading .env, .env.* and secrets/**. code-implementer is granted both the mcp__context7__* and the plugin-namespaced mcp__plugin_context7_context7__* tool names. The baseline's CLAUDE.md and agent-dispatch.md now say that a spoke cannot nest because disallowedTools: Agent stops it (Claude Code otherwise allows three layers) and that a session in auto, acceptEdits or bypass mode overrides a spoke's permissionMode. typescript-guidance records a project with no TypeScript toolchain as last-verified=n/a instead of unset, treats a test runner, linter or type-test tool's own documentation (named in the project's devDependencies) as a source for that tool, and harness-guidance notes how far back it read the changelog on a first sweep. Installing a pack now writes .claude/settings.json the way Prettier prints it (a short array of strings stays on one line), so the emitted project's own format check keeps passing after the baseline gained a permissions.deny array.

• #188 68f3ff7 Thanks @enri3l! - adopt: a re-run now also deletes .groundwork/customization-report.md, the report /customize writes at the end of an adopt run, and names it in the removed-files message. The adoption report's .gitignore advice now recommends tracking the two reports and ignoring the rest of .groundwork/. The /customize skill copied into the project replaces the report sections it supersedes, keeps adoption-decisions.json current and resumable, retargets installed skills and agents to the project's tooling, asks before treating a missing .groundwork/ on a repository with commits as a fresh bootstrap, and points its re-run advice at the default latest tag instead of @rc.

@monte3l/groundwork@1.0.0

Major Changes

• #22 7afec0e Thanks @enri3l! - First stable 1.0 release. The public API is frozen as of this release: CLI flags, modes, and exit codes; the .groundwork/inventory.json and adoption-report.md file formats; the .groundwork/packs/ staging layout and pack names; the engines.node floor; and /customize's invocation name. See the README's "Versioning policy" section for the full list and what's explicitly excluded (the baseline's emitted contents, which follow current upstream guidance and can still change in a minor release).

  Only fixes land in the 1.0 series -- any further API change waits for 1.1. Users of the 0.x next tag or a 1.0.0-rc release must switch to latest: SemVer prerelease ranges don't cross from 0.1.0-next.N or 1.0.0-rc.N to 1.0.0 automatically.

Minor Changes

• #11 5c56af2 Thanks @enri3l! - First public release. @monte3l/groundwork bootstraps a TypeScript + Claude Code project (fresh mode) or surveys an existing one read-only (adopt mode). It installs the /customize skill (@monte3l/groundwork-plugin, distributed via the monte3l Claude Code plugin marketplace, not npm) into every project it touches.

• #16 7095714 Thanks @enri3l! - Breaking (allowed pre-1.0; see the upcoming versioning policy): the CLI's argument parsing is now strict. An unrecognized flag, a --name/--pack given with no value (or a value that looks like another flag), more than one positional argument, or --adopt together with --fresh now fail fast with a usage error and exit code 2, instead of being silently accepted or ignored. A genuine runtime error still exits 1. --help/-h and --version/-v are now both documented in the usage text.

  The published package's exports map no longer advertises a "." entry (nor main/types) -- @monte3l/groundwork is a CLI, not a library, and its only supported entry point is the m3l-groundwork binary. Importing it as a JS module was never documented and is no longer possible.

  .groundwork/adoption-report.md's header now also states the inventory's schemaVersion alongside the CLI version that generated it.

Patch Changes

• #184 b32e689 Thanks @enri3l! - 1.0.0 is the same code as 1.0.0-rc.8, published on the latest dist-tag. The package README now says npx @monte3l/groundwork with no @rc.

• #142 8140d8b Thanks @enri3l! - Adopt mode now recognises a Claude Code plugin repository. The inventory moves to schema 6 and records survey.harness.pluginLayout (the .claude-plugin/plugin.json manifest and which of hooks/hooks.json, skills/, agents/, commands/ and .mcp.json exist). The adoption report no longer prints "0 of 0 checks pass" or "100% over 0 checks" when nothing was gradable, says plugin components at the repository root are outside the harness grader's scope, and leaves fresh-only packs (publishing) out of the post-merge cap estimate. /customize gains a plugin project kind, recommends plugin-dev for it, names .claude/ files by full path in CLAUDE.md, and grades the harness after Round 2.

• #93 aac52e3 Thanks @enri3l! - Align the emitted baseline's devDependencies with the repo's own toolchain: vitest and @vitest/coverage-v8 move to ^5.0.2, and eslint, typescript-eslint, knip and the pnpm packageManager pin move to their current minors. TypeScript stays on ^6.0.3.

• #33 7aa6665 Thanks @enri3l! - The emitted baseline's CI workflows now pin every uses: by commit SHA (with a # vX comment naming the tag) instead of a floating major tag, matching this repo's own SHA-pinning discipline: actions/checkout (v6 -> v7), pnpm/action-setup (v4 -> v6), actions/setup-node, actions/dependency-review-action (v4 -> v5), and actions/github-script. A new .github/dependabot.yml (github-actions ecosystem) keeps those pins from going stale. The claude-action pack's workflow gets the same treatment (actions/checkout v6 -> v7, anthropics/claude-code-action v1 -> the exact patch this repo pins).

• #115 1d995fa Thanks @enri3l! - An unexpected CLI failure now prints its error name (TypeError: ...), and setting M3L_DEBUG to any non-empty value also prints its stack trace. Bidirectional-text control characters in error messages are escaped like other control characters. When adopt mode has to stage the /customize skill at .groundwork/customize/, the adoption report's next step now says so, matching the console.

• #91 44d9063 Thanks @enri3l! - Fresh mode now fails before writing anything when it can know the run will not work. Exit-code change: an unknown or fresh-incompatible --pack now exits 2 (a usage error, with the usage text) instead of exiting 1 after half-writing the target; --pack statusline points at harness-extras, which it was folded into. Fresh mode on Windows is refused before anything is written, with exit 1 ("Windows is not supported yet (Linux and macOS only)"); adopt mode, --help, --version and --list-packs still work there. A failed git init or pnpm install after the project is written now exits 1 with one message that says the project was written and what to run by hand, and keeps the original error as its cause, instead of a raw stack trace.

• #30 4592b61 Thanks @enri3l! - The CLI's invocation contract now rejects several previously-silent or wrongly-coded invocations as usage errors (exit code 2), matching the frozen "invalid or contradictory invocations fail fast" policy:

  • Adopt mode now rejects --force and --pack outright with CliUsageError, instead of throwing a plain runtime error (--force, exit 1) or silently ignoring the flag entirely (--pack).
  • --adopt against a target directory that doesn't exist now fails with a clear usage error, instead of an uncaught filesystem exception.
  • A repeated --name (or any future single-value flag) now fails fast, instead of silently keeping the last value.
  • .groundwork/adoption-report.md now detects a git worktree or submodule (.git as a file, not a directory) as an existing project to adopt, instead of misdetecting it as empty.
  • A malformed package.json is now recorded once in the adoption report's undetermined list, instead of being silently dropped (or, in one intermediate state, reported twice).
  • The adoption report's caps table now shows Workflows and Scripts rows, and folds every listed pack's budget into the displayed post-merge total and over-cap warning, instead of omitting two of the five caps and excluding pack budgets from the total it displays.
  • A pack whose pack.json has an internal name not matching its own directory, or a malformed budget, now fails to load with a clear error instead of risking a staging collision or propagating NaN into the caps table.
  • Several smaller robustness fixes: a non-object tsconfig.json/package.json (e.g. literally null) no longer crashes conflict detection; the /customize skill's staleness check now compares all four of its files, not just SKILL.md; a settings-merge collision check no longer misfires on two semantically-identical values that merely have their keys in a different order; re-staging a pack now clears files a newer version dropped.

• #116 57307a7 Thanks @enri3l! - Fresh mode now checks every destination of the baseline, any --pack and the /customize skill before writing anything, and refuses (writing nothing) when one sits under a symlink or a non-directory, or is a symlink or directory where a file goes (a symlink at a /customize skill file is replaced, never written through), so --force no longer writes through a symlinked .claude. The adopt survey records a file or directory it cannot read, or a dangling link or loop, under undetermined instead of aborting. The emitted guard-hub-src-writes.mjs now also blocks writes to or removal of a parent of src/ or tests/, php and deno write verbs and node/python deletes and moves; it remains a conservative screen, not a proof. The emitted check-toolchain step and a...

@monte3l/groundwork@1.0.0-rc.8

Patch Changes

• #176 5ea0732 Thanks @enri3l! - pack(publishing): the release workflow now prints the staged id to approve in the job log and as a run annotation, through a new "Show the staged ids to approve" step. changesets swallows the publisher's stdout, so the id previously appeared nowhere in the log.