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

@@ -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
 }

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.
+
+<a id="plan-sections-invalid"></a>
+### `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 `<out>/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.
+
+<a id="plan-amend-pending"></a>
+### `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 <dir> --plan <file>
+--incorporates <decision id,...>`. `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 <dir> --withdraw <decision id>` records
+the withdrawal in the journal.
+
+<a id="gstack-version-changed"></a>
+### `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.
+
+<a id="install-verdict-failed"></a>
+### `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`.
+
+<a id="artifact-gate-unsettled"></a>
+### `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.

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 <dir> --plan <file> --incorporates <decision id,...>`; or drop one with `gstack-autoplan revise --out <dir> --withdraw <decision id>`',
+  },
+  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 <skill>`) 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<string, ResultCode>;
 
 export type ResultCodeName = keyof typeof RESULT_CODES;