@jakobm/peacekeeper 0.0.0-stage → 0.12.2

package/scripts/check-project-requirements.txt

@@ -0,0 +1,326 @@
+CHECK-PROJECT: EXPECTED PROJECT ARCHITECTURE
+
+Purpose and scope
+  One project pins its Node/npm toolchain, installs the peacekeeper Codex
+  lifecycle hooks, and runs reproducible PR checks. Published npm packages also
+  verify a release before publishing the tested version.
+
+  check-project reads local files at the Git root. It makes no network requests,
+  runs no project scripts, and changes no files. Failure exits with status 1.
+  Independent failures are reported together. Missing or unreadable prerequisites
+  can block dependent checks; the reported failures are not an exhaustive list
+  of problems behind those prerequisites. Fix them and run the command again.
+  --explain prints this entire document without loading or checking a project.
+
+Project configuration
+  A valid peacekeeper.config.json is required at the Git root, along with
+  package.json. The normal configuration schema still applies.
+
+  Select the PR workflow by filename, in this order:
+    projectChecks.testWorkflow -> git.releaseTestWorkflow -> test.yml
+  Select required job names in this order:
+    projectChecks.requiredJobs -> git.releaseRequiredChecks -> ["test"]
+  For published packages, git.releaseRequiredChecks is mandatory and its names
+  are always added to the required jobs. Set git.releaseTestWorkflow to the
+  selected PR workflow for release verification. Published projects cannot
+  select different workflows for project checks and release verification.
+
+  Example configuration fields (merge into the full project configuration):
+    "git": {
+      "releaseTestWorkflow": "package.yml",
+      "releaseRequiredChecks": ["test"]
+    },
+    "projectChecks": {
+      "testWorkflow": "package.yml",
+      "requiredJobs": ["test"]
+    }
+  projectChecks is optional; when present it requires both testWorkflow and
+  requiredJobs. Omit it when release settings already select the desired jobs.
+
+Toolchain: package.json and all Node-based CI jobs
+  Pin exact versions in package.json with:
+    volta pin node@<exact-version> npm@<exact-version>
+  Both volta.node and volta.npm must be exact semantic versions. engines.node
+  must be a valid range satisfied by volta.node. Remove .nvmrc even when its
+  version matches volta.node; package.json volta pins select Node and npm.
+
+  Install Volta locally and ensure its shims are first in PATH (volta setup).
+  In each CI job using setup-node, Volta, or direct Node/npm/npx/Volta commands:
+    - Check out the repository before one volta-cli/action setup step.
+    - Checkout and Volta setup must be unconditional and must not allow failure.
+    - Do not set node-version, npm-version, or package-json-path on Volta setup.
+    - Run Node/npm/npx commands only after Volta setup.
+    - Remove actions/setup-node, nvm use/install, volta install/pin/run, and
+      global npm install commands from CI. package.json selects the toolchain.
+
+  Minimal setup steps:
+    - uses: actions/checkout@v5
+    - uses: volta-cli/action@v5
+    - run: npm ci
+    - run: npm test
+
+Codex lifecycle hooks
+  .codex/hooks.json must contain the current peacekeeper hooks exactly once
+  for each lifecycle event, in their expected order, without group conditions.
+  Unrelated hooks are allowed. Repair with:
+    peacekeeper install-hooks
+  Hook installation does not itself grant Codex trust.
+
+All GitHub Actions workflows
+  Every .yml/.yaml file under .github/workflows must parse and declare jobs.
+  Where present, actions/checkout and volta-cli/action must use stable version
+  tags at major 5 or newer (v5, v5.0, v5.0.0, or newer). These are compatibility
+  floors, not latest-version recommendations. SHA and branch refs cannot be
+  verified offline and are rejected for these actions.
+
+  Runner labels must not contain moving *-latest images. Choose versioned
+  images suitable for the project, such as ubuntu-24.04. Direct labels, label
+  objects, and matrix.<key> references including matrix include are inspected.
+  Other dynamic runner expressions are not resolved.
+
+Required PR workflow and jobs
+  The selected workflow must declare pull_request. PR filters must not use
+  paths, paths-ignore, branches-ignore, or types. If branches is specified, it
+  must include git.defaultBranch literally.
+
+  Each required name must match exactly one static job display name (name), or
+  the job ID if name is absent. Expressions in required names are rejected.
+  Required jobs and all their needs dependencies must use local steps, must
+  not allow failure, and must not have conditions that skip required PR checks.
+  Accepted job conditions are absent, success(), ${{ success() }}, or exactly:
+    ${{ github.event_name == 'pull_request' }}
+
+  Each required test job must run unconditional npm ci before an unconditional
+  supported validation command, with neither step allowed to fail. Commands
+  must be direct run steps, exactly one of:
+    npm test
+    npm run test
+    npm run test:<name>       (name contains letters, digits, _ or -)
+    npm pack --dry-run
+    npm pack --dry-run --json
+  Shell wrappers, combined commands, and reusable workflows cannot establish
+  these requirements. Conditional reporting steps after tests are allowed.
+  An unconditional step either omits if or sets it to success() or
+  ${{ success() }}.
+
+  Matrix example: tests on three platforms and one static required gate:
+    jobs:
+      matrix-tests:
+        strategy:
+          matrix:
+            os: [ubuntu-24.04, macos-15, windows-2025]
+        runs-on: ${{ matrix.os }}
+        steps:
+          - uses: actions/checkout@v5
+          - uses: volta-cli/action@v5
+          - run: npm ci
+          - run: npm test
+      test:
+        needs: matrix-tests
+        runs-on: ubuntu-24.04
+        steps:
+          - uses: actions/checkout@v5
+          - uses: volta-cli/action@v5
+          - run: npm ci
+          - run: npm pack --dry-run
+  Configure the required name as "test". Its default success condition means it
+  only passes after the entire matrix succeeds; it also validates the package.
+  Keep this gate name static and unique. Matrix-generated check names alone do
+  not provide the single exact match required by release verification. Actual
+  GitHub check contexts and branch protection still need online verification.
+
+  If any matrix leg fails or is cancelled, the dependent test gate is normally
+  skipped, not failed. verify-release requires each configured release job to
+  conclude success, so a skipped gate blocks publication (even if the overall
+  workflow conclusion were success).
+
+  GitHub branch protection treats skipped jobs as acceptable status checks.
+  Requiring only the gate therefore does NOT guarantee a failing matrix blocks
+  merging. Also require every matrix test check in GitHub branch protection or
+  its active ruleset, using the exact check names observed in a PR run. Keep
+  those requirements aligned when matrix membership changes. They supplement
+  the static "test" name in git.releaseRequiredChecks; do not put dynamic matrix
+  names in that setting. Alternatively, use separate static required jobs for
+  each platform and list all of them in git.releaseRequiredChecks. A gate using
+  always() to fail explicitly on failed dependencies is not currently accepted
+  by check-project's required-job condition rules.
+
+Publication: packages without private: true
+  package.json version must be exact and stable (no prerelease). Commit a
+  package-lock.json or npm-shrinkwrap.json; existing lockfile version fields
+  must match the package version.
+
+  Exactly one workflow must contain a job with ID publish. It must have a
+  static display name and a step whose run is exactly npm publish. The workflow
+  must accept the current v<package-version> tag on push. The publish job must
+  either run in a workflow restricted to v-prefixed tag pushes, or use exactly:
+    if: ${{ github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v') }}
+  The publish job must not allow failure.
+
+  In publish steps, run unconditional npm ci, then unconditional verify-release,
+  then npm publish. Neither install nor verification may allow failure.
+  Accepted direct verification commands:
+    peacekeeper verify-release
+    npm exec --no -- peacekeeper verify-release
+    node bin/peacekeeper.js verify-release
+    node node_modules/@jakobm/peacekeeper/bin/peacekeeper.js verify-release
+  The node paths may also start with ./.
+
+  Verification must receive these environment inputs, directly on the step or
+  inherited from the job/workflow:
+    RELEASE_TAG: ${{ github.ref_name }}
+    GH_TOKEN: ${{ secrets.RELEASE_POLICY_TOKEN }}
+  Set job permissions (or workflow permissions if the job has none) to include:
+    contents: read
+    id-token: write
+  contents: write is also accepted. The same toolchain rules apply to publishing.
+
+  private: true skips publication checks, but not toolchain, hooks, or PR checks.
+
+Online release policy and GitHub token setup
+  These are online installation requirements; check-project only verifies the
+  local declarations above. Use verify-release-protection to check the branch
+  policy and verify-release before publishing to check the release itself.
+
+  Configure the default branch from git.defaultBranch with every exact job name
+  in git.releaseRequiredChecks mandatory and "Require branches to be up to date
+  before merging" enabled. Choose either:
+    - Classic branch protection with strict status checks and enforcement for
+      administrators as well (no administrator bypass).
+    - Active branch rulesets requiring strict status checks, without any bypass
+      actors. Organization-inherited rulesets are included in verification.
+  Merge queues are not currently an alternative to this strict policy. For the
+  matrix example, also require its matrix checks as described above.
+
+  Create a fine-grained GitHub PAT or GitHub App installation token with access
+  to this repository and these repository permissions:
+    Administration: read
+    Contents: read
+    Pull requests: read
+    Actions: read
+  For repository rulesets, Administration: write is additionally needed because
+  GitHub only exposes bypass actors to callers with write access to the ruleset.
+  For organization-inherited rulesets, repository Administration permission
+  alone does not establish write access to the organization-owned ruleset.
+  Consult GitHub's organization ruleset endpoint documentation for supported
+  token types and organization permissions (the fine-grained token section):
+    https://docs.github.com/en/rest/orgs/rules#get-an-organization-repository-ruleset
+  The token must also have write access to the contributing ruleset for GitHub
+  to expose bypass actors. Missing bypass information causes verification to
+  fail; confirm access with verify-release-protection.
+
+  Recommended Actions secret name: RELEASE_POLICY_TOKEN. A maintainer with
+  permission to manage Actions secrets can save it with:
+    gh secret set RELEASE_POLICY_TOKEN --repo OWNER/REPO
+  Paste the token at the interactive prompt. Map the secret to GH_TOKEN on the
+  verification step. This GitHub token verifies policy and CI; npm publishing
+  uses a separate OIDC identity. The ordinary workflow GITHUB_TOKEN cannot gain
+  Administration permissions through workflow YAML. Rotate the policy token
+  when it expires, or arrange short-lived GitHub App tokens in your workflow.
+  Fork PRs do not receive repository secrets; do not expose this token by
+  running fork code with pull_request_target.
+
+  verify-release-protection uses GITHUB_BASE_REF, or git.defaultBranch outside
+  PR CI. It can be run before tests in a required trusted PR job. verify-release
+  checks matching package/tag/lockfile versions, that the tagged commit belongs
+  to the default branch and is the merge commit of a same-repository merged
+  release/v<version> PR, and the latest selected PR workflow run and required
+  jobs. The workflow and all matching required jobs must conclude success.
+  A manually created tag without that release PR is rejected. API access errors
+  and unverifiable protection settings stop verification. Use the release
+  command to prepare the release PR and tag through the supported workflow.
+
+Complete npm trusted-publishing example with Volta
+  Choose one layout; keep exactly one job with ID publish across all workflows:
+    - Keep publishing in the existing package.yml alongside PR checks. Merge
+      the publish job below into that file, retain its pull_request trigger,
+      add push.tags: ['v*'], and set the publish job condition exactly to:
+        if: ${{ github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v') }}
+      Keep git.releaseTestWorkflow and the npm trusted-publisher filename set
+      to package.yml. Do not also create a publish job in another workflow.
+    - Move publishing to a separate publish.yml as shown below. Remove the old
+      publish job from package.yml (and its tag trigger if no other job needs
+      it). Keep PR checks in package.yml and git.releaseTestWorkflow pointing
+      there. Set the npm trusted-publisher filename to publish.yml.
+
+  The complete example below uses the second layout for a public npm package.
+  Adapt an existing publish.yml instead of adding a duplicate publish job. Install
+  @jakobm/peacekeeper as a project development dependency so npm ci makes the
+  verification command available. The GitHub-hosted Ubuntu runner provides gh.
+
+  Pin Node >=22.14.0 and npm >=11.5.1 in package.json for npm trusted publishing;
+  for example, exact pins 22.14.0 and 11.21.0 meet those minimums. Do not install
+  another npm globally in CI. In the package's npmjs.com settings, add a GitHub
+  Actions trusted publisher with the exact owner, repository and workflow
+  filename publish.yml for the separate layout, or package.yml for the combined
+  layout (filename only). Enable direct npm publish in its
+  allowed actions; staged publishing alone does not support this workflow.
+  If you configure an npm trusted-publisher environment name, add the matching
+  environment to the publish job. Use GitHub-hosted runners; npm does not
+  currently support self-hosted runners for trusted publishing.
+
+  Set package.json publication settings for this public npm package:
+    "publishConfig": {
+      "registry": "https://registry.npmjs.org/",
+      "access": "public"
+    }
+  Use the package's intended visibility instead if publishing a private scoped
+  npm package. npm package visibility is separate from package.json private:
+  true, which prevents npm publication altogether.
+
+  Complete .github/workflows/publish.yml:
+    name: Publish
+    on:
+      push:
+        tags: ['v*']
+    jobs:
+      publish:
+        runs-on: ubuntu-24.04
+        permissions:
+          contents: read
+          id-token: write
+        steps:
+          - uses: actions/checkout@v5
+          - uses: volta-cli/action@v5
+            with:
+              registry-url: https://registry.npmjs.org
+          - run: npm ci
+          - name: Verify release
+            env:
+              GH_TOKEN: ${{ secrets.RELEASE_POLICY_TOKEN }}
+              RELEASE_TAG: ${{ github.ref_name }}
+            run: npm exec --no -- peacekeeper verify-release
+          - run: npm publish
+
+  Volta selects the pinned tools and its registry-url input configures npm's
+  registry, replacing that setup-node responsibility. publishConfig also pins
+  the publication target. npm publish detects GitHub's OIDC environment and
+  exchanges its identity for a short-lived npm credential; id-token: write
+  enables this and the npm trusted-publisher entry authorizes the workflow.
+  No NPM_TOKEN, npm login, or secret NODE_AUTH_TOKEN is needed to publish.
+  Do not carry an old npm publishing token into this workflow. If npm ci needs
+  private dependencies, configure their read authentication separately; OIDC
+  publishing does not authenticate dependency installation. Add any necessary
+  build step before publication, keeping npm publish as its own direct step.
+
+  check-project verifies supported local workflow structure, not the npm OIDC
+  minimum versions, trusted-publisher registration, package visibility, registry
+  credentials, or actual publishing access. Verify those external settings too.
+  Upstream references for provider-specific setup and changing prerequisites:
+    https://docs.npmjs.com/trusted-publishers
+    https://github.com/volta-cli/action#readme
+    https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches
+
+What a passing check does and does not establish
+  Passing means the supported local configuration matches these conventions.
+  It does not prove tests ran or passed, inspect test-script behavior, validate
+  installed dependency versions, or check Git remotes and ignored files.
+  It cannot confirm actual GitHub branch protection, token/secret access,
+  successful workflow runs, or npm trusted publisher configuration. Those need
+  online verification; verify-release handles the release checks it supports.
+
+Using this check in the test chain
+  Add "pretest": "peacekeeper check-project" to package.json, prepending it
+  to any existing pretest command. This also runs before cached test receipts
+  can skip the test runner. Putting the check only in tests.commands does not
+  guarantee it runs when a cached receipt is reused.

package/scripts/check-project.js

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { isDeepStrictEqual } = require('node:util');
+const semver = require('semver');
+const YAML = require('yaml');
+const { projectConfig } = require('./project-config');
+const { planHooks, classifyCommand } = require('./install-hooks');
+const { inspectWorkflow, ensureLockfilesMatch } = require('./release-core');
+
+function read(root, file, parse = JSON.parse) {
+  try { return parse(fs.readFileSync(path.join(root, file), 'utf8')); }
+  catch (error) { throw new Error(`${file}: ${error.message}`); }
+}
+function unconditional(value) {
+  return value === undefined || value === 'success()' || value === '${{ success() }}';
+}
+function directCommand(step, expression) {
+  return typeof step?.run === 'string' && expression.test(step.run.trim());
+}
+const testCommand = /^npm (?:test|run test(?::[\w-]+)?|pack --dry-run(?: --json)?)$/u;
+const installCommand = /^npm ci$/u;
+const verifyCommand = /^(?:peacekeeper|npm exec --no -- peacekeeper|node (?:\.\/)?(?:node_modules\/@jakobm\/peacekeeper\/)?bin\/peacekeeper\.js) verify-release$/u;
+
+function checkProject(cwd = process.cwd()) {
+  const config = projectConfig(cwd);
+  const root = config.root;
+  const manifest = read(root, 'package.json');
+  const errors = [];
+  let category;
+  const requireThat = (condition, message) => {
+    if (!condition) errors.push(`[${category}] ${message}`);
+    return Boolean(condition);
+  };
+  const check = (nextCategory, action) => {
+    const previous = category;
+    category = nextCategory;
+    try { action(); } catch (error) { errors.push(`[${category}] ${error.message}`); }
+    finally { category = previous; }
+  };
+  const workflows = new Map();
+  check('CI', () => {
+    const directory = path.join(root, '.github/workflows');
+    for (const file of fs.readdirSync(directory).filter(file => /\.ya?ml$/u.test(file))) {
+      check('CI', () => {
+        const document = read(root, `.github/workflows/${file}`, YAML.parse);
+        if (!requireThat(document && typeof document.jobs === 'object' && document.jobs !== null && !Array.isArray(document.jobs), `${file}: declare workflow jobs; dependent checks are blocked.`)) return;
+        workflows.set(file, document);
+      });
+    }
+    requireThat(workflows.size, 'Add a PR workflow in .github/workflows.');
+  });
+
+  // These are runtime compatibility floors, not a list of latest releases.
+  const actionMinimums = new Map([['actions/checkout', 5], ['volta-cli/action', 5]]);
+  for (const [file, workflow] of workflows) {
+    for (const [id, job] of Object.entries(workflow.jobs)) {
+      check('CI', () => {
+        const runner = job?.['runs-on'];
+        const labels = typeof runner === 'object' && !Array.isArray(runner) ? runner?.labels : runner;
+        const values = (Array.isArray(labels) ? labels : [labels]).flatMap(label => {
+          if (typeof label !== 'string') return [];
+          const keys = [...label.matchAll(/\$\{\{\s*matrix\.([\w-]+)\s*\}\}/gu)].map(match => match[1]);
+          return [label, ...keys.flatMap(key => {
+            const matrix = job.strategy?.matrix;
+            return [matrix?.[key], ...(matrix?.include || []).map(entry => entry[key])].flat();
+          })];
+        });
+        const moving = [...new Set(values.filter(value => typeof value === 'string' && /(?:^|[^\w-])[\w-]+-latest(?:$|[^\w-])/u.test(value)))];
+        requireThat(!moving.length,
+          `${file}/${id}: found ${moving.join(', ')}; pin runner images (for example ubuntu-24.04) instead of moving *-latest labels.`);
+        for (const step of job?.steps || []) {
+          if (typeof step?.uses !== 'string') continue;
+          const separator = step.uses.lastIndexOf('@');
+          const action = step.uses.slice(0, separator);
+          const minimum = actionMinimums.get(action);
+          if (!minimum) continue;
+          const version = /^v(\d+)(?:\.\d+){0,2}$/u.exec(step.uses.slice(separator + 1));
+          requireThat(version && Number(version[1]) >= minimum,
+            `${file}/${id}: found ${step.uses}; use ${action}@v${minimum} or newer with a stable version tag; older releases use deprecated Node.js action runtimes. SHA and branch refs cannot be verified offline.`);
+        }
+      });
+    }
+  }
+
+  check('tools', () => {
+    for (const name of ['node', 'npm']) {
+      requireThat(semver.valid(manifest.volta?.[name]) === manifest.volta?.[name] && typeof manifest.volta?.[name] === 'string',
+        `package.json: pin an exact volta.${name} version with volta pin.`);
+    }
+    requireThat(typeof manifest.engines?.node === 'string' && semver.validRange(manifest.engines.node)
+      && semver.satisfies(manifest.volta?.node, manifest.engines.node),
+    'package.json: volta.node must satisfy engines.node.');
+    requireThat(!fs.existsSync(path.join(root, '.nvmrc')),
+      '.nvmrc must be removed; package.json volta pins select the Node and npm versions.');
+  });
+
+  for (const [file, workflow] of workflows) {
+    for (const [id, job] of Object.entries(workflow.jobs)) {
+      check('tools', () => {
+        const steps = job?.steps || [];
+        const nodeSteps = steps.filter(step => /^(?:actions\/setup-node|volta-cli\/action)@/u.test(step?.uses || '')
+          || /\b(?:node|npm|npx|volta)\s/u.test(step?.run || ''));
+        if (!nodeSteps.length) return;
+        const toolIndex = steps.findIndex(step => /^volta-cli\/action@/u.test(step?.uses || ''));
+        requireThat(toolIndex >= 0, `${file}/${id}: use volta-cli/action to select project Node and npm versions. Volta setup checks are blocked until that step exists.`);
+        requireThat(steps.filter(step => /^volta-cli\/action@/u.test(step?.uses || '')).length <= 1, `${file}/${id}: use one Volta setup step per job.`);
+        requireThat(!steps.some(step => /^actions\/setup-node@/u.test(step?.uses || '')
+          || /\b(?:nvm\s+(?:use|install)|volta\s+(?:install|pin|run)|npm\s+(?:i|install)\s+(?:--global|-g)\b)/u.test(step?.run || '')),
+        `${file}/${id}: remove competing Node/npm setup commands.`);
+        if (toolIndex < 0) return; // Remaining setup checks need a Volta step.
+        const tool = steps[toolIndex];
+        requireThat(unconditional(tool.if) && !tool['continue-on-error'], `${file}/${id}: Volta setup must not be conditional or allowed to fail.`);
+        requireThat(steps.slice(0, toolIndex).some(step => /^actions\/checkout@/u.test(step?.uses || '') && unconditional(step.if) && !step['continue-on-error']),
+          `${file}/${id}: check out the project before Volta setup.`);
+        requireThat(!['node-version', 'npm-version', 'package-json-path'].some(key => Object.hasOwn(tool.with || {}, key)),
+          `${file}/${id}: remove Volta version/path overrides; use package.json.`);
+        requireThat(!steps.slice(0, toolIndex).some(step => /\b(?:node|npm|npx)\s/u.test(step?.run || '')),
+          `${file}/${id}: set up Volta before Node/npm commands.`);
+      });
+    }
+  }
+
+  check('hooks', () => {
+    const document = read(root, '.codex/hooks.json');
+    const localSource = fs.realpathSync(root) === fs.realpathSync(path.resolve(__dirname, '..'));
+    const expected = planHooks(document, localSource).document;
+    for (const event of new Set([...Object.keys(document.hooks || {}), ...Object.keys(expected.hooks)])) {
+      const owned = groups => groups.flatMap(group => {
+        const handlers = group.hooks.filter(hook => classifyCommand(hook.command) !== 'other');
+        if (handlers.length) requireThat(Object.keys(group).every(key => key === 'hooks'),
+          '.codex/hooks.json: peacekeeper lifecycle hooks must not have group conditions.');
+        return handlers;
+      });
+      requireThat(isDeepStrictEqual(owned(document.hooks?.[event] || []), owned(expected.hooks[event] || [])),
+        `.codex/hooks.json: missing, duplicate or outdated ${event} lifecycle hooks; run peacekeeper install-hooks.`);
+    }
+  });
+
+  const published = manifest.private !== true;
+  const filename = config.projectChecks?.testWorkflow || config.git.releaseTestWorkflow || 'test.yml';
+  const required = [...new Set([...(config.projectChecks?.requiredJobs || config.git.releaseRequiredChecks || ['test']), ...(published ? config.git.releaseRequiredChecks || [] : [])])];
+  check('CI', () => {
+    const workflow = workflows.get(filename);
+    if (!requireThat(workflow, `${filename}: configured PR workflow is missing (selected by ${config.projectChecks?.testWorkflow ? 'projectChecks.testWorkflow' : config.git.releaseTestWorkflow ? 'git.releaseTestWorkflow' : 'default test.yml'}). Set projectChecks.testWorkflow${published ? ' and git.releaseTestWorkflow to the same existing file' : ' to an existing file'} in peacekeeper.config.json. PR checks are blocked until it can be read.`)) return;
+    const on = workflow.on;
+    const simpleTrigger = on === 'pull_request' || (Array.isArray(on) && on.includes('pull_request'));
+    requireThat(simpleTrigger || (on && typeof on === 'object' && Object.hasOwn(on, 'pull_request')), `${filename}: declare an on.pull_request trigger.`);
+    const filters = simpleTrigger ? null : on?.pull_request;
+    requireThat(filters === null || (filters && typeof filters === 'object' && !Array.isArray(filters)
+      && !['paths', 'paths-ignore', 'branches-ignore', 'types'].some(key => Object.hasOwn(filters, key))
+      && (!filters.branches || (Array.isArray(filters.branches) && filters.branches.includes(config.git.defaultBranch)))),
+    `${filename}: PR filters must include the default branch and must not skip required checks by path or event type.`);
+    const checked = new Set();
+    function requiredJob(id, job, testsRequired) {
+      if (!requireThat(job && typeof job === 'object', `${filename}/${id}: required job is missing; checks for this job are blocked.`)) return;
+      requireThat(unconditional(job.if) || job.if === "${{ github.event_name == 'pull_request' }}", `${filename}/${id}: required PR job must not be skipped by an if condition.`);
+      requireThat(!job['continue-on-error'] && !job.uses, `${filename}/${id}: required jobs must have verifiable local steps and must not allow failure.`);
+      if (checked.has(id)) return;
+      checked.add(id);
+      const needs = job.needs === undefined ? [] : Array.isArray(job.needs) ? job.needs : [job.needs];
+      for (const dependency of needs) requiredJob(dependency, workflow.jobs[dependency], false);
+      if (!testsRequired) return;
+      const steps = job.steps || [];
+      const installed = steps.findIndex(step => directCommand(step, installCommand) && unconditional(step.if) && !step['continue-on-error']);
+      const tested = steps.findIndex(step => directCommand(step, testCommand) && unconditional(step.if) && !step['continue-on-error']);
+      requireThat(installed >= 0 && tested > installed, `${filename}/${id}: run unconditional npm ci before npm test, npm run test:<name>, or npm pack --dry-run (without continue-on-error).`);
+    }
+    for (const name of required) {
+      const matching = Object.entries(workflow.jobs).filter(([id, job]) => (job.name || id) === name);
+      if (!requireThat(matching.length === 1 && !name.includes('${{'), `${filename}: required job ${name} must have a unique static name. Match a job name (or ID when name is absent); checks for this job are blocked.`)) continue;
+      // Validate the test steps even if this job was visited as a dependency.
+      checked.clear();
+      requiredJob(...matching[0], true);
+    }
+  });
+
+  if (published) check('publication', () => {
+    requireThat(config.git.releaseRequiredChecks?.length, 'Configure git.releaseRequiredChecks for a published package.');
+    requireThat(!config.git.releaseTestWorkflow || config.git.releaseTestWorkflow === filename,
+      'projectChecks.testWorkflow must match git.releaseTestWorkflow.');
+    requireThat(semver.valid(manifest.version) === manifest.version && !semver.prerelease(manifest.version), 'package.json: published packages need an exact stable version.');
+    requireThat(['package-lock.json', 'npm-shrinkwrap.json'].some(file => fs.existsSync(path.join(root, file))), 'Commit a package lockfile before publishing.');
+    check('publication', () => ensureLockfilesMatch(root, manifest.version));
+    let publishing;
+    try { publishing = inspectWorkflow(root, `v${manifest.version}`); }
+    catch (error) {
+      requireThat(false, `${error.message} Publish-step checks are blocked until a supported publish workflow can be identified.`);
+      return;
+    }
+    const workflow = workflows.get(path.basename(publishing.path));
+    const job = workflow.jobs.publish;
+    const steps = job.steps;
+    requireThat(!job['continue-on-error'], `${publishing.path}: publication must not allow failure.`);
+    const installed = steps.findIndex(step => directCommand(step, installCommand) && unconditional(step.if) && !step['continue-on-error']);
+    const verify = steps.findIndex(step => directCommand(step, verifyCommand));
+    const publish = steps.findIndex(step => step.run === 'npm publish');
+    requireThat(installed >= 0 && verify > installed && verify < publish && unconditional(steps[verify].if) && !steps[verify]['continue-on-error'],
+      `${publishing.path}: run verify-release unconditionally before npm publish.`);
+    const environment = { ...workflow.env, ...job.env, ...steps[verify]?.env };
+    requireThat(environment.RELEASE_TAG === '${{ github.ref_name }}' && environment.GH_TOKEN,
+      `${publishing.path}: verify-release needs RELEASE_TAG from github.ref_name and GH_TOKEN.`);
+    const permissions = job.permissions || workflow.permissions;
+    requireThat(permissions && permissions['id-token'] === 'write' && ['read', 'write'].includes(permissions.contents),
+      `${publishing.path}: declare contents: read and id-token: write for publishing.`);
+    const selected = config.git.releaseTestWorkflow || path.basename(publishing.path);
+    requireThat(selected === filename, 'Configure git.releaseTestWorkflow to select the checked PR workflow.');
+  });
+  return { errors, published };
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  if (args.length === 1 && args[0] === '--explain') {
+    process.stdout.write(fs.readFileSync(path.join(__dirname, 'check-project-requirements.txt'), 'utf8'));
+    return;
+  }
+  if (args.length === 1 && ['--help', '-h'].includes(args[0])) {
+    console.log('Usage: peacekeeper check-project [--explain]');
+    return;
+  }
+  if (args.length) throw new Error('Usage: peacekeeper check-project [--explain]');
+  console.log('Run peacekeeper check-project --explain for the complete expected project architecture and requirements.');
+  const { errors, published } = checkProject();
+  if (errors.length) {
+    for (const error of errors) console.error(`FAIL ${error}`);
+    process.exitCode = 1;
+  } else console.log(`Project checks passed: tools, hooks, CI${published ? ', publication' : ' (private package; publication skipped)'}.`);
+}
+if (require.main === module) {
+  try { main(); } catch (error) { console.error(`FAIL ${error.message}`); process.exitCode = 1; }
+}
+module.exports = { checkProject };

package/scripts/check-test-receipt.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+
+const fs = require('node:fs');
+const { ROOT, environmentFingerprint, receiptPath, snapshot } = require('./receipt-state');
+const { projectConfig } = require('./project-config');
+function successMessage(root = ROOT()) {
+  const command = projectConfig(root).tests.npmTestUsesRunner
+    ? 'npm test -- rerun'
+    : 'node node_modules/@jakobm/peacekeeper/bin/peacekeeper.js run-tests rerun';
+  return `Tests already passed for this change set. In order to rerun tests anyway, use: ${command}`;
+}
+
+function matchesReceipt(receipt, root = ROOT()) {
+  const { receiptMaxAgeMinutes } = projectConfig(root).tests;
+  if (!receipt || receipt.version !== 1 || !Number.isFinite(receipt.passedAt) ||
+      Date.now() < receipt.passedAt || Date.now() - receipt.passedAt > receiptMaxAgeMinutes * 60_000 ||
+      receipt.environment !== environmentFingerprint()) return false;
+  const current = snapshot(root, receipt.baseCommit);
+  return JSON.stringify(current.changedFiles) === JSON.stringify(receipt.changedFiles);
+}
+
+function checkReceipt(root = ROOT()) {
+  let receipt;
+  try {
+    receipt = JSON.parse(fs.readFileSync(receiptPath(root), 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT' || error instanceof SyntaxError) return false;
+    throw error;
+  }
+  return matchesReceipt(receipt, root);
+}
+
+if (require.main === module) {
+  if (process.argv.length !== 2) {
+    console.error('Usage: node scripts/check-test-receipt.js');
+    process.exitCode = 2;
+  } else {
+    try {
+      if (!checkReceipt()) process.exitCode = 1;
+      else console.log(successMessage());
+    } catch (error) {
+      console.error(error.message);
+      process.exitCode = 1;
+    }
+  }
+}
+
+module.exports = { checkReceipt, matchesReceipt, successMessage };