From c3c96b3ad0af6a486958872020ace795e83a8f2d Mon Sep 17 00:00:00 2001 From: garrytan Date: Mon, 26 Oct 2026 16:10:24 +0000 Subject: [PATCH] docs(pregate): PREGATE_INCOMPLETE names a signal-killed runner; CHANGELOG lists every doc edit Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --- CHANGELOG.md | 2 +- docs/troubleshooting.md | 10 ++++++---- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fbd9bd1f8..bb401fab0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,7 +14,7 @@ - **`literals` no longer floods on a common module stem or a one-digit value** (`lib/pregate/checks/literals.ts` `consumersOf`). A test file counted as a consumer of a changed constant when it merely contained the source file's stem as a bare word (`install`, `retry`), so `GSTACK_CAPY_WRAPPER=2 → 3` in `capy/skill/gstack/scripts/install.sh` flagged 575 test files (`PREGATE_LITERALS`; GSTA-114, #3475). The module now counts only as a path fragment (`/install.sh`, `/retry.js`, `/retry'`), and an old value shorter than two characters needs the constant's name in the file. The same edit now flags the 5 files that name `GSTACK_CAPY_WRAPPER`. Regression: `test/pregate-selection.test.ts` "consumersOf: a module stem is a path fragment…". ### Changed -- `docs/pregate.md`: the `allowlist` row, the "No policy yet" paragraph, and three sections (allowlist, environment failures, scratch). `docs/troubleshooting.md`: `PREGATE_NO_POLICY` and `PREGATE_ENVIRONMENT` anchors; `PREGATE_NO_LANE` and `PREGATE_INCOMPLETE` point at them. `lib/headless-artifacts.ts`: the pregate schema accepts `cause`, `environment` and `scratch` (additive). `gstack-pregate --help` documents `--run`. +- `docs/pregate.md`: the `allowlist` row, the "No policy yet" paragraph, three sections (allowlist, environment failures, scratch), the synopsis (`--run `), the stage-1 `guards` and stage-2 `lanes` bullets and the Publication code list. `docs/troubleshooting.md`: `PREGATE_NO_POLICY` and `PREGATE_ENVIRONMENT` anchors; `PREGATE_NO_LANE` and `PREGATE_INCOMPLETE` point at them; `PREGATE_GUARD_FAILED` carves out a guard whose own binary is off PATH, `PREGATE_SECRETS` points at the allowlist, `PREGATE_INCOMPLETE` names a signal-killed runner. `lib/headless-artifacts.ts`: the pregate schema accepts `cause`, `environment` and `scratch` (additive). `gstack-pregate --help` documents `--run`. - Existing pregate tests whose fixtures had no policy and asserted the hard `PREGATE_NO_LANE` (`test/pregate-selection.test.ts`, `pregate-docs-lane-review.test.ts`, `pregate-non-js.test.ts`, `pregate-rust.test.ts`) now assert the no-policy warning and that the file is still named as unmapped; the Dart missing-SDK cases in `test/pregate-dart.test.ts` assert `PREGATE_ENVIRONMENT` and the new fix text. ### Tests diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index b0b15ba84..3f081d302 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -3078,16 +3078,18 @@ should have found it, report the specifier as a resolver gap. ### `PREGATE_INCOMPLETE` -**Meaning.** A check timed out, repo commands were not allowed, no runner is -declared or detected, or the working tree changed while the check ran. -Incomplete is never pass and blocks publication. A tool missing from PATH, a +**Meaning.** A check timed out, a runner process was killed by a signal (out of +memory, an outside kill) and ended without an exit code, repo commands were not +allowed, no runner is declared or detected, or the working tree changed while +the check ran. Incomplete is never pass and blocks publication. A tool missing from PATH, a network or quota error before any test ran, or a full disk is [`PREGATE_ENVIRONMENT`](#pregate-environment) instead, so the machine's failure reads apart from the diff's. **Fix.** Pass `--allow-repo-commands`, commit the `pubspec.yaml` of a Dart package the message says has none (or declare `runner`), raise `--timeout`, or -keep the tree still, then rerun. A tool missing from PATH is +keep the tree still, then rerun. A runner killed by a signal never passes: read +the lane log, then rerun or split the selection. A tool missing from PATH is [`PREGATE_ENVIRONMENT`](#pregate-environment), with its own fix.