diff --git a/bin/gstack-pregate b/bin/gstack-pregate
index c63d17e49..1dd04f857 100755
--- a/bin/gstack-pregate
+++ b/bin/gstack-pregate
@@ -221,10 +221,11 @@ function cmdClear(root: string, rest: string[]): number {
if (!read.file) { process.stderr.write(resultLine('gstack-pregate clear', 'PREGATE_STALE', `${out} is missing or invalid; run gstack-pregate first`) + '\n'); return EXIT.fail; }
const runs = rest.flatMap((a, i) => a === '--run' ? [rest[i + 1]!] : []);
const runUrl = flag(rest, '--run-url');
- const checked = runs.length || runUrl ? runCheck(root, rest.includes('--allow-repo-commands')) : undefined;
- if (checked && 'error' in checked && runs.length) { process.stderr.write(`gstack-pregate clear: ${checked.error}\n`); return EXIT.fail; }
+ const bundleLane = flag(rest, '--bundle-lane');
+ const checked = runs.length || runUrl || bundleLane ? runCheck(root, lane, rest.includes('--allow-repo-commands')) : undefined;
+ if (checked && 'error' in checked && (runs.length || checked.profiled)) { process.stderr.write(`gstack-pregate clear: ${checked.error}${checked.profiled ? `; the base branch declares a run profile for ${lane}, so it clears only with --run` : ''}\n`); return EXIT.fail; }
const evidence = checked && !('error' in checked) ? checked : undefined;
- const decision = clearDecision(read.file, lane, { runUrl, runs, bundleLane: flag(rest, '--bundle-lane'), receiptPath: flag(rest, '--receipt'), evidence }, root);
+ const decision = clearDecision(read.file, lane, { runUrl, runs, bundleLane, receiptPath: flag(rest, '--receipt'), evidence }, root);
if ('refused' in decision) {
if (decision.refused === 'usage') { process.stderr.write(`gstack-pregate clear: ${decision.message}\n`); return EXIT.usage; }
process.stderr.write(`gstack-pregate clear: receipt refused — ${decision.message}; fix: ${decision.fix ?? RESULT_CODES.PREGATE_RECEIPT_INVALID.fix} ${resultCodeSuffix('PREGATE_RECEIPT_INVALID')}\n`);
@@ -235,17 +236,18 @@ function cmdClear(root: string, rest: string[]): number {
if (/ runs=\S+ profiles=/.test(decision.receipt)) process.stdout.write(`REUSE: accepted ${lane} ${decision.receipt}\n`);
if (decision.substitution) process.stdout.write(`PREGATE_RECEIPT_SUBSTITUTED: ${describeSubstitution(decision.substitution)}\n`);
process.stdout.write(`PREGATE_CLEARED: ${lane} receipt=${decision.receipt} verdict=${file.verdict}${decision.attested ? ` (attested, not validated: ${lane} has no machine-checkable receipt)` : ''}\n`);
+ if (checked && 'error' in checked) process.stderr.write(`gstack-pregate clear: run profiles unavailable (${checked.error}); ${lane} was recorded without run verification\n`);
return EXIT.ok;
}
/** The run-evidence inputs for `clear --run`: the base branch's run profiles, this repository on GitHub, and the gate's inventory command (a pin-file command, so only with --allow-repo-commands). */
-function runCheck(root: string, allowRepoCommands: boolean): RunCheck | { error: string } {
+function runCheck(root: string, lane: string, allowRepoCommands: boolean): RunCheck | { error: string; profiled?: boolean } {
const base = resolveBaseBranch(root);
const loaded = loadConfigFromBase(root, base);
if (isConfigUnavailable(loaded)) return { error: `the base branch's ${PREGATE_CONFIG_PATH} is unreadable (${loaded.detail}); run profiles come only from the base` };
if (loaded.errors.length) return { error: `the base branch's ${PREGATE_CONFIG_PATH} is invalid: ${loaded.errors.map(e => `${e.path}: ${e.message}`).join('; ')}` };
const repo = /github\.com[:/]([\w.-]+\/[\w.-]+?)(?:\.git)?\/?$/.exec(gitOut(root, ['remote', 'get-url', 'origin']) ?? '')?.[1];
- if (!repo) return { error: 'origin is not a github.com repository; run evidence is read from GitHub Actions' };
+ if (!repo) return { error: 'origin is not a github.com repository; run evidence is read from GitHub Actions', profiled: lane === REMOTE_GATE_LANE ? !!loaded.config.remote_gate_runs : !!loaded.config.run_profiles[lane] };
return {
repo, deps: ghRunDeps(repo, root), profiles: loaded.config.run_profiles, gateRuns: loaded.config.remote_gate_runs, now: new Date(),
inventory: command => {
diff --git a/docs/pregate.md b/docs/pregate.md
index 3bf588201..8df0fbc7a 100644
--- a/docs/pregate.md
+++ b/docs/pregate.md
@@ -592,7 +592,10 @@ on prose: a pasted URL is only a pointer the verifier resolves.
```
Profiles are read only from `origin/`, so a pull request can tighten
-them but never relax them. Each profile names the workflow file, the events it
+them but never relax them. That covers the profile, not the suite it names: the
+workflow file a run executed and the inventory command are the branch's own, as
+the remote gate's script already is, so a diff to either is reviewed like any
+other gate change. Each profile names the workflow file, the events it
accepts, every job that must have passed (each exactly once), and the artifact
holding the run's `tree.json`. `max_age_hours` (1–168, default 24) bounds how
old the run may be, and `os` (`Linux`, `macOS`, `Windows`) requires
@@ -613,8 +616,12 @@ once:
- `tree.json` names this run, attempt, event and head. It is not a reuse
record (a reuse is never evidence). Its tree equals the tree git computes for
the run's head commit.
-- No newer run of the same workflow on that head, or on pregate.json's own
- head, failed, was cancelled or is still running.
+- No run of the same workflow on that head, or on pregate.json's own head,
+ whose newest attempt started after this run was created failed, was
+ cancelled or is still running (`run_started_at`, so a red re-run of an older
+ run counts, and re-running this run does not hide a failure in between).
+- Its event is `push` or `workflow_dispatch`. A `pull_request` run tests the
+ merge commit, not the head tree, so no profile may accept it.
- The run finished within `max_age_hours`, and on the profile's OS when it
names one.
- For `pregate.json/remote_gate`: there is exactly one verified run per
@@ -632,13 +639,21 @@ verification is named with its own reason (`fork_run`, `event_mismatch`,
`run_not_success`, `job_missing`, `artifact_mismatch`, `artifact_reused`,
`tree_mismatch`, `newer_run_vetoes`, `run_stale`, `os_mismatch`, `api_error`,
…); the clear-level codes are `no_verified_run`, `tree_mismatch` (runs on
-different trees), `inventory_failed`, `inventory_empty`, `inventory_uncovered`
-and `no_tests`. Accepted, `clear` prints `REUSE: accepted `, and
+different trees), `tree_not_stamp_only`, `inventory_failed`, `inventory_empty`,
+`inventory_uncovered` and `no_tests`. A wrong run count or a lane with no
+profile is a usage error (exit 2), not a REUSE refusal. When the base config or
+the GitHub origin cannot be read, `--run` fails, and so do `--run-url` and
+`--bundle-lane` for a lane the base profiles; any other lane is recorded as
+before, with a warning naming the cause. Accepted, `clear` prints `REUSE: accepted `, and
the receipt reads
`remote-gate tree= tests= runs=/,… profiles=