mirror of
https://github.com/garrytan/gstack.git
synced 2026-11-17 05:41:50 +01:00
+8








28f1385eac
* fix: sourced helpers locate themselves under zsh (#3024) Skill blocks source bin/gstack-codex-probe and bin/gstack-egress-lib.sh into the host's shell. Under zsh (macOS default) BASH_SOURCE is empty, so Codex model selection resolved /../scripts/... and every outside pass reported CODEX_MODEL: invalid; the egress lib resolved to the caller's cwd. Resolve the file once at source time (BASH_SOURCE under bash, %x under zsh), and replace the bash-only ${!name} indirection in the auth probe. A free test derives every sourced helper from the generated skills and sources each under bash and zsh. Co-authored-by: marcosdetry <marcosdetry@users.noreply.github.com> Co-authored-by: akshaykalia <akshaykalia@users.noreply.github.com> Co-authored-by: scottgigante-hubflow <scottgigante-hubflow@users.noreply.github.com> Co-authored-by: woodsonl <woodsonl@users.noreply.github.com> Co-authored-by: bezdekt <bezdekt@users.noreply.github.com> * fix: reply and issue templates never pass untrusted text in double quotes (#3046) greptile-triage's reply APIs posted -f body="<reply text>" while the templates quote SHAs and diff code in backticks; in double quotes bash ran each span (replies posted as 'Fixed in .', and diff or reviewer text ran as a command). The pre-existing-failure issue template and /spec's issue title had the same shape. All three now go through quoted heredocs. The generated-bash lint gains untrusted-in-quotes and now also covers runtime reference docs in skill directories (review/greptile-triage.md). Co-authored-by: dgrant <dgrant@users.noreply.github.com> * fix: a Codex usage limit is its own state, not 'inconclusive; proceeding' (#3051) The model probe matched only model and broken-install errors, so a usage or rate limit fell through to MODEL_PROBE_INCONCLUSIVE: Codex's own message (with the reset time) was dropped, the hint pointed at model config, and every later skill re-probed for 30 s. The probe now returns MODEL_QUOTA_EXHAUSTED (exit 4) on a failed, non-timeout call that names a usage limit, rate limit, insufficient_quota or 429, relays Codex's line verbatim and caches it for 15 minutes. Preflights map it to CODEX_MODE: quota_exhausted (missing coverage, no further Codex calls), and classifyOutsideReview reports a mid-run limit as unavailable (quota) with its own troubleshooting anchor. Co-authored-by: venkatareddyg <venkatareddyg@users.noreply.github.com> * test: record ship/review union sizes after the quota branch and issue template * fix: Codex watchdog freezes the command before reaping its children The bash-native watchdog (stock macOS, no timeout binary) ran pkill -P on the command's children and then killed the command. Between the two, the command continued past its killed child and printed output after its deadline. Stop it first. The test's minimal PATH also lacked pkill, which the watchdog uses to reap children (stock macOS ships it), so the orphaned child held stdout open and the capture waited out its sleep. * fix(autoplan): an oversize session journal is a hard too_large denial, not a retryable identity failure (#3050) The guard capped journal reads at 32 MiB and reported a longer journal as 'identity', which the hook treats as deny-and-retry. A journal only grows, so /autoplan could never enter Phase 1 in a long session, and the troubleshooting row sent people chasing symlinks. Oversize journals now report too_large as a hard cause that names the size and the supported fallback (run the reviews by hand or start a new session). Co-authored-by: venkatareddyg <venkatareddyg@users.noreply.github.com> * fix(deps): clear the weekly OSV findings (#3040) Raise overrides to fixed releases: ip-address 10.7.3 (our own pin was the vulnerable 10.3.1; reachable through socks in browse's proxy path), fast-uri 3.1.8, hono 4.13.13, proxy-addr 2.0.8, @modelcontextprotocol/sdk 1.31.0, sharp 0.35.5, and in lib/diagram-render dompurify 3.4.16 (bundled by mermaid) and source-map-js 1.2.2; the render page is rebuilt. Three advisories without a usable fix get justified, expiring ignores: braces (build-time only, excalidraw -> sass -> chokidar; a test checks the page carries no chokidar code), sprintf-js (roarr's constant-format logger) and katex (needs pre-existing prototype pollution; fix outside mermaid's range). osv-scanner with the repo config: no issues found. * fix(autoplan): name a shell-built snapshot init as the cause of the missing-evidence denial (#3045) The guard binds a phase entry only to a literal snapshot-init Bash call. When the model resolved the tool path into a variable, chained or piped the call, init ran and succeeded but the denial said 'Complete the existing snapshot init step', which reads as already done, so the run gave up. When no init binds but a Bash call looks like one, the denial now says the shape cannot be bound and prints the literal re-run (answers reused:true). The binding rule is unchanged, and the skill says to run init on its own. Co-authored-by: CharlesBerg85 <CharlesBerg85@users.noreply.github.com> * fix(browse): chain reads piped stdin synchronously, so Windows runs the flow (#3039) On Windows, an awaited Bun.stdin.text() inside the CLI's un-awaited main() let the process exit 0 before reading stdin: a replayed flow reported success with nothing sent to the daemon. Read fd 0 synchronously (skipped for a terminal); empty input now gets the server's usage error and a non-zero exit. Co-authored-by: VaibDeveloper <VaibDeveloper@users.noreply.github.com> * fix(browse): clearer config-mismatch refusal and a WebGL note for the macOS GPU flags (#3030) A plain call refused because another session started the daemon with --headed/--proxy was told to 'apply --proxy/--headed', flags it never passed. It now says who started the daemon and offers both remedies. The BROWSER.md env table notes that the default macOS GPU flags disable WebGL and that GSTACK_DISABLE_GPU=off restores it for WebGL QA. Co-authored-by: Hagetino <Hagetino@users.noreply.github.com> * fix(ship): skip Greptile triage when no PR exists yet (#3020) /ship's first run on a branch dispatched a triage subagent only to learn there was no PR. Step 10 now checks for a PR inline (gh's 'no pull requests found') and records that Greptile runs on the PR once it exists; other gh errors still dispatch so the child can report unavailable. Co-authored-by: dgrant <dgrant@users.noreply.github.com> * fix(router): route only to loaded skills, and say when not to invoke (#3018) The root router listed every skill and ended 'When in doubt, invoke the skill'. Current Claude models follow that literally: they tried to invoke skills a user had turned off in Claude Code's skillOverrides (which gstack's own disabled_skills render cannot see), and borderline requests tipped into full workflows. The router now routes only to skills in the session's available-skills list and names when to answer directly; the CLAUDE.md routing block skill-start offers says the same. Co-authored-by: Rekin226 <Rekin226@users.noreply.github.com> * fix: spawned sessions never auto-grant consent or publish off the machine (#3016) Spawned sessions auto-choose the recommended option except for destructive or irreversible choices. Main already withholds the artifacts-sync consent prompt from spawned sessions; the remaining gap was any other prompt whose recommended option grants a consent or syncs data off the machine. Every spawned directive (skill-start's block, the escape sentence, the Conductor deny reason and the AUQ-error fallback) now names that as irreversible. A consent the user already gave interactively stays in force. Co-authored-by: ekson73 <ekson73@users.noreply.github.com> * test: fix the spawned-block slice and type the #3045 re-init events * fix(redact): TypeScript types and JSX expressions are code, not env.kv secrets (#3048) A credential-named parameter or prop with an unquoted code value (`session: SessionState,`, `key={turn.requestId + turn.role}`, `apiKey={settings.apiKey}`) cleared the entropy gate and blocked pushes as a MEDIUM env.kv finding. One rule replaces the PR's two keyword heuristics: a value that reads as a code name (no digits, word-like camelCase or dotted parts) with a code terminator, or a brace expression of such names with no quoted literal, is source syntax. Paired controls keep firing on quoted, brace-wrapped, concatenated, YAML-bare and random-letter literals. Co-authored-by: tianxchen <tianxchen@users.noreply.github.com> * fix(setup): refuse to register a hook that does not parse (#3032) Claude Code runs gstack's hook shims through /bin/sh; a shim that does not parse exits 2, which for a PreToolUse hook blocks the tool call in every session until someone finds the file. Before any hook registration is healed or written, setup now runs bash -n on each registered shim and a Bun parse of its TypeScript entry, and stops with the file, line and fix. A lean rewrite of the PR's idea (one gate block plus a test that runs it). Co-authored-by: BenjaminDSmithy <BenjaminDSmithy@users.noreply.github.com> * fix(browse): Windows runtime roots start the server from the source checkout's bundle (#3026) On Windows a host runtime root (~/.codex/skills/gstack and the other env-var hosts) holds file copies of browse/dist and no node_modules, so its server-node.mjs could not import playwright and every browser skill died (the module-scope server.ts half was fixed in v1.91.19.0). setup now records the source checkout in every runtime root's .source-path, and the CLI runs that checkout's bundle when the adjacent one cannot reach playwright. Verified by unit layout tests and the Windows CI lane, not live on Windows. Co-authored-by: ubay887 <ubay887@users.noreply.github.com> * fix(copilot): on Windows, run bash blocks in Git for Windows Bash (#3047) Copilot CLI on Windows ran gstack's extensionless helpers straight from PowerShell, which opened an app picker, and bare bash can resolve to WSL. The Copilot tool glossary (rendered into every Copilot skill) now says to run each bash block in Git for Windows Bash by its full path and never to translate a block into PowerShell. The PR's PowerShell repair skill and README section are not taken. Co-authored-by: nareshh74 <nareshh74@users.noreply.github.com> * test: record ship's union size after the Greptile no-PR check * fix: keep issue numbers out of model-read Copilot text; seed the new routing sentence in the autoplan fixture * docs: Oct 6 fix-wave plan, reviewed through /autoplan * fix(autoplan): every oversize-journal path reports too_large with a recovery that keeps the work Review follow-up to the #3050 fix. The summed batch read and the narrowed parent loop now report too_large with the real size instead of a plain error naming a hard-coded 32 MiB. The denial names the size and the cap, and gives the recovery that keeps work (/context-save, new session, /context-restore, /autoplan) with a docs anchor. A test seam that can only lower the cap replaces the 33 MiB fixture. * test(autoplan): negative controls and more shapes for the shell-built init denial * fix(redact): decide TS/JSX source syntax by file context, not by value shape Review follow-up to the #3048 fix. The word-shape heuristic also exempted real secrets made of words (API_KEY=VelvetRiverOrbitSunset; in a .env). The scanner now takes the file path (ScanOptions.sourcePath): the pre-push hook scans the pushed diff per file with its +++ b/ path, and gstack-redact --from-file passes its path. Only in a TypeScript/JSX file is an unquoted value after ':' or a JSX brace of names treated as source; the same line in .env/YAML, or with no path, is scanned as a literal, and the jwt pattern still fires in .ts files. Co-authored-by: tianxchen <tianxchen@users.noreply.github.com> * docs: gstack's own CLAUDE.md routing block matches the new router wording Live check (Claude Code 2.1.284): a skill set to "off" in skillOverrides is absent from the session's skill list while its sibling is listed, and both are listed without the override, so 'route only to skills in your available-skills list' holds. * fix(sync-gbrain): don't offer a call-graph build for a source with no code pages (#3029) Step 3.5 offered --dream for any source with pages, including one that holds only markdown (synced with gbrain's default strategy), where a build cannot help, and the injected CLAUDE.md guidance told future sessions to run --dream for any count: 0. On gbrain >= 0.60, code-def for an impossible symbol answers .status (probed live against gbrain 0.60.96: ready for a code source, out_of_scope for a markdown-only one). Step 3.5 now probes the pinned source first, reports the cause instead of asking on out_of_scope, and keeps today's offer when the probe is unknown (older gbrain, an error). gstack's own sync uses --strategy code, so the PR's soft-delete claim does not apply to gstack's path. Co-authored-by: syong <syong@users.noreply.github.com> * fix(setup): register the hooks that parse, refuse the rest with file:line (#3032) The landed gate stopped setup before any registration, so one unparseable hook left every other hook unregistered. On the Claude install the canonical root is the checkout Claude Code runs hooks from, so there is no staged swap to abort: setup now registers the hooks that parse, refuses the ones that do not with file and line, finishes the install and exits non-zero, saying it is a gstack bug and that a skipped hook keeps running from the checkout. bin/gstack-hook-check derives its list from setup's _hook_command_path calls plus the autoplan phase-publication hook (a test keeps them equal), parses each shim with its shebang's interpreter, and bundles each TypeScript entry with its local imports (packages external) into a temp dir, so a broken or missing import, or a missing entry, fails. Co-authored-by: BenjaminDSmithy <BenjaminDSmithy@users.noreply.github.com> * fix(auto-update): hold an update whose hooks do not parse, before the checkout moves bin/gstack-session-update fast-forwards the live checkout before setup runs, and Claude Code runs hooks straight from it, so setup's gate cannot protect an auto-update. After the Bun floor check the updater extracts the incoming revision with git archive and runs bin/gstack-hook-check on it; a failure holds the update like bun-too-old, records hook-does-not-parse with file:line in the update status, and the next session start says the current hooks keep running. Fixture-remote tests cover a broken shim, a broken imported module and a parseable control. Co-authored-by: BenjaminDSmithy <BenjaminDSmithy@users.noreply.github.com> * fix(browse): chain with no flow is a usage error before any daemon boots (#3039) Empty piped input, a terminal with no arguments, and a readFileSync(0) error (EAGAIN, EOF) now print the chain usage with the cause and its troubleshooting link and exit 1 before ensureServer(), instead of sending an empty argument to a daemon the CLI booted for it. Tests run the real CLI with no daemon and no browser, plus the stub-daemon flow. Co-authored-by: VaibDeveloper <VaibDeveloper@users.noreply.github.com> * fix(browse): refuse a runtime-root CLI and checkout server from different builds (#3026) A Windows runtime root runs the source checkout's Node server bundle through .source-path. When the root's CLI and the checkout's bundle carry different browse/dist/.version builds (the checkout was rebuilt without refreshing the root), the CLI now refuses to start the server with both builds, the ./setup fix and its troubleshooting anchor. Unversioned dev builds are not called skew. Co-authored-by: ubay887 <ubay887@users.noreply.github.com> * ci(windows): real isolated ./setup install, then a piped chain flow through the installed browse windows-setup-e2e built the checkout but never ran ./setup. It now installs the codex host into an isolated HOME (a runtime root copy with no node_modules), then from an unrelated directory pipes a two-command chain flow at a loopback page into the installed browse and asserts the page text, and that empty piped input exits 1 with the usage error. Covers the checkout-bundle path and the piped-stdin path end to end. * test(lint): free text never enters a generated command (structural rule) The generated-bash lint's untrusted-in-quotes rule (gh/glab/git/curl text flags in double quotes only) becomes free-text-placeholder: any <placeholder> anywhere in any command, in double, single or no quotes, and in heredoc bodies (quoted or not), unless it is on the reviewed identifier allowlist (test/helpers/placeholder-allowlist.ts) with the grammar a value must match. Quoted-only identifiers (URLs, selectors, paths printed by gstack) must sit inside quotes. Backslash-newline continuations now read as one command, so a flag and its value on separate lines are still seen together. Co-authored-by: dgrant <dgrant@users.noreply.github.com> * fix: reply, issue and spec text travel as agent-written files, never through a heredoc Replaces the quoted-heredoc bodies with CEO-12's file mechanism: a bash block creates a private mktemp file in the project's .gstack/tmp/ (kept out of git through .git/info/exclude), the agent writes the text with its file-write tool, and the next block posts with -F body=@file, --body-file or "$(cat file)". A heredoc ends early at any body line equal to its delimiter; a file has no such line. When the file was never written the block refuses with the path and the command to send it by hand, and it deletes the file after a successful post. - review/greptile-triage.md: replies; the fetched JSON moves from fixed /tmp/greptile_*.json paths to a mktemp directory; REPO and PR are re-derived per block instead of read from a previous shell. - Test-failure issues: title and body files, platform case on github/gitlab, assignee only when it is a valid login. - /spec: one draft file feeds the audit hash, every redaction scan, the issue and the archive; the archive no longer expands <title>/<body> inside an unquoted heredoc; the decision-log JSON is built by jq from files. Location verified against Claude Code 2.1.284 (Dockerfile.ci pin): project-local .gstack/tmp is writable under acceptEdits with no prompt and keeps mode 0600; $TMPDIR and the gstack state root prompt even under acceptEdits. Co-authored-by: dgrant <dgrant@users.noreply.github.com> * fix(ship): Greptile triage runs only when a PR exists; every other case says why PR: unknown (gh missing, not logged in, a non-GitHub remote, or a failed lookup) used to dispatch the triage child anyway. The Step 10 check now tests gh, its login, the remote and the PR in that order, and every case but 'PR: exists' skips the dispatch and records 'Greptile: not run (<reason>); runs on the PR once it exists'. Co-authored-by: dgrant <dgrant@users.noreply.github.com> * fix: question-tuning commands carry no free text The question log took the summary in single quotes and the preference write took the user's own words; an apostrophe ended the quote and the rest ran as shell. The summary is now a kebab-case slug (an identifier with a grammar), and the optional free_text field is no longer passed from skills (the binary still accepts it). * fix(cso): Windows finds docker.exe only under known-folder roots and says transport is unsupported (#3028) On Windows /cso looked for docker only in Git's directory and System32, so Docker Desktop was never found and the gap read as 'not installed'. It now resolves Program Files, Program Files (x86) and the Windows directory through PowerShell's [Environment]::GetFolderPath (not the process environment), checks each candidate's real path against those roots and rejects reparse points. lib/cso/docker.ts admits only unix:/// endpoints, so a trusted docker.exe reports 'native Windows Docker transport is not supported yet; static assessment only'; one outside the roots is refused as outside the trusted install locations, not overridable. Both carry an anchor. Native named-pipe transport is not implemented. * fix: sourced helpers share one self-locate block and fail loudly when they cannot locate themselves (#3024 rework) The codex probe and the egress lib now carry one byte-identical block: BASH_SOURCE under bash or %x under zsh, made absolute with $PWD, else a set GSTACK_ROOT that holds the helper. Anything else (dash, sh, a shell that cannot name the file) prints "gstack: cannot locate <helper> (shell: ...)" with the docs/troubleshooting.md#sourced-helper-location URL and returns before any bash- or zsh-only syntax. The Claude-only default path and the $(pwd) fallback are gone. The generated Codex preflight dot-sources the probe and, when it cannot load, reports CODEX_MODE: helper_unavailable with the helper's own line instead of falling through to not_authed. The class guard enumerates nested sources, makes real resolver, auth, state-root and egress-home calls under bash and zsh (absolute, relative then cd, bare name via PATH), covers dash and an unknown shell, runs the full preflight, and lints BASH_SOURCE to the shared block plus other bash-only constructs. Co-authored-by: marcosdetry <marcosdetry@users.noreply.github.com> Co-authored-by: akshaykalia <akshaykalia@users.noreply.github.com> Co-authored-by: scottgigante-hubflow <scottgigante-hubflow@users.noreply.github.com> Co-authored-by: woodsonl <woodsonl@users.noreply.github.com> Co-authored-by: bezdekt <bezdekt@users.noreply.github.com> * fix(cso): a Maven or Gradle repository is Java, not Python (#3028) With no supported stack metadata, preparation defaulted to Python and asked a Java repository for requirements.txt. A root pom.xml, build.gradle or build.gradle.kts now names the stack as Java (unsupported for runtime preparation, so the prerequisite says so), and Python helper scripts or a root requirements.txt beside it no longer make it Python. * fix(browse): BROWSER.md says plainly how to enable WebGL; the mismatch refusal links Daemon discipline (#3030) The GSTACK_DISABLE_GPU row now states the effect and the switch: set GSTACK_DISABLE_GPU=off to enable WebGL (off is the only recognized value). The reworded config-mismatch refusal links BROWSER.md's Daemon discipline section. Free tests pin both. Co-authored-by: Hagetino <Hagetino@users.noreply.github.com> * test(windows): name the B2, B4, B5 and B12 tests in the curated Windows lane The runtime-root bundle tests lived in browse/test/config.test.ts and the Copilot glossary test in test/host-config.test.ts, both excluded from the Windows lane, so the two Windows-only fixes were never checked on Windows. Move each into its own Windows-safe file (unchanged assertions) and list it, the piped-stdin chain test and the /cso docker.exe discovery test as named Windows coverage in scripts/lib/windows-curation.ts. * fix: the free-text block exits loudly when mktemp fails; spec and redact tests follow the file mechanism The redact resolver test, the #2679 mktemp guard test, the /spec invariant and the spec secret-sink harness pinned the heredoc transport. They now pin the agent-written file: the harness runs the draft-file block, writes the draft the way the file-write tool would, then runs the real scan fence, with every HIGH/MEDIUM/scanner-failure assertion unchanged. Co-authored-by: dgrant <dgrant@users.noreply.github.com> * test: hostile payloads through the generated posting blocks, identifier grammars, every quoting shape - The lint reads a whole command, so an unquoted multi-word placeholder is caught; negative controls cover double, single and no quotes, quoted and unquoted heredocs, continuation lines, and quoted-only identifiers used unquoted. - Every allowlisted grammar rejects quote-breaking characters (and shell operators and whitespace when used unquoted); git accepts 'fix;id' and 'fix`id`' as branch names, the ref grammar does not. - Greptile replies, test-failure issues (GitHub and GitLab) and /spec filing and archive run from the real generated text with stub gh/glab: a body with backticks, $(...), an apostrophe and lines equal to EOF and the old heredoc delimiters arrives byte for byte, nothing in it runs, and the temp file is gone. An unwritten file is refused with its path and the manual command, and nothing is sent. Co-authored-by: dgrant <dgrant@users.noreply.github.com> * test(ship): the PR check precedes the Greptile dispatch, and each skip names its reason Runs Step 10's generated check against stub gh for gh missing, not logged in, a non-GitHub remote, no PR, a failed lookup and an existing PR. Fails on the previous text (which printed PR: unknown and dispatched). Co-authored-by: dgrant <dgrant@users.noreply.github.com> * feat(ship): ship-measure runner for the measure-then-fix loop (A6) scripts/ship-measure.ts owns /ship's diagnostic measurement of a red eval case: per-kind aggregation (rule trials; behavior panels of 3, each at its own 2 of 3 plus 90% of trials; judge outputs scored by 3-sample panels, standalone judge ids accepted), one artifact directory per baseline, repair round and trial, a diagnostic label with verdict null that refuses the eval history dir, an estimated admission budget that reserves every concurrent trial and reconciles actual cost, the ask-once rule, the repair-round limit, the unmeasured skip and the per-case PR table. Free-suite flakes (CEO-1): 'free' reruns one shard's exact file list N times, rerun 1 alone as the baseline and the rest in parallel at max(1, floor(cores / shard concurrency)), each with its own HOME, state root and flake ledger, GSTACK_FREE_RETRY_FLAKY=0, under a wall cap that reports a partial count. test:ubicloud --diagnostic runs the same on one VM with the retry off. bin/gstack-config gains the DX-7 keys with their CEO-9 defaults and rejecting validators. Free tests drive every kind, the budget stop, the unmeasured skip and the free reruns with fake runners. * fix: a Codex usage limit is quota_exhausted, a plain 429 is rate_limited, and only Codex's own error lines count (#3051 rework) The probe's quota signature used to treat any rate limit, "too many requests" or 429 as quota, and read the whole output, which echoes the prompt. Now only Codex's trailing ERROR: / stream error lines are read. A usage-limit or insufficient_quota line is MODEL_QUOTA_EXHAUSTED (exit 4, cached 15 minutes; quota wins over a 429 that names insufficient_quota); a plain 429 is MODEL_PROBE_RATE_LIMITED (exit 0, state rate_limited, never cached), reported as CODEX_MODE: unverified (rate_limited) so the review still runs and decides. The quota HINT says how many minutes gstack skips Codex and how to retry now (GSTACK_CODEX_PROBE_RETRY=1 skips the negative cache for that probe, or delete <state root>/.codex-model-probe), with the full troubleshooting URL. classifyOutsideReview reads the same trailing lines: a mid-review quota is unavailable (quota_exhausted), a mid-review 429 unavailable (rate_limited). New gate row rate_limited and docs anchor codex-rate-limited; the quota row documents the retry. Tests cover each line shape, the echoed prompt, exit 0, timeout, retry recovery, probe/classifier parity, and two fresh-shell preflight blocks where the second makes no paid Codex call. Co-authored-by: venkatareddyg <venkatareddyg@users.noreply.github.com> * ci: the eval image installs zsh, and the macOS lane sources the Codex probe from zsh Dockerfile.ci adds zsh so the sourced-helper guard runs (and fails loudly when zsh is missing) inside the eval container too. The macOS named regressions job sources bin/gstack-codex-probe from zsh in an unrelated directory and runs _gstack_codex_select_model exec (no paid call), then runs the sourced-helper guard on the macOS runner. A free test pins both lanes and runs the macOS step's script locally. * test: deterministic regression for the Codex watchdog freezing the command before reaping its children The existing stubborn-child test caught the reap-then-kill race only some of the time (2 of 3 runs on the pre-fix watchdog). A pkill that sleeps after reaping widens the window between reaping the children and killing the command, so a watchdog that does not SIGSTOP the command first always lets it print "late" after the deadline. Fails 3 of 3 on the pre-fix watchdog, passes 3 of 3 on the current one. * test: live codex smokes run codex in a private HOME and CODEX_HOME codex-resume-flag-semantics and codex-e2e-sol-scope probe the codex CLI (the latter at module load, in every free run), and every codex run writes $CODEX_HOME/tmp/arg0, so with a real codex on PATH they wrote into the developer's ~/.codex. Both now give codex a private HOME and CODEX_HOME and remove it afterwards. A free test runs each file against a stub codex that records HOME and CODEX_HOME and asserts neither is the caller's. * feat(ship): a red eval runs classify, measure, fix, re-measure, gate once (A6) Step 6 no longer stops at the first red paid eval: it reads the new lazily loaded measure section and runs the loop for each red case, and Step 5 measures a failed free-suite shard (diagnostic reruns, retry off) before the triage can call it pre-existing. The section states the diagnostic- not-verdict rule, the per-kind table, the ask-once and named-red stops, the unmeasured label and the honest-fix wording (observed k/n after fix at <cause>). A free test pins the steps and their order in the generated skill and checks every command and flag it names exists in the runner. Ship's parity cap rises to 1.455 (measured 272,944 / 187,706 = 1.4541). * docs(testing): diagnostic measurement is not a verdict; per-kind measure table (A6) * test(ship): seeded-flake paid case for the measure loop (A6, periodic, behavior) A fixture repo with no remote documents a single-case eval command and a gate command, both free local stubs. queue-priorities claims trial slots with atomic mkdir (reset per ship-measure round) and fails slots 2, 5 and 9 while src/priorities.js leaves its seed-shuffled list unsorted, printing failure_cause and failure_detail that name the line. The paid case gives /ship's generated Step 6 and measure section to a live session and asserts it measured the case alone, fixed the named line without touching the eval, re-measured at least 10 passing trials on the sorted file, and only then ran the gate once; any question other than the spend question is a contract violation. A free test measures the fixture through the real ship-measure CLI: 7/10 unsorted, 7/10 after an unrelated edit with the gate still red (ENG-13's negative control), 10/10 after the sort with the gate green. * test(cso): the missing-scanner case points Docker at a dead socket 'an optional scanner prerequisite does not turn completed manual coverage partial' assumed no usable Docker. On a machine with Docker and a pulled gitleaks image the scan completed and the test failed (also on main). The scan step now gets a DOCKER_HOST that cannot connect, which is the prerequisite-missing condition the test describes. * fix: Aside prompts travel as agent-written files, never inside the command The open-ended reading recipe (browse, devex-review), scrape's fuzzy-intent read and the shared web-research block put the model's question, query and reply format inside a double-quoted _aside_exec argument, where backticks and $(...) from page or repo text would run. The agent now writes the prompt into a private .gstack/tmp file; the send block rebuilds the path from the printed basename, refuses when the file is empty, and passes "$(cat "$PROMPT_FILE")". The fixed read-only sentence stays in the shell source. aside-driver pins move from the inline prompt to the file-based send block. Co-authored-by: dgrant <dgrant@users.noreply.github.com> * fix: design briefs and approval feedback travel as agent-written files Design briefs went into $D variants/generate/check as a double-quoted argument, and approval feedback was spliced into a single-quoted echo of JSON, so a quote, backtick or $(...) in either broke the command or ran. The agent now writes each brief into a private .gstack/tmp file and the block passes --brief "$(cat "$BRIEF_FILE")" (the CLI's --brief-file expects a JSON brief, so plain text uses --brief). variants and the later check reuse the same brief file. approved.json is built with jq -n from --arg values and --rawfile feedback, so the feedback is data. The office-hours mockup flow creates its brief and feedback files in one block. design-approval-flow now writes the feedback file (with quotes, backticks and $(...) in it) instead of substituting <FEEDBACK>, and checks the file is removed after the save. Co-authored-by: dgrant <dgrant@users.noreply.github.com> * fix: carve office-hours on every host to stay under the 160,000-byte ceiling With its brief, feedback and research prompts moved into files, the inlined office-hours render is 161,329 bytes on Codex and 160,302 on Factory, over SKILL_BYTE_CEILING, so gen-skill-docs --host all fails. Per the C4 policy (carve every skill whose external render exceeds the ceiling), office-hours joins ship and plan-ceo-review in CARVED_ON_EVERY_HOST. The Claude render is unchanged; external hosts read its sections relative to the installed skill. external-host-carve and qa-lazy-sections now include office-hours in their carved-skill lists. Co-authored-by: dgrant <dgrant@users.noreply.github.com> * chore: regenerate after the free-text mktemp guard * fix(codex): prompts and review focus travel as agent-written files Co-authored-by: dgrant <dgrant@users.noreply.github.com> Challenge and consult prompts, and the /codex review focus text, are written by the agent into private .gstack/tmp files and fed to Codex on stdin or read back with cat; no heredoc carries them. Consult's new and resumed runs share one block (and one parser) so no placeholder stands in for the parser; a resumed run reads its session id from .context/codex-session-id and checks it. Adds the A3 group 2 placeholder allowlist block. * fix(benchmark-models): an inline prompt goes through a prompt file Co-authored-by: dgrant <dgrant@users.noreply.github.com> * fix(land-and-deploy): PR head repository and branch travel as data Co-authored-by: dgrant <dgrant@users.noreply.github.com> The branch check reads headRepository/headRefName from gh's JSON into quoted shell variables; ls-remote, the confirm-first delete and the local delete use those variables instead of model-substituted names. The postfail test now pins the variable form it replaces. * fix(office-hours): the reviewer receipt must match the receipt grammar before the check runs Co-authored-by: dgrant <dgrant@users.noreply.github.com> * fix(setup-gbrain): cleanup-orphans collects the PAT with read_secret_to_env Co-authored-by: dgrant <dgrant@users.noreply.github.com> * fix(ship): PR body drafts and rejected test paths are agent-written files Co-authored-by: dgrant <dgrant@users.noreply.github.com> The PR body is written into two private drafts (through ## Documentation, and from ## Test plan on); the scan block splices Step 14.5's section between them into the scanned temp file and deletes the drafts. Rejected test paths are read from a written list, and paths outside the repository are skipped. Tests that ran the old heredoc blocks now write the drafts and list first. * fix(sync-gbrain): orchestrator flags must match an allowlisted grammar Co-authored-by: dgrant <dgrant@users.noreply.github.com> * fix: the gbrain page save and external-host placeholders pass the free-text rule The gbrain save block passed the whole page through a quoted heredoc inside --content; the agent now writes it to a mktemp file and gbrain put reads it on stdin. The Claude Code outside-voice runtime root and session mode, and the feature slug, join the allowlist with grammars; unused entries are dropped, and a test keeps every allowlisted placeholder tied to a real use. Co-authored-by: dgrant <dgrant@users.noreply.github.com> * fix: skill-specific Aside research queries travel as prompt files investigate, office-hours, plan-ceo-review, review, plan-eng-review, design-consultation Phase 2, the shared test bootstrap (B2) and QA's test bootstrap each carried their own _aside_exec call with the model-filled query inside a double-quoted argument. Skills that already carry the Web research block now give only the prompt-file text and use that block to create, write and send it; design-consultation, the shared bootstrap and QA create the file and send it with the new {{ASIDE_RESEARCH_SEND}} resolver, which is the same send block the research section uses (read-only sentence stays in the shell). aside-driver's B2 pin and qa-browser-preservation's bootstrap contract move from the inline call to the prompt file and the shared send resolver. Co-authored-by: dgrant <dgrant@users.noreply.github.com> * fix: prose design commands pass briefs and feedback as data The DESIGN_SETUP command list taught `iterate --feedback "..."`, and design-consultation's late-change and plan-design-review's slop-regenerate lines showed `--feedback "<feedback>"` / `"..."`; design-shotgun's retry showed `generate --brief "<brief>"` and `evolve --brief "<brief>"`. Feedback now reads "$(cat "$FEEDBACK_FILE")" from an agent-written mktemp file (the setup note says how), and the shotgun retry reads the variant's own brief out of briefs.json with jq instead of retyping it. Co-authored-by: dgrant <dgrant@users.noreply.github.com> * test: record parity sizes after the free-text file mechanism; refresh ship goldens Measured union and skeleton sizes for ship, plan-eng-review, plan-design-review, office-hours, design-consultation, review, qa, browse and design-shotgun after every posting, prompt and brief site moved to agent-written mktemp files; the ship goldens pick up the question-tuning slug and the dropped free_text field. * test: parity caps for the combined wave head (rounded up past the measured ratio) * fix(plan-ceo-review): the mode handoff helper reminds the model to lead its chat with the line (#3038) Periodic run 37272185151's auto-decide-preserved red replays as the Step 0E handoff-line class: the model ran gstack-ceo-mode-handoff --auto, got the exact line, then opened its chat with a heading and a paraphrase, so the user never saw the auto-decide line (the terminal collapses tool output) and the detector saw no outcome. The helper now prints a one-line reminder on stderr beside the line; the detector accepts the line followed by that reminder and nothing else. The ship Greptile check test reads its template (test-of-test ratchet). * test: every troubleshooting link in shipped code resolves, relative or full URL * docs(todos): Oct 6 fix-wave follow-ups * v1.91.32.0 release notes: Codex works from zsh, free text never enters shell commands, honest failures * fix(plan-ceo-review): show the mode handoff line through a PostToolUse hook, not model compliance (#3038) The stderr reminder beside the handoff line measured 1/10 on auto-decide-preserved: the model still opened its chat with a paraphrase ('I've set review mode to HOLD SCOPE...'), so the user never saw the line and the detector saw no outcome. /plan-ceo-review now declares a Claude-only PostToolUse hook that shows the helper's exact line as a system message. Diagnostic measurement on this head: 10/10, the line visible in every trial while no trial's chat led with it. The reminder is reverted. * fix: type the handoff hook's line filter * fix: repairs from the integrated free suite - The self-locate markers looked like heredocs to the pipe-deadlock guard; they are plain comment fences now. - The spawned block keeps the canonical 'conservative non-destructive' phrase the cross-surface drift guard pins. - The free-text block's mktemp refusal says 'mktemp failed', as every /codex temp file must. - The batch transcript read reports sizes in MiB. - docs/TESTING_INTERNALS.md gets a real 'Ship measure' heading for its anchor. - The early-question harness admits /plan-ceo-review's handoff hook by its exact command (it only adds a system message); any other PostToolUse Bash hook is still refused. - Paid file count and the unconsumed-file example follow the new seeded case; ship goldens refreshed. - The CSO scanner test points Docker at a dead socket, so a machine with the pulled image does not scan. * test(cso): a host with no Docker binary is also a no-scan host The missing-image scan test failed on a Docker-less VM (docker is not installed in a trusted directory). Every accepted message is a reason the scan cannot run here; the not_assessed, helper-owned artifact assertions are unchanged. * ci: split the USERPROFILE assignment from export (SC2155) * fix(browse): Windows runtime roots read .source-path as a native path (#3026) The new windows-setup-e2e journey showed the installed browse could not start its server. setup runs under Git Bash and wrote .source-path as an MSYS path (/d/a/gstack); Node read it as \d\a\gstack on the current drive, found nothing, and fell back to the root's own bundle, which cannot import playwright. setup now writes cygpath -m, and the CLI maps an MSYS drive path for installs written by an older setup. The journey prints the daemon and startup logs when the chain fails. * fix(ship-measure): defects from the parallel #3034 plan review - A trial passes only with a JUnit testcase that executed and passed; a --case that selected nothing also exits 0. - measure runs a no-cost --list preflight that must plan the case's own file before any paid trial. - Diagnostic trials drop EVALS_CACHE_DIR/EVALS_CACHE_RUNTIME_ID, so they never reuse a stored judge pass or publish one the gate could reuse. - Gate once: when CI runs the gate on push, the push is the gate run; the skill no longer also starts eval:bg:pr (a second paid gate). - ubi-runner: down fails unless the VM is confirmed gone, and nothing sweeps other runners' VMs by default (UBI_GC_HOURS opt-in). * test(windows): the seeded-flake fixture drives a POSIX shell stub, so it stays off the Windows lane CreateProcess cannot exec the fixture's ./evals.sh shebang script (status null on windows-free-shard 6). The measure runner is covered on Windows by ship-measure.test.ts, which uses in-process fake runners. * fix: the free-text block refuses an unset temp dir instead of writing at / The rendered block ran mktemp "$_GT/..." with _GT unset in the portability test; on Linux that fails at /, but Git Bash on Windows can write to its install root, so the block went on (windows-free-shard 3). It now uses ${_GT:?}, so an unset directory always fails closed with the mktemp message. * test: pin the guarded ${_GT:?} temp-file form * test: the Greptile check's gh stub uses a portable shebang On Windows the absolute bash path has a space, so the stub never ran and every case read 'gh not logged in' (windows-free-shard 1). * test: the Greptile check runs with the native PATH and the gh stub first The PATH-only stub bin could not run its stub on Windows (every case read 'gh not logged in'). Stub cases now keep the real PATH with the stub first; only the no-gh case drops directories holding a real gh. --------- Co-authored-by: marcosdetry <marcosdetry@users.noreply.github.com> Co-authored-by: akshaykalia <akshaykalia@users.noreply.github.com> Co-authored-by: scottgigante-hubflow <scottgigante-hubflow@users.noreply.github.com> Co-authored-by: woodsonl <woodsonl@users.noreply.github.com> Co-authored-by: bezdekt <bezdekt@users.noreply.github.com> Co-authored-by: dgrant <dgrant@users.noreply.github.com> Co-authored-by: venkatareddyg <venkatareddyg@users.noreply.github.com> Co-authored-by: CharlesBerg85 <CharlesBerg85@users.noreply.github.com> Co-authored-by: VaibDeveloper <VaibDeveloper@users.noreply.github.com> Co-authored-by: Hagetino <Hagetino@users.noreply.github.com> Co-authored-by: Rekin226 <Rekin226@users.noreply.github.com> Co-authored-by: ekson73 <ekson73@users.noreply.github.com> Co-authored-by: tianxchen <tianxchen@users.noreply.github.com> Co-authored-by: BenjaminDSmithy <BenjaminDSmithy@users.noreply.github.com> Co-authored-by: ubay887 <ubay887@users.noreply.github.com> Co-authored-by: nareshh74 <nareshh74@users.noreply.github.com> Co-authored-by: syong <syong@users.noreply.github.com>
607 lines
32 KiB
Cheetah
607 lines
32 KiB
Cheetah
## Review preparation
|
||
|
||
Follow the blocks below in order after startup. Confidence Calibration and
|
||
Decision procedure are reference rules, not additional review passes.
|
||
|
||
## Review record and write policy
|
||
|
||
- **Target:** the plan, diff or code path selected at the Scope gate. It stays fixed.
|
||
- **Working plan:** the proposed work and its current approvals. For a plan target,
|
||
start with that plan; for code, build a remedy plan from the findings. This is
|
||
review content, not permission to edit implementation or create another file.
|
||
- **Report file:** the one destination for the working plan, findings, decision
|
||
ledger and final structured report. It may be the selected plan or a separate file.
|
||
|
||
| Target | Evidence to examine |
|
||
|---|---|
|
||
| Plan or design document | Proposed paths, checked against existing interfaces and tests |
|
||
| Branch diff | Changed behavior and surrounding code, traced from entry points |
|
||
| Specific file or directory | Existing behavior and relevant callers/tests |
|
||
|
||
When Test review or Outside Voice refers to the plan, use the current working
|
||
plan and this target evidence. Trace current behavior and proposed changes
|
||
separately. Include actual decisions in Outside Voice's bounded input.
|
||
|
||
Choose the **report file** before any ledger write:
|
||
1. Use the output/report path explicitly requested by the user.
|
||
2. Otherwise use the selected plan file, if there is one.
|
||
3. Otherwise use `$GSTACK_STATE_ROOT/projects/$SLUG/$BRANCH-eng-review-{YYYYMMDD-HHMMSS}.md`, adding a suffix on collision. Obtain assignments from `~/.claude/skills/gstack/bin/gstack-paths` and `~/.claude/skills/gstack/bin/gstack-slug`; failed commands or missing values make this path unavailable.
|
||
|
||
Never substitute an unrelated active plan or silently replace a requested destination.
|
||
|
||
**Check each artifact and parent directory's permission before writing.** Honor
|
||
user and host limits, including active-plan-only restrictions. Permission for one
|
||
path authorizes no other; implementation edits require explicit authority.
|
||
|
||
| Artifact | Destination | If writing is forbidden |
|
||
|---|---|---|
|
||
| Working plan, ledger and complete review report | Selected report file | Ask for a permitted destination if the user can supply one; wait without completion telemetry. If none is permitted, follow **Read-only review** below, then use **Blocked outcome**. |
|
||
| QA Test Plan and task JSONL | Discovery paths below | Present each completely as **not persisted** and continue. |
|
||
| TODOS.md | The project's TODO file | Present accepted TODO content as **not persisted** and continue. |
|
||
| Required Review Log | The helper's state location | Present its fields as **not persisted**; at Review Log, use **Blocked outcome** instead of publishing a saved review. The final gate cannot pass without this log. |
|
||
| Best-effort metadata/learning logs | Helper-defined locations | Skip forbidden writes; otherwise keep their best-effort behavior. |
|
||
|
||
QA Test Plan/task JSONL keep discovery paths `$GSTACK_STATE_ROOT/projects/{slug}/`:
|
||
`{user}-{branch}-eng-review-test-plan-{datetime}.md` and
|
||
`tasks-eng-review-{datetime}.jsonl`. Keep their formats; do not relocate.
|
||
|
||
**First report save:** Name the fixed target in the report header. Read an
|
||
existing destination and preserve its content. For a new file, create permitted
|
||
parent directories, then write that header, an unchanged copy of the original
|
||
plan (for plan targets), and the scope record or ledger being saved. Recheck option 3's collision before
|
||
creation; use a suffix rather than overwrite. Findings and fixes first enter
|
||
through Scope Challenge C's ledger saves, never earlier. Put records before an existing `## GSTACK REVIEW REPORT`, or
|
||
at EOF if absent; create that terminal report only at Plan File Review Report.
|
||
|
||
**Write routes.** A forbidden write follows its row above.
|
||
- **Read-only review:** At each scope/decision record save, present the complete
|
||
record, grid and authorized amendments as **not persisted** instead. At both
|
||
pre-question and post-answer verification gates, perform the same comparisons
|
||
on that presentation instead of a saved Read. This supports chat review, never
|
||
the saved-report gate.
|
||
- **Failed permitted save** (error or failed Read-back): use **Recovery routing →
|
||
Repairable write/read failure**, never the routes above. Do not ask from an
|
||
unsaved record; an unrecovered failed write blocks the review.
|
||
|
||
{{LEARNINGS_SEARCH}}
|
||
|
||
## Retrospective learning
|
||
History paths by review target:
|
||
- Plan: named existing paths. Mark named future paths `not available`; missing
|
||
history proves nothing about proposed behavior. Never invent paths.
|
||
- Branch diff: changed files.
|
||
- File/directory: selected path.
|
||
|
||
Run `git log --oneline -- <paths>` and `git log --grep=revert --oneline -- <paths>`.
|
||
Check recurring issues and reversals.
|
||
|
||
**Plan-review evidence:** Implementation/validation steps are proposals. Calibrate
|
||
findings below: quote the motivating plan requirement (file:line) and check existing interfaces
|
||
where applicable. Do not require future code or call a proposed regression observed.
|
||
Code-specific examples concern existing code.
|
||
|
||
Bounded probes address named current-behavior/interface uncertainties. Report
|
||
evidence, limits, unknowns and future verification. Complete the review without
|
||
building proposed code. Keep suppressed findings for the output appendix.
|
||
|
||
{{CONFIDENCE_CALIBRATION}}
|
||
|
||
## Decision procedure
|
||
|
||
Use this transaction for findings from Scope Challenge, Sections 1–4, Outside
|
||
Voice, late changes and TODO choices. Finish one choice before the next.
|
||
|
||
Context Recovery/prerequisites, Prior Learnings configuration and the initial
|
||
target selector use their own menus, without a pre-answer ledger. Scope Challenge
|
||
B also uses its own selectors and post-answer scope record. These selections
|
||
approve no engineering remedy; navigation likewise grants no implementation scope.
|
||
|
||
Use the preamble's tool resolution, failure fallback and authorized auto-decision
|
||
rules. Use Review record and write policy for every save below.
|
||
|
||
### Prepare an unanswered choice
|
||
|
||
**Establish current state.**
|
||
|
||
Read the request, source and actual answers. Give each finding a number, severity,
|
||
confidence, file:line and reviewer. Record two separate facts:
|
||
- **Plan baseline:** the last approved value, exact scope and answer reference;
|
||
if nothing was approved, record the original proposal.
|
||
- **Runtime evidence:** what existing code or a probe shows. Mark unverified
|
||
behavior unknown.
|
||
|
||
Approval does not prove deployed behavior, and observed behavior does not grant
|
||
approval. Drafts, recommendations and reviewer agreement grant neither. For a
|
||
factual correction that changes no behavior, record the correction and evidence;
|
||
no question or comparison grid is needed.
|
||
|
||
If an exact prior approval covers the work, cite its answer and disposition.
|
||
Carry its necessary code, tests, documentation and later-discovered required
|
||
proof forward without asking again. Otherwise leave the remedy pending. Reopen
|
||
an approved choice only for a concrete new risk, contradictory evidence or a
|
||
changed assumption. Explain the reason and retain earlier values, complete
|
||
briefs and answers in History. Record remaining unknowns and uncertain risks.
|
||
If no new answer is needed, continue the calling section; otherwise prepare one
|
||
pending choice below.
|
||
|
||
**Separate independent choices.**
|
||
|
||
Before drafting options, list each current value and proposed change: behavior,
|
||
approach, guarantee or bound. Include response timing, resources, lifetimes and
|
||
optional verification method or depth. Give each bound a measure and unit.
|
||
|
||
Give independently selectable changes separate IDs. If the user can accept one
|
||
while another stays approved or undecided, they are separate choices even in the
|
||
same finding, function or patch. A reopened choice keeps its ID and receives the
|
||
next continuous `D<N>` question number.
|
||
|
||
Keep one behavior with its necessary code, tests and documentation. Alternative
|
||
mechanisms for that fixed behavior belong in one question; independently
|
||
selectable runtime outcomes do not. Optional depths of one verification form
|
||
one choice. Separate instrumentation, follow-ups, guarantees and policies need
|
||
their own choices, and their tests wait for approval.
|
||
|
||
**Compare one choice.**
|
||
|
||
Select one pending ID. Prepare its question in this order:
|
||
|
||
**Draft the native fields:** build `currentDecision`:
|
||
- `question`: the complete D-numbered preamble brief, including Project, ELI10,
|
||
Stakes, Recommendation and applicable completeness/net fields.
|
||
- `header`: the exact native header.
|
||
- `options`: every exact label and full description.
|
||
|
||
Put the problem and file:line in the native fields. Offer 2–3 options, including
|
||
do-nothing when reasonable; Outside Voice retains its four-option menu.
|
||
Each option must explain human/CC effort, risk and maintenance. Tie the
|
||
recommendation to the engineering preferences; prefer complete coverage when
|
||
extra CC effort is marginal. Make the header and every label final before saving:
|
||
within the host's stated length limits, or under 5 words each when none are stated.
|
||
Put details in descriptions.
|
||
|
||
For one fixed approved contract, coverage choices vary implementation or proof
|
||
depth. Apply the preamble's Completeness scores or kind-note accordingly.
|
||
Test-review scores rate existing/proposed tests, not answer status.
|
||
|
||
**Audit the commitments.** Build a separate **comparison grid** for the whole
|
||
brief. Give every selectable
|
||
behavior, approach, guarantee or bound a row. Show its concrete current value,
|
||
each option's value and work, and any approval citation. Include shared, fixed
|
||
and pending choices.
|
||
|
||
Use these three checks for every column:
|
||
1. Vary only this choice: every column repeats each other approved value
|
||
unchanged and leaves each other pending choice pending. A value shared by all
|
||
options still needs approval if it is new.
|
||
2. Treat necessary implementation and proof of an approved contract as common
|
||
work. Cite its answer instead of creating another approval row. Never cut an
|
||
established contract or its required proof.
|
||
3. An Investigate/Defer option must bound the investigation and name what stays
|
||
unchanged or pending. It approves no implementation, including a conditional
|
||
fix. Keep that remedy pending.
|
||
|
||
**Reconcile before saving.** Compare each option's full label and description
|
||
with every row in its grid column. They must make the same commitments and retain
|
||
the same conditions. Put all deliberation in the native question/descriptions;
|
||
a saved-only Pros/cons block cannot supply missing decision context. Repair
|
||
contradictions now. If you discover another independent choice, separate it and
|
||
rebuild this comparison before saving or sending the question.
|
||
|
||
For example, jitter and a delay cap can be chosen independently. A menu of “both / cap only / neither” bundles them by omitting “jitter only.” Ask about jitter first:
|
||
|
||
| Choice | Current | A | B |
|
||
|---|---|---|---|
|
||
| R1 jitter | unspecified, pending | on | off |
|
||
| R2 delay cap | unspecified, pending | unspecified, pending | unspecified, pending |
|
||
|
||
After the jitter answer, carry that value into both options of the later cap question.
|
||
|
||
**Pending-record checkpoint.**
|
||
|
||
Save the record, complete grid and exact `currentDecision` using the report
|
||
placement above. Include every native field, the recommendation
|
||
and all options. A–D record selectors are ledger notation only: if a saved label
|
||
already starts `A)`/`B)`/`C)`/`D)`, keep that one prefix; otherwise add it. Compare
|
||
the label separately from that notation by removing the selector before matching.
|
||
|
||
When revising, replace the whole current payload for this record: comparison
|
||
grid, question, header, options, state, actual answer and accepted scope. Keep
|
||
other choices' headings, content and approvals intact; move superseded payloads
|
||
to History. Do not leave duplicate Question, Header or Options fields.
|
||
|
||
```markdown
|
||
## Decision ledger
|
||
|
||
### R1: <one independently selectable choice>
|
||
Finding: <number, severity, confidence, file:line and reviewer>
|
||
Plan baseline: <last approved value, exact scope and answer reference; otherwise the original proposal>
|
||
Runtime evidence: <observed value and source/probe; unknown if unverified>
|
||
Comparison grid: <complete comparison grid>
|
||
Question D2:
|
||
<currentDecision.question in full, including its D2 title and recommendation>
|
||
Header: <currentDecision.header>
|
||
Options:
|
||
<first option's exact label, with one A) record selector>
|
||
<first option's full description>
|
||
<second option's exact label, with one B) record selector>
|
||
<second option's full description>
|
||
|
||
State: <pending, or approved>
|
||
Actual answer: <unanswered, or actual option and answer reference>
|
||
Accepted scope: <exact approved work; none if no change approved>
|
||
History: <earlier values, briefs, answers and reason for reopening>
|
||
```
|
||
|
||
Check the Write/Edit result, then use Read to fetch the entire saved record.
|
||
Compare every native field with `currentDecision` and the whole saved grid with
|
||
the prepared comparison.
|
||
Read after the final edit, even if Edit says the content is current in context.
|
||
Grep, chat references, summaries and planned writes do not verify the record.
|
||
Repair any difference and repeat the complete Read before asking. A failed save
|
||
blocks the question; unreadable or unverifiable records use **Recovery routing**.
|
||
|
||
If any payload field changes, including a shortened label or formatting edit,
|
||
rebuild the comparison, replace the whole saved payload and Read it again. An older
|
||
comparison or a critic's advice cannot substitute for this verification.
|
||
|
||
### Send once and wait
|
||
|
||
Send `AskUserQuestion({ questions: [currentDecision] })` only after the pending-record checkpoint passes. Send one
|
||
question object for one choice; other IDs wait. Copy the verified question,
|
||
header, labels and descriptions literally. Do not add or strip brief paragraphs
|
||
or rebuild options. Authorized prose and auto-decisions use this same verified
|
||
brief with the preamble's rendering and answer rules.
|
||
When Question Tuning is enabled, copying the verified question preserves its
|
||
`<gstack-qid:{question_id}>` marker.
|
||
|
||
**STOP until the actual answer arrives.** Do not apply a remedy, make another
|
||
call, start the next section or call ExitPlanMode while the choice awaits an
|
||
answer. An obvious fix still needs an answer unless exact prior approval covers it.
|
||
|
||
### Record the answer
|
||
|
||
Read the selected saved label, full description and grid column together. Carry
|
||
all commitments, conditions, unchanged values and pending choices forward. If
|
||
they conflict or bundle independent choices, preserve the actual answer, explain
|
||
the conflict and return to **Prepare an unanswered choice** for a new verified
|
||
brief and another answer. Do not reinterpret a caption,
|
||
drop a commitment or advance with conflicting approvals.
|
||
|
||
Replace the whole adjacent `State` / `Actual answer` / `Accepted scope` block
|
||
after the options. Use the actual option and answer reference. Set State to
|
||
`approved` for accepted scope or `pending` for an unresolved remedy. Each field
|
||
must occur once outside History. Preserve the options and move superseded states
|
||
to History. If older fields are separated, consolidate all three and remove their
|
||
old occurrences in the same edit; never update only the answer/scope tail.
|
||
|
||
Use a scoped Edit to save this record and only the authorized working-plan
|
||
amendments. Leave other choices unchanged.
|
||
|
||
Check the save result, then Read the entire resolution block, including State.
|
||
Verify that its unique state, actual answer and accepted scope match the complete
|
||
selected option and grid column. An answer-only search or current-in-context hint
|
||
cannot replace Read. Correct any discrepancy before advancing; apply the write
|
||
policy to failures.
|
||
|
||
For the next choice, use the updated working plan and answer; when finished,
|
||
continue the calling section. Keep chosen values
|
||
fixed in later questions, and explain when a choice has become irrelevant rather
|
||
than asking it again. Start the next section only when no answer is pending in
|
||
this section. Keep unresolved risks and verification visible; resolve risk and
|
||
safety choices before readiness. /autoplan uses its authorized decisions and
|
||
audit trail, leaving User Challenges for its final gate.
|
||
|
||
## Scope Challenge
|
||
|
||
### A. Assess the target
|
||
|
||
Complete these checks before the complexity decision in B. Do not apply scope
|
||
changes or write findings into the plan yet.
|
||
|
||
- **What already solves each sub-problem?** Inspect helpers, libraries, callers and reusable outputs: behavior and dependency/deployment boundaries. Cite authored sources; label proposed callers with their motivating plan requirement and assumptions.
|
||
- **What minimum changes achieve the goal?** Flag work deferrable without blocking it; challenge scope creep.
|
||
- **Complexity check:** Count the selected work, not files read only as evidence:
|
||
for a plan, its proposed changed files and new classes/services; for a diff,
|
||
changed files and classes/services introduced by that diff; for a file/directory,
|
||
files in that selected scope and any explicitly proposed new classes/services.
|
||
Count each once, label estimates, and seek fewer moving parts. Use these counts in B.
|
||
- **Search check:** For each new architectural pattern, infrastructure component
|
||
or concurrency approach, research built-ins, current practice and pitfalls
|
||
through Aside (entrypoint readiness), one read-only request per pattern.
|
||
Prompt file text (create, write and send it with the Web research runs in Aside blocks in SKILL.md):
|
||
`{framework} {pattern} built-in, {pattern} best practice {current year}, and {framework} {pattern} pitfalls. Reply with up to 8 bullets, each with its source URL.`
|
||
|
||
If Aside is unavailable, use host WebSearch for these queries. With neither,
|
||
skip and note: "Search unavailable — proceeding with in-distribution knowledge only."
|
||
|
||
Prefer available built-ins. Label recommendations **[Layer 1]**, **[Layer 2]**,
|
||
**[Layer 3]** or **[EUREKA]** per Search Before Building; explain departures
|
||
from standard practice.
|
||
- **TODOS cross-reference:** Read existing `TODOS.md`: what blocks this plan,
|
||
fits this PR without expanding scope, or needs a new TODO?
|
||
|
||
- **Completeness check:** Full tests, edges and errors cost 10-100x less with AI.
|
||
Prefer completeness when a shortcut saves only CC+gstack minutes. Boil the ocean.
|
||
|
||
- **Distribution check:** For new artifacts, verify build/publish CI/CD, target
|
||
OS/architectures and download/install channels. Put deferrals in "NOT in scope".
|
||
|
||
### B. Resolve complexity selectors
|
||
|
||
With fewer than 8 files AND fewer than 2 new classes/services, skip B's questions
|
||
and go directly to **C. Resolve findings**.
|
||
At 8+ files or 2+ new classes/services, STOP before Section 1. Use the
|
||
preamble's decision-brief format for this complexity gate, in this order:
|
||
|
||
Initial scope selectors need no grid or **pre-answer** ledger write. Ask and
|
||
wait before changes.
|
||
|
||
1. Explain the complexity. Ask each proposed feature cut/deferral separately;
|
||
wait before changing scope. With no proposed cuts, keep the feature list and
|
||
go directly to the structure question.
|
||
2. Always ask the structure question when this gate trips, even with no cuts.
|
||
Compare only the file/class arrangement. Use labels `Original arrangement`
|
||
and `Smaller arrangement`; put files/classes in each description. Both retain
|
||
the same approved feature list, contracts and approved
|
||
security/error/test/performance fixes. Include `Pending remedies not decided here: <ids>` in the
|
||
question; unapproved fixes stay pending. If no smaller arrangement preserves
|
||
these commitments, explain that and offer confirmation of the original
|
||
arrangement or a pause to investigate a smaller one. Wait for the answer.
|
||
A pause leaves the arrangement undecided: investigate only the agreed question,
|
||
then return to this structure selector. Do not continue to C until it is settled.
|
||
3. Save the actual feature and structure answers as one scope record: `feature
|
||
answers: <refs>; structure: <A/B + ref>; accepted scope: <exact scope>;
|
||
pending remedies: <ids or none>`.
|
||
|
||
This is a post-answer scope summary, not a remedy's pending ledger record.
|
||
Save it under the write policy and Read it back against the actual answers;
|
||
on the permitted read-only route, present and verify it as **not persisted**.
|
||
Do not invent a pre-answer record afterward. A failed save or Read blocks advancement.
|
||
|
||
After verification, apply only accepted scope changes. Do not re-argue reduction
|
||
or skip approved components. Continue to **C. Resolve findings**.
|
||
|
||
### C. Resolve findings
|
||
|
||
Run C whether B was completed or skipped.
|
||
|
||
1. Present numbered Scope Challenge findings with calibrated severity, confidence
|
||
and source; use "No issues found" for an empty list.
|
||
2. Resolve each remedy through Decision procedure, reusing exact answers.
|
||
Findings and scope answers approve no remedies.
|
||
3. Report accepted/rejected/deferred/pending dispositions from those answers.
|
||
|
||
Record the Scope Challenge result from actual accepted changes: with a scope
|
||
reduction, `scope reduced per recommendation`; otherwise `scope accepted as-is`,
|
||
including when B was skipped. A smaller arrangement that preserves scope is not
|
||
a scope reduction. This result supplies MODE; it approves no pending remedy.
|
||
Keep it current if later approved choices change scope.
|
||
Continue to Section 1 only when no answer is pending.
|
||
|
||
## Review Sections (after scope is agreed)
|
||
|
||
Evaluate Architecture → Code Quality → Tests → Performance. Never condense,
|
||
abbreviate or skip a section, including strategy/spec/infra plans.
|
||
|
||
After each of Sections 1–4, resolve new or reopened choices through Decision
|
||
procedure, report findings and dispositions, then continue. Per section, output
|
||
every main-report finding in the Confidence Calibration format, most severe first
|
||
(or "No issues found"), one question per new or reopened choice, then `Dispositions:` (accepted, rejected,
|
||
deferred or pending, with D-number or answer) for each finding.
|
||
|
||
### 1. Architecture review
|
||
Evaluate:
|
||
* System/component boundaries, dependencies and coupling.
|
||
* Data flow, bottlenecks, scaling and single points of failure.
|
||
* Security: auth, data access and API boundaries.
|
||
* Key flows needing ASCII diagrams in plans/code.
|
||
* One realistic production failure per new path/integration; does the plan handle it?
|
||
* **Distribution architecture:** New artifacts' build, publish and update paths; included or deferred CI/CD.
|
||
|
||
### 2. Code quality review
|
||
Evaluate:
|
||
* Organization and module structure.
|
||
* Shared-code opportunities in the target and related callers, using the rubric below. No standalone history/PR sweep or quotas. Check proposed caller assumptions against existing interfaces.
|
||
* Explicitly flag error handling gaps and missing edge cases.
|
||
* Technical debt, fragility and needless complexity per engineering preferences.
|
||
* Accuracy of touched files' ASCII diagrams.
|
||
|
||
{{SHARED_LIBS_RUBRIC}}
|
||
|
||
Use Decision procedure for new/reopened extraction choices; scope approval does not approve extraction.
|
||
|
||
### 3. Test review
|
||
|
||
For shared-code changes, audit existing/missing shared-contract tests (behavior,
|
||
errors, side effects, boundaries) and each migrated caller's integration/differences.
|
||
Rejected extractions still need coverage for real duplicated-code defects.
|
||
|
||
{{TEST_COVERAGE_AUDIT_PLAN}}
|
||
|
||
After **Add missing tests to the plan** resolves test/eval decisions and the Test Plan Artifact is saved or presented, report the Test review findings and their dispositions and continue to Performance review.
|
||
|
||
### 4. Performance review
|
||
Evaluate:
|
||
* N+1 queries and database access patterns.
|
||
* Memory usage.
|
||
* Caching opportunities.
|
||
* Slow or complex paths.
|
||
|
||
On per-request or looped paths, check queries in loops, unbounded
|
||
queries or caches, missing indexes, whole-file loads and blocking calls without
|
||
timeouts. Give each finding's scale (rows, requests/s, bytes) or mark it
|
||
unknown; never invent benchmarks.
|
||
|
||
{{CODEX_PLAN_REVIEW}}
|
||
|
||
### Continue after Outside Voice
|
||
|
||
Finish the Outside Voice branch. Only completed reviews enter Cross-model tension. Record the actual coverage, including disabled or unavailable outcomes, in the Completion summary, then continue below.
|
||
|
||
## Final planning decisions
|
||
|
||
After Sections 1–4 and Outside Voice, resolve the TODO choices, then check Approval readiness before Required outputs.
|
||
|
||
### TODOS.md updates
|
||
Review every potential TODO. Reuse an exact prior disposition under Decision procedure; ask about each unanswered proposal in its own AskUserQuestion. Never batch TODOs or silently skip them. Use `~/.claude/skills/gstack/review/TODOS-format.md`.
|
||
|
||
For each TODO, record **What**, **Why**, **Pros**, **Cons** (cost/complexity/risk),
|
||
**Context** (motivation, current state, where to start in 3 months), and
|
||
**Depends on / blocked by** (prerequisites/order).
|
||
|
||
Then present options: **A)** Add to TODOS.md **B)** Skip — not valuable enough **C)** Build it now in this PR instead of deferring.
|
||
|
||
Option C records accepted implementation scope; still do not edit product code.
|
||
|
||
{{PLAN_REVIEW_APPROVAL_CHECK}}
|
||
|
||
## Required outputs
|
||
|
||
After Approval readiness passes, follow this finish sequence using the reference
|
||
sections below; those references are not another review cycle.
|
||
|
||
For recovery or changed outputs, use the entrypoint's **Recovery routing**.
|
||
Reuse a successful Review Log only for unchanged saved outputs; changed outputs
|
||
must pass steps 1–4 again.
|
||
|
||
1. **Prepare the review body.** Complete the working plan, Implementation Tasks
|
||
and Completion summary below. Leave choices pending according to each record's
|
||
current State, actual answer and accepted scope. Save permitted auxiliary artifacts under the write policy.
|
||
Check the Test Plan already produced in Test review; update that artifact only
|
||
if later approved decisions changed its requirements. Do not recreate unchanged output.
|
||
2. **Save and Read back.** Use Plan File Review Report to save the complete body
|
||
and terminal `## GSTACK REVIEW REPORT`; pass its Read-back gate. Forbidden
|
||
persistence or an unrecovered save requires **Blocked outcome**, not logging.
|
||
3. **Log the saved review.** Run Review Log with saved Completion summary values.
|
||
If the required log is forbidden, show fields as not persisted and take **Blocked outcome**;
|
||
failures use the write policy's recovery. Neither supplies completion or saved-dashboard credit.
|
||
4. **Publish.** Display the Review Readiness Dashboard, then present the saved
|
||
Completion summary to the user.
|
||
5. **Choose navigation.** Use Next Steps — Review Chaining; wait for its answer.
|
||
A substantive change follows
|
||
**Recovery routing → Late change or missing work** before navigation resumes.
|
||
6. **Finish.** Run Learning hooks, including gated Brain Calibration Write-Back;
|
||
then return to the entrypoint's Section self-check and read-only EXIT PLAN MODE GATE in
|
||
every host mode. Only after both pass, run success telemetry and cache refresh;
|
||
call ExitPlanMode only in host plan mode.
|
||
|
||
### Output reference — review body
|
||
|
||
Place `Suppressed findings` as a body appendix before the terminal
|
||
`## GSTACK REVIEW REPORT`; nothing follows that terminal report.
|
||
|
||
### "NOT in scope" section
|
||
List considered work that was explicitly deferred, with one sentence explaining each deferral.
|
||
|
||
### "What already exists" section
|
||
Link existing solutions and distinguish reuse/rebuilding. For accepted shared-code
|
||
choices, reference their Code Quality/Test decisions and complete rubric evidence.
|
||
Explain safer separation or net growth; never re-ask settled remedies.
|
||
|
||
### Diagrams
|
||
Diagram non-trivial flows, states and pipelines in ASCII. Name files needing inline
|
||
diagrams for complex model, service or mixin behavior.
|
||
|
||
### Failure modes
|
||
For each new diagrammed path, name a realistic production failure, its test/error
|
||
handling coverage, and whether users see a clear error or a silent failure.
|
||
|
||
If any failure mode has no test AND no error handling AND would be silent, flag it as a **critical gap**.
|
||
|
||
### Worktree parallelization strategy
|
||
|
||
Group implementation into parallel git worktrees (`isolation: "worktree"`) or workspaces.
|
||
With one primary module or fewer than 2 independent workstreams, write:
|
||
"Sequential implementation, no parallelization opportunity." Otherwise give a
|
||
**Dependency table** by module, not guessed file:
|
||
|
||
| Step | Modules touched | Depends on |
|
||
|------|----------------|------------|
|
||
| (step name) | (directories/modules, NOT specific files) | (other steps, or —) |
|
||
|
||
**Parallel lanes:** disjoint modules together; shared modules sequentially, dependencies
|
||
later (`Lane A: step1 → step2 (shared models/)` / `Lane B: step3 (independent)`).
|
||
**Execution order:** launch/wait points ("Launch A + B. Merge both. Then C.").
|
||
**Conflict flags:** cross-lane shared modules to sequence or coordinate.
|
||
|
||
{{TASKS_SECTION_EMIT:eng-review}}
|
||
|
||
### Unresolved decisions
|
||
List unanswered/interrupted choices as "Unresolved decisions that may bite you later",
|
||
with IDs and missing answers. Never silently default. Count each once, excluding
|
||
prior reviews; the terminal report adds those separately.
|
||
|
||
### Completion summary
|
||
From final decisions/outputs; publish after report Read-back and Review Log:
|
||
- Step 0: Scope Challenge — ___ (scope accepted as-is / scope reduced per recommendation)
|
||
- Architecture Review: ___ issues found
|
||
- Code Quality Review: ___ issues found
|
||
- Test Review: diagram produced, ___ gaps identified
|
||
- Performance Review: ___ issues found
|
||
- NOT in scope: written
|
||
- What already exists: written
|
||
- TODOS.md updates: ___ items proposed to user
|
||
- Failure modes: ___ critical gaps flagged
|
||
- Unresolved decisions: ___ in this review
|
||
- Outside voice: recorded provider, completed / unavailable / disabled / skipped (reason)
|
||
- Parallelization: ___ lanes, ___ parallel / ___ sequential
|
||
- Lake Score: X/Y = answers picking a 10/10 option / answers scored for Completeness; N/A if Y=0.
|
||
|
||
{{PLAN_FILE_REVIEW_REPORT}}
|
||
|
||
## Review Log
|
||
|
||
Use these commands in finish step 3, after successful Read-back. Both logs follow the write policy: required review log, best-effort decision log.
|
||
|
||
```bash
|
||
~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"plan-eng-review","timestamp":"TIMESTAMP","status":"STATUS","unresolved":N,"critical_gaps":N,"issues_found":N,"mode":"MODE","commit":"COMMIT"}' || exit $?
|
||
~/.claude/skills/gstack/bin/gstack-decision-log '{"decision":"Eng review (MODE): ARCH_SUMMARY","rationale":"KEY_DECISION","scope":"branch","source":"skill","confidence":8}' 2>/dev/null || true
|
||
```
|
||
|
||
Second command: `ARCH_SUMMARY` = findings/dispositions; `KEY_DECISION` = durable
|
||
architecture choice. Omit it when none exists.
|
||
|
||
- **TIMESTAMP**: current ISO 8601 datetime
|
||
- **STATUS**: "clean" if `issues_found=0`, `unresolved=0` and `critical_gaps=0`; else "issues_open". Count resolved findings too; "issues_open" can mean mapped work, not failure.
|
||
- **unresolved**: this review's "Unresolved decisions" count; do not include prior reviews
|
||
- **critical_gaps**: number from "Failure modes: ___ critical gaps flagged"
|
||
- **issues_found**: four-section count only (Architecture + Code Quality + Performance + Test gaps). Report Scope Challenge and Outside Voice findings separately.
|
||
- **MODE**: FULL_REVIEW for the Scope Challenge result "scope accepted as-is"; SCOPE_REDUCED for "scope reduced per recommendation".
|
||
- **COMMIT**: output of `git rev-parse --short HEAD`
|
||
|
||
Only a successful required log permits publication as a saved review.
|
||
|
||
{{REVIEW_DASHBOARD}}
|
||
|
||
## Next Steps — Review Chaining
|
||
|
||
In finish step 5, offer applicable routes from the published dashboard:
|
||
- **A) Run /plan-design-review:** unreviewed UI scope (frontend, CSS, views or
|
||
interactions in the diagram/findings).
|
||
- **B) Run /plan-ceo-review:** optionally, an unreviewed significant product change
|
||
(new user-facing features, changed direction or substantial scope expansion).
|
||
- **C) Ready to implement — run /ship when done**
|
||
|
||
Flag stale CEO/design reviews from contradictory assumptions or significant commit
|
||
drift. If no further review is needed or `skip_eng_review: true`, state
|
||
"All relevant reviews complete. Run /ship when ready."
|
||
|
||
AskUserQuestion with only the applicable options. This is **navigation only**:
|
||
copy the working plan's task prerequisites, dependencies and execution order
|
||
without adding or strengthening them in the question or descriptions. A test
|
||
required before editing one function does not make every independent lane wait.
|
||
A next-step answer approves no implementation change.
|
||
|
||
## Learning hooks
|
||
|
||
In finish step 6, keep the working plan/approvals fixed. Review operational learnings
|
||
per preamble; use Capture Learnings below for other discoveries. Never log twice.
|
||
|
||
{{LEARNINGS_LOG}}
|
||
|
||
{{GBRAIN_SAVE_RESULTS}}
|
||
|
||
**Calibration gate status:** No supported preamble/config produces `BRAIN_CALIBRATION_WRITEBACK`. Skip unless that source explicitly enables it. Personal trust/MCP availability cannot enable it; never set it yourself.
|
||
|
||
{{BRAIN_WRITE_BACK}}
|