v1.91.97.0 fix: closable unattended /autoplan runs on Capy (field wave B, items 6-13) (#3165)

* docs(designs): gstack field wave plan (2026-10-12) and the shared simulated Capy host fixture Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * fix(autoplan): scope keys on rendered surfaces, per-axis provenance, --no-dx and a read-only plan marker UI scope reads the Implementation plan only and needs a rendered file path or a UI term next to a visual noun; bare UI words stay weak evidence (sections load, no Design phase). Scope records sources {ui,dx} (flag|marker|detected), --no-dx turns DX off, a first-line  marker is read and never written, and the first next prints SCOPE: evidence plus a SCOPE_PIN hint. The snapshot tool's scope output carries uiRequired from the same detector and autoplan Step 2 uses it instead of a prose grep (field wave item 11). Intentional pin change: test/review-checklists.test.ts Scope literal and the source= line shape (source=ui:detected,dx:detected). Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * fix(plan-reality): a receipt per measured number, the rule text for a rule claim, dot-path receipts Each clause stating a measured quantity (a unit, or a number after measured/costs/ takes/took) needs its own receipt; misses print unreceipted_numbers=<n> and one NUMBER_UNRECEIPTED: <clause> line each. A line claiming a decision rule must quote it or link its file:line (unquoted=<n>). Either miss maps to the existing verdict (incomplete unattended, repair otherwise). RECEIPT_RE accepts dot paths and needs a hex letter or a commit/backtick context for a sha. New pure checkPlanReality(planText) runs the same checks over plan prose for gstack-autoplan submit (field wave item 12). The unreceipted= text token is now pinned as well as the JSON. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * feat(autoplan): generated DRIVER.md, the compact entry for a parent driving gstack-autoplan autoplan/DRIVER.md (from autoplan/DRIVER.md.tmpl) is what a parent agent on any host reads instead of autoplan/SKILL.md: phase order and scope flags, the next/submit/ answer/revise/export loop with the plan-specified submit --record/--attest/ --unavailable, revise --incorporates/--withdraw and next --scaffold, the reviewer RESULT FORMAT, the gate grammar including all as-is, the run files, the result codes and the coordinator contract, every list rendered from code (117 lines). gen:skill-docs emits it as a Claude asset, so normal, out-dir and dry-run inventories and the freshness check cover it. gstack-autoplan --help and the first next print DRIVER: <root>/autoplan/DRIVER.md, resolved through an install root's recorded .source-path (new lib/source-root.ts) (field wave item 13). Intentional pin change: test/gen-skill-docs-checks.test.ts asset inventory gains autoplan/DRIVER.md. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * feat(doctor): --min-revision, a launch Bun found off PATH, planning-only pins SKIP gstack-doctor --check gains --min-revision <v>|unknown: below it the revision row FAILs with REVISION_BELOW_MINIMUM naming the Capy wrapper or bin/gstack-upgrade; unknown says so and never claims the minimum. The runtime and pins rows name a supported Bun found in $BUN_INSTALL/bin (not on PATH) with the export/GSTACK_LAUNCH fix (gstack_bun_launch_dir, one helper in bin/gstack-bun-version.sh). --for a planning-only workflow (autoplan, the plan reviews, office-hours) reports a repo test-pin mismatch as SKIP pins (planning-only; ...). New result codes UPGRADE_REFUSED, UPGRADE_FETCH_FAILED, REVISION_BELOW_MINIMUM, CAPY_WRAPPER_STALE, INSTALL_UNVERIFIED with troubleshooting anchors; REVISION_UNMET's fix names bin/gstack-upgrade. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * feat(install): install verdict and install admission at skill start bin/gstack-install-verdict.sh (Bash) and lib/install-verdict.ts (TypeScript) are the one reader of the install verdict gstack-capy-install writes to <state root>/install-verdicts/<sha256(checkout realpath)>.json (checkout, HEAD, workflow and required components, planning-only pins, trailer). The source checkout and capy/support.env resolve through gstack_source_root / sourceRoot, which follow an installed root's .source-path. gstack-skill-start, after SESSION_KIND: an unattended session (any host) refuses on a PATH Bun below the supported minimum; with GSTACK_CAPY=1 an unattended or explicit spawned session also refuses without a passing verdict for this checkout, HEAD and workflow (INSTALL_UNVERIFIED). A refusal prints the INSTALL: row, an install-refused instruction block bound to its SESSION_ID, GSTACK_RESULT ... status=refused run=- and exits 3. Ambient spawned sessions warn; GSTACK_ALLOW_UNSUPPORTED_RUNTIME=1 admits and says so. capy/support.env declares GSTACK_MIN_REVISION and GSTACK_CAPY_MIN_WRAPPER. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * feat(capy-install): launch PATH, Bun reuse and CI pins, setup skip on HEAD, verdict, --check The GSTACK_LAUNCH line carries PATH=<dir>:$PATH when the certified Bun is not first on PATH, plus GSTACK_CAPY=1 and GSTACK_INSTALL_VERDICT, and GSTACK_LAUNCH_PATH: <dir>; the doctor runs with that PATH. A supported Bun in $BUN_INSTALL/bin is reused instead of downloaded again. Project pins are read with bin/gstack-runtime-pins.ts (CI lanes included): when every exact pin is gstack's verified version the archive is installed alongside a different PATH Bun; any other exact pin is RUNTIME_PIN_CONFLICT. Both ./setup runs are skipped when this HEAD was set up with the same hosts, model and browser flag and the check passes (never after a fast-forward); a failed setup ends with gstack: fail setup and is retried next run. --check certifies only; GSTACK_CAPY_LOCK_HELD=1 accepts the bootstrapper's held lock; result anchors come from the generated components table; REV_NOTE names bin/gstack-upgrade. Intentional pin change: test/gstack-capy-install.test.ts --revision trailer now names <root>/bin/gstack-upgrade (the old text named a command that never existed). Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * 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> * artifact contract: changes, recommended_basis, carried decisions, attested count, settled-gate check Findings and decisions carry the user challenge's `changes` value; decisions record recommended_basis, origin, carried_from and chosen_text; validate refuses a complete run with an unsettled gate (ARTIFACT_GATE_UNSETTLED) and prints attested=<n>. The gate reply grammar gains `all as-is` and resolves partial replies against prior answers (field wave B2a/B2b). Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * autoplan: run-state fields, plan-text hashing, version migration and admission modules RunState gains gstack_version, plan_input/heading, scope_flags, plan_revision, amendments and plan_reality; voices record receipt kind and reviewed hash. New pure modules: Implementation-plan review hash, scaffold and drift lines (B1c); gstack_version stamp and legacy decision-id migration (B1a); install-verdict and Bun-minimum admission with a local verdict shim until lane A's lib/install-verdict.ts lands. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> bin/gstack-autoplan-snapshot.ts exports its section scanner and review projection, and initializes only a plan with no section headings by wrapping it. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * autoplan: closable runs - submit --record/--attest/--unavailable, revise, amendment interlock, agreeing-UC defaults, admission B1a: an older run directory prints GSTACK_VERSION_CHANGED once and migrates legacy decision ids; a newer one refuses. B1b: submit binds hand-run records (fence, table, severity list, No findings.), attested binds need --attempt, --attempt is optional with one open attempt, --unavailable/--failed close an outside voice native_only, and submit caches the plan-reality report by Implementation-plan hash. B1c: revise reviews a revised plan in the same run as one recoverable transaction (reopen on hash drift plus Eng, add newly in-scope phases, .r<rev>/.v<k> archives, gate_rev+1 at the gate); PLAN_SECTIONS_INVALID and next --scaffold; PLAN_CHANGED / PLAN_SOURCE_CHANGED drift hints. B2a/B2b: user challenges carry changes; agreeing voices with the same changes on a confirmed finding recommend b with both remedies shown (or the reconcile proposal); accepted changes print APPLY and become pending amendments that next and export refuse past until revise --incorporates names them or --withdraw drops one; all as-is; partial replies, DECIDED block, carry-forward and rerun demotion. Mutating verbs pass admission (GSTACK_CAPY install verdict; unattended Bun minimum; override recorded as a deviation). Intentional pin rewrite: test/autoplan-answer-invalidation.test.ts reopen tests now revise --incorporates before rerun. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * feat(upgrade): bin/gstack-upgrade, the unattended fast-forward every fix line names --check fetches and prints current|behind <installed> -> <remote> (<n> commits); the default fast-forwards to the remote default branch tip and reinstalls (bin/gstack-capy-install on a Capy install, else ./setup --refresh-registered), completing a pending reinstall on the next run. It refuses (UPGRADE_REFUSED, exit 3, nothing changed) a dirty tracked byte, a diverged commit, a pinned checkout, the incoming Bun floor and a held .setup-lock; never stashes or resets; an unreachable remote is UPGRADE_FETCH_FAILED. Fetches are receipted (fail-open). The unattended skill-end UPGRADE_AVAILABLE line is followed by UPGRADE_COMMAND naming it. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * feat(capy): vendored Capy skill, frozen bootstrapper and full wrapper bin/gstack-capy-session capy/skill/gstack/ is the Drive skill's source of truth. scripts/install.sh is a frozen bootstrapper: it prints gstack-capy-skill: wrapper <n> (<path>), clones or fetches under .gstack-capy-install.lock, reads the remote capy/support.env (FETCH_HEAD), fast-forwards a clean unpinned checkout below GSTACK_MIN_REVISION (refusing dirty, diverged or pinned checkouts with the exact commands; GSTACK_CAPY_AUTO_UPGRADE=0 disables), and execs the checkout's own bin/gstack-capy-session with GSTACK_CAPY_LOCK_HELD=1 so the held lock is never taken twice. Offline it says the remote minimum is unknown. A Drive copy older than GSTACK_CAPY_MIN_WRAPPER prints an owner action (CAPY_WRAPPER_STALE). SKILL.md: check at session start, install lazily before the first workflow, the GSTACK_LAUNCH line, the trailer rule, the subagent first-report line, gstack-pregate sealed before any push, and the autoplan/DRIVER.md pointer. The context-budget fixture gains the skill's entry. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * docs: Capy install layers, lazy install, snapshot bake, forward-only recovery, raising the minimum docs/capy-install.md describes the three layers (Drive bootstrapper, full wrapper, installer), the lazy install, the GSTACK_LAUNCH line, install admission, baking gstack into a Capy snapshot, and that recovery after an interrupted fast-forward completes or refuses the pending install stages (checking out an older commit is not a rollback). docs/CHANGELOG_STYLE.md (the release doc; there is no docs/RELEASING.md) says when GSTACK_MIN_REVISION may be raised. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * refactor(capy): the stale-copy owner action moves from the frozen bootstrapper to bin/gstack-capy-session The checkout-owned full wrapper reads GSTACK_CAPY_MIN_WRAPPER through gstack_support_env_get(gstack_source_root) and compares it with the bootstrapper revision it was handed, so the rule can change without recopying the Drive skill. The bootstrapper keeps only what a stale checkout cannot do: clone, fetch, read the remote minimum, fast-forward, exec. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * v1.91.96.0: honest install and self-upgrade on Capy; supported minimum 1.91.96.0 Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * v1.91.97.0: closable unattended autoplan runs on Capy Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * test: drop the helper-only Capy host fixture test (test-of-test ratchet); lane tests exercise the helper Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * fix(autoplan): revise naming a non-pending decision refuses with AMENDMENT_UNKNOWN, not PLAN_AMEND_PENDING Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * test: bound the new sync spawns in the install-verdict and wrapper tests (spawnSync tripwire) Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * test(autoplan): pin CLI refusals to the result-code registry's fix text Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * fix(gen-skill-docs): emit autoplan/DRIVER.md only when the autoplan template is in the tree (setup fixtures with a skill subset) Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * fix(autoplan): run.lock is linked into place with its owner written; a fresh unreadable lock is held, not stolen Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * ci(paid-pr-profile): the vendored Capy skill is free-only; free-only files are not prompts needing paid coverage Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * chore(harness): non-behavioral HARNESS_VERSION decision for the PR-profile free-only rule Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * test(doctor): lane A runtime and pins cases are platform-neutral (bash paths; a lane-free .bun-version pin) Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * docs(designs): field wave plan with amendments and the gate rev 2-3 review record (ARTIFACT_VALID, 3 gate revisions) Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * fix(capy-install): follow a project's exact Bun pin above the minimum when gstack has its verified archive (adds Bun 1.4.3) Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * docs: the installer follows a verified exact project Bun pin (capy-install, troubleshooting, changelog) Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * fix(capy-install): the install reason names the project's pin and gstack's real minimum Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * ci: run the main-targeted checks after retargeting #3165 to main Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * test(autoplan-admission): the PATH-Bun refusal case needs the POSIX Capy host stub; skip it on Windows Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --------- Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
2026-11-02 15:04:37 +01:00 · 2026-10-13 15:17:39 +00:00
1 parent ada251bbc0
commit 945ac301a9
@@ -2542,3 +2542,69 @@ 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="amendment-unknown"></a>
+### `AMENDMENT_UNKNOWN`
+
+**Meaning.** `gstack-autoplan revise --incorporates` or `--withdraw` named a
+decision id that is not a pending amendment: the owner never accepted it as a
+plan change at the gate (for example a gate answered before gstack recorded
+amendments), or it was already incorporated or withdrawn. Nothing was changed.
+
+**Fix.** Name only the ids the refusal lists after `pending:`. With none
+pending, revise without `--incorporates`:
+`gstack-autoplan revise --out <dir> --plan <file>`.
+
+<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="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.
@@ -138,18 +138,29 @@ On a host where the parent dispatches the reviewers itself (Capy, any
 orchestrator without a Claude Code harness), `bin/gstack-autoplan` is the
 explicit, durable state machine for the whole run. The parent never reads the
 review record; it runs a loop over two commands and reads the printed lines.
+A parent on any host reads `autoplan/DRIVER.md` (its path is printed as
+`DRIVER:` by `gstack-autoplan --help` and the first `next`) instead of
+autoplan/SKILL.md: the phase order, the artifact contract and the gate protocol
+in about a hundred lines, generated from the code.

 ```bash
 AP=bin/gstack-autoplan
-$AP next --out <dir> --plan <plan.md> [--ui|--no-ui] [--developer-tool] [--light] [--spend-cap <usd>]
+$AP next --out <dir> --plan <plan.md> [--ui|--no-ui] [--developer-tool] [--no-dx] [--light] [--spend-cap <usd>]
 #   PHASE: ceo snapshot=<sha> order=ceo,design,dx,eng
-#   Skipped sections: none (scope: ui=yes,dx=yes,source=detected; checklist=loaded)
+#   SCOPE: ui=yes (...) dx=yes (detected: ...) source=ui:detected,dx:detected
+#   DRIVER: <root>/autoplan/DRIVER.md
+#   Skipped sections: none (scope: ui=yes,dx=yes,source=ui:detected,dx:detected; checklist=loaded)
 #   ATTEMPT: <run>-a1 phase=ceo voice=native  prompt=<dir>/ceo-native-prompt.md  result=<dir>/ceo-native.md  model_family=...
 #   ATTEMPT: <run>-a2 phase=ceo voice=outside prompt=<dir>/ceo-outside-prompt.md result=<dir>/ceo-outside.md model_family=differs from the native reviewer
 #   SPEND: spent=0.00 reserved=0.00 unknown=0(0.00) worst_case=0.00 cap=none
 #   GSTACK_RESULT: skill=autoplan status=awaiting_result run=<dir>
 ```

+The first `next` prints `SCOPE: … source=ui:<flag|marker|detected>,dx:<…>`
+and, when CLI flags differ from the plan's marker, `SCOPE_PIN: add <!--
+gstack-autoplan-scope: … --> as the first line of <file>`; gstack never writes
+the plan.
+
 1. **Dispatch each `ATTEMPT:`.** The native voice is a subagent on the parent's
   own model given the prompt file; the outside voice is a subagent on another
   model family, or `bin/gstack-outside-voice run --runner codex-cli|api
@@ -182,15 +193,25 @@ $AP next --out <dir> --plan <plan.md> [--ui|--no-ui] [--developer-tool] [--light
   disagreements as auto items and `p1` plan approval; nothing is approved.
 4. **Answer the gate** with the reply grammar and the revision you read:
   ```bash
-   $AP answer --out <dir> --gate-rev 1 --reply "all"              # APPROVED: status=complete, no new paid phase
-   $AP answer --out <dir> --gate-rev 1 --reply "all except d1b"   # REOPENED: ceo,eng (Eng last); next continues the loop
+   $AP answer --out <dir> --gate-rev 1 --reply "all"              # every recommendation; agreeing plan changes print APPLY:
+   $AP answer --out <dir> --gate-rev 1 --reply "all as-is"        # APPROVED: keeps every direction, no new paid phase
+   $AP answer --out <dir> --gate-rev 1 --reply "all except d1b"   # APPLY: <id> ...; REOPENED: ceo,eng; NEXT: gstack-autoplan revise ...
   ```
+   A user challenge both voices raised on a confirmed finding with the same
+   `changes` value is recommended as `b`, and option b shows both voices'
+   remedies (`recommended: b (both voices; remedies shown)`); a `--reconcile`
+   record naming one shared `proposal` shows that instead. Disagreeing or
+   missing remedies keep `a`. Every accepted plan change prints
+   `APPLY: <decision id> <title> -> <chosen text>` and becomes a pending
+   amendment: `next` refuses with `PLAN_AMEND_PENDING` and `export` refuses a
+   `complete` run until `revise --incorporates` names it (see below).
   A stale revision (`GATE_REV_STALE`, exit 3), bare `yes`/`no`, or a
   conflicting reply (`GATE_REPLY_UNPARSED`) writes nothing. A reply that
   leaves approval items pending records only the answered auto items and
-   keeps the gate. A non-recommended choice on a reviewed item reopens that
-   phase plus Eng, archives their bound files as `*.r<rev>.*`, and the next
-   gate is `gate_rev + 1`; `p1d` reopens every phase; `p1e` ends `incomplete`.
+   keeps the gate; a later reply never overwrites an earlier answer. A choice
+   that changes the plan reopens that phase plus Eng, archives their bound
+   files as `*.r<rev>.*`, and the next gate is `gate_rev + 1`; `p1d` reruns
+   every phase on the current plan; `p1e` ends `incomplete`.
 5. **Export and validate.** `$AP export --out <dir>` writes `plan.md` (with
   the `## URGENT, outside this plan` block first), `review-record.md`,
   `tasks.jsonl`, `decisions.jsonl`, `findings.jsonl`, `timing.json` and
@@ -219,7 +240,8 @@ Each prompt file ends with this contract; `submit` enforces it.
   object per line: `{"id":"F1","severity":"High","title":"...","file":"...","line":12,"fix":"..."}`
   inside a ```` ```gstack-findings ```` fence. `severity` is Critical | High |
   Medium | Low | Informational; `"user_challenge": true` marks a recommended
-   change to the plan's stated direction; `"urgent": true` with
+   change to the plan's stated direction and needs `"changes": "scope" |
+   "cost" | "direction"` (what accepting it changes); `"urgent": true` with
   `"suggested_owner"` marks a security or data-loss finding the plan does not
   own. An empty fence means no findings; a missing fence is refused.
 3. The whole result is written to the printed `result=` path.
@@ -241,6 +263,42 @@ by its runner. Result codes: `EXECUTION_UNKNOWN`, `RUN_LOCKED`,
 `SPEND_CAP_EXCEEDED`, `CONSENSUS_MISSING`, `OUTSIDE_RUNNER_UNAVAILABLE`
 (anchors in [troubleshooting.md](troubleshooting.md)).

+### Hand-run records, revised plans and admission
+
+- **Hand-run reviews.** `submit --record <file>` binds a review that did not
+  follow the RESULT FORMAT: the `gstack-findings` fence, one findings table
+  (Severity and Title columns), one severity-tagged list (`- [High] title`) or
+  a `No findings.` line. Without its `INPUT:` line it binds only with
+  `--attest "<reason>"` and `--attempt <id>` (receipt `attested`; refused after
+  a later `revise`), and `gstack-artifact validate` prints `attested=<n>`.
+  `--attempt` may be omitted when exactly one attempt is open.
+  `submit --voice outside --unavailable "<reason>"` (or `--failed`) closes the
+  phase `native_only` once native is bound; `next` and `resume` never
+  redispatch it.
+- **Revising the plan in the same run.** Edit the source plan, then
+  `$AP revise --out <dir> --plan <file> [--incorporates <decision id,...>]`.
+  Every phase whose reviewed Implementation-plan hash differs reopens (plus
+  Eng); newly in-scope phases are added; archives keep `.r<rev>` names with
+  `.v<k>` only on collision; a revise at `gate_pending` makes the next gate
+  `gate_rev + 1`. `--incorporates` discharges only the named amendments and
+  refuses an unchanged plan; `revise --out <dir> --withdraw <decision id>`
+  drops one as a journaled owner decision. `next` prints `PLAN_CHANGED` and
+  `answer` prints `PLAN_SOURCE_CHANGED` when the source plan moved since the
+  snapshot. A plan without both `## Implementation plan` and `## Review record`
+  refuses with `PLAN_SECTIONS_INVALID`; `next --scaffold` reviews a copy with
+  the missing heading added. `resume` completes an interrupted revise.
+- **Admission and upgrades.** `next`, `submit`, `answer`, `revise`, `export`
+  and `run` refuse on a Capy host (`GSTACK_CAPY=1`) without an ok install
+  verdict for this checkout, HEAD and workflow at `$GSTACK_INSTALL_VERDICT`
+  (`INSTALL_UNVERIFIED`), and in any unattended session when the running Bun
+  is below gstack's supported minimum (`RUNTIME_BELOW_MINIMUM`); the decision
+  is the same one `gstack-skill-start` makes (see Install admission);
+  `GSTACK_ALLOW_UNSUPPORTED_RUNTIME=1` overrides and records a run deviation.
+  `status` and `resume` are never gated. A run directory written by an older
+  gstack prints `GSTACK_VERSION_CHANGED` once and moves forward (legacy
+  decision ids are renamed and journaled); one written by a newer gstack is
+  refused.
+
 ## Owner brief

 `gstack-owner-brief render --out <dir>` is what the owner sees at the final