actions-warden 0.2.0 → 0.3.0

package/docs/CONFIGURATION.md

@@ -0,0 +1,340 @@
+# Configuration, ignores, and baselines
+
+actions-warden can run with built-in defaults, or load a versioned policy from
+the repository being scanned.
+
+## Policy discovery
+
+The default filenames are:
+
+```text
+.actions-warden.yml
+.actions-warden.yaml
+```
+
+If both exist, `.actions-warden.yml` wins. Select another file with `--config`,
+or skip repository policy with `--ignore-config`:
+
+```sh
+actions-warden audit --config=security/actions-warden.yml
+actions-warden audit --ignore-config
+```
+
+The policy path must resolve inside `--cwd`, including after symlink
+resolution. `--config` and `--ignore-config` are mutually exclusive.
+
+Configuration is strict by design. Unknown top-level keys, unknown rule IDs,
+unknown nested keys, invalid severities, and values of the wrong type stop the
+scan. This prevents a typo from silently weakening policy.
+
+## Complete policy shape
+
+```yaml
+version: 1
+baseline: .actions-warden-baseline.json
+
+ignore-paths:
+  - .github/workflows/generated/**
+  - .github/actions/vendor/**
+
+rules:
+  excessive-permissions:
+    enabled: true
+    severity: high
+  unpinned-container-image:
+    enabled: false
+
+runner-policy:
+  self-hosted-labels:
+    - private-*
+    - arc-*
+  trusted-groups:
+    - github-hosted-*
+  flag-unknown-groups: true
+```
+
+| key | type | default | meaning |
+|---|---|---|---|
+| `version` | integer | `1` | Policy schema; if present, must be `1` |
+| `baseline` | non-empty string | none | Baseline path relative to `--cwd` |
+| `ignore-paths` | string array | `[]` | Picomatch globs excluded before parsing |
+| `rules` | mapping | `{}` | Per-rule enablement and severity overrides |
+| `runner-policy` | mapping | built-in defaults | Additional self-hosted runner selectors and group trust |
+
+Rule policies accept only:
+
+| key | type | default |
+|---|---|---|
+| `enabled` | boolean | `true` |
+| `severity` | `low`, `medium`, `high`, or `critical` | rule default |
+
+A CLI `--baseline` overrides the policy's `baseline`. A CLI `--severity`
+filters after any configured severity override.
+
+## Rule IDs
+
+Use the installed version as the source of truth:
+
+```sh
+actions-warden rules --format=json
+```
+
+The current built-in rules are:
+
+| ID | default severity | detects |
+|---|---|---|
+| `unpinned-action` | high | External actions and reusable workflows without a full commit SHA |
+| `unpinned-docker-action` | high | Mutable `docker://` action images |
+| `unpinned-container-image` | high | Mutable job, service, or Docker action images |
+| `excessive-permissions` | medium | Broadly writable workflow or job `GITHUB_TOKEN` permissions |
+| `secrets-in-env` | medium | Named job secrets exposed broadly; workflow-wide or dynamic all-secret exposure is high |
+| `script-injection` | critical | Untrusted GitHub context, including tainted `env`, interpolated into a shell or script action |
+| `pull-request-target-checkout` | critical | Privileged pull-request code retrieval without an active checkout guard |
+| `reusable-workflow-secrets-inherit` | high | External reusable workflows receiving every caller secret |
+| `untrusted-self-hosted-runner` | high | Untrusted pull-request code reaching self-hosted infrastructure |
+| `workflow-run-artifact-execution` | critical | Privileged `workflow_run` jobs executing cross-run artifacts |
+| `workflow-structure` | medium | Structurally invalid workflow or composite-action syntax |
+
+Rule findings may adjust severity based on the recognized pattern. A configured
+severity override is applied to every finding produced by that rule.
+
+## Rule accuracy and analysis boundaries
+
+The audit is static and offline. It parses YAML and follows a small amount of
+local data flow, but it does not evaluate expressions, call referenced actions,
+inspect organization settings, or execute workflow code. Findings therefore
+describe a recognized risk pattern and its evidence, not a proof that every
+runtime path is exploitable.
+
+The current rule boundaries are deliberate:
+
+- `unpinned-action` requires a full 40-character commit SHA for external
+  actions and reusable workflows. Workspace-relative `./` references and
+  GitHub's `$/` self-repository references are not external dependencies. A
+  `$/` reference follows the exact workflow commit and requires runner 2.336.0
+  or newer, cannot include an `@ref` suffix, and is not available on GitHub
+  Enterprise Server; see GitHub's [self-repository syntax announcement](https://github.blog/changelog/2026-07-30-reference-same-repository-actions-with-self-repository-syntax/).
+- `excessive-permissions` treats a missing top-level declaration as a low
+  advisory because token defaults are configurable. It reports `write-all` and
+  maps with at least three writable scopes, but does not guess that one
+  purpose-specific write scope is unnecessary. Invalid permission values are
+  reported by `workflow-structure` instead.
+- `secrets-in-env` reports a named secret at job scope as medium, and raises
+  workflow-wide scope, dynamic indexing, and `toJSON(secrets)` to high. GitHub
+  may need to expose every available secret to resolve a dynamic reference.
+  Job scope can be necessary for a secret-dependent `if` condition; in that
+  case every job step should be trusted and the secret should carry minimal
+  privilege. A named step-scoped secret is outside this rule, but dynamic or
+  all-secret access is reported even at step scope.
+- `script-injection` follows known attacker-controlled GitHub fields directly
+  into `run` and `actions/github-script`, and through workflow, job, or step
+  `env` when the script re-interpolates `${{ env.NAME }}`. The safe boundary is
+  native shell syntax such as `"$NAME"` or JavaScript `process.env.NAME`, as in
+  GitHub's [CodeQL recommendation](https://codeql.github.com/codeql-query-help/actions/actions-code-injection-critical/).
+- `pull-request-target-checkout` understands GitHub's June 2026 checkout
+  protection and its July 20 backport for floating `actions/checkout` v2-v7
+  tags, protected release
+  versions (`v2.8.0`, `v3.7.0`, `v4.4.0`, `v5.1.0`, `v6.1.0`, and v7+), and the
+  exact known release SHAs. It still reports an explicit or expression-driven
+  `allow-unsafe-pr-checkout`, older versions, direct `git`/`gh` fetches, and
+  unknown pinned SHAs. Version comments are not trusted as security evidence.
+  A protected floating major can therefore avoid this finding while still
+  producing `unpinned-action`; the two rules cover different risks. See
+  GitHub's [checkout protection announcement](https://github.blog/changelog/2026-06-18-safer-pull_request_target-defaults-for-github-actions-checkout/).
+- `workflow-run-artifact-execution` treats the official
+  `actions/download-artifact` action as cross-run only when `run-id` selects
+  another run. A same-run download is not enough to trigger the rule. Artifact
+  paths under `${{ runner.temp }}` remain isolated from unrelated workspace
+  commands, but execution or loading from that exact path is still reported.
+- `untrusted-self-hosted-runner` reports ordinary `pull_request` jobs on
+  recognized self-hosted selectors. For `pull_request_target`, it requires a
+  recognized unsafe PR checkout or direct fetch instead of assuming that a
+  trusted labeling job executes fork code. Literal matrix dimensions and
+  `include` entries are followed when `runs-on` selects a matrix key. Matrices
+  generated by expressions still require manual review. Use `runner-policy`
+  for organization-specific labels and groups.
+- `workflow-structure` checks required trigger/job/step shapes, reusable-job
+  conflicts, permission values, and composite run-step shells. It recognizes
+  GitHub's current `background`, `wait`, `wait-all`, `cancel`, and `parallel`
+  step syntax, validates the documented control shapes, and recursively scans
+  actions and scripts inside `parallel` groups. Background and parallel steps
+  authored inside composite actions are reported because GitHub does not
+  support them there. See GitHub's [current concurrent-step
+  syntax](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstepsbackground).
+  This rule is not a full replacement for GitHub's server-side workflow
+  validator.
+
+Execution recognition is intentionally conservative but finite: it covers
+common shell scripts, package managers, build/test commands, local actions, and
+build-like third-party actions. A custom action or unusual interpreter can
+consume untrusted files without being recognized. Review privileged
+`pull_request_target` and `workflow_run` jobs manually, and use GitHub Actions
+CodeQL alongside this audit when complete interprocedural analysis is needed.
+
+## Runner policy
+
+The self-hosted runner rule always recognizes the literal `self-hosted` label.
+Policy can add organization-specific labels and group handling:
+
+```yaml
+runner-policy:
+  self-hosted-labels:
+    - linux-prod-*
+    - arc-runner-*
+  trusted-groups:
+    - github-hosted-*
+  flag-unknown-groups: true
+```
+
+`self-hosted-labels` and `trusted-groups` use Picomatch glob syntax.
+
+GitHub runner groups are not assumed unsafe by default because a group may
+select GitHub-hosted infrastructure. When `flag-unknown-groups` is `true`, a
+pull-request job using a group is reported unless the group matches
+`trusted-groups`.
+
+## Path exclusions
+
+`ignore-paths` is applied before a workflow is parsed:
+
+```yaml
+ignore-paths:
+  - .github/workflows/generated/**
+  - .github/actions/third-party/**
+```
+
+For a local audit, paths are relative to `--cwd`. For `org-scan`, the local
+organization policy applies to every repository and paths begin with
+`owner/repository/`:
+
+```yaml
+ignore-paths:
+  - my-org/generated-repo/.github/workflows/**
+  - my-org/archive-*/.github/actions/**
+```
+
+A path exclusion removes the file from coverage. Use it for generated or
+vendored sources whose ownership and review process is understood, and protect
+policy changes like code.
+
+## Inline ignore directives
+
+Use an inline directive when a specific finding has been reviewed and the file
+should remain in scan coverage.
+
+Ignore one rule on the same line:
+
+```yaml
+- uses: owner/action@v1 # actions-warden-ignore: unpinned-action
+```
+
+Ignore the next non-empty, non-comment line:
+
+```yaml
+# actions-warden-ignore-next-line: excessive-permissions
+permissions: write-all
+```
+
+Ignore a block:
+
+```yaml
+# actions-warden-ignore-start: workflow-structure
+permissions:
+# actions-warden-ignore-end
+```
+
+Ignore a rule for the whole file:
+
+```yaml
+# actions-warden-ignore-file: unpinned-action
+```
+
+The short `aw-` prefix is also accepted, for example
+`# aw-ignore-next-line: script-injection`. Multiple rule IDs may be separated by
+commas or whitespace. Omitting rule IDs suppresses every rule in that scope;
+prefer naming the narrowest rule so future checks remain active.
+
+Unmatched `ignore-start` directives extend to the end of the file. An
+`ignore-end` without an open block has no effect.
+
+## Baselines
+
+A baseline accepts existing, reviewed findings while allowing new findings to
+fail the scan.
+
+Create one from the current unfiltered finding set:
+
+```sh
+actions-warden audit \
+  --create-baseline=.actions-warden-baseline.json
+```
+
+The command writes a deterministic document:
+
+```json
+{
+  "schemaVersion": "1.0",
+  "generatedBy": "actions-warden",
+  "findings": [
+    {
+      "id": "18b82e86d7c14fe2",
+      "fingerprint": "a5c4f4a2797d17d9",
+      "ruleId": "unpinned-action",
+      "severity": "high",
+      "file": ".github/workflows/ci.yml",
+      "line": 14
+    }
+  ]
+}
+```
+
+Load it explicitly:
+
+```sh
+actions-warden audit \
+  --baseline=.actions-warden-baseline.json
+```
+
+or through policy:
+
+```yaml
+version: 1
+baseline: .actions-warden-baseline.json
+```
+
+Each finding has two matching identities:
+
+- `id` identifies the exact repository-relative source occurrence and is stable
+  across clones;
+- `fingerprint` ignores line movement while retaining semantic fields, file,
+  rule, and source-order ordinal for equivalent duplicates.
+
+A baseline match suppresses the finding from `findings`. The summary still
+reports `totalFindings` and `suppressed`. Parser failures cannot be baselined.
+
+Review baseline diffs carefully. Deleting a finding from the baseline makes it
+active again; adding one accepts that risk without changing the workflow.
+
+## Policy ownership
+
+Treat these files as security controls:
+
+```text
+.actions-warden.yml
+.actions-warden.yaml
+.actions-warden-baseline.json
+```
+
+Recommended controls include:
+
+- require review from a security or platform owner through `CODEOWNERS`;
+- prevent unreviewed direct pushes with branch protection;
+- show policy and baseline diffs in dependency-maintenance pull requests;
+- avoid granting a scanning pull request permission to rewrite its own policy.
+
+## Related guides
+
+- [CLI reference](./CLI.md)
+- [Output contracts](./OUTPUTS.md)
+- [GitHub Action](./GITHUB-ACTION.md)
+- [Security policy](../SECURITY.md)

package/docs/DEVELOPMENT.md

@@ -0,0 +1,350 @@
+# Developer guide
+
+This guide is for contributors changing actions-warden itself. For public CLI
+usage, start with the [CLI reference](./CLI.md).
+
+## Prerequisites
+
+- Node.js 20 or newer;
+- npm with the lockfile committed by the repository;
+- optional: `prek` or Python `pre-commit` for local hooks.
+
+Install exactly the locked dependency graph:
+
+```sh
+npm ci
+```
+
+The repository's `.npmrc` pins dependencies exactly and disables package
+lifecycle scripts during installation.
+
+Install hooks with either runner:
+
+```sh
+prek install --hook-type pre-commit --hook-type pre-push
+```
+
+or:
+
+```sh
+pre-commit install --hook-type pre-commit
+pre-commit install --hook-type pre-push
+```
+
+## Validation commands
+
+| command | purpose |
+|---|---|
+| `npm test` | Run the complete Vitest suite once |
+| `npm run test:watch` | Run Vitest in watch mode |
+| `npm run lint` | Lint source, scripts, and tests |
+| `npm run check:yaml` | Parse repository YAML files |
+| `npm run check:docs` | Validate local documentation links |
+| `npm run check:package` | Inspect the exact npm tarball manifest, required files, executable mode, and size bounds |
+| `npm run verify-deps` | Require exact runtime and development versions |
+| `npm run verify-version-sync` | Keep package, lockfile, bundled runtime, plugin, and public invocations aligned |
+| `npm run build:action` | Rebuild the committed Action bundle |
+| `npm run check:action-bundle` | Compare a clean rebuild with working and staged bundles |
+| `npm run audit` | Run the configured npm vulnerability threshold |
+| `npm run release:prepare -- X.Y.Z` | Update all local stable-version sources without committing or publishing |
+| `npm run release:check` | Gate a staged release candidate against npm state and every release validation |
+
+Before opening a pull request, run:
+
+```sh
+npm run verify-version-sync
+npm run verify-deps
+npm run check:yaml
+npm run check:docs
+npm run check:package
+npm run lint
+npm test
+npm run audit
+```
+
+If code reachable from `src/action.js` changed, also run:
+
+```sh
+npm run build:action
+npm run check:action-bundle
+```
+
+## Repository map
+
+```text
+src/
+  cli.js                    CLI parsing, exit codes, and output routing
+  action.js                 GitHub Action input/output adapter
+  index.js                  public JavaScript exports
+  version.js                runtime version embedded in the Action bundle
+  commands/                 audit, pin, verify, upgrade, report, org-scan
+  lib/
+    parser.js               YAML-to-normalized-workflow model
+    targets.js, paths.js    repository target discovery
+    config.js, baseline.js  policy and accepted-finding controls
+    resolver.js, cache.js   GitHub API, caching, ref and ownership checks
+    github-org.js           read-only organization/tree/blob access
+    agent-mode.js           explicit bounded AI-agent CLI defaults
+    org-checkpoint.js       validated atomic organization resume state
+    org-progress.js         human rendering of structured scan progress
+    identity.js             stable IDs and semantic fingerprints
+    patcher.js, writer.js   source-range rewrites and guarded atomic writes
+    formatter.js, redact.js structured output and credential redaction
+    annotations.js          GitHub workflow annotations
+    concurrency.js          bounded async work
+  rules/                    one module per audit rule
+
+test/                       Vitest suites and hostile/edge-case fixtures
+scripts/                    repository validation and release helpers
+docs/                       user, integration, AI, and developer guides
+examples/                   copyable GitHub workflow examples
+skills/actions-warden/      Claude Code skill
+dist/                       generated, committed GitHub Action bundle
+action.yml                  public Action inputs, outputs, and runtime
+```
+
+## Data flow
+
+A local audit follows this path:
+
+```text
+targets → source read → YAML parser → normalized workflow model
+        → ignore directives → rules → stable identities
+        → severity/baseline filtering → renderer
+```
+
+Pin and upgrade add:
+
+```text
+normalized action refs → GitHub resolution and ownership verification
+                       → source-range patch plan → reparse
+                       → guarded atomic writer only when dryRun=false
+```
+
+An organization scan follows:
+
+```text
+repository listing → default-branch Git tree → bounded YAML blob reads
+                   → in-memory auditSources → repository aggregation
+
+optional checkpoint → identity validation → fresh tree SHA comparison
+                    → reuse unchanged error-free result or rescan
+```
+
+Remote repositories are never cloned, checked out, imported, or executed.
+
+## Safety invariants
+
+Changes must preserve these boundaries:
+
+- `pin` and `upgrade` default to dry-run at the command and API layers.
+- CLI and Action mutation require an explicit write option.
+- A resolver failure must not fall back to a guessed tag or SHA.
+- Commits must be verified as belonging to the referenced repository.
+- Workflow rewrites operate on parsed scalar ranges and reparse before write.
+- Writes and configured paths remain inside the real repository root.
+- Symlink escapes and explicit targets that match nothing fail.
+- Credentials are redacted in JSON, TOON, text, SARIF, annotations, and
+  top-level errors.
+- Finding and change IDs exclude absolute checkout paths.
+- Parser errors remain findings and cannot be baselined away.
+- Organization coverage failures remain visible and make status fail.
+- Organization source reads remain count- and size-bounded and bypass disk
+  cache.
+- Organization resume never trusts a stale result without fresh discovery and
+  a matching repository identity, default branch, and tree SHA. Failed results
+  are never reused.
+- Checkpoints use guarded atomic writes, remain inside the working directory,
+  omit tokens and raw YAML, and cannot replace active policy or baseline files.
+- Progress stays outside deterministic report serialization; CLI progress is
+  stderr-only and Action progress cannot form workflow commands.
+- Agent mode is an explicit opt-in, never a TTY, parent-process, CI, or
+  vendor-environment heuristic. Explicit CLI output and progress options win.
+  Its automatic artifact key uses the validated checkpoint identity, and its
+  stdout receipt never includes findings or repository result arrays.
+- Attacker-controlled values cannot forge TOON lines or GitHub annotations.
+
+Tests should demonstrate the fail-closed behavior for any change touching these
+boundaries.
+
+## Adding or changing a rule
+
+A rule module exports:
+
+```js
+export const id = 'example-rule';
+export const severity = 'high';
+export const description = 'Short sentence describing the risk.';
+
+export function check(workflow, context = {}) {
+  return [{
+    id,
+    severity,
+    line: 1,
+    fields: {
+      type: id,
+      sev: severity,
+      evidence: 'structured-value',
+    },
+    explain: 'one concise remediation',
+  }];
+}
+```
+
+Then:
+
+1. register the module in `src/rules/index.js`;
+2. add focused tests for safe and unsafe cases;
+3. test trigger, expression, quoting, and malformed-input boundaries relevant
+   to the rule;
+4. when behavior depends on a moving GitHub or first-party action contract,
+   verify it against a primary source, record the date/version boundary in code,
+   and test the last unsafe plus first safe version;
+5. test at least one legitimate pattern that must remain clean so remediation
+   guidance does not become a false-positive generator;
+6. update the rule table and accuracy boundaries in `docs/CONFIGURATION.md`,
+   plus the Claude skill;
+7. run `actions-warden rules --format=json` and ensure the ID is not redacted;
+8. rebuild the Action bundle.
+
+Keep `fields` structured and concise. They become JSON evidence, TOON fields,
+SARIF messages, and Action annotations. Never place raw secret values in them.
+Suggestions must name a safe end state, preserve legitimate use cases, and
+avoid claiming that one mitigation closes risks outside the rule's evidence.
+
+## Adding or changing a command
+
+A command normally needs changes in:
+
+1. `src/commands/<name>.js` for the API result and renderer;
+2. `src/cli.js` for public CLI flags and exit semantics;
+3. `src/index.js` and `package.json` exports;
+4. `src/action.js` and `action.yml` if the Action exposes it;
+5. command, CLI, Action, annotation, and output-format tests;
+6. `docs/CLI.md`, `docs/OUTPUTS.md`, API docs, and relevant examples;
+7. the Claude skill and version-sync checker when its command surface changes;
+8. the committed Action bundle.
+
+Return operational problems as structured `errors` when useful work can
+continue. Throw when top-level input or discovery makes the requested scope
+undefined or unsafe.
+
+Every non-JSON renderer must expose enough information to explain a `FAIL`
+status. Every JSON renderer must include `schemaVersion`, command data, and
+top-level `status`.
+
+## Parser and patcher changes
+
+The parser retains both a normalized model for rules and source locations for
+precise rewrites. When changing it:
+
+- cover workflow files and composite `action.yml` metadata;
+- preserve and recursively inspect steps inside `parallel` groups, while
+  retaining background/control-step declarations for structure checks;
+- include quoted, unquoted, inline, multiline, and malformed YAML cases;
+- avoid evaluating expressions;
+- preserve source offsets for patchable `uses` values;
+- test Windows and POSIX path normalization where relevant.
+
+The patcher should make the smallest source-range replacement. Do not reserialize
+the entire YAML document: that would destroy comments, formatting, anchors, and
+reviewable diffs.
+
+Property tests in `test/patcher-properties.test.js` exercise rewrite stability.
+
+## GitHub API changes
+
+All runtime requests belong in the resolver or organization GitHub layer and
+must remain pinned to `https://api.github.com`.
+
+For new endpoints:
+
+- validate status and response shape;
+- paginate boundedly;
+- validate identities, SHAs, sizes, encodings, and UTF-8 as applicable;
+- set timeouts and bounded retries through the shared fetch layer;
+- preserve authentication-isolated cache keys;
+- decide explicitly whether private content may be cached;
+- accumulate scoped errors when continued reporting is safe;
+- add tests with mocked responses for truncation and malformed data.
+
+Never execute content to determine what it contains.
+
+When changing organization resume behavior, cover interrupted writes,
+checkpoint schema and identity mismatches, hostile fields, changed tree SHAs,
+previous repository errors, output equivalence, and concurrent completions.
+Persist each completed result before emitting its completion event so an
+observer failure or process interruption loses at most in-flight work.
+
+## Output compatibility
+
+JSON is the public machine interface. Raw command results and serialized JSON
+are deliberately different: renderers add repository-relative paths,
+redaction, and `schemaVersion`.
+
+When changing output:
+
+- retain top-level `status`;
+- treat new fields as additive where possible;
+- update `docs/OUTPUTS.md`;
+- test all four formats;
+- prevent embedded control characters from forging records;
+- ensure error details are visible in every format;
+- verify stable IDs remain stable unless their semantic input changed.
+
+## GitHub Action bundle
+
+Never edit `dist/index.js` or `dist/package.json` by hand. They are generated:
+
+```sh
+npm run build:action
+```
+
+Commit source and its rebuilt bundle together when the Action runtime changes.
+`npm run check:action-bundle` performs a clean build in a temporary directory
+and compares both working-tree and staged bundle files.
+
+A docs-only, test-only, or CLI-only change that is unreachable from
+`src/action.js` does not require a bundle rebuild.
+
+## Tests and fixtures
+
+Tests use Vitest and should be deterministic and network-independent. Mock
+GitHub responses rather than relying on live repositories. Use temporary
+directories for writes and assert both file content and failure behavior.
+
+Useful focused runs:
+
+```sh
+npx vitest --run test/audit.test.js
+npx vitest --run test/org-scan.test.js
+npx vitest --run -t "stable id"
+```
+
+Keep hostile input in fixtures or inline strings when it clarifies the threat
+being tested. Tests should not contain real credentials.
+
+## Documentation maintenance
+
+README is the landing page, not the full manual. Put durable detail in the
+focused guide that owns it, then link from README.
+
+When CLI, Action, config, output, or API behavior changes:
+
+1. update the owning reference document;
+2. update examples and AI guidance that depend on it;
+3. run `npm run check:docs`;
+4. run live `--help` and at least one documented example against
+   `node src/cli.js`.
+
+Keep examples copyable, use exact package versions for `npx`, and use full
+commit placeholders for the Action itself.
+
+## Releases
+
+The authoritative [release runbook](../RELEASING.md) defines maintainer and
+agent authorization, SemVer selection, live-state preflight, preparation,
+trusted publication, monitoring, verification, and partial-failure recovery.
+Do not bump versions as part of an unrelated contribution. `release:prepare`
+is local-only; `release:check` is intended for a reviewed, staged candidate and
+will fail a stale or already-published version.