@jakobm/peacekeeper
v0.29.0
Published
Shared repository test, Git worktree, and Codex hook commands
Readme
Peacekeeper
TypeScript tools for Codex Git worktree hooks, merged branch cleanup, and cached test receipts. The package supports Node.js 22.14 or later in the 22.x line and requires Git. Each calling project supplies its own configuration at its Git root.
The public npm package is @jakobm/peacekeeper; its CLI command is peacekeeper.
Install it with npm install --save-exact @jakobm/peacekeeper@<version>, selecting
a published version. Replace the example dependency pin below with that version.
Command groups
Use peacekeeper <group> <command>. Running a group without a command displays
its help; --help also works at the root, group, and command levels. Shell
completion follows the same hierarchy.
| Group | Commands |
| --- | --- |
| project | create, check, update-config, check-conventions |
| test | run, check-receipt, record-receipt, prepare |
| github | configure, generate-setup |
| release | assess, verify, verify-protection, verify-version, publish |
| codex | install-hooks, init-worktree, checkpoint, session-start, stop, session-end |
| cleanup | merged-branches, empty-directories, queue-merged-worktree |
peacekeeper project check
peacekeeper test run --checkpoint
peacekeeper github configure --help
peacekeeper release publish patch
peacekeeper cleanup merged-branches --executeThe previous flat command names remain accepted for existing scripts and hooks.
For example, run-tests --checkpoint maps to test run --checkpoint,
checkpoint-codex-changes maps to codex checkpoint, and release patch maps
to release publish patch. Bare release now displays the release group's help.
Help and generated project files use the grouped names. Update existing package
scripts and CI to those names. The legacy hook installer remains available, but its repository-local files
conflict with the current project requirements.
Architecture
All application code and tests are authored in TypeScript. Domain modules belong to the
Portico tree under src/modules.
The flat module set consists of cli, configuration, projects, testing,
releases, lifecycle, and maintenance. The cli module alone maps command
names to explicit operations on each domain's frozen facade. Modules
receive private factories, permitted module facades, and external services through
Portico injection; direct runtime imports inside the module tree are rejected by
the configured portico check. Each module declares its type-only contract in
interface.ts and exports its named porticoFacade factory from facade.ts.
Permitted dependencies are declared in
src/modules/dependencies.yaml. Cmdabra generates the CLI implementation contract
as src/modules/cli/types.ts from the root cmdabra.yaml; npm run typecheck
verifies that it is current before checking the TypeScript project.
Generate the dependency views and SVG diagram with npm run architecture. The
checked-in output lives in architecture/. Peacekeeper's configured
generated-files convention verifies that output during npm test.
Checkpoint and session lifecycle hooks use the same Cmdabra and Portico composition
as other CLI commands. Dependencies must therefore be installed in every worktree
before its hooks run; run npm ci explicitly when preparing a worktree.
The CLI also exposes Cmdabra's global --cmdabra-complete option for
shell completion adapters.
It accepts the current word index followed by all command-line words and prints
completion candidates without running a command.
Testing Peacekeeper
Run npm test with the pinned Volta toolchain to build and run type checks,
module boundaries, repository conventions, and the complete test suite.
Read-only CLI behavior is covered by human-readable .case acceptance files in
tests/acceptance, following the pattern used by
Ledlight and Cmdabra. Each case runs the actual CLI in an isolated temporary Git
repository and compares stdout, stderr, and exit status. Sections supply command
arguments, project configuration, files, environment, and stdin as needed. The
runner also rejects unexpected file changes.
Keep network operations, publishing, background workers, and repository mutations in the existing integration suites with controlled dependencies. Acceptance cases cover deterministic output and local preflight failures for those commands. CLI syntax validation and generated help output are covered by Cmdabra's own tests. Expected output is reviewed text; tests never regenerate it automatically.
Reuse the central workflows
Use Peacekeeper's reusable workflows for PR checks and npm publication. They
check out the calling repository, select its pinned Node/npm versions through
Volta, and run npm ci. The PR workflow verifies GitHub policy and runs
npm test; the publish workflow verifies the release and runs npm publish
through OIDC. Put project-specific checks, including packaging checks, in
tests.all. Neither workflow accepts inputs.
Install a Peacekeeper version containing this support before switching. Older
versions reject required reusable jobs. A minimal .github/workflows/test.yml is:
on:
pull_request:
branches: [main]
permissions:
contents: read
jobs:
test:
uses: jakobmattsson/peacekeeper/.github/workflows/reusable-pr.yml@17a6c202c0f3cd66f1bb4a42d1dc8c78e7eb60d6
secrets:
RELEASE_POLICY_TOKEN: ${{ secrets.RELEASE_POLICY_TOKEN }}For npm packages, keep a separate publishing entrypoint with its existing filename (the filename forms part of the npm trusted-publisher registration):
on:
push:
tags: ['v*']
permissions:
contents: read
id-token: write
jobs:
publish:
uses: jakobmattsson/peacekeeper/.github/workflows/reusable-publish.yml@a438e3d706a1812fea72dc0858378566f4e3bb21
secrets:
RELEASE_POLICY_TOKEN: ${{ secrets.RELEASE_POLICY_TOKEN }}The caller owns event triggers, explicit permissions, and secret mapping.
GitHub does not let the called workflow raise permissions granted by the caller;
publication therefore declares id-token: write in both. name is optional.
Use git.defaultBranch in the PR trigger. Pass the policy secret explicitly;
secrets: inherit is not supported, and its source may have another name.
The policy token is exposed only to verification. Configure repository secrets,
GitHub protection, and npm trusted publishing separately; fork PRs do not receive
repository secrets. npm must authorize the calling repository and entrypoint.
GitHub names the checks test / test and publish / publish: the caller job's
name (or ID), followed by the central job name. Merge these fields into the full
project configuration:
projectChecks:
testWorkflow: test.yml
requiredJobs: ['test / test']
git:
releaseTestWorkflow: test.yml
releaseRequiredChecks: ['test / test']If the caller has name: CI, require CI / test instead. Update GitHub's required
checks to the same name when migrating and confirm it in a PR run. A skipped or
renamed check cannot satisfy release verification. Additional local jobs remain
supported and are validated separately when required. project create generates
these thin callers, including publication for npm projects.
Peacekeeper trusts reviewed central implementations through the full workflow
commit SHAs bundled in
reusable-workflows.json.
Caller contracts are checked offline, without downloading remote YAML. Unknown
SHAs, branch names, tags, inherited secrets, inputs, matrices and runner/step
or failure-handling overrides are rejected. Inline workflows remain supported.
To approve an update, review, test and commit the central workflows first, then
add that commit's full SHA to the allowlist in a subsequent commit. Preserve the
single static test or publish job, explicit policy secret, no-input contract,
and verified setup and step order. Contract tests check both implementations
through the public project checker. Consumers deliberately update approved pins.
Standard CI test environment
The central PR workflow runs one Ubuntu 24.04 job. It cancels superseded runs for
one PR, installs npm dependencies, validates the project, prepares the test
prerequisites, verifies GitHub policy and runs npm test.
Declare the optional test prerequisites in peacekeeper.config.yaml:
tests:
aptPackages: [ledger, bash-completion]
playwrightBrowsers: [chromium, webkit]Both lists default to empty. aptPackages installs Ubuntu packages, optionally
pinned as name=version. playwrightBrowsers installs the named browsers and
their system dependencies using the project's installed Playwright CLI. The
project's lockfile therefore selects the matching browser versions. An empty
browser list skips Playwright installation entirely, including its system
dependencies; Peacekeeper never installs the Playwright npm package itself.
test prepare installs these prerequisites after npm ci and before tests.
project update-config adds explicit empty lists to existing configurations.
The standard workflow allows 15 minutes for preparation, 30 minutes for tests
and 60 minutes for the overall job. Upgrade the approved PR workflow pin
together with Peacekeeper when adopting this preparation support.
Keep actual package, image and application checks in the canonical test chain.
npm test must run the complete intended verification. It can use Peacekeeper's
runner or the project's independent test engine. For an independent engine,
set tests.npmTestUsesRunner: false and tests.all: ['npm test']; that npm
script must not invoke peacekeeper test run recursively. Project validation
also runs explicitly in CI.
Projects needing additional setup or reporting can define their own workflows with ordinary GitHub Actions steps. The standard workflow only configures the two prerequisite lists above.
Create a compliant TypeScript project
project create creates a minimal ESM TypeScript library in an existing, completely
empty GitHub repository. The command version owns the generated project contract,
all tool pins, and the exact @jakobm/peacekeeper development dependency. This
command additionally requires Volta so generation and verification use those pins.
peacekeeper project create \
--repository https://github.com/OWNER/REPOSITORY.git \
--directory /absolute/path/to/REPOSITORY \
--package-name @scope/REPOSITORY \
--author-name "Example Author" \
--author-email [email protected] \
--publish-to-npm trueAll arguments are mandatory. Only https://github.com/OWNER/REPOSITORY[.git]
URLs are accepted. The package basename must equal the repository name. Published
packages must be scoped; private packages must be unscoped and use
--publish-to-npm false.
Before creating the destination, the command verifies that it does not exist and
that the remote has no Git refs. It then installs dependencies, builds, typechecks,
runs the complete Peacekeeper test and project checks, and (for published packages)
tests the packed package from a temporary consumer. Only after every local check
passes does it create one initial commit on main and push without force.
Generated projects use npm's prepare lifecycle hook to build after dependency
installation, before packing or publishing, and when installed directly from Git.
An argument or preflight failure creates nothing. A later failure leaves the local directory for inspection but does not commit or push. A push failure leaves the verified local commit. Inspect or remove the directory before retrying.
The generator creates an executable setup-github-config.sh and never runs it.
Use it in two steps, with the same plan directory:
./setup-github-config.sh ./github-plans
# Review every saved plan, including protection deletions.
./setup-github-config.sh --execute ./github-plansThe wrapper invokes the generator's exact @jakobm/peacekeeper version through
npm exec --package, then runs groundskeeper secrets sync --name
RELEASE_POLICY_TOKEN --new-repo OWNER/REPO only after every configuration has
succeeded and been read back. Planning never synchronizes secrets. Published
projects also require initial manual npm publication and trusted publishing
configuration; generating or running GitHub setup does not publish a package.
To generate the same wrapper for existing repositories:
peacekeeper github generate-setup \
--repository https://github.com/OWNER/REPOSITORY.git \
--repository https://github.com/OWNER/ANOTHER-REPOSITORY.git > setup-github-config.shGeneration reads and validates remote policy and captures the exact source SHA
for each repository. The wrapper refuses to plan from a different commit if that
source subsequently moves. For a single repository, --policy-pr NUMBER selects
an introduction/upgrade PR, and --source-ref COMMIT_SHA asserts its expected head
(or the expected default-branch SHA). Generate separate wrappers for repositories
with different explicit policy sources. Existing generated scripts retain their
old implementation; regenerate them to adopt this flow.
Plan and apply exact GitHub configuration
github configure owns GitHub policy for one explicit OWNER/REPO on github.com.
It works outside a Git checkout and reads policy files exclusively from GitHub;
local configuration, dependencies and target-repository code are not executed.
Dry-run is the default:
peacekeeper github configure --repository OWNER/REPO --plan-file github-plan.json
peacekeeper github configure --plan-file github-plan.json --execute
# Bootstrap using an open PR in the same repository targeting its default branch.
peacekeeper github configure --repository OWNER/REPO --policy-pr 31 \
--source-ref FULL_HEAD_SHA --plan-file bootstrap-plan.jsonThe source is resolved to an exact commit before reading peacekeeper.config.yaml
and .github/CODEOWNERS. An absent configuration uses the running version's
bundled defaults, including repository-owner fallback for a null
git.requiredApprover. Absence is established from the source Git tree; API or
permission failures never select defaults. Invalid YAML/schema and legacy
peacekeeper.config.json are errors. The personal repository owner must be the
required approver, and CODEOWNERS must contain exactly one effective rule,
* @OWNER, even when configuration defaults are used.
A policy PR's files are read at its exact head SHA. The result marks this as
bootstrap: GitHub uses CODEOWNERS from the target branch, so ownership changes in
that PR only become effective after merge. This command configures GitHub settings
and never merges the PR or claims that unmerged ownership files are already active.
--source-ref is an expected SHA guard for the selected source, not a way to skip
PR validation or select an unrelated historical commit.
The owned surface is exactly:
- Repository merge methods: merge commits enabled, squash and rebase disabled.
- Repository auto-merge availability and automatic merged-branch deletion enabled.
- Exactly the two canonical active branch rulesets from the bundled shared policy.
- No classic branch protection rules anywhere in the repository.
Every other repository-owned branch ruleset and every classic protection rule will be deleted, including protections for other branches and wildcard rules that do not currently match a branch. The canonical rulesets protect only the default branch; other branches can lose protection. There is no preserve-other- branches option. Future exceptions belong in versioned Peacekeeper configuration. Secrets, collaborators, deploy keys, webhooks, environments, security settings, and tag/push rulesets are outside the owned surface and are preserved. Inherited active branch rules that cannot be proven compatible with the canonical policy are blockers and must be resolved at their source. Missing bypass visibility or incomplete inventory blocks planning instead of assuming there are no restrictions.
Dry-run shows every creation, update and deletion with before/after policy and
blockers. --plan-file saves a new JSON file exclusively (existing files are not
overwritten). Omit it to inspect a plan without saving. Execute requires the saved
plan. Policy-source overrides cannot be combined with --execute; an optional
--repository OWNER/REPO asserts the saved target without changing it. Generated
wrappers always use this assertion before synchronizing secrets.
Before writing, Peacekeeper validates the plan against its current canonical
policy, exact package version, source SHA, default branch/SHA, stable repo identity
and relevant observed GitHub configuration. A moved source or changed precondition
requires a new plan. Editing the plan does not authorize arbitrary API requests.
The executor establishes and checks the canonical protections before deletions, checks relevant remote state between operations and reads the entire owned surface back before success. GitHub has no transactions: concurrent changes can still occur between checks and API writes. Failures report completed/attempted operations and read-back state where available. After a partial failure, plan again into a new file/directory and apply the remaining changes; already correct configuration needs no rollback. The same recovery applies to a partially completed multi-repo wrapper. After verified success, a fresh plan has no changes. Secret synchronization is a separate step; a secret-sync failure does not roll back GitHub settings.
Use a manually authenticated GitHub identity with repository Administration write
access for execute, and sufficient Contents/Administration read access for complete
policy inspection. Do not put admin-write credentials in Actions secrets.
The shared policy model also serves release verify-protection; that existing
command retains its documented semantic alternatives, including equivalent classic
protection, while github configure verifies the exact owned configuration.
Machine-readable contract
Add --json for a JSON result on stdout. Human output is not an automation API.
Every result contains resultFormatVersion: 1, peacekeeperVersion, and status.
Planning results include plan; failures include an error and/or blocker details.
Status values are planned, blocked, stale, partial, verification-failed,
succeeded, and failed. Execute results include completed and, when available,
attempted, observed, readbackError and bootstrap. A blocked plan can be saved
for inspection but cannot execute. Planning errors that prevent a complete plan
return structured blockers without writing a plan file.
Saved plans use formatVersion: 1 and contain peacekeeperVersion,
repository: { id, slug }, source: { kind, sha, defaultBranch, defaultSha,
policyPr? }, bootstrap, configSource (remote or defaults), observed,
desired, changes and blockers. observed covers owned repository settings,
repository-owned/inherited branch rulesets, and complete classic protection rules
with allowance actors. desired carries canonical settings/rulesets and absence
requirements. Changes identify their resource kind, action, existing id
where applicable, and before/after policy as applicable.
Policy arrays are normalized as unordered collections. Response metadata is
excluded; unknown rule parameters remain significant. GitHub's empty
required_reviewers list and null check integration IDs normalize away, and omitted
require_extra_approval_for_unattributed_changes uses GitHub's true default.
These rules apply equally to canonical policy and observed state.
Exit status is 0 for an unblocked plan (even with changes) or verified execute success, 1 for blockers, stale/invalid plans, partial execution or other operational failures, and 2 for Cmdabra syntax errors. Plan/execute is a Peacekeeper-owned contract, not a generic API request format. Groundskeeper should retain plans unchanged and return them to the same exactly pinned Peacekeeper version.
When moving an existing project to Peacekeeper, update its dependency and lockfile,
package scripts, and configuration filename together. Replace previous lifecycle
hook commands with the definitions below before running peacekeeper codex install-hooks.
The installer recognizes Peacekeeper commands; it does not translate commands
from a differently named package. Each existing worktree needs the new dependency
and configuration. Test receipts start fresh under the new package identity;
finish any pending release before switching release tools.
Recommended caller setup
Add the three files below to the calling project. Replace the Git branch settings and test commands with that project's values. Install the package from npm; no GitHub SSH access is needed for the dependency.
1. package.json
Include these entries in the caller's package.json, alongside its other scripts and dependencies. Pin the npm dependency to an exact version and change it deliberately when upgrading. The lint script and ESLint dependency are needed only for the eslint . test command in this example.
{
"private": true,
"scripts": {
"lint": "eslint .",
"test": "peacekeeper test run",
"cleanup:branches": "peacekeeper cleanup merged-branches",
"cleanup:empty-directories": "peacekeeper cleanup empty-directories"
},
"devDependencies": {
"eslint": "^9.39.5"
},
"dependencies": {
"@jakobm/peacekeeper": "0.12.1"
}
}Run npm install from the project root and commit the resulting package-lock.json. npm adds node_modules/.bin to the PATH of package scripts, so package scripts can call peacekeeper by name.
2. peacekeeper.config.yaml
Place this file at the caller's Git root. Every field, including nested fields, is required. Unknown fields and invalid values are rejected. If no file exists, Peacekeeper uses the complete bundled defaults. The defaults contain no test commands; configure those before running tests or recording or reusing a test receipt.
Run peacekeeper project update-config to create the file or recursively fill missing
fields from the defaults. Existing values, including empty arrays, are preserved.
Comments in an existing YAML file are preserved. Review newly inserted values.
The old tests.commands field is migrated to tests.all; tests.checkpoint
defaults to an empty list. If both commands and all exist, resolve that
ambiguity manually before updating.
Invalid YAML, unknown fields, or invalid existing
values cause failure without changing the file. Repeating the command on a
complete valid file leaves it unchanged.
The former peacekeeper.config.json filename is not accepted. Rename and convert
it before upgrading so Peacekeeper cannot silently fall back to defaults.
All CLI commands validate configuration before executing, except help,
project check --explain, and project update-config. Checkpoint hooks instead validate
the event worktree configuration when the event requires instructions or a check.
An incomplete existing file fails
with missing field paths and a repair hint. Updates introducing new fields
therefore require peacekeeper project update-config before ordinary commands can run.
Complete example:
publishesToNpm: false
git:
remote: origin
defaultBranch: main
branchPrefix: codex/
requiredApprover: OWNER
checkpointPushRemotes:
- origin
releaseMergeMethod: merge
releaseRequiredChecks:
- test
releaseTestWorkflow: test.yml
tests:
all:
- eslint .
- peacekeeper project check-conventions
- node --test
checkpoint:
- eslint .
- peacekeeper project check-conventions
receiptMaxAgeMinutes: 60
npmTestUsesRunner: true
conventions:
rules: []
loggingDirectory: tmp/logs
loggingEnabled: true
projectChecks:
testWorkflow: test.yml
requiredJobs:
- testgit.remote and git.defaultBranch identify the branch used for checkpointing and cleanup. git.branchPrefix names new task branches. git.requiredApprover names the personal GitHub repository owner who must approve other users' PRs and may bypass only the approval ruleset from a PR. Set it explicitly after project update-config; its bundled default is null. The root project must contain .github/CODEOWNERS with the single non-comment rule * @OWNER, matching this value.
peacekeeper test run is the full test command and runs tests.all.
peacekeeper test run --checkpoint runs tests.checkpoint instead; the flag
is off by default. Each consuming project chooses both lists. Every checkpoint
command must also occur in all as the exact same shell command string.
Invalid membership fails configuration validation before either mode executes
any test commands, including with --force or existing receipts. An empty
checkpoint list is valid, as is one containing all commands. tests.all must
contain at least one command before tests or receipt commands can be used.
Both modes always run the local project check validation first, even when all
selected commands have valid receipts or the checkpoint list is empty. Explicit
project check invocations in either list are rejected as redundant. Commands
run in list order from the caller's Git root; install any executables they use.
Repeated identical strings run once per invocation. The runner stops at the
first failure and records a receipt immediately after each successful command.
receiptMaxAgeMinutes controls how long each command receipt can be reused.
Set npmTestUsesRunner to true only when the caller's npm test script invokes
peacekeeper test run; the rerun hint then uses npm test -- --force (and
--checkpoint when selected). Otherwise it uses the explicit package path.
loggingDirectory stores hook invocation logs relative to the primary Git
worktree's root.
loggingEnabled has the bundled default true; set it to false to disable invocation logs and the background cleanup worker's log file. Existing logs are kept. The setting is read from the primary checkout's configuration, including for linked worktrees. SessionStart and Stop logs include the process and event working directories, event type, primary-checkout classification, and hook response or error. Only selected event fields are logged, never the full incoming payload. These logs require the Peacekeeper script to start; a missing Node.js executable or package must be diagnosed in Codex's own logs.
Checkpoint hook failures write the cause to stderr and exit with code 2 instead of reporting success. For Stop, this requests continued work under the Codex hook protocol. Invocation logging is advisory: a logging failure is reported on stderr, but the checkpoint instructions or check still run and retain their result. Behavior configuration comes from the event's worktree, while log settings come from the primary checkout. A logging warning alone does not change the exit code.
To publish checkpoint branches automatically, set git.checkpointPushRemotes (fragment):
remote: origin
defaultBranch: main
branchPrefix: codex/
checkpointPushRemotes:
- origin
- backupEach name must identify a Git remote configured in the calling repository. Checkpoints push to exactly those remotes, creating the task branch if
needed. The bundled default is ["origin"]; set an empty list to disable checkpoint pushes.
The field must be present; there is no implicit push fallback. Pushes never use force. Only a push to git.remote sets the
branch's upstream. If a push fails, earlier pushes are kept and the checkpoint
records a failure; fix the cause and rerun the checkpoint command to retry without
creating another commit when there are no new changes.
Receipts are stored outside the repository under peacekeeper-test-receipts in
Node.js's os.tmpdir(). Each Git root has one file containing separate receipts
keyed by exact command strings, independent of the selected test level. After
test run --checkpoint, a subsequent test run skips shared commands with
valid receipts and runs the remaining commands. Running all also covers
checkpoint. Receipt validation fingerprints changed files and the process
environment; changing a command creates a different cache identity. Legacy
whole-suite receipts are ignored and replaced as commands pass.
Each command's previous receipt is invalidated before it runs. Successful
commands keep their receipts if a later command fails, so a retry can resume
with the failed or untested commands. --force and CI bypass reuse and invalidate
all selected receipts up front, including commands not reached after a failure;
receipts for unselected commands are preserved. Failed project validation
invalidates all command receipts for the repository.
The runner compares repository contents and the test environment before and after each command. If either changes during that command, it exits with an error and records no receipt for it. Rerun tests on the resulting contents. Test-generated files should be ignored or written outside the repository.
test check-receipt succeeds only when every command in tests.all has a valid
receipt. test record-receipt certifies those commands without executing them.
Both support --checkpoint to select tests.checkpoint instead.
Legacy repository hooks
Repository-local .codex is no longer supported by project check. Remove
existing .codex directories when upgrading, preserving any needed setup outside
the repository first. New projects do not generate them. The commands below
remain available for explicit legacy use and create files rejected by project validation.
Install or update the project hooks from the caller's Git worktree:
npm exec --no -- peacekeeper codex install-hooks --dry-run
npm exec --no -- peacekeeper codex install-hooksThe command creates or updates .codex/hooks.json at the Git root. It preserves
other handlers, their order, group settings, and other configuration fields.
Known Peacekeeper invocations are replaced with current definitions and
duplicates are removed. Our hooks are installed in their own groups, without
inheriting another group's matcher. Repeating the command makes no further change.
Supported migrations include standalone peacekeeper, npm exec --no --,
npx --no-install, documented node bin paths, and direct node scripts/ hook
invocations. Unknown wrappers, composed shell commands, and additional handler
options are not replaced automatically. If an entry appears related to Peacekeeper
but cannot be safely migrated, the command exits with an error identifying
it and leaves the entire file unchanged. Review that entry, preserve any custom
logic as a separate hook, then rerun the installer. Wrappers whose names do not
identify Peacekeeper cannot be detected; review those yourself before installing.
The installer writes atomically and rejects malformed files. It changes only
.codex/hooks.json, not AGENTS.md, project configuration, or hooks in other
configuration layers. Configure Git remotes, tests, and dependencies separately,
and review and trust the installed hooks with /hooks in Codex.
The installed file contains these definitions (other existing hooks are retained):
{
"description": "Repository lifecycle hooks.",
"hooks": {
"SessionStart": [
{
"hooks": [
{
"type": "command",
"command": "node \"$(git rev-parse --show-toplevel)/node_modules/@jakobm/peacekeeper/dist/bin/peacekeeper.js\" codex session-start",
"timeout": 30,
"statusMessage": "Loading Codex checkpoint instructions"
}
]
}
],
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "node \"$(git rev-parse --show-toplevel)/node_modules/@jakobm/peacekeeper/dist/bin/peacekeeper.js\" codex stop",
"timeout": 30,
"statusMessage": "Checking for an uncommitted Codex checkpoint"
}
]
}
],
"SessionEnd": [
{
"hooks": [
{
"type": "command",
"command": "node \"$(git rev-parse --show-toplevel)/node_modules/@jakobm/peacekeeper/dist/bin/peacekeeper.js\" codex session-end",
"timeout": 3,
"statusMessage": "Scheduling merged branch cleanup"
}
]
}
]
}
}The commands resolve the package from the current Git worktree. Install dependencies in each worktree where the hooks will run; the commands need that worktree's node_modules/@jakobm/peacekeeper. The checkpoint hooks apply only to linked worktrees. SessionStart supplies the checkpoint instructions before work begins, including on resume, fork, and after compaction; no matcher is needed. Stop uses the same package-owned instructions as a fallback. You do not need to copy checkpoint rules into each project's AGENTS.md. Explicit user instructions not to commit or push take precedence: the agent must skip the checkpoint command when they conflict, even if Stop requests it. The hook checks Git state and cannot determine user intent itself. When uncommitted changes remain, the Stop hook asks the agent to review the diff and run codex checkpoint with a descriptive English commit message. That command stages all changes and commits them on a task branch; it refuses the configured default branch. With git.checkpointPushRemotes, it pushes without force to each listed remote, including new branches. An empty array keeps the branch local.
SessionEnd starts a detached worker to clean up the session worktree and branch only if the captured branch tip is still unchanged and fully merged into the remote default branch. Dirty or locked worktrees are kept. Worker output is appended to cleanup-ended-session.log in the shared Git directory. Cleanup does not require the primary worktree to have the default branch checked out. A local default branch that can fast-forward is updated before cleanup: a branch not checked out in any worktree is moved atomically, while a checked-out branch is merged in its clean worktree so its files and index stay synchronized. A dirty or diverged default branch is left unchanged. Codex loads project hooks only after the project hook source is trusted; review them with /hooks. The three-second SessionEnd timeout is the maximum documented for that event. See the Codex hooks reference for hook loading, trust, and timeout behavior.
Adopting shared checkpoint instructions
For a project that already uses the Stop hook, upgrade to a package release that
includes codex session-start and codex install-hooks, then run the installer above.
The installer also updates Stop and SessionEnd. Review and trust the updated hooks with /hooks,
then start a new session or resume one to load the instructions. The pinned package version must include these commands.
Remove the duplicated checkpoint section from the project's AGENTS.md once the
new hook is enabled. Keep any project-specific rules there. Installing the npm
dependency alone does not activate hooks: each caller must configure and trust
them. The shared policy then follows the installed package version.
Check the setup
From the caller's Git worktree, run npm test for tests.all, npm test -- --checkpoint for tests.checkpoint, npm test -- --force to bypass command receipts, npm run cleanup:branches to preview merged branch cleanup, and npm run cleanup:empty-directories to preview removal of empty directories and directories containing only ignored files. The latter command protects the root .git, node_modules, and tmp directories; other selected directories are removed recursively, including their ignored contents. Add -- --execute to either cleanup package script to apply it. Run npm exec --no -- peacekeeper --help for the complete command list. To create a manual checkpoint, use npm exec --no -- peacekeeper codex checkpoint --subject "<subject>" --body "<body paragraph>".
Directory cleanup also preserves nested Git repositories and linked worktrees, including their parent directories when those parents are ignored. It does not clean inside those repositories. Branch cleanup rechecks local branch tips and worktree identity, locks, and changes before removal; a changed plan is skipped before deleting the affected worktree or branches. Remote branch deletion still uses an exact-commit lease.
This repository uses the same hooks and configuration, with commands pointing to
its own dist/bin/peacekeeper.js instead of an installed copy. Its git.checkpointPushRemotes is set to ["origin"] to publish checkpoint branches automatically. There is no dependency
on a published version of itself. npm exec --no -- peacekeeper also resolves
the root package's own bin, including the checkpoint command requested by the
Stop hook. Install dependencies with npm ci to run the full test suite.
Run npm test in this repository to verify the shared package itself, or
npm test -- --force to force a fresh run. Its configured test command runs Node's
test runner directly, avoiding recursion through npm test. The cleanup package
scripts work the same way as in calling projects.
When first adopting these hooks, make sure the primary checkout also contains
peacekeeper.config.yaml before trusting them with /hooks: invocation logs
are stored there and session cleanup reads that checkout's configuration.
The hook definitions can then be reviewed and trusted in Codex; committing them
does not grant trust automatically.
Configured repository conventions
Define general file conventions in peacekeeper.config.yaml and run:
peacekeeper project check-conventionsAdd peacekeeper project check-conventions explicitly to tests.all to include it
in the normal test run at the desired position. It is not added automatically.
Each rule is reported as a Node.js test. Violations, file errors, failed generators,
and invalid configuration cause a nonzero exit status; one failing rule does not
hide the results of later rules. A failed command in test run has no passing
receipt; successful earlier commands retain their own receipts.
All configured paths and generator working directories are relative to the Git
root, even when the command is invoked from a subdirectory. Use forward slashes
on every platform. There is no separate conventions file. conventions.rules: []
is valid and reports that no rules are configured. Existing projects must run
peacekeeper project update-config to add this field before ordinary commands can run;
existing rules and YAML comments are preserved.
Standalone checks always run and do not create or reuse test receipts. When
included in tests.all, they follow test run' existing receipt reuse;
use peacekeeper test run --force to rerun the full configured test flow.
Run project check-conventions --update separately from that flow when updating output.
The testing module owns rule execution and Node test reporting. The
configuration module owns the rule contract and strict validation, and cli
maps the command through the testing facade.
Peacekeeper's own configuration checks generated architecture output, kebab-case
TypeScript filenames, the two permitted files at the module root, test and fixture
files in the test tree, and sorted dependency lists. These rules run as an explicit
step in npm test; the architecture output check uses the same rule runner as
consumer projects.
Allowed files
conventions:
rules:
- check: allowed-files
files: "tests/acceptance/**/*"
allow:
- "tests/acceptance/**/*.case"
- "tests/acceptance/**/README.md"
- check: allowed-files
files: "scripts/*"
allow: []files selects existing files using glob patterns. * matches within one path
segment; ** includes subdirectories. Directories themselves are not checked.
Hidden files are included. Symbolic directory links are not recursively followed.
Each selected file must match at least one allow pattern. The patterns in
allow are also relative to the repository root. An explicit empty
list forbids every selected file; omitting allow is a configuration error.
Overlapping rules must each pass independently.
The literal directory prefix before the first glob segment must exist. For
example, scripts/* fails when scripts is missing, but passes when it exists
and contains no direct files. These rules constrain existing files; they do not
require files to be present.
Corresponding files
conventions:
rules:
- check: corresponding-files
from: "tests/unit/src/{path}.test.ts"
to: "src/{path}.ts"Each matching from file must have an existing file at its corresponding to
path. {path} captures a nonempty relative path, including subdirectories, and
substitutes it unchanged into the target. Both templates must contain exactly
one {path} placeholder and no other glob patterns. The literal source
directory must exist; an existing empty source directory is allowed.
The check is one-way: extra target files are allowed. A directory at the target path does not count as a corresponding file. Missing targets are reported with both the source and expected target paths.
An empty conventions.rules list is valid. Unknown checks and fields,
absolute paths, parent traversal, and negated patterns are configuration errors.
Sorted YAML lists
conventions:
rules:
- check: sorted-yaml-lists
file: "src/modules/dependencies.yaml"Recursively checks every list containing only strings, including lists nested
inside mappings or other lists. Ordering uses JavaScript's case-sensitive
string sort, without locale rules. Empty lists and duplicate values are allowed.
Other lists are traversed for nested string lists, but are not themselves sorted.
Failures identify the file and the YAML value path. Missing files and invalid
YAML fail the check. file must be a literal relative path.
Document links
conventions:
rules:
- check: document-links
document: "README.md"
files: "docs/**/*"Every selected file must be the destination of an inline Markdown link in
document. Destinations are relative to the document's directory; URL-encoded
paths, fragments, query strings, and optional double-quoted titles are supported.
External URLs do not cover local files. Extra links are allowed. This simple
check recognizes inline link syntax only, not reference links or HTML links;
it does not parse Markdown blocks, so link-shaped text in code also counts.
The file selection has the same directory and glob semantics as allowed-files.
A missing document fails, and document must be a literal relative path.
File names
conventions:
rules:
- check: file-names
files: "{src,scripts,tests}/**/*.ts"
match: '^[a-z][a-z0-9]*(?:-[a-z0-9]+)*(?:\.test|\.d)?\.ts$'files selects files using the same glob and directory semantics as
allowed-files. match is a case-sensitive JavaScript regular expression
using Unicode mode, applied to each file's basename including its extensions.
Directory names are not checked. Use ^ and $ to require a full-name match;
without anchors, substring matches are allowed. Invalid expressions are
configuration errors. Failures report the file and expected expression.
YAML single quotes preserve regex backslashes without extra escaping.
The example requires kebab-case TypeScript filenames with optional .test or
.d suffixes. Adjust the expression to the calling project's naming conventions.
Generated files
conventions:
rules:
- check: generated-files
run: 'portico architecture --modules dist/src/modules --output "{output}"'
expected: architectureRuns a shell command from the repository root, with local
node_modules/.bin programs available. Quote "{output}" in the command:
the runner substitutes a temporary output directory and removes it afterward.
The command must succeed. The expected directory must exist and contain exactly
the same relative file paths and bytes, including hidden and nested files.
Empty directories are not compared. Generation must be deterministic.
Run peacekeeper project check-conventions --update to regenerate all configured outputs.
This replaces each expected directory only after its generator succeeds, removing
stale files. Expected directories must contain only reproducible generated output;
review the diff before committing. Git metadata paths and expected paths containing
symbolic links are rejected. Temporary output is removed after each rule.
Other convention rules are still checked and are never automatically repaired. The command does not sort YAML, rename files, create corresponding source files, or insert document links. Updates happen per rule, so generated files may have been updated even if another rule fails. A failed generator preserves that rule's previous expected files and reports its exit status and output.
Check project conventions locally
Run peacekeeper project check to check the local project configuration.
Declare the mandatory boolean publishesToNpm in peacekeeper.config.yaml.
Its default is false; project update-config inserts false without inferring intent
from package metadata. Set it to true for packages published to npm (including
restricted scoped packages). Peacekeeper itself sets it to true.
A missing field in an existing configuration is a project check error.
With true, declare a publishable package (private absent or false), a valid
npm name, stable version, description, license, nonempty files list, and
publishConfig with registry https://registry.npmjs.org/ and explicit access
public or restricted. Add a direct peacekeeper release publish package script
(the npm-exec and local Node CLI forms are also supported) and the verified OIDC
release workflow described below. Put packaging checks such as
npm pack --dry-run --json or npm run test:package in tests.all.
Installation tests of the packed package in a temporary consumer project are
recommended. The local checker does not enforce a special packaging command
or inspect test-script assertions.
With false, set package.json.private to true and remove publishConfig,
files, npm publication/release scripts, and npm publication workflow steps.
Checks recognize direct commands, shell command lists, npm script aliases and
npm-publish actions; arbitrary shell wrappers and reusable workflows cannot be
proven free of publication code by this local check. Remove dedicated npm
publishing credentials and trusted-publisher registrations separately.
Internal npm pack, build scripts, module entry points and CLI metadata remain
allowed, as do deployment workflows and read authentication for dependencies.
PR checks, lockfiles, toolchain requirements and release verify-protection
remain independent of publication intent, including git.releaseRequiredChecks.
All projects must declare nonblank author and repository values in
package.json. npm object forms are supported with nonblank author.name
and repository.url strings.
Run peacekeeper project check --explain for the complete expected
architecture, requirements, configuration examples, and verification limits.
The command prints the bundled formal requirements,
which can also be read without a repository or project configuration.
The repository root must not contain .codex, even as an empty directory, file,
or symbolic link. Remove it when upgrading, preserving any needed setup outside
the repository first. Validation reports the violation without changing files.
New projects omit both environment configuration and repository hooks. The legacy
codex install-hooks command still creates .codex/hooks.json when explicitly
requested; that output fails project check.
Prepare new worktrees explicitly: select the pinned Volta toolchain, run npm ci,
and, when needed, run peacekeeper codex init-worktree --sync-primary for a fresh
worktree. Keep project-specific setup in your external environment configuration.
--sync-primary makes Peacekeeper also update a clean primary checkout when its
default branch can be fast-forwarded safely. A clean non-default branch there is
first synchronized
with the configured remote; divergent history is published under the next free
versioned name such as feature-v2. Dirty, detached, ahead, or divergent primary
checkouts are left untouched with an explicit skip message. The command records
completion in the linked worktree's private Git directory, retries interrupted
npm ci runs, and does not move an established worktree on later setup runs.
Assess unpublished changes
Run peacekeeper release assess (or npm exec --no -- peacekeeper release assess)
from a project using Peacekeeper. A syntactically valid invocation writes one
pretty-printed JSON object to stdout, with fields ordered as recommendation,
model, releaseSha, previousReleaseSha, and motivation:
{
"recommendation": "patch",
"model": "example-model",
"releaseSha": "2222222222222222222222222222222222222222",
"previousReleaseSha": "1111111111111111111111111111111111111111",
"motivation": "The unpublished changes fix a backward-compatible CLI bug."
}recommendation is patch, minor, major, noop (no publication needed), or
undetermined (insufficient evidence or a failed assessment). motivation
explains the decision. The command takes no arguments. Assessment outcomes,
including operational failures, exit with status zero and return JSON; callers
must inspect recommendation. This differs from CLI syntax and usage failures,
which Cmdabra reports as exit status 2 with help text on stderr and no JSON on
stdout. This distinction was introduced after Peacekeeper 0.20.0; integrations
upgrading from that version must check the process status before parsing stdout.
model is the model name reported in Codex's startup metadata on stderr. It is
null if Codex does not report recognizable model metadata or cannot start.
Peacekeeper reads it from the CLI rather than asking the AI to identify itself;
model selection remains at Codex's default.
previousReleaseSha is the verified published release commit; releaseSha is the fetched
default-branch commit being assessed. Peacekeeper supplies these full commit IDs,
independently of the AI response. They remain available when Codex cannot complete
its analysis. Each is null if it could not be resolved and verified. The target
identifies the source code a release would start from at assessment time; a later
release adds its version commit and tags the actual release PR merge commit.
The command requires Git, npm, an authenticated GitHub CLI (gh) with repository
read access, and an installed, authenticated Codex CLI supporting codex exec,
--ephemeral, and --output-schema. It fetches origin's default branch,
which must match git.defaultBranch, and pins its exact commit. It uses the
highest stable version published on the public npm registry as the baseline;
prereleases and tags without npm publication do not advance that baseline.
The published version must have a matching remote v<version> tag in the target's
ancestry. Package names and versions at the tag and target must agree with npm;
when npm supplies gitHead, it must match the tag's commit. Missing tags,
inconsistent metadata, no previous stable publication, unsupported private or
workspace packages, and unavailable history or services produce undetermined.
It does not guess an older baseline when the latest stable release cannot be verified.
Peacekeeper creates a temporary detached worktree at the target commit. Codex
inspects the complete commit range, source, documentation and package metadata
using terminal commands in a read-only sandbox with approvals disabled. It
uses Codex's default model selection and explicitly sets reasoning effort and
verbosity to low. It returns a JSON Schema-constrained result, which
Peacekeeper validates again.
The prompt applies semver: for versions from 1.0.0, breaking changes require
major, compatible features minor, and compatible fixes patch. For 0.x, breaking
changes require minor and other publishable changes patch. Internal changes may
give noop; incomplete or ambiguous evidence gives undetermined. Codex has
20 minutes to finish; individual Git, GitHub and npm operations have one minute.
The caller's branch and uncommitted files are preserved. Fetching updates remote
tracking refs; temporary worktrees and assessment refs are cleaned up afterward.
The command only recommends a release: it does not change versions, create a PR,
commit, tag, push, or publish, and it does not change peacekeeper release publish.
Codex logs are captured separately from the final JSON. AI assessments can be
wrong; the result applies to the fetched commit, and callers should reassess if
the default branch changes before using it.
Publish an npm release
Install Volta and ensure its shims are first in PATH
(volta setup configures supported shell profiles; restart your shell afterward).
Then run npm ci at the repository root. Volta automatically selects the exact
Node.js and npm versions in package.json for ordinary node, npm, and npx
commands, including in non-interactive agent shells with Volta on PATH.
GitHub Actions uses volta-cli/action to select the same project versions.
Check volta which node, node --version, and npm --version to verify your
setup. Use volta pin node@<version> npm@<version> to update the project versions;
engines.node separately describes supported consumer versions.
Review npm pack --dry-run --json before
publishing; npm includes the compiled dist/ tree, the README, and package metadata.
Configure npm trusted publishing for @jakobm/peacekeeper with repository owner
jakobmattsson, repository peacekeeper, and workflow filename package.yml,
with direct publishing enabled. Confirm npm publish access to the @jakobm
scope separately from GitHub repository access. The workflow verifies
the release and publishes via OIDC. It needs no npm access token.
test.yml calls the central PR workflow, producing test / test. package.yml calls the central publication workflow and runs
on v* tags and only verifies and publishes. Merging to main does not start
another run.
Release verification uses GitHub's enforced branch policy instead of retaining
artifacts of tested contents. Configure git.releaseRequiredChecks in the root
peacekeeper.config.yaml with the exact CI job names required for a release
(for this repository: ["test / test"]). These checks must be mandatory
with Require branches to be up to date before merging enabled. Classic branch
protection may provide the base PR and check requirements. Active base rulesets
may provide them instead. Merge
queues are not currently an alternative
to this strict policy. Repositories must also enable Automatically delete head
branches (delete_branch_on_merge=true).
The default branch must also have exactly one active approval ruleset. It must
require one approval from the sole global code owner, dismiss stale approvals
after new pushes, and contain no rule except that pull-request approval rule. Its
only bypass actor must be the personal repository owner from git.requiredApprover,
with bypass_mode: pull_request. This lets the owner merge their own PR without
approval while the separate base policy still requires a PR and successful CI.
No other user, team, role, or app may bypass either policy. Peacekeeper verifies
bypass actors when GitHub returns them. GitHub hides them from read-only
administration tokens, in which case Peacekeeper warns that this part remains
unknown instead of reporting a false success or failure.
Only merge commits may be used. Either disable squash and rebase
in repository settings, or restrict the default branch's pull-request ruleset to
allowed_merge_methods: ["merge"]. Other branches are outside this policy.
Required linear history and any applicable PR rule excluding merge commits fail
verification. Bypass actors for base PR and strict-check rules require manual
inspection only when GitHub omits them from its response.
Enable allow_auto_merge in repository settings: this permits opting in per PR;
the release command enables auto-merge on its release PRs.
project check makes no network requests. It runs implicitly before
tests.all or tests.checkpoint, including when reusing receipts, and checks that the configured
PR workflow uses only pull_request, with branches set to exactly
[git.defaultBranch], and runs release verify-protection with GH_TOKEN after npm ci and
before tests in a job listed in git.releaseRequiredChecks, either through local
steps or the approved central PR workflow above. The job and step must
not skip verification or ignore failures. The online verifier then checks that
exactly those configured check names are mandatory on GitHub, including its own
job; missing and additional checks are both configuration drift.
Push, manual, scheduled, and other triggers are rejected in this workflow. Keep
publishing, deployment, reports, and benchmarks in separate workflows.
For example, in a required test job:
- run: npm ci
- run: peacekeeper release verify-protection
env:
GH_TOKEN: ${{ secrets.RELEASE_POLICY_TOKEN }}
- run: npm testThis creates a local-to-CI chain: missing workflows are detected on the next local
npm test; incorrect GitHub settings are detected on the next PR run. It is not
continuous monitoring. Removing both CI and the local invocation prevents this
chain from running. No central scheduled audit is required by this setup.
The PR test job runs peacekeeper release verify-protection before its tests.
The command reads the actual default branch from GitHub, regardless of the PR
base. Other release commands require their configured branch to match it.
peacekeeper release publish checks the default branch before preparing a release
and again immediately before each merge attempt. Before publishing,
peacekeeper release verify checks the policy, matching package/tag/lockfile
versions, a same-repository merged release/v<version> PR, and successful required
jobs in its latest PR workflow run. Manual tags without that PR are rejected.
release verify-version remains available for local version checks alone.
API failures, missing permissions, and unverifiable rules stop the commands.
Bypass actors are the exception when GitHub omits them: policy verification then
prints Cannot verify bypass users unless given write access. Run a manual check
instead; available as a gist. and continues with that part marked unknown. When
the API returns bypass actors, Peacekeeper compares them with the same policy used
to generate the setup script and rejects drift.
The workflow expects a RELEASE_POLICY_TOKEN Actions secret, exposed to the
commands as GH_TOKEN. Use a fine-grained PAT or GitHub App token with access to
this repository and Administration read, Contents read/write, Pull requests read and
Actions read permissions. Contents write is required even to read merge-related
settings such as delete_branch_on_merge. Administration read is sufficient for
the remaining checks; ruleset write access is required for GitHub to reveal
bypass actors.
The normal workflow GITHUB_TOKEN cannot be granted Administration permission
through workflow YAML. After correcting access or rules, rerun the failed job.
Fork PRs do not receive this secret and fail the policy check; do not expose it
by executing fork code with pull_request_target.
To set this up for this repository:
Open the token creation form with the required permissions prefilled. For another repository, change the resource owner. Select Only select repositories, choose
peacekeeper, review the permissions and expiration, and generate the token. If the owner requires approval, wait until the token is approved.Save the token as an Actions secret with the following command.
ghprompts for the value interactively; paste the token at the prompt, keeping it out of the command and shell history. Theghaccount running this command needs permission to manage repository Actions secrets. The policy token itself does not need Secrets permission.gh secret set RELEASE_POLICY_TOKEN --repo jakobmattsson/peacekeeperConfirm the secret name exists, then find and rerun the failed test workflow:
gh secret list --repo jakobmattsson/peacekeeper gh run list --repo jakobmattsson/peacekeeper --workflow test.yml --limit 5 gh run rerun RUN_ID --failed --repo jakobmattsson/peacekeeperReplace
RUN_IDwith the run ID from the listing. To retry publication, list runs with--workflow package.ymlinstead. When the token expires, create a replacement and rungh secret setagain to update the same secret.
GitHub requires fine-grained PAT creation in the browser; gh can store the
resulting token as a secret but cannot create that PAT. See GitHub's token setup
documentation
and the gh secret set reference.
This policy trusts GitHub to enforce the checked settings when merging. It does
not retain historical proof of the tested file tree if administrators change
settings between CI and merge. Keep the package.yml filename unchanged: npm
trusted publishing is configured for that workflow file.
Releases use merge commits on the default branch, including retries of legacy
state without a merge method. Saved unfinished releases that explicitly select
squash or rebase must be restarted. git.releaseMergeMethod remains accepted for
configuration compatibility, but no longer selects the default-branch merge method.
From a clean repository root, run npm run release -- patch, minor, or major.
The required prerelease script runs npm ci first, replacing node_modules
with the exact dependency versions in the committed lockfile before npm resolves
and starts Peacekeeper. Always use the npm script; invoking peacekeeper release publish
directly bypasses this dependency bootstrap.
The command fetches the default branch and uses a temporary detached worktree to
increment the package and lockfile versions. Your current branch and local default
branch stay unchanged, including when the default branch is checked out elsewhere.
Before changing versions it logs Preparing release from origin/<branch> at <SHA>.
using the full source commit ID checked out in the temporary worktree.
It pushes a release/v<version> branch and opens a release PR. The command enables
auto-merge for the expected PR head using a merge commit, then waits up to 20
minutes for GitHub to complete the merge,
respecting required checks, reviews, resolved conversations, and branch freshness.
It never uses an administrator bypass or pushes directly to the default branch.
After merge, the command verifies the package files at the PR's actual merge
commit, tags that commit with v<version>, and pushes the tag. The existing
workflow publishes through npm trusted publishing. The command then waits for
the publish job and for the version to appear on npm. Monitoring reads the run
status before its jobs so a job finishing between requests does not produce a
false publication failure. Git and an authenticated
GitHub CLI (gh) with Contents read/write, Pull requests read/write, Actions
read and the policy-reading access described above are required. Registry checks
use a temporary npm cache and request current metadata.
Retry the same command and release type after an interruption: release state is
stored in peacekeeper-release.json in the shared Git directory, so retries
from another worktree of the same checkout continue the same PR and version.
Already-merged PRs and already-pushed matching tags are reused. A local lock
prevents concurrent commands in that checkout; an open release PR from a different
checkout blocks a new release. Do not delete the state or manually create a new
version commit or tag to retry. If publishing failed, fix the cause and rerun the
tag workflow on GitHub before retrying the command.
If merge requirements remain unmet, the comman
