From 3d0baf320efc0726dbb7e4fdaf7afcfc82329b19 Mon Sep 17 00:00:00 2001 From: garrytan Date: Tue, 13 Oct 2026 01:09:04 +0000 Subject: [PATCH] result codes: PLAN_SECTIONS_INVALID, PLAN_AMEND_PENDING, GSTACK_VERSION_CHANGED, INSTALL_VERDICT_FAILED, ARTIFACT_GATE_UNSETTLED Troubleshooting anchors for each and the regenerated doctor components table (field wave lane B-core). Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --- bin/gstack-doctor-components.sh | 5 +++ docs/troubleshooting.md | 68 +++++++++++++++++++++++++++++++++ lib/result-codes.ts | 25 ++++++++++++ 3 files changed, 98 insertions(+) diff --git a/bin/gstack-doctor-components.sh b/bin/gstack-doctor-components.sh index cd35ad99b..34d93fea1 100644 --- a/bin/gstack-doctor-components.sh +++ b/bin/gstack-doctor-components.sh @@ -166,6 +166,11 @@ gstack_result_anchor() { CONTRIBUTOR_SOURCE_UNAVAILABLE) printf '%s' 'contributor-source-unavailable' ;; BRIEF_INPUT_MISSING) printf '%s' 'brief-input-missing' ;; DRAFT_DIRECTION_UNRESOLVED) printf '%s' 'draft-direction-unresolved' ;; + PLAN_SECTIONS_INVALID) printf '%s' 'plan-sections-invalid' ;; + PLAN_AMEND_PENDING) printf '%s' 'plan-amend-pending' ;; + GSTACK_VERSION_CHANGED) printf '%s' 'gstack-version-changed' ;; + INSTALL_VERDICT_FAILED) printf '%s' 'install-verdict-failed' ;; + ARTIFACT_GATE_UNSETTLED) printf '%s' 'artifact-gate-unsettled' ;; *) return 1 ;; esac } diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 54e28a2a9..3025e4b2b 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -2464,3 +2464,71 @@ it failed, `git checkout -- . && ./setup` in the checkout discards local edits and rewrites every file. Use your install directory if it is not `~/.claude/skills/gstack` (`./setup --status` prints it). Expected result: the next `./setup` prints no CRLF warning. + + +### `PLAN_SECTIONS_INVALID` + +**Meaning.** `gstack-autoplan next` reviews only the plan's `## Implementation +plan` section and keeps the `## Review record` private, so the plan needs +exactly one non-empty Implementation plan section followed by one Review record +section, both outside code fences. A plan with neither heading is wrapped +automatically; one heading alone, duplicate or reversed headings, or an empty +section is refused before anything is written. The error names the problem. + +**Fix.** Add the missing heading, or rerun the first `next` with `--scaffold`: +it writes `/plan-source.md` with the missing heading added, reviews that +copy and prints `SCAFFOLDED:`. Your plan file is never edited. Duplicate, +reversed or empty sections are ambiguous and must be fixed by hand. + + +### `PLAN_AMEND_PENDING` + +**Meaning.** The owner accepted at least one plan change at the gate (each was +printed as an `APPLY:` line), and the run's plan has not absorbed it, so a rerun +would review the old plan. `next` refuses until every accepted change is +incorporated or withdrawn; `export` refuses a `complete` run with one pending. + +**Fix.** Edit the plan, then `gstack-autoplan revise --out --plan +--incorporates `. `revise` binds each named id to the old and +new Implementation-plan hashes and refuses when the Implementation plan did +not change; an id you do not name stays pending. To drop an accepted change +instead, `gstack-autoplan revise --out --withdraw ` records +the withdrawal in the journal. + + +### `GSTACK_VERSION_CHANGED` + +**Meaning.** `run.json.gstack_version` names a different gstack than the one +running. For an older run (or one written before the field existed) this is a +notice: the command journals `gstack_version_changed`, runs the forward +migrations (for example rewriting decision ids minted before 1.91.95) and +continues. For a run written by a newer gstack the command refuses, because an +older runner cannot know the newer state. + +**Fix.** Nothing for the notice. For the refusal, upgrade gstack +(`bin/gstack-upgrade`) on this machine and rerun the command. + + +### `INSTALL_VERDICT_FAILED` + +**Meaning.** On a Capy host (`GSTACK_CAPY=1`) `gstack-autoplan`'s mutating +verbs (`next`, `submit`, `answer`, `revise`, `export`) need the install verdict +the Capy wrapper writes (`GSTACK_INSTALL_VERDICT`) to say `gstack: ok` for this +checkout and HEAD. Missing, failing, or written for another checkout or HEAD +refuses before anything is written. `status` and `resume` stay available. + +**Fix.** Run the Capy gstack skill wrapper until its trailer is `gstack: ok`, +then launch commands with its `GSTACK_LAUNCH` line. To proceed anyway, set +`GSTACK_ALLOW_UNSUPPORTED_RUNTIME=1`; the override is recorded in +`run.json.deviations` and printed as `ADMISSION: override`. + + +### `ARTIFACT_GATE_UNSETTLED` + +**Meaning.** `gstack-artifact validate` found a run whose status is `complete` +while an approval item of its last gate revision is still pending, or an +accepted plan change (`run.json.amendments`) is still pending. The runner never +writes that state; it comes from a hand edit or an older runner. + +**Fix.** Answer the gate with `gstack-autoplan answer` until no approval is +pending, and `revise --incorporates` or `--withdraw` each pending amendment. diff --git a/lib/result-codes.ts b/lib/result-codes.ts index d73b7c304..79e867273 100644 --- a/lib/result-codes.ts +++ b/lib/result-codes.ts @@ -466,6 +466,31 @@ export const RESULT_CODES = { summary: 'a `draft direction stands until the owner decides` line names a decision that is still pending', fix: 'answer the gate (`gstack-autoplan answer`) before closing; the close rewrites only decided lines', }, + PLAN_SECTIONS_INVALID: { + anchor: 'plan-sections-invalid', + summary: 'the plan does not have exactly one non-empty `## Implementation plan` section followed by one `## Review record` section', + fix: 'add the missing heading, or rerun the first `gstack-autoplan next` with --scaffold to review a scaffolded copy (your plan file is never edited); duplicate, reversed or empty sections are fixed by hand', + }, + PLAN_AMEND_PENDING: { + anchor: 'plan-amend-pending', + summary: 'the owner accepted plan changes at the gate that the plan has not absorbed yet', + fix: 'edit the plan, then `gstack-autoplan revise --out --plan --incorporates `; or drop one with `gstack-autoplan revise --out --withdraw `', + }, + GSTACK_VERSION_CHANGED: { + anchor: 'gstack-version-changed', + summary: 'the run directory was written by a different gstack version', + fix: 'nothing to do for an older run (journaled forward migrations ran); a run written by a newer gstack needs that gstack: upgrade with bin/gstack-upgrade', + }, + INSTALL_VERDICT_FAILED: { + anchor: 'install-verdict-failed', + summary: 'on a Capy host (GSTACK_CAPY=1) the install verdict is missing, failing, or for another checkout or HEAD', + fix: 'run the Capy gstack skill wrapper (`install.sh --for `) until its trailer is `gstack: ok`, then launch with its GSTACK_LAUNCH line; GSTACK_ALLOW_UNSUPPORTED_RUNTIME=1 overrides and is recorded as a run deviation', + }, + ARTIFACT_GATE_UNSETTLED: { + anchor: 'artifact-gate-unsettled', + summary: 'the run says complete while an approval item of its last gate revision or an accepted plan amendment is still pending', + fix: 'answer the gate until every approval settles and revise (or withdraw) every accepted change with `gstack-autoplan`; never hand-edit status', + }, } as const satisfies Record; export type ResultCodeName = keyof typeof RESULT_CODES;