Merge 857f100d79 into c43c850cae

CHANGELOG.md

@@ -1,5 +1,141 @@
 # Changelog
 
+## [1.59.0.0] - 2026-06-01
+
+## **The whole plan-review family got carved. plan-eng, plan-design, and plan-devex now load their review bodies only after you have agreed scope.**
+
+The three remaining heavyweight plan-review skills followed `/plan-ceo-review` into the skeleton + on-demand section pattern. Each one's review body — the multi-section deep review, the outside voice, the required outputs, and the review report writer — moved into `sections/review-sections.md` behind a single STOP-Read that fires only after Step 0 scope is agreed. Step 0 (the conversation that decides what to review) and the plan-mode exit gate stay in the always-loaded skeleton. Same pattern, same safety net: Layer 0 confirms the AskUserQuestion format spec stays always-loaded in every skeleton, and the carved-vs-verbose proof established for plan-ceo holds for the family.
+
+### The numbers that matter
+
+Measured from the generated skeletons (`wc -c <skill>/SKILL.md`), regenerated for all hosts:
+
+| Skill | Before | After | Δ |
+|-------|--------|-------|---|
+| plan-eng-review | 106,984 B | 54,892 B | -48.7% |
+| plan-design-review | 112,057 B | 76,024 B | -32.2% |
+| plan-devex-review | 110,621 B | 69,658 B | -37.0% |
+
+Combined with v1.54-v1.58, six skills are now carved (ship, plan-ceo-review, office-hours, plan-eng-review, plan-design-review, plan-devex-review) and the shared preamble shed its CJK manual corpus-wide. The always-loaded review prose loads only when a review actually reaches it.
+
+### What this means for you
+
+Every plan-review skill starts lighter and pulls in its review body on demand. The reviews are identical pass for pass; only what is in context when changed. External hosts (codex, factory, kiro, opencode) still receive the full inline skill, so nothing regresses off Claude.
+
+### Itemized changes
+
+#### Changed
+- `/plan-eng-review`, `/plan-design-review`, `/plan-devex-review` are each a skeleton + one `sections/review-sections.md` on Claude; Step 0 stays always-loaded.
+- Parity, size-budget, and gen-skill-docs treat all three as carved skills (union content checks, skeleton-shrink assertions).
+
+## [1.58.0.0] - 2026-06-01
+
+## **Every skill that asks you questions got a little lighter, all at once — the AskUserQuestion preamble stopped carrying its rare-case manuals inline.**
+
+The AskUserQuestion format block is inlined into every interactive skill (~33 of them). It carried the full multi-paragraph CJK / non-ASCII escaping manual inline, even though that rule only matters when a question contains Chinese, Japanese, or Korean text. The operative rule ("write non-ASCII characters literally, never `\u`-escape") already lives in the always-loaded self-check, so the long justification moved to `docs/askuserquestion-cjk.md`, read on demand. One change, every skill benefits. This is the preamble half of the token-reduction program: per-skill carves shrink one skill at a time, this shrinks the shared surface that rides on all of them.
+
+### The numbers that matter
+
+Measured across the Claude-host corpus (`cat SKILL.md */SKILL.md | wc -c`), regenerated for all hosts:
+
+| Metric | Before (v1.57) | After (v1.58) | Δ |
+|--------|----------------|---------------|---|
+| Claude-host skill corpus | 3,087,499 B | 3,057,975 B | -29,524 B |
+| per interactive skill | full CJK manual inline | rule + 1 doc pointer | ~900 B each × ~33 |
+| AUQ core format (Layer 0) | always-loaded | always-loaded (unchanged) | guaranteed |
+
+The core decision-brief format (ELI10, recommendation, pros/cons, stakes, self-check) is untouched and still always-loaded — Layer 0 enforces it. Only the rarely-needed CJK rationale moved on-demand.
+
+### What this means for you
+
+Nothing changes in how questions look or behave. For the rare CJK question, the agent reads one small doc for the full rationale; the operative rule was never removed. Every interactive skill is ~900 bytes lighter at the always-loaded layer.
+
+### Itemized changes
+
+#### Added
+- `docs/askuserquestion-cjk.md` — full non-ASCII / CJK escaping rationale + worked example, read on demand.
+
+#### Changed
+- The AskUserQuestion preamble block trims the inline CJK manual to the operative rule + a doc pointer; the self-check reminder stays always-loaded.
+
+## [1.57.0.0] - 2026-06-01
+
+## **/office-hours got 25% lighter, and there is now a test that proves slimming a skill never degrades the questions it asks you.**
+
+Two things shipped. First, `/office-hours` is the third Phase B carve: at 118KB it was the second-heaviest skill, and every session paid for the design-doc templates and the tiered relationship handoff up front, even though those only matter at the very end. They moved into `sections/design-and-handoff.md`, behind a single STOP-Read after Phase 4.5. The live conversation (Phases 1 through 4.5) stays in the always-loaded skeleton. Second, and bigger for the long run: a paranoid AskUserQuestion test suite that proves the carving program does not quietly wreck the most user-facing surface in gstack. The fear was real. Slimming a skill could strand the question format (no ELI10, no recommendation, no pros/cons) in a section that is not loaded when the question fires. Now that cannot happen without a test going red.
+
+### The numbers that matter
+
+Measured from the generated skeletons (`wc -c <skill>/SKILL.md`) and the SDK capture eval (`test/skill-e2e-auq-matrix.test.ts`), regenerated for all hosts:
+
+| Metric | Before (v1.56) | After (v1.57) | Δ |
+|--------|----------------|---------------|---|
+| office-hours always-loaded | 118,280 B (~29.5K tokens) | 88,975 B (~22.2K tokens) | -24.8% |
+| design doc + handoff loaded per run | always | only at Phase 5 | on-demand |
+| office-hours AUQ (carved vs verbose) | 7/7 format, substance 5 | 7/7 format, substance 5 | no degradation |
+| skills with always-loaded AUQ-format guarantee | 0 | every interactive skill | Layer 0 |
+
+Across `/plan-ceo-review`, `/plan-eng-review`, `/plan-design-review`, `/plan-devex-review`, `/office-hours`, `/cso`, `/spec`, `/design-consultation`, and `/codex`, the first AskUserQuestion each fires scores a perfect 7/7 on format with recommendation substance 4-5.
+
+### What this means for you
+
+`/office-hours` starts a quarter lighter and pulls in the design-doc and handoff machinery only when it reaches them. You will not notice any behavior change. And every skill that asks you questions now carries a guarantee: the decision-brief format (plain-English ELI10, an explicit recommendation with a real reason, pros and cons, the stakes) is provably in context the instant any question fires, in both the fat and slim versions. The carving program can keep shrinking skills without anyone wondering whether the questions got worse.
+
+### Itemized changes
+
+#### Added
+- `office-hours/sections/design-and-handoff.md` — Phase 5 design-doc templates + Phase 6 tiered handoff, behind a STOP-Read pointer, with a passive `manifest.json` registry.
+- `test/auq-format-always-loaded.test.ts` — free, per-PR keystone: every interactive skill must carry the full AskUserQuestion format spec in its always-loaded skeleton, never stranded in a section. 51 cases plus a negative control.
+- `test/skill-e2e-auq-matrix.test.ts` — drives each AUQ-heavy skill to its first question and grades it to the plan-ceo bar (7/7 format, substance >=4).
+- `test/skill-e2e-auq-verbose-vs-carved-ab.test.ts` — proves a carved skill's question is not worse than the pre-carve monolith's, on the same trigger.
+- `test/skill-e2e-auq-consistency.test.ts` — same trigger N times, fails on any format element that appears in one run but not another.
+- `test/codex-e2e-recommendation-substance.test.ts` — grades `/codex`'s live recommendation substance.
+
+#### Changed
+- `/office-hours` is a skeleton + one section on Claude; Phases 1-4.5 stay always-loaded; external hosts still receive the full inline skill (no behavior change off Claude).
+
+#### For contributors
+- `test/helpers/auq-sdk-capture.ts` — reusable SDK capture engine: drives a skill to its AUQ, captures the verbatim generated text cleanly (real-PTY mangles plan-mode questions), grades format + recommendation substance robust to the connective.
+- Parity, size-budget, gen-skill-docs, and skill-validation treat office-hours as a carved skill (union content checks, skeleton-shrink assertion).
+
+## [1.56.0.0] - 2026-05-31
+
+## **The biggest plan-review skill stopped taxing every session. /plan-ceo-review's always-loaded cost dropped 42%, and its deep review loads only when you reach it.**
+
+`/plan-ceo-review` was the heaviest skill at 138KB, and every session paid for all of it up front, even during the Step 0 scope conversation that does not need the 11-section review prose yet. It is now an 81KB decision-tree skeleton plus one `sections/review-sections.md` the agent opens on demand. The 11 review sections, the outside-voice rules, the required-output registries, the completion summary, the review report writer, and the mode quick reference all moved behind a single STOP-Read pointer that fires only after you have agreed scope and mode. All of Step 0, the conversational front half, stays in the always-loaded skeleton byte for byte. Other hosts (codex, factory, kiro, opencode) keep the full inline skill, so nothing regresses off Claude. This is the second Phase B carve after `/ship`, following the documented one-at-a-time order.
+
+### The numbers that matter
+
+Measured directly from the generated skeleton (`wc -c plan-ceo-review/SKILL.md`) and its one section file, regenerated for all hosts:
+
+| Metric | Before (v1.55) | After (v1.56) | Δ |
+|--------|----------------|---------------|---|
+| plan-ceo-review always-loaded | 138,838 B (~34.4K tokens) | 80,731 B (~20.1K tokens) | -42% |
+| review prose loaded per run | all of it | only after scope + mode agreed | on-demand |
+| skeleton + section union | 138,838 B | 139,110 B | behavior preserved |
+| External-host plan-ceo-review | inline | inline (unchanged behavior) | no regression |
+
+The skeleton is what loads the instant `/plan-ceo-review` is invoked, so the ~14.4K-token drop is paid back on every review, not once.
+
+### What this means for you
+
+A `/plan-ceo-review` run starts ~42% lighter and pulls in the 11-section review only when it reaches it, after you have agreed scope and mode. You will not notice any behavior change. The review is identical section for section; the difference is what is in context when. If you want to read the review chapter in isolation, it lives at `~/.claude/skills/gstack/plan-ceo-review/sections/review-sections.md`.
+
+### Itemized changes
+
+#### Added
+- `plan-ceo-review/sections/review-sections.md` — the 11-section deep review, outside-voice rules, required-output registries, completion summary, review report writer, next-step chaining, and mode quick reference, behind a STOP-Read pointer, with a passive `manifest.json` registry.
+- `test/skill-ceo-section-ordering.test.ts` — gate-tier static guard: the STOP fires after Step 0, the review body is absent from the skeleton, the report writer lives in the section, and nothing review-governing sits below the STOP.
+- `test/skill-e2e-plan-ceo-review-section-loading.test.ts` — periodic real-PTY backstop that refreshes the installed skill, drives the full Step 0, and asserts the section is Read before the report.
+
+#### Changed
+- `/plan-ceo-review` is a skeleton + one section on Claude; Step 0 (scope + mode) stays always-loaded; external hosts still receive the full inline skill (no behavior change off Claude).
+- Parity, size-budget, and section-manifest tests treat plan-ceo-review as a carved skill (content + size floors run against the skeleton + section union; the skeleton-shrink assertion guards the always-loaded win).
+
+#### For contributors
+- `section-manifest-consistency` now discovers every carved skill automatically, so the next Phase B carve is covered the moment its manifest lands.
+- `gen-skill-docs` and `skill-validation` read the skeleton + sections union for carved skills, so relocated prose still counts in content checks.
+
 ## [1.55.1.0] - 2026-06-02
 
 ## **Telemetry now tells you exactly what it records and where it stays. The project-slug helper hands the shell a safe identifier on every path.**

TODOS.md

@@ -19,6 +19,38 @@ v1.47.0.0 baselines retained in `test/fixtures/` for the v1→v2 audit trail. Th
 captured skill bytes match `origin/main` exactly (the rebasing branch left every
 SKILL.md untouched). `bun test` is green again.
 
+## Token-reduction follow-ups (Phase B, filed via /plan-eng-review on the plan-ceo-review carve)
+
+### P3: Carve the always-loaded `{{PREAMBLE}}` reference blocks into an on-demand doc
+
+**What:** The per-skill section carves (`/ship` v1.54, `/plan-ceo-review` v1.56) yield
+real but bounded wins (-42% to -59% on the carved skill) because the shared
+`{{PREAMBLE}}` (~40-50KB on every tier-3/4 skill) is the dominant always-loaded cost
+and stays inline. Move the rarely-needed preamble REFERENCE blocks (the AskUserQuestion
+split-rules and the CJK / lone-surrogate escaping reference) into an on-demand
+section-style doc the agent reads only when it hits those edge cases, leaving the hot
+path (voice, completeness principle, recommendation format) inline.
+
+**Why:** Highest-ROI remaining token target. One preamble carve helps EVERY tier-≥2
+skill at once, not one skill per PR. The eng-review on the plan-ceo carve flagged that
+per-skill carves stay modest precisely because the preamble dominates the always-loaded
+surface.
+
+**Pros:** A single change reduces always-loaded cost across the whole skill pack.
+**Cons:** The preamble is load-bearing and shared; a botched carve regresses every skill.
+Needs the same union-parity + per-push freshness guards the section carves use, applied
+corpus-wide.
+
+**Context:** Builds on the v2 section pipeline (`scripts/resolvers/sections.ts`,
+`{{SECTION:id}}` / `{{SECTION_INDEX}}`). The preamble source is
+`scripts/resolvers/preamble.ts`. Measure which sub-blocks are cold (escaping reference,
+split-rules) vs hot (voice, recommendation format) before cutting. Validate on one skill,
+then roll corpus-wide.
+
+**Effort estimate:** L (human team) → M (CC+gstack)
+**Priority:** P3
+**Depends on / blocked by:** The section pipeline (shipped v1.54). No hard blocker.
+
 ## gbrowser memory follow-ups (filed via /plan-eng-review + /codex on the v1.49 leak-fix PR)
 
 These four items came out of the memory-leak investigation that shipped

VERSION

@@ -1 +1 @@
-1.55.1.0
+1.59.0.0

autoplan/SKILL.md

@@ -371,25 +371,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

canary/SKILL.md

@@ -363,25 +363,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

codex/SKILL.md

@@ -366,25 +366,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

context-restore/SKILL.md

@@ -367,25 +367,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

context-save/SKILL.md

@@ -366,25 +366,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

cso/SKILL.md

@@ -369,25 +369,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

design-consultation/SKILL.md

@@ -389,25 +389,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

design-html/SKILL.md

@@ -370,25 +370,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

design-review/SKILL.md

@@ -367,25 +367,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

design-shotgun/SKILL.md

@@ -384,25 +384,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

devex-review/SKILL.md

@@ -369,25 +369,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

docs/askuserquestion-cjk.md

@@ -0,0 +1,29 @@
+# AskUserQuestion — non-ASCII / CJK characters
+
+Read this on demand when an AskUserQuestion contains Chinese (繁體/簡體),
+Japanese, Korean, or other non-ASCII text. The operative rule is in the
+always-loaded AskUserQuestion self-check ("Non-ASCII characters written directly,
+NOT \u-escaped"); this doc is the full justification.
+
+## The rule
+
+When any string field (question, option label, option description) contains
+non-ASCII text, emit the literal UTF-8 characters in the JSON string. **Never
+escape them as `\uXXXX`.**
+
+Claude Code's tool parameter pipe is UTF-8 native and passes characters through
+unchanged. Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
+
+## Why escaping fails
+
+Manually escaping requires recalling each codepoint from training, which is
+unreliable for long CJK strings — the model regularly emits the wrong codepoint.
+Example: writing `㄃` thinking it is 管 (U+7BA1), but `㄃` is actually ㄃,
+so the user sees `管理工具` rendered as `㄃3用箱`.
+
+The trigger is long, multi-line questions with hundreds of CJK characters: that
+is exactly when reflexive escaping kicks in and exactly when miscoding is most
+damaging. Long ≠ escape. Keep characters literal.
+
+- Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
+- Right: `"question": "請選擇管理工具"`

document-generate/SKILL.md

@@ -369,25 +369,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

document-release/SKILL.md

@@ -367,25 +367,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

health/SKILL.md

@@ -365,25 +365,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

investigate/SKILL.md

@@ -404,25 +404,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

ios-clean/SKILL.md

@@ -367,25 +367,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

ios-design-review/SKILL.md

@@ -369,25 +369,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

ios-fix/SKILL.md

@@ -370,25 +370,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

ios-qa/SKILL.md

@@ -373,25 +373,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

ios-sync/SKILL.md

@@ -367,25 +367,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

land-and-deploy/SKILL.md

@@ -362,25 +362,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

landing-report/SKILL.md

@@ -363,25 +363,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

learn/SKILL.md

@@ -365,25 +365,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

office-hours/SKILL.md

@@ -400,25 +400,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 
@@ -940,6 +927,18 @@ Output: "Here's what I understand about this project and the area you want to ch
 
 ---
 
+
+---
+## Section index — Read each section when its situation applies
+
+This skill is a decision-tree skeleton. The steps below point to on-demand
+sections. Read a section in full before doing its step; do not work from memory.
+
+| When | Read this section |
+|------|-------------------|
+| writing the design doc and running the tiered relationship handoff (Phases 5-6, after the conversation and alternatives are done) | `sections/design-and-handoff.md` |
+---
+
 ## Phase 2A: Startup Mode — YC Product Diagnostic
 
 Use this mode when the user is building a startup or doing intrapreneurship.
@@ -1580,546 +1579,12 @@ selection in Phase 6 Beat 3.5.
 
 ---
 
-## Phase 5: Design Doc
+> **STOP.** Before writing the design doc and running the tiered relationship handoff (Phases 5-6, after the conversation and alternatives are done), Read `~/.claude/skills/gstack/office-hours/sections/design-and-handoff.md` and execute it
+> in full. Do not work from memory — that section is the source of truth for this step.
 
-Write the design document to the project directory.
+## Section self-check (before you finish)
 
-```bash
+Confirm you Read every section the Section index named as applying to this run, and executed it in full. The design doc and the handoff are the deliverables — if you produced them from memory without Reading `sections/design-and-handoff.md`, stop and Read it now.
-eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" && mkdir -p ~/.gstack/projects/$SLUG
-USER=$(whoami)
-DATETIME=$(date +%Y%m%d-%H%M%S)
-```
-
-**Design lineage:** Before writing, check for existing design docs on this branch:
-```bash
-setopt +o nomatch 2>/dev/null || true  # zsh compat
-PRIOR=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1)
-```
-If `$PRIOR` exists, the new doc gets a `Supersedes:` field referencing it. This creates a revision chain — you can trace how a design evolved across office hours sessions.
-
-Write to `~/.gstack/projects/{slug}/{user}-{branch}-design-{datetime}.md`.
-
-After writing the design doc, tell the user:
-**"Design doc saved to: {full path}. Other skills (/plan-ceo-review, /plan-eng-review) will find it automatically."**
-
-### Startup mode design doc template:
-
-```markdown
-# Design: {title}
-
-Generated by /office-hours on {date}
-Branch: {branch}
-Repo: {owner/repo}
-Status: DRAFT
-Mode: Startup
-Supersedes: {prior filename — omit this line if first design on this branch}
-
-## Problem Statement
-{from Phase 2A}
-
-## Demand Evidence
-{from Q1 — specific quotes, numbers, behaviors demonstrating real demand}
-
-## Status Quo
-{from Q2 — concrete current workflow users live with today}
-
-## Target User & Narrowest Wedge
-{from Q3 + Q4 — the specific human and the smallest version worth paying for}
-
-## Constraints
-{from Phase 2A}
-
-## Premises
-{from Phase 3}
-
-## Cross-Model Perspective
-{If second opinion ran in Phase 3.5 (Codex or Claude subagent): independent cold read — steelman, key insight, challenged premise, prototype suggestion. Verbatim or close paraphrase. If second opinion did NOT run (skipped or unavailable): omit this section entirely — do not include it.}
-
-## Approaches Considered
-### Approach A: {name}
-{from Phase 4}
-### Approach B: {name}
-{from Phase 4}
-
-## Recommended Approach
-{chosen approach with rationale}
-
-## Open Questions
-{any unresolved questions from the office hours}
-
-## Success Criteria
-{measurable criteria from Phase 2A}
-
-## Distribution Plan
-{how users get the deliverable — binary download, package manager, container image, web service, etc.}
-{CI/CD pipeline for building and publishing — GitHub Actions, manual release, auto-deploy on merge?}
-{omit this section if the deliverable is a web service with existing deployment pipeline}
-
-## Dependencies
-{blockers, prerequisites, related work}
-
-## The Assignment
-{one concrete real-world action the founder should take next — not "go build it"}
-
-## What I noticed about how you think
-{observational, mentor-like reflections referencing specific things the user said during the session. Quote their words back to them — don't characterize their behavior. 2-4 bullets.}
-```
-
-### Builder mode design doc template:
-
-```markdown
-# Design: {title}
-
-Generated by /office-hours on {date}
-Branch: {branch}
-Repo: {owner/repo}
-Status: DRAFT
-Mode: Builder
-Supersedes: {prior filename — omit this line if first design on this branch}
-
-## Problem Statement
-{from Phase 2B}
-
-## What Makes This Cool
-{the core delight, novelty, or "whoa" factor}
-
-## Constraints
-{from Phase 2B}
-
-## Premises
-{from Phase 3}
-
-## Cross-Model Perspective
-{If second opinion ran in Phase 3.5 (Codex or Claude subagent): independent cold read — coolest version, key insight, existing tools, prototype suggestion. Verbatim or close paraphrase. If second opinion did NOT run (skipped or unavailable): omit this section entirely — do not include it.}
-
-## Approaches Considered
-### Approach A: {name}
-{from Phase 4}
-### Approach B: {name}
-{from Phase 4}
-
-## Recommended Approach
-{chosen approach with rationale}
-
-## Open Questions
-{any unresolved questions from the office hours}
-
-## Success Criteria
-{what "done" looks like}
-
-## Distribution Plan
-{how users get the deliverable — binary download, package manager, container image, web service, etc.}
-{CI/CD pipeline for building and publishing — or "existing deployment pipeline covers this"}
-
-## Next Steps
-{concrete build tasks — what to implement first, second, third}
-
-## What I noticed about how you think
-{observational, mentor-like reflections referencing specific things the user said during the session. Quote their words back to them — don't characterize their behavior. 2-4 bullets.}
-```
-
----
-
-## Spec Review Loop
-
-Before presenting the document to the user for approval, run an adversarial review.
-
-**Step 1: Dispatch reviewer subagent**
-
-Use the Agent tool to dispatch an independent reviewer. The reviewer has fresh context
-and cannot see the brainstorming conversation — only the document. This ensures genuine
-adversarial independence.
-
-Prompt the subagent with:
-- The file path of the document just written
-- "Read this document and review it on 5 dimensions. For each dimension, note PASS or
-  list specific issues with suggested fixes. At the end, output a quality score (1-10)
-  across all dimensions."
-
-**Dimensions:**
-1. **Completeness** — Are all requirements addressed? Missing edge cases?
-2. **Consistency** — Do parts of the document agree with each other? Contradictions?
-3. **Clarity** — Could an engineer implement this without asking questions? Ambiguous language?
-4. **Scope** — Does the document creep beyond the original problem? YAGNI violations?
-5. **Feasibility** — Can this actually be built with the stated approach? Hidden complexity?
-
-The subagent should return:
-- A quality score (1-10)
-- PASS if no issues, or a numbered list of issues with dimension, description, and fix
-
-**Step 2: Fix and re-dispatch**
-
-If the reviewer returns issues:
-1. Fix each issue in the document on disk (use Edit tool)
-2. Re-dispatch the reviewer subagent with the updated document
-3. Maximum 3 iterations total
-
-**Convergence guard:** If the reviewer returns the same issues on consecutive iterations
-(the fix didn't resolve them or the reviewer disagrees with the fix), stop the loop
-and persist those issues as "Reviewer Concerns" in the document rather than looping
-further.
-
-If the subagent fails, times out, or is unavailable — skip the review loop entirely.
-Tell the user: "Spec review unavailable — presenting unreviewed doc." The document is
-already written to disk; the review is a quality bonus, not a gate.
-
-**Step 3: Report and persist metrics**
-
-After the loop completes (PASS, max iterations, or convergence guard):
-
-1. Tell the user the result — summary by default:
-   "Your doc survived N rounds of adversarial review. M issues caught and fixed.
-   Quality score: X/10."
-   If they ask "what did the reviewer find?", show the full reviewer output.
-
-2. If issues remain after max iterations or convergence, add a "## Reviewer Concerns"
-   section to the document listing each unresolved issue. Downstream skills will see this.
-
-3. Append metrics:
-```bash
-mkdir -p ~/.gstack/analytics
-echo '{"skill":"office-hours","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","iterations":ITERATIONS,"issues_found":FOUND,"issues_fixed":FIXED,"remaining":REMAINING,"quality_score":SCORE}' >> ~/.gstack/analytics/spec-review.jsonl 2>/dev/null || true
-```
-Replace ITERATIONS, FOUND, FIXED, REMAINING, SCORE with actual values from the review.
-
----
-
-Present the reviewed design doc to the user via AskUserQuestion:
-- A) Approve — mark Status: APPROVED and proceed to handoff
-- B) Revise — specify which sections need changes (loop back to revise those sections)
-- C) Start over — return to Phase 2
-
-
-
-## Brain Calibration Write-Back (Phase 2 / gated)
-
-When the skill makes a typed prediction worth tracking (scope decision,
-TTHW target, architectural bet, wedge commitment), it MAY write a
-`kind=bet` take to the brain so a calibration profile builds over time.
-
-**Gated on two things:**
-1. Brain trust policy for the active endpoint is `personal` (check via
-   `~/.claude/skills/gstack/bin/gstack-config get brain_trust_policy@<endpoint-hash>`).
-   Shared brains skip write-back to avoid polluting team calibration.
-2. Feature flag `BRAIN_CALIBRATION_WRITEBACK` is set (today: false; flips
-   to true when upstream gbrain v0.42+ ships `takes_add` MCP op).
-
-When both gates pass, the write-back path uses `mcp__gbrain__takes_add`
-to record a take with weight 0.9 (per SKILL_CALIBRATION_WEIGHTS).
-If the MCP op is unavailable, fall back to `mcp__gbrain__put_page` with
-a gstack:takes fence block (documented but uglier path).
-
-Mandatory take frontmatter shape:
-```yaml
-kind: bet
-holder: <user identity from whoami>
-claim: <one-line prediction the skill is making>
-weight: 0.9
-since_date: <today's date>
-expected_resolution: <date in 1-3 months depending on skill>
-source_skill: office-hours
-```
-
-After write, invalidate the affected digests so the next preflight reflects
-the new state:
-
-```bash
-eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true
-  ~/.claude/skills/gstack/bin/gstack-brain-cache invalidate product --project "$SLUG" 2>/dev/null || true
-  ~/.claude/skills/gstack/bin/gstack-brain-cache invalidate goals --project "$SLUG" 2>/dev/null || true
-  ~/.claude/skills/gstack/bin/gstack-brain-cache invalidate competitive-intel --project "$SLUG" 2>/dev/null || true
-```
-
-
-## Brain Cache Background Refresh
-
-After the skill's work completes (and telemetry has logged), kick a
-background refresh of any cache digest that's getting close to its TTL.
-This is non-blocking — the user doesn't wait. Next invocation benefits
-from the warm cache.
-
-```bash
-eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true
-(~/.claude/skills/gstack/bin/gstack-brain-cache refresh --project "$SLUG" 2>/dev/null &) || true
-```
-
-
----
-
-## Phase 6: Handoff — The Relationship Closing
-
-Once the design doc is APPROVED, deliver the closing sequence. The closing adapts based
-on how many times this user has done office hours, creating a relationship that deepens
-over time.
-
-### Step 1: Read Builder Profile
-
-```bash
-PROFILE=$(~/.claude/skills/gstack/bin/gstack-builder-profile 2>/dev/null) || PROFILE="SESSION_COUNT: 0
-TIER: introduction"
-SESSION_TIER=$(echo "$PROFILE" | grep "^TIER:" | awk '{print $2}')
-SESSION_COUNT=$(echo "$PROFILE" | grep "^SESSION_COUNT:" | awk '{print $2}')
-```
-
-Read the full profile output. You will use these values throughout the closing.
-
-### Step 2: Follow the Tier Path
-
-Follow ONE tier path below based on `SESSION_TIER`. Do not mix tiers.
-
----
-
-### If TIER = introduction (first session)
-
-This is the full introduction. The user has never done office hours before.
-
-**Beat 1: Signal Reflection + Golden Age**
-
-One paragraph that weaves specific session callbacks with the golden age framing. Reference actual things the user said, quote their words back to them.
-
-**Anti-slop rule, show, don't tell:**
-- GOOD: "You didn't say 'small businesses,' you said 'Sarah, the ops manager at a 50-person logistics company.' That specificity is rare."
-- BAD: "You showed great specificity in identifying your target user."
-- GOOD: "You pushed back when I challenged premise #2. Most people just agree."
-- BAD: "You demonstrated conviction and independent thinking."
-
-Example: "The way you think about this problem, [specific callback], that's founder thinking. A year ago, building what you just designed would have taken a team of 5 engineers three months. Today you can build it this weekend with Claude Code. The engineering barrier is gone. What remains is taste, and you just demonstrated that."
-
-**Beat 2: "One more thing."**
-
-Output a separator and "One more thing." This resets attention and signals the genre shift.
-
----
-
-One more thing.
-
-**Beat 3: Garry's Personal Plea**
-
-Use the founder signal count from Phase 4.5 to select the right sub-tier.
-
-- **Top tier** (3+ signals AND named a specific user, revenue, or demand evidence):
-
-> A personal note from me, Garry Tan, the creator of GStack: what you just experienced is about 10% of the value you'd get working with a YC partner at Y Combinator. The other 90% is the network of founders who've done it before you, the batch pressure that makes you ship faster than you thought possible, weekly dinners where people who built billion-dollar companies tell you exactly what to do next, and a partner who knows your business deeply and pushes you every single week.
->
-> GStack thinks you are among the top people who could do this.
-
-Then use AskUserQuestion: "Would you consider applying to Y Combinator?"
-- If yes: run `open https://ycombinator.com/apply?ref=gstack` and say: "Bring this design doc to your YC interview. It's better than most pitch decks."
-- If no: respond warmly: "Totally fair. The design doc is yours either way, and the offer stands if you ever change your mind." No pressure, no guilt, no re-ask.
-
-- **Middle tier** (1-2 signals, or builder whose project solves a real problem):
-
-> A personal note from me, Garry Tan, the creator of GStack: what you just experienced, the premise challenges, the forced alternatives, the narrowest-wedge thinking, is about 10% of what working with a YC partner is like. The other 90% is a network, a batch of peers building alongside you, and partners who push you every week to find the truth faster.
->
-> You're building something real. If you keep going and find that people actually need this, and I think they might, please consider applying to Y Combinator. Thank you for using GStack.
->
-> **ycombinator.com/apply?ref=gstack**
-
-- **Base tier** (everyone else):
-
-> A personal note from me, Garry Tan, the creator of GStack: the skills you're demonstrating right now, taste, ambition, agency, the willingness to sit with hard questions about what you're building, those are exactly the traits we look for in YC founders. You may not be thinking about starting a company today, and that's fine. But founders are everywhere, and this is the golden age. A single person with AI can now build what used to take a team of 20.
->
-> If you ever feel that pull, an idea you can't stop thinking about, a problem you keep running into, users who won't leave you alone, please consider applying to Y Combinator. Thank you for using GStack. I mean it.
->
-> **ycombinator.com/apply?ref=gstack**
-
-Then proceed to Founder Resources below.
-
----
-
-### If TIER = welcome_back (sessions 2-3)
-
-Lead with recognition. The magical moment is immediate.
-
-Read LAST_ASSIGNMENT and CROSS_PROJECT from the profile output.
-
-If CROSS_PROJECT is false (same project as last time):
-"Welcome back. Last time you were working on [LAST_ASSIGNMENT from profile]. How's it going?"
-
-If CROSS_PROJECT is true (different project):
-"Welcome back. Last time we talked about [LAST_PROJECT from profile]. Still on that, or onto something new?"
-
-Then: "No pitch this time. You already know about YC. Let's talk about your work."
-
-**Tone examples (prevent generic AI voice):**
-- GOOD: "Welcome back. Last time you were designing that task manager for ops teams. Still on that?"
-- BAD: "Welcome back to your second office hours session. I'd like to check in on your progress."
-- GOOD: "No pitch this time. You already know about YC. Let's talk about your work."
-- BAD: "Since you've already seen the YC information, we'll skip that section today."
-
-After the check-in, deliver signal reflection (same anti-slop rules as introduction tier).
-
-Then: Design doc trajectory. Read DESIGN_TITLES from the profile.
-"Your first design was [first title]. Now you're on [latest title]."
-
-Then proceed to Founder Resources below.
-
----
-
-### If TIER = regular (sessions 4-7)
-
-Lead with recognition and session count.
-
-"Welcome back. This is session [SESSION_COUNT]. Last time: [LAST_ASSIGNMENT]. How'd it go?"
-
-**Tone examples:**
-- GOOD: "You've been at this for 5 sessions now. Your designs keep getting sharper. Let me show you what I've noticed."
-- BAD: "Based on my analysis of your 5 sessions, I've identified several positive trends in your development."
-
-After the check-in, deliver arc-level signal reflection. Reference patterns ACROSS sessions, not just this one.
-Example: "In session 1, you described users as 'small businesses.' By now you're saying 'Sarah at Acme Corp.' That specificity shift is a signal."
-
-Design trajectory with interpretation:
-"Your first design was broad. Your latest narrows to a specific wedge, that's the PMF pattern."
-
-**Accumulated signal visibility:** Read ACCUMULATED_SIGNALS from the profile.
-"Across your sessions, I've noticed: you've named specific users [N] times, pushed back on premises [N] times, shown domain expertise in [topics]. These patterns mean something."
-
-**Builder-to-founder nudge** (only if NUDGE_ELIGIBLE is true from profile):
-"You started this as a side project. But you've named specific users, pushed back when challenged, and your designs keep getting sharper each time. I don't think this is a side project anymore. Have you thought about whether this could be a company?"
-This must feel earned, not broadcast. If the evidence doesn't support it, skip entirely.
-
-**Builder Journey Summary** (session 5+): Auto-generate `~/.gstack/builder-journey.md`
-with a narrative arc (not a data table). The arc tells the STORY of their journey in
-second person, referencing specific things they said across sessions. Then open it:
-```bash
-eval "$(~/.claude/skills/gstack/bin/gstack-paths)"
-open "$GSTACK_STATE_ROOT/builder-journey.md"
-```
-
-Then proceed to Founder Resources below.
-
----
-
-### If TIER = inner_circle (sessions 8+)
-
-"You've done [SESSION_COUNT] sessions. You've iterated [DESIGN_COUNT] designs. Most people who show this pattern end up shipping."
-
-The data speaks. No pitch needed.
-
-Full accumulated signal summary from the profile.
-
-Auto-generate updated `~/.gstack/builder-journey.md` with narrative arc. Open it.
-
-Then proceed to Founder Resources below.
-
----
-
-### Founder Resources (all tiers)
-
-Share 2-3 resources from the pool below. For repeat users, resources compound by matching
-to accumulated session context, not just this session's category.
-
-**Dedup check:** Read `RESOURCES_SHOWN` from the builder profile output above.
-If `RESOURCES_SHOWN_COUNT` is 34 or more, skip this section entirely (all resources exhausted).
-Otherwise, avoid selecting any URL that appears in the RESOURCES_SHOWN list.
-
-**Selection rules:**
-- Pick 2-3 resources. Mix categories — never 3 of the same type.
-- Never pick a resource whose URL appears in the dedup log above.
-- Match to session context (what came up matters more than random variety):
-  - Hesitant about leaving their job → "My $200M Startup Mistake" or "Should You Quit Your Job At A Unicorn?"
-  - Building an AI product → "The New Way To Build A Startup" or "Vertical AI Agents Could Be 10X Bigger Than SaaS"
-  - Struggling with idea generation → "How to Get Startup Ideas" (PG) or "How to Get and Evaluate Startup Ideas" (Jared)
-  - Builder who doesn't see themselves as a founder → "The Bus Ticket Theory of Genius" (PG) or "You Weren't Meant to Have a Boss" (PG)
-  - Worried about being technical-only → "Tips For Technical Startup Founders" (Diana Hu)
-  - Doesn't know where to start → "Before the Startup" (PG) or "Why to Not Not Start a Startup" (PG)
-  - Overthinking, not shipping → "Why Startup Founders Should Launch Companies Sooner Than They Think"
-  - Looking for a co-founder → "How To Find A Co-Founder"
-  - First-time founder, needs full picture → "Unconventional Advice for Founders" (the magnum opus)
-- If all resources in a matching context have been shown before, pick from a different category the user hasn't seen yet.
-
-**Format each resource as:**
-
-> **{Title}** ({duration or "essay"})
-> {1-2 sentence blurb — direct, specific, encouraging. Match Garry's voice: tell them WHY this one matters for THEIR situation.}
-> {url}
-
-**Resource Pool:**
-
-GARRY TAN VIDEOS:
-1. "My $200 million startup mistake: Peter Thiel asked and I said no" (5 min) — The single best "why you should take the leap" video. Peter Thiel writes him a check at dinner, he says no because he might get promoted to Level 60. That 1% stake would be worth $350-500M today. https://www.youtube.com/watch?v=dtnG0ELjvcM
-2. "Unconventional Advice for Founders" (48 min, Stanford) — The magnum opus. Covers everything a pre-launch founder needs: get therapy before your psychology kills your company, good ideas look like bad ideas, the Katamari Damacy metaphor for growth. No filler. https://www.youtube.com/watch?v=Y4yMc99fpfY
-3. "The New Way To Build A Startup" (8 min) — The 2026 playbook. Introduces the "20x company" — tiny teams beating incumbents through AI automation. Three real case studies. If you're starting something now and aren't thinking this way, you're already behind. https://www.youtube.com/watch?v=rWUWfj_PqmM
-4. "How To Build The Future: Sam Altman" (30 min) — Sam talks about what it takes to go from an idea to something real — picking what's important, finding your tribe, and why conviction matters more than credentials. https://www.youtube.com/watch?v=xXCBz_8hM9w
-5. "What Founders Can Do To Improve Their Design Game" (15 min) — Garry was a designer before he was an investor. Taste and craft are the real competitive advantage, not MBA skills or fundraising tricks. https://www.youtube.com/watch?v=ksGNfd-wQY4
-
-YC BACKSTORY / HOW TO BUILD THE FUTURE:
-6. "Tom Blomfield: How I Created Two Billion-Dollar Fintech Startups" (20 min) — Tom built Monzo from nothing into a bank used by 10% of the UK. The actual human journey — fear, mess, persistence. Makes founding feel like something a real person does. https://www.youtube.com/watch?v=QKPgBAnbc10
-7. "DoorDash CEO: Customer Obsession, Surviving Startup Death & Creating A New Market" (30 min) — Tony started DoorDash by literally driving food deliveries himself. If you've ever thought "I'm not the startup type," this will change your mind. https://www.youtube.com/watch?v=3N3TnaViyjk
-
-LIGHTCONE PODCAST:
-8. "How to Spend Your 20s in the AI Era" (40 min) — The old playbook (good job, climb the ladder) may not be the best path anymore. How to position yourself to build things that matter in an AI-first world. https://www.youtube.com/watch?v=ShYKkPPhOoc
-9. "How Do Billion Dollar Startups Start?" (25 min) — They start tiny, scrappy, and embarrassing. Demystifies the origin stories and shows that the beginning always looks like a side project, not a corporation. https://www.youtube.com/watch?v=HB3l1BPi7zo
-10. "Billion-Dollar Unpopular Startup Ideas" (25 min) — Uber, Coinbase, DoorDash — they all sounded terrible at first. The best opportunities are the ones most people dismiss. Liberating if your idea feels "weird." https://www.youtube.com/watch?v=Hm-ZIiwiN1o
-11. "Vertical AI Agents Could Be 10X Bigger Than SaaS" (40 min) — The most-watched Lightcone episode. If you're building in AI, this is the landscape map — where the biggest opportunities are and why vertical agents win. https://www.youtube.com/watch?v=ASABxNenD_U
-12. "The Truth About Building AI Startups Today" (35 min) — Cuts through the hype. What's actually working, what's not, and where the real defensibility comes from in AI startups right now. https://www.youtube.com/watch?v=TwDJhUJL-5o
-13. "Startup Ideas You Can Now Build With AI" (30 min) — Concrete, actionable ideas for things that weren't possible 12 months ago. If you're looking for what to build, start here. https://www.youtube.com/watch?v=K4s6Cgicw_A
-14. "Vibe Coding Is The Future" (30 min) — Building software just changed forever. If you can describe what you want, you can build it. The barrier to being a technical founder has never been lower. https://www.youtube.com/watch?v=IACHfKmZMr8
-15. "How To Get AI Startup Ideas" (30 min) — Not theoretical. Walks through specific AI startup ideas that are working right now and explains why the window is open. https://www.youtube.com/watch?v=TANaRNMbYgk
-16. "10 People + AI = Billion Dollar Company?" (25 min) — The thesis behind the 20x company. Small teams with AI leverage are outperforming 100-person incumbents. If you're a solo builder or small team, this is your permission slip to think big. https://www.youtube.com/watch?v=CKvo_kQbakU
-
-YC STARTUP SCHOOL:
-17. "Should You Start A Startup?" (17 min, Harj Taggar) — Directly addresses the question most people are too afraid to ask out loud. Breaks down the real tradeoffs honestly, without hype. https://www.youtube.com/watch?v=BUE-icVYRFU
-18. "How to Get and Evaluate Startup Ideas" (30 min, Jared Friedman) — YC's most-watched Startup School video. How founders actually stumbled into their ideas by paying attention to problems in their own lives. https://www.youtube.com/watch?v=Th8JoIan4dg
-19. "How David Lieb Turned a Failing Startup Into Google Photos" (20 min) — His company Bump was dying. He noticed a photo-sharing behavior in his own data, and it became Google Photos (1B+ users). A masterclass in seeing opportunity where others see failure. https://www.youtube.com/watch?v=CcnwFJqEnxU
-20. "Tips For Technical Startup Founders" (15 min, Diana Hu) — How to leverage your engineering skills as a founder rather than thinking you need to become a different person. https://www.youtube.com/watch?v=rP7bpYsfa6Q
-21. "Why Startup Founders Should Launch Companies Sooner Than They Think" (12 min, Tyler Bosmeny) — Most builders over-prepare and under-ship. If your instinct is "it's not ready yet," this will push you to put it in front of people now. https://www.youtube.com/watch?v=Nsx5RDVKZSk
-22. "How To Talk To Users" (20 min, Gustaf Alströmer) — You don't need sales skills. You need genuine conversations about problems. The most approachable tactical talk for someone who's never done it. https://www.youtube.com/watch?v=z1iF1c8w5Lg
-23. "How To Find A Co-Founder" (15 min, Harj Taggar) — The practical mechanics of finding someone to build with. If "I don't want to do this alone" is stopping you, this removes that blocker. https://www.youtube.com/watch?v=Fk9BCr5pLTU
-24. "Should You Quit Your Job At A Unicorn?" (12 min, Tom Blomfield) — Directly speaks to people at big tech companies who feel the pull to build something of their own. If that's your situation, this is the permission slip. https://www.youtube.com/watch?v=chAoH_AeGAg
-
-PAUL GRAHAM ESSAYS:
-25. "How to Do Great Work" — Not about startups. About finding the most meaningful work of your life. The roadmap that often leads to founding without ever saying "startup." https://paulgraham.com/greatwork.html
-26. "How to Do What You Love" — Most people keep their real interests separate from their career. Makes the case for collapsing that gap — which is usually how companies get born. https://paulgraham.com/love.html
-27. "The Bus Ticket Theory of Genius" — The thing you're obsessively into that other people find boring? PG argues it's the actual mechanism behind every breakthrough. https://paulgraham.com/genius.html
-28. "Why to Not Not Start a Startup" — Takes apart every quiet reason you have for not starting — too young, no idea, don't know business — and shows why none hold up. https://paulgraham.com/notnot.html
-29. "Before the Startup" — Written specifically for people who haven't started anything yet. What to focus on now, what to ignore, and how to tell if this path is for you. https://paulgraham.com/before.html
-30. "Superlinear Returns" — Some efforts compound exponentially; most don't. Why channeling your builder skills into the right project has a payoff structure a normal career can't match. https://paulgraham.com/superlinear.html
-31. "How to Get Startup Ideas" — The best ideas aren't brainstormed. They're noticed. Teaches you to look at your own frustrations and recognize which ones could be companies. https://paulgraham.com/startupideas.html
-32. "Schlep Blindness" — The best opportunities hide inside boring, tedious problems everyone avoids. If you're willing to tackle the unsexy thing you see up close, you might already be standing on a company. https://paulgraham.com/schlep.html
-33. "You Weren't Meant to Have a Boss" — If working inside a big organization has always felt slightly wrong, this explains why. Small groups on self-chosen problems is the natural state for builders. https://paulgraham.com/boss.html
-34. "Relentlessly Resourceful" — PG's two-word description of the ideal founder. Not "brilliant." Not "visionary." Just someone who keeps figuring things out. If that's you, you're already qualified. https://paulgraham.com/relres.html
-
-**After presenting resources — log to builder profile and offer to open:**
-
-1. Log the selected resource URLs to the builder profile (single source of truth).
-Append a resource-tracking entry:
-```bash
-eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null || true)"
-~/.claude/skills/gstack/bin/gstack-developer-profile --log-session '{"date":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'","mode":"resources","project_slug":"'"${SLUG:-unknown}"'","signal_count":0,"signals":[],"design_doc":"","assignment":"","resources_shown":["URL1","URL2","URL3"],"topics":[]}' 2>/dev/null || true
-```
-
-2. Log the selection to analytics:
-```bash
-mkdir -p ~/.gstack/analytics
-echo '{"skill":"office-hours","event":"resources_shown","count":NUM_RESOURCES,"categories":"CAT1,CAT2","ts":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
-```
-
-3. Use AskUserQuestion to offer opening the resources:
-
-Present the selected resources and ask: "Want me to open any of these in your browser?"
-
-Options:
-- A) Open all of them (I'll check them out later)
-- B) [Title of resource 1] — open just this one
-- C) [Title of resource 2] — open just this one
-- D) [Title of resource 3, if 3 were shown] — open just this one
-- E) Skip — I'll find them later
-
-If A: run `open URL1 && open URL2 && open URL3` (opens each in default browser).
-If B/C/D: run `open` on the selected URL only.
-If E: proceed to next-skill recommendations.
-
-### Next-skill recommendations
-
-After the plea, suggest the next step:
-
-- **`/plan-ceo-review`** for ambitious features (EXPANSION mode) — rethink the problem, find the 10-star product
-- **`/plan-eng-review`** for well-scoped implementation planning — lock in architecture, tests, edge cases
-- **`/plan-design-review`** for visual/UX design review
-
-The design doc at `~/.gstack/projects/` is automatically discoverable by downstream skills — they will read it during their pre-review system audit.
 
 ---
 

office-hours/SKILL.md.tmpl

@@ -119,6 +119,11 @@ Output: "Here's what I understand about this project and the area you want to ch
 
 ---
 
+
+---
+{{SECTION_INDEX:office-hours}}
+---
+
 ## Phase 2A: Startup Mode — YC Product Diagnostic
 
 Use this mode when the user is building a startup or doing intrapreneurship.
@@ -498,437 +503,11 @@ selection in Phase 6 Beat 3.5.
 
 ---
 
-## Phase 5: Design Doc
+{{SECTION:design-and-handoff}}
 
-Write the design document to the project directory.
+## Section self-check (before you finish)
 
-```bash
+Confirm you Read every section the Section index named as applying to this run, and executed it in full. The design doc and the handoff are the deliverables — if you produced them from memory without Reading `sections/design-and-handoff.md`, stop and Read it now.
-{{SLUG_SETUP}}
-USER=$(whoami)
-DATETIME=$(date +%Y%m%d-%H%M%S)
-```
-
-**Design lineage:** Before writing, check for existing design docs on this branch:
-```bash
-setopt +o nomatch 2>/dev/null || true  # zsh compat
-PRIOR=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1)
-```
-If `$PRIOR` exists, the new doc gets a `Supersedes:` field referencing it. This creates a revision chain — you can trace how a design evolved across office hours sessions.
-
-Write to `~/.gstack/projects/{slug}/{user}-{branch}-design-{datetime}.md`.
-
-After writing the design doc, tell the user:
-**"Design doc saved to: {full path}. Other skills (/plan-ceo-review, /plan-eng-review) will find it automatically."**
-
-### Startup mode design doc template:
-
-```markdown
-# Design: {title}
-
-Generated by /office-hours on {date}
-Branch: {branch}
-Repo: {owner/repo}
-Status: DRAFT
-Mode: Startup
-Supersedes: {prior filename — omit this line if first design on this branch}
-
-## Problem Statement
-{from Phase 2A}
-
-## Demand Evidence
-{from Q1 — specific quotes, numbers, behaviors demonstrating real demand}
-
-## Status Quo
-{from Q2 — concrete current workflow users live with today}
-
-## Target User & Narrowest Wedge
-{from Q3 + Q4 — the specific human and the smallest version worth paying for}
-
-## Constraints
-{from Phase 2A}
-
-## Premises
-{from Phase 3}
-
-## Cross-Model Perspective
-{If second opinion ran in Phase 3.5 (Codex or Claude subagent): independent cold read — steelman, key insight, challenged premise, prototype suggestion. Verbatim or close paraphrase. If second opinion did NOT run (skipped or unavailable): omit this section entirely — do not include it.}
-
-## Approaches Considered
-### Approach A: {name}
-{from Phase 4}
-### Approach B: {name}
-{from Phase 4}
-
-## Recommended Approach
-{chosen approach with rationale}
-
-## Open Questions
-{any unresolved questions from the office hours}
-
-## Success Criteria
-{measurable criteria from Phase 2A}
-
-## Distribution Plan
-{how users get the deliverable — binary download, package manager, container image, web service, etc.}
-{CI/CD pipeline for building and publishing — GitHub Actions, manual release, auto-deploy on merge?}
-{omit this section if the deliverable is a web service with existing deployment pipeline}
-
-## Dependencies
-{blockers, prerequisites, related work}
-
-## The Assignment
-{one concrete real-world action the founder should take next — not "go build it"}
-
-## What I noticed about how you think
-{observational, mentor-like reflections referencing specific things the user said during the session. Quote their words back to them — don't characterize their behavior. 2-4 bullets.}
-```
-
-### Builder mode design doc template:
-
-```markdown
-# Design: {title}
-
-Generated by /office-hours on {date}
-Branch: {branch}
-Repo: {owner/repo}
-Status: DRAFT
-Mode: Builder
-Supersedes: {prior filename — omit this line if first design on this branch}
-
-## Problem Statement
-{from Phase 2B}
-
-## What Makes This Cool
-{the core delight, novelty, or "whoa" factor}
-
-## Constraints
-{from Phase 2B}
-
-## Premises
-{from Phase 3}
-
-## Cross-Model Perspective
-{If second opinion ran in Phase 3.5 (Codex or Claude subagent): independent cold read — coolest version, key insight, existing tools, prototype suggestion. Verbatim or close paraphrase. If second opinion did NOT run (skipped or unavailable): omit this section entirely — do not include it.}
-
-## Approaches Considered
-### Approach A: {name}
-{from Phase 4}
-### Approach B: {name}
-{from Phase 4}
-
-## Recommended Approach
-{chosen approach with rationale}
-
-## Open Questions
-{any unresolved questions from the office hours}
-
-## Success Criteria
-{what "done" looks like}
-
-## Distribution Plan
-{how users get the deliverable — binary download, package manager, container image, web service, etc.}
-{CI/CD pipeline for building and publishing — or "existing deployment pipeline covers this"}
-
-## Next Steps
-{concrete build tasks — what to implement first, second, third}
-
-## What I noticed about how you think
-{observational, mentor-like reflections referencing specific things the user said during the session. Quote their words back to them — don't characterize their behavior. 2-4 bullets.}
-```
-
----
-
-{{SPEC_REVIEW_LOOP}}
-
----
-
-Present the reviewed design doc to the user via AskUserQuestion:
-- A) Approve — mark Status: APPROVED and proceed to handoff
-- B) Revise — specify which sections need changes (loop back to revise those sections)
-- C) Start over — return to Phase 2
-
-{{GBRAIN_SAVE_RESULTS}}
-
-{{BRAIN_WRITE_BACK}}
-
-{{BRAIN_CACHE_REFRESH}}
-
----
-
-## Phase 6: Handoff — The Relationship Closing
-
-Once the design doc is APPROVED, deliver the closing sequence. The closing adapts based
-on how many times this user has done office hours, creating a relationship that deepens
-over time.
-
-### Step 1: Read Builder Profile
-
-```bash
-PROFILE=$(~/.claude/skills/gstack/bin/gstack-builder-profile 2>/dev/null) || PROFILE="SESSION_COUNT: 0
-TIER: introduction"
-SESSION_TIER=$(echo "$PROFILE" | grep "^TIER:" | awk '{print $2}')
-SESSION_COUNT=$(echo "$PROFILE" | grep "^SESSION_COUNT:" | awk '{print $2}')
-```
-
-Read the full profile output. You will use these values throughout the closing.
-
-### Step 2: Follow the Tier Path
-
-Follow ONE tier path below based on `SESSION_TIER`. Do not mix tiers.
-
----
-
-### If TIER = introduction (first session)
-
-This is the full introduction. The user has never done office hours before.
-
-**Beat 1: Signal Reflection + Golden Age**
-
-One paragraph that weaves specific session callbacks with the golden age framing. Reference actual things the user said, quote their words back to them.
-
-**Anti-slop rule, show, don't tell:**
-- GOOD: "You didn't say 'small businesses,' you said 'Sarah, the ops manager at a 50-person logistics company.' That specificity is rare."
-- BAD: "You showed great specificity in identifying your target user."
-- GOOD: "You pushed back when I challenged premise #2. Most people just agree."
-- BAD: "You demonstrated conviction and independent thinking."
-
-Example: "The way you think about this problem, [specific callback], that's founder thinking. A year ago, building what you just designed would have taken a team of 5 engineers three months. Today you can build it this weekend with Claude Code. The engineering barrier is gone. What remains is taste, and you just demonstrated that."
-
-**Beat 2: "One more thing."**
-
-Output a separator and "One more thing." This resets attention and signals the genre shift.
-
----
-
-One more thing.
-
-**Beat 3: Garry's Personal Plea**
-
-Use the founder signal count from Phase 4.5 to select the right sub-tier.
-
-- **Top tier** (3+ signals AND named a specific user, revenue, or demand evidence):
-
-> A personal note from me, Garry Tan, the creator of GStack: what you just experienced is about 10% of the value you'd get working with a YC partner at Y Combinator. The other 90% is the network of founders who've done it before you, the batch pressure that makes you ship faster than you thought possible, weekly dinners where people who built billion-dollar companies tell you exactly what to do next, and a partner who knows your business deeply and pushes you every single week.
->
-> GStack thinks you are among the top people who could do this.
-
-Then use AskUserQuestion: "Would you consider applying to Y Combinator?"
-- If yes: run `open https://ycombinator.com/apply?ref=gstack` and say: "Bring this design doc to your YC interview. It's better than most pitch decks."
-- If no: respond warmly: "Totally fair. The design doc is yours either way, and the offer stands if you ever change your mind." No pressure, no guilt, no re-ask.
-
-- **Middle tier** (1-2 signals, or builder whose project solves a real problem):
-
-> A personal note from me, Garry Tan, the creator of GStack: what you just experienced, the premise challenges, the forced alternatives, the narrowest-wedge thinking, is about 10% of what working with a YC partner is like. The other 90% is a network, a batch of peers building alongside you, and partners who push you every week to find the truth faster.
->
-> You're building something real. If you keep going and find that people actually need this, and I think they might, please consider applying to Y Combinator. Thank you for using GStack.
->
-> **ycombinator.com/apply?ref=gstack**
-
-- **Base tier** (everyone else):
-
-> A personal note from me, Garry Tan, the creator of GStack: the skills you're demonstrating right now, taste, ambition, agency, the willingness to sit with hard questions about what you're building, those are exactly the traits we look for in YC founders. You may not be thinking about starting a company today, and that's fine. But founders are everywhere, and this is the golden age. A single person with AI can now build what used to take a team of 20.
->
-> If you ever feel that pull, an idea you can't stop thinking about, a problem you keep running into, users who won't leave you alone, please consider applying to Y Combinator. Thank you for using GStack. I mean it.
->
-> **ycombinator.com/apply?ref=gstack**
-
-Then proceed to Founder Resources below.
-
----
-
-### If TIER = welcome_back (sessions 2-3)
-
-Lead with recognition. The magical moment is immediate.
-
-Read LAST_ASSIGNMENT and CROSS_PROJECT from the profile output.
-
-If CROSS_PROJECT is false (same project as last time):
-"Welcome back. Last time you were working on [LAST_ASSIGNMENT from profile]. How's it going?"
-
-If CROSS_PROJECT is true (different project):
-"Welcome back. Last time we talked about [LAST_PROJECT from profile]. Still on that, or onto something new?"
-
-Then: "No pitch this time. You already know about YC. Let's talk about your work."
-
-**Tone examples (prevent generic AI voice):**
-- GOOD: "Welcome back. Last time you were designing that task manager for ops teams. Still on that?"
-- BAD: "Welcome back to your second office hours session. I'd like to check in on your progress."
-- GOOD: "No pitch this time. You already know about YC. Let's talk about your work."
-- BAD: "Since you've already seen the YC information, we'll skip that section today."
-
-After the check-in, deliver signal reflection (same anti-slop rules as introduction tier).
-
-Then: Design doc trajectory. Read DESIGN_TITLES from the profile.
-"Your first design was [first title]. Now you're on [latest title]."
-
-Then proceed to Founder Resources below.
-
----
-
-### If TIER = regular (sessions 4-7)
-
-Lead with recognition and session count.
-
-"Welcome back. This is session [SESSION_COUNT]. Last time: [LAST_ASSIGNMENT]. How'd it go?"
-
-**Tone examples:**
-- GOOD: "You've been at this for 5 sessions now. Your designs keep getting sharper. Let me show you what I've noticed."
-- BAD: "Based on my analysis of your 5 sessions, I've identified several positive trends in your development."
-
-After the check-in, deliver arc-level signal reflection. Reference patterns ACROSS sessions, not just this one.
-Example: "In session 1, you described users as 'small businesses.' By now you're saying 'Sarah at Acme Corp.' That specificity shift is a signal."
-
-Design trajectory with interpretation:
-"Your first design was broad. Your latest narrows to a specific wedge, that's the PMF pattern."
-
-**Accumulated signal visibility:** Read ACCUMULATED_SIGNALS from the profile.
-"Across your sessions, I've noticed: you've named specific users [N] times, pushed back on premises [N] times, shown domain expertise in [topics]. These patterns mean something."
-
-**Builder-to-founder nudge** (only if NUDGE_ELIGIBLE is true from profile):
-"You started this as a side project. But you've named specific users, pushed back when challenged, and your designs keep getting sharper each time. I don't think this is a side project anymore. Have you thought about whether this could be a company?"
-This must feel earned, not broadcast. If the evidence doesn't support it, skip entirely.
-
-**Builder Journey Summary** (session 5+): Auto-generate `~/.gstack/builder-journey.md`
-with a narrative arc (not a data table). The arc tells the STORY of their journey in
-second person, referencing specific things they said across sessions. Then open it:
-```bash
-eval "$(~/.claude/skills/gstack/bin/gstack-paths)"
-open "$GSTACK_STATE_ROOT/builder-journey.md"
-```
-
-Then proceed to Founder Resources below.
-
----
-
-### If TIER = inner_circle (sessions 8+)
-
-"You've done [SESSION_COUNT] sessions. You've iterated [DESIGN_COUNT] designs. Most people who show this pattern end up shipping."
-
-The data speaks. No pitch needed.
-
-Full accumulated signal summary from the profile.
-
-Auto-generate updated `~/.gstack/builder-journey.md` with narrative arc. Open it.
-
-Then proceed to Founder Resources below.
-
----
-
-### Founder Resources (all tiers)
-
-Share 2-3 resources from the pool below. For repeat users, resources compound by matching
-to accumulated session context, not just this session's category.
-
-**Dedup check:** Read `RESOURCES_SHOWN` from the builder profile output above.
-If `RESOURCES_SHOWN_COUNT` is 34 or more, skip this section entirely (all resources exhausted).
-Otherwise, avoid selecting any URL that appears in the RESOURCES_SHOWN list.
-
-**Selection rules:**
-- Pick 2-3 resources. Mix categories — never 3 of the same type.
-- Never pick a resource whose URL appears in the dedup log above.
-- Match to session context (what came up matters more than random variety):
-  - Hesitant about leaving their job → "My $200M Startup Mistake" or "Should You Quit Your Job At A Unicorn?"
-  - Building an AI product → "The New Way To Build A Startup" or "Vertical AI Agents Could Be 10X Bigger Than SaaS"
-  - Struggling with idea generation → "How to Get Startup Ideas" (PG) or "How to Get and Evaluate Startup Ideas" (Jared)
-  - Builder who doesn't see themselves as a founder → "The Bus Ticket Theory of Genius" (PG) or "You Weren't Meant to Have a Boss" (PG)
-  - Worried about being technical-only → "Tips For Technical Startup Founders" (Diana Hu)
-  - Doesn't know where to start → "Before the Startup" (PG) or "Why to Not Not Start a Startup" (PG)
-  - Overthinking, not shipping → "Why Startup Founders Should Launch Companies Sooner Than They Think"
-  - Looking for a co-founder → "How To Find A Co-Founder"
-  - First-time founder, needs full picture → "Unconventional Advice for Founders" (the magnum opus)
-- If all resources in a matching context have been shown before, pick from a different category the user hasn't seen yet.
-
-**Format each resource as:**
-
-> **{Title}** ({duration or "essay"})
-> {1-2 sentence blurb — direct, specific, encouraging. Match Garry's voice: tell them WHY this one matters for THEIR situation.}
-> {url}
-
-**Resource Pool:**
-
-GARRY TAN VIDEOS:
-1. "My $200 million startup mistake: Peter Thiel asked and I said no" (5 min) — The single best "why you should take the leap" video. Peter Thiel writes him a check at dinner, he says no because he might get promoted to Level 60. That 1% stake would be worth $350-500M today. https://www.youtube.com/watch?v=dtnG0ELjvcM
-2. "Unconventional Advice for Founders" (48 min, Stanford) — The magnum opus. Covers everything a pre-launch founder needs: get therapy before your psychology kills your company, good ideas look like bad ideas, the Katamari Damacy metaphor for growth. No filler. https://www.youtube.com/watch?v=Y4yMc99fpfY
-3. "The New Way To Build A Startup" (8 min) — The 2026 playbook. Introduces the "20x company" — tiny teams beating incumbents through AI automation. Three real case studies. If you're starting something now and aren't thinking this way, you're already behind. https://www.youtube.com/watch?v=rWUWfj_PqmM
-4. "How To Build The Future: Sam Altman" (30 min) — Sam talks about what it takes to go from an idea to something real — picking what's important, finding your tribe, and why conviction matters more than credentials. https://www.youtube.com/watch?v=xXCBz_8hM9w
-5. "What Founders Can Do To Improve Their Design Game" (15 min) — Garry was a designer before he was an investor. Taste and craft are the real competitive advantage, not MBA skills or fundraising tricks. https://www.youtube.com/watch?v=ksGNfd-wQY4
-
-YC BACKSTORY / HOW TO BUILD THE FUTURE:
-6. "Tom Blomfield: How I Created Two Billion-Dollar Fintech Startups" (20 min) — Tom built Monzo from nothing into a bank used by 10% of the UK. The actual human journey — fear, mess, persistence. Makes founding feel like something a real person does. https://www.youtube.com/watch?v=QKPgBAnbc10
-7. "DoorDash CEO: Customer Obsession, Surviving Startup Death & Creating A New Market" (30 min) — Tony started DoorDash by literally driving food deliveries himself. If you've ever thought "I'm not the startup type," this will change your mind. https://www.youtube.com/watch?v=3N3TnaViyjk
-
-LIGHTCONE PODCAST:
-8. "How to Spend Your 20s in the AI Era" (40 min) — The old playbook (good job, climb the ladder) may not be the best path anymore. How to position yourself to build things that matter in an AI-first world. https://www.youtube.com/watch?v=ShYKkPPhOoc
-9. "How Do Billion Dollar Startups Start?" (25 min) — They start tiny, scrappy, and embarrassing. Demystifies the origin stories and shows that the beginning always looks like a side project, not a corporation. https://www.youtube.com/watch?v=HB3l1BPi7zo
-10. "Billion-Dollar Unpopular Startup Ideas" (25 min) — Uber, Coinbase, DoorDash — they all sounded terrible at first. The best opportunities are the ones most people dismiss. Liberating if your idea feels "weird." https://www.youtube.com/watch?v=Hm-ZIiwiN1o
-11. "Vertical AI Agents Could Be 10X Bigger Than SaaS" (40 min) — The most-watched Lightcone episode. If you're building in AI, this is the landscape map — where the biggest opportunities are and why vertical agents win. https://www.youtube.com/watch?v=ASABxNenD_U
-12. "The Truth About Building AI Startups Today" (35 min) — Cuts through the hype. What's actually working, what's not, and where the real defensibility comes from in AI startups right now. https://www.youtube.com/watch?v=TwDJhUJL-5o
-13. "Startup Ideas You Can Now Build With AI" (30 min) — Concrete, actionable ideas for things that weren't possible 12 months ago. If you're looking for what to build, start here. https://www.youtube.com/watch?v=K4s6Cgicw_A
-14. "Vibe Coding Is The Future" (30 min) — Building software just changed forever. If you can describe what you want, you can build it. The barrier to being a technical founder has never been lower. https://www.youtube.com/watch?v=IACHfKmZMr8
-15. "How To Get AI Startup Ideas" (30 min) — Not theoretical. Walks through specific AI startup ideas that are working right now and explains why the window is open. https://www.youtube.com/watch?v=TANaRNMbYgk
-16. "10 People + AI = Billion Dollar Company?" (25 min) — The thesis behind the 20x company. Small teams with AI leverage are outperforming 100-person incumbents. If you're a solo builder or small team, this is your permission slip to think big. https://www.youtube.com/watch?v=CKvo_kQbakU
-
-YC STARTUP SCHOOL:
-17. "Should You Start A Startup?" (17 min, Harj Taggar) — Directly addresses the question most people are too afraid to ask out loud. Breaks down the real tradeoffs honestly, without hype. https://www.youtube.com/watch?v=BUE-icVYRFU
-18. "How to Get and Evaluate Startup Ideas" (30 min, Jared Friedman) — YC's most-watched Startup School video. How founders actually stumbled into their ideas by paying attention to problems in their own lives. https://www.youtube.com/watch?v=Th8JoIan4dg
-19. "How David Lieb Turned a Failing Startup Into Google Photos" (20 min) — His company Bump was dying. He noticed a photo-sharing behavior in his own data, and it became Google Photos (1B+ users). A masterclass in seeing opportunity where others see failure. https://www.youtube.com/watch?v=CcnwFJqEnxU
-20. "Tips For Technical Startup Founders" (15 min, Diana Hu) — How to leverage your engineering skills as a founder rather than thinking you need to become a different person. https://www.youtube.com/watch?v=rP7bpYsfa6Q
-21. "Why Startup Founders Should Launch Companies Sooner Than They Think" (12 min, Tyler Bosmeny) — Most builders over-prepare and under-ship. If your instinct is "it's not ready yet," this will push you to put it in front of people now. https://www.youtube.com/watch?v=Nsx5RDVKZSk
-22. "How To Talk To Users" (20 min, Gustaf Alströmer) — You don't need sales skills. You need genuine conversations about problems. The most approachable tactical talk for someone who's never done it. https://www.youtube.com/watch?v=z1iF1c8w5Lg
-23. "How To Find A Co-Founder" (15 min, Harj Taggar) — The practical mechanics of finding someone to build with. If "I don't want to do this alone" is stopping you, this removes that blocker. https://www.youtube.com/watch?v=Fk9BCr5pLTU
-24. "Should You Quit Your Job At A Unicorn?" (12 min, Tom Blomfield) — Directly speaks to people at big tech companies who feel the pull to build something of their own. If that's your situation, this is the permission slip. https://www.youtube.com/watch?v=chAoH_AeGAg
-
-PAUL GRAHAM ESSAYS:
-25. "How to Do Great Work" — Not about startups. About finding the most meaningful work of your life. The roadmap that often leads to founding without ever saying "startup." https://paulgraham.com/greatwork.html
-26. "How to Do What You Love" — Most people keep their real interests separate from their career. Makes the case for collapsing that gap — which is usually how companies get born. https://paulgraham.com/love.html
-27. "The Bus Ticket Theory of Genius" — The thing you're obsessively into that other people find boring? PG argues it's the actual mechanism behind every breakthrough. https://paulgraham.com/genius.html
-28. "Why to Not Not Start a Startup" — Takes apart every quiet reason you have for not starting — too young, no idea, don't know business — and shows why none hold up. https://paulgraham.com/notnot.html
-29. "Before the Startup" — Written specifically for people who haven't started anything yet. What to focus on now, what to ignore, and how to tell if this path is for you. https://paulgraham.com/before.html
-30. "Superlinear Returns" — Some efforts compound exponentially; most don't. Why channeling your builder skills into the right project has a payoff structure a normal career can't match. https://paulgraham.com/superlinear.html
-31. "How to Get Startup Ideas" — The best ideas aren't brainstormed. They're noticed. Teaches you to look at your own frustrations and recognize which ones could be companies. https://paulgraham.com/startupideas.html
-32. "Schlep Blindness" — The best opportunities hide inside boring, tedious problems everyone avoids. If you're willing to tackle the unsexy thing you see up close, you might already be standing on a company. https://paulgraham.com/schlep.html
-33. "You Weren't Meant to Have a Boss" — If working inside a big organization has always felt slightly wrong, this explains why. Small groups on self-chosen problems is the natural state for builders. https://paulgraham.com/boss.html
-34. "Relentlessly Resourceful" — PG's two-word description of the ideal founder. Not "brilliant." Not "visionary." Just someone who keeps figuring things out. If that's you, you're already qualified. https://paulgraham.com/relres.html
-
-**After presenting resources — log to builder profile and offer to open:**
-
-1. Log the selected resource URLs to the builder profile (single source of truth).
-Append a resource-tracking entry:
-```bash
-eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null || true)"
-~/.claude/skills/gstack/bin/gstack-developer-profile --log-session '{"date":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'","mode":"resources","project_slug":"'"${SLUG:-unknown}"'","signal_count":0,"signals":[],"design_doc":"","assignment":"","resources_shown":["URL1","URL2","URL3"],"topics":[]}' 2>/dev/null || true
-```
-
-2. Log the selection to analytics:
-```bash
-mkdir -p ~/.gstack/analytics
-echo '{"skill":"office-hours","event":"resources_shown","count":NUM_RESOURCES,"categories":"CAT1,CAT2","ts":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
-```
-
-3. Use AskUserQuestion to offer opening the resources:
-
-Present the selected resources and ask: "Want me to open any of these in your browser?"
-
-Options:
-- A) Open all of them (I'll check them out later)
-- B) [Title of resource 1] — open just this one
-- C) [Title of resource 2] — open just this one
-- D) [Title of resource 3, if 3 were shown] — open just this one
-- E) Skip — I'll find them later
-
-If A: run `open URL1 && open URL2 && open URL3` (opens each in default browser).
-If B/C/D: run `open` on the selected URL only.
-If E: proceed to next-skill recommendations.
-
-### Next-skill recommendations
-
-After the plea, suggest the next step:
-
-- **`/plan-ceo-review`** for ambitious features (EXPANSION mode) — rethink the problem, find the 10-star product
-- **`/plan-eng-review`** for well-scoped implementation planning — lock in architecture, tests, edge cases
-- **`/plan-design-review`** for visual/UX design review
-
-The design doc at `~/.gstack/projects/` is automatically discoverable by downstream skills — they will read it during their pre-review system audit.
 
 ---
 

office-hours/sections/design-and-handoff.md

@@ -0,0 +1,543 @@
+<!-- AUTO-GENERATED from design-and-handoff.md.tmpl — do not edit directly -->
+<!-- Regenerate: bun run gen:skill-docs -->
+## Phase 5: Design Doc
+
+Write the design document to the project directory.
+
+```bash
+eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" && mkdir -p ~/.gstack/projects/$SLUG
+USER=$(whoami)
+DATETIME=$(date +%Y%m%d-%H%M%S)
+```
+
+**Design lineage:** Before writing, check for existing design docs on this branch:
+```bash
+setopt +o nomatch 2>/dev/null || true  # zsh compat
+PRIOR=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1)
+```
+If `$PRIOR` exists, the new doc gets a `Supersedes:` field referencing it. This creates a revision chain — you can trace how a design evolved across office hours sessions.
+
+Write to `~/.gstack/projects/{slug}/{user}-{branch}-design-{datetime}.md`.
+
+After writing the design doc, tell the user:
+**"Design doc saved to: {full path}. Other skills (/plan-ceo-review, /plan-eng-review) will find it automatically."**
+
+### Startup mode design doc template:
+
+```markdown
+# Design: {title}
+
+Generated by /office-hours on {date}
+Branch: {branch}
+Repo: {owner/repo}
+Status: DRAFT
+Mode: Startup
+Supersedes: {prior filename — omit this line if first design on this branch}
+
+## Problem Statement
+{from Phase 2A}
+
+## Demand Evidence
+{from Q1 — specific quotes, numbers, behaviors demonstrating real demand}
+
+## Status Quo
+{from Q2 — concrete current workflow users live with today}
+
+## Target User & Narrowest Wedge
+{from Q3 + Q4 — the specific human and the smallest version worth paying for}
+
+## Constraints
+{from Phase 2A}
+
+## Premises
+{from Phase 3}
+
+## Cross-Model Perspective
+{If second opinion ran in Phase 3.5 (Codex or Claude subagent): independent cold read — steelman, key insight, challenged premise, prototype suggestion. Verbatim or close paraphrase. If second opinion did NOT run (skipped or unavailable): omit this section entirely — do not include it.}
+
+## Approaches Considered
+### Approach A: {name}
+{from Phase 4}
+### Approach B: {name}
+{from Phase 4}
+
+## Recommended Approach
+{chosen approach with rationale}
+
+## Open Questions
+{any unresolved questions from the office hours}
+
+## Success Criteria
+{measurable criteria from Phase 2A}
+
+## Distribution Plan
+{how users get the deliverable — binary download, package manager, container image, web service, etc.}
+{CI/CD pipeline for building and publishing — GitHub Actions, manual release, auto-deploy on merge?}
+{omit this section if the deliverable is a web service with existing deployment pipeline}
+
+## Dependencies
+{blockers, prerequisites, related work}
+
+## The Assignment
+{one concrete real-world action the founder should take next — not "go build it"}
+
+## What I noticed about how you think
+{observational, mentor-like reflections referencing specific things the user said during the session. Quote their words back to them — don't characterize their behavior. 2-4 bullets.}
+```
+
+### Builder mode design doc template:
+
+```markdown
+# Design: {title}
+
+Generated by /office-hours on {date}
+Branch: {branch}
+Repo: {owner/repo}
+Status: DRAFT
+Mode: Builder
+Supersedes: {prior filename — omit this line if first design on this branch}
+
+## Problem Statement
+{from Phase 2B}
+
+## What Makes This Cool
+{the core delight, novelty, or "whoa" factor}
+
+## Constraints
+{from Phase 2B}
+
+## Premises
+{from Phase 3}
+
+## Cross-Model Perspective
+{If second opinion ran in Phase 3.5 (Codex or Claude subagent): independent cold read — coolest version, key insight, existing tools, prototype suggestion. Verbatim or close paraphrase. If second opinion did NOT run (skipped or unavailable): omit this section entirely — do not include it.}
+
+## Approaches Considered
+### Approach A: {name}
+{from Phase 4}
+### Approach B: {name}
+{from Phase 4}
+
+## Recommended Approach
+{chosen approach with rationale}
+
+## Open Questions
+{any unresolved questions from the office hours}
+
+## Success Criteria
+{what "done" looks like}
+
+## Distribution Plan
+{how users get the deliverable — binary download, package manager, container image, web service, etc.}
+{CI/CD pipeline for building and publishing — or "existing deployment pipeline covers this"}
+
+## Next Steps
+{concrete build tasks — what to implement first, second, third}
+
+## What I noticed about how you think
+{observational, mentor-like reflections referencing specific things the user said during the session. Quote their words back to them — don't characterize their behavior. 2-4 bullets.}
+```
+
+---
+
+## Spec Review Loop
+
+Before presenting the document to the user for approval, run an adversarial review.
+
+**Step 1: Dispatch reviewer subagent**
+
+Use the Agent tool to dispatch an independent reviewer. The reviewer has fresh context
+and cannot see the brainstorming conversation — only the document. This ensures genuine
+adversarial independence.
+
+Prompt the subagent with:
+- The file path of the document just written
+- "Read this document and review it on 5 dimensions. For each dimension, note PASS or
+  list specific issues with suggested fixes. At the end, output a quality score (1-10)
+  across all dimensions."
+
+**Dimensions:**
+1. **Completeness** — Are all requirements addressed? Missing edge cases?
+2. **Consistency** — Do parts of the document agree with each other? Contradictions?
+3. **Clarity** — Could an engineer implement this without asking questions? Ambiguous language?
+4. **Scope** — Does the document creep beyond the original problem? YAGNI violations?
+5. **Feasibility** — Can this actually be built with the stated approach? Hidden complexity?
+
+The subagent should return:
+- A quality score (1-10)
+- PASS if no issues, or a numbered list of issues with dimension, description, and fix
+
+**Step 2: Fix and re-dispatch**
+
+If the reviewer returns issues:
+1. Fix each issue in the document on disk (use Edit tool)
+2. Re-dispatch the reviewer subagent with the updated document
+3. Maximum 3 iterations total
+
+**Convergence guard:** If the reviewer returns the same issues on consecutive iterations
+(the fix didn't resolve them or the reviewer disagrees with the fix), stop the loop
+and persist those issues as "Reviewer Concerns" in the document rather than looping
+further.
+
+If the subagent fails, times out, or is unavailable — skip the review loop entirely.
+Tell the user: "Spec review unavailable — presenting unreviewed doc." The document is
+already written to disk; the review is a quality bonus, not a gate.
+
+**Step 3: Report and persist metrics**
+
+After the loop completes (PASS, max iterations, or convergence guard):
+
+1. Tell the user the result — summary by default:
+   "Your doc survived N rounds of adversarial review. M issues caught and fixed.
+   Quality score: X/10."
+   If they ask "what did the reviewer find?", show the full reviewer output.
+
+2. If issues remain after max iterations or convergence, add a "## Reviewer Concerns"
+   section to the document listing each unresolved issue. Downstream skills will see this.
+
+3. Append metrics:
+```bash
+mkdir -p ~/.gstack/analytics
+echo '{"skill":"office-hours","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","iterations":ITERATIONS,"issues_found":FOUND,"issues_fixed":FIXED,"remaining":REMAINING,"quality_score":SCORE}' >> ~/.gstack/analytics/spec-review.jsonl 2>/dev/null || true
+```
+Replace ITERATIONS, FOUND, FIXED, REMAINING, SCORE with actual values from the review.
+
+---
+
+Present the reviewed design doc to the user via AskUserQuestion:
+- A) Approve — mark Status: APPROVED and proceed to handoff
+- B) Revise — specify which sections need changes (loop back to revise those sections)
+- C) Start over — return to Phase 2
+
+
+
+## Brain Calibration Write-Back (Phase 2 / gated)
+
+When the skill makes a typed prediction worth tracking (scope decision,
+TTHW target, architectural bet, wedge commitment), it MAY write a
+`kind=bet` take to the brain so a calibration profile builds over time.
+
+**Gated on two things:**
+1. Brain trust policy for the active endpoint is `personal` (check via
+   `~/.claude/skills/gstack/bin/gstack-config get brain_trust_policy@<endpoint-hash>`).
+   Shared brains skip write-back to avoid polluting team calibration.
+2. Feature flag `BRAIN_CALIBRATION_WRITEBACK` is set (today: false; flips
+   to true when upstream gbrain v0.42+ ships `takes_add` MCP op).
+
+When both gates pass, the write-back path uses `mcp__gbrain__takes_add`
+to record a take with weight 0.9 (per SKILL_CALIBRATION_WEIGHTS).
+If the MCP op is unavailable, fall back to `mcp__gbrain__put_page` with
+a gstack:takes fence block (documented but uglier path).
+
+Mandatory take frontmatter shape:
+```yaml
+kind: bet
+holder: <user identity from whoami>
+claim: <one-line prediction the skill is making>
+weight: 0.9
+since_date: <today's date>
+expected_resolution: <date in 1-3 months depending on skill>
+source_skill: office-hours
+```
+
+After write, invalidate the affected digests so the next preflight reflects
+the new state:
+
+```bash
+eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true
+  ~/.claude/skills/gstack/bin/gstack-brain-cache invalidate product --project "$SLUG" 2>/dev/null || true
+  ~/.claude/skills/gstack/bin/gstack-brain-cache invalidate goals --project "$SLUG" 2>/dev/null || true
+  ~/.claude/skills/gstack/bin/gstack-brain-cache invalidate competitive-intel --project "$SLUG" 2>/dev/null || true
+```
+
+
+## Brain Cache Background Refresh
+
+After the skill's work completes (and telemetry has logged), kick a
+background refresh of any cache digest that's getting close to its TTL.
+This is non-blocking — the user doesn't wait. Next invocation benefits
+from the warm cache.
+
+```bash
+eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true
+(~/.claude/skills/gstack/bin/gstack-brain-cache refresh --project "$SLUG" 2>/dev/null &) || true
+```
+
+
+---
+
+## Phase 6: Handoff — The Relationship Closing
+
+Once the design doc is APPROVED, deliver the closing sequence. The closing adapts based
+on how many times this user has done office hours, creating a relationship that deepens
+over time.
+
+### Step 1: Read Builder Profile
+
+```bash
+PROFILE=$(~/.claude/skills/gstack/bin/gstack-builder-profile 2>/dev/null) || PROFILE="SESSION_COUNT: 0
+TIER: introduction"
+SESSION_TIER=$(echo "$PROFILE" | grep "^TIER:" | awk '{print $2}')
+SESSION_COUNT=$(echo "$PROFILE" | grep "^SESSION_COUNT:" | awk '{print $2}')
+```
+
+Read the full profile output. You will use these values throughout the closing.
+
+### Step 2: Follow the Tier Path
+
+Follow ONE tier path below based on `SESSION_TIER`. Do not mix tiers.
+
+---
+
+### If TIER = introduction (first session)
+
+This is the full introduction. The user has never done office hours before.
+
+**Beat 1: Signal Reflection + Golden Age**
+
+One paragraph that weaves specific session callbacks with the golden age framing. Reference actual things the user said, quote their words back to them.
+
+**Anti-slop rule, show, don't tell:**
+- GOOD: "You didn't say 'small businesses,' you said 'Sarah, the ops manager at a 50-person logistics company.' That specificity is rare."
+- BAD: "You showed great specificity in identifying your target user."
+- GOOD: "You pushed back when I challenged premise #2. Most people just agree."
+- BAD: "You demonstrated conviction and independent thinking."
+
+Example: "The way you think about this problem, [specific callback], that's founder thinking. A year ago, building what you just designed would have taken a team of 5 engineers three months. Today you can build it this weekend with Claude Code. The engineering barrier is gone. What remains is taste, and you just demonstrated that."
+
+**Beat 2: "One more thing."**
+
+Output a separator and "One more thing." This resets attention and signals the genre shift.
+
+---
+
+One more thing.
+
+**Beat 3: Garry's Personal Plea**
+
+Use the founder signal count from Phase 4.5 to select the right sub-tier.
+
+- **Top tier** (3+ signals AND named a specific user, revenue, or demand evidence):
+
+> A personal note from me, Garry Tan, the creator of GStack: what you just experienced is about 10% of the value you'd get working with a YC partner at Y Combinator. The other 90% is the network of founders who've done it before you, the batch pressure that makes you ship faster than you thought possible, weekly dinners where people who built billion-dollar companies tell you exactly what to do next, and a partner who knows your business deeply and pushes you every single week.
+>
+> GStack thinks you are among the top people who could do this.
+
+Then use AskUserQuestion: "Would you consider applying to Y Combinator?"
+- If yes: run `open https://ycombinator.com/apply?ref=gstack` and say: "Bring this design doc to your YC interview. It's better than most pitch decks."
+- If no: respond warmly: "Totally fair. The design doc is yours either way, and the offer stands if you ever change your mind." No pressure, no guilt, no re-ask.
+
+- **Middle tier** (1-2 signals, or builder whose project solves a real problem):
+
+> A personal note from me, Garry Tan, the creator of GStack: what you just experienced, the premise challenges, the forced alternatives, the narrowest-wedge thinking, is about 10% of what working with a YC partner is like. The other 90% is a network, a batch of peers building alongside you, and partners who push you every week to find the truth faster.
+>
+> You're building something real. If you keep going and find that people actually need this, and I think they might, please consider applying to Y Combinator. Thank you for using GStack.
+>
+> **ycombinator.com/apply?ref=gstack**
+
+- **Base tier** (everyone else):
+
+> A personal note from me, Garry Tan, the creator of GStack: the skills you're demonstrating right now, taste, ambition, agency, the willingness to sit with hard questions about what you're building, those are exactly the traits we look for in YC founders. You may not be thinking about starting a company today, and that's fine. But founders are everywhere, and this is the golden age. A single person with AI can now build what used to take a team of 20.
+>
+> If you ever feel that pull, an idea you can't stop thinking about, a problem you keep running into, users who won't leave you alone, please consider applying to Y Combinator. Thank you for using GStack. I mean it.
+>
+> **ycombinator.com/apply?ref=gstack**
+
+Then proceed to Founder Resources below.
+
+---
+
+### If TIER = welcome_back (sessions 2-3)
+
+Lead with recognition. The magical moment is immediate.
+
+Read LAST_ASSIGNMENT and CROSS_PROJECT from the profile output.
+
+If CROSS_PROJECT is false (same project as last time):
+"Welcome back. Last time you were working on [LAST_ASSIGNMENT from profile]. How's it going?"
+
+If CROSS_PROJECT is true (different project):
+"Welcome back. Last time we talked about [LAST_PROJECT from profile]. Still on that, or onto something new?"
+
+Then: "No pitch this time. You already know about YC. Let's talk about your work."
+
+**Tone examples (prevent generic AI voice):**
+- GOOD: "Welcome back. Last time you were designing that task manager for ops teams. Still on that?"
+- BAD: "Welcome back to your second office hours session. I'd like to check in on your progress."
+- GOOD: "No pitch this time. You already know about YC. Let's talk about your work."
+- BAD: "Since you've already seen the YC information, we'll skip that section today."
+
+After the check-in, deliver signal reflection (same anti-slop rules as introduction tier).
+
+Then: Design doc trajectory. Read DESIGN_TITLES from the profile.
+"Your first design was [first title]. Now you're on [latest title]."
+
+Then proceed to Founder Resources below.
+
+---
+
+### If TIER = regular (sessions 4-7)
+
+Lead with recognition and session count.
+
+"Welcome back. This is session [SESSION_COUNT]. Last time: [LAST_ASSIGNMENT]. How'd it go?"
+
+**Tone examples:**
+- GOOD: "You've been at this for 5 sessions now. Your designs keep getting sharper. Let me show you what I've noticed."
+- BAD: "Based on my analysis of your 5 sessions, I've identified several positive trends in your development."
+
+After the check-in, deliver arc-level signal reflection. Reference patterns ACROSS sessions, not just this one.
+Example: "In session 1, you described users as 'small businesses.' By now you're saying 'Sarah at Acme Corp.' That specificity shift is a signal."
+
+Design trajectory with interpretation:
+"Your first design was broad. Your latest narrows to a specific wedge, that's the PMF pattern."
+
+**Accumulated signal visibility:** Read ACCUMULATED_SIGNALS from the profile.
+"Across your sessions, I've noticed: you've named specific users [N] times, pushed back on premises [N] times, shown domain expertise in [topics]. These patterns mean something."
+
+**Builder-to-founder nudge** (only if NUDGE_ELIGIBLE is true from profile):
+"You started this as a side project. But you've named specific users, pushed back when challenged, and your designs keep getting sharper each time. I don't think this is a side project anymore. Have you thought about whether this could be a company?"
+This must feel earned, not broadcast. If the evidence doesn't support it, skip entirely.
+
+**Builder Journey Summary** (session 5+): Auto-generate `~/.gstack/builder-journey.md`
+with a narrative arc (not a data table). The arc tells the STORY of their journey in
+second person, referencing specific things they said across sessions. Then open it:
+```bash
+eval "$(~/.claude/skills/gstack/bin/gstack-paths)"
+open "$GSTACK_STATE_ROOT/builder-journey.md"
+```
+
+Then proceed to Founder Resources below.
+
+---
+
+### If TIER = inner_circle (sessions 8+)
+
+"You've done [SESSION_COUNT] sessions. You've iterated [DESIGN_COUNT] designs. Most people who show this pattern end up shipping."
+
+The data speaks. No pitch needed.
+
+Full accumulated signal summary from the profile.
+
+Auto-generate updated `~/.gstack/builder-journey.md` with narrative arc. Open it.
+
+Then proceed to Founder Resources below.
+
+---
+
+### Founder Resources (all tiers)
+
+Share 2-3 resources from the pool below. For repeat users, resources compound by matching
+to accumulated session context, not just this session's category.
+
+**Dedup check:** Read `RESOURCES_SHOWN` from the builder profile output above.
+If `RESOURCES_SHOWN_COUNT` is 34 or more, skip this section entirely (all resources exhausted).
+Otherwise, avoid selecting any URL that appears in the RESOURCES_SHOWN list.
+
+**Selection rules:**
+- Pick 2-3 resources. Mix categories — never 3 of the same type.
+- Never pick a resource whose URL appears in the dedup log above.
+- Match to session context (what came up matters more than random variety):
+  - Hesitant about leaving their job → "My $200M Startup Mistake" or "Should You Quit Your Job At A Unicorn?"
+  - Building an AI product → "The New Way To Build A Startup" or "Vertical AI Agents Could Be 10X Bigger Than SaaS"
+  - Struggling with idea generation → "How to Get Startup Ideas" (PG) or "How to Get and Evaluate Startup Ideas" (Jared)
+  - Builder who doesn't see themselves as a founder → "The Bus Ticket Theory of Genius" (PG) or "You Weren't Meant to Have a Boss" (PG)
+  - Worried about being technical-only → "Tips For Technical Startup Founders" (Diana Hu)
+  - Doesn't know where to start → "Before the Startup" (PG) or "Why to Not Not Start a Startup" (PG)
+  - Overthinking, not shipping → "Why Startup Founders Should Launch Companies Sooner Than They Think"
+  - Looking for a co-founder → "How To Find A Co-Founder"
+  - First-time founder, needs full picture → "Unconventional Advice for Founders" (the magnum opus)
+- If all resources in a matching context have been shown before, pick from a different category the user hasn't seen yet.
+
+**Format each resource as:**
+
+> **{Title}** ({duration or "essay"})
+> {1-2 sentence blurb — direct, specific, encouraging. Match Garry's voice: tell them WHY this one matters for THEIR situation.}
+> {url}
+
+**Resource Pool:**
+
+GARRY TAN VIDEOS:
+1. "My $200 million startup mistake: Peter Thiel asked and I said no" (5 min) — The single best "why you should take the leap" video. Peter Thiel writes him a check at dinner, he says no because he might get promoted to Level 60. That 1% stake would be worth $350-500M today. https://www.youtube.com/watch?v=dtnG0ELjvcM
+2. "Unconventional Advice for Founders" (48 min, Stanford) — The magnum opus. Covers everything a pre-launch founder needs: get therapy before your psychology kills your company, good ideas look like bad ideas, the Katamari Damacy metaphor for growth. No filler. https://www.youtube.com/watch?v=Y4yMc99fpfY
+3. "The New Way To Build A Startup" (8 min) — The 2026 playbook. Introduces the "20x company" — tiny teams beating incumbents through AI automation. Three real case studies. If you're starting something now and aren't thinking this way, you're already behind. https://www.youtube.com/watch?v=rWUWfj_PqmM
+4. "How To Build The Future: Sam Altman" (30 min) — Sam talks about what it takes to go from an idea to something real — picking what's important, finding your tribe, and why conviction matters more than credentials. https://www.youtube.com/watch?v=xXCBz_8hM9w
+5. "What Founders Can Do To Improve Their Design Game" (15 min) — Garry was a designer before he was an investor. Taste and craft are the real competitive advantage, not MBA skills or fundraising tricks. https://www.youtube.com/watch?v=ksGNfd-wQY4
+
+YC BACKSTORY / HOW TO BUILD THE FUTURE:
+6. "Tom Blomfield: How I Created Two Billion-Dollar Fintech Startups" (20 min) — Tom built Monzo from nothing into a bank used by 10% of the UK. The actual human journey — fear, mess, persistence. Makes founding feel like something a real person does. https://www.youtube.com/watch?v=QKPgBAnbc10
+7. "DoorDash CEO: Customer Obsession, Surviving Startup Death & Creating A New Market" (30 min) — Tony started DoorDash by literally driving food deliveries himself. If you've ever thought "I'm not the startup type," this will change your mind. https://www.youtube.com/watch?v=3N3TnaViyjk
+
+LIGHTCONE PODCAST:
+8. "How to Spend Your 20s in the AI Era" (40 min) — The old playbook (good job, climb the ladder) may not be the best path anymore. How to position yourself to build things that matter in an AI-first world. https://www.youtube.com/watch?v=ShYKkPPhOoc
+9. "How Do Billion Dollar Startups Start?" (25 min) — They start tiny, scrappy, and embarrassing. Demystifies the origin stories and shows that the beginning always looks like a side project, not a corporation. https://www.youtube.com/watch?v=HB3l1BPi7zo
+10. "Billion-Dollar Unpopular Startup Ideas" (25 min) — Uber, Coinbase, DoorDash — they all sounded terrible at first. The best opportunities are the ones most people dismiss. Liberating if your idea feels "weird." https://www.youtube.com/watch?v=Hm-ZIiwiN1o
+11. "Vertical AI Agents Could Be 10X Bigger Than SaaS" (40 min) — The most-watched Lightcone episode. If you're building in AI, this is the landscape map — where the biggest opportunities are and why vertical agents win. https://www.youtube.com/watch?v=ASABxNenD_U
+12. "The Truth About Building AI Startups Today" (35 min) — Cuts through the hype. What's actually working, what's not, and where the real defensibility comes from in AI startups right now. https://www.youtube.com/watch?v=TwDJhUJL-5o
+13. "Startup Ideas You Can Now Build With AI" (30 min) — Concrete, actionable ideas for things that weren't possible 12 months ago. If you're looking for what to build, start here. https://www.youtube.com/watch?v=K4s6Cgicw_A
+14. "Vibe Coding Is The Future" (30 min) — Building software just changed forever. If you can describe what you want, you can build it. The barrier to being a technical founder has never been lower. https://www.youtube.com/watch?v=IACHfKmZMr8
+15. "How To Get AI Startup Ideas" (30 min) — Not theoretical. Walks through specific AI startup ideas that are working right now and explains why the window is open. https://www.youtube.com/watch?v=TANaRNMbYgk
+16. "10 People + AI = Billion Dollar Company?" (25 min) — The thesis behind the 20x company. Small teams with AI leverage are outperforming 100-person incumbents. If you're a solo builder or small team, this is your permission slip to think big. https://www.youtube.com/watch?v=CKvo_kQbakU
+
+YC STARTUP SCHOOL:
+17. "Should You Start A Startup?" (17 min, Harj Taggar) — Directly addresses the question most people are too afraid to ask out loud. Breaks down the real tradeoffs honestly, without hype. https://www.youtube.com/watch?v=BUE-icVYRFU
+18. "How to Get and Evaluate Startup Ideas" (30 min, Jared Friedman) — YC's most-watched Startup School video. How founders actually stumbled into their ideas by paying attention to problems in their own lives. https://www.youtube.com/watch?v=Th8JoIan4dg
+19. "How David Lieb Turned a Failing Startup Into Google Photos" (20 min) — His company Bump was dying. He noticed a photo-sharing behavior in his own data, and it became Google Photos (1B+ users). A masterclass in seeing opportunity where others see failure. https://www.youtube.com/watch?v=CcnwFJqEnxU
+20. "Tips For Technical Startup Founders" (15 min, Diana Hu) — How to leverage your engineering skills as a founder rather than thinking you need to become a different person. https://www.youtube.com/watch?v=rP7bpYsfa6Q
+21. "Why Startup Founders Should Launch Companies Sooner Than They Think" (12 min, Tyler Bosmeny) — Most builders over-prepare and under-ship. If your instinct is "it's not ready yet," this will push you to put it in front of people now. https://www.youtube.com/watch?v=Nsx5RDVKZSk
+22. "How To Talk To Users" (20 min, Gustaf Alströmer) — You don't need sales skills. You need genuine conversations about problems. The most approachable tactical talk for someone who's never done it. https://www.youtube.com/watch?v=z1iF1c8w5Lg
+23. "How To Find A Co-Founder" (15 min, Harj Taggar) — The practical mechanics of finding someone to build with. If "I don't want to do this alone" is stopping you, this removes that blocker. https://www.youtube.com/watch?v=Fk9BCr5pLTU
+24. "Should You Quit Your Job At A Unicorn?" (12 min, Tom Blomfield) — Directly speaks to people at big tech companies who feel the pull to build something of their own. If that's your situation, this is the permission slip. https://www.youtube.com/watch?v=chAoH_AeGAg
+
+PAUL GRAHAM ESSAYS:
+25. "How to Do Great Work" — Not about startups. About finding the most meaningful work of your life. The roadmap that often leads to founding without ever saying "startup." https://paulgraham.com/greatwork.html
+26. "How to Do What You Love" — Most people keep their real interests separate from their career. Makes the case for collapsing that gap — which is usually how companies get born. https://paulgraham.com/love.html
+27. "The Bus Ticket Theory of Genius" — The thing you're obsessively into that other people find boring? PG argues it's the actual mechanism behind every breakthrough. https://paulgraham.com/genius.html
+28. "Why to Not Not Start a Startup" — Takes apart every quiet reason you have for not starting — too young, no idea, don't know business — and shows why none hold up. https://paulgraham.com/notnot.html
+29. "Before the Startup" — Written specifically for people who haven't started anything yet. What to focus on now, what to ignore, and how to tell if this path is for you. https://paulgraham.com/before.html
+30. "Superlinear Returns" — Some efforts compound exponentially; most don't. Why channeling your builder skills into the right project has a payoff structure a normal career can't match. https://paulgraham.com/superlinear.html
+31. "How to Get Startup Ideas" — The best ideas aren't brainstormed. They're noticed. Teaches you to look at your own frustrations and recognize which ones could be companies. https://paulgraham.com/startupideas.html
+32. "Schlep Blindness" — The best opportunities hide inside boring, tedious problems everyone avoids. If you're willing to tackle the unsexy thing you see up close, you might already be standing on a company. https://paulgraham.com/schlep.html
+33. "You Weren't Meant to Have a Boss" — If working inside a big organization has always felt slightly wrong, this explains why. Small groups on self-chosen problems is the natural state for builders. https://paulgraham.com/boss.html
+34. "Relentlessly Resourceful" — PG's two-word description of the ideal founder. Not "brilliant." Not "visionary." Just someone who keeps figuring things out. If that's you, you're already qualified. https://paulgraham.com/relres.html
+
+**After presenting resources — log to builder profile and offer to open:**
+
+1. Log the selected resource URLs to the builder profile (single source of truth).
+Append a resource-tracking entry:
+```bash
+eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null || true)"
+~/.claude/skills/gstack/bin/gstack-developer-profile --log-session '{"date":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'","mode":"resources","project_slug":"'"${SLUG:-unknown}"'","signal_count":0,"signals":[],"design_doc":"","assignment":"","resources_shown":["URL1","URL2","URL3"],"topics":[]}' 2>/dev/null || true
+```
+
+2. Log the selection to analytics:
+```bash
+mkdir -p ~/.gstack/analytics
+echo '{"skill":"office-hours","event":"resources_shown","count":NUM_RESOURCES,"categories":"CAT1,CAT2","ts":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
+```
+
+3. Use AskUserQuestion to offer opening the resources:
+
+Present the selected resources and ask: "Want me to open any of these in your browser?"
+
+Options:
+- A) Open all of them (I'll check them out later)
+- B) [Title of resource 1] — open just this one
+- C) [Title of resource 2] — open just this one
+- D) [Title of resource 3, if 3 were shown] — open just this one
+- E) Skip — I'll find them later
+
+If A: run `open URL1 && open URL2 && open URL3` (opens each in default browser).
+If B/C/D: run `open` on the selected URL only.
+If E: proceed to next-skill recommendations.
+
+### Next-skill recommendations
+
+After the plea, suggest the next step:
+
+- **`/plan-ceo-review`** for ambitious features (EXPANSION mode) — rethink the problem, find the 10-star product
+- **`/plan-eng-review`** for well-scoped implementation planning — lock in architecture, tests, edge cases
+- **`/plan-design-review`** for visual/UX design review
+
+The design doc at `~/.gstack/projects/` is automatically discoverable by downstream skills — they will read it during their pre-review system audit.
+

office-hours/sections/design-and-handoff.md.tmpl

@@ -0,0 +1,432 @@
+## Phase 5: Design Doc
+
+Write the design document to the project directory.
+
+```bash
+{{SLUG_SETUP}}
+USER=$(whoami)
+DATETIME=$(date +%Y%m%d-%H%M%S)
+```
+
+**Design lineage:** Before writing, check for existing design docs on this branch:
+```bash
+setopt +o nomatch 2>/dev/null || true  # zsh compat
+PRIOR=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1)
+```
+If `$PRIOR` exists, the new doc gets a `Supersedes:` field referencing it. This creates a revision chain — you can trace how a design evolved across office hours sessions.
+
+Write to `~/.gstack/projects/{slug}/{user}-{branch}-design-{datetime}.md`.
+
+After writing the design doc, tell the user:
+**"Design doc saved to: {full path}. Other skills (/plan-ceo-review, /plan-eng-review) will find it automatically."**
+
+### Startup mode design doc template:
+
+```markdown
+# Design: {title}
+
+Generated by /office-hours on {date}
+Branch: {branch}
+Repo: {owner/repo}
+Status: DRAFT
+Mode: Startup
+Supersedes: {prior filename — omit this line if first design on this branch}
+
+## Problem Statement
+{from Phase 2A}
+
+## Demand Evidence
+{from Q1 — specific quotes, numbers, behaviors demonstrating real demand}
+
+## Status Quo
+{from Q2 — concrete current workflow users live with today}
+
+## Target User & Narrowest Wedge
+{from Q3 + Q4 — the specific human and the smallest version worth paying for}
+
+## Constraints
+{from Phase 2A}
+
+## Premises
+{from Phase 3}
+
+## Cross-Model Perspective
+{If second opinion ran in Phase 3.5 (Codex or Claude subagent): independent cold read — steelman, key insight, challenged premise, prototype suggestion. Verbatim or close paraphrase. If second opinion did NOT run (skipped or unavailable): omit this section entirely — do not include it.}
+
+## Approaches Considered
+### Approach A: {name}
+{from Phase 4}
+### Approach B: {name}
+{from Phase 4}
+
+## Recommended Approach
+{chosen approach with rationale}
+
+## Open Questions
+{any unresolved questions from the office hours}
+
+## Success Criteria
+{measurable criteria from Phase 2A}
+
+## Distribution Plan
+{how users get the deliverable — binary download, package manager, container image, web service, etc.}
+{CI/CD pipeline for building and publishing — GitHub Actions, manual release, auto-deploy on merge?}
+{omit this section if the deliverable is a web service with existing deployment pipeline}
+
+## Dependencies
+{blockers, prerequisites, related work}
+
+## The Assignment
+{one concrete real-world action the founder should take next — not "go build it"}
+
+## What I noticed about how you think
+{observational, mentor-like reflections referencing specific things the user said during the session. Quote their words back to them — don't characterize their behavior. 2-4 bullets.}
+```
+
+### Builder mode design doc template:
+
+```markdown
+# Design: {title}
+
+Generated by /office-hours on {date}
+Branch: {branch}
+Repo: {owner/repo}
+Status: DRAFT
+Mode: Builder
+Supersedes: {prior filename — omit this line if first design on this branch}
+
+## Problem Statement
+{from Phase 2B}
+
+## What Makes This Cool
+{the core delight, novelty, or "whoa" factor}
+
+## Constraints
+{from Phase 2B}
+
+## Premises
+{from Phase 3}
+
+## Cross-Model Perspective
+{If second opinion ran in Phase 3.5 (Codex or Claude subagent): independent cold read — coolest version, key insight, existing tools, prototype suggestion. Verbatim or close paraphrase. If second opinion did NOT run (skipped or unavailable): omit this section entirely — do not include it.}
+
+## Approaches Considered
+### Approach A: {name}
+{from Phase 4}
+### Approach B: {name}
+{from Phase 4}
+
+## Recommended Approach
+{chosen approach with rationale}
+
+## Open Questions
+{any unresolved questions from the office hours}
+
+## Success Criteria
+{what "done" looks like}
+
+## Distribution Plan
+{how users get the deliverable — binary download, package manager, container image, web service, etc.}
+{CI/CD pipeline for building and publishing — or "existing deployment pipeline covers this"}
+
+## Next Steps
+{concrete build tasks — what to implement first, second, third}
+
+## What I noticed about how you think
+{observational, mentor-like reflections referencing specific things the user said during the session. Quote their words back to them — don't characterize their behavior. 2-4 bullets.}
+```
+
+---
+
+{{SPEC_REVIEW_LOOP}}
+
+---
+
+Present the reviewed design doc to the user via AskUserQuestion:
+- A) Approve — mark Status: APPROVED and proceed to handoff
+- B) Revise — specify which sections need changes (loop back to revise those sections)
+- C) Start over — return to Phase 2
+
+{{GBRAIN_SAVE_RESULTS}}
+
+{{BRAIN_WRITE_BACK}}
+
+{{BRAIN_CACHE_REFRESH}}
+
+---
+
+## Phase 6: Handoff — The Relationship Closing
+
+Once the design doc is APPROVED, deliver the closing sequence. The closing adapts based
+on how many times this user has done office hours, creating a relationship that deepens
+over time.
+
+### Step 1: Read Builder Profile
+
+```bash
+PROFILE=$(~/.claude/skills/gstack/bin/gstack-builder-profile 2>/dev/null) || PROFILE="SESSION_COUNT: 0
+TIER: introduction"
+SESSION_TIER=$(echo "$PROFILE" | grep "^TIER:" | awk '{print $2}')
+SESSION_COUNT=$(echo "$PROFILE" | grep "^SESSION_COUNT:" | awk '{print $2}')
+```
+
+Read the full profile output. You will use these values throughout the closing.
+
+### Step 2: Follow the Tier Path
+
+Follow ONE tier path below based on `SESSION_TIER`. Do not mix tiers.
+
+---
+
+### If TIER = introduction (first session)
+
+This is the full introduction. The user has never done office hours before.
+
+**Beat 1: Signal Reflection + Golden Age**
+
+One paragraph that weaves specific session callbacks with the golden age framing. Reference actual things the user said, quote their words back to them.
+
+**Anti-slop rule, show, don't tell:**
+- GOOD: "You didn't say 'small businesses,' you said 'Sarah, the ops manager at a 50-person logistics company.' That specificity is rare."
+- BAD: "You showed great specificity in identifying your target user."
+- GOOD: "You pushed back when I challenged premise #2. Most people just agree."
+- BAD: "You demonstrated conviction and independent thinking."
+
+Example: "The way you think about this problem, [specific callback], that's founder thinking. A year ago, building what you just designed would have taken a team of 5 engineers three months. Today you can build it this weekend with Claude Code. The engineering barrier is gone. What remains is taste, and you just demonstrated that."
+
+**Beat 2: "One more thing."**
+
+Output a separator and "One more thing." This resets attention and signals the genre shift.
+
+---
+
+One more thing.
+
+**Beat 3: Garry's Personal Plea**
+
+Use the founder signal count from Phase 4.5 to select the right sub-tier.
+
+- **Top tier** (3+ signals AND named a specific user, revenue, or demand evidence):
+
+> A personal note from me, Garry Tan, the creator of GStack: what you just experienced is about 10% of the value you'd get working with a YC partner at Y Combinator. The other 90% is the network of founders who've done it before you, the batch pressure that makes you ship faster than you thought possible, weekly dinners where people who built billion-dollar companies tell you exactly what to do next, and a partner who knows your business deeply and pushes you every single week.
+>
+> GStack thinks you are among the top people who could do this.
+
+Then use AskUserQuestion: "Would you consider applying to Y Combinator?"
+- If yes: run `open https://ycombinator.com/apply?ref=gstack` and say: "Bring this design doc to your YC interview. It's better than most pitch decks."
+- If no: respond warmly: "Totally fair. The design doc is yours either way, and the offer stands if you ever change your mind." No pressure, no guilt, no re-ask.
+
+- **Middle tier** (1-2 signals, or builder whose project solves a real problem):
+
+> A personal note from me, Garry Tan, the creator of GStack: what you just experienced, the premise challenges, the forced alternatives, the narrowest-wedge thinking, is about 10% of what working with a YC partner is like. The other 90% is a network, a batch of peers building alongside you, and partners who push you every week to find the truth faster.
+>
+> You're building something real. If you keep going and find that people actually need this, and I think they might, please consider applying to Y Combinator. Thank you for using GStack.
+>
+> **ycombinator.com/apply?ref=gstack**
+
+- **Base tier** (everyone else):
+
+> A personal note from me, Garry Tan, the creator of GStack: the skills you're demonstrating right now, taste, ambition, agency, the willingness to sit with hard questions about what you're building, those are exactly the traits we look for in YC founders. You may not be thinking about starting a company today, and that's fine. But founders are everywhere, and this is the golden age. A single person with AI can now build what used to take a team of 20.
+>
+> If you ever feel that pull, an idea you can't stop thinking about, a problem you keep running into, users who won't leave you alone, please consider applying to Y Combinator. Thank you for using GStack. I mean it.
+>
+> **ycombinator.com/apply?ref=gstack**
+
+Then proceed to Founder Resources below.
+
+---
+
+### If TIER = welcome_back (sessions 2-3)
+
+Lead with recognition. The magical moment is immediate.
+
+Read LAST_ASSIGNMENT and CROSS_PROJECT from the profile output.
+
+If CROSS_PROJECT is false (same project as last time):
+"Welcome back. Last time you were working on [LAST_ASSIGNMENT from profile]. How's it going?"
+
+If CROSS_PROJECT is true (different project):
+"Welcome back. Last time we talked about [LAST_PROJECT from profile]. Still on that, or onto something new?"
+
+Then: "No pitch this time. You already know about YC. Let's talk about your work."
+
+**Tone examples (prevent generic AI voice):**
+- GOOD: "Welcome back. Last time you were designing that task manager for ops teams. Still on that?"
+- BAD: "Welcome back to your second office hours session. I'd like to check in on your progress."
+- GOOD: "No pitch this time. You already know about YC. Let's talk about your work."
+- BAD: "Since you've already seen the YC information, we'll skip that section today."
+
+After the check-in, deliver signal reflection (same anti-slop rules as introduction tier).
+
+Then: Design doc trajectory. Read DESIGN_TITLES from the profile.
+"Your first design was [first title]. Now you're on [latest title]."
+
+Then proceed to Founder Resources below.
+
+---
+
+### If TIER = regular (sessions 4-7)
+
+Lead with recognition and session count.
+
+"Welcome back. This is session [SESSION_COUNT]. Last time: [LAST_ASSIGNMENT]. How'd it go?"
+
+**Tone examples:**
+- GOOD: "You've been at this for 5 sessions now. Your designs keep getting sharper. Let me show you what I've noticed."
+- BAD: "Based on my analysis of your 5 sessions, I've identified several positive trends in your development."
+
+After the check-in, deliver arc-level signal reflection. Reference patterns ACROSS sessions, not just this one.
+Example: "In session 1, you described users as 'small businesses.' By now you're saying 'Sarah at Acme Corp.' That specificity shift is a signal."
+
+Design trajectory with interpretation:
+"Your first design was broad. Your latest narrows to a specific wedge, that's the PMF pattern."
+
+**Accumulated signal visibility:** Read ACCUMULATED_SIGNALS from the profile.
+"Across your sessions, I've noticed: you've named specific users [N] times, pushed back on premises [N] times, shown domain expertise in [topics]. These patterns mean something."
+
+**Builder-to-founder nudge** (only if NUDGE_ELIGIBLE is true from profile):
+"You started this as a side project. But you've named specific users, pushed back when challenged, and your designs keep getting sharper each time. I don't think this is a side project anymore. Have you thought about whether this could be a company?"
+This must feel earned, not broadcast. If the evidence doesn't support it, skip entirely.
+
+**Builder Journey Summary** (session 5+): Auto-generate `~/.gstack/builder-journey.md`
+with a narrative arc (not a data table). The arc tells the STORY of their journey in
+second person, referencing specific things they said across sessions. Then open it:
+```bash
+eval "$(~/.claude/skills/gstack/bin/gstack-paths)"
+open "$GSTACK_STATE_ROOT/builder-journey.md"
+```
+
+Then proceed to Founder Resources below.
+
+---
+
+### If TIER = inner_circle (sessions 8+)
+
+"You've done [SESSION_COUNT] sessions. You've iterated [DESIGN_COUNT] designs. Most people who show this pattern end up shipping."
+
+The data speaks. No pitch needed.
+
+Full accumulated signal summary from the profile.
+
+Auto-generate updated `~/.gstack/builder-journey.md` with narrative arc. Open it.
+
+Then proceed to Founder Resources below.
+
+---
+
+### Founder Resources (all tiers)
+
+Share 2-3 resources from the pool below. For repeat users, resources compound by matching
+to accumulated session context, not just this session's category.
+
+**Dedup check:** Read `RESOURCES_SHOWN` from the builder profile output above.
+If `RESOURCES_SHOWN_COUNT` is 34 or more, skip this section entirely (all resources exhausted).
+Otherwise, avoid selecting any URL that appears in the RESOURCES_SHOWN list.
+
+**Selection rules:**
+- Pick 2-3 resources. Mix categories — never 3 of the same type.
+- Never pick a resource whose URL appears in the dedup log above.
+- Match to session context (what came up matters more than random variety):
+  - Hesitant about leaving their job → "My $200M Startup Mistake" or "Should You Quit Your Job At A Unicorn?"
+  - Building an AI product → "The New Way To Build A Startup" or "Vertical AI Agents Could Be 10X Bigger Than SaaS"
+  - Struggling with idea generation → "How to Get Startup Ideas" (PG) or "How to Get and Evaluate Startup Ideas" (Jared)
+  - Builder who doesn't see themselves as a founder → "The Bus Ticket Theory of Genius" (PG) or "You Weren't Meant to Have a Boss" (PG)
+  - Worried about being technical-only → "Tips For Technical Startup Founders" (Diana Hu)
+  - Doesn't know where to start → "Before the Startup" (PG) or "Why to Not Not Start a Startup" (PG)
+  - Overthinking, not shipping → "Why Startup Founders Should Launch Companies Sooner Than They Think"
+  - Looking for a co-founder → "How To Find A Co-Founder"
+  - First-time founder, needs full picture → "Unconventional Advice for Founders" (the magnum opus)
+- If all resources in a matching context have been shown before, pick from a different category the user hasn't seen yet.
+
+**Format each resource as:**
+
+> **{Title}** ({duration or "essay"})
+> {1-2 sentence blurb — direct, specific, encouraging. Match Garry's voice: tell them WHY this one matters for THEIR situation.}
+> {url}
+
+**Resource Pool:**
+
+GARRY TAN VIDEOS:
+1. "My $200 million startup mistake: Peter Thiel asked and I said no" (5 min) — The single best "why you should take the leap" video. Peter Thiel writes him a check at dinner, he says no because he might get promoted to Level 60. That 1% stake would be worth $350-500M today. https://www.youtube.com/watch?v=dtnG0ELjvcM
+2. "Unconventional Advice for Founders" (48 min, Stanford) — The magnum opus. Covers everything a pre-launch founder needs: get therapy before your psychology kills your company, good ideas look like bad ideas, the Katamari Damacy metaphor for growth. No filler. https://www.youtube.com/watch?v=Y4yMc99fpfY
+3. "The New Way To Build A Startup" (8 min) — The 2026 playbook. Introduces the "20x company" — tiny teams beating incumbents through AI automation. Three real case studies. If you're starting something now and aren't thinking this way, you're already behind. https://www.youtube.com/watch?v=rWUWfj_PqmM
+4. "How To Build The Future: Sam Altman" (30 min) — Sam talks about what it takes to go from an idea to something real — picking what's important, finding your tribe, and why conviction matters more than credentials. https://www.youtube.com/watch?v=xXCBz_8hM9w
+5. "What Founders Can Do To Improve Their Design Game" (15 min) — Garry was a designer before he was an investor. Taste and craft are the real competitive advantage, not MBA skills or fundraising tricks. https://www.youtube.com/watch?v=ksGNfd-wQY4
+
+YC BACKSTORY / HOW TO BUILD THE FUTURE:
+6. "Tom Blomfield: How I Created Two Billion-Dollar Fintech Startups" (20 min) — Tom built Monzo from nothing into a bank used by 10% of the UK. The actual human journey — fear, mess, persistence. Makes founding feel like something a real person does. https://www.youtube.com/watch?v=QKPgBAnbc10
+7. "DoorDash CEO: Customer Obsession, Surviving Startup Death & Creating A New Market" (30 min) — Tony started DoorDash by literally driving food deliveries himself. If you've ever thought "I'm not the startup type," this will change your mind. https://www.youtube.com/watch?v=3N3TnaViyjk
+
+LIGHTCONE PODCAST:
+8. "How to Spend Your 20s in the AI Era" (40 min) — The old playbook (good job, climb the ladder) may not be the best path anymore. How to position yourself to build things that matter in an AI-first world. https://www.youtube.com/watch?v=ShYKkPPhOoc
+9. "How Do Billion Dollar Startups Start?" (25 min) — They start tiny, scrappy, and embarrassing. Demystifies the origin stories and shows that the beginning always looks like a side project, not a corporation. https://www.youtube.com/watch?v=HB3l1BPi7zo
+10. "Billion-Dollar Unpopular Startup Ideas" (25 min) — Uber, Coinbase, DoorDash — they all sounded terrible at first. The best opportunities are the ones most people dismiss. Liberating if your idea feels "weird." https://www.youtube.com/watch?v=Hm-ZIiwiN1o
+11. "Vertical AI Agents Could Be 10X Bigger Than SaaS" (40 min) — The most-watched Lightcone episode. If you're building in AI, this is the landscape map — where the biggest opportunities are and why vertical agents win. https://www.youtube.com/watch?v=ASABxNenD_U
+12. "The Truth About Building AI Startups Today" (35 min) — Cuts through the hype. What's actually working, what's not, and where the real defensibility comes from in AI startups right now. https://www.youtube.com/watch?v=TwDJhUJL-5o
+13. "Startup Ideas You Can Now Build With AI" (30 min) — Concrete, actionable ideas for things that weren't possible 12 months ago. If you're looking for what to build, start here. https://www.youtube.com/watch?v=K4s6Cgicw_A
+14. "Vibe Coding Is The Future" (30 min) — Building software just changed forever. If you can describe what you want, you can build it. The barrier to being a technical founder has never been lower. https://www.youtube.com/watch?v=IACHfKmZMr8
+15. "How To Get AI Startup Ideas" (30 min) — Not theoretical. Walks through specific AI startup ideas that are working right now and explains why the window is open. https://www.youtube.com/watch?v=TANaRNMbYgk
+16. "10 People + AI = Billion Dollar Company?" (25 min) — The thesis behind the 20x company. Small teams with AI leverage are outperforming 100-person incumbents. If you're a solo builder or small team, this is your permission slip to think big. https://www.youtube.com/watch?v=CKvo_kQbakU
+
+YC STARTUP SCHOOL:
+17. "Should You Start A Startup?" (17 min, Harj Taggar) — Directly addresses the question most people are too afraid to ask out loud. Breaks down the real tradeoffs honestly, without hype. https://www.youtube.com/watch?v=BUE-icVYRFU
+18. "How to Get and Evaluate Startup Ideas" (30 min, Jared Friedman) — YC's most-watched Startup School video. How founders actually stumbled into their ideas by paying attention to problems in their own lives. https://www.youtube.com/watch?v=Th8JoIan4dg
+19. "How David Lieb Turned a Failing Startup Into Google Photos" (20 min) — His company Bump was dying. He noticed a photo-sharing behavior in his own data, and it became Google Photos (1B+ users). A masterclass in seeing opportunity where others see failure. https://www.youtube.com/watch?v=CcnwFJqEnxU
+20. "Tips For Technical Startup Founders" (15 min, Diana Hu) — How to leverage your engineering skills as a founder rather than thinking you need to become a different person. https://www.youtube.com/watch?v=rP7bpYsfa6Q
+21. "Why Startup Founders Should Launch Companies Sooner Than They Think" (12 min, Tyler Bosmeny) — Most builders over-prepare and under-ship. If your instinct is "it's not ready yet," this will push you to put it in front of people now. https://www.youtube.com/watch?v=Nsx5RDVKZSk
+22. "How To Talk To Users" (20 min, Gustaf Alströmer) — You don't need sales skills. You need genuine conversations about problems. The most approachable tactical talk for someone who's never done it. https://www.youtube.com/watch?v=z1iF1c8w5Lg
+23. "How To Find A Co-Founder" (15 min, Harj Taggar) — The practical mechanics of finding someone to build with. If "I don't want to do this alone" is stopping you, this removes that blocker. https://www.youtube.com/watch?v=Fk9BCr5pLTU
+24. "Should You Quit Your Job At A Unicorn?" (12 min, Tom Blomfield) — Directly speaks to people at big tech companies who feel the pull to build something of their own. If that's your situation, this is the permission slip. https://www.youtube.com/watch?v=chAoH_AeGAg
+
+PAUL GRAHAM ESSAYS:
+25. "How to Do Great Work" — Not about startups. About finding the most meaningful work of your life. The roadmap that often leads to founding without ever saying "startup." https://paulgraham.com/greatwork.html
+26. "How to Do What You Love" — Most people keep their real interests separate from their career. Makes the case for collapsing that gap — which is usually how companies get born. https://paulgraham.com/love.html
+27. "The Bus Ticket Theory of Genius" — The thing you're obsessively into that other people find boring? PG argues it's the actual mechanism behind every breakthrough. https://paulgraham.com/genius.html
+28. "Why to Not Not Start a Startup" — Takes apart every quiet reason you have for not starting — too young, no idea, don't know business — and shows why none hold up. https://paulgraham.com/notnot.html
+29. "Before the Startup" — Written specifically for people who haven't started anything yet. What to focus on now, what to ignore, and how to tell if this path is for you. https://paulgraham.com/before.html
+30. "Superlinear Returns" — Some efforts compound exponentially; most don't. Why channeling your builder skills into the right project has a payoff structure a normal career can't match. https://paulgraham.com/superlinear.html
+31. "How to Get Startup Ideas" — The best ideas aren't brainstormed. They're noticed. Teaches you to look at your own frustrations and recognize which ones could be companies. https://paulgraham.com/startupideas.html
+32. "Schlep Blindness" — The best opportunities hide inside boring, tedious problems everyone avoids. If you're willing to tackle the unsexy thing you see up close, you might already be standing on a company. https://paulgraham.com/schlep.html
+33. "You Weren't Meant to Have a Boss" — If working inside a big organization has always felt slightly wrong, this explains why. Small groups on self-chosen problems is the natural state for builders. https://paulgraham.com/boss.html
+34. "Relentlessly Resourceful" — PG's two-word description of the ideal founder. Not "brilliant." Not "visionary." Just someone who keeps figuring things out. If that's you, you're already qualified. https://paulgraham.com/relres.html
+
+**After presenting resources — log to builder profile and offer to open:**
+
+1. Log the selected resource URLs to the builder profile (single source of truth).
+Append a resource-tracking entry:
+```bash
+eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null || true)"
+~/.claude/skills/gstack/bin/gstack-developer-profile --log-session '{"date":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'","mode":"resources","project_slug":"'"${SLUG:-unknown}"'","signal_count":0,"signals":[],"design_doc":"","assignment":"","resources_shown":["URL1","URL2","URL3"],"topics":[]}' 2>/dev/null || true
+```
+
+2. Log the selection to analytics:
+```bash
+mkdir -p ~/.gstack/analytics
+echo '{"skill":"office-hours","event":"resources_shown","count":NUM_RESOURCES,"categories":"CAT1,CAT2","ts":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
+```
+
+3. Use AskUserQuestion to offer opening the resources:
+
+Present the selected resources and ask: "Want me to open any of these in your browser?"
+
+Options:
+- A) Open all of them (I'll check them out later)
+- B) [Title of resource 1] — open just this one
+- C) [Title of resource 2] — open just this one
+- D) [Title of resource 3, if 3 were shown] — open just this one
+- E) Skip — I'll find them later
+
+If A: run `open URL1 && open URL2 && open URL3` (opens each in default browser).
+If B/C/D: run `open` on the selected URL only.
+If E: proceed to next-skill recommendations.
+
+### Next-skill recommendations
+
+After the plea, suggest the next step:
+
+- **`/plan-ceo-review`** for ambitious features (EXPANSION mode) — rethink the problem, find the 10-star product
+- **`/plan-eng-review`** for well-scoped implementation planning — lock in architecture, tests, edge cases
+- **`/plan-design-review`** for visual/UX design review
+
+The design doc at `~/.gstack/projects/` is automatically discoverable by downstream skills — they will read it during their pre-review system audit.
+

office-hours/sections/manifest.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://gstack.dev/schemas/section-manifest.json",
+  "skill": "office-hours",
+  "version": 1,
+  "note": "PASSIVE registry (v2 plan T9 / CM2). Fields are IDs, file paths, human titles, and human-readable trigger text ONLY. The skeleton's decision-tree prose is the ONLY place that decides WHEN to read a section. No machine predicate here — see docs/designs/v2_PLAN.md.",
+  "sections": [
+    {
+      "id": "design-and-handoff",
+      "file": "design-and-handoff.md",
+      "title": "Phase 5 design doc + Phase 6 relationship handoff",
+      "trigger": "writing the design doc and running the tiered relationship handoff (Phases 5-6, after the conversation and alternatives are done)"
+    }
+  ]
+}

open-gstack-browser/SKILL.md

@@ -362,25 +362,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "gstack",
-  "version": "1.55.1.0",
+  "version": "1.59.0.0",
   "description": "Garry's Stack — Claude Code skills + fast headless browser. One repo, one install, entire AI engineering workflow.",
   "license": "MIT",
   "type": "module",

pair-agent/SKILL.md

@@ -364,25 +364,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

plan-ceo-review/SKILL.md

@@ -394,25 +394,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 
@@ -1119,6 +1106,15 @@ rm -f /tmp/.gstack-brain-context-$$.md 2>/dev/null || true
 `gstack/`, `concepts/` only). Personal/family/therapy content never leaks here.
 
 
+## Section index — Read each section when its situation applies
+
+This skill is a decision-tree skeleton. The steps below point to on-demand
+sections. Read a section in full before doing its step; do not work from memory.
+
+| When | Read this section |
+|------|-------------------|
+| running the 11-section deep review, required outputs, and review report (only after Step 0 scope and mode are agreed) | `sections/review-sections.md` |
+
 ## Step 0: Nuclear Scope Challenge + Mode Selection
 
 ### 0A. Premise Challenge
@@ -1364,904 +1360,18 @@ Present these mode options via AskUserQuestion using the preamble's AskUserQuest
 **STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
 **Reminder: Do NOT make any code changes. Review only.**
 
-## Review Sections (11 sections, after scope and mode are agreed)
+> **STOP.** Before running the 11-section deep review, required outputs, and review report (only after Step 0 scope and mode are agreed), Read `~/.claude/skills/gstack/plan-ceo-review/sections/review-sections.md` and execute it
+> in full. Do not work from memory — that section is the source of truth for this step.
 
-**Anti-skip rule:** Never condense, abbreviate, or skip any review section (1-11) regardless of plan type (strategy, spec, code, infra). Every section in this skill exists for a reason. "This is a strategy doc so implementation sections don't apply" is always wrong — implementation details are where strategy breaks down. If a section genuinely has zero findings, say "No issues found" and move on — but you must evaluate it.
+## Section self-check (before you finish)
 
-**Anti-shortcut clause:** The plan file is the OUTPUT of the interactive review, not a substitute for it. Writing every finding into one plan write and calling ExitPlanMode without firing AskUserQuestion is the precise failure mode of the May 2026 transcript bug — the model explored, found issues, and dumped them into a deliverable rather than walking the user through them. If you have ANY non-trivial finding in any review section, the path from finding to ExitPlanMode goes THROUGH AskUserQuestion. Zero findings in every section is the only path to ExitPlanMode that bypasses AskUserQuestion. If you find yourself wanting to write a plan with findings before asking, stop and call AskUserQuestion now — that's the bug, recognize it.
+You ran a carved skill. The Section index above named `sections/review-sections.md`
+as the source of truth for the 11-section deep review, the required outputs, and the
+review report. Confirm you issued a Read for it and executed every section from the
+file, not from memory. If you produced the Completion Summary or wrote the review
+report without Reading that section, STOP, Read it now, and redo the review from the
+source of truth.
 
-### Section 1: Architecture Review
-Evaluate and diagram:
-* Overall system design and component boundaries. Draw the dependency graph.
-* Data flow — all four paths. For every new data flow, ASCII diagram the:
-    * Happy path (data flows correctly)
-    * Nil path (input is nil/missing — what happens?)
-    * Empty path (input is present but empty/zero-length — what happens?)
-    * Error path (upstream call fails — what happens?)
-* State machines. ASCII diagram for every new stateful object. Include impossible/invalid transitions and what prevents them.
-* Coupling concerns. Which components are now coupled that weren't before? Is that coupling justified? Draw the before/after dependency graph.
-* Scaling characteristics. What breaks first under 10x load? Under 100x?
-* Single points of failure. Map them.
-* Security architecture. Auth boundaries, data access patterns, API surfaces. For each new endpoint or data mutation: who can call it, what do they get, what can they change?
-* Production failure scenarios. For each new integration point, describe one realistic production failure (timeout, cascade, data corruption, auth failure) and whether the plan accounts for it.
-* Rollback posture. If this ships and immediately breaks, what's the rollback procedure? Git revert? Feature flag? DB migration rollback? How long?
-
-**EXPANSION and SELECTIVE EXPANSION additions:**
-* What would make this architecture beautiful? Not just correct — elegant. Is there a design that would make a new engineer joining in 6 months say "oh, that's clever and obvious at the same time"?
-* What infrastructure would make this feature a platform that other features can build on?
-
-**SELECTIVE EXPANSION:** If any accepted cherry-picks from Step 0D affect the architecture, evaluate their architectural fit here. Flag any that create coupling concerns or don't integrate cleanly — this is a chance to revisit the decision with new information.
-
-Required ASCII diagram: full system architecture showing new components and their relationships to existing ones.
-**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
-**Reminder: Do NOT make any code changes. Review only.**
-
-### Section 2: Error & Rescue Map
-This is the section that catches silent failures. It is not optional.
-For every new method, service, or codepath that can fail, fill in this table:
-```
-  METHOD/CODEPATH          | WHAT CAN GO WRONG           | EXCEPTION CLASS
-  -------------------------|-----------------------------|-----------------
-  ExampleService#call      | API timeout                 | TimeoutError
-                           | API returns 429             | RateLimitError
-                           | API returns malformed JSON  | JSONParseError
-                           | DB connection pool exhausted| ConnectionPoolExhausted
-                           | Record not found            | RecordNotFound
-  -------------------------|-----------------------------|-----------------
-
-  EXCEPTION CLASS              | RESCUED?  | RESCUE ACTION          | USER SEES
-  -----------------------------|-----------|------------------------|------------------
-  TimeoutError                 | Y         | Retry 2x, then raise   | "Service temporarily unavailable"
-  RateLimitError               | Y         | Backoff + retry         | Nothing (transparent)
-  JSONParseError               | N ← GAP   | —                      | 500 error ← BAD
-  ConnectionPoolExhausted      | N ← GAP   | —                      | 500 error ← BAD
-  RecordNotFound               | Y         | Return nil, log warning | "Not found" message
-```
-Rules for this section:
-* Catch-all error handling (`rescue StandardError`, `catch (Exception e)`, `except Exception`) is ALWAYS a smell. Name the specific exceptions.
-* Catching an error with only a generic log message is insufficient. Log the full context: what was being attempted, with what arguments, for what user/request.
-* Every rescued error must either: retry with backoff, degrade gracefully with a user-visible message, or re-raise with added context. "Swallow and continue" is almost never acceptable.
-* For each GAP (unrescued error that should be rescued): specify the rescue action and what the user should see.
-* For LLM/AI service calls specifically: what happens when the response is malformed? When it's empty? When it hallucinates invalid JSON? When the model returns a refusal? Each of these is a distinct failure mode.
-**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
-**Reminder: Do NOT make any code changes. Review only.**
-
-### Section 3: Security & Threat Model
-Security is not a sub-bullet of architecture. It gets its own section.
-Evaluate:
-* Attack surface expansion. What new attack vectors does this plan introduce? New endpoints, new params, new file paths, new background jobs?
-* Input validation. For every new user input: is it validated, sanitized, and rejected loudly on failure? What happens with: nil, empty string, string when integer expected, string exceeding max length, unicode edge cases, HTML/script injection attempts?
-* Authorization. For every new data access: is it scoped to the right user/role? Is there a direct object reference vulnerability? Can user A access user B's data by manipulating IDs?
-* Secrets and credentials. New secrets? In env vars, not hardcoded? Rotatable?
-* Dependency risk. New gems/npm packages? Security track record?
-* Data classification. PII, payment data, credentials? Handling consistent with existing patterns?
-* Injection vectors. SQL, command, template, LLM prompt injection — check all.
-* Audit logging. For sensitive operations: is there an audit trail?
-
-For each finding: threat, likelihood (High/Med/Low), impact (High/Med/Low), and whether the plan mitigates it.
-**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
-**Reminder: Do NOT make any code changes. Review only.**
-
-### Section 4: Data Flow & Interaction Edge Cases
-This section traces data through the system and interactions through the UI with adversarial thoroughness.
-
-**Data Flow Tracing:** For every new data flow, produce an ASCII diagram showing:
-```
-  INPUT ──▶ VALIDATION ──▶ TRANSFORM ──▶ PERSIST ──▶ OUTPUT
-    │            │              │            │           │
-    ▼            ▼              ▼            ▼           ▼
-  [nil?]    [invalid?]    [exception?]  [conflict?]  [stale?]
-  [empty?]  [too long?]   [timeout?]    [dup key?]   [partial?]
-  [wrong    [wrong type?] [OOM?]        [locked?]    [encoding?]
-   type?]
-```
-For each node: what happens on each shadow path? Is it tested?
-
-**Interaction Edge Cases:** For every new user-visible interaction, evaluate:
-```
-  INTERACTION          | EDGE CASE              | HANDLED? | HOW?
-  ---------------------|------------------------|----------|--------
-  Form submission      | Double-click submit    | ?        |
-                       | Submit with stale CSRF | ?        |
-                       | Submit during deploy   | ?        |
-  Async operation      | User navigates away    | ?        |
-                       | Operation times out    | ?        |
-                       | Retry while in-flight  | ?        |
-  List/table view      | Zero results           | ?        |
-                       | 10,000 results         | ?        |
-                       | Results change mid-page| ?        |
-  Background job       | Job fails after 3 of   | ?        |
-                       | 10 items processed     |          |
-                       | Job runs twice (dup)   | ?        |
-                       | Queue backs up 2 hours | ?        |
-```
-Flag any unhandled edge case as a gap. For each gap, specify the fix.
-**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
-**Reminder: Do NOT make any code changes. Review only.**
-
-### Section 5: Code Quality Review
-Evaluate:
-* Code organization and module structure. Does new code fit existing patterns? If it deviates, is there a reason?
-* DRY violations. Be aggressive. If the same logic exists elsewhere, flag it and reference the file and line.
-* Naming quality. Are new classes, methods, and variables named for what they do, not how they do it?
-* Error handling patterns. (Cross-reference with Section 2 — this section reviews the patterns; Section 2 maps the specifics.)
-* Missing edge cases. List explicitly: "What happens when X is nil?" "When the API returns 429?" etc.
-* Over-engineering check. Any new abstraction solving a problem that doesn't exist yet?
-* Under-engineering check. Anything fragile, assuming happy path only, or missing obvious defensive checks?
-* Cyclomatic complexity. Flag any new method that branches more than 5 times. Propose a refactor.
-**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
-**Reminder: Do NOT make any code changes. Review only.**
-
-### Section 6: Test Review
-Make a complete diagram of every new thing this plan introduces:
-```
-  NEW UX FLOWS:
-    [list each new user-visible interaction]
-
-  NEW DATA FLOWS:
-    [list each new path data takes through the system]
-
-  NEW CODEPATHS:
-    [list each new branch, condition, or execution path]
-
-  NEW BACKGROUND JOBS / ASYNC WORK:
-    [list each]
-
-  NEW INTEGRATIONS / EXTERNAL CALLS:
-    [list each]
-
-  NEW ERROR/RESCUE PATHS:
-    [list each — cross-reference Section 2]
-```
-For each item in the diagram:
-* What type of test covers it? (Unit / Integration / System / E2E)
-* Does a test for it exist in the plan? If not, write the test spec header.
-* What is the happy path test?
-* What is the failure path test? (Be specific — which failure?)
-* What is the edge case test? (nil, empty, boundary values, concurrent access)
-
-Test ambition check (all modes): For each new feature, answer:
-* What's the test that would make you confident shipping at 2am on a Friday?
-* What's the test a hostile QA engineer would write to break this?
-* What's the chaos test?
-
-Test pyramid check: Many unit, fewer integration, few E2E? Or inverted?
-Flakiness risk: Flag any test depending on time, randomness, external services, or ordering.
-Load/stress test requirements: For any new codepath called frequently or processing significant data.
-
-For LLM/prompt changes: Check CLAUDE.md for the "Prompt/LLM changes" file patterns. If this plan touches ANY of those patterns, state which eval suites must be run, which cases should be added, and what baselines to compare against.
-**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
-**Reminder: Do NOT make any code changes. Review only.**
-
-### Section 7: Performance Review
-Evaluate:
-* N+1 queries. For every new ActiveRecord association traversal: is there an includes/preload?
-* Memory usage. For every new data structure: what's the maximum size in production?
-* Database indexes. For every new query: is there an index?
-* Caching opportunities. For every expensive computation or external call: should it be cached?
-* Background job sizing. For every new job: worst-case payload, runtime, retry behavior?
-* Slow paths. Top 3 slowest new codepaths and estimated p99 latency.
-* Connection pool pressure. New DB connections, Redis connections, HTTP connections?
-**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
-**Reminder: Do NOT make any code changes. Review only.**
-
-### Section 8: Observability & Debuggability Review
-New systems break. This section ensures you can see why.
-Evaluate:
-* Logging. For every new codepath: structured log lines at entry, exit, and each significant branch?
-* Metrics. For every new feature: what metric tells you it's working? What tells you it's broken?
-* Tracing. For new cross-service or cross-job flows: trace IDs propagated?
-* Alerting. What new alerts should exist?
-* Dashboards. What new dashboard panels do you want on day 1?
-* Debuggability. If a bug is reported 3 weeks post-ship, can you reconstruct what happened from logs alone?
-* Admin tooling. New operational tasks that need admin UI or rake tasks?
-* Runbooks. For each new failure mode: what's the operational response?
-
-**EXPANSION and SELECTIVE EXPANSION addition:**
-* What observability would make this feature a joy to operate? (For SELECTIVE EXPANSION, include observability for any accepted cherry-picks.)
-**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
-**Reminder: Do NOT make any code changes. Review only.**
-
-### Section 9: Deployment & Rollout Review
-Evaluate:
-* Migration safety. For every new DB migration: backward-compatible? Zero-downtime? Table locks?
-* Feature flags. Should any part be behind a feature flag?
-* Rollout order. Correct sequence: migrate first, deploy second?
-* Rollback plan. Explicit step-by-step.
-* Deploy-time risk window. Old code and new code running simultaneously — what breaks?
-* Environment parity. Tested in staging?
-* Post-deploy verification checklist. First 5 minutes? First hour?
-* Smoke tests. What automated checks should run immediately post-deploy?
-
-**EXPANSION and SELECTIVE EXPANSION addition:**
-* What deploy infrastructure would make shipping this feature routine? (For SELECTIVE EXPANSION, assess whether accepted cherry-picks change the deployment risk profile.)
-**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
-**Reminder: Do NOT make any code changes. Review only.**
-
-### Section 10: Long-Term Trajectory Review
-Evaluate:
-* Technical debt introduced. Code debt, operational debt, testing debt, documentation debt.
-* Path dependency. Does this make future changes harder?
-* Knowledge concentration. Documentation sufficient for a new engineer?
-* Reversibility. Rate 1-5: 1 = one-way door, 5 = easily reversible.
-* Ecosystem fit. Aligns with Rails/JS ecosystem direction?
-* The 1-year question. Read this plan as a new engineer in 12 months — obvious?
-
-**EXPANSION and SELECTIVE EXPANSION additions:**
-* What comes after this ships? Phase 2? Phase 3? Does the architecture support that trajectory?
-* Platform potential. Does this create capabilities other features can leverage?
-* (SELECTIVE EXPANSION only) Retrospective: Were the right cherry-picks accepted? Did any rejected expansions turn out to be load-bearing for the accepted ones?
-**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
-**Reminder: Do NOT make any code changes. Review only.**
-
-### Section 11: Design & UX Review (skip if no UI scope detected)
-The CEO calling in the designer. Not a pixel-level audit — that's /plan-design-review and /design-review. This is ensuring the plan has design intentionality.
-
-Evaluate:
-* Information architecture — what does the user see first, second, third?
-* Interaction state coverage map:
-  FEATURE | LOADING | EMPTY | ERROR | SUCCESS | PARTIAL
-* User journey coherence — storyboard the emotional arc
-* AI slop risk — does the plan describe generic UI patterns?
-* DESIGN.md alignment — does the plan match the stated design system?
-* Responsive intention — is mobile mentioned or afterthought?
-* Accessibility basics — keyboard nav, screen readers, contrast, touch targets
-
-**EXPANSION and SELECTIVE EXPANSION additions:**
-* What would make this UI feel *inevitable*?
-* What 30-minute UI touches would make users think "oh nice, they thought of that"?
-
-Required ASCII diagram: user flow showing screens/states and transitions.
-
-If this plan has significant UI scope, recommend: "Consider running /plan-design-review for a deep design review of this plan before implementation."
-**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
-**Reminder: Do NOT make any code changes. Review only.**
-
-## Outside Voice — Independent Plan Challenge (optional, recommended)
-
-After all review sections are complete, offer an independent second opinion from a
-different AI system. Two models agreeing on a plan is stronger signal than one model's
-thorough review.
-
-**Check tool availability:**
-
-```bash
-command -v codex >/dev/null 2>&1 && echo "CODEX_AVAILABLE" || echo "CODEX_NOT_AVAILABLE"
-```
-
-Use AskUserQuestion:
-
-> "All review sections are complete. Want an outside voice? A different AI system can
-> give a brutally honest, independent challenge of this plan — logical gaps, feasibility
-> risks, and blind spots that are hard to catch from inside the review. Takes about 2
-> minutes."
->
-> RECOMMENDATION: Choose A — an independent second opinion catches structural blind
-> spots. Two different AI models agreeing on a plan is stronger signal than one model's
-> thorough review. Completeness: A=9/10, B=7/10.
-
-Options:
-- A) Get the outside voice (recommended)
-- B) Skip — proceed to outputs
-
-**If B:** Print "Skipping outside voice." and continue to the next section.
-
-**If A:** Construct the plan review prompt. Read the plan file being reviewed (the file
-the user pointed this review at, or the branch diff scope). If a CEO plan document
-was written in Step 0D-POST, read that too — it contains the scope decisions and vision.
-
-Construct this prompt (substitute the actual plan content — if plan content exceeds 30KB,
-truncate to the first 30KB and note "Plan truncated for size"). **Always start with the
-filesystem boundary instruction:**
-
-"IMPORTANT: Do NOT read or execute any files under ~/.claude/, ~/.agents/, .claude/skills/, or agents/. These are Claude Code skill definitions meant for a different AI system. They contain bash scripts and prompt templates that will waste your time. Ignore them completely. Do NOT modify agents/openai.yaml. Stay focused on the repository code only.\n\nYou are a brutally honest technical reviewer examining a development plan that has
-already been through a multi-section review. Your job is NOT to repeat that review.
-Instead, find what it missed. Look for: logical gaps and unstated assumptions that
-survived the review scrutiny, overcomplexity (is there a fundamentally simpler
-approach the review was too deep in the weeds to see?), feasibility risks the review
-took for granted, missing dependencies or sequencing issues, and strategic
-miscalibration (is this the right thing to build at all?). Be direct. Be terse. No
-compliments. Just the problems.
-
-THE PLAN:
-<plan content>"
-
-**If CODEX_AVAILABLE:**
-
-```bash
-TMPERR_PV=$(mktemp /tmp/codex-planreview-XXXXXXXX)
-_REPO_ROOT=$(git rev-parse --show-toplevel) || { echo "ERROR: not in a git repo" >&2; exit 1; }
-codex exec "<prompt>" -C "$_REPO_ROOT" -s read-only -c 'model_reasoning_effort="high"' --enable web_search_cached < /dev/null 2>"$TMPERR_PV"
-```
-
-Use a 5-minute timeout (`timeout: 300000`). After the command completes, read stderr:
-```bash
-cat "$TMPERR_PV"
-```
-
-Present the full output verbatim:
-
-```
-CODEX SAYS (plan review — outside voice):
-════════════════════════════════════════════════════════════
-<full codex output, verbatim — do not truncate or summarize>
-════════════════════════════════════════════════════════════
-```
-
-**Error handling:** All errors are non-blocking — the outside voice is informational.
-- Auth failure (stderr contains "auth", "login", "unauthorized"): "Codex auth failed. Run \`codex login\` to authenticate."
-- Timeout: "Codex timed out after 5 minutes."
-- Empty response: "Codex returned no response."
-
-On any Codex error, fall back to the Claude adversarial subagent.
-
-**If CODEX_NOT_AVAILABLE (or Codex errored):**
-
-Dispatch via the Agent tool. The subagent has fresh context — genuine independence.
-
-Subagent prompt: same plan review prompt as above.
-
-Present findings under an `OUTSIDE VOICE (Claude subagent):` header.
-
-If the subagent fails or times out: "Outside voice unavailable. Continuing to outputs."
-
-**Cross-model tension:**
-
-After presenting the outside voice findings, note any points where the outside voice
-disagrees with the review findings from earlier sections. Flag these as:
-
-```
-CROSS-MODEL TENSION:
-  [Topic]: Review said X. Outside voice says Y. [Present both perspectives neutrally.
-  State what context you might be missing that would change the answer.]
-```
-
-**User Sovereignty:** Do NOT auto-incorporate outside voice recommendations into the plan.
-Present each tension point to the user. The user decides. Cross-model agreement is a
-strong signal — present it as such — but it is NOT permission to act. You may state
-which argument you find more compelling, but you MUST NOT apply the change without
-explicit user approval.
-
-For each substantive tension point, use AskUserQuestion:
-
-> "Cross-model disagreement on [topic]. The review found [X] but the outside voice
-> argues [Y]. [One sentence on what context you might be missing.]"
->
-> RECOMMENDATION: Choose [A or B] because [one-line reason explaining which argument
-> is more compelling and why]. Completeness: A=X/10, B=Y/10.
-
-Options:
-- A) Accept the outside voice's recommendation (I'll apply this change)
-- B) Keep the current approach (reject the outside voice)
-- C) Investigate further before deciding
-- D) Add to TODOS.md for later
-
-Wait for the user's response. Do NOT default to accepting because you agree with the
-outside voice. If the user chooses B, the current approach stands — do not re-argue.
-
-If no tension points exist, note: "No cross-model tension — both reviewers agree."
-
-**Persist the result:**
-```bash
-~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"codex-plan-review","timestamp":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'","status":"STATUS","source":"SOURCE","commit":"'"$(git rev-parse --short HEAD)"'"}'
-```
-
-Substitute: STATUS = "clean" if no findings, "issues_found" if findings exist.
-SOURCE = "codex" if Codex ran, "claude" if subagent ran.
-
-**Cleanup:** Run `rm -f "$TMPERR_PV"` after processing (if Codex was used).
-
----
-
-### Outside Voice Integration Rule
-
-Outside voice findings are INFORMATIONAL until the user explicitly approves each one.
-Do NOT incorporate outside voice recommendations into the plan without presenting each
-finding via AskUserQuestion and getting explicit approval. This applies even when you
-agree with the outside voice. Cross-model consensus is a strong signal — present it as
-such — but the user makes the decision.
-
-## Post-Implementation Design Audit (if UI scope detected)
-After implementation, run `/design-review` on the live site to catch visual issues that can only be evaluated with rendered output.
-
-## CRITICAL RULE — How to ask questions
-Follow the AskUserQuestion format from the Preamble above. Additional rules for plan reviews:
-* **One issue = one AskUserQuestion call.** Never combine multiple issues into one question.
-* Describe the problem concretely, with file and line references.
-* Present 2-3 options, including "do nothing" where reasonable.
-* For each option: effort, risk, and maintenance burden in one line.
-* **Map the reasoning to my engineering preferences above.** One sentence connecting your recommendation to a specific preference.
-* Label with issue NUMBER + option LETTER (e.g., "3A", "3B").
-* **Zero findings:** if a section has zero findings, state "No issues, moving on" and proceed. Otherwise, use AskUserQuestion for each finding — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan.
-
-## Required Outputs
-
-### "NOT in scope" section
-List work considered and explicitly deferred, with one-line rationale each.
-
-### "What already exists" section
-List existing code/flows that partially solve sub-problems and whether the plan reuses them.
-
-### "Dream state delta" section
-Where this plan leaves us relative to the 12-month ideal.
-
-### Error & Rescue Registry (from Section 2)
-Complete table of every method that can fail, every exception class, rescued status, rescue action, user impact.
-
-### Failure Modes Registry
-```
-  CODEPATH | FAILURE MODE   | RESCUED? | TEST? | USER SEES?     | LOGGED?
-  ---------|----------------|----------|-------|----------------|--------
-```
-Any row with RESCUED=N, TEST=N, USER SEES=Silent → **CRITICAL GAP**.
-
-### TODOS.md updates
-Present each potential TODO as its own individual AskUserQuestion. Never batch TODOs — one per question. Never silently skip this step. Follow the format in `.claude/skills/review/TODOS-format.md`.
-
-For each TODO, describe:
-* **What:** One-line description of the work.
-* **Why:** The concrete problem it solves or value it unlocks.
-* **Pros:** What you gain by doing this work.
-* **Cons:** Cost, complexity, or risks of doing it.
-* **Context:** Enough detail that someone picking this up in 3 months understands the motivation, the current state, and where to start.
-* **Effort estimate:** S/M/L/XL (human team) → with CC+gstack: S→S, M→S, L→M, XL→L
-* **Priority:** P1/P2/P3
-* **Depends on / blocked by:** Any prerequisites or ordering constraints.
-
-Then present options: **A)** Add to TODOS.md **B)** Skip — not valuable enough **C)** Build it now in this PR instead of deferring.
-
-### Scope Expansion Decisions (EXPANSION and SELECTIVE EXPANSION only)
-For EXPANSION and SELECTIVE EXPANSION modes: expansion opportunities and delight items were surfaced and decided in Step 0D (opt-in/cherry-pick ceremony). The decisions are persisted in the CEO plan document. Reference the CEO plan for the full record. Do not re-surface them here — list the accepted expansions for completeness:
-* Accepted: {list items added to scope}
-* Deferred: {list items sent to TODOS.md}
-* Skipped: {list items rejected}
-
-### Diagrams (mandatory, produce all that apply)
-1. System architecture
-2. Data flow (including shadow paths)
-3. State machine
-4. Error flow
-5. Deployment sequence
-6. Rollback flowchart
-
-### Stale Diagram Audit
-List every ASCII diagram in files this plan touches. Still accurate?
-
-## Implementation Tasks
-
-Before closing this review, synthesize the findings above into a flat list of
-build-actionable tasks. Each task derives from a specific finding — no padding.
-Emit the markdown section AND write a JSONL artifact that `/autoplan` can
-aggregate across phases.
-
-### Markdown section (always emit)
-
-```markdown
-## Implementation Tasks
-Synthesized from this review's findings. Each task derives from a specific
-finding above. Run with Claude Code or Codex; checkbox as you ship.
-
-- [ ] **T1 (P1, human: ~2h / CC: ~15min)** — <component> — <imperative title>
-  - Surfaced by: <section name> — <specific finding text or line reference>
-  - Files: <paths to touch>
-  - Verify: <test command or manual check>
-- [ ] **T2 (P2, human: ~30min / CC: ~5min)** — ...
-```
-
-Rules:
-- P1 blocks ship; P2 should land same branch; P3 is a follow-up TODO.
-- If a finding produced no actionable task, do not invent one.
-- If a section had zero findings, emit `_No new tasks from <section>._`
-- Effort uses the AI-compression table from CLAUDE.md.
-
-### JSONL artifact (always write, even if zero tasks)
-
-`/autoplan` reads this file to aggregate across phases. Build each line with
-`jq -nc` so titles and source findings containing quotes, newlines, or
-backslashes serialize cleanly — never use hand-rolled `echo` / `printf`.
-
-```bash
-eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)"
-TASKS_DIR="${HOME}/.gstack/projects/${SLUG:-unknown}"
-mkdir -p "$TASKS_DIR"
-TASKS_FILE="$TASKS_DIR/tasks-ceo-review-$(date +%Y%m%d-%H%M%S).jsonl"
-COMMIT=$(git rev-parse HEAD 2>/dev/null || echo unknown)
-BRANCH=$(git branch --show-current 2>/dev/null || echo unknown)
-RUN_ID="$(date -u +%Y%m%dT%H%M%SZ)-$$"
-
-# Repeat ONE jq invocation per task identified during this review.
-# Substitute the placeholders inline with shell variables you set per task:
-#   TASK_ID (T1, T2, ...), PRIORITY (P1/P2/P3), COMPONENT, TITLE,
-#   SOURCE_FINDING, EFFORT_HUMAN, EFFORT_CC, FILES_JSON (a JSON array literal
-#   like '["browse/src/sanitize.ts","browse/src/server.ts"]').
-jq -nc \
-  --arg phase 'ceo-review' \
-  --arg run_id "$RUN_ID" \
-  --arg branch "$BRANCH" \
-  --arg commit "$COMMIT" \
-  --arg id "$TASK_ID" \
-  --arg priority "$PRIORITY" \
-  --arg component "$COMPONENT" \
-  --arg effort_human "$EFFORT_HUMAN" \
-  --arg effort_cc "$EFFORT_CC" \
-  --arg title "$TITLE" \
-  --arg source_finding "$SOURCE_FINDING" \
-  --argjson files "$FILES_JSON" \
-  '{phase:$phase, run_id:$run_id, branch:$branch, commit:$commit, id:$id, priority:$priority, component:$component, files:$files, effort_human:$effort_human, effort_cc:$effort_cc, title:$title, source_finding:$source_finding}' \
-  >> "$TASKS_FILE"
-```
-
-If `jq` is not installed, fall back to skipping the JSONL write and warn
-the user to install jq for autoplan aggregation. Never hand-roll JSONL.
-
-If zero tasks were identified in this review, still touch the JSONL file
-(`: > "$TASKS_FILE"`) so the aggregator sees that the phase produced output
-this run (an empty file means "ran, no findings" — distinct from "didn't run").
-
-
-### Completion Summary
-```
-  +====================================================================+
-  |            MEGA PLAN REVIEW — COMPLETION SUMMARY                   |
-  +====================================================================+
-  | Mode selected        | EXPANSION / SELECTIVE / HOLD / REDUCTION     |
-  | System Audit         | [key findings]                              |
-  | Step 0               | [mode + key decisions]                      |
-  | Section 1  (Arch)    | ___ issues found                            |
-  | Section 2  (Errors)  | ___ error paths mapped, ___ GAPS            |
-  | Section 3  (Security)| ___ issues found, ___ High severity         |
-  | Section 4  (Data/UX) | ___ edge cases mapped, ___ unhandled        |
-  | Section 5  (Quality) | ___ issues found                            |
-  | Section 6  (Tests)   | Diagram produced, ___ gaps                  |
-  | Section 7  (Perf)    | ___ issues found                            |
-  | Section 8  (Observ)  | ___ gaps found                              |
-  | Section 9  (Deploy)  | ___ risks flagged                           |
-  | Section 10 (Future)  | Reversibility: _/5, debt items: ___         |
-  | Section 11 (Design)  | ___ issues / SKIPPED (no UI scope)          |
-  +--------------------------------------------------------------------+
-  | NOT in scope         | written (___ items)                          |
-  | What already exists  | written                                     |
-  | Dream state delta    | written                                     |
-  | Error/rescue registry| ___ methods, ___ CRITICAL GAPS              |
-  | Failure modes        | ___ total, ___ CRITICAL GAPS                |
-  | TODOS.md updates     | ___ items proposed                          |
-  | Scope proposals      | ___ proposed, ___ accepted (EXP + SEL)      |
-  | CEO plan             | written / skipped (HOLD/REDUCTION)           |
-  | Outside voice        | ran (codex/claude) / skipped                 |
-  | Lake Score           | X/Y recommendations chose complete option   |
-  | Diagrams produced    | ___ (list types)                            |
-  | Stale diagrams found | ___                                         |
-  | Unresolved decisions | ___ (listed below)                          |
-  +====================================================================+
-```
-
-### Unresolved Decisions
-If any AskUserQuestion goes unanswered, note it here. Never silently default.
-
-## Handoff Note Cleanup
-
-After producing the Completion Summary, clean up any handoff notes for this branch —
-the review is complete and the context is no longer needed.
-
-```bash
-setopt +o nomatch 2>/dev/null || true  # zsh compat
-eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)"
-rm -f ~/.gstack/projects/$SLUG/*-$BRANCH-ceo-handoff-*.md 2>/dev/null || true
-```
-
-## Review Log
-
-After producing the Completion Summary above, persist the review result.
-
-**PLAN MODE EXCEPTION — ALWAYS RUN:** This command writes review metadata to
-`~/.gstack/` (user config directory, not project files). The skill preamble
-already writes to `~/.gstack/sessions/` and `~/.gstack/analytics/` — this is
-the same pattern. The review dashboard depends on this data. Skipping this
-command breaks the review readiness dashboard in /ship.
-
-```bash
-~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"plan-ceo-review","timestamp":"TIMESTAMP","status":"STATUS","unresolved":N,"critical_gaps":N,"mode":"MODE","scope_proposed":N,"scope_accepted":N,"scope_deferred":N,"commit":"COMMIT"}'
-```
-
-Before running this command, substitute the placeholder values from the Completion Summary you just produced:
-- **TIMESTAMP**: current ISO 8601 datetime (e.g., 2026-03-16T14:30:00)
-- **STATUS**: "clean" if 0 unresolved decisions AND 0 critical gaps; otherwise "issues_open"
-- **unresolved**: number from "Unresolved decisions" in the summary
-- **critical_gaps**: number from "Failure modes: ___ CRITICAL GAPS" in the summary
-- **MODE**: the mode the user selected (SCOPE_EXPANSION / SELECTIVE_EXPANSION / HOLD_SCOPE / SCOPE_REDUCTION)
-- **scope_proposed**: number from "Scope proposals: ___ proposed" in the summary (0 for HOLD/REDUCTION)
-- **scope_accepted**: number from "Scope proposals: ___ accepted" in the summary (0 for HOLD/REDUCTION)
-- **scope_deferred**: number of items deferred to TODOS.md from scope decisions (0 for HOLD/REDUCTION)
-- **COMMIT**: output of `git rev-parse --short HEAD`
-
-## Review Readiness Dashboard
-
-After completing the review, read the review log and config to display the dashboard.
-
-```bash
-~/.claude/skills/gstack/bin/gstack-review-read
-```
-
-Parse the output. Find the most recent entry for each skill (plan-ceo-review, plan-eng-review, review, plan-design-review, design-review-lite, adversarial-review, codex-review, codex-plan-review). Ignore entries with timestamps older than 7 days. For the Eng Review row, show whichever is more recent between `review` (diff-scoped pre-landing review) and `plan-eng-review` (plan-stage architecture review). Append "(DIFF)" or "(PLAN)" to the status to distinguish. For the Adversarial row, show whichever is more recent between `adversarial-review` (new auto-scaled) and `codex-review` (legacy). For Design Review, show whichever is more recent between `plan-design-review` (full visual audit) and `design-review-lite` (code-level check). Append "(FULL)" or "(LITE)" to the status to distinguish. For the Outside Voice row, show the most recent `codex-plan-review` entry — this captures outside voices from both /plan-ceo-review and /plan-eng-review.
-
-**Source attribution:** If the most recent entry for a skill has a \`"via"\` field, append it to the status label in parentheses. Examples: `plan-eng-review` with `via:"autoplan"` shows as "CLEAR (PLAN via /autoplan)". `review` with `via:"ship"` shows as "CLEAR (DIFF via /ship)". Entries without a `via` field show as "CLEAR (PLAN)" or "CLEAR (DIFF)" as before.
-
-Note: `autoplan-voices` and `design-outside-voices` entries are audit-trail-only (forensic data for cross-model consensus analysis). They do not appear in the dashboard and are not checked by any consumer.
-
-Display:
-
-```
-+====================================================================+
-|                    REVIEW READINESS DASHBOARD                       |
-+====================================================================+
-| Review          | Runs | Last Run            | Status    | Required |
-|-----------------|------|---------------------|-----------|----------|
-| Eng Review      |  1   | 2026-03-16 15:00    | CLEAR     | YES      |
-| CEO Review      |  0   | —                   | —         | no       |
-| Design Review   |  0   | —                   | —         | no       |
-| Adversarial     |  0   | —                   | —         | no       |
-| Outside Voice   |  0   | —                   | —         | no       |
-+--------------------------------------------------------------------+
-| VERDICT: CLEARED — Eng Review passed                                |
-+====================================================================+
-```
-
-**Review tiers:**
-- **Eng Review (required by default):** The only review that gates shipping. Covers architecture, code quality, tests, performance. Can be disabled globally with \`gstack-config set skip_eng_review true\` (the "don't bother me" setting).
-- **CEO Review (optional):** Use your judgment. Recommend it for big product/business changes, new user-facing features, or scope decisions. Skip for bug fixes, refactors, infra, and cleanup.
-- **Design Review (optional):** Use your judgment. Recommend it for UI/UX changes. Skip for backend-only, infra, or prompt-only changes.
-- **Adversarial Review (automatic):** Always-on for every review. Every diff gets both Claude adversarial subagent and Codex adversarial challenge. Large diffs (200+ lines) additionally get Codex structured review with P1 gate. No configuration needed.
-- **Outside Voice (optional):** Independent plan review from a different AI model. Offered after all review sections complete in /plan-ceo-review and /plan-eng-review. Falls back to Claude subagent if Codex is unavailable. Never gates shipping.
-
-**Verdict logic:**
-- **CLEARED**: Eng Review has >= 1 entry within 7 days from either \`review\` or \`plan-eng-review\` with status "clean" (or \`skip_eng_review\` is \`true\`)
-- **NOT CLEARED**: Eng Review missing, stale (>7 days), or has open issues
-- CEO, Design, and Codex reviews are shown for context but never block shipping
-- If \`skip_eng_review\` config is \`true\`, Eng Review shows "SKIPPED (global)" and verdict is CLEARED
-
-**Staleness detection:** After displaying the dashboard, check if any existing reviews may be stale:
-- Parse the \`---HEAD---\` section from the bash output to get the current HEAD commit hash
-- For each review entry that has a \`commit\` field: compare it against the current HEAD. If different, count elapsed commits: \`git rev-list --count STORED_COMMIT..HEAD\`. Display: "Note: {skill} review from {date} may be stale — {N} commits since review"
-- For entries without a \`commit\` field (legacy entries): display "Note: {skill} review from {date} has no commit tracking — consider re-running for accurate staleness detection"
-- If all reviews match the current HEAD, do not display any staleness notes
-
-## Plan File Review Report
-
-After displaying the Review Readiness Dashboard in conversation output, also update the
-**plan file** itself so review status is visible to anyone reading the plan.
-
-### Detect the plan file
-
-1. Check if there is an active plan file in this conversation (the host provides plan file
-   paths in system messages — look for plan file references in the conversation context).
-2. If not found, skip this section silently — not every review runs in plan mode.
-
-### Generate the report
-
-Read the review log output you already have from the Review Readiness Dashboard step above.
-Parse each JSONL entry. Each skill logs different fields:
-
-- **plan-ceo-review**: \`status\`, \`unresolved\`, \`critical_gaps\`, \`mode\`, \`scope_proposed\`, \`scope_accepted\`, \`scope_deferred\`, \`commit\`
-  → Findings: "{scope_proposed} proposals, {scope_accepted} accepted, {scope_deferred} deferred"
-  → If scope fields are 0 or missing (HOLD/REDUCTION mode): "mode: {mode}, {critical_gaps} critical gaps"
-- **plan-eng-review**: \`status\`, \`unresolved\`, \`critical_gaps\`, \`issues_found\`, \`mode\`, \`commit\`
-  → Findings: "{issues_found} issues, {critical_gaps} critical gaps"
-- **plan-design-review**: \`status\`, \`initial_score\`, \`overall_score\`, \`unresolved\`, \`decisions_made\`, \`commit\`
-  → Findings: "score: {initial_score}/10 → {overall_score}/10, {decisions_made} decisions"
-- **plan-devex-review**: \`status\`, \`initial_score\`, \`overall_score\`, \`product_type\`, \`tthw_current\`, \`tthw_target\`, \`mode\`, \`persona\`, \`competitive_tier\`, \`unresolved\`, \`commit\`
-  → Findings: "score: {initial_score}/10 → {overall_score}/10, TTHW: {tthw_current} → {tthw_target}"
-- **devex-review**: \`status\`, \`overall_score\`, \`product_type\`, \`tthw_measured\`, \`dimensions_tested\`, \`dimensions_inferred\`, \`boomerang\`, \`commit\`
-  → Findings: "score: {overall_score}/10, TTHW: {tthw_measured}, {dimensions_tested} tested/{dimensions_inferred} inferred"
-- **codex-review**: \`status\`, \`gate\`, \`findings\`, \`findings_fixed\`
-  → Findings: "{findings} findings, {findings_fixed}/{findings} fixed"
-
-All fields needed for the Findings column are now present in the JSONL entries.
-For the review you just completed, you may use richer details from your own Completion
-Summary. For prior reviews, use the JSONL fields directly — they contain all required data.
-
-Produce this markdown table:
-
-\`\`\`markdown
-## GSTACK REVIEW REPORT
-
-| Review | Trigger | Why | Runs | Status | Findings |
-|--------|---------|-----|------|--------|----------|
-| CEO Review | \`/plan-ceo-review\` | Scope & strategy | {runs} | {status} | {findings} |
-| Codex Review | \`/codex review\` | Independent 2nd opinion | {runs} | {status} | {findings} |
-| Eng Review | \`/plan-eng-review\` | Architecture & tests (required) | {runs} | {status} | {findings} |
-| Design Review | \`/plan-design-review\` | UI/UX gaps | {runs} | {status} | {findings} |
-| DX Review | \`/plan-devex-review\` | Developer experience gaps | {runs} | {status} | {findings} |
-\`\`\`
-
-Below the table, add these lines (omit any that are empty/not applicable):
-
-- **CODEX:** (only if codex-review ran) — one-line summary of codex fixes
-- **CROSS-MODEL:** (only if both Claude and Codex reviews exist) — overlap analysis
-- **UNRESOLVED:** total unresolved decisions across all reviews
-- **VERDICT:** list reviews that are CLEAR (e.g., "CEO + ENG CLEARED — ready to implement").
-  If Eng Review is not CLEAR and not skipped globally, append "eng review required".
-
-### Write to the plan file
-
-**PLAN MODE EXCEPTION — ALWAYS RUN:** This writes to the plan file, which is the one
-file you are allowed to edit in plan mode. The plan file review report is part of the
-plan's living status.
-
-The report must always be the LAST section of the plan file — never mid-file.
-Use a single delete-then-append flow:
-
-1. Read the plan file (Read tool) to see its full current content. Search the read
-   output for a \`## GSTACK REVIEW REPORT\` heading anywhere in the file.
-2. If found, use the Edit tool to DELETE the entire existing section. Match from
-   \`## GSTACK REVIEW REPORT\` through either the next \`## \` heading or end of
-   file, whichever comes first. Replace with the empty string. This applies
-   regardless of where the section currently lives — mid-file deletion is
-   intentional, not a special case. If the Edit fails (e.g., concurrent edit
-   changed the content), re-read the plan file and retry once.
-3. After the delete (or skipped, if no section existed), append the new
-   \`## GSTACK REVIEW REPORT\` section at the END of the file. Use the Edit
-   tool to match the file's current last paragraph and add the section after it,
-   or use Write to re-emit the whole file with the section at the end.
-4. Verify with the Read tool that \`## GSTACK REVIEW REPORT\` is the last
-   \`## \` heading in the file before continuing. If it isn't, repeat steps
-   2-3 once.
-
-Do NOT replace the section in place. The "replace mid-file" path is what allowed
-prior versions to leave the report mid-file when an older report already lived
-there — the user then sees a plan whose review report is not at the bottom and
-(correctly) rejects it.
-
-## Next Steps — Review Chaining
-
-After displaying the Review Readiness Dashboard, recommend the next review(s) based on what this CEO review discovered. Read the dashboard output to see which reviews have already been run and whether they are stale.
-
-**Recommend /plan-eng-review if eng review is not skipped globally** — check the dashboard output for `skip_eng_review`. If it is `true`, eng review is opted out — do not recommend it. Otherwise, eng review is the required shipping gate. If this CEO review expanded scope, changed architectural direction, or accepted scope expansions, emphasize that a fresh eng review is needed. If an eng review already exists in the dashboard but the commit hash shows it predates this CEO review, note that it may be stale and should be re-run.
-
-**Recommend /plan-design-review if UI scope was detected** — specifically if Section 11 (Design & UX Review) was NOT skipped, or if accepted scope expansions included UI-facing features. If an existing design review is stale (commit hash drift), note that. In SCOPE REDUCTION mode, skip this recommendation — design review is unlikely relevant for scope cuts.
-
-**If both are needed, recommend eng review first** (required gate), then design review.
-
-Use AskUserQuestion to present the next step. Include only applicable options:
-- **A)** Run /plan-eng-review next (required gate)
-- **B)** Run /plan-design-review next (only if UI scope detected)
-- **C)** Skip — I'll handle reviews manually
-
-## docs/designs Promotion (EXPANSION and SELECTIVE EXPANSION only)
-
-At the end of the review, if the vision produced a compelling feature direction, offer to promote the CEO plan to the project repo. AskUserQuestion:
-
-"The vision from this review produced {N} accepted scope expansions. Want to promote it to a design doc in the repo?"
-- **A)** Promote to `docs/designs/{FEATURE}.md` (committed to repo, visible to the team)
-- **B)** Keep in `~/.gstack/projects/` only (local, personal reference)
-- **C)** Skip
-
-If promoted, copy the CEO plan content to `docs/designs/{FEATURE}.md` (create the directory if needed) and update the `status` field in the original CEO plan from `ACTIVE` to `PROMOTED`.
-
-## Formatting Rules
-* NUMBER issues (1, 2, 3...) and LETTERS for options (A, B, C...).
-* Label with NUMBER + LETTER (e.g., "3A", "3B").
-* One sentence max per option.
-* After each section, pause and wait for feedback.
-* Use **CRITICAL GAP** / **WARNING** / **OK** for scannability.
-
-## Capture Learnings
-
-If you discovered a non-obvious pattern, pitfall, or architectural insight during
-this session, log it for future sessions:
-
-```bash
-~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"plan-ceo-review","type":"TYPE","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"SOURCE","files":["path/to/relevant/file"]}'
-```
-
-**Types:** `pattern` (reusable approach), `pitfall` (what NOT to do), `preference`
-(user stated), `architecture` (structural decision), `tool` (library/framework insight),
-`operational` (project environment/CLI/workflow knowledge).
-
-**Sources:** `observed` (you found this in the code), `user-stated` (user told you),
-`inferred` (AI deduction), `cross-model` (both Claude and Codex agree).
-
-**Confidence:** 1-10. Be honest. An observed pattern you verified in the code is 8-9.
-An inference you're not sure about is 4-5. A user preference they explicitly stated is 10.
-
-**files:** Include the specific file paths this learning references. This enables
-staleness detection: if those files are later deleted, the learning can be flagged.
-
-**Only log genuine discoveries.** Don't log obvious things. Don't log things the user
-already knows. A good test: would this insight save time in a future session? If yes, log it.
-
-
-
-## Brain Calibration Write-Back (Phase 2 / gated)
-
-When the skill makes a typed prediction worth tracking (scope decision,
-TTHW target, architectural bet, wedge commitment), it MAY write a
-`kind=bet` take to the brain so a calibration profile builds over time.
-
-**Gated on two things:**
-1. Brain trust policy for the active endpoint is `personal` (check via
-   `~/.claude/skills/gstack/bin/gstack-config get brain_trust_policy@<endpoint-hash>`).
-   Shared brains skip write-back to avoid polluting team calibration.
-2. Feature flag `BRAIN_CALIBRATION_WRITEBACK` is set (today: false; flips
-   to true when upstream gbrain v0.42+ ships `takes_add` MCP op).
-
-When both gates pass, the write-back path uses `mcp__gbrain__takes_add`
-to record a take with weight 0.8 (per SKILL_CALIBRATION_WEIGHTS).
-If the MCP op is unavailable, fall back to `mcp__gbrain__put_page` with
-a gstack:takes fence block (documented but uglier path).
-
-Mandatory take frontmatter shape:
-```yaml
-kind: bet
-holder: <user identity from whoami>
-claim: <one-line prediction the skill is making>
-weight: 0.8
-since_date: <today's date>
-expected_resolution: <date in 1-3 months depending on skill>
-source_skill: plan-ceo-review
-```
-
-After write, invalidate the affected digests so the next preflight reflects
-the new state:
-
-```bash
-eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true
-  ~/.claude/skills/gstack/bin/gstack-brain-cache invalidate product --project "$SLUG" 2>/dev/null || true
-  ~/.claude/skills/gstack/bin/gstack-brain-cache invalidate goals --project "$SLUG" 2>/dev/null || true
-  ~/.claude/skills/gstack/bin/gstack-brain-cache invalidate competitive-intel --project "$SLUG" 2>/dev/null || true
-```
-
-
-## Brain Cache Background Refresh
-
-After the skill's work completes (and telemetry has logged), kick a
-background refresh of any cache digest that's getting close to its TTL.
-This is non-blocking — the user doesn't wait. Next invocation benefits
-from the warm cache.
-
-```bash
-eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true
-(~/.claude/skills/gstack/bin/gstack-brain-cache refresh --project "$SLUG" 2>/dev/null &) || true
-```
-
-
-## Mode Quick Reference
-```
-  ┌────────────────────────────────────────────────────────────────────────────────┐
-  │                            MODE COMPARISON                                     │
-  ├─────────────┬──────────────┬──────────────┬──────────────┬────────────────────┤
-  │             │  EXPANSION   │  SELECTIVE   │  HOLD SCOPE  │  REDUCTION         │
-  ├─────────────┼──────────────┼──────────────┼──────────────┼────────────────────┤
-  │ Scope       │ Push UP      │ Hold + offer │ Maintain     │ Push DOWN          │
-  │             │ (opt-in)     │              │              │                    │
-  │ Recommend   │ Enthusiastic │ Neutral      │ N/A          │ N/A                │
-  │ posture     │              │              │              │                    │
-  │ 10x check   │ Mandatory    │ Surface as   │ Optional     │ Skip               │
-  │             │              │ cherry-pick  │              │                    │
-  │ Platonic    │ Yes          │ No           │ No           │ No                 │
-  │ ideal       │              │              │              │                    │
-  │ Delight     │ Opt-in       │ Cherry-pick  │ Note if seen │ Skip               │
-  │ opps        │ ceremony     │ ceremony     │              │                    │
-  │ Complexity  │ "Is it big   │ "Is it right │ "Is it too   │ "Is it the bare    │
-  │ question    │  enough?"    │  + what else │  complex?"   │  minimum?"         │
-  │             │              │  is tempting"│              │                    │
-  │ Taste       │ Yes          │ Yes          │ No           │ No                 │
-  │ calibration │              │              │              │                    │
-  │ Temporal    │ Full (hr 1-6)│ Full (hr 1-6)│ Key decisions│ Skip               │
-  │ interrogate │              │              │  only        │                    │
-  │ Observ.     │ "Joy to      │ "Joy to      │ "Can we      │ "Can we see if     │
-  │ standard    │  operate"    │  operate"    │  debug it?"  │  it's broken?"     │
-  │ Deploy      │ Infra as     │ Safe deploy  │ Safe deploy  │ Simplest possible  │
-  │ standard    │ feature scope│ + cherry-pick│  + rollback  │  deploy            │
-  │             │              │  risk check  │              │                    │
-  │ Error map   │ Full + chaos │ Full + chaos │ Full         │ Critical paths     │
-  │             │  scenarios   │ for accepted │              │  only              │
-  │ CEO plan    │ Written      │ Written      │ Skipped      │ Skipped            │
-  │ Phase 2/3   │ Map accepted │ Map accepted │ Note it      │ Skip               │
-  │ planning    │              │ cherry-picks │              │                    │
-  │ Design      │ "Inevitable" │ If UI scope  │ If UI scope  │ Skip               │
-  │ (Sec 11)    │  UI review   │  detected    │  detected    │                    │
-  └─────────────┴──────────────┴──────────────┴──────────────┴────────────────────┘
-```
 
 ## EXIT PLAN MODE GATE (BLOCKING)
 

plan-ceo-review/SKILL.md.tmpl

@@ -224,6 +224,8 @@ Feed into the Premise Challenge (0A) and Dream State Mapping (0C). If you find a
 
 {{BRAIN_PREFLIGHT}}
 
+{{SECTION_INDEX:plan-ceo-review}}
+
 ## Step 0: Nuclear Scope Challenge + Mode Selection
 
 ### 0A. Premise Challenge
@@ -409,494 +411,16 @@ Present these mode options via AskUserQuestion using the preamble's AskUserQuest
 **STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
 **Reminder: Do NOT make any code changes. Review only.**
 
-## Review Sections (11 sections, after scope and mode are agreed)
+{{SECTION:review-sections}}
 
-**Anti-skip rule:** Never condense, abbreviate, or skip any review section (1-11) regardless of plan type (strategy, spec, code, infra). Every section in this skill exists for a reason. "This is a strategy doc so implementation sections don't apply" is always wrong — implementation details are where strategy breaks down. If a section genuinely has zero findings, say "No issues found" and move on — but you must evaluate it.
+## Section self-check (before you finish)
 
-{{ANTI_SHORTCUT_CLAUSE}}
+You ran a carved skill. The Section index above named `sections/review-sections.md`
+as the source of truth for the 11-section deep review, the required outputs, and the
+review report. Confirm you issued a Read for it and executed every section from the
+file, not from memory. If you produced the Completion Summary or wrote the review
+report without Reading that section, STOP, Read it now, and redo the review from the
+source of truth.
 
-### Section 1: Architecture Review
-Evaluate and diagram:
-* Overall system design and component boundaries. Draw the dependency graph.
-* Data flow — all four paths. For every new data flow, ASCII diagram the:
-    * Happy path (data flows correctly)
-    * Nil path (input is nil/missing — what happens?)
-    * Empty path (input is present but empty/zero-length — what happens?)
-    * Error path (upstream call fails — what happens?)
-* State machines. ASCII diagram for every new stateful object. Include impossible/invalid transitions and what prevents them.
-* Coupling concerns. Which components are now coupled that weren't before? Is that coupling justified? Draw the before/after dependency graph.
-* Scaling characteristics. What breaks first under 10x load? Under 100x?
-* Single points of failure. Map them.
-* Security architecture. Auth boundaries, data access patterns, API surfaces. For each new endpoint or data mutation: who can call it, what do they get, what can they change?
-* Production failure scenarios. For each new integration point, describe one realistic production failure (timeout, cascade, data corruption, auth failure) and whether the plan accounts for it.
-* Rollback posture. If this ships and immediately breaks, what's the rollback procedure? Git revert? Feature flag? DB migration rollback? How long?
-
-**EXPANSION and SELECTIVE EXPANSION additions:**
-* What would make this architecture beautiful? Not just correct — elegant. Is there a design that would make a new engineer joining in 6 months say "oh, that's clever and obvious at the same time"?
-* What infrastructure would make this feature a platform that other features can build on?
-
-**SELECTIVE EXPANSION:** If any accepted cherry-picks from Step 0D affect the architecture, evaluate their architectural fit here. Flag any that create coupling concerns or don't integrate cleanly — this is a chance to revisit the decision with new information.
-
-Required ASCII diagram: full system architecture showing new components and their relationships to existing ones.
-**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
-**Reminder: Do NOT make any code changes. Review only.**
-
-### Section 2: Error & Rescue Map
-This is the section that catches silent failures. It is not optional.
-For every new method, service, or codepath that can fail, fill in this table:
-```
-  METHOD/CODEPATH          | WHAT CAN GO WRONG           | EXCEPTION CLASS
-  -------------------------|-----------------------------|-----------------
-  ExampleService#call      | API timeout                 | TimeoutError
-                           | API returns 429             | RateLimitError
-                           | API returns malformed JSON  | JSONParseError
-                           | DB connection pool exhausted| ConnectionPoolExhausted
-                           | Record not found            | RecordNotFound
-  -------------------------|-----------------------------|-----------------
-
-  EXCEPTION CLASS              | RESCUED?  | RESCUE ACTION          | USER SEES
-  -----------------------------|-----------|------------------------|------------------
-  TimeoutError                 | Y         | Retry 2x, then raise   | "Service temporarily unavailable"
-  RateLimitError               | Y         | Backoff + retry         | Nothing (transparent)
-  JSONParseError               | N ← GAP   | —                      | 500 error ← BAD
-  ConnectionPoolExhausted      | N ← GAP   | —                      | 500 error ← BAD
-  RecordNotFound               | Y         | Return nil, log warning | "Not found" message
-```
-Rules for this section:
-* Catch-all error handling (`rescue StandardError`, `catch (Exception e)`, `except Exception`) is ALWAYS a smell. Name the specific exceptions.
-* Catching an error with only a generic log message is insufficient. Log the full context: what was being attempted, with what arguments, for what user/request.
-* Every rescued error must either: retry with backoff, degrade gracefully with a user-visible message, or re-raise with added context. "Swallow and continue" is almost never acceptable.
-* For each GAP (unrescued error that should be rescued): specify the rescue action and what the user should see.
-* For LLM/AI service calls specifically: what happens when the response is malformed? When it's empty? When it hallucinates invalid JSON? When the model returns a refusal? Each of these is a distinct failure mode.
-**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
-**Reminder: Do NOT make any code changes. Review only.**
-
-### Section 3: Security & Threat Model
-Security is not a sub-bullet of architecture. It gets its own section.
-Evaluate:
-* Attack surface expansion. What new attack vectors does this plan introduce? New endpoints, new params, new file paths, new background jobs?
-* Input validation. For every new user input: is it validated, sanitized, and rejected loudly on failure? What happens with: nil, empty string, string when integer expected, string exceeding max length, unicode edge cases, HTML/script injection attempts?
-* Authorization. For every new data access: is it scoped to the right user/role? Is there a direct object reference vulnerability? Can user A access user B's data by manipulating IDs?
-* Secrets and credentials. New secrets? In env vars, not hardcoded? Rotatable?
-* Dependency risk. New gems/npm packages? Security track record?
-* Data classification. PII, payment data, credentials? Handling consistent with existing patterns?
-* Injection vectors. SQL, command, template, LLM prompt injection — check all.
-* Audit logging. For sensitive operations: is there an audit trail?
-
-For each finding: threat, likelihood (High/Med/Low), impact (High/Med/Low), and whether the plan mitigates it.
-**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
-**Reminder: Do NOT make any code changes. Review only.**
-
-### Section 4: Data Flow & Interaction Edge Cases
-This section traces data through the system and interactions through the UI with adversarial thoroughness.
-
-**Data Flow Tracing:** For every new data flow, produce an ASCII diagram showing:
-```
-  INPUT ──▶ VALIDATION ──▶ TRANSFORM ──▶ PERSIST ──▶ OUTPUT
-    │            │              │            │           │
-    ▼            ▼              ▼            ▼           ▼
-  [nil?]    [invalid?]    [exception?]  [conflict?]  [stale?]
-  [empty?]  [too long?]   [timeout?]    [dup key?]   [partial?]
-  [wrong    [wrong type?] [OOM?]        [locked?]    [encoding?]
-   type?]
-```
-For each node: what happens on each shadow path? Is it tested?
-
-**Interaction Edge Cases:** For every new user-visible interaction, evaluate:
-```
-  INTERACTION          | EDGE CASE              | HANDLED? | HOW?
-  ---------------------|------------------------|----------|--------
-  Form submission      | Double-click submit    | ?        |
-                       | Submit with stale CSRF | ?        |
-                       | Submit during deploy   | ?        |
-  Async operation      | User navigates away    | ?        |
-                       | Operation times out    | ?        |
-                       | Retry while in-flight  | ?        |
-  List/table view      | Zero results           | ?        |
-                       | 10,000 results         | ?        |
-                       | Results change mid-page| ?        |
-  Background job       | Job fails after 3 of   | ?        |
-                       | 10 items processed     |          |
-                       | Job runs twice (dup)   | ?        |
-                       | Queue backs up 2 hours | ?        |
-```
-Flag any unhandled edge case as a gap. For each gap, specify the fix.
-**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
-**Reminder: Do NOT make any code changes. Review only.**
-
-### Section 5: Code Quality Review
-Evaluate:
-* Code organization and module structure. Does new code fit existing patterns? If it deviates, is there a reason?
-* DRY violations. Be aggressive. If the same logic exists elsewhere, flag it and reference the file and line.
-* Naming quality. Are new classes, methods, and variables named for what they do, not how they do it?
-* Error handling patterns. (Cross-reference with Section 2 — this section reviews the patterns; Section 2 maps the specifics.)
-* Missing edge cases. List explicitly: "What happens when X is nil?" "When the API returns 429?" etc.
-* Over-engineering check. Any new abstraction solving a problem that doesn't exist yet?
-* Under-engineering check. Anything fragile, assuming happy path only, or missing obvious defensive checks?
-* Cyclomatic complexity. Flag any new method that branches more than 5 times. Propose a refactor.
-**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
-**Reminder: Do NOT make any code changes. Review only.**
-
-### Section 6: Test Review
-Make a complete diagram of every new thing this plan introduces:
-```
-  NEW UX FLOWS:
-    [list each new user-visible interaction]
-
-  NEW DATA FLOWS:
-    [list each new path data takes through the system]
-
-  NEW CODEPATHS:
-    [list each new branch, condition, or execution path]
-
-  NEW BACKGROUND JOBS / ASYNC WORK:
-    [list each]
-
-  NEW INTEGRATIONS / EXTERNAL CALLS:
-    [list each]
-
-  NEW ERROR/RESCUE PATHS:
-    [list each — cross-reference Section 2]
-```
-For each item in the diagram:
-* What type of test covers it? (Unit / Integration / System / E2E)
-* Does a test for it exist in the plan? If not, write the test spec header.
-* What is the happy path test?
-* What is the failure path test? (Be specific — which failure?)
-* What is the edge case test? (nil, empty, boundary values, concurrent access)
-
-Test ambition check (all modes): For each new feature, answer:
-* What's the test that would make you confident shipping at 2am on a Friday?
-* What's the test a hostile QA engineer would write to break this?
-* What's the chaos test?
-
-Test pyramid check: Many unit, fewer integration, few E2E? Or inverted?
-Flakiness risk: Flag any test depending on time, randomness, external services, or ordering.
-Load/stress test requirements: For any new codepath called frequently or processing significant data.
-
-For LLM/prompt changes: Check CLAUDE.md for the "Prompt/LLM changes" file patterns. If this plan touches ANY of those patterns, state which eval suites must be run, which cases should be added, and what baselines to compare against.
-**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
-**Reminder: Do NOT make any code changes. Review only.**
-
-### Section 7: Performance Review
-Evaluate:
-* N+1 queries. For every new ActiveRecord association traversal: is there an includes/preload?
-* Memory usage. For every new data structure: what's the maximum size in production?
-* Database indexes. For every new query: is there an index?
-* Caching opportunities. For every expensive computation or external call: should it be cached?
-* Background job sizing. For every new job: worst-case payload, runtime, retry behavior?
-* Slow paths. Top 3 slowest new codepaths and estimated p99 latency.
-* Connection pool pressure. New DB connections, Redis connections, HTTP connections?
-**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
-**Reminder: Do NOT make any code changes. Review only.**
-
-### Section 8: Observability & Debuggability Review
-New systems break. This section ensures you can see why.
-Evaluate:
-* Logging. For every new codepath: structured log lines at entry, exit, and each significant branch?
-* Metrics. For every new feature: what metric tells you it's working? What tells you it's broken?
-* Tracing. For new cross-service or cross-job flows: trace IDs propagated?
-* Alerting. What new alerts should exist?
-* Dashboards. What new dashboard panels do you want on day 1?
-* Debuggability. If a bug is reported 3 weeks post-ship, can you reconstruct what happened from logs alone?
-* Admin tooling. New operational tasks that need admin UI or rake tasks?
-* Runbooks. For each new failure mode: what's the operational response?
-
-**EXPANSION and SELECTIVE EXPANSION addition:**
-* What observability would make this feature a joy to operate? (For SELECTIVE EXPANSION, include observability for any accepted cherry-picks.)
-**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
-**Reminder: Do NOT make any code changes. Review only.**
-
-### Section 9: Deployment & Rollout Review
-Evaluate:
-* Migration safety. For every new DB migration: backward-compatible? Zero-downtime? Table locks?
-* Feature flags. Should any part be behind a feature flag?
-* Rollout order. Correct sequence: migrate first, deploy second?
-* Rollback plan. Explicit step-by-step.
-* Deploy-time risk window. Old code and new code running simultaneously — what breaks?
-* Environment parity. Tested in staging?
-* Post-deploy verification checklist. First 5 minutes? First hour?
-* Smoke tests. What automated checks should run immediately post-deploy?
-
-**EXPANSION and SELECTIVE EXPANSION addition:**
-* What deploy infrastructure would make shipping this feature routine? (For SELECTIVE EXPANSION, assess whether accepted cherry-picks change the deployment risk profile.)
-**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
-**Reminder: Do NOT make any code changes. Review only.**
-
-### Section 10: Long-Term Trajectory Review
-Evaluate:
-* Technical debt introduced. Code debt, operational debt, testing debt, documentation debt.
-* Path dependency. Does this make future changes harder?
-* Knowledge concentration. Documentation sufficient for a new engineer?
-* Reversibility. Rate 1-5: 1 = one-way door, 5 = easily reversible.
-* Ecosystem fit. Aligns with Rails/JS ecosystem direction?
-* The 1-year question. Read this plan as a new engineer in 12 months — obvious?
-
-**EXPANSION and SELECTIVE EXPANSION additions:**
-* What comes after this ships? Phase 2? Phase 3? Does the architecture support that trajectory?
-* Platform potential. Does this create capabilities other features can leverage?
-* (SELECTIVE EXPANSION only) Retrospective: Were the right cherry-picks accepted? Did any rejected expansions turn out to be load-bearing for the accepted ones?
-**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
-**Reminder: Do NOT make any code changes. Review only.**
-
-### Section 11: Design & UX Review (skip if no UI scope detected)
-The CEO calling in the designer. Not a pixel-level audit — that's /plan-design-review and /design-review. This is ensuring the plan has design intentionality.
-
-Evaluate:
-* Information architecture — what does the user see first, second, third?
-* Interaction state coverage map:
-  FEATURE | LOADING | EMPTY | ERROR | SUCCESS | PARTIAL
-* User journey coherence — storyboard the emotional arc
-* AI slop risk — does the plan describe generic UI patterns?
-* DESIGN.md alignment — does the plan match the stated design system?
-* Responsive intention — is mobile mentioned or afterthought?
-* Accessibility basics — keyboard nav, screen readers, contrast, touch targets
-
-**EXPANSION and SELECTIVE EXPANSION additions:**
-* What would make this UI feel *inevitable*?
-* What 30-minute UI touches would make users think "oh nice, they thought of that"?
-
-Required ASCII diagram: user flow showing screens/states and transitions.
-
-If this plan has significant UI scope, recommend: "Consider running /plan-design-review for a deep design review of this plan before implementation."
-**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
-**Reminder: Do NOT make any code changes. Review only.**
-
-{{CODEX_PLAN_REVIEW}}
-
-### Outside Voice Integration Rule
-
-Outside voice findings are INFORMATIONAL until the user explicitly approves each one.
-Do NOT incorporate outside voice recommendations into the plan without presenting each
-finding via AskUserQuestion and getting explicit approval. This applies even when you
-agree with the outside voice. Cross-model consensus is a strong signal — present it as
-such — but the user makes the decision.
-
-## Post-Implementation Design Audit (if UI scope detected)
-After implementation, run `/design-review` on the live site to catch visual issues that can only be evaluated with rendered output.
-
-## CRITICAL RULE — How to ask questions
-Follow the AskUserQuestion format from the Preamble above. Additional rules for plan reviews:
-* **One issue = one AskUserQuestion call.** Never combine multiple issues into one question.
-* Describe the problem concretely, with file and line references.
-* Present 2-3 options, including "do nothing" where reasonable.
-* For each option: effort, risk, and maintenance burden in one line.
-* **Map the reasoning to my engineering preferences above.** One sentence connecting your recommendation to a specific preference.
-* Label with issue NUMBER + option LETTER (e.g., "3A", "3B").
-* **Zero findings:** if a section has zero findings, state "No issues, moving on" and proceed. Otherwise, use AskUserQuestion for each finding — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan.
-
-## Required Outputs
-
-### "NOT in scope" section
-List work considered and explicitly deferred, with one-line rationale each.
-
-### "What already exists" section
-List existing code/flows that partially solve sub-problems and whether the plan reuses them.
-
-### "Dream state delta" section
-Where this plan leaves us relative to the 12-month ideal.
-
-### Error & Rescue Registry (from Section 2)
-Complete table of every method that can fail, every exception class, rescued status, rescue action, user impact.
-
-### Failure Modes Registry
-```
-  CODEPATH | FAILURE MODE   | RESCUED? | TEST? | USER SEES?     | LOGGED?
-  ---------|----------------|----------|-------|----------------|--------
-```
-Any row with RESCUED=N, TEST=N, USER SEES=Silent → **CRITICAL GAP**.
-
-### TODOS.md updates
-Present each potential TODO as its own individual AskUserQuestion. Never batch TODOs — one per question. Never silently skip this step. Follow the format in `.claude/skills/review/TODOS-format.md`.
-
-For each TODO, describe:
-* **What:** One-line description of the work.
-* **Why:** The concrete problem it solves or value it unlocks.
-* **Pros:** What you gain by doing this work.
-* **Cons:** Cost, complexity, or risks of doing it.
-* **Context:** Enough detail that someone picking this up in 3 months understands the motivation, the current state, and where to start.
-* **Effort estimate:** S/M/L/XL (human team) → with CC+gstack: S→S, M→S, L→M, XL→L
-* **Priority:** P1/P2/P3
-* **Depends on / blocked by:** Any prerequisites or ordering constraints.
-
-Then present options: **A)** Add to TODOS.md **B)** Skip — not valuable enough **C)** Build it now in this PR instead of deferring.
-
-### Scope Expansion Decisions (EXPANSION and SELECTIVE EXPANSION only)
-For EXPANSION and SELECTIVE EXPANSION modes: expansion opportunities and delight items were surfaced and decided in Step 0D (opt-in/cherry-pick ceremony). The decisions are persisted in the CEO plan document. Reference the CEO plan for the full record. Do not re-surface them here — list the accepted expansions for completeness:
-* Accepted: {list items added to scope}
-* Deferred: {list items sent to TODOS.md}
-* Skipped: {list items rejected}
-
-### Diagrams (mandatory, produce all that apply)
-1. System architecture
-2. Data flow (including shadow paths)
-3. State machine
-4. Error flow
-5. Deployment sequence
-6. Rollback flowchart
-
-### Stale Diagram Audit
-List every ASCII diagram in files this plan touches. Still accurate?
-
-{{TASKS_SECTION_EMIT:ceo-review}}
-
-### Completion Summary
-```
-  +====================================================================+
-  |            MEGA PLAN REVIEW — COMPLETION SUMMARY                   |
-  +====================================================================+
-  | Mode selected        | EXPANSION / SELECTIVE / HOLD / REDUCTION     |
-  | System Audit         | [key findings]                              |
-  | Step 0               | [mode + key decisions]                      |
-  | Section 1  (Arch)    | ___ issues found                            |
-  | Section 2  (Errors)  | ___ error paths mapped, ___ GAPS            |
-  | Section 3  (Security)| ___ issues found, ___ High severity         |
-  | Section 4  (Data/UX) | ___ edge cases mapped, ___ unhandled        |
-  | Section 5  (Quality) | ___ issues found                            |
-  | Section 6  (Tests)   | Diagram produced, ___ gaps                  |
-  | Section 7  (Perf)    | ___ issues found                            |
-  | Section 8  (Observ)  | ___ gaps found                              |
-  | Section 9  (Deploy)  | ___ risks flagged                           |
-  | Section 10 (Future)  | Reversibility: _/5, debt items: ___         |
-  | Section 11 (Design)  | ___ issues / SKIPPED (no UI scope)          |
-  +--------------------------------------------------------------------+
-  | NOT in scope         | written (___ items)                          |
-  | What already exists  | written                                     |
-  | Dream state delta    | written                                     |
-  | Error/rescue registry| ___ methods, ___ CRITICAL GAPS              |
-  | Failure modes        | ___ total, ___ CRITICAL GAPS                |
-  | TODOS.md updates     | ___ items proposed                          |
-  | Scope proposals      | ___ proposed, ___ accepted (EXP + SEL)      |
-  | CEO plan             | written / skipped (HOLD/REDUCTION)           |
-  | Outside voice        | ran (codex/claude) / skipped                 |
-  | Lake Score           | X/Y recommendations chose complete option   |
-  | Diagrams produced    | ___ (list types)                            |
-  | Stale diagrams found | ___                                         |
-  | Unresolved decisions | ___ (listed below)                          |
-  +====================================================================+
-```
-
-### Unresolved Decisions
-If any AskUserQuestion goes unanswered, note it here. Never silently default.
-
-## Handoff Note Cleanup
-
-After producing the Completion Summary, clean up any handoff notes for this branch —
-the review is complete and the context is no longer needed.
-
-```bash
-setopt +o nomatch 2>/dev/null || true  # zsh compat
-{{SLUG_EVAL}}
-rm -f ~/.gstack/projects/$SLUG/*-$BRANCH-ceo-handoff-*.md 2>/dev/null || true
-```
-
-## Review Log
-
-After producing the Completion Summary above, persist the review result.
-
-**PLAN MODE EXCEPTION — ALWAYS RUN:** This command writes review metadata to
-`~/.gstack/` (user config directory, not project files). The skill preamble
-already writes to `~/.gstack/sessions/` and `~/.gstack/analytics/` — this is
-the same pattern. The review dashboard depends on this data. Skipping this
-command breaks the review readiness dashboard in /ship.
-
-```bash
-~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"plan-ceo-review","timestamp":"TIMESTAMP","status":"STATUS","unresolved":N,"critical_gaps":N,"mode":"MODE","scope_proposed":N,"scope_accepted":N,"scope_deferred":N,"commit":"COMMIT"}'
-```
-
-Before running this command, substitute the placeholder values from the Completion Summary you just produced:
-- **TIMESTAMP**: current ISO 8601 datetime (e.g., 2026-03-16T14:30:00)
-- **STATUS**: "clean" if 0 unresolved decisions AND 0 critical gaps; otherwise "issues_open"
-- **unresolved**: number from "Unresolved decisions" in the summary
-- **critical_gaps**: number from "Failure modes: ___ CRITICAL GAPS" in the summary
-- **MODE**: the mode the user selected (SCOPE_EXPANSION / SELECTIVE_EXPANSION / HOLD_SCOPE / SCOPE_REDUCTION)
-- **scope_proposed**: number from "Scope proposals: ___ proposed" in the summary (0 for HOLD/REDUCTION)
-- **scope_accepted**: number from "Scope proposals: ___ accepted" in the summary (0 for HOLD/REDUCTION)
-- **scope_deferred**: number of items deferred to TODOS.md from scope decisions (0 for HOLD/REDUCTION)
-- **COMMIT**: output of `git rev-parse --short HEAD`
-
-{{REVIEW_DASHBOARD}}
-
-{{PLAN_FILE_REVIEW_REPORT}}
-
-## Next Steps — Review Chaining
-
-After displaying the Review Readiness Dashboard, recommend the next review(s) based on what this CEO review discovered. Read the dashboard output to see which reviews have already been run and whether they are stale.
-
-**Recommend /plan-eng-review if eng review is not skipped globally** — check the dashboard output for `skip_eng_review`. If it is `true`, eng review is opted out — do not recommend it. Otherwise, eng review is the required shipping gate. If this CEO review expanded scope, changed architectural direction, or accepted scope expansions, emphasize that a fresh eng review is needed. If an eng review already exists in the dashboard but the commit hash shows it predates this CEO review, note that it may be stale and should be re-run.
-
-**Recommend /plan-design-review if UI scope was detected** — specifically if Section 11 (Design & UX Review) was NOT skipped, or if accepted scope expansions included UI-facing features. If an existing design review is stale (commit hash drift), note that. In SCOPE REDUCTION mode, skip this recommendation — design review is unlikely relevant for scope cuts.
-
-**If both are needed, recommend eng review first** (required gate), then design review.
-
-Use AskUserQuestion to present the next step. Include only applicable options:
-- **A)** Run /plan-eng-review next (required gate)
-- **B)** Run /plan-design-review next (only if UI scope detected)
-- **C)** Skip — I'll handle reviews manually
-
-## docs/designs Promotion (EXPANSION and SELECTIVE EXPANSION only)
-
-At the end of the review, if the vision produced a compelling feature direction, offer to promote the CEO plan to the project repo. AskUserQuestion:
-
-"The vision from this review produced {N} accepted scope expansions. Want to promote it to a design doc in the repo?"
-- **A)** Promote to `docs/designs/{FEATURE}.md` (committed to repo, visible to the team)
-- **B)** Keep in `~/.gstack/projects/` only (local, personal reference)
-- **C)** Skip
-
-If promoted, copy the CEO plan content to `docs/designs/{FEATURE}.md` (create the directory if needed) and update the `status` field in the original CEO plan from `ACTIVE` to `PROMOTED`.
-
-## Formatting Rules
-* NUMBER issues (1, 2, 3...) and LETTERS for options (A, B, C...).
-* Label with NUMBER + LETTER (e.g., "3A", "3B").
-* One sentence max per option.
-* After each section, pause and wait for feedback.
-* Use **CRITICAL GAP** / **WARNING** / **OK** for scannability.
-
-{{LEARNINGS_LOG}}
-
-{{GBRAIN_SAVE_RESULTS}}
-
-{{BRAIN_WRITE_BACK}}
-
-{{BRAIN_CACHE_REFRESH}}
-
-## Mode Quick Reference
-```
-  ┌────────────────────────────────────────────────────────────────────────────────┐
-  │                            MODE COMPARISON                                     │
-  ├─────────────┬──────────────┬──────────────┬──────────────┬────────────────────┤
-  │             │  EXPANSION   │  SELECTIVE   │  HOLD SCOPE  │  REDUCTION         │
-  ├─────────────┼──────────────┼──────────────┼──────────────┼────────────────────┤
-  │ Scope       │ Push UP      │ Hold + offer │ Maintain     │ Push DOWN          │
-  │             │ (opt-in)     │              │              │                    │
-  │ Recommend   │ Enthusiastic │ Neutral      │ N/A          │ N/A                │
-  │ posture     │              │              │              │                    │
-  │ 10x check   │ Mandatory    │ Surface as   │ Optional     │ Skip               │
-  │             │              │ cherry-pick  │              │                    │
-  │ Platonic    │ Yes          │ No           │ No           │ No                 │
-  │ ideal       │              │              │              │                    │
-  │ Delight     │ Opt-in       │ Cherry-pick  │ Note if seen │ Skip               │
-  │ opps        │ ceremony     │ ceremony     │              │                    │
-  │ Complexity  │ "Is it big   │ "Is it right │ "Is it too   │ "Is it the bare    │
-  │ question    │  enough?"    │  + what else │  complex?"   │  minimum?"         │
-  │             │              │  is tempting"│              │                    │
-  │ Taste       │ Yes          │ Yes          │ No           │ No                 │
-  │ calibration │              │              │              │                    │
-  │ Temporal    │ Full (hr 1-6)│ Full (hr 1-6)│ Key decisions│ Skip               │
-  │ interrogate │              │              │  only        │                    │
-  │ Observ.     │ "Joy to      │ "Joy to      │ "Can we      │ "Can we see if     │
-  │ standard    │  operate"    │  operate"    │  debug it?"  │  it's broken?"     │
-  │ Deploy      │ Infra as     │ Safe deploy  │ Safe deploy  │ Simplest possible  │
-  │ standard    │ feature scope│ + cherry-pick│  + rollback  │  deploy            │
-  │             │              │  risk check  │              │                    │
-  │ Error map   │ Full + chaos │ Full + chaos │ Full         │ Critical paths     │
-  │             │  scenarios   │ for accepted │              │  only              │
-  │ CEO plan    │ Written      │ Written      │ Skipped      │ Skipped            │
-  │ Phase 2/3   │ Map accepted │ Map accepted │ Note it      │ Skip               │
-  │ planning    │              │ cherry-picks │              │                    │
-  │ Design      │ "Inevitable" │ If UI scope  │ If UI scope  │ Skip               │
-  │ (Sec 11)    │  UI review   │  detected    │  detected    │                    │
-  └─────────────┴──────────────┴──────────────┴──────────────┴────────────────────┘
-```
 
 {{EXIT_PLAN_MODE_GATE}}

plan-ceo-review/sections/manifest.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://gstack.dev/schemas/section-manifest.json",
+  "skill": "plan-ceo-review",
+  "version": 1,
+  "note": "PASSIVE registry (v2 plan T9 / CM2). Fields are IDs, file paths, human titles, and human-readable trigger text ONLY. The skeleton's decision-tree prose is the ONLY place that decides WHEN to read a section; required-reads live in the E2E fixtures. No machine predicate here — see docs/designs/v2_PLAN.md:663.",
+  "sections": [
+    {
+      "id": "review-sections",
+      "file": "review-sections.md",
+      "title": "11-section deep review, required outputs + review report",
+      "trigger": "running the 11-section deep review, required outputs, and review report (only after Step 0 scope and mode are agreed)"
+    }
+  ]
+}

plan-ceo-review/sections/review-sections.md

@@ -0,0 +1,900 @@
+<!-- AUTO-GENERATED from review-sections.md.tmpl — do not edit directly -->
+<!-- Regenerate: bun run gen:skill-docs -->
+## Review Sections (11 sections, after scope and mode are agreed)
+
+**Anti-skip rule:** Never condense, abbreviate, or skip any review section (1-11) regardless of plan type (strategy, spec, code, infra). Every section in this skill exists for a reason. "This is a strategy doc so implementation sections don't apply" is always wrong — implementation details are where strategy breaks down. If a section genuinely has zero findings, say "No issues found" and move on — but you must evaluate it.
+
+**Anti-shortcut clause:** The plan file is the OUTPUT of the interactive review, not a substitute for it. Writing every finding into one plan write and calling ExitPlanMode without firing AskUserQuestion is the precise failure mode of the May 2026 transcript bug — the model explored, found issues, and dumped them into a deliverable rather than walking the user through them. If you have ANY non-trivial finding in any review section, the path from finding to ExitPlanMode goes THROUGH AskUserQuestion. Zero findings in every section is the only path to ExitPlanMode that bypasses AskUserQuestion. If you find yourself wanting to write a plan with findings before asking, stop and call AskUserQuestion now — that's the bug, recognize it.
+
+### Section 1: Architecture Review
+Evaluate and diagram:
+* Overall system design and component boundaries. Draw the dependency graph.
+* Data flow — all four paths. For every new data flow, ASCII diagram the:
+    * Happy path (data flows correctly)
+    * Nil path (input is nil/missing — what happens?)
+    * Empty path (input is present but empty/zero-length — what happens?)
+    * Error path (upstream call fails — what happens?)
+* State machines. ASCII diagram for every new stateful object. Include impossible/invalid transitions and what prevents them.
+* Coupling concerns. Which components are now coupled that weren't before? Is that coupling justified? Draw the before/after dependency graph.
+* Scaling characteristics. What breaks first under 10x load? Under 100x?
+* Single points of failure. Map them.
+* Security architecture. Auth boundaries, data access patterns, API surfaces. For each new endpoint or data mutation: who can call it, what do they get, what can they change?
+* Production failure scenarios. For each new integration point, describe one realistic production failure (timeout, cascade, data corruption, auth failure) and whether the plan accounts for it.
+* Rollback posture. If this ships and immediately breaks, what's the rollback procedure? Git revert? Feature flag? DB migration rollback? How long?
+
+**EXPANSION and SELECTIVE EXPANSION additions:**
+* What would make this architecture beautiful? Not just correct — elegant. Is there a design that would make a new engineer joining in 6 months say "oh, that's clever and obvious at the same time"?
+* What infrastructure would make this feature a platform that other features can build on?
+
+**SELECTIVE EXPANSION:** If any accepted cherry-picks from Step 0D affect the architecture, evaluate their architectural fit here. Flag any that create coupling concerns or don't integrate cleanly — this is a chance to revisit the decision with new information.
+
+Required ASCII diagram: full system architecture showing new components and their relationships to existing ones.
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
+**Reminder: Do NOT make any code changes. Review only.**
+
+### Section 2: Error & Rescue Map
+This is the section that catches silent failures. It is not optional.
+For every new method, service, or codepath that can fail, fill in this table:
+```
+  METHOD/CODEPATH          | WHAT CAN GO WRONG           | EXCEPTION CLASS
+  -------------------------|-----------------------------|-----------------
+  ExampleService#call      | API timeout                 | TimeoutError
+                           | API returns 429             | RateLimitError
+                           | API returns malformed JSON  | JSONParseError
+                           | DB connection pool exhausted| ConnectionPoolExhausted
+                           | Record not found            | RecordNotFound
+  -------------------------|-----------------------------|-----------------
+
+  EXCEPTION CLASS              | RESCUED?  | RESCUE ACTION          | USER SEES
+  -----------------------------|-----------|------------------------|------------------
+  TimeoutError                 | Y         | Retry 2x, then raise   | "Service temporarily unavailable"
+  RateLimitError               | Y         | Backoff + retry         | Nothing (transparent)
+  JSONParseError               | N ← GAP   | —                      | 500 error ← BAD
+  ConnectionPoolExhausted      | N ← GAP   | —                      | 500 error ← BAD
+  RecordNotFound               | Y         | Return nil, log warning | "Not found" message
+```
+Rules for this section:
+* Catch-all error handling (`rescue StandardError`, `catch (Exception e)`, `except Exception`) is ALWAYS a smell. Name the specific exceptions.
+* Catching an error with only a generic log message is insufficient. Log the full context: what was being attempted, with what arguments, for what user/request.
+* Every rescued error must either: retry with backoff, degrade gracefully with a user-visible message, or re-raise with added context. "Swallow and continue" is almost never acceptable.
+* For each GAP (unrescued error that should be rescued): specify the rescue action and what the user should see.
+* For LLM/AI service calls specifically: what happens when the response is malformed? When it's empty? When it hallucinates invalid JSON? When the model returns a refusal? Each of these is a distinct failure mode.
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
+**Reminder: Do NOT make any code changes. Review only.**
+
+### Section 3: Security & Threat Model
+Security is not a sub-bullet of architecture. It gets its own section.
+Evaluate:
+* Attack surface expansion. What new attack vectors does this plan introduce? New endpoints, new params, new file paths, new background jobs?
+* Input validation. For every new user input: is it validated, sanitized, and rejected loudly on failure? What happens with: nil, empty string, string when integer expected, string exceeding max length, unicode edge cases, HTML/script injection attempts?
+* Authorization. For every new data access: is it scoped to the right user/role? Is there a direct object reference vulnerability? Can user A access user B's data by manipulating IDs?
+* Secrets and credentials. New secrets? In env vars, not hardcoded? Rotatable?
+* Dependency risk. New gems/npm packages? Security track record?
+* Data classification. PII, payment data, credentials? Handling consistent with existing patterns?
+* Injection vectors. SQL, command, template, LLM prompt injection — check all.
+* Audit logging. For sensitive operations: is there an audit trail?
+
+For each finding: threat, likelihood (High/Med/Low), impact (High/Med/Low), and whether the plan mitigates it.
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
+**Reminder: Do NOT make any code changes. Review only.**
+
+### Section 4: Data Flow & Interaction Edge Cases
+This section traces data through the system and interactions through the UI with adversarial thoroughness.
+
+**Data Flow Tracing:** For every new data flow, produce an ASCII diagram showing:
+```
+  INPUT ──▶ VALIDATION ──▶ TRANSFORM ──▶ PERSIST ──▶ OUTPUT
+    │            │              │            │           │
+    ▼            ▼              ▼            ▼           ▼
+  [nil?]    [invalid?]    [exception?]  [conflict?]  [stale?]
+  [empty?]  [too long?]   [timeout?]    [dup key?]   [partial?]
+  [wrong    [wrong type?] [OOM?]        [locked?]    [encoding?]
+   type?]
+```
+For each node: what happens on each shadow path? Is it tested?
+
+**Interaction Edge Cases:** For every new user-visible interaction, evaluate:
+```
+  INTERACTION          | EDGE CASE              | HANDLED? | HOW?
+  ---------------------|------------------------|----------|--------
+  Form submission      | Double-click submit    | ?        |
+                       | Submit with stale CSRF | ?        |
+                       | Submit during deploy   | ?        |
+  Async operation      | User navigates away    | ?        |
+                       | Operation times out    | ?        |
+                       | Retry while in-flight  | ?        |
+  List/table view      | Zero results           | ?        |
+                       | 10,000 results         | ?        |
+                       | Results change mid-page| ?        |
+  Background job       | Job fails after 3 of   | ?        |
+                       | 10 items processed     |          |
+                       | Job runs twice (dup)   | ?        |
+                       | Queue backs up 2 hours | ?        |
+```
+Flag any unhandled edge case as a gap. For each gap, specify the fix.
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
+**Reminder: Do NOT make any code changes. Review only.**
+
+### Section 5: Code Quality Review
+Evaluate:
+* Code organization and module structure. Does new code fit existing patterns? If it deviates, is there a reason?
+* DRY violations. Be aggressive. If the same logic exists elsewhere, flag it and reference the file and line.
+* Naming quality. Are new classes, methods, and variables named for what they do, not how they do it?
+* Error handling patterns. (Cross-reference with Section 2 — this section reviews the patterns; Section 2 maps the specifics.)
+* Missing edge cases. List explicitly: "What happens when X is nil?" "When the API returns 429?" etc.
+* Over-engineering check. Any new abstraction solving a problem that doesn't exist yet?
+* Under-engineering check. Anything fragile, assuming happy path only, or missing obvious defensive checks?
+* Cyclomatic complexity. Flag any new method that branches more than 5 times. Propose a refactor.
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
+**Reminder: Do NOT make any code changes. Review only.**
+
+### Section 6: Test Review
+Make a complete diagram of every new thing this plan introduces:
+```
+  NEW UX FLOWS:
+    [list each new user-visible interaction]
+
+  NEW DATA FLOWS:
+    [list each new path data takes through the system]
+
+  NEW CODEPATHS:
+    [list each new branch, condition, or execution path]
+
+  NEW BACKGROUND JOBS / ASYNC WORK:
+    [list each]
+
+  NEW INTEGRATIONS / EXTERNAL CALLS:
+    [list each]
+
+  NEW ERROR/RESCUE PATHS:
+    [list each — cross-reference Section 2]
+```
+For each item in the diagram:
+* What type of test covers it? (Unit / Integration / System / E2E)
+* Does a test for it exist in the plan? If not, write the test spec header.
+* What is the happy path test?
+* What is the failure path test? (Be specific — which failure?)
+* What is the edge case test? (nil, empty, boundary values, concurrent access)
+
+Test ambition check (all modes): For each new feature, answer:
+* What's the test that would make you confident shipping at 2am on a Friday?
+* What's the test a hostile QA engineer would write to break this?
+* What's the chaos test?
+
+Test pyramid check: Many unit, fewer integration, few E2E? Or inverted?
+Flakiness risk: Flag any test depending on time, randomness, external services, or ordering.
+Load/stress test requirements: For any new codepath called frequently or processing significant data.
+
+For LLM/prompt changes: Check CLAUDE.md for the "Prompt/LLM changes" file patterns. If this plan touches ANY of those patterns, state which eval suites must be run, which cases should be added, and what baselines to compare against.
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
+**Reminder: Do NOT make any code changes. Review only.**
+
+### Section 7: Performance Review
+Evaluate:
+* N+1 queries. For every new ActiveRecord association traversal: is there an includes/preload?
+* Memory usage. For every new data structure: what's the maximum size in production?
+* Database indexes. For every new query: is there an index?
+* Caching opportunities. For every expensive computation or external call: should it be cached?
+* Background job sizing. For every new job: worst-case payload, runtime, retry behavior?
+* Slow paths. Top 3 slowest new codepaths and estimated p99 latency.
+* Connection pool pressure. New DB connections, Redis connections, HTTP connections?
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
+**Reminder: Do NOT make any code changes. Review only.**
+
+### Section 8: Observability & Debuggability Review
+New systems break. This section ensures you can see why.
+Evaluate:
+* Logging. For every new codepath: structured log lines at entry, exit, and each significant branch?
+* Metrics. For every new feature: what metric tells you it's working? What tells you it's broken?
+* Tracing. For new cross-service or cross-job flows: trace IDs propagated?
+* Alerting. What new alerts should exist?
+* Dashboards. What new dashboard panels do you want on day 1?
+* Debuggability. If a bug is reported 3 weeks post-ship, can you reconstruct what happened from logs alone?
+* Admin tooling. New operational tasks that need admin UI or rake tasks?
+* Runbooks. For each new failure mode: what's the operational response?
+
+**EXPANSION and SELECTIVE EXPANSION addition:**
+* What observability would make this feature a joy to operate? (For SELECTIVE EXPANSION, include observability for any accepted cherry-picks.)
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
+**Reminder: Do NOT make any code changes. Review only.**
+
+### Section 9: Deployment & Rollout Review
+Evaluate:
+* Migration safety. For every new DB migration: backward-compatible? Zero-downtime? Table locks?
+* Feature flags. Should any part be behind a feature flag?
+* Rollout order. Correct sequence: migrate first, deploy second?
+* Rollback plan. Explicit step-by-step.
+* Deploy-time risk window. Old code and new code running simultaneously — what breaks?
+* Environment parity. Tested in staging?
+* Post-deploy verification checklist. First 5 minutes? First hour?
+* Smoke tests. What automated checks should run immediately post-deploy?
+
+**EXPANSION and SELECTIVE EXPANSION addition:**
+* What deploy infrastructure would make shipping this feature routine? (For SELECTIVE EXPANSION, assess whether accepted cherry-picks change the deployment risk profile.)
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
+**Reminder: Do NOT make any code changes. Review only.**
+
+### Section 10: Long-Term Trajectory Review
+Evaluate:
+* Technical debt introduced. Code debt, operational debt, testing debt, documentation debt.
+* Path dependency. Does this make future changes harder?
+* Knowledge concentration. Documentation sufficient for a new engineer?
+* Reversibility. Rate 1-5: 1 = one-way door, 5 = easily reversible.
+* Ecosystem fit. Aligns with Rails/JS ecosystem direction?
+* The 1-year question. Read this plan as a new engineer in 12 months — obvious?
+
+**EXPANSION and SELECTIVE EXPANSION additions:**
+* What comes after this ships? Phase 2? Phase 3? Does the architecture support that trajectory?
+* Platform potential. Does this create capabilities other features can leverage?
+* (SELECTIVE EXPANSION only) Retrospective: Were the right cherry-picks accepted? Did any rejected expansions turn out to be load-bearing for the accepted ones?
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
+**Reminder: Do NOT make any code changes. Review only.**
+
+### Section 11: Design & UX Review (skip if no UI scope detected)
+The CEO calling in the designer. Not a pixel-level audit — that's /plan-design-review and /design-review. This is ensuring the plan has design intentionality.
+
+Evaluate:
+* Information architecture — what does the user see first, second, third?
+* Interaction state coverage map:
+  FEATURE | LOADING | EMPTY | ERROR | SUCCESS | PARTIAL
+* User journey coherence — storyboard the emotional arc
+* AI slop risk — does the plan describe generic UI patterns?
+* DESIGN.md alignment — does the plan match the stated design system?
+* Responsive intention — is mobile mentioned or afterthought?
+* Accessibility basics — keyboard nav, screen readers, contrast, touch targets
+
+**EXPANSION and SELECTIVE EXPANSION additions:**
+* What would make this UI feel *inevitable*?
+* What 30-minute UI touches would make users think "oh nice, they thought of that"?
+
+Required ASCII diagram: user flow showing screens/states and transitions.
+
+If this plan has significant UI scope, recommend: "Consider running /plan-design-review for a deep design review of this plan before implementation."
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
+**Reminder: Do NOT make any code changes. Review only.**
+
+## Outside Voice — Independent Plan Challenge (optional, recommended)
+
+After all review sections are complete, offer an independent second opinion from a
+different AI system. Two models agreeing on a plan is stronger signal than one model's
+thorough review.
+
+**Check tool availability:**
+
+```bash
+command -v codex >/dev/null 2>&1 && echo "CODEX_AVAILABLE" || echo "CODEX_NOT_AVAILABLE"
+```
+
+Use AskUserQuestion:
+
+> "All review sections are complete. Want an outside voice? A different AI system can
+> give a brutally honest, independent challenge of this plan — logical gaps, feasibility
+> risks, and blind spots that are hard to catch from inside the review. Takes about 2
+> minutes."
+>
+> RECOMMENDATION: Choose A — an independent second opinion catches structural blind
+> spots. Two different AI models agreeing on a plan is stronger signal than one model's
+> thorough review. Completeness: A=9/10, B=7/10.
+
+Options:
+- A) Get the outside voice (recommended)
+- B) Skip — proceed to outputs
+
+**If B:** Print "Skipping outside voice." and continue to the next section.
+
+**If A:** Construct the plan review prompt. Read the plan file being reviewed (the file
+the user pointed this review at, or the branch diff scope). If a CEO plan document
+was written in Step 0D-POST, read that too — it contains the scope decisions and vision.
+
+Construct this prompt (substitute the actual plan content — if plan content exceeds 30KB,
+truncate to the first 30KB and note "Plan truncated for size"). **Always start with the
+filesystem boundary instruction:**
+
+"IMPORTANT: Do NOT read or execute any files under ~/.claude/, ~/.agents/, .claude/skills/, or agents/. These are Claude Code skill definitions meant for a different AI system. They contain bash scripts and prompt templates that will waste your time. Ignore them completely. Do NOT modify agents/openai.yaml. Stay focused on the repository code only.\n\nYou are a brutally honest technical reviewer examining a development plan that has
+already been through a multi-section review. Your job is NOT to repeat that review.
+Instead, find what it missed. Look for: logical gaps and unstated assumptions that
+survived the review scrutiny, overcomplexity (is there a fundamentally simpler
+approach the review was too deep in the weeds to see?), feasibility risks the review
+took for granted, missing dependencies or sequencing issues, and strategic
+miscalibration (is this the right thing to build at all?). Be direct. Be terse. No
+compliments. Just the problems.
+
+THE PLAN:
+<plan content>"
+
+**If CODEX_AVAILABLE:**
+
+```bash
+TMPERR_PV=$(mktemp /tmp/codex-planreview-XXXXXXXX)
+_REPO_ROOT=$(git rev-parse --show-toplevel) || { echo "ERROR: not in a git repo" >&2; exit 1; }
+codex exec "<prompt>" -C "$_REPO_ROOT" -s read-only -c 'model_reasoning_effort="high"' --enable web_search_cached < /dev/null 2>"$TMPERR_PV"
+```
+
+Use a 5-minute timeout (`timeout: 300000`). After the command completes, read stderr:
+```bash
+cat "$TMPERR_PV"
+```
+
+Present the full output verbatim:
+
+```
+CODEX SAYS (plan review — outside voice):
+════════════════════════════════════════════════════════════
+<full codex output, verbatim — do not truncate or summarize>
+════════════════════════════════════════════════════════════
+```
+
+**Error handling:** All errors are non-blocking — the outside voice is informational.
+- Auth failure (stderr contains "auth", "login", "unauthorized"): "Codex auth failed. Run \`codex login\` to authenticate."
+- Timeout: "Codex timed out after 5 minutes."
+- Empty response: "Codex returned no response."
+
+On any Codex error, fall back to the Claude adversarial subagent.
+
+**If CODEX_NOT_AVAILABLE (or Codex errored):**
+
+Dispatch via the Agent tool. The subagent has fresh context — genuine independence.
+
+Subagent prompt: same plan review prompt as above.
+
+Present findings under an `OUTSIDE VOICE (Claude subagent):` header.
+
+If the subagent fails or times out: "Outside voice unavailable. Continuing to outputs."
+
+**Cross-model tension:**
+
+After presenting the outside voice findings, note any points where the outside voice
+disagrees with the review findings from earlier sections. Flag these as:
+
+```
+CROSS-MODEL TENSION:
+  [Topic]: Review said X. Outside voice says Y. [Present both perspectives neutrally.
+  State what context you might be missing that would change the answer.]
+```
+
+**User Sovereignty:** Do NOT auto-incorporate outside voice recommendations into the plan.
+Present each tension point to the user. The user decides. Cross-model agreement is a
+strong signal — present it as such — but it is NOT permission to act. You may state
+which argument you find more compelling, but you MUST NOT apply the change without
+explicit user approval.
+
+For each substantive tension point, use AskUserQuestion:
+
+> "Cross-model disagreement on [topic]. The review found [X] but the outside voice
+> argues [Y]. [One sentence on what context you might be missing.]"
+>
+> RECOMMENDATION: Choose [A or B] because [one-line reason explaining which argument
+> is more compelling and why]. Completeness: A=X/10, B=Y/10.
+
+Options:
+- A) Accept the outside voice's recommendation (I'll apply this change)
+- B) Keep the current approach (reject the outside voice)
+- C) Investigate further before deciding
+- D) Add to TODOS.md for later
+
+Wait for the user's response. Do NOT default to accepting because you agree with the
+outside voice. If the user chooses B, the current approach stands — do not re-argue.
+
+If no tension points exist, note: "No cross-model tension — both reviewers agree."
+
+**Persist the result:**
+```bash
+~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"codex-plan-review","timestamp":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'","status":"STATUS","source":"SOURCE","commit":"'"$(git rev-parse --short HEAD)"'"}'
+```
+
+Substitute: STATUS = "clean" if no findings, "issues_found" if findings exist.
+SOURCE = "codex" if Codex ran, "claude" if subagent ran.
+
+**Cleanup:** Run `rm -f "$TMPERR_PV"` after processing (if Codex was used).
+
+---
+
+### Outside Voice Integration Rule
+
+Outside voice findings are INFORMATIONAL until the user explicitly approves each one.
+Do NOT incorporate outside voice recommendations into the plan without presenting each
+finding via AskUserQuestion and getting explicit approval. This applies even when you
+agree with the outside voice. Cross-model consensus is a strong signal — present it as
+such — but the user makes the decision.
+
+## Post-Implementation Design Audit (if UI scope detected)
+After implementation, run `/design-review` on the live site to catch visual issues that can only be evaluated with rendered output.
+
+## CRITICAL RULE — How to ask questions
+Follow the AskUserQuestion format from the Preamble above. Additional rules for plan reviews:
+* **One issue = one AskUserQuestion call.** Never combine multiple issues into one question.
+* Describe the problem concretely, with file and line references.
+* Present 2-3 options, including "do nothing" where reasonable.
+* For each option: effort, risk, and maintenance burden in one line.
+* **Map the reasoning to my engineering preferences above.** One sentence connecting your recommendation to a specific preference.
+* Label with issue NUMBER + option LETTER (e.g., "3A", "3B").
+* **Zero findings:** if a section has zero findings, state "No issues, moving on" and proceed. Otherwise, use AskUserQuestion for each finding — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan.
+
+## Required Outputs
+
+### "NOT in scope" section
+List work considered and explicitly deferred, with one-line rationale each.
+
+### "What already exists" section
+List existing code/flows that partially solve sub-problems and whether the plan reuses them.
+
+### "Dream state delta" section
+Where this plan leaves us relative to the 12-month ideal.
+
+### Error & Rescue Registry (from Section 2)
+Complete table of every method that can fail, every exception class, rescued status, rescue action, user impact.
+
+### Failure Modes Registry
+```
+  CODEPATH | FAILURE MODE   | RESCUED? | TEST? | USER SEES?     | LOGGED?
+  ---------|----------------|----------|-------|----------------|--------
+```
+Any row with RESCUED=N, TEST=N, USER SEES=Silent → **CRITICAL GAP**.
+
+### TODOS.md updates
+Present each potential TODO as its own individual AskUserQuestion. Never batch TODOs — one per question. Never silently skip this step. Follow the format in `.claude/skills/review/TODOS-format.md`.
+
+For each TODO, describe:
+* **What:** One-line description of the work.
+* **Why:** The concrete problem it solves or value it unlocks.
+* **Pros:** What you gain by doing this work.
+* **Cons:** Cost, complexity, or risks of doing it.
+* **Context:** Enough detail that someone picking this up in 3 months understands the motivation, the current state, and where to start.
+* **Effort estimate:** S/M/L/XL (human team) → with CC+gstack: S→S, M→S, L→M, XL→L
+* **Priority:** P1/P2/P3
+* **Depends on / blocked by:** Any prerequisites or ordering constraints.
+
+Then present options: **A)** Add to TODOS.md **B)** Skip — not valuable enough **C)** Build it now in this PR instead of deferring.
+
+### Scope Expansion Decisions (EXPANSION and SELECTIVE EXPANSION only)
+For EXPANSION and SELECTIVE EXPANSION modes: expansion opportunities and delight items were surfaced and decided in Step 0D (opt-in/cherry-pick ceremony). The decisions are persisted in the CEO plan document. Reference the CEO plan for the full record. Do not re-surface them here — list the accepted expansions for completeness:
+* Accepted: {list items added to scope}
+* Deferred: {list items sent to TODOS.md}
+* Skipped: {list items rejected}
+
+### Diagrams (mandatory, produce all that apply)
+1. System architecture
+2. Data flow (including shadow paths)
+3. State machine
+4. Error flow
+5. Deployment sequence
+6. Rollback flowchart
+
+### Stale Diagram Audit
+List every ASCII diagram in files this plan touches. Still accurate?
+
+## Implementation Tasks
+
+Before closing this review, synthesize the findings above into a flat list of
+build-actionable tasks. Each task derives from a specific finding — no padding.
+Emit the markdown section AND write a JSONL artifact that `/autoplan` can
+aggregate across phases.
+
+### Markdown section (always emit)
+
+```markdown
+## Implementation Tasks
+Synthesized from this review's findings. Each task derives from a specific
+finding above. Run with Claude Code or Codex; checkbox as you ship.
+
+- [ ] **T1 (P1, human: ~2h / CC: ~15min)** — <component> — <imperative title>
+  - Surfaced by: <section name> — <specific finding text or line reference>
+  - Files: <paths to touch>
+  - Verify: <test command or manual check>
+- [ ] **T2 (P2, human: ~30min / CC: ~5min)** — ...
+```
+
+Rules:
+- P1 blocks ship; P2 should land same branch; P3 is a follow-up TODO.
+- If a finding produced no actionable task, do not invent one.
+- If a section had zero findings, emit `_No new tasks from <section>._`
+- Effort uses the AI-compression table from CLAUDE.md.
+
+### JSONL artifact (always write, even if zero tasks)
+
+`/autoplan` reads this file to aggregate across phases. Build each line with
+`jq -nc` so titles and source findings containing quotes, newlines, or
+backslashes serialize cleanly — never use hand-rolled `echo` / `printf`.
+
+```bash
+eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)"
+TASKS_DIR="${HOME}/.gstack/projects/${SLUG:-unknown}"
+mkdir -p "$TASKS_DIR"
+TASKS_FILE="$TASKS_DIR/tasks-ceo-review-$(date +%Y%m%d-%H%M%S).jsonl"
+COMMIT=$(git rev-parse HEAD 2>/dev/null || echo unknown)
+BRANCH=$(git branch --show-current 2>/dev/null || echo unknown)
+RUN_ID="$(date -u +%Y%m%dT%H%M%SZ)-$$"
+
+# Repeat ONE jq invocation per task identified during this review.
+# Substitute the placeholders inline with shell variables you set per task:
+#   TASK_ID (T1, T2, ...), PRIORITY (P1/P2/P3), COMPONENT, TITLE,
+#   SOURCE_FINDING, EFFORT_HUMAN, EFFORT_CC, FILES_JSON (a JSON array literal
+#   like '["browse/src/sanitize.ts","browse/src/server.ts"]').
+jq -nc \
+  --arg phase 'ceo-review' \
+  --arg run_id "$RUN_ID" \
+  --arg branch "$BRANCH" \
+  --arg commit "$COMMIT" \
+  --arg id "$TASK_ID" \
+  --arg priority "$PRIORITY" \
+  --arg component "$COMPONENT" \
+  --arg effort_human "$EFFORT_HUMAN" \
+  --arg effort_cc "$EFFORT_CC" \
+  --arg title "$TITLE" \
+  --arg source_finding "$SOURCE_FINDING" \
+  --argjson files "$FILES_JSON" \
+  '{phase:$phase, run_id:$run_id, branch:$branch, commit:$commit, id:$id, priority:$priority, component:$component, files:$files, effort_human:$effort_human, effort_cc:$effort_cc, title:$title, source_finding:$source_finding}' \
+  >> "$TASKS_FILE"
+```
+
+If `jq` is not installed, fall back to skipping the JSONL write and warn
+the user to install jq for autoplan aggregation. Never hand-roll JSONL.
+
+If zero tasks were identified in this review, still touch the JSONL file
+(`: > "$TASKS_FILE"`) so the aggregator sees that the phase produced output
+this run (an empty file means "ran, no findings" — distinct from "didn't run").
+
+
+### Completion Summary
+```
+  +====================================================================+
+  |            MEGA PLAN REVIEW — COMPLETION SUMMARY                   |
+  +====================================================================+
+  | Mode selected        | EXPANSION / SELECTIVE / HOLD / REDUCTION     |
+  | System Audit         | [key findings]                              |
+  | Step 0               | [mode + key decisions]                      |
+  | Section 1  (Arch)    | ___ issues found                            |
+  | Section 2  (Errors)  | ___ error paths mapped, ___ GAPS            |
+  | Section 3  (Security)| ___ issues found, ___ High severity         |
+  | Section 4  (Data/UX) | ___ edge cases mapped, ___ unhandled        |
+  | Section 5  (Quality) | ___ issues found                            |
+  | Section 6  (Tests)   | Diagram produced, ___ gaps                  |
+  | Section 7  (Perf)    | ___ issues found                            |
+  | Section 8  (Observ)  | ___ gaps found                              |
+  | Section 9  (Deploy)  | ___ risks flagged                           |
+  | Section 10 (Future)  | Reversibility: _/5, debt items: ___         |
+  | Section 11 (Design)  | ___ issues / SKIPPED (no UI scope)          |
+  +--------------------------------------------------------------------+
+  | NOT in scope         | written (___ items)                          |
+  | What already exists  | written                                     |
+  | Dream state delta    | written                                     |
+  | Error/rescue registry| ___ methods, ___ CRITICAL GAPS              |
+  | Failure modes        | ___ total, ___ CRITICAL GAPS                |
+  | TODOS.md updates     | ___ items proposed                          |
+  | Scope proposals      | ___ proposed, ___ accepted (EXP + SEL)      |
+  | CEO plan             | written / skipped (HOLD/REDUCTION)           |
+  | Outside voice        | ran (codex/claude) / skipped                 |
+  | Lake Score           | X/Y recommendations chose complete option   |
+  | Diagrams produced    | ___ (list types)                            |
+  | Stale diagrams found | ___                                         |
+  | Unresolved decisions | ___ (listed below)                          |
+  +====================================================================+
+```
+
+### Unresolved Decisions
+If any AskUserQuestion goes unanswered, note it here. Never silently default.
+
+## Handoff Note Cleanup
+
+After producing the Completion Summary, clean up any handoff notes for this branch —
+the review is complete and the context is no longer needed.
+
+```bash
+setopt +o nomatch 2>/dev/null || true  # zsh compat
+eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)"
+rm -f ~/.gstack/projects/$SLUG/*-$BRANCH-ceo-handoff-*.md 2>/dev/null || true
+```
+
+## Review Log
+
+After producing the Completion Summary above, persist the review result.
+
+**PLAN MODE EXCEPTION — ALWAYS RUN:** This command writes review metadata to
+`~/.gstack/` (user config directory, not project files). The skill preamble
+already writes to `~/.gstack/sessions/` and `~/.gstack/analytics/` — this is
+the same pattern. The review dashboard depends on this data. Skipping this
+command breaks the review readiness dashboard in /ship.
+
+```bash
+~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"plan-ceo-review","timestamp":"TIMESTAMP","status":"STATUS","unresolved":N,"critical_gaps":N,"mode":"MODE","scope_proposed":N,"scope_accepted":N,"scope_deferred":N,"commit":"COMMIT"}'
+```
+
+Before running this command, substitute the placeholder values from the Completion Summary you just produced:
+- **TIMESTAMP**: current ISO 8601 datetime (e.g., 2026-03-16T14:30:00)
+- **STATUS**: "clean" if 0 unresolved decisions AND 0 critical gaps; otherwise "issues_open"
+- **unresolved**: number from "Unresolved decisions" in the summary
+- **critical_gaps**: number from "Failure modes: ___ CRITICAL GAPS" in the summary
+- **MODE**: the mode the user selected (SCOPE_EXPANSION / SELECTIVE_EXPANSION / HOLD_SCOPE / SCOPE_REDUCTION)
+- **scope_proposed**: number from "Scope proposals: ___ proposed" in the summary (0 for HOLD/REDUCTION)
+- **scope_accepted**: number from "Scope proposals: ___ accepted" in the summary (0 for HOLD/REDUCTION)
+- **scope_deferred**: number of items deferred to TODOS.md from scope decisions (0 for HOLD/REDUCTION)
+- **COMMIT**: output of `git rev-parse --short HEAD`
+
+## Review Readiness Dashboard
+
+After completing the review, read the review log and config to display the dashboard.
+
+```bash
+~/.claude/skills/gstack/bin/gstack-review-read
+```
+
+Parse the output. Find the most recent entry for each skill (plan-ceo-review, plan-eng-review, review, plan-design-review, design-review-lite, adversarial-review, codex-review, codex-plan-review). Ignore entries with timestamps older than 7 days. For the Eng Review row, show whichever is more recent between `review` (diff-scoped pre-landing review) and `plan-eng-review` (plan-stage architecture review). Append "(DIFF)" or "(PLAN)" to the status to distinguish. For the Adversarial row, show whichever is more recent between `adversarial-review` (new auto-scaled) and `codex-review` (legacy). For Design Review, show whichever is more recent between `plan-design-review` (full visual audit) and `design-review-lite` (code-level check). Append "(FULL)" or "(LITE)" to the status to distinguish. For the Outside Voice row, show the most recent `codex-plan-review` entry — this captures outside voices from both /plan-ceo-review and /plan-eng-review.
+
+**Source attribution:** If the most recent entry for a skill has a \`"via"\` field, append it to the status label in parentheses. Examples: `plan-eng-review` with `via:"autoplan"` shows as "CLEAR (PLAN via /autoplan)". `review` with `via:"ship"` shows as "CLEAR (DIFF via /ship)". Entries without a `via` field show as "CLEAR (PLAN)" or "CLEAR (DIFF)" as before.
+
+Note: `autoplan-voices` and `design-outside-voices` entries are audit-trail-only (forensic data for cross-model consensus analysis). They do not appear in the dashboard and are not checked by any consumer.
+
+Display:
+
+```
++====================================================================+
+|                    REVIEW READINESS DASHBOARD                       |
++====================================================================+
+| Review          | Runs | Last Run            | Status    | Required |
+|-----------------|------|---------------------|-----------|----------|
+| Eng Review      |  1   | 2026-03-16 15:00    | CLEAR     | YES      |
+| CEO Review      |  0   | —                   | —         | no       |
+| Design Review   |  0   | —                   | —         | no       |
+| Adversarial     |  0   | —                   | —         | no       |
+| Outside Voice   |  0   | —                   | —         | no       |
++--------------------------------------------------------------------+
+| VERDICT: CLEARED — Eng Review passed                                |
++====================================================================+
+```
+
+**Review tiers:**
+- **Eng Review (required by default):** The only review that gates shipping. Covers architecture, code quality, tests, performance. Can be disabled globally with \`gstack-config set skip_eng_review true\` (the "don't bother me" setting).
+- **CEO Review (optional):** Use your judgment. Recommend it for big product/business changes, new user-facing features, or scope decisions. Skip for bug fixes, refactors, infra, and cleanup.
+- **Design Review (optional):** Use your judgment. Recommend it for UI/UX changes. Skip for backend-only, infra, or prompt-only changes.
+- **Adversarial Review (automatic):** Always-on for every review. Every diff gets both Claude adversarial subagent and Codex adversarial challenge. Large diffs (200+ lines) additionally get Codex structured review with P1 gate. No configuration needed.
+- **Outside Voice (optional):** Independent plan review from a different AI model. Offered after all review sections complete in /plan-ceo-review and /plan-eng-review. Falls back to Claude subagent if Codex is unavailable. Never gates shipping.
+
+**Verdict logic:**
+- **CLEARED**: Eng Review has >= 1 entry within 7 days from either \`review\` or \`plan-eng-review\` with status "clean" (or \`skip_eng_review\` is \`true\`)
+- **NOT CLEARED**: Eng Review missing, stale (>7 days), or has open issues
+- CEO, Design, and Codex reviews are shown for context but never block shipping
+- If \`skip_eng_review\` config is \`true\`, Eng Review shows "SKIPPED (global)" and verdict is CLEARED
+
+**Staleness detection:** After displaying the dashboard, check if any existing reviews may be stale:
+- Parse the \`---HEAD---\` section from the bash output to get the current HEAD commit hash
+- For each review entry that has a \`commit\` field: compare it against the current HEAD. If different, count elapsed commits: \`git rev-list --count STORED_COMMIT..HEAD\`. Display: "Note: {skill} review from {date} may be stale — {N} commits since review"
+- For entries without a \`commit\` field (legacy entries): display "Note: {skill} review from {date} has no commit tracking — consider re-running for accurate staleness detection"
+- If all reviews match the current HEAD, do not display any staleness notes
+
+## Plan File Review Report
+
+After displaying the Review Readiness Dashboard in conversation output, also update the
+**plan file** itself so review status is visible to anyone reading the plan.
+
+### Detect the plan file
+
+1. Check if there is an active plan file in this conversation (the host provides plan file
+   paths in system messages — look for plan file references in the conversation context).
+2. If not found, skip this section silently — not every review runs in plan mode.
+
+### Generate the report
+
+Read the review log output you already have from the Review Readiness Dashboard step above.
+Parse each JSONL entry. Each skill logs different fields:
+
+- **plan-ceo-review**: \`status\`, \`unresolved\`, \`critical_gaps\`, \`mode\`, \`scope_proposed\`, \`scope_accepted\`, \`scope_deferred\`, \`commit\`
+  → Findings: "{scope_proposed} proposals, {scope_accepted} accepted, {scope_deferred} deferred"
+  → If scope fields are 0 or missing (HOLD/REDUCTION mode): "mode: {mode}, {critical_gaps} critical gaps"
+- **plan-eng-review**: \`status\`, \`unresolved\`, \`critical_gaps\`, \`issues_found\`, \`mode\`, \`commit\`
+  → Findings: "{issues_found} issues, {critical_gaps} critical gaps"
+- **plan-design-review**: \`status\`, \`initial_score\`, \`overall_score\`, \`unresolved\`, \`decisions_made\`, \`commit\`
+  → Findings: "score: {initial_score}/10 → {overall_score}/10, {decisions_made} decisions"
+- **plan-devex-review**: \`status\`, \`initial_score\`, \`overall_score\`, \`product_type\`, \`tthw_current\`, \`tthw_target\`, \`mode\`, \`persona\`, \`competitive_tier\`, \`unresolved\`, \`commit\`
+  → Findings: "score: {initial_score}/10 → {overall_score}/10, TTHW: {tthw_current} → {tthw_target}"
+- **devex-review**: \`status\`, \`overall_score\`, \`product_type\`, \`tthw_measured\`, \`dimensions_tested\`, \`dimensions_inferred\`, \`boomerang\`, \`commit\`
+  → Findings: "score: {overall_score}/10, TTHW: {tthw_measured}, {dimensions_tested} tested/{dimensions_inferred} inferred"
+- **codex-review**: \`status\`, \`gate\`, \`findings\`, \`findings_fixed\`
+  → Findings: "{findings} findings, {findings_fixed}/{findings} fixed"
+
+All fields needed for the Findings column are now present in the JSONL entries.
+For the review you just completed, you may use richer details from your own Completion
+Summary. For prior reviews, use the JSONL fields directly — they contain all required data.
+
+Produce this markdown table:
+
+\`\`\`markdown
+## GSTACK REVIEW REPORT
+
+| Review | Trigger | Why | Runs | Status | Findings |
+|--------|---------|-----|------|--------|----------|
+| CEO Review | \`/plan-ceo-review\` | Scope & strategy | {runs} | {status} | {findings} |
+| Codex Review | \`/codex review\` | Independent 2nd opinion | {runs} | {status} | {findings} |
+| Eng Review | \`/plan-eng-review\` | Architecture & tests (required) | {runs} | {status} | {findings} |
+| Design Review | \`/plan-design-review\` | UI/UX gaps | {runs} | {status} | {findings} |
+| DX Review | \`/plan-devex-review\` | Developer experience gaps | {runs} | {status} | {findings} |
+\`\`\`
+
+Below the table, add these lines (omit any that are empty/not applicable):
+
+- **CODEX:** (only if codex-review ran) — one-line summary of codex fixes
+- **CROSS-MODEL:** (only if both Claude and Codex reviews exist) — overlap analysis
+- **UNRESOLVED:** total unresolved decisions across all reviews
+- **VERDICT:** list reviews that are CLEAR (e.g., "CEO + ENG CLEARED — ready to implement").
+  If Eng Review is not CLEAR and not skipped globally, append "eng review required".
+
+### Write to the plan file
+
+**PLAN MODE EXCEPTION — ALWAYS RUN:** This writes to the plan file, which is the one
+file you are allowed to edit in plan mode. The plan file review report is part of the
+plan's living status.
+
+The report must always be the LAST section of the plan file — never mid-file.
+Use a single delete-then-append flow:
+
+1. Read the plan file (Read tool) to see its full current content. Search the read
+   output for a \`## GSTACK REVIEW REPORT\` heading anywhere in the file.
+2. If found, use the Edit tool to DELETE the entire existing section. Match from
+   \`## GSTACK REVIEW REPORT\` through either the next \`## \` heading or end of
+   file, whichever comes first. Replace with the empty string. This applies
+   regardless of where the section currently lives — mid-file deletion is
+   intentional, not a special case. If the Edit fails (e.g., concurrent edit
+   changed the content), re-read the plan file and retry once.
+3. After the delete (or skipped, if no section existed), append the new
+   \`## GSTACK REVIEW REPORT\` section at the END of the file. Use the Edit
+   tool to match the file's current last paragraph and add the section after it,
+   or use Write to re-emit the whole file with the section at the end.
+4. Verify with the Read tool that \`## GSTACK REVIEW REPORT\` is the last
+   \`## \` heading in the file before continuing. If it isn't, repeat steps
+   2-3 once.
+
+Do NOT replace the section in place. The "replace mid-file" path is what allowed
+prior versions to leave the report mid-file when an older report already lived
+there — the user then sees a plan whose review report is not at the bottom and
+(correctly) rejects it.
+
+## Next Steps — Review Chaining
+
+After displaying the Review Readiness Dashboard, recommend the next review(s) based on what this CEO review discovered. Read the dashboard output to see which reviews have already been run and whether they are stale.
+
+**Recommend /plan-eng-review if eng review is not skipped globally** — check the dashboard output for `skip_eng_review`. If it is `true`, eng review is opted out — do not recommend it. Otherwise, eng review is the required shipping gate. If this CEO review expanded scope, changed architectural direction, or accepted scope expansions, emphasize that a fresh eng review is needed. If an eng review already exists in the dashboard but the commit hash shows it predates this CEO review, note that it may be stale and should be re-run.
+
+**Recommend /plan-design-review if UI scope was detected** — specifically if Section 11 (Design & UX Review) was NOT skipped, or if accepted scope expansions included UI-facing features. If an existing design review is stale (commit hash drift), note that. In SCOPE REDUCTION mode, skip this recommendation — design review is unlikely relevant for scope cuts.
+
+**If both are needed, recommend eng review first** (required gate), then design review.
+
+Use AskUserQuestion to present the next step. Include only applicable options:
+- **A)** Run /plan-eng-review next (required gate)
+- **B)** Run /plan-design-review next (only if UI scope detected)
+- **C)** Skip — I'll handle reviews manually
+
+## docs/designs Promotion (EXPANSION and SELECTIVE EXPANSION only)
+
+At the end of the review, if the vision produced a compelling feature direction, offer to promote the CEO plan to the project repo. AskUserQuestion:
+
+"The vision from this review produced {N} accepted scope expansions. Want to promote it to a design doc in the repo?"
+- **A)** Promote to `docs/designs/{FEATURE}.md` (committed to repo, visible to the team)
+- **B)** Keep in `~/.gstack/projects/` only (local, personal reference)
+- **C)** Skip
+
+If promoted, copy the CEO plan content to `docs/designs/{FEATURE}.md` (create the directory if needed) and update the `status` field in the original CEO plan from `ACTIVE` to `PROMOTED`.
+
+## Formatting Rules
+* NUMBER issues (1, 2, 3...) and LETTERS for options (A, B, C...).
+* Label with NUMBER + LETTER (e.g., "3A", "3B").
+* One sentence max per option.
+* After each section, pause and wait for feedback.
+* Use **CRITICAL GAP** / **WARNING** / **OK** for scannability.
+
+## Capture Learnings
+
+If you discovered a non-obvious pattern, pitfall, or architectural insight during
+this session, log it for future sessions:
+
+```bash
+~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"plan-ceo-review","type":"TYPE","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"SOURCE","files":["path/to/relevant/file"]}'
+```
+
+**Types:** `pattern` (reusable approach), `pitfall` (what NOT to do), `preference`
+(user stated), `architecture` (structural decision), `tool` (library/framework insight),
+`operational` (project environment/CLI/workflow knowledge).
+
+**Sources:** `observed` (you found this in the code), `user-stated` (user told you),
+`inferred` (AI deduction), `cross-model` (both Claude and Codex agree).
+
+**Confidence:** 1-10. Be honest. An observed pattern you verified in the code is 8-9.
+An inference you're not sure about is 4-5. A user preference they explicitly stated is 10.
+
+**files:** Include the specific file paths this learning references. This enables
+staleness detection: if those files are later deleted, the learning can be flagged.
+
+**Only log genuine discoveries.** Don't log obvious things. Don't log things the user
+already knows. A good test: would this insight save time in a future session? If yes, log it.
+
+
+
+## Brain Calibration Write-Back (Phase 2 / gated)
+
+When the skill makes a typed prediction worth tracking (scope decision,
+TTHW target, architectural bet, wedge commitment), it MAY write a
+`kind=bet` take to the brain so a calibration profile builds over time.
+
+**Gated on two things:**
+1. Brain trust policy for the active endpoint is `personal` (check via
+   `~/.claude/skills/gstack/bin/gstack-config get brain_trust_policy@<endpoint-hash>`).
+   Shared brains skip write-back to avoid polluting team calibration.
+2. Feature flag `BRAIN_CALIBRATION_WRITEBACK` is set (today: false; flips
+   to true when upstream gbrain v0.42+ ships `takes_add` MCP op).
+
+When both gates pass, the write-back path uses `mcp__gbrain__takes_add`
+to record a take with weight 0.8 (per SKILL_CALIBRATION_WEIGHTS).
+If the MCP op is unavailable, fall back to `mcp__gbrain__put_page` with
+a gstack:takes fence block (documented but uglier path).
+
+Mandatory take frontmatter shape:
+```yaml
+kind: bet
+holder: <user identity from whoami>
+claim: <one-line prediction the skill is making>
+weight: 0.8
+since_date: <today's date>
+expected_resolution: <date in 1-3 months depending on skill>
+source_skill: plan-ceo-review
+```
+
+After write, invalidate the affected digests so the next preflight reflects
+the new state:
+
+```bash
+eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true
+  ~/.claude/skills/gstack/bin/gstack-brain-cache invalidate product --project "$SLUG" 2>/dev/null || true
+  ~/.claude/skills/gstack/bin/gstack-brain-cache invalidate goals --project "$SLUG" 2>/dev/null || true
+  ~/.claude/skills/gstack/bin/gstack-brain-cache invalidate competitive-intel --project "$SLUG" 2>/dev/null || true
+```
+
+
+## Brain Cache Background Refresh
+
+After the skill's work completes (and telemetry has logged), kick a
+background refresh of any cache digest that's getting close to its TTL.
+This is non-blocking — the user doesn't wait. Next invocation benefits
+from the warm cache.
+
+```bash
+eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true
+(~/.claude/skills/gstack/bin/gstack-brain-cache refresh --project "$SLUG" 2>/dev/null &) || true
+```
+
+
+## Mode Quick Reference
+```
+  ┌────────────────────────────────────────────────────────────────────────────────┐
+  │                            MODE COMPARISON                                     │
+  ├─────────────┬──────────────┬──────────────┬──────────────┬────────────────────┤
+  │             │  EXPANSION   │  SELECTIVE   │  HOLD SCOPE  │  REDUCTION         │
+  ├─────────────┼──────────────┼──────────────┼──────────────┼────────────────────┤
+  │ Scope       │ Push UP      │ Hold + offer │ Maintain     │ Push DOWN          │
+  │             │ (opt-in)     │              │              │                    │
+  │ Recommend   │ Enthusiastic │ Neutral      │ N/A          │ N/A                │
+  │ posture     │              │              │              │                    │
+  │ 10x check   │ Mandatory    │ Surface as   │ Optional     │ Skip               │
+  │             │              │ cherry-pick  │              │                    │
+  │ Platonic    │ Yes          │ No           │ No           │ No                 │
+  │ ideal       │              │              │              │                    │
+  │ Delight     │ Opt-in       │ Cherry-pick  │ Note if seen │ Skip               │
+  │ opps        │ ceremony     │ ceremony     │              │                    │
+  │ Complexity  │ "Is it big   │ "Is it right │ "Is it too   │ "Is it the bare    │
+  │ question    │  enough?"    │  + what else │  complex?"   │  minimum?"         │
+  │             │              │  is tempting"│              │                    │
+  │ Taste       │ Yes          │ Yes          │ No           │ No                 │
+  │ calibration │              │              │              │                    │
+  │ Temporal    │ Full (hr 1-6)│ Full (hr 1-6)│ Key decisions│ Skip               │
+  │ interrogate │              │              │  only        │                    │
+  │ Observ.     │ "Joy to      │ "Joy to      │ "Can we      │ "Can we see if     │
+  │ standard    │  operate"    │  operate"    │  debug it?"  │  it's broken?"     │
+  │ Deploy      │ Infra as     │ Safe deploy  │ Safe deploy  │ Simplest possible  │
+  │ standard    │ feature scope│ + cherry-pick│  + rollback  │  deploy            │
+  │             │              │  risk check  │              │                    │
+  │ Error map   │ Full + chaos │ Full + chaos │ Full         │ Critical paths     │
+  │             │  scenarios   │ for accepted │              │  only              │
+  │ CEO plan    │ Written      │ Written      │ Skipped      │ Skipped            │
+  │ Phase 2/3   │ Map accepted │ Map accepted │ Note it      │ Skip               │
+  │ planning    │              │ cherry-picks │              │                    │
+  │ Design      │ "Inevitable" │ If UI scope  │ If UI scope  │ Skip               │
+  │ (Sec 11)    │  UI review   │  detected    │  detected    │                    │
+  └─────────────┴──────────────┴──────────────┴──────────────┴────────────────────┘
+```

plan-ceo-review/sections/review-sections.md.tmpl

@@ -0,0 +1,489 @@
+## Review Sections (11 sections, after scope and mode are agreed)
+
+**Anti-skip rule:** Never condense, abbreviate, or skip any review section (1-11) regardless of plan type (strategy, spec, code, infra). Every section in this skill exists for a reason. "This is a strategy doc so implementation sections don't apply" is always wrong — implementation details are where strategy breaks down. If a section genuinely has zero findings, say "No issues found" and move on — but you must evaluate it.
+
+{{ANTI_SHORTCUT_CLAUSE}}
+
+### Section 1: Architecture Review
+Evaluate and diagram:
+* Overall system design and component boundaries. Draw the dependency graph.
+* Data flow — all four paths. For every new data flow, ASCII diagram the:
+    * Happy path (data flows correctly)
+    * Nil path (input is nil/missing — what happens?)
+    * Empty path (input is present but empty/zero-length — what happens?)
+    * Error path (upstream call fails — what happens?)
+* State machines. ASCII diagram for every new stateful object. Include impossible/invalid transitions and what prevents them.
+* Coupling concerns. Which components are now coupled that weren't before? Is that coupling justified? Draw the before/after dependency graph.
+* Scaling characteristics. What breaks first under 10x load? Under 100x?
+* Single points of failure. Map them.
+* Security architecture. Auth boundaries, data access patterns, API surfaces. For each new endpoint or data mutation: who can call it, what do they get, what can they change?
+* Production failure scenarios. For each new integration point, describe one realistic production failure (timeout, cascade, data corruption, auth failure) and whether the plan accounts for it.
+* Rollback posture. If this ships and immediately breaks, what's the rollback procedure? Git revert? Feature flag? DB migration rollback? How long?
+
+**EXPANSION and SELECTIVE EXPANSION additions:**
+* What would make this architecture beautiful? Not just correct — elegant. Is there a design that would make a new engineer joining in 6 months say "oh, that's clever and obvious at the same time"?
+* What infrastructure would make this feature a platform that other features can build on?
+
+**SELECTIVE EXPANSION:** If any accepted cherry-picks from Step 0D affect the architecture, evaluate their architectural fit here. Flag any that create coupling concerns or don't integrate cleanly — this is a chance to revisit the decision with new information.
+
+Required ASCII diagram: full system architecture showing new components and their relationships to existing ones.
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
+**Reminder: Do NOT make any code changes. Review only.**
+
+### Section 2: Error & Rescue Map
+This is the section that catches silent failures. It is not optional.
+For every new method, service, or codepath that can fail, fill in this table:
+```
+  METHOD/CODEPATH          | WHAT CAN GO WRONG           | EXCEPTION CLASS
+  -------------------------|-----------------------------|-----------------
+  ExampleService#call      | API timeout                 | TimeoutError
+                           | API returns 429             | RateLimitError
+                           | API returns malformed JSON  | JSONParseError
+                           | DB connection pool exhausted| ConnectionPoolExhausted
+                           | Record not found            | RecordNotFound
+  -------------------------|-----------------------------|-----------------
+
+  EXCEPTION CLASS              | RESCUED?  | RESCUE ACTION          | USER SEES
+  -----------------------------|-----------|------------------------|------------------
+  TimeoutError                 | Y         | Retry 2x, then raise   | "Service temporarily unavailable"
+  RateLimitError               | Y         | Backoff + retry         | Nothing (transparent)
+  JSONParseError               | N ← GAP   | —                      | 500 error ← BAD
+  ConnectionPoolExhausted      | N ← GAP   | —                      | 500 error ← BAD
+  RecordNotFound               | Y         | Return nil, log warning | "Not found" message
+```
+Rules for this section:
+* Catch-all error handling (`rescue StandardError`, `catch (Exception e)`, `except Exception`) is ALWAYS a smell. Name the specific exceptions.
+* Catching an error with only a generic log message is insufficient. Log the full context: what was being attempted, with what arguments, for what user/request.
+* Every rescued error must either: retry with backoff, degrade gracefully with a user-visible message, or re-raise with added context. "Swallow and continue" is almost never acceptable.
+* For each GAP (unrescued error that should be rescued): specify the rescue action and what the user should see.
+* For LLM/AI service calls specifically: what happens when the response is malformed? When it's empty? When it hallucinates invalid JSON? When the model returns a refusal? Each of these is a distinct failure mode.
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
+**Reminder: Do NOT make any code changes. Review only.**
+
+### Section 3: Security & Threat Model
+Security is not a sub-bullet of architecture. It gets its own section.
+Evaluate:
+* Attack surface expansion. What new attack vectors does this plan introduce? New endpoints, new params, new file paths, new background jobs?
+* Input validation. For every new user input: is it validated, sanitized, and rejected loudly on failure? What happens with: nil, empty string, string when integer expected, string exceeding max length, unicode edge cases, HTML/script injection attempts?
+* Authorization. For every new data access: is it scoped to the right user/role? Is there a direct object reference vulnerability? Can user A access user B's data by manipulating IDs?
+* Secrets and credentials. New secrets? In env vars, not hardcoded? Rotatable?
+* Dependency risk. New gems/npm packages? Security track record?
+* Data classification. PII, payment data, credentials? Handling consistent with existing patterns?
+* Injection vectors. SQL, command, template, LLM prompt injection — check all.
+* Audit logging. For sensitive operations: is there an audit trail?
+
+For each finding: threat, likelihood (High/Med/Low), impact (High/Med/Low), and whether the plan mitigates it.
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
+**Reminder: Do NOT make any code changes. Review only.**
+
+### Section 4: Data Flow & Interaction Edge Cases
+This section traces data through the system and interactions through the UI with adversarial thoroughness.
+
+**Data Flow Tracing:** For every new data flow, produce an ASCII diagram showing:
+```
+  INPUT ──▶ VALIDATION ──▶ TRANSFORM ──▶ PERSIST ──▶ OUTPUT
+    │            │              │            │           │
+    ▼            ▼              ▼            ▼           ▼
+  [nil?]    [invalid?]    [exception?]  [conflict?]  [stale?]
+  [empty?]  [too long?]   [timeout?]    [dup key?]   [partial?]
+  [wrong    [wrong type?] [OOM?]        [locked?]    [encoding?]
+   type?]
+```
+For each node: what happens on each shadow path? Is it tested?
+
+**Interaction Edge Cases:** For every new user-visible interaction, evaluate:
+```
+  INTERACTION          | EDGE CASE              | HANDLED? | HOW?
+  ---------------------|------------------------|----------|--------
+  Form submission      | Double-click submit    | ?        |
+                       | Submit with stale CSRF | ?        |
+                       | Submit during deploy   | ?        |
+  Async operation      | User navigates away    | ?        |
+                       | Operation times out    | ?        |
+                       | Retry while in-flight  | ?        |
+  List/table view      | Zero results           | ?        |
+                       | 10,000 results         | ?        |
+                       | Results change mid-page| ?        |
+  Background job       | Job fails after 3 of   | ?        |
+                       | 10 items processed     |          |
+                       | Job runs twice (dup)   | ?        |
+                       | Queue backs up 2 hours | ?        |
+```
+Flag any unhandled edge case as a gap. For each gap, specify the fix.
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
+**Reminder: Do NOT make any code changes. Review only.**
+
+### Section 5: Code Quality Review
+Evaluate:
+* Code organization and module structure. Does new code fit existing patterns? If it deviates, is there a reason?
+* DRY violations. Be aggressive. If the same logic exists elsewhere, flag it and reference the file and line.
+* Naming quality. Are new classes, methods, and variables named for what they do, not how they do it?
+* Error handling patterns. (Cross-reference with Section 2 — this section reviews the patterns; Section 2 maps the specifics.)
+* Missing edge cases. List explicitly: "What happens when X is nil?" "When the API returns 429?" etc.
+* Over-engineering check. Any new abstraction solving a problem that doesn't exist yet?
+* Under-engineering check. Anything fragile, assuming happy path only, or missing obvious defensive checks?
+* Cyclomatic complexity. Flag any new method that branches more than 5 times. Propose a refactor.
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
+**Reminder: Do NOT make any code changes. Review only.**
+
+### Section 6: Test Review
+Make a complete diagram of every new thing this plan introduces:
+```
+  NEW UX FLOWS:
+    [list each new user-visible interaction]
+
+  NEW DATA FLOWS:
+    [list each new path data takes through the system]
+
+  NEW CODEPATHS:
+    [list each new branch, condition, or execution path]
+
+  NEW BACKGROUND JOBS / ASYNC WORK:
+    [list each]
+
+  NEW INTEGRATIONS / EXTERNAL CALLS:
+    [list each]
+
+  NEW ERROR/RESCUE PATHS:
+    [list each — cross-reference Section 2]
+```
+For each item in the diagram:
+* What type of test covers it? (Unit / Integration / System / E2E)
+* Does a test for it exist in the plan? If not, write the test spec header.
+* What is the happy path test?
+* What is the failure path test? (Be specific — which failure?)
+* What is the edge case test? (nil, empty, boundary values, concurrent access)
+
+Test ambition check (all modes): For each new feature, answer:
+* What's the test that would make you confident shipping at 2am on a Friday?
+* What's the test a hostile QA engineer would write to break this?
+* What's the chaos test?
+
+Test pyramid check: Many unit, fewer integration, few E2E? Or inverted?
+Flakiness risk: Flag any test depending on time, randomness, external services, or ordering.
+Load/stress test requirements: For any new codepath called frequently or processing significant data.
+
+For LLM/prompt changes: Check CLAUDE.md for the "Prompt/LLM changes" file patterns. If this plan touches ANY of those patterns, state which eval suites must be run, which cases should be added, and what baselines to compare against.
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
+**Reminder: Do NOT make any code changes. Review only.**
+
+### Section 7: Performance Review
+Evaluate:
+* N+1 queries. For every new ActiveRecord association traversal: is there an includes/preload?
+* Memory usage. For every new data structure: what's the maximum size in production?
+* Database indexes. For every new query: is there an index?
+* Caching opportunities. For every expensive computation or external call: should it be cached?
+* Background job sizing. For every new job: worst-case payload, runtime, retry behavior?
+* Slow paths. Top 3 slowest new codepaths and estimated p99 latency.
+* Connection pool pressure. New DB connections, Redis connections, HTTP connections?
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
+**Reminder: Do NOT make any code changes. Review only.**
+
+### Section 8: Observability & Debuggability Review
+New systems break. This section ensures you can see why.
+Evaluate:
+* Logging. For every new codepath: structured log lines at entry, exit, and each significant branch?
+* Metrics. For every new feature: what metric tells you it's working? What tells you it's broken?
+* Tracing. For new cross-service or cross-job flows: trace IDs propagated?
+* Alerting. What new alerts should exist?
+* Dashboards. What new dashboard panels do you want on day 1?
+* Debuggability. If a bug is reported 3 weeks post-ship, can you reconstruct what happened from logs alone?
+* Admin tooling. New operational tasks that need admin UI or rake tasks?
+* Runbooks. For each new failure mode: what's the operational response?
+
+**EXPANSION and SELECTIVE EXPANSION addition:**
+* What observability would make this feature a joy to operate? (For SELECTIVE EXPANSION, include observability for any accepted cherry-picks.)
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
+**Reminder: Do NOT make any code changes. Review only.**
+
+### Section 9: Deployment & Rollout Review
+Evaluate:
+* Migration safety. For every new DB migration: backward-compatible? Zero-downtime? Table locks?
+* Feature flags. Should any part be behind a feature flag?
+* Rollout order. Correct sequence: migrate first, deploy second?
+* Rollback plan. Explicit step-by-step.
+* Deploy-time risk window. Old code and new code running simultaneously — what breaks?
+* Environment parity. Tested in staging?
+* Post-deploy verification checklist. First 5 minutes? First hour?
+* Smoke tests. What automated checks should run immediately post-deploy?
+
+**EXPANSION and SELECTIVE EXPANSION addition:**
+* What deploy infrastructure would make shipping this feature routine? (For SELECTIVE EXPANSION, assess whether accepted cherry-picks change the deployment risk profile.)
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
+**Reminder: Do NOT make any code changes. Review only.**
+
+### Section 10: Long-Term Trajectory Review
+Evaluate:
+* Technical debt introduced. Code debt, operational debt, testing debt, documentation debt.
+* Path dependency. Does this make future changes harder?
+* Knowledge concentration. Documentation sufficient for a new engineer?
+* Reversibility. Rate 1-5: 1 = one-way door, 5 = easily reversible.
+* Ecosystem fit. Aligns with Rails/JS ecosystem direction?
+* The 1-year question. Read this plan as a new engineer in 12 months — obvious?
+
+**EXPANSION and SELECTIVE EXPANSION additions:**
+* What comes after this ships? Phase 2? Phase 3? Does the architecture support that trajectory?
+* Platform potential. Does this create capabilities other features can leverage?
+* (SELECTIVE EXPANSION only) Retrospective: Were the right cherry-picks accepted? Did any rejected expansions turn out to be load-bearing for the accepted ones?
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
+**Reminder: Do NOT make any code changes. Review only.**
+
+### Section 11: Design & UX Review (skip if no UI scope detected)
+The CEO calling in the designer. Not a pixel-level audit — that's /plan-design-review and /design-review. This is ensuring the plan has design intentionality.
+
+Evaluate:
+* Information architecture — what does the user see first, second, third?
+* Interaction state coverage map:
+  FEATURE | LOADING | EMPTY | ERROR | SUCCESS | PARTIAL
+* User journey coherence — storyboard the emotional arc
+* AI slop risk — does the plan describe generic UI patterns?
+* DESIGN.md alignment — does the plan match the stated design system?
+* Responsive intention — is mobile mentioned or afterthought?
+* Accessibility basics — keyboard nav, screen readers, contrast, touch targets
+
+**EXPANSION and SELECTIVE EXPANSION additions:**
+* What would make this UI feel *inevitable*?
+* What 30-minute UI touches would make users think "oh nice, they thought of that"?
+
+Required ASCII diagram: user flow showing screens/states and transitions.
+
+If this plan has significant UI scope, recommend: "Consider running /plan-design-review for a deep design review of this plan before implementation."
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If this section turned up zero findings, state "No issues, moving on" and proceed. If the section has findings, you MUST call AskUserQuestion as a tool_use — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan. Do NOT proceed until the user responds.
+**Reminder: Do NOT make any code changes. Review only.**
+
+{{CODEX_PLAN_REVIEW}}
+
+### Outside Voice Integration Rule
+
+Outside voice findings are INFORMATIONAL until the user explicitly approves each one.
+Do NOT incorporate outside voice recommendations into the plan without presenting each
+finding via AskUserQuestion and getting explicit approval. This applies even when you
+agree with the outside voice. Cross-model consensus is a strong signal — present it as
+such — but the user makes the decision.
+
+## Post-Implementation Design Audit (if UI scope detected)
+After implementation, run `/design-review` on the live site to catch visual issues that can only be evaluated with rendered output.
+
+## CRITICAL RULE — How to ask questions
+Follow the AskUserQuestion format from the Preamble above. Additional rules for plan reviews:
+* **One issue = one AskUserQuestion call.** Never combine multiple issues into one question.
+* Describe the problem concretely, with file and line references.
+* Present 2-3 options, including "do nothing" where reasonable.
+* For each option: effort, risk, and maintenance burden in one line.
+* **Map the reasoning to my engineering preferences above.** One sentence connecting your recommendation to a specific preference.
+* Label with issue NUMBER + option LETTER (e.g., "3A", "3B").
+* **Zero findings:** if a section has zero findings, state "No issues, moving on" and proceed. Otherwise, use AskUserQuestion for each finding — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan.
+
+## Required Outputs
+
+### "NOT in scope" section
+List work considered and explicitly deferred, with one-line rationale each.
+
+### "What already exists" section
+List existing code/flows that partially solve sub-problems and whether the plan reuses them.
+
+### "Dream state delta" section
+Where this plan leaves us relative to the 12-month ideal.
+
+### Error & Rescue Registry (from Section 2)
+Complete table of every method that can fail, every exception class, rescued status, rescue action, user impact.
+
+### Failure Modes Registry
+```
+  CODEPATH | FAILURE MODE   | RESCUED? | TEST? | USER SEES?     | LOGGED?
+  ---------|----------------|----------|-------|----------------|--------
+```
+Any row with RESCUED=N, TEST=N, USER SEES=Silent → **CRITICAL GAP**.
+
+### TODOS.md updates
+Present each potential TODO as its own individual AskUserQuestion. Never batch TODOs — one per question. Never silently skip this step. Follow the format in `.claude/skills/review/TODOS-format.md`.
+
+For each TODO, describe:
+* **What:** One-line description of the work.
+* **Why:** The concrete problem it solves or value it unlocks.
+* **Pros:** What you gain by doing this work.
+* **Cons:** Cost, complexity, or risks of doing it.
+* **Context:** Enough detail that someone picking this up in 3 months understands the motivation, the current state, and where to start.
+* **Effort estimate:** S/M/L/XL (human team) → with CC+gstack: S→S, M→S, L→M, XL→L
+* **Priority:** P1/P2/P3
+* **Depends on / blocked by:** Any prerequisites or ordering constraints.
+
+Then present options: **A)** Add to TODOS.md **B)** Skip — not valuable enough **C)** Build it now in this PR instead of deferring.
+
+### Scope Expansion Decisions (EXPANSION and SELECTIVE EXPANSION only)
+For EXPANSION and SELECTIVE EXPANSION modes: expansion opportunities and delight items were surfaced and decided in Step 0D (opt-in/cherry-pick ceremony). The decisions are persisted in the CEO plan document. Reference the CEO plan for the full record. Do not re-surface them here — list the accepted expansions for completeness:
+* Accepted: {list items added to scope}
+* Deferred: {list items sent to TODOS.md}
+* Skipped: {list items rejected}
+
+### Diagrams (mandatory, produce all that apply)
+1. System architecture
+2. Data flow (including shadow paths)
+3. State machine
+4. Error flow
+5. Deployment sequence
+6. Rollback flowchart
+
+### Stale Diagram Audit
+List every ASCII diagram in files this plan touches. Still accurate?
+
+{{TASKS_SECTION_EMIT:ceo-review}}
+
+### Completion Summary
+```
+  +====================================================================+
+  |            MEGA PLAN REVIEW — COMPLETION SUMMARY                   |
+  +====================================================================+
+  | Mode selected        | EXPANSION / SELECTIVE / HOLD / REDUCTION     |
+  | System Audit         | [key findings]                              |
+  | Step 0               | [mode + key decisions]                      |
+  | Section 1  (Arch)    | ___ issues found                            |
+  | Section 2  (Errors)  | ___ error paths mapped, ___ GAPS            |
+  | Section 3  (Security)| ___ issues found, ___ High severity         |
+  | Section 4  (Data/UX) | ___ edge cases mapped, ___ unhandled        |
+  | Section 5  (Quality) | ___ issues found                            |
+  | Section 6  (Tests)   | Diagram produced, ___ gaps                  |
+  | Section 7  (Perf)    | ___ issues found                            |
+  | Section 8  (Observ)  | ___ gaps found                              |
+  | Section 9  (Deploy)  | ___ risks flagged                           |
+  | Section 10 (Future)  | Reversibility: _/5, debt items: ___         |
+  | Section 11 (Design)  | ___ issues / SKIPPED (no UI scope)          |
+  +--------------------------------------------------------------------+
+  | NOT in scope         | written (___ items)                          |
+  | What already exists  | written                                     |
+  | Dream state delta    | written                                     |
+  | Error/rescue registry| ___ methods, ___ CRITICAL GAPS              |
+  | Failure modes        | ___ total, ___ CRITICAL GAPS                |
+  | TODOS.md updates     | ___ items proposed                          |
+  | Scope proposals      | ___ proposed, ___ accepted (EXP + SEL)      |
+  | CEO plan             | written / skipped (HOLD/REDUCTION)           |
+  | Outside voice        | ran (codex/claude) / skipped                 |
+  | Lake Score           | X/Y recommendations chose complete option   |
+  | Diagrams produced    | ___ (list types)                            |
+  | Stale diagrams found | ___                                         |
+  | Unresolved decisions | ___ (listed below)                          |
+  +====================================================================+
+```
+
+### Unresolved Decisions
+If any AskUserQuestion goes unanswered, note it here. Never silently default.
+
+## Handoff Note Cleanup
+
+After producing the Completion Summary, clean up any handoff notes for this branch —
+the review is complete and the context is no longer needed.
+
+```bash
+setopt +o nomatch 2>/dev/null || true  # zsh compat
+{{SLUG_EVAL}}
+rm -f ~/.gstack/projects/$SLUG/*-$BRANCH-ceo-handoff-*.md 2>/dev/null || true
+```
+
+## Review Log
+
+After producing the Completion Summary above, persist the review result.
+
+**PLAN MODE EXCEPTION — ALWAYS RUN:** This command writes review metadata to
+`~/.gstack/` (user config directory, not project files). The skill preamble
+already writes to `~/.gstack/sessions/` and `~/.gstack/analytics/` — this is
+the same pattern. The review dashboard depends on this data. Skipping this
+command breaks the review readiness dashboard in /ship.
+
+```bash
+~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"plan-ceo-review","timestamp":"TIMESTAMP","status":"STATUS","unresolved":N,"critical_gaps":N,"mode":"MODE","scope_proposed":N,"scope_accepted":N,"scope_deferred":N,"commit":"COMMIT"}'
+```
+
+Before running this command, substitute the placeholder values from the Completion Summary you just produced:
+- **TIMESTAMP**: current ISO 8601 datetime (e.g., 2026-03-16T14:30:00)
+- **STATUS**: "clean" if 0 unresolved decisions AND 0 critical gaps; otherwise "issues_open"
+- **unresolved**: number from "Unresolved decisions" in the summary
+- **critical_gaps**: number from "Failure modes: ___ CRITICAL GAPS" in the summary
+- **MODE**: the mode the user selected (SCOPE_EXPANSION / SELECTIVE_EXPANSION / HOLD_SCOPE / SCOPE_REDUCTION)
+- **scope_proposed**: number from "Scope proposals: ___ proposed" in the summary (0 for HOLD/REDUCTION)
+- **scope_accepted**: number from "Scope proposals: ___ accepted" in the summary (0 for HOLD/REDUCTION)
+- **scope_deferred**: number of items deferred to TODOS.md from scope decisions (0 for HOLD/REDUCTION)
+- **COMMIT**: output of `git rev-parse --short HEAD`
+
+{{REVIEW_DASHBOARD}}
+
+{{PLAN_FILE_REVIEW_REPORT}}
+
+## Next Steps — Review Chaining
+
+After displaying the Review Readiness Dashboard, recommend the next review(s) based on what this CEO review discovered. Read the dashboard output to see which reviews have already been run and whether they are stale.
+
+**Recommend /plan-eng-review if eng review is not skipped globally** — check the dashboard output for `skip_eng_review`. If it is `true`, eng review is opted out — do not recommend it. Otherwise, eng review is the required shipping gate. If this CEO review expanded scope, changed architectural direction, or accepted scope expansions, emphasize that a fresh eng review is needed. If an eng review already exists in the dashboard but the commit hash shows it predates this CEO review, note that it may be stale and should be re-run.
+
+**Recommend /plan-design-review if UI scope was detected** — specifically if Section 11 (Design & UX Review) was NOT skipped, or if accepted scope expansions included UI-facing features. If an existing design review is stale (commit hash drift), note that. In SCOPE REDUCTION mode, skip this recommendation — design review is unlikely relevant for scope cuts.
+
+**If both are needed, recommend eng review first** (required gate), then design review.
+
+Use AskUserQuestion to present the next step. Include only applicable options:
+- **A)** Run /plan-eng-review next (required gate)
+- **B)** Run /plan-design-review next (only if UI scope detected)
+- **C)** Skip — I'll handle reviews manually
+
+## docs/designs Promotion (EXPANSION and SELECTIVE EXPANSION only)
+
+At the end of the review, if the vision produced a compelling feature direction, offer to promote the CEO plan to the project repo. AskUserQuestion:
+
+"The vision from this review produced {N} accepted scope expansions. Want to promote it to a design doc in the repo?"
+- **A)** Promote to `docs/designs/{FEATURE}.md` (committed to repo, visible to the team)
+- **B)** Keep in `~/.gstack/projects/` only (local, personal reference)
+- **C)** Skip
+
+If promoted, copy the CEO plan content to `docs/designs/{FEATURE}.md` (create the directory if needed) and update the `status` field in the original CEO plan from `ACTIVE` to `PROMOTED`.
+
+## Formatting Rules
+* NUMBER issues (1, 2, 3...) and LETTERS for options (A, B, C...).
+* Label with NUMBER + LETTER (e.g., "3A", "3B").
+* One sentence max per option.
+* After each section, pause and wait for feedback.
+* Use **CRITICAL GAP** / **WARNING** / **OK** for scannability.
+
+{{LEARNINGS_LOG}}
+
+{{GBRAIN_SAVE_RESULTS}}
+
+{{BRAIN_WRITE_BACK}}
+
+{{BRAIN_CACHE_REFRESH}}
+
+## Mode Quick Reference
+```
+  ┌────────────────────────────────────────────────────────────────────────────────┐
+  │                            MODE COMPARISON                                     │
+  ├─────────────┬──────────────┬──────────────┬──────────────┬────────────────────┤
+  │             │  EXPANSION   │  SELECTIVE   │  HOLD SCOPE  │  REDUCTION         │
+  ├─────────────┼──────────────┼──────────────┼──────────────┼────────────────────┤
+  │ Scope       │ Push UP      │ Hold + offer │ Maintain     │ Push DOWN          │
+  │             │ (opt-in)     │              │              │                    │
+  │ Recommend   │ Enthusiastic │ Neutral      │ N/A          │ N/A                │
+  │ posture     │              │              │              │                    │
+  │ 10x check   │ Mandatory    │ Surface as   │ Optional     │ Skip               │
+  │             │              │ cherry-pick  │              │                    │
+  │ Platonic    │ Yes          │ No           │ No           │ No                 │
+  │ ideal       │              │              │              │                    │
+  │ Delight     │ Opt-in       │ Cherry-pick  │ Note if seen │ Skip               │
+  │ opps        │ ceremony     │ ceremony     │              │                    │
+  │ Complexity  │ "Is it big   │ "Is it right │ "Is it too   │ "Is it the bare    │
+  │ question    │  enough?"    │  + what else │  complex?"   │  minimum?"         │
+  │             │              │  is tempting"│              │                    │
+  │ Taste       │ Yes          │ Yes          │ No           │ No                 │
+  │ calibration │              │              │              │                    │
+  │ Temporal    │ Full (hr 1-6)│ Full (hr 1-6)│ Key decisions│ Skip               │
+  │ interrogate │              │              │  only        │                    │
+  │ Observ.     │ "Joy to      │ "Joy to      │ "Can we      │ "Can we see if     │
+  │ standard    │  operate"    │  operate"    │  debug it?"  │  it's broken?"     │
+  │ Deploy      │ Infra as     │ Safe deploy  │ Safe deploy  │ Simplest possible  │
+  │ standard    │ feature scope│ + cherry-pick│  + rollback  │  deploy            │
+  │             │              │  risk check  │              │                    │
+  │ Error map   │ Full + chaos │ Full + chaos │ Full         │ Critical paths     │
+  │             │  scenarios   │ for accepted │              │  only              │
+  │ CEO plan    │ Written      │ Written      │ Skipped      │ Skipped            │
+  │ Phase 2/3   │ Map accepted │ Map accepted │ Note it      │ Skip               │
+  │ planning    │              │ cherry-picks │              │                    │
+  │ Design      │ "Inevitable" │ If UI scope  │ If UI scope  │ Skip               │
+  │ (Sec 11)    │  UI review   │  detected    │  detected    │                    │
+  └─────────────┴──────────────┴──────────────┴──────────────┴────────────────────┘
+```

plan-design-review/SKILL.md

@@ -366,25 +366,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 
@@ -1047,6 +1034,18 @@ rm -f /tmp/.gstack-brain-context-$$.md 2>/dev/null || true
 `gstack/`, `concepts/` only). Personal/family/therapy content never leaks here.
 
 
+---
+## Section index — Read each section when its situation applies
+
+This skill is a decision-tree skeleton. The steps below point to on-demand
+sections. Read a section in full before doing its step; do not work from memory.
+
+| When | Read this section |
+|------|-------------------|
+| running the 7 design passes, required outputs, and review report (only after Step 0 scope is agreed) | `sections/review-sections.md` |
+---
+
+
 ## Step 0: Design Scope Assessment
 
 ### 0A. Initial Design Rating
@@ -1388,609 +1387,12 @@ Show the mockup to the user via the Read tool. This makes the gap between
 If the design binary is not available, skip this and continue with text-based
 descriptions of what 10/10 looks like.
 
-## Review Sections (7 passes, after scope is agreed)
+> **STOP.** Before running the 7 design passes, required outputs, and review report (only after Step 0 scope is agreed), Read `~/.claude/skills/gstack/plan-design-review/sections/review-sections.md` and execute it
+> in full. Do not work from memory — that section is the source of truth for this step.
 
-**Anti-skip rule:** Never condense, abbreviate, or skip any review pass (1-7) regardless of plan type (strategy, spec, code, infra). Every pass in this skill exists for a reason. "This is a strategy doc so design passes don't apply" is always wrong — design gaps are where implementation breaks down. If a pass genuinely has zero findings, say "No issues found" and move on — but you must evaluate it.
+## Section self-check (before you finish)
 
-**Anti-shortcut clause:** The plan file is the OUTPUT of the interactive review, not a substitute for it. Writing every finding into one plan write and calling ExitPlanMode without firing AskUserQuestion is the precise failure mode of the May 2026 transcript bug — the model explored, found issues, and dumped them into a deliverable rather than walking the user through them. If you have ANY non-trivial finding in any review section, the path from finding to ExitPlanMode goes THROUGH AskUserQuestion. Zero findings in every section is the only path to ExitPlanMode that bypasses AskUserQuestion. If you find yourself wanting to write a plan with findings before asking, stop and call AskUserQuestion now — that's the bug, recognize it.
+Confirm you Read the review section the Section index named, and executed all 7 design passes, the required outputs, and the review report in full. If you produced findings or the review report from memory without Reading `sections/review-sections.md`, stop and Read it now.
-
-## Prior Learnings
-
-Search for relevant learnings from previous sessions:
-
-```bash
-_CROSS_PROJ=$(~/.claude/skills/gstack/bin/gstack-config get cross_project_learnings 2>/dev/null || echo "unset")
-echo "CROSS_PROJECT: $_CROSS_PROJ"
-if [ "$_CROSS_PROJ" = "true" ]; then
-  ~/.claude/skills/gstack/bin/gstack-learnings-search --limit 10 --cross-project 2>/dev/null || true
-else
-  ~/.claude/skills/gstack/bin/gstack-learnings-search --limit 10 2>/dev/null || true
-fi
-```
-
-If `CROSS_PROJECT` is `unset` (first time): Use AskUserQuestion:
-
-> gstack can search learnings from your other projects on this machine to find
-> patterns that might apply here. This stays local (no data leaves your machine).
-> Recommended for solo developers. Skip if you work on multiple client codebases
-> where cross-contamination would be a concern.
-
-Options:
-- A) Enable cross-project learnings (recommended)
-- B) Keep learnings project-scoped only
-
-If A: run `~/.claude/skills/gstack/bin/gstack-config set cross_project_learnings true`
-If B: run `~/.claude/skills/gstack/bin/gstack-config set cross_project_learnings false`
-
-Then re-run the search with the appropriate flag.
-
-If learnings are found, incorporate them into your analysis. When a review finding
-matches a past learning, display:
-
-**"Prior learning applied: [key] (confidence N/10, from [date])"**
-
-This makes the compounding visible. The user should see that gstack is getting
-smarter on their codebase over time.
-
-### Pass 1: Information Architecture
-Rate 0-10: Does the plan define what the user sees first, second, third?
-FIX TO 10: Add information hierarchy to the plan. Include ASCII diagram of screen/page structure and navigation flow. Apply "constraint worship" — if you can only show 3 things, which 3?
-**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues, say so and move on. Do NOT proceed until user responds.
-
-### Pass 2: Interaction State Coverage
-Rate 0-10: Does the plan specify loading, empty, error, success, partial states?
-FIX TO 10: Add interaction state table to the plan:
-```
-  FEATURE              | LOADING | EMPTY | ERROR | SUCCESS | PARTIAL
-  ---------------------|---------|-------|-------|---------|--------
-  [each UI feature]    | [spec]  | [spec]| [spec]| [spec]  | [spec]
-```
-For each state: describe what the user SEES, not backend behavior.
-Empty states are features — specify warmth, primary action, context.
-**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY.
-
-### Pass 3: User Journey & Emotional Arc
-Rate 0-10: Does the plan consider the user's emotional experience?
-FIX TO 10: Add user journey storyboard:
-```
-  STEP | USER DOES        | USER FEELS      | PLAN SPECIFIES?
-  -----|------------------|-----------------|----------------
-  1    | Lands on page    | [what emotion?] | [what supports it?]
-  ...
-```
-Apply time-horizon design: 5-sec visceral, 5-min behavioral, 5-year reflective.
-**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY.
-
-### Pass 4: AI Slop Risk
-Rate 0-10: Does the plan describe specific, intentional UI — or generic patterns?
-FIX TO 10: Rewrite vague UI descriptions with specific alternatives.
-
-### Design Hard Rules
-
-**Classifier — determine rule set before evaluating:**
-- **MARKETING/LANDING PAGE** (hero-driven, brand-forward, conversion-focused) → apply Landing Page Rules
-- **APP UI** (workspace-driven, data-dense, task-focused: dashboards, admin, settings) → apply App UI Rules
-- **HYBRID** (marketing shell with app-like sections) → apply Landing Page Rules to hero/marketing sections, App UI Rules to functional sections
-
-**Hard rejection criteria** (instant-fail patterns — flag if ANY apply):
-1. Generic SaaS card grid as first impression
-2. Beautiful image with weak brand
-3. Strong headline with no clear action
-4. Busy imagery behind text
-5. Sections repeating same mood statement
-6. Carousel with no narrative purpose
-7. App UI made of stacked cards instead of layout
-
-**Litmus checks** (answer YES/NO for each — used for cross-model consensus scoring):
-1. Brand/product unmistakable in first screen?
-2. One strong visual anchor present?
-3. Page understandable by scanning headlines only?
-4. Each section has one job?
-5. Are cards actually necessary?
-6. Does motion improve hierarchy or atmosphere?
-7. Would design feel premium with all decorative shadows removed?
-
-**Landing page rules** (apply when classifier = MARKETING/LANDING):
-- First viewport reads as one composition, not a dashboard
-- Brand-first hierarchy: brand > headline > body > CTA
-- Typography: expressive, purposeful — no default stacks (Inter, Roboto, Arial, system)
-- No flat single-color backgrounds — use gradients, images, subtle patterns
-- Hero: full-bleed, edge-to-edge, no inset/tiled/rounded variants
-- Hero budget: brand, one headline, one supporting sentence, one CTA group, one image
-- No cards in hero. Cards only when card IS the interaction
-- One job per section: one purpose, one headline, one short supporting sentence
-- Motion: 2-3 intentional motions minimum (entrance, scroll-linked, hover/reveal)
-- Color: define CSS variables, avoid purple-on-white defaults, one accent color default
-- Copy: product language not design commentary. "If deleting 30% improves it, keep deleting"
-- Beautiful defaults: composition-first, brand as loudest text, two typefaces max, cardless by default, first viewport as poster not document
-
-**App UI rules** (apply when classifier = APP UI):
-- Calm surface hierarchy, strong typography, few colors
-- Dense but readable, minimal chrome
-- Organize: primary workspace, navigation, secondary context, one accent
-- Avoid: dashboard-card mosaics, thick borders, decorative gradients, ornamental icons
-- Copy: utility language — orientation, status, action. Not mood/brand/aspiration
-- Cards only when card IS the interaction
-- Section headings state what area is or what user can do ("Selected KPIs", "Plan status")
-
-**Universal rules** (apply to ALL types):
-- Define CSS variables for color system
-- No default font stacks (Inter, Roboto, Arial, system)
-- One job per section
-- "If deleting 30% of the copy improves it, keep deleting"
-- Cards earn their existence — no decorative card grids
-- NEVER use small, low-contrast type (body text < 16px or contrast ratio < 4.5:1 on body text)
-- NEVER put labels inside form fields as the only label (placeholder-as-label pattern — labels must be visible when the field has content)
-- ALWAYS preserve visited vs unvisited link distinction (visited links must have a different color)
-- NEVER float headings between paragraphs (heading must be visually closer to the section it introduces than to the preceding section)
-
-**AI Slop blacklist** (the 10 patterns that scream "AI-generated"):
-1. Purple/violet/indigo gradient backgrounds or blue-to-purple color schemes
-2. **The 3-column feature grid:** icon-in-colored-circle + bold title + 2-line description, repeated 3x symmetrically. THE most recognizable AI layout.
-3. Icons in colored circles as section decoration (SaaS starter template look)
-4. Centered everything (`text-align: center` on all headings, descriptions, cards)
-5. Uniform bubbly border-radius on every element (same large radius on everything)
-6. Decorative blobs, floating circles, wavy SVG dividers (if a section feels empty, it needs better content, not decoration)
-7. Emoji as design elements (rockets in headings, emoji as bullet points)
-8. Colored left-border on cards (`border-left: 3px solid <accent>`)
-9. Generic hero copy ("Welcome to [X]", "Unlock the power of...", "Your all-in-one solution for...")
-10. Cookie-cutter section rhythm (hero → 3 features → testimonials → pricing → CTA, every section same height)
-11. system-ui or `-apple-system` as the PRIMARY display/body font — the "I gave up on typography" signal. Pick a real typeface.
-
-Source: [OpenAI "Designing Delightful Frontends with GPT-5.4"](https://developers.openai.com/blog/designing-delightful-frontends-with-gpt-5-4) (Mar 2026) + gstack design methodology.
-- "Cards with icons" → what differentiates these from every SaaS template?
-- "Hero section" → what makes this hero feel like THIS product?
-- "Clean, modern UI" → meaningless. Replace with actual design decisions.
-- "Dashboard with widgets" → what makes this NOT every other dashboard?
-If visual mockups were generated in Step 0.5, evaluate them against the AI slop blacklist above. Read each mockup image using the Read tool. Does the mockup fall into generic patterns (3-column grid, centered hero, stock-photo feel)? If so, flag it and offer to regenerate with more specific direction via `$D iterate --feedback "..."`.
-**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY.
-
-### Pass 5: Design System Alignment
-Rate 0-10: Does the plan align with DESIGN.md?
-FIX TO 10: If DESIGN.md exists, annotate with specific tokens/components. If no DESIGN.md, flag the gap and recommend `/design-consultation`.
-Flag any new component — does it fit the existing vocabulary?
-**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY.
-
-### Pass 6: Responsive & Accessibility
-Rate 0-10: Does the plan specify mobile/tablet, keyboard nav, screen readers?
-FIX TO 10: Add responsive specs per viewport — not "stacked on mobile" but intentional layout changes. Add a11y: keyboard nav patterns, ARIA landmarks, touch target sizes (44px min), color contrast requirements.
-**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY.
-
-### Pass 7: Unresolved Design Decisions
-Surface ambiguities that will haunt implementation:
-```
-  DECISION NEEDED              | IF DEFERRED, WHAT HAPPENS
-  -----------------------------|---------------------------
-  What does empty state look like? | Engineer ships "No items found."
-  Mobile nav pattern?          | Desktop nav hides behind hamburger
-  ...
-```
-If visual mockups were generated in Step 0.5, reference them as evidence when surfacing unresolved decisions. A mockup makes decisions concrete — e.g., "Your approved mockup shows a sidebar nav, but the plan doesn't specify mobile behavior. What happens to this sidebar on 375px?"
-Each decision = one AskUserQuestion with recommendation + WHY + alternatives. Edit the plan with each decision as it's made.
-
-### Post-Pass: Update Mockups (if generated)
-
-If mockups were generated in Step 0.5 and review passes changed significant design decisions (information architecture restructure, new states, layout changes), offer to regenerate (one-shot, not a loop):
-
-AskUserQuestion: "The review passes changed [list major design changes]. Want me to regenerate mockups to reflect the updated plan? This ensures the visual reference matches what we're actually building."
-
-If yes, use `$D iterate` with feedback summarizing the changes, or `$D variants` with an updated brief. Save to the same `$_DESIGN_DIR` directory.
-
-## CRITICAL RULE — How to ask questions
-Follow the AskUserQuestion format from the Preamble above. Additional rules for plan design reviews:
-* **One issue = one AskUserQuestion call.** Never combine multiple issues into one question.
-* Describe the design gap concretely — what's missing, what the user will experience if it's not specified.
-* Present 2-3 options. For each: effort to specify now, risk if deferred.
-* **Map to Design Principles above.** One sentence connecting your recommendation to a specific principle.
-* Label with issue NUMBER + option LETTER (e.g., "3A", "3B").
-* **Zero findings:** if a section has zero findings, state "No issues, moving on" and proceed. Otherwise, use AskUserQuestion for each gap — a gap with an "obvious fix" is still a gap and still needs user approval before any change lands in the plan.
-* **NEVER use AskUserQuestion to ask which variant the user prefers.** Always create a comparison board first (`$D compare --serve`) and open it in the browser. The board has rating controls, comments, remix/regenerate buttons, and structured feedback output. Use AskUserQuestion ONLY to notify the user the board is open and wait for them to finish — not to present variants inline and ask "which do you prefer?" That is a degraded experience.
-
-## Required Outputs
-
-### "NOT in scope" section
-Design decisions considered and explicitly deferred, with one-line rationale each.
-
-### "What already exists" section
-Existing DESIGN.md, UI patterns, and components that the plan should reuse.
-
-### TODOS.md updates
-After all review passes are complete, present each potential TODO as its own individual AskUserQuestion. Never batch TODOs — one per question. Never silently skip this step.
-
-For design debt: missing a11y, unresolved responsive behavior, deferred empty states. Each TODO gets:
-* **What:** One-line description of the work.
-* **Why:** The concrete problem it solves or value it unlocks.
-* **Pros:** What you gain by doing this work.
-* **Cons:** Cost, complexity, or risks of doing it.
-* **Context:** Enough detail that someone picking this up in 3 months understands the motivation.
-* **Depends on / blocked by:** Any prerequisites.
-
-Then present options: **A)** Add to TODOS.md **B)** Skip — not valuable enough **C)** Build it now in this PR instead of deferring.
-
-## Implementation Tasks
-
-Before closing this review, synthesize the findings above into a flat list of
-build-actionable tasks. Each task derives from a specific finding — no padding.
-Emit the markdown section AND write a JSONL artifact that `/autoplan` can
-aggregate across phases.
-
-### Markdown section (always emit)
-
-```markdown
-## Implementation Tasks
-Synthesized from this review's findings. Each task derives from a specific
-finding above. Run with Claude Code or Codex; checkbox as you ship.
-
-- [ ] **T1 (P1, human: ~2h / CC: ~15min)** — <component> — <imperative title>
-  - Surfaced by: <section name> — <specific finding text or line reference>
-  - Files: <paths to touch>
-  - Verify: <test command or manual check>
-- [ ] **T2 (P2, human: ~30min / CC: ~5min)** — ...
-```
-
-Rules:
-- P1 blocks ship; P2 should land same branch; P3 is a follow-up TODO.
-- If a finding produced no actionable task, do not invent one.
-- If a section had zero findings, emit `_No new tasks from <section>._`
-- Effort uses the AI-compression table from CLAUDE.md.
-
-### JSONL artifact (always write, even if zero tasks)
-
-`/autoplan` reads this file to aggregate across phases. Build each line with
-`jq -nc` so titles and source findings containing quotes, newlines, or
-backslashes serialize cleanly — never use hand-rolled `echo` / `printf`.
-
-```bash
-eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)"
-TASKS_DIR="${HOME}/.gstack/projects/${SLUG:-unknown}"
-mkdir -p "$TASKS_DIR"
-TASKS_FILE="$TASKS_DIR/tasks-design-review-$(date +%Y%m%d-%H%M%S).jsonl"
-COMMIT=$(git rev-parse HEAD 2>/dev/null || echo unknown)
-BRANCH=$(git branch --show-current 2>/dev/null || echo unknown)
-RUN_ID="$(date -u +%Y%m%dT%H%M%SZ)-$$"
-
-# Repeat ONE jq invocation per task identified during this review.
-# Substitute the placeholders inline with shell variables you set per task:
-#   TASK_ID (T1, T2, ...), PRIORITY (P1/P2/P3), COMPONENT, TITLE,
-#   SOURCE_FINDING, EFFORT_HUMAN, EFFORT_CC, FILES_JSON (a JSON array literal
-#   like '["browse/src/sanitize.ts","browse/src/server.ts"]').
-jq -nc \
-  --arg phase 'design-review' \
-  --arg run_id "$RUN_ID" \
-  --arg branch "$BRANCH" \
-  --arg commit "$COMMIT" \
-  --arg id "$TASK_ID" \
-  --arg priority "$PRIORITY" \
-  --arg component "$COMPONENT" \
-  --arg effort_human "$EFFORT_HUMAN" \
-  --arg effort_cc "$EFFORT_CC" \
-  --arg title "$TITLE" \
-  --arg source_finding "$SOURCE_FINDING" \
-  --argjson files "$FILES_JSON" \
-  '{phase:$phase, run_id:$run_id, branch:$branch, commit:$commit, id:$id, priority:$priority, component:$component, files:$files, effort_human:$effort_human, effort_cc:$effort_cc, title:$title, source_finding:$source_finding}' \
-  >> "$TASKS_FILE"
-```
-
-If `jq` is not installed, fall back to skipping the JSONL write and warn
-the user to install jq for autoplan aggregation. Never hand-roll JSONL.
-
-If zero tasks were identified in this review, still touch the JSONL file
-(`: > "$TASKS_FILE"`) so the aggregator sees that the phase produced output
-this run (an empty file means "ran, no findings" — distinct from "didn't run").
-
-
-### Completion Summary
-```
-  +====================================================================+
-  |         DESIGN PLAN REVIEW — COMPLETION SUMMARY                    |
-  +====================================================================+
-  | System Audit         | [DESIGN.md status, UI scope]                |
-  | Step 0               | [initial rating, focus areas]               |
-  | Pass 1  (Info Arch)  | ___/10 → ___/10 after fixes                |
-  | Pass 2  (States)     | ___/10 → ___/10 after fixes                |
-  | Pass 3  (Journey)    | ___/10 → ___/10 after fixes                |
-  | Pass 4  (AI Slop)    | ___/10 → ___/10 after fixes                |
-  | Pass 5  (Design Sys) | ___/10 → ___/10 after fixes                |
-  | Pass 6  (Responsive) | ___/10 → ___/10 after fixes                |
-  | Pass 7  (Decisions)  | ___ resolved, ___ deferred                 |
-  +--------------------------------------------------------------------+
-  | NOT in scope         | written (___ items)                         |
-  | What already exists  | written                                     |
-  | TODOS.md updates     | ___ items proposed                          |
-  | Approved Mockups     | ___ generated, ___ approved                  |
-  | Decisions made       | ___ added to plan                           |
-  | Decisions deferred   | ___ (listed below)                          |
-  | Overall design score | ___/10 → ___/10                             |
-  +====================================================================+
-```
-
-If all passes 8+: "Plan is design-complete. Run /design-review after implementation for visual QA."
-If any below 8: note what's unresolved and why (user chose to defer).
-
-### Unresolved Decisions
-If any AskUserQuestion goes unanswered, note it here. Never silently default to an option.
-
-### Approved Mockups
-
-If visual mockups were generated during this review, add to the plan file:
-
-```
-## Approved Mockups
-
-| Screen/Section | Mockup Path | Direction | Notes |
-|----------------|-------------|-----------|-------|
-| [screen name]  | ~/.gstack/projects/$SLUG/designs/[folder]/[filename].png | [brief description] | [constraints from review] |
-```
-
-Include the full path to each approved mockup (the variant the user chose), a one-line description of the direction, and any constraints. The implementer reads this to know exactly which visual to build from. These persist across conversations and workspaces. If no mockups were generated, omit this section.
-
-## Review Log
-
-After producing the Completion Summary above, persist the review result.
-
-**PLAN MODE EXCEPTION — ALWAYS RUN:** This command writes review metadata to
-`~/.gstack/` (user config directory, not project files). The skill preamble
-already writes to `~/.gstack/sessions/` and `~/.gstack/analytics/` — this is
-the same pattern. The review dashboard depends on this data. Skipping this
-command breaks the review readiness dashboard in /ship.
-
-```bash
-~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"plan-design-review","timestamp":"TIMESTAMP","status":"STATUS","initial_score":N,"overall_score":N,"unresolved":N,"decisions_made":N,"commit":"COMMIT"}'
-```
-
-Substitute values from the Completion Summary:
-- **TIMESTAMP**: current ISO 8601 datetime
-- **STATUS**: "clean" if overall score 8+ AND 0 unresolved; otherwise "issues_open"
-- **initial_score**: initial overall design score before fixes (0-10)
-- **overall_score**: final overall design score after fixes (0-10)
-- **unresolved**: number of unresolved design decisions
-- **decisions_made**: number of design decisions added to the plan
-- **COMMIT**: output of `git rev-parse --short HEAD`
-
-## Review Readiness Dashboard
-
-After completing the review, read the review log and config to display the dashboard.
-
-```bash
-~/.claude/skills/gstack/bin/gstack-review-read
-```
-
-Parse the output. Find the most recent entry for each skill (plan-ceo-review, plan-eng-review, review, plan-design-review, design-review-lite, adversarial-review, codex-review, codex-plan-review). Ignore entries with timestamps older than 7 days. For the Eng Review row, show whichever is more recent between `review` (diff-scoped pre-landing review) and `plan-eng-review` (plan-stage architecture review). Append "(DIFF)" or "(PLAN)" to the status to distinguish. For the Adversarial row, show whichever is more recent between `adversarial-review` (new auto-scaled) and `codex-review` (legacy). For Design Review, show whichever is more recent between `plan-design-review` (full visual audit) and `design-review-lite` (code-level check). Append "(FULL)" or "(LITE)" to the status to distinguish. For the Outside Voice row, show the most recent `codex-plan-review` entry — this captures outside voices from both /plan-ceo-review and /plan-eng-review.
-
-**Source attribution:** If the most recent entry for a skill has a \`"via"\` field, append it to the status label in parentheses. Examples: `plan-eng-review` with `via:"autoplan"` shows as "CLEAR (PLAN via /autoplan)". `review` with `via:"ship"` shows as "CLEAR (DIFF via /ship)". Entries without a `via` field show as "CLEAR (PLAN)" or "CLEAR (DIFF)" as before.
-
-Note: `autoplan-voices` and `design-outside-voices` entries are audit-trail-only (forensic data for cross-model consensus analysis). They do not appear in the dashboard and are not checked by any consumer.
-
-Display:
-
-```
-+====================================================================+
-|                    REVIEW READINESS DASHBOARD                       |
-+====================================================================+
-| Review          | Runs | Last Run            | Status    | Required |
-|-----------------|------|---------------------|-----------|----------|
-| Eng Review      |  1   | 2026-03-16 15:00    | CLEAR     | YES      |
-| CEO Review      |  0   | —                   | —         | no       |
-| Design Review   |  0   | —                   | —         | no       |
-| Adversarial     |  0   | —                   | —         | no       |
-| Outside Voice   |  0   | —                   | —         | no       |
-+--------------------------------------------------------------------+
-| VERDICT: CLEARED — Eng Review passed                                |
-+====================================================================+
-```
-
-**Review tiers:**
-- **Eng Review (required by default):** The only review that gates shipping. Covers architecture, code quality, tests, performance. Can be disabled globally with \`gstack-config set skip_eng_review true\` (the "don't bother me" setting).
-- **CEO Review (optional):** Use your judgment. Recommend it for big product/business changes, new user-facing features, or scope decisions. Skip for bug fixes, refactors, infra, and cleanup.
-- **Design Review (optional):** Use your judgment. Recommend it for UI/UX changes. Skip for backend-only, infra, or prompt-only changes.
-- **Adversarial Review (automatic):** Always-on for every review. Every diff gets both Claude adversarial subagent and Codex adversarial challenge. Large diffs (200+ lines) additionally get Codex structured review with P1 gate. No configuration needed.
-- **Outside Voice (optional):** Independent plan review from a different AI model. Offered after all review sections complete in /plan-ceo-review and /plan-eng-review. Falls back to Claude subagent if Codex is unavailable. Never gates shipping.
-
-**Verdict logic:**
-- **CLEARED**: Eng Review has >= 1 entry within 7 days from either \`review\` or \`plan-eng-review\` with status "clean" (or \`skip_eng_review\` is \`true\`)
-- **NOT CLEARED**: Eng Review missing, stale (>7 days), or has open issues
-- CEO, Design, and Codex reviews are shown for context but never block shipping
-- If \`skip_eng_review\` config is \`true\`, Eng Review shows "SKIPPED (global)" and verdict is CLEARED
-
-**Staleness detection:** After displaying the dashboard, check if any existing reviews may be stale:
-- Parse the \`---HEAD---\` section from the bash output to get the current HEAD commit hash
-- For each review entry that has a \`commit\` field: compare it against the current HEAD. If different, count elapsed commits: \`git rev-list --count STORED_COMMIT..HEAD\`. Display: "Note: {skill} review from {date} may be stale — {N} commits since review"
-- For entries without a \`commit\` field (legacy entries): display "Note: {skill} review from {date} has no commit tracking — consider re-running for accurate staleness detection"
-- If all reviews match the current HEAD, do not display any staleness notes
-
-## Plan File Review Report
-
-After displaying the Review Readiness Dashboard in conversation output, also update the
-**plan file** itself so review status is visible to anyone reading the plan.
-
-### Detect the plan file
-
-1. Check if there is an active plan file in this conversation (the host provides plan file
-   paths in system messages — look for plan file references in the conversation context).
-2. If not found, skip this section silently — not every review runs in plan mode.
-
-### Generate the report
-
-Read the review log output you already have from the Review Readiness Dashboard step above.
-Parse each JSONL entry. Each skill logs different fields:
-
-- **plan-ceo-review**: \`status\`, \`unresolved\`, \`critical_gaps\`, \`mode\`, \`scope_proposed\`, \`scope_accepted\`, \`scope_deferred\`, \`commit\`
-  → Findings: "{scope_proposed} proposals, {scope_accepted} accepted, {scope_deferred} deferred"
-  → If scope fields are 0 or missing (HOLD/REDUCTION mode): "mode: {mode}, {critical_gaps} critical gaps"
-- **plan-eng-review**: \`status\`, \`unresolved\`, \`critical_gaps\`, \`issues_found\`, \`mode\`, \`commit\`
-  → Findings: "{issues_found} issues, {critical_gaps} critical gaps"
-- **plan-design-review**: \`status\`, \`initial_score\`, \`overall_score\`, \`unresolved\`, \`decisions_made\`, \`commit\`
-  → Findings: "score: {initial_score}/10 → {overall_score}/10, {decisions_made} decisions"
-- **plan-devex-review**: \`status\`, \`initial_score\`, \`overall_score\`, \`product_type\`, \`tthw_current\`, \`tthw_target\`, \`mode\`, \`persona\`, \`competitive_tier\`, \`unresolved\`, \`commit\`
-  → Findings: "score: {initial_score}/10 → {overall_score}/10, TTHW: {tthw_current} → {tthw_target}"
-- **devex-review**: \`status\`, \`overall_score\`, \`product_type\`, \`tthw_measured\`, \`dimensions_tested\`, \`dimensions_inferred\`, \`boomerang\`, \`commit\`
-  → Findings: "score: {overall_score}/10, TTHW: {tthw_measured}, {dimensions_tested} tested/{dimensions_inferred} inferred"
-- **codex-review**: \`status\`, \`gate\`, \`findings\`, \`findings_fixed\`
-  → Findings: "{findings} findings, {findings_fixed}/{findings} fixed"
-
-All fields needed for the Findings column are now present in the JSONL entries.
-For the review you just completed, you may use richer details from your own Completion
-Summary. For prior reviews, use the JSONL fields directly — they contain all required data.
-
-Produce this markdown table:
-
-\`\`\`markdown
-## GSTACK REVIEW REPORT
-
-| Review | Trigger | Why | Runs | Status | Findings |
-|--------|---------|-----|------|--------|----------|
-| CEO Review | \`/plan-ceo-review\` | Scope & strategy | {runs} | {status} | {findings} |
-| Codex Review | \`/codex review\` | Independent 2nd opinion | {runs} | {status} | {findings} |
-| Eng Review | \`/plan-eng-review\` | Architecture & tests (required) | {runs} | {status} | {findings} |
-| Design Review | \`/plan-design-review\` | UI/UX gaps | {runs} | {status} | {findings} |
-| DX Review | \`/plan-devex-review\` | Developer experience gaps | {runs} | {status} | {findings} |
-\`\`\`
-
-Below the table, add these lines (omit any that are empty/not applicable):
-
-- **CODEX:** (only if codex-review ran) — one-line summary of codex fixes
-- **CROSS-MODEL:** (only if both Claude and Codex reviews exist) — overlap analysis
-- **UNRESOLVED:** total unresolved decisions across all reviews
-- **VERDICT:** list reviews that are CLEAR (e.g., "CEO + ENG CLEARED — ready to implement").
-  If Eng Review is not CLEAR and not skipped globally, append "eng review required".
-
-### Write to the plan file
-
-**PLAN MODE EXCEPTION — ALWAYS RUN:** This writes to the plan file, which is the one
-file you are allowed to edit in plan mode. The plan file review report is part of the
-plan's living status.
-
-The report must always be the LAST section of the plan file — never mid-file.
-Use a single delete-then-append flow:
-
-1. Read the plan file (Read tool) to see its full current content. Search the read
-   output for a \`## GSTACK REVIEW REPORT\` heading anywhere in the file.
-2. If found, use the Edit tool to DELETE the entire existing section. Match from
-   \`## GSTACK REVIEW REPORT\` through either the next \`## \` heading or end of
-   file, whichever comes first. Replace with the empty string. This applies
-   regardless of where the section currently lives — mid-file deletion is
-   intentional, not a special case. If the Edit fails (e.g., concurrent edit
-   changed the content), re-read the plan file and retry once.
-3. After the delete (or skipped, if no section existed), append the new
-   \`## GSTACK REVIEW REPORT\` section at the END of the file. Use the Edit
-   tool to match the file's current last paragraph and add the section after it,
-   or use Write to re-emit the whole file with the section at the end.
-4. Verify with the Read tool that \`## GSTACK REVIEW REPORT\` is the last
-   \`## \` heading in the file before continuing. If it isn't, repeat steps
-   2-3 once.
-
-Do NOT replace the section in place. The "replace mid-file" path is what allowed
-prior versions to leave the report mid-file when an older report already lived
-there — the user then sees a plan whose review report is not at the bottom and
-(correctly) rejects it.
-
-## Capture Learnings
-
-If you discovered a non-obvious pattern, pitfall, or architectural insight during
-this session, log it for future sessions:
-
-```bash
-~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"plan-design-review","type":"TYPE","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"SOURCE","files":["path/to/relevant/file"]}'
-```
-
-**Types:** `pattern` (reusable approach), `pitfall` (what NOT to do), `preference`
-(user stated), `architecture` (structural decision), `tool` (library/framework insight),
-`operational` (project environment/CLI/workflow knowledge).
-
-**Sources:** `observed` (you found this in the code), `user-stated` (user told you),
-`inferred` (AI deduction), `cross-model` (both Claude and Codex agree).
-
-**Confidence:** 1-10. Be honest. An observed pattern you verified in the code is 8-9.
-An inference you're not sure about is 4-5. A user preference they explicitly stated is 10.
-
-**files:** Include the specific file paths this learning references. This enables
-staleness detection: if those files are later deleted, the learning can be flagged.
-
-**Only log genuine discoveries.** Don't log obvious things. Don't log things the user
-already knows. A good test: would this insight save time in a future session? If yes, log it.
-
-
-
-## Brain Calibration Write-Back (Phase 2 / gated)
-
-When the skill makes a typed prediction worth tracking (scope decision,
-TTHW target, architectural bet, wedge commitment), it MAY write a
-`kind=bet` take to the brain so a calibration profile builds over time.
-
-**Gated on two things:**
-1. Brain trust policy for the active endpoint is `personal` (check via
-   `~/.claude/skills/gstack/bin/gstack-config get brain_trust_policy@<endpoint-hash>`).
-   Shared brains skip write-back to avoid polluting team calibration.
-2. Feature flag `BRAIN_CALIBRATION_WRITEBACK` is set (today: false; flips
-   to true when upstream gbrain v0.42+ ships `takes_add` MCP op).
-
-When both gates pass, the write-back path uses `mcp__gbrain__takes_add`
-to record a take with weight 0.5 (per SKILL_CALIBRATION_WEIGHTS).
-If the MCP op is unavailable, fall back to `mcp__gbrain__put_page` with
-a gstack:takes fence block (documented but uglier path).
-
-Mandatory take frontmatter shape:
-```yaml
-kind: bet
-holder: <user identity from whoami>
-claim: <one-line prediction the skill is making>
-weight: 0.5
-since_date: <today's date>
-expected_resolution: <date in 1-3 months depending on skill>
-source_skill: plan-design-review
-```
-
-After write, invalidate the affected digests so the next preflight reflects
-the new state:
-
-```bash
-eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true
-  ~/.claude/skills/gstack/bin/gstack-brain-cache invalidate brand --project "$SLUG" 2>/dev/null || true
-```
-
-
-## Brain Cache Background Refresh
-
-After the skill's work completes (and telemetry has logged), kick a
-background refresh of any cache digest that's getting close to its TTL.
-This is non-blocking — the user doesn't wait. Next invocation benefits
-from the warm cache.
-
-```bash
-eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true
-(~/.claude/skills/gstack/bin/gstack-brain-cache refresh --project "$SLUG" 2>/dev/null &) || true
-```
-
-
-## Next Steps — Review Chaining
-
-After displaying the Review Readiness Dashboard, recommend the next review(s) based on what this design review discovered. Read the dashboard output to see which reviews have already been run and whether they are stale.
-
-**Recommend /plan-eng-review if eng review is not skipped globally** — check the dashboard output for `skip_eng_review`. If it is `true`, eng review is opted out — do not recommend it. Otherwise, eng review is the required shipping gate. If this design review added significant interaction specifications, new user flows, or changed the information architecture, emphasize that eng review needs to validate the architectural implications. If an eng review already exists but the commit hash shows it predates this design review, note that it may be stale and should be re-run.
-
-**Consider recommending /plan-ceo-review** — but only if this design review revealed fundamental product direction gaps. Specifically: if the overall design score started below 4/10, if the information architecture had major structural problems, or if the review surfaced questions about whether the right problem is being solved. AND no CEO review exists in the dashboard. This is a selective recommendation — most design reviews should NOT trigger a CEO review.
-
-**If both are needed, recommend eng review first** (required gate).
-
-**Recommend design exploration skills when appropriate** — /design-shotgun and /design-html
-produce design artifacts (mockups, HTML previews), not application code. They belong in
-plan mode alongside reviews. If this design review found visual issues that would benefit
-from exploring new directions, recommend /design-shotgun. If approved mockups exist and
-need to be turned into working HTML, recommend /design-html.
-
-Use AskUserQuestion to present the next step. Include only applicable options:
-- **A)** Run /plan-eng-review next (required gate)
-- **B)** Run /plan-ceo-review (only if fundamental product gaps found)
-- **C)** Run /design-shotgun — explore visual design variants for issues found
-- **D)** Run /design-html — generate Pretext-native HTML from approved mockups
-- **E)** Skip — I'll handle next steps manually
-
-## Formatting Rules
-* NUMBER issues (1, 2, 3...) and LETTERS for options (A, B, C...).
-* Label with NUMBER + LETTER (e.g., "3A", "3B").
-* One sentence max per option.
-* After each pass, pause and wait for feedback.
-* Rate before and after each pass for scannability.
 
 ## EXIT PLAN MODE GATE (BLOCKING)
 

plan-design-review/SKILL.md.tmpl

@@ -140,6 +140,11 @@ Report findings before proceeding to Step 0.
 
 {{BRAIN_PREFLIGHT}}
 
+---
+{{SECTION_INDEX:plan-design-review}}
+---
+
+
 ## Step 0: Design Scope Assessment
 
 ### 0A. Initial Design Rating
@@ -263,227 +268,10 @@ Show the mockup to the user via the Read tool. This makes the gap between
 If the design binary is not available, skip this and continue with text-based
 descriptions of what 10/10 looks like.
 
-## Review Sections (7 passes, after scope is agreed)
+{{SECTION:review-sections}}
 
-**Anti-skip rule:** Never condense, abbreviate, or skip any review pass (1-7) regardless of plan type (strategy, spec, code, infra). Every pass in this skill exists for a reason. "This is a strategy doc so design passes don't apply" is always wrong — design gaps are where implementation breaks down. If a pass genuinely has zero findings, say "No issues found" and move on — but you must evaluate it.
+## Section self-check (before you finish)
 
-{{ANTI_SHORTCUT_CLAUSE}}
+Confirm you Read the review section the Section index named, and executed all 7 design passes, the required outputs, and the review report in full. If you produced findings or the review report from memory without Reading `sections/review-sections.md`, stop and Read it now.
-
-{{LEARNINGS_SEARCH}}
-
-### Pass 1: Information Architecture
-Rate 0-10: Does the plan define what the user sees first, second, third?
-FIX TO 10: Add information hierarchy to the plan. Include ASCII diagram of screen/page structure and navigation flow. Apply "constraint worship" — if you can only show 3 things, which 3?
-**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues, say so and move on. Do NOT proceed until user responds.
-
-### Pass 2: Interaction State Coverage
-Rate 0-10: Does the plan specify loading, empty, error, success, partial states?
-FIX TO 10: Add interaction state table to the plan:
-```
-  FEATURE              | LOADING | EMPTY | ERROR | SUCCESS | PARTIAL
-  ---------------------|---------|-------|-------|---------|--------
-  [each UI feature]    | [spec]  | [spec]| [spec]| [spec]  | [spec]
-```
-For each state: describe what the user SEES, not backend behavior.
-Empty states are features — specify warmth, primary action, context.
-**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY.
-
-### Pass 3: User Journey & Emotional Arc
-Rate 0-10: Does the plan consider the user's emotional experience?
-FIX TO 10: Add user journey storyboard:
-```
-  STEP | USER DOES        | USER FEELS      | PLAN SPECIFIES?
-  -----|------------------|-----------------|----------------
-  1    | Lands on page    | [what emotion?] | [what supports it?]
-  ...
-```
-Apply time-horizon design: 5-sec visceral, 5-min behavioral, 5-year reflective.
-**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY.
-
-### Pass 4: AI Slop Risk
-Rate 0-10: Does the plan describe specific, intentional UI — or generic patterns?
-FIX TO 10: Rewrite vague UI descriptions with specific alternatives.
-
-{{DESIGN_HARD_RULES}}
-- "Cards with icons" → what differentiates these from every SaaS template?
-- "Hero section" → what makes this hero feel like THIS product?
-- "Clean, modern UI" → meaningless. Replace with actual design decisions.
-- "Dashboard with widgets" → what makes this NOT every other dashboard?
-If visual mockups were generated in Step 0.5, evaluate them against the AI slop blacklist above. Read each mockup image using the Read tool. Does the mockup fall into generic patterns (3-column grid, centered hero, stock-photo feel)? If so, flag it and offer to regenerate with more specific direction via `$D iterate --feedback "..."`.
-**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY.
-
-### Pass 5: Design System Alignment
-Rate 0-10: Does the plan align with DESIGN.md?
-FIX TO 10: If DESIGN.md exists, annotate with specific tokens/components. If no DESIGN.md, flag the gap and recommend `/design-consultation`.
-Flag any new component — does it fit the existing vocabulary?
-**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY.
-
-### Pass 6: Responsive & Accessibility
-Rate 0-10: Does the plan specify mobile/tablet, keyboard nav, screen readers?
-FIX TO 10: Add responsive specs per viewport — not "stacked on mobile" but intentional layout changes. Add a11y: keyboard nav patterns, ARIA landmarks, touch target sizes (44px min), color contrast requirements.
-**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY.
-
-### Pass 7: Unresolved Design Decisions
-Surface ambiguities that will haunt implementation:
-```
-  DECISION NEEDED              | IF DEFERRED, WHAT HAPPENS
-  -----------------------------|---------------------------
-  What does empty state look like? | Engineer ships "No items found."
-  Mobile nav pattern?          | Desktop nav hides behind hamburger
-  ...
-```
-If visual mockups were generated in Step 0.5, reference them as evidence when surfacing unresolved decisions. A mockup makes decisions concrete — e.g., "Your approved mockup shows a sidebar nav, but the plan doesn't specify mobile behavior. What happens to this sidebar on 375px?"
-Each decision = one AskUserQuestion with recommendation + WHY + alternatives. Edit the plan with each decision as it's made.
-
-### Post-Pass: Update Mockups (if generated)
-
-If mockups were generated in Step 0.5 and review passes changed significant design decisions (information architecture restructure, new states, layout changes), offer to regenerate (one-shot, not a loop):
-
-AskUserQuestion: "The review passes changed [list major design changes]. Want me to regenerate mockups to reflect the updated plan? This ensures the visual reference matches what we're actually building."
-
-If yes, use `$D iterate` with feedback summarizing the changes, or `$D variants` with an updated brief. Save to the same `$_DESIGN_DIR` directory.
-
-## CRITICAL RULE — How to ask questions
-Follow the AskUserQuestion format from the Preamble above. Additional rules for plan design reviews:
-* **One issue = one AskUserQuestion call.** Never combine multiple issues into one question.
-* Describe the design gap concretely — what's missing, what the user will experience if it's not specified.
-* Present 2-3 options. For each: effort to specify now, risk if deferred.
-* **Map to Design Principles above.** One sentence connecting your recommendation to a specific principle.
-* Label with issue NUMBER + option LETTER (e.g., "3A", "3B").
-* **Zero findings:** if a section has zero findings, state "No issues, moving on" and proceed. Otherwise, use AskUserQuestion for each gap — a gap with an "obvious fix" is still a gap and still needs user approval before any change lands in the plan.
-* **NEVER use AskUserQuestion to ask which variant the user prefers.** Always create a comparison board first (`$D compare --serve`) and open it in the browser. The board has rating controls, comments, remix/regenerate buttons, and structured feedback output. Use AskUserQuestion ONLY to notify the user the board is open and wait for them to finish — not to present variants inline and ask "which do you prefer?" That is a degraded experience.
-
-## Required Outputs
-
-### "NOT in scope" section
-Design decisions considered and explicitly deferred, with one-line rationale each.
-
-### "What already exists" section
-Existing DESIGN.md, UI patterns, and components that the plan should reuse.
-
-### TODOS.md updates
-After all review passes are complete, present each potential TODO as its own individual AskUserQuestion. Never batch TODOs — one per question. Never silently skip this step.
-
-For design debt: missing a11y, unresolved responsive behavior, deferred empty states. Each TODO gets:
-* **What:** One-line description of the work.
-* **Why:** The concrete problem it solves or value it unlocks.
-* **Pros:** What you gain by doing this work.
-* **Cons:** Cost, complexity, or risks of doing it.
-* **Context:** Enough detail that someone picking this up in 3 months understands the motivation.
-* **Depends on / blocked by:** Any prerequisites.
-
-Then present options: **A)** Add to TODOS.md **B)** Skip — not valuable enough **C)** Build it now in this PR instead of deferring.
-
-{{TASKS_SECTION_EMIT:design-review}}
-
-### Completion Summary
-```
-  +====================================================================+
-  |         DESIGN PLAN REVIEW — COMPLETION SUMMARY                    |
-  +====================================================================+
-  | System Audit         | [DESIGN.md status, UI scope]                |
-  | Step 0               | [initial rating, focus areas]               |
-  | Pass 1  (Info Arch)  | ___/10 → ___/10 after fixes                |
-  | Pass 2  (States)     | ___/10 → ___/10 after fixes                |
-  | Pass 3  (Journey)    | ___/10 → ___/10 after fixes                |
-  | Pass 4  (AI Slop)    | ___/10 → ___/10 after fixes                |
-  | Pass 5  (Design Sys) | ___/10 → ___/10 after fixes                |
-  | Pass 6  (Responsive) | ___/10 → ___/10 after fixes                |
-  | Pass 7  (Decisions)  | ___ resolved, ___ deferred                 |
-  +--------------------------------------------------------------------+
-  | NOT in scope         | written (___ items)                         |
-  | What already exists  | written                                     |
-  | TODOS.md updates     | ___ items proposed                          |
-  | Approved Mockups     | ___ generated, ___ approved                  |
-  | Decisions made       | ___ added to plan                           |
-  | Decisions deferred   | ___ (listed below)                          |
-  | Overall design score | ___/10 → ___/10                             |
-  +====================================================================+
-```
-
-If all passes 8+: "Plan is design-complete. Run /design-review after implementation for visual QA."
-If any below 8: note what's unresolved and why (user chose to defer).
-
-### Unresolved Decisions
-If any AskUserQuestion goes unanswered, note it here. Never silently default to an option.
-
-### Approved Mockups
-
-If visual mockups were generated during this review, add to the plan file:
-
-```
-## Approved Mockups
-
-| Screen/Section | Mockup Path | Direction | Notes |
-|----------------|-------------|-----------|-------|
-| [screen name]  | ~/.gstack/projects/$SLUG/designs/[folder]/[filename].png | [brief description] | [constraints from review] |
-```
-
-Include the full path to each approved mockup (the variant the user chose), a one-line description of the direction, and any constraints. The implementer reads this to know exactly which visual to build from. These persist across conversations and workspaces. If no mockups were generated, omit this section.
-
-## Review Log
-
-After producing the Completion Summary above, persist the review result.
-
-**PLAN MODE EXCEPTION — ALWAYS RUN:** This command writes review metadata to
-`~/.gstack/` (user config directory, not project files). The skill preamble
-already writes to `~/.gstack/sessions/` and `~/.gstack/analytics/` — this is
-the same pattern. The review dashboard depends on this data. Skipping this
-command breaks the review readiness dashboard in /ship.
-
-```bash
-~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"plan-design-review","timestamp":"TIMESTAMP","status":"STATUS","initial_score":N,"overall_score":N,"unresolved":N,"decisions_made":N,"commit":"COMMIT"}'
-```
-
-Substitute values from the Completion Summary:
-- **TIMESTAMP**: current ISO 8601 datetime
-- **STATUS**: "clean" if overall score 8+ AND 0 unresolved; otherwise "issues_open"
-- **initial_score**: initial overall design score before fixes (0-10)
-- **overall_score**: final overall design score after fixes (0-10)
-- **unresolved**: number of unresolved design decisions
-- **decisions_made**: number of design decisions added to the plan
-- **COMMIT**: output of `git rev-parse --short HEAD`
-
-{{REVIEW_DASHBOARD}}
-
-{{PLAN_FILE_REVIEW_REPORT}}
-
-{{LEARNINGS_LOG}}
-
-{{GBRAIN_SAVE_RESULTS}}
-
-{{BRAIN_WRITE_BACK}}
-
-{{BRAIN_CACHE_REFRESH}}
-
-## Next Steps — Review Chaining
-
-After displaying the Review Readiness Dashboard, recommend the next review(s) based on what this design review discovered. Read the dashboard output to see which reviews have already been run and whether they are stale.
-
-**Recommend /plan-eng-review if eng review is not skipped globally** — check the dashboard output for `skip_eng_review`. If it is `true`, eng review is opted out — do not recommend it. Otherwise, eng review is the required shipping gate. If this design review added significant interaction specifications, new user flows, or changed the information architecture, emphasize that eng review needs to validate the architectural implications. If an eng review already exists but the commit hash shows it predates this design review, note that it may be stale and should be re-run.
-
-**Consider recommending /plan-ceo-review** — but only if this design review revealed fundamental product direction gaps. Specifically: if the overall design score started below 4/10, if the information architecture had major structural problems, or if the review surfaced questions about whether the right problem is being solved. AND no CEO review exists in the dashboard. This is a selective recommendation — most design reviews should NOT trigger a CEO review.
-
-**If both are needed, recommend eng review first** (required gate).
-
-**Recommend design exploration skills when appropriate** — /design-shotgun and /design-html
-produce design artifacts (mockups, HTML previews), not application code. They belong in
-plan mode alongside reviews. If this design review found visual issues that would benefit
-from exploring new directions, recommend /design-shotgun. If approved mockups exist and
-need to be turned into working HTML, recommend /design-html.
-
-Use AskUserQuestion to present the next step. Include only applicable options:
-- **A)** Run /plan-eng-review next (required gate)
-- **B)** Run /plan-ceo-review (only if fundamental product gaps found)
-- **C)** Run /design-shotgun — explore visual design variants for issues found
-- **D)** Run /design-html — generate Pretext-native HTML from approved mockups
-- **E)** Skip — I'll handle next steps manually
-
-## Formatting Rules
-* NUMBER issues (1, 2, 3...) and LETTERS for options (A, B, C...).
-* Label with NUMBER + LETTER (e.g., "3A", "3B").
-* One sentence max per option.
-* After each pass, pause and wait for feedback.
-* Rate before and after each pass for scannability.
 
 {{EXIT_PLAN_MODE_GATE}}

plan-design-review/sections/manifest.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://gstack.dev/schemas/section-manifest.json",
+  "skill": "plan-design-review",
+  "version": 1,
+  "note": "PASSIVE registry (v2 plan T9 / CM2). id/file/title/trigger text ONLY. The skeleton's decision-tree prose decides WHEN to read. See docs/designs/v2_PLAN.md.",
+  "sections": [
+    {
+      "id": "review-sections",
+      "file": "review-sections.md",
+      "title": "7 design passes, required outputs + review report",
+      "trigger": "running the 7 design passes, required outputs, and review report (only after Step 0 scope is agreed)"
+    }
+  ]
+}

plan-design-review/sections/review-sections.md

@@ -0,0 +1,606 @@
+<!-- AUTO-GENERATED from review-sections.md.tmpl — do not edit directly -->
+<!-- Regenerate: bun run gen:skill-docs -->
+## Review Sections (7 passes, after scope is agreed)
+
+**Anti-skip rule:** Never condense, abbreviate, or skip any review pass (1-7) regardless of plan type (strategy, spec, code, infra). Every pass in this skill exists for a reason. "This is a strategy doc so design passes don't apply" is always wrong — design gaps are where implementation breaks down. If a pass genuinely has zero findings, say "No issues found" and move on — but you must evaluate it.
+
+**Anti-shortcut clause:** The plan file is the OUTPUT of the interactive review, not a substitute for it. Writing every finding into one plan write and calling ExitPlanMode without firing AskUserQuestion is the precise failure mode of the May 2026 transcript bug — the model explored, found issues, and dumped them into a deliverable rather than walking the user through them. If you have ANY non-trivial finding in any review section, the path from finding to ExitPlanMode goes THROUGH AskUserQuestion. Zero findings in every section is the only path to ExitPlanMode that bypasses AskUserQuestion. If you find yourself wanting to write a plan with findings before asking, stop and call AskUserQuestion now — that's the bug, recognize it.
+
+## Prior Learnings
+
+Search for relevant learnings from previous sessions:
+
+```bash
+_CROSS_PROJ=$(~/.claude/skills/gstack/bin/gstack-config get cross_project_learnings 2>/dev/null || echo "unset")
+echo "CROSS_PROJECT: $_CROSS_PROJ"
+if [ "$_CROSS_PROJ" = "true" ]; then
+  ~/.claude/skills/gstack/bin/gstack-learnings-search --limit 10 --cross-project 2>/dev/null || true
+else
+  ~/.claude/skills/gstack/bin/gstack-learnings-search --limit 10 2>/dev/null || true
+fi
+```
+
+If `CROSS_PROJECT` is `unset` (first time): Use AskUserQuestion:
+
+> gstack can search learnings from your other projects on this machine to find
+> patterns that might apply here. This stays local (no data leaves your machine).
+> Recommended for solo developers. Skip if you work on multiple client codebases
+> where cross-contamination would be a concern.
+
+Options:
+- A) Enable cross-project learnings (recommended)
+- B) Keep learnings project-scoped only
+
+If A: run `~/.claude/skills/gstack/bin/gstack-config set cross_project_learnings true`
+If B: run `~/.claude/skills/gstack/bin/gstack-config set cross_project_learnings false`
+
+Then re-run the search with the appropriate flag.
+
+If learnings are found, incorporate them into your analysis. When a review finding
+matches a past learning, display:
+
+**"Prior learning applied: [key] (confidence N/10, from [date])"**
+
+This makes the compounding visible. The user should see that gstack is getting
+smarter on their codebase over time.
+
+### Pass 1: Information Architecture
+Rate 0-10: Does the plan define what the user sees first, second, third?
+FIX TO 10: Add information hierarchy to the plan. Include ASCII diagram of screen/page structure and navigation flow. Apply "constraint worship" — if you can only show 3 things, which 3?
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues, say so and move on. Do NOT proceed until user responds.
+
+### Pass 2: Interaction State Coverage
+Rate 0-10: Does the plan specify loading, empty, error, success, partial states?
+FIX TO 10: Add interaction state table to the plan:
+```
+  FEATURE              | LOADING | EMPTY | ERROR | SUCCESS | PARTIAL
+  ---------------------|---------|-------|-------|---------|--------
+  [each UI feature]    | [spec]  | [spec]| [spec]| [spec]  | [spec]
+```
+For each state: describe what the user SEES, not backend behavior.
+Empty states are features — specify warmth, primary action, context.
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY.
+
+### Pass 3: User Journey & Emotional Arc
+Rate 0-10: Does the plan consider the user's emotional experience?
+FIX TO 10: Add user journey storyboard:
+```
+  STEP | USER DOES        | USER FEELS      | PLAN SPECIFIES?
+  -----|------------------|-----------------|----------------
+  1    | Lands on page    | [what emotion?] | [what supports it?]
+  ...
+```
+Apply time-horizon design: 5-sec visceral, 5-min behavioral, 5-year reflective.
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY.
+
+### Pass 4: AI Slop Risk
+Rate 0-10: Does the plan describe specific, intentional UI — or generic patterns?
+FIX TO 10: Rewrite vague UI descriptions with specific alternatives.
+
+### Design Hard Rules
+
+**Classifier — determine rule set before evaluating:**
+- **MARKETING/LANDING PAGE** (hero-driven, brand-forward, conversion-focused) → apply Landing Page Rules
+- **APP UI** (workspace-driven, data-dense, task-focused: dashboards, admin, settings) → apply App UI Rules
+- **HYBRID** (marketing shell with app-like sections) → apply Landing Page Rules to hero/marketing sections, App UI Rules to functional sections
+
+**Hard rejection criteria** (instant-fail patterns — flag if ANY apply):
+1. Generic SaaS card grid as first impression
+2. Beautiful image with weak brand
+3. Strong headline with no clear action
+4. Busy imagery behind text
+5. Sections repeating same mood statement
+6. Carousel with no narrative purpose
+7. App UI made of stacked cards instead of layout
+
+**Litmus checks** (answer YES/NO for each — used for cross-model consensus scoring):
+1. Brand/product unmistakable in first screen?
+2. One strong visual anchor present?
+3. Page understandable by scanning headlines only?
+4. Each section has one job?
+5. Are cards actually necessary?
+6. Does motion improve hierarchy or atmosphere?
+7. Would design feel premium with all decorative shadows removed?
+
+**Landing page rules** (apply when classifier = MARKETING/LANDING):
+- First viewport reads as one composition, not a dashboard
+- Brand-first hierarchy: brand > headline > body > CTA
+- Typography: expressive, purposeful — no default stacks (Inter, Roboto, Arial, system)
+- No flat single-color backgrounds — use gradients, images, subtle patterns
+- Hero: full-bleed, edge-to-edge, no inset/tiled/rounded variants
+- Hero budget: brand, one headline, one supporting sentence, one CTA group, one image
+- No cards in hero. Cards only when card IS the interaction
+- One job per section: one purpose, one headline, one short supporting sentence
+- Motion: 2-3 intentional motions minimum (entrance, scroll-linked, hover/reveal)
+- Color: define CSS variables, avoid purple-on-white defaults, one accent color default
+- Copy: product language not design commentary. "If deleting 30% improves it, keep deleting"
+- Beautiful defaults: composition-first, brand as loudest text, two typefaces max, cardless by default, first viewport as poster not document
+
+**App UI rules** (apply when classifier = APP UI):
+- Calm surface hierarchy, strong typography, few colors
+- Dense but readable, minimal chrome
+- Organize: primary workspace, navigation, secondary context, one accent
+- Avoid: dashboard-card mosaics, thick borders, decorative gradients, ornamental icons
+- Copy: utility language — orientation, status, action. Not mood/brand/aspiration
+- Cards only when card IS the interaction
+- Section headings state what area is or what user can do ("Selected KPIs", "Plan status")
+
+**Universal rules** (apply to ALL types):
+- Define CSS variables for color system
+- No default font stacks (Inter, Roboto, Arial, system)
+- One job per section
+- "If deleting 30% of the copy improves it, keep deleting"
+- Cards earn their existence — no decorative card grids
+- NEVER use small, low-contrast type (body text < 16px or contrast ratio < 4.5:1 on body text)
+- NEVER put labels inside form fields as the only label (placeholder-as-label pattern — labels must be visible when the field has content)
+- ALWAYS preserve visited vs unvisited link distinction (visited links must have a different color)
+- NEVER float headings between paragraphs (heading must be visually closer to the section it introduces than to the preceding section)
+
+**AI Slop blacklist** (the 10 patterns that scream "AI-generated"):
+1. Purple/violet/indigo gradient backgrounds or blue-to-purple color schemes
+2. **The 3-column feature grid:** icon-in-colored-circle + bold title + 2-line description, repeated 3x symmetrically. THE most recognizable AI layout.
+3. Icons in colored circles as section decoration (SaaS starter template look)
+4. Centered everything (`text-align: center` on all headings, descriptions, cards)
+5. Uniform bubbly border-radius on every element (same large radius on everything)
+6. Decorative blobs, floating circles, wavy SVG dividers (if a section feels empty, it needs better content, not decoration)
+7. Emoji as design elements (rockets in headings, emoji as bullet points)
+8. Colored left-border on cards (`border-left: 3px solid <accent>`)
+9. Generic hero copy ("Welcome to [X]", "Unlock the power of...", "Your all-in-one solution for...")
+10. Cookie-cutter section rhythm (hero → 3 features → testimonials → pricing → CTA, every section same height)
+11. system-ui or `-apple-system` as the PRIMARY display/body font — the "I gave up on typography" signal. Pick a real typeface.
+
+Source: [OpenAI "Designing Delightful Frontends with GPT-5.4"](https://developers.openai.com/blog/designing-delightful-frontends-with-gpt-5-4) (Mar 2026) + gstack design methodology.
+- "Cards with icons" → what differentiates these from every SaaS template?
+- "Hero section" → what makes this hero feel like THIS product?
+- "Clean, modern UI" → meaningless. Replace with actual design decisions.
+- "Dashboard with widgets" → what makes this NOT every other dashboard?
+If visual mockups were generated in Step 0.5, evaluate them against the AI slop blacklist above. Read each mockup image using the Read tool. Does the mockup fall into generic patterns (3-column grid, centered hero, stock-photo feel)? If so, flag it and offer to regenerate with more specific direction via `$D iterate --feedback "..."`.
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY.
+
+### Pass 5: Design System Alignment
+Rate 0-10: Does the plan align with DESIGN.md?
+FIX TO 10: If DESIGN.md exists, annotate with specific tokens/components. If no DESIGN.md, flag the gap and recommend `/design-consultation`.
+Flag any new component — does it fit the existing vocabulary?
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY.
+
+### Pass 6: Responsive & Accessibility
+Rate 0-10: Does the plan specify mobile/tablet, keyboard nav, screen readers?
+FIX TO 10: Add responsive specs per viewport — not "stacked on mobile" but intentional layout changes. Add a11y: keyboard nav patterns, ARIA landmarks, touch target sizes (44px min), color contrast requirements.
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY.
+
+### Pass 7: Unresolved Design Decisions
+Surface ambiguities that will haunt implementation:
+```
+  DECISION NEEDED              | IF DEFERRED, WHAT HAPPENS
+  -----------------------------|---------------------------
+  What does empty state look like? | Engineer ships "No items found."
+  Mobile nav pattern?          | Desktop nav hides behind hamburger
+  ...
+```
+If visual mockups were generated in Step 0.5, reference them as evidence when surfacing unresolved decisions. A mockup makes decisions concrete — e.g., "Your approved mockup shows a sidebar nav, but the plan doesn't specify mobile behavior. What happens to this sidebar on 375px?"
+Each decision = one AskUserQuestion with recommendation + WHY + alternatives. Edit the plan with each decision as it's made.
+
+### Post-Pass: Update Mockups (if generated)
+
+If mockups were generated in Step 0.5 and review passes changed significant design decisions (information architecture restructure, new states, layout changes), offer to regenerate (one-shot, not a loop):
+
+AskUserQuestion: "The review passes changed [list major design changes]. Want me to regenerate mockups to reflect the updated plan? This ensures the visual reference matches what we're actually building."
+
+If yes, use `$D iterate` with feedback summarizing the changes, or `$D variants` with an updated brief. Save to the same `$_DESIGN_DIR` directory.
+
+## CRITICAL RULE — How to ask questions
+Follow the AskUserQuestion format from the Preamble above. Additional rules for plan design reviews:
+* **One issue = one AskUserQuestion call.** Never combine multiple issues into one question.
+* Describe the design gap concretely — what's missing, what the user will experience if it's not specified.
+* Present 2-3 options. For each: effort to specify now, risk if deferred.
+* **Map to Design Principles above.** One sentence connecting your recommendation to a specific principle.
+* Label with issue NUMBER + option LETTER (e.g., "3A", "3B").
+* **Zero findings:** if a section has zero findings, state "No issues, moving on" and proceed. Otherwise, use AskUserQuestion for each gap — a gap with an "obvious fix" is still a gap and still needs user approval before any change lands in the plan.
+* **NEVER use AskUserQuestion to ask which variant the user prefers.** Always create a comparison board first (`$D compare --serve`) and open it in the browser. The board has rating controls, comments, remix/regenerate buttons, and structured feedback output. Use AskUserQuestion ONLY to notify the user the board is open and wait for them to finish — not to present variants inline and ask "which do you prefer?" That is a degraded experience.
+
+## Required Outputs
+
+### "NOT in scope" section
+Design decisions considered and explicitly deferred, with one-line rationale each.
+
+### "What already exists" section
+Existing DESIGN.md, UI patterns, and components that the plan should reuse.
+
+### TODOS.md updates
+After all review passes are complete, present each potential TODO as its own individual AskUserQuestion. Never batch TODOs — one per question. Never silently skip this step.
+
+For design debt: missing a11y, unresolved responsive behavior, deferred empty states. Each TODO gets:
+* **What:** One-line description of the work.
+* **Why:** The concrete problem it solves or value it unlocks.
+* **Pros:** What you gain by doing this work.
+* **Cons:** Cost, complexity, or risks of doing it.
+* **Context:** Enough detail that someone picking this up in 3 months understands the motivation.
+* **Depends on / blocked by:** Any prerequisites.
+
+Then present options: **A)** Add to TODOS.md **B)** Skip — not valuable enough **C)** Build it now in this PR instead of deferring.
+
+## Implementation Tasks
+
+Before closing this review, synthesize the findings above into a flat list of
+build-actionable tasks. Each task derives from a specific finding — no padding.
+Emit the markdown section AND write a JSONL artifact that `/autoplan` can
+aggregate across phases.
+
+### Markdown section (always emit)
+
+```markdown
+## Implementation Tasks
+Synthesized from this review's findings. Each task derives from a specific
+finding above. Run with Claude Code or Codex; checkbox as you ship.
+
+- [ ] **T1 (P1, human: ~2h / CC: ~15min)** — <component> — <imperative title>
+  - Surfaced by: <section name> — <specific finding text or line reference>
+  - Files: <paths to touch>
+  - Verify: <test command or manual check>
+- [ ] **T2 (P2, human: ~30min / CC: ~5min)** — ...
+```
+
+Rules:
+- P1 blocks ship; P2 should land same branch; P3 is a follow-up TODO.
+- If a finding produced no actionable task, do not invent one.
+- If a section had zero findings, emit `_No new tasks from <section>._`
+- Effort uses the AI-compression table from CLAUDE.md.
+
+### JSONL artifact (always write, even if zero tasks)
+
+`/autoplan` reads this file to aggregate across phases. Build each line with
+`jq -nc` so titles and source findings containing quotes, newlines, or
+backslashes serialize cleanly — never use hand-rolled `echo` / `printf`.
+
+```bash
+eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)"
+TASKS_DIR="${HOME}/.gstack/projects/${SLUG:-unknown}"
+mkdir -p "$TASKS_DIR"
+TASKS_FILE="$TASKS_DIR/tasks-design-review-$(date +%Y%m%d-%H%M%S).jsonl"
+COMMIT=$(git rev-parse HEAD 2>/dev/null || echo unknown)
+BRANCH=$(git branch --show-current 2>/dev/null || echo unknown)
+RUN_ID="$(date -u +%Y%m%dT%H%M%SZ)-$$"
+
+# Repeat ONE jq invocation per task identified during this review.
+# Substitute the placeholders inline with shell variables you set per task:
+#   TASK_ID (T1, T2, ...), PRIORITY (P1/P2/P3), COMPONENT, TITLE,
+#   SOURCE_FINDING, EFFORT_HUMAN, EFFORT_CC, FILES_JSON (a JSON array literal
+#   like '["browse/src/sanitize.ts","browse/src/server.ts"]').
+jq -nc \
+  --arg phase 'design-review' \
+  --arg run_id "$RUN_ID" \
+  --arg branch "$BRANCH" \
+  --arg commit "$COMMIT" \
+  --arg id "$TASK_ID" \
+  --arg priority "$PRIORITY" \
+  --arg component "$COMPONENT" \
+  --arg effort_human "$EFFORT_HUMAN" \
+  --arg effort_cc "$EFFORT_CC" \
+  --arg title "$TITLE" \
+  --arg source_finding "$SOURCE_FINDING" \
+  --argjson files "$FILES_JSON" \
+  '{phase:$phase, run_id:$run_id, branch:$branch, commit:$commit, id:$id, priority:$priority, component:$component, files:$files, effort_human:$effort_human, effort_cc:$effort_cc, title:$title, source_finding:$source_finding}' \
+  >> "$TASKS_FILE"
+```
+
+If `jq` is not installed, fall back to skipping the JSONL write and warn
+the user to install jq for autoplan aggregation. Never hand-roll JSONL.
+
+If zero tasks were identified in this review, still touch the JSONL file
+(`: > "$TASKS_FILE"`) so the aggregator sees that the phase produced output
+this run (an empty file means "ran, no findings" — distinct from "didn't run").
+
+
+### Completion Summary
+```
+  +====================================================================+
+  |         DESIGN PLAN REVIEW — COMPLETION SUMMARY                    |
+  +====================================================================+
+  | System Audit         | [DESIGN.md status, UI scope]                |
+  | Step 0               | [initial rating, focus areas]               |
+  | Pass 1  (Info Arch)  | ___/10 → ___/10 after fixes                |
+  | Pass 2  (States)     | ___/10 → ___/10 after fixes                |
+  | Pass 3  (Journey)    | ___/10 → ___/10 after fixes                |
+  | Pass 4  (AI Slop)    | ___/10 → ___/10 after fixes                |
+  | Pass 5  (Design Sys) | ___/10 → ___/10 after fixes                |
+  | Pass 6  (Responsive) | ___/10 → ___/10 after fixes                |
+  | Pass 7  (Decisions)  | ___ resolved, ___ deferred                 |
+  +--------------------------------------------------------------------+
+  | NOT in scope         | written (___ items)                         |
+  | What already exists  | written                                     |
+  | TODOS.md updates     | ___ items proposed                          |
+  | Approved Mockups     | ___ generated, ___ approved                  |
+  | Decisions made       | ___ added to plan                           |
+  | Decisions deferred   | ___ (listed below)                          |
+  | Overall design score | ___/10 → ___/10                             |
+  +====================================================================+
+```
+
+If all passes 8+: "Plan is design-complete. Run /design-review after implementation for visual QA."
+If any below 8: note what's unresolved and why (user chose to defer).
+
+### Unresolved Decisions
+If any AskUserQuestion goes unanswered, note it here. Never silently default to an option.
+
+### Approved Mockups
+
+If visual mockups were generated during this review, add to the plan file:
+
+```
+## Approved Mockups
+
+| Screen/Section | Mockup Path | Direction | Notes |
+|----------------|-------------|-----------|-------|
+| [screen name]  | ~/.gstack/projects/$SLUG/designs/[folder]/[filename].png | [brief description] | [constraints from review] |
+```
+
+Include the full path to each approved mockup (the variant the user chose), a one-line description of the direction, and any constraints. The implementer reads this to know exactly which visual to build from. These persist across conversations and workspaces. If no mockups were generated, omit this section.
+
+## Review Log
+
+After producing the Completion Summary above, persist the review result.
+
+**PLAN MODE EXCEPTION — ALWAYS RUN:** This command writes review metadata to
+`~/.gstack/` (user config directory, not project files). The skill preamble
+already writes to `~/.gstack/sessions/` and `~/.gstack/analytics/` — this is
+the same pattern. The review dashboard depends on this data. Skipping this
+command breaks the review readiness dashboard in /ship.
+
+```bash
+~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"plan-design-review","timestamp":"TIMESTAMP","status":"STATUS","initial_score":N,"overall_score":N,"unresolved":N,"decisions_made":N,"commit":"COMMIT"}'
+```
+
+Substitute values from the Completion Summary:
+- **TIMESTAMP**: current ISO 8601 datetime
+- **STATUS**: "clean" if overall score 8+ AND 0 unresolved; otherwise "issues_open"
+- **initial_score**: initial overall design score before fixes (0-10)
+- **overall_score**: final overall design score after fixes (0-10)
+- **unresolved**: number of unresolved design decisions
+- **decisions_made**: number of design decisions added to the plan
+- **COMMIT**: output of `git rev-parse --short HEAD`
+
+## Review Readiness Dashboard
+
+After completing the review, read the review log and config to display the dashboard.
+
+```bash
+~/.claude/skills/gstack/bin/gstack-review-read
+```
+
+Parse the output. Find the most recent entry for each skill (plan-ceo-review, plan-eng-review, review, plan-design-review, design-review-lite, adversarial-review, codex-review, codex-plan-review). Ignore entries with timestamps older than 7 days. For the Eng Review row, show whichever is more recent between `review` (diff-scoped pre-landing review) and `plan-eng-review` (plan-stage architecture review). Append "(DIFF)" or "(PLAN)" to the status to distinguish. For the Adversarial row, show whichever is more recent between `adversarial-review` (new auto-scaled) and `codex-review` (legacy). For Design Review, show whichever is more recent between `plan-design-review` (full visual audit) and `design-review-lite` (code-level check). Append "(FULL)" or "(LITE)" to the status to distinguish. For the Outside Voice row, show the most recent `codex-plan-review` entry — this captures outside voices from both /plan-ceo-review and /plan-eng-review.
+
+**Source attribution:** If the most recent entry for a skill has a \`"via"\` field, append it to the status label in parentheses. Examples: `plan-eng-review` with `via:"autoplan"` shows as "CLEAR (PLAN via /autoplan)". `review` with `via:"ship"` shows as "CLEAR (DIFF via /ship)". Entries without a `via` field show as "CLEAR (PLAN)" or "CLEAR (DIFF)" as before.
+
+Note: `autoplan-voices` and `design-outside-voices` entries are audit-trail-only (forensic data for cross-model consensus analysis). They do not appear in the dashboard and are not checked by any consumer.
+
+Display:
+
+```
++====================================================================+
+|                    REVIEW READINESS DASHBOARD                       |
++====================================================================+
+| Review          | Runs | Last Run            | Status    | Required |
+|-----------------|------|---------------------|-----------|----------|
+| Eng Review      |  1   | 2026-03-16 15:00    | CLEAR     | YES      |
+| CEO Review      |  0   | —                   | —         | no       |
+| Design Review   |  0   | —                   | —         | no       |
+| Adversarial     |  0   | —                   | —         | no       |
+| Outside Voice   |  0   | —                   | —         | no       |
++--------------------------------------------------------------------+
+| VERDICT: CLEARED — Eng Review passed                                |
++====================================================================+
+```
+
+**Review tiers:**
+- **Eng Review (required by default):** The only review that gates shipping. Covers architecture, code quality, tests, performance. Can be disabled globally with \`gstack-config set skip_eng_review true\` (the "don't bother me" setting).
+- **CEO Review (optional):** Use your judgment. Recommend it for big product/business changes, new user-facing features, or scope decisions. Skip for bug fixes, refactors, infra, and cleanup.
+- **Design Review (optional):** Use your judgment. Recommend it for UI/UX changes. Skip for backend-only, infra, or prompt-only changes.
+- **Adversarial Review (automatic):** Always-on for every review. Every diff gets both Claude adversarial subagent and Codex adversarial challenge. Large diffs (200+ lines) additionally get Codex structured review with P1 gate. No configuration needed.
+- **Outside Voice (optional):** Independent plan review from a different AI model. Offered after all review sections complete in /plan-ceo-review and /plan-eng-review. Falls back to Claude subagent if Codex is unavailable. Never gates shipping.
+
+**Verdict logic:**
+- **CLEARED**: Eng Review has >= 1 entry within 7 days from either \`review\` or \`plan-eng-review\` with status "clean" (or \`skip_eng_review\` is \`true\`)
+- **NOT CLEARED**: Eng Review missing, stale (>7 days), or has open issues
+- CEO, Design, and Codex reviews are shown for context but never block shipping
+- If \`skip_eng_review\` config is \`true\`, Eng Review shows "SKIPPED (global)" and verdict is CLEARED
+
+**Staleness detection:** After displaying the dashboard, check if any existing reviews may be stale:
+- Parse the \`---HEAD---\` section from the bash output to get the current HEAD commit hash
+- For each review entry that has a \`commit\` field: compare it against the current HEAD. If different, count elapsed commits: \`git rev-list --count STORED_COMMIT..HEAD\`. Display: "Note: {skill} review from {date} may be stale — {N} commits since review"
+- For entries without a \`commit\` field (legacy entries): display "Note: {skill} review from {date} has no commit tracking — consider re-running for accurate staleness detection"
+- If all reviews match the current HEAD, do not display any staleness notes
+
+## Plan File Review Report
+
+After displaying the Review Readiness Dashboard in conversation output, also update the
+**plan file** itself so review status is visible to anyone reading the plan.
+
+### Detect the plan file
+
+1. Check if there is an active plan file in this conversation (the host provides plan file
+   paths in system messages — look for plan file references in the conversation context).
+2. If not found, skip this section silently — not every review runs in plan mode.
+
+### Generate the report
+
+Read the review log output you already have from the Review Readiness Dashboard step above.
+Parse each JSONL entry. Each skill logs different fields:
+
+- **plan-ceo-review**: \`status\`, \`unresolved\`, \`critical_gaps\`, \`mode\`, \`scope_proposed\`, \`scope_accepted\`, \`scope_deferred\`, \`commit\`
+  → Findings: "{scope_proposed} proposals, {scope_accepted} accepted, {scope_deferred} deferred"
+  → If scope fields are 0 or missing (HOLD/REDUCTION mode): "mode: {mode}, {critical_gaps} critical gaps"
+- **plan-eng-review**: \`status\`, \`unresolved\`, \`critical_gaps\`, \`issues_found\`, \`mode\`, \`commit\`
+  → Findings: "{issues_found} issues, {critical_gaps} critical gaps"
+- **plan-design-review**: \`status\`, \`initial_score\`, \`overall_score\`, \`unresolved\`, \`decisions_made\`, \`commit\`
+  → Findings: "score: {initial_score}/10 → {overall_score}/10, {decisions_made} decisions"
+- **plan-devex-review**: \`status\`, \`initial_score\`, \`overall_score\`, \`product_type\`, \`tthw_current\`, \`tthw_target\`, \`mode\`, \`persona\`, \`competitive_tier\`, \`unresolved\`, \`commit\`
+  → Findings: "score: {initial_score}/10 → {overall_score}/10, TTHW: {tthw_current} → {tthw_target}"
+- **devex-review**: \`status\`, \`overall_score\`, \`product_type\`, \`tthw_measured\`, \`dimensions_tested\`, \`dimensions_inferred\`, \`boomerang\`, \`commit\`
+  → Findings: "score: {overall_score}/10, TTHW: {tthw_measured}, {dimensions_tested} tested/{dimensions_inferred} inferred"
+- **codex-review**: \`status\`, \`gate\`, \`findings\`, \`findings_fixed\`
+  → Findings: "{findings} findings, {findings_fixed}/{findings} fixed"
+
+All fields needed for the Findings column are now present in the JSONL entries.
+For the review you just completed, you may use richer details from your own Completion
+Summary. For prior reviews, use the JSONL fields directly — they contain all required data.
+
+Produce this markdown table:
+
+\`\`\`markdown
+## GSTACK REVIEW REPORT
+
+| Review | Trigger | Why | Runs | Status | Findings |
+|--------|---------|-----|------|--------|----------|
+| CEO Review | \`/plan-ceo-review\` | Scope & strategy | {runs} | {status} | {findings} |
+| Codex Review | \`/codex review\` | Independent 2nd opinion | {runs} | {status} | {findings} |
+| Eng Review | \`/plan-eng-review\` | Architecture & tests (required) | {runs} | {status} | {findings} |
+| Design Review | \`/plan-design-review\` | UI/UX gaps | {runs} | {status} | {findings} |
+| DX Review | \`/plan-devex-review\` | Developer experience gaps | {runs} | {status} | {findings} |
+\`\`\`
+
+Below the table, add these lines (omit any that are empty/not applicable):
+
+- **CODEX:** (only if codex-review ran) — one-line summary of codex fixes
+- **CROSS-MODEL:** (only if both Claude and Codex reviews exist) — overlap analysis
+- **UNRESOLVED:** total unresolved decisions across all reviews
+- **VERDICT:** list reviews that are CLEAR (e.g., "CEO + ENG CLEARED — ready to implement").
+  If Eng Review is not CLEAR and not skipped globally, append "eng review required".
+
+### Write to the plan file
+
+**PLAN MODE EXCEPTION — ALWAYS RUN:** This writes to the plan file, which is the one
+file you are allowed to edit in plan mode. The plan file review report is part of the
+plan's living status.
+
+The report must always be the LAST section of the plan file — never mid-file.
+Use a single delete-then-append flow:
+
+1. Read the plan file (Read tool) to see its full current content. Search the read
+   output for a \`## GSTACK REVIEW REPORT\` heading anywhere in the file.
+2. If found, use the Edit tool to DELETE the entire existing section. Match from
+   \`## GSTACK REVIEW REPORT\` through either the next \`## \` heading or end of
+   file, whichever comes first. Replace with the empty string. This applies
+   regardless of where the section currently lives — mid-file deletion is
+   intentional, not a special case. If the Edit fails (e.g., concurrent edit
+   changed the content), re-read the plan file and retry once.
+3. After the delete (or skipped, if no section existed), append the new
+   \`## GSTACK REVIEW REPORT\` section at the END of the file. Use the Edit
+   tool to match the file's current last paragraph and add the section after it,
+   or use Write to re-emit the whole file with the section at the end.
+4. Verify with the Read tool that \`## GSTACK REVIEW REPORT\` is the last
+   \`## \` heading in the file before continuing. If it isn't, repeat steps
+   2-3 once.
+
+Do NOT replace the section in place. The "replace mid-file" path is what allowed
+prior versions to leave the report mid-file when an older report already lived
+there — the user then sees a plan whose review report is not at the bottom and
+(correctly) rejects it.
+
+## Capture Learnings
+
+If you discovered a non-obvious pattern, pitfall, or architectural insight during
+this session, log it for future sessions:
+
+```bash
+~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"plan-design-review","type":"TYPE","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"SOURCE","files":["path/to/relevant/file"]}'
+```
+
+**Types:** `pattern` (reusable approach), `pitfall` (what NOT to do), `preference`
+(user stated), `architecture` (structural decision), `tool` (library/framework insight),
+`operational` (project environment/CLI/workflow knowledge).
+
+**Sources:** `observed` (you found this in the code), `user-stated` (user told you),
+`inferred` (AI deduction), `cross-model` (both Claude and Codex agree).
+
+**Confidence:** 1-10. Be honest. An observed pattern you verified in the code is 8-9.
+An inference you're not sure about is 4-5. A user preference they explicitly stated is 10.
+
+**files:** Include the specific file paths this learning references. This enables
+staleness detection: if those files are later deleted, the learning can be flagged.
+
+**Only log genuine discoveries.** Don't log obvious things. Don't log things the user
+already knows. A good test: would this insight save time in a future session? If yes, log it.
+
+
+
+## Brain Calibration Write-Back (Phase 2 / gated)
+
+When the skill makes a typed prediction worth tracking (scope decision,
+TTHW target, architectural bet, wedge commitment), it MAY write a
+`kind=bet` take to the brain so a calibration profile builds over time.
+
+**Gated on two things:**
+1. Brain trust policy for the active endpoint is `personal` (check via
+   `~/.claude/skills/gstack/bin/gstack-config get brain_trust_policy@<endpoint-hash>`).
+   Shared brains skip write-back to avoid polluting team calibration.
+2. Feature flag `BRAIN_CALIBRATION_WRITEBACK` is set (today: false; flips
+   to true when upstream gbrain v0.42+ ships `takes_add` MCP op).
+
+When both gates pass, the write-back path uses `mcp__gbrain__takes_add`
+to record a take with weight 0.5 (per SKILL_CALIBRATION_WEIGHTS).
+If the MCP op is unavailable, fall back to `mcp__gbrain__put_page` with
+a gstack:takes fence block (documented but uglier path).
+
+Mandatory take frontmatter shape:
+```yaml
+kind: bet
+holder: <user identity from whoami>
+claim: <one-line prediction the skill is making>
+weight: 0.5
+since_date: <today's date>
+expected_resolution: <date in 1-3 months depending on skill>
+source_skill: plan-design-review
+```
+
+After write, invalidate the affected digests so the next preflight reflects
+the new state:
+
+```bash
+eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true
+  ~/.claude/skills/gstack/bin/gstack-brain-cache invalidate brand --project "$SLUG" 2>/dev/null || true
+```
+
+
+## Brain Cache Background Refresh
+
+After the skill's work completes (and telemetry has logged), kick a
+background refresh of any cache digest that's getting close to its TTL.
+This is non-blocking — the user doesn't wait. Next invocation benefits
+from the warm cache.
+
+```bash
+eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true
+(~/.claude/skills/gstack/bin/gstack-brain-cache refresh --project "$SLUG" 2>/dev/null &) || true
+```
+
+
+## Next Steps — Review Chaining
+
+After displaying the Review Readiness Dashboard, recommend the next review(s) based on what this design review discovered. Read the dashboard output to see which reviews have already been run and whether they are stale.
+
+**Recommend /plan-eng-review if eng review is not skipped globally** — check the dashboard output for `skip_eng_review`. If it is `true`, eng review is opted out — do not recommend it. Otherwise, eng review is the required shipping gate. If this design review added significant interaction specifications, new user flows, or changed the information architecture, emphasize that eng review needs to validate the architectural implications. If an eng review already exists but the commit hash shows it predates this design review, note that it may be stale and should be re-run.
+
+**Consider recommending /plan-ceo-review** — but only if this design review revealed fundamental product direction gaps. Specifically: if the overall design score started below 4/10, if the information architecture had major structural problems, or if the review surfaced questions about whether the right problem is being solved. AND no CEO review exists in the dashboard. This is a selective recommendation — most design reviews should NOT trigger a CEO review.
+
+**If both are needed, recommend eng review first** (required gate).
+
+**Recommend design exploration skills when appropriate** — /design-shotgun and /design-html
+produce design artifacts (mockups, HTML previews), not application code. They belong in
+plan mode alongside reviews. If this design review found visual issues that would benefit
+from exploring new directions, recommend /design-shotgun. If approved mockups exist and
+need to be turned into working HTML, recommend /design-html.
+
+Use AskUserQuestion to present the next step. Include only applicable options:
+- **A)** Run /plan-eng-review next (required gate)
+- **B)** Run /plan-ceo-review (only if fundamental product gaps found)
+- **C)** Run /design-shotgun — explore visual design variants for issues found
+- **D)** Run /design-html — generate Pretext-native HTML from approved mockups
+- **E)** Skip — I'll handle next steps manually
+
+## Formatting Rules
+* NUMBER issues (1, 2, 3...) and LETTERS for options (A, B, C...).
+* Label with NUMBER + LETTER (e.g., "3A", "3B").
+* One sentence max per option.
+* After each pass, pause and wait for feedback.
+* Rate before and after each pass for scannability.
+

plan-design-review/sections/review-sections.md.tmpl

@@ -0,0 +1,223 @@
+## Review Sections (7 passes, after scope is agreed)
+
+**Anti-skip rule:** Never condense, abbreviate, or skip any review pass (1-7) regardless of plan type (strategy, spec, code, infra). Every pass in this skill exists for a reason. "This is a strategy doc so design passes don't apply" is always wrong — design gaps are where implementation breaks down. If a pass genuinely has zero findings, say "No issues found" and move on — but you must evaluate it.
+
+{{ANTI_SHORTCUT_CLAUSE}}
+
+{{LEARNINGS_SEARCH}}
+
+### Pass 1: Information Architecture
+Rate 0-10: Does the plan define what the user sees first, second, third?
+FIX TO 10: Add information hierarchy to the plan. Include ASCII diagram of screen/page structure and navigation flow. Apply "constraint worship" — if you can only show 3 things, which 3?
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues, say so and move on. Do NOT proceed until user responds.
+
+### Pass 2: Interaction State Coverage
+Rate 0-10: Does the plan specify loading, empty, error, success, partial states?
+FIX TO 10: Add interaction state table to the plan:
+```
+  FEATURE              | LOADING | EMPTY | ERROR | SUCCESS | PARTIAL
+  ---------------------|---------|-------|-------|---------|--------
+  [each UI feature]    | [spec]  | [spec]| [spec]| [spec]  | [spec]
+```
+For each state: describe what the user SEES, not backend behavior.
+Empty states are features — specify warmth, primary action, context.
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY.
+
+### Pass 3: User Journey & Emotional Arc
+Rate 0-10: Does the plan consider the user's emotional experience?
+FIX TO 10: Add user journey storyboard:
+```
+  STEP | USER DOES        | USER FEELS      | PLAN SPECIFIES?
+  -----|------------------|-----------------|----------------
+  1    | Lands on page    | [what emotion?] | [what supports it?]
+  ...
+```
+Apply time-horizon design: 5-sec visceral, 5-min behavioral, 5-year reflective.
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY.
+
+### Pass 4: AI Slop Risk
+Rate 0-10: Does the plan describe specific, intentional UI — or generic patterns?
+FIX TO 10: Rewrite vague UI descriptions with specific alternatives.
+
+{{DESIGN_HARD_RULES}}
+- "Cards with icons" → what differentiates these from every SaaS template?
+- "Hero section" → what makes this hero feel like THIS product?
+- "Clean, modern UI" → meaningless. Replace with actual design decisions.
+- "Dashboard with widgets" → what makes this NOT every other dashboard?
+If visual mockups were generated in Step 0.5, evaluate them against the AI slop blacklist above. Read each mockup image using the Read tool. Does the mockup fall into generic patterns (3-column grid, centered hero, stock-photo feel)? If so, flag it and offer to regenerate with more specific direction via `$D iterate --feedback "..."`.
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY.
+
+### Pass 5: Design System Alignment
+Rate 0-10: Does the plan align with DESIGN.md?
+FIX TO 10: If DESIGN.md exists, annotate with specific tokens/components. If no DESIGN.md, flag the gap and recommend `/design-consultation`.
+Flag any new component — does it fit the existing vocabulary?
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY.
+
+### Pass 6: Responsive & Accessibility
+Rate 0-10: Does the plan specify mobile/tablet, keyboard nav, screen readers?
+FIX TO 10: Add responsive specs per viewport — not "stacked on mobile" but intentional layout changes. Add a11y: keyboard nav patterns, ARIA landmarks, touch target sizes (44px min), color contrast requirements.
+**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY.
+
+### Pass 7: Unresolved Design Decisions
+Surface ambiguities that will haunt implementation:
+```
+  DECISION NEEDED              | IF DEFERRED, WHAT HAPPENS
+  -----------------------------|---------------------------
+  What does empty state look like? | Engineer ships "No items found."
+  Mobile nav pattern?          | Desktop nav hides behind hamburger
+  ...
+```
+If visual mockups were generated in Step 0.5, reference them as evidence when surfacing unresolved decisions. A mockup makes decisions concrete — e.g., "Your approved mockup shows a sidebar nav, but the plan doesn't specify mobile behavior. What happens to this sidebar on 375px?"
+Each decision = one AskUserQuestion with recommendation + WHY + alternatives. Edit the plan with each decision as it's made.
+
+### Post-Pass: Update Mockups (if generated)
+
+If mockups were generated in Step 0.5 and review passes changed significant design decisions (information architecture restructure, new states, layout changes), offer to regenerate (one-shot, not a loop):
+
+AskUserQuestion: "The review passes changed [list major design changes]. Want me to regenerate mockups to reflect the updated plan? This ensures the visual reference matches what we're actually building."
+
+If yes, use `$D iterate` with feedback summarizing the changes, or `$D variants` with an updated brief. Save to the same `$_DESIGN_DIR` directory.
+
+## CRITICAL RULE — How to ask questions
+Follow the AskUserQuestion format from the Preamble above. Additional rules for plan design reviews:
+* **One issue = one AskUserQuestion call.** Never combine multiple issues into one question.
+* Describe the design gap concretely — what's missing, what the user will experience if it's not specified.
+* Present 2-3 options. For each: effort to specify now, risk if deferred.
+* **Map to Design Principles above.** One sentence connecting your recommendation to a specific principle.
+* Label with issue NUMBER + option LETTER (e.g., "3A", "3B").
+* **Zero findings:** if a section has zero findings, state "No issues, moving on" and proceed. Otherwise, use AskUserQuestion for each gap — a gap with an "obvious fix" is still a gap and still needs user approval before any change lands in the plan.
+* **NEVER use AskUserQuestion to ask which variant the user prefers.** Always create a comparison board first (`$D compare --serve`) and open it in the browser. The board has rating controls, comments, remix/regenerate buttons, and structured feedback output. Use AskUserQuestion ONLY to notify the user the board is open and wait for them to finish — not to present variants inline and ask "which do you prefer?" That is a degraded experience.
+
+## Required Outputs
+
+### "NOT in scope" section
+Design decisions considered and explicitly deferred, with one-line rationale each.
+
+### "What already exists" section
+Existing DESIGN.md, UI patterns, and components that the plan should reuse.
+
+### TODOS.md updates
+After all review passes are complete, present each potential TODO as its own individual AskUserQuestion. Never batch TODOs — one per question. Never silently skip this step.
+
+For design debt: missing a11y, unresolved responsive behavior, deferred empty states. Each TODO gets:
+* **What:** One-line description of the work.
+* **Why:** The concrete problem it solves or value it unlocks.
+* **Pros:** What you gain by doing this work.
+* **Cons:** Cost, complexity, or risks of doing it.
+* **Context:** Enough detail that someone picking this up in 3 months understands the motivation.
+* **Depends on / blocked by:** Any prerequisites.
+
+Then present options: **A)** Add to TODOS.md **B)** Skip — not valuable enough **C)** Build it now in this PR instead of deferring.
+
+{{TASKS_SECTION_EMIT:design-review}}
+
+### Completion Summary
+```
+  +====================================================================+
+  |         DESIGN PLAN REVIEW — COMPLETION SUMMARY                    |
+  +====================================================================+
+  | System Audit         | [DESIGN.md status, UI scope]                |
+  | Step 0               | [initial rating, focus areas]               |
+  | Pass 1  (Info Arch)  | ___/10 → ___/10 after fixes                |
+  | Pass 2  (States)     | ___/10 → ___/10 after fixes                |
+  | Pass 3  (Journey)    | ___/10 → ___/10 after fixes                |
+  | Pass 4  (AI Slop)    | ___/10 → ___/10 after fixes                |
+  | Pass 5  (Design Sys) | ___/10 → ___/10 after fixes                |
+  | Pass 6  (Responsive) | ___/10 → ___/10 after fixes                |
+  | Pass 7  (Decisions)  | ___ resolved, ___ deferred                 |
+  +--------------------------------------------------------------------+
+  | NOT in scope         | written (___ items)                         |
+  | What already exists  | written                                     |
+  | TODOS.md updates     | ___ items proposed                          |
+  | Approved Mockups     | ___ generated, ___ approved                  |
+  | Decisions made       | ___ added to plan                           |
+  | Decisions deferred   | ___ (listed below)                          |
+  | Overall design score | ___/10 → ___/10                             |
+  +====================================================================+
+```
+
+If all passes 8+: "Plan is design-complete. Run /design-review after implementation for visual QA."
+If any below 8: note what's unresolved and why (user chose to defer).
+
+### Unresolved Decisions
+If any AskUserQuestion goes unanswered, note it here. Never silently default to an option.
+
+### Approved Mockups
+
+If visual mockups were generated during this review, add to the plan file:
+
+```
+## Approved Mockups
+
+| Screen/Section | Mockup Path | Direction | Notes |
+|----------------|-------------|-----------|-------|
+| [screen name]  | ~/.gstack/projects/$SLUG/designs/[folder]/[filename].png | [brief description] | [constraints from review] |
+```
+
+Include the full path to each approved mockup (the variant the user chose), a one-line description of the direction, and any constraints. The implementer reads this to know exactly which visual to build from. These persist across conversations and workspaces. If no mockups were generated, omit this section.
+
+## Review Log
+
+After producing the Completion Summary above, persist the review result.
+
+**PLAN MODE EXCEPTION — ALWAYS RUN:** This command writes review metadata to
+`~/.gstack/` (user config directory, not project files). The skill preamble
+already writes to `~/.gstack/sessions/` and `~/.gstack/analytics/` — this is
+the same pattern. The review dashboard depends on this data. Skipping this
+command breaks the review readiness dashboard in /ship.
+
+```bash
+~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"plan-design-review","timestamp":"TIMESTAMP","status":"STATUS","initial_score":N,"overall_score":N,"unresolved":N,"decisions_made":N,"commit":"COMMIT"}'
+```
+
+Substitute values from the Completion Summary:
+- **TIMESTAMP**: current ISO 8601 datetime
+- **STATUS**: "clean" if overall score 8+ AND 0 unresolved; otherwise "issues_open"
+- **initial_score**: initial overall design score before fixes (0-10)
+- **overall_score**: final overall design score after fixes (0-10)
+- **unresolved**: number of unresolved design decisions
+- **decisions_made**: number of design decisions added to the plan
+- **COMMIT**: output of `git rev-parse --short HEAD`
+
+{{REVIEW_DASHBOARD}}
+
+{{PLAN_FILE_REVIEW_REPORT}}
+
+{{LEARNINGS_LOG}}
+
+{{GBRAIN_SAVE_RESULTS}}
+
+{{BRAIN_WRITE_BACK}}
+
+{{BRAIN_CACHE_REFRESH}}
+
+## Next Steps — Review Chaining
+
+After displaying the Review Readiness Dashboard, recommend the next review(s) based on what this design review discovered. Read the dashboard output to see which reviews have already been run and whether they are stale.
+
+**Recommend /plan-eng-review if eng review is not skipped globally** — check the dashboard output for `skip_eng_review`. If it is `true`, eng review is opted out — do not recommend it. Otherwise, eng review is the required shipping gate. If this design review added significant interaction specifications, new user flows, or changed the information architecture, emphasize that eng review needs to validate the architectural implications. If an eng review already exists but the commit hash shows it predates this design review, note that it may be stale and should be re-run.
+
+**Consider recommending /plan-ceo-review** — but only if this design review revealed fundamental product direction gaps. Specifically: if the overall design score started below 4/10, if the information architecture had major structural problems, or if the review surfaced questions about whether the right problem is being solved. AND no CEO review exists in the dashboard. This is a selective recommendation — most design reviews should NOT trigger a CEO review.
+
+**If both are needed, recommend eng review first** (required gate).
+
+**Recommend design exploration skills when appropriate** — /design-shotgun and /design-html
+produce design artifacts (mockups, HTML previews), not application code. They belong in
+plan mode alongside reviews. If this design review found visual issues that would benefit
+from exploring new directions, recommend /design-shotgun. If approved mockups exist and
+need to be turned into working HTML, recommend /design-html.
+
+Use AskUserQuestion to present the next step. Include only applicable options:
+- **A)** Run /plan-eng-review next (required gate)
+- **B)** Run /plan-ceo-review (only if fundamental product gaps found)
+- **C)** Run /design-shotgun — explore visual design variants for issues found
+- **D)** Run /design-html — generate Pretext-native HTML from approved mockups
+- **E)** Skip — I'll handle next steps manually
+
+## Formatting Rules
+* NUMBER issues (1, 2, 3...) and LETTERS for options (A, B, C...).
+* Label with NUMBER + LETTER (e.g., "3A", "3B").
+* One sentence max per option.
+* After each pass, pause and wait for feedback.
+* Rate before and after each pass for scannability.
+

plan-devex-review/SKILL.md

@@ -372,25 +372,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 
@@ -1042,6 +1029,18 @@ rm -f /tmp/.gstack-brain-context-$$.md 2>/dev/null || true
 `gstack/`, `concepts/` only). Personal/family/therapy content never leaks here.
 
 
+---
+## Section index — Read each section when its situation applies
+
+This skill is a decision-tree skeleton. The steps below point to on-demand
+sections. Read a section in full before doing its step; do not work from memory.
+
+| When | Read this section |
+|------|-------------------|
+| running the 8 DX passes, required outputs, and review report (only after Step 0 investigation is complete) | `sections/review-sections.md` |
+---
+
+
 ## Step 0: DX Investigation (before scoring)
 
 The core principle: **gather evidence and force decisions BEFORE scoring, not during
@@ -1351,839 +1350,12 @@ Pattern:
 - **DX TRIAGE:** Only flag gaps that would block adoption (score below 5). Skip gaps
   that are nice-to-have (score 5-7).
 
-## Review Sections (8 passes, after Step 0 is complete)
+> **STOP.** Before running the 8 DX passes, required outputs, and review report (only after Step 0 investigation is complete), Read `~/.claude/skills/gstack/plan-devex-review/sections/review-sections.md` and execute it
+> in full. Do not work from memory — that section is the source of truth for this step.
 
-**Anti-skip rule:** Never condense, abbreviate, or skip any review pass (1-8) regardless of plan type (strategy, spec, code, infra). Every pass in this skill exists for a reason. "This is a strategy doc so DX passes don't apply" is always wrong — DX gaps are where adoption breaks down. If a pass genuinely has zero findings, say "No issues found" and move on — but you must evaluate it.
+## Section self-check (before you finish)
 
-**Anti-shortcut clause:** The plan file is the OUTPUT of the interactive review, not a substitute for it. Writing every finding into one plan write and calling ExitPlanMode without firing AskUserQuestion is the precise failure mode of the May 2026 transcript bug — the model explored, found issues, and dumped them into a deliverable rather than walking the user through them. If you have ANY non-trivial finding in any review section, the path from finding to ExitPlanMode goes THROUGH AskUserQuestion. Zero findings in every section is the only path to ExitPlanMode that bypasses AskUserQuestion. If you find yourself wanting to write a plan with findings before asking, stop and call AskUserQuestion now — that's the bug, recognize it.
+Confirm you Read the review section the Section index named, and executed all 8 DX passes, the required outputs, and the review report in full. If you produced findings or the review report from memory without Reading `sections/review-sections.md`, stop and Read it now.
-
-## Prior Learnings
-
-Search for relevant learnings from previous sessions:
-
-```bash
-_CROSS_PROJ=$(~/.claude/skills/gstack/bin/gstack-config get cross_project_learnings 2>/dev/null || echo "unset")
-echo "CROSS_PROJECT: $_CROSS_PROJ"
-if [ "$_CROSS_PROJ" = "true" ]; then
-  ~/.claude/skills/gstack/bin/gstack-learnings-search --limit 10 --cross-project 2>/dev/null || true
-else
-  ~/.claude/skills/gstack/bin/gstack-learnings-search --limit 10 2>/dev/null || true
-fi
-```
-
-If `CROSS_PROJECT` is `unset` (first time): Use AskUserQuestion:
-
-> gstack can search learnings from your other projects on this machine to find
-> patterns that might apply here. This stays local (no data leaves your machine).
-> Recommended for solo developers. Skip if you work on multiple client codebases
-> where cross-contamination would be a concern.
-
-Options:
-- A) Enable cross-project learnings (recommended)
-- B) Keep learnings project-scoped only
-
-If A: run `~/.claude/skills/gstack/bin/gstack-config set cross_project_learnings true`
-If B: run `~/.claude/skills/gstack/bin/gstack-config set cross_project_learnings false`
-
-Then re-run the search with the appropriate flag.
-
-If learnings are found, incorporate them into your analysis. When a review finding
-matches a past learning, display:
-
-**"Prior learning applied: [key] (confidence N/10, from [date])"**
-
-This makes the compounding visible. The user should see that gstack is getting
-smarter on their codebase over time.
-
-### DX Trend Check
-
-Before starting review passes, check for prior DX reviews on this project:
-
-```bash
-eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)"
-~/.claude/skills/gstack/bin/gstack-review-read 2>/dev/null | grep plan-devex-review || echo "NO_PRIOR_DX_REVIEWS"
-```
-
-If prior reviews exist, display the trend:
-```
-DX TREND (prior reviews):
-  Dimension        | Prior Score | Notes
-  Getting Started  | 4/10        | from 2026-03-15
-  ...
-```
-
-### Pass 1: Getting Started Experience (Zero Friction)
-
-Rate 0-10: Can a developer go from zero to hello world in under 5 minutes?
-
-**Evidence recall:** Reference the competitive benchmark from 0C (target tier), the
-magical moment from 0D (delivery vehicle), and any Install/Hello World friction
-points from 0F.
-
-Load reference: Read the "## Pass 1" section from `~/.claude/skills/gstack/plan-devex-review/dx-hall-of-fame.md`.
-
-Evaluate:
-- **Installation**: One command? One click? No prerequisites?
-- **First run**: Does the first command produce visible, meaningful output?
-- **Sandbox/Playground**: Can developers try before installing?
-- **Free tier**: No credit card, no sales call, no company email?
-- **Quick start guide**: Copy-paste complete? Shows real output?
-- **Auth/credential bootstrapping**: How many steps between "I want to try" and "it works"?
-- **Magical moment delivery**: Is the vehicle chosen in 0D actually in the plan?
-- **Competitive gap**: How far is the TTHW from the target tier chosen in 0C?
-
-FIX TO 10: Write the ideal getting started sequence. Specify exact commands,
-expected output, and time budget per step. Target: 3 steps or fewer, under the
-time chosen in 0C.
-
-Stripe test: Can a [persona from 0A] go from "never heard of this" to "it worked"
-in one terminal session without leaving the terminal?
-
-**STOP.** AskUserQuestion once per issue. Recommend + WHY. Reference the persona.
-
-### Pass 2: API/CLI/SDK Design (Usable + Useful)
-
-Rate 0-10: Is the interface intuitive, consistent, and complete?
-
-**Evidence recall:** Does the API surface match [persona from 0A]'s mental model?
-A YC founder expects `tool.do(thing)`. A platform engineer expects
-`tool.configure(options).execute(thing)`.
-
-Load reference: Read the "## Pass 2" section from `~/.claude/skills/gstack/plan-devex-review/dx-hall-of-fame.md`.
-
-Evaluate:
-- **Naming**: Guessable without docs? Consistent grammar?
-- **Defaults**: Every parameter has a sensible default? Simplest call gives useful result?
-- **Consistency**: Same patterns across the entire API surface?
-- **Completeness**: 100% coverage or do devs drop to raw HTTP for edge cases?
-- **Discoverability**: Can devs explore from CLI/playground without docs?
-- **Reliability/trust**: Latency, retries, rate limits, idempotency, offline behavior?
-- **Progressive disclosure**: Simple case is production-ready, complexity revealed gradually?
-- **Persona fit**: Does the interface match how [persona] thinks about the problem?
-
-Good API design test: Can a [persona] use this API correctly after seeing one example?
-
-**STOP.** AskUserQuestion once per issue. Recommend + WHY.
-
-### Pass 3: Error Messages & Debugging (Fight Uncertainty)
-
-Rate 0-10: When something goes wrong, does the developer know what happened, why,
-and how to fix it?
-
-**Evidence recall:** Reference any error-related friction points from 0F and confusion
-points from 0G.
-
-Load reference: Read the "## Pass 3" section from `~/.claude/skills/gstack/plan-devex-review/dx-hall-of-fame.md`.
-
-**Trace 3 specific error paths** from the plan or codebase. For each, evaluate against
-the three-tier system from the Hall of Fame:
-- **Tier 1 (Elm):** Conversational, first person, exact location, suggested fix
-- **Tier 2 (Rust):** Error code links to tutorial, primary + secondary labels, help section
-- **Tier 3 (Stripe API):** Structured JSON with type, code, message, param, doc_url
-
-For each error path, show what the developer currently sees vs. what they should see.
-
-Also evaluate:
-- **Permission/sandbox/safety model**: What can go wrong? How clear is the blast radius?
-- **Debug mode**: Verbose output available?
-- **Stack traces**: Useful or internal framework noise?
-
-**STOP.** AskUserQuestion once per issue. Recommend + WHY.
-
-### Pass 4: Documentation & Learning (Findable + Learn by Doing)
-
-Rate 0-10: Can a developer find what they need and learn by doing?
-
-**Evidence recall:** Does the docs architecture match [persona from 0A]'s learning
-style? A YC founder needs copy-paste examples front and center. A platform engineer
-needs architecture docs and API reference.
-
-Load reference: Read the "## Pass 4" section from `~/.claude/skills/gstack/plan-devex-review/dx-hall-of-fame.md`.
-
-Evaluate:
-- **Information architecture**: Find what they need in under 2 minutes?
-- **Progressive disclosure**: Beginners see simple, experts find advanced?
-- **Code examples**: Copy-paste complete? Work as-is? Real context?
-- **Interactive elements**: Playgrounds, sandboxes, "try it" buttons?
-- **Versioning**: Docs match the version dev is using?
-- **Tutorials vs references**: Both exist?
-
-**STOP.** AskUserQuestion once per issue. Recommend + WHY.
-
-### Pass 5: Upgrade & Migration Path (Credible)
-
-Rate 0-10: Can developers upgrade without fear?
-
-Load reference: Read the "## Pass 5" section from `~/.claude/skills/gstack/plan-devex-review/dx-hall-of-fame.md`.
-
-Evaluate:
-- **Backward compatibility**: What breaks? Blast radius limited?
-- **Deprecation warnings**: Advance notice? Actionable? ("use newMethod() instead")
-- **Migration guides**: Step-by-step for every breaking change?
-- **Codemods**: Automated migration scripts?
-- **Versioning strategy**: Semantic versioning? Clear policy?
-
-**STOP.** AskUserQuestion once per issue. Recommend + WHY.
-
-### Pass 6: Developer Environment & Tooling (Valuable + Accessible)
-
-Rate 0-10: Does this integrate into developers' existing workflows?
-
-**Evidence recall:** Does local dev setup work for [persona from 0A]'s typical
-environment?
-
-Load reference: Read the "## Pass 6" section from `~/.claude/skills/gstack/plan-devex-review/dx-hall-of-fame.md`.
-
-Evaluate:
-- **Editor integration**: Language server? Autocomplete? Inline docs?
-- **CI/CD**: Works in GitHub Actions, GitLab CI? Non-interactive mode?
-- **TypeScript support**: Types included? Good IntelliSense?
-- **Testing support**: Easy to mock? Test utilities?
-- **Local development**: Hot reload? Watch mode? Fast feedback?
-- **Cross-platform**: Mac, Linux, Windows? Docker? ARM/x86?
-- **Local env reproducibility**: Works across OS, package managers, containers, proxies?
-- **Observability/testability**: Dry-run mode? Verbose output? Sample apps? Fixtures?
-
-**STOP.** AskUserQuestion once per issue. Recommend + WHY.
-
-### Pass 7: Community & Ecosystem (Findable + Desirable)
-
-Rate 0-10: Is there a community, and does the plan invest in ecosystem health?
-
-Load reference: Read the "## Pass 7" section from `~/.claude/skills/gstack/plan-devex-review/dx-hall-of-fame.md`.
-
-Evaluate:
-- **Open source**: Code open? Permissive license?
-- **Community channels**: Where do devs ask questions? Someone answering?
-- **Examples**: Real-world, runnable? Not just hello world?
-- **Plugin/extension ecosystem**: Can devs extend it?
-- **Contributing guide**: Process clear?
-- **Pricing transparency**: No surprise bills?
-
-**STOP.** AskUserQuestion once per issue. Recommend + WHY.
-
-### Pass 8: DX Measurement & Feedback Loops (Implement + Refine)
-
-Rate 0-10: Does the plan include ways to measure and improve DX over time?
-
-Load reference: Read the "## Pass 8" section from `~/.claude/skills/gstack/plan-devex-review/dx-hall-of-fame.md`.
-
-Evaluate:
-- **TTHW tracking**: Can you measure getting started time? Is it instrumented?
-- **Journey analytics**: Where do devs drop off?
-- **Feedback mechanisms**: Bug reports? NPS? Feedback button?
-- **Friction audits**: Periodic reviews planned?
-- **Boomerang readiness**: Will /devex-review be able to measure reality vs. plan?
-
-**STOP.** AskUserQuestion once per issue. Recommend + WHY.
-
-### Appendix: Claude Code Skill DX Checklist
-
-**Conditional: only run when product type includes "Claude Code skill".**
-
-This is NOT a scored pass. It's a checklist of proven patterns from gstack's own DX.
-
-Load reference: Read the "## Claude Code Skill DX Checklist" section from
-`~/.claude/skills/gstack/plan-devex-review/dx-hall-of-fame.md`.
-
-Check each item. For any unchecked item, explain what's missing and suggest the fix.
-
-**STOP.** AskUserQuestion for any item that requires a design decision.
-
-## Outside Voice — Independent Plan Challenge (optional, recommended)
-
-After all review sections are complete, offer an independent second opinion from a
-different AI system. Two models agreeing on a plan is stronger signal than one model's
-thorough review.
-
-**Check tool availability:**
-
-```bash
-command -v codex >/dev/null 2>&1 && echo "CODEX_AVAILABLE" || echo "CODEX_NOT_AVAILABLE"
-```
-
-Use AskUserQuestion:
-
-> "All review sections are complete. Want an outside voice? A different AI system can
-> give a brutally honest, independent challenge of this plan — logical gaps, feasibility
-> risks, and blind spots that are hard to catch from inside the review. Takes about 2
-> minutes."
->
-> RECOMMENDATION: Choose A — an independent second opinion catches structural blind
-> spots. Two different AI models agreeing on a plan is stronger signal than one model's
-> thorough review. Completeness: A=9/10, B=7/10.
-
-Options:
-- A) Get the outside voice (recommended)
-- B) Skip — proceed to outputs
-
-**If B:** Print "Skipping outside voice." and continue to the next section.
-
-**If A:** Construct the plan review prompt. Read the plan file being reviewed (the file
-the user pointed this review at, or the branch diff scope). If a CEO plan document
-was written in Step 0D-POST, read that too — it contains the scope decisions and vision.
-
-Construct this prompt (substitute the actual plan content — if plan content exceeds 30KB,
-truncate to the first 30KB and note "Plan truncated for size"). **Always start with the
-filesystem boundary instruction:**
-
-"IMPORTANT: Do NOT read or execute any files under ~/.claude/, ~/.agents/, .claude/skills/, or agents/. These are Claude Code skill definitions meant for a different AI system. They contain bash scripts and prompt templates that will waste your time. Ignore them completely. Do NOT modify agents/openai.yaml. Stay focused on the repository code only.\n\nYou are a brutally honest technical reviewer examining a development plan that has
-already been through a multi-section review. Your job is NOT to repeat that review.
-Instead, find what it missed. Look for: logical gaps and unstated assumptions that
-survived the review scrutiny, overcomplexity (is there a fundamentally simpler
-approach the review was too deep in the weeds to see?), feasibility risks the review
-took for granted, missing dependencies or sequencing issues, and strategic
-miscalibration (is this the right thing to build at all?). Be direct. Be terse. No
-compliments. Just the problems.
-
-THE PLAN:
-<plan content>"
-
-**If CODEX_AVAILABLE:**
-
-```bash
-TMPERR_PV=$(mktemp /tmp/codex-planreview-XXXXXXXX)
-_REPO_ROOT=$(git rev-parse --show-toplevel) || { echo "ERROR: not in a git repo" >&2; exit 1; }
-codex exec "<prompt>" -C "$_REPO_ROOT" -s read-only -c 'model_reasoning_effort="high"' --enable web_search_cached < /dev/null 2>"$TMPERR_PV"
-```
-
-Use a 5-minute timeout (`timeout: 300000`). After the command completes, read stderr:
-```bash
-cat "$TMPERR_PV"
-```
-
-Present the full output verbatim:
-
-```
-CODEX SAYS (plan review — outside voice):
-════════════════════════════════════════════════════════════
-<full codex output, verbatim — do not truncate or summarize>
-════════════════════════════════════════════════════════════
-```
-
-**Error handling:** All errors are non-blocking — the outside voice is informational.
-- Auth failure (stderr contains "auth", "login", "unauthorized"): "Codex auth failed. Run \`codex login\` to authenticate."
-- Timeout: "Codex timed out after 5 minutes."
-- Empty response: "Codex returned no response."
-
-On any Codex error, fall back to the Claude adversarial subagent.
-
-**If CODEX_NOT_AVAILABLE (or Codex errored):**
-
-Dispatch via the Agent tool. The subagent has fresh context — genuine independence.
-
-Subagent prompt: same plan review prompt as above.
-
-Present findings under an `OUTSIDE VOICE (Claude subagent):` header.
-
-If the subagent fails or times out: "Outside voice unavailable. Continuing to outputs."
-
-**Cross-model tension:**
-
-After presenting the outside voice findings, note any points where the outside voice
-disagrees with the review findings from earlier sections. Flag these as:
-
-```
-CROSS-MODEL TENSION:
-  [Topic]: Review said X. Outside voice says Y. [Present both perspectives neutrally.
-  State what context you might be missing that would change the answer.]
-```
-
-**User Sovereignty:** Do NOT auto-incorporate outside voice recommendations into the plan.
-Present each tension point to the user. The user decides. Cross-model agreement is a
-strong signal — present it as such — but it is NOT permission to act. You may state
-which argument you find more compelling, but you MUST NOT apply the change without
-explicit user approval.
-
-For each substantive tension point, use AskUserQuestion:
-
-> "Cross-model disagreement on [topic]. The review found [X] but the outside voice
-> argues [Y]. [One sentence on what context you might be missing.]"
->
-> RECOMMENDATION: Choose [A or B] because [one-line reason explaining which argument
-> is more compelling and why]. Completeness: A=X/10, B=Y/10.
-
-Options:
-- A) Accept the outside voice's recommendation (I'll apply this change)
-- B) Keep the current approach (reject the outside voice)
-- C) Investigate further before deciding
-- D) Add to TODOS.md for later
-
-Wait for the user's response. Do NOT default to accepting because you agree with the
-outside voice. If the user chooses B, the current approach stands — do not re-argue.
-
-If no tension points exist, note: "No cross-model tension — both reviewers agree."
-
-**Persist the result:**
-```bash
-~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"codex-plan-review","timestamp":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'","status":"STATUS","source":"SOURCE","commit":"'"$(git rev-parse --short HEAD)"'"}'
-```
-
-Substitute: STATUS = "clean" if no findings, "issues_found" if findings exist.
-SOURCE = "codex" if Codex ran, "claude" if subagent ran.
-
-**Cleanup:** Run `rm -f "$TMPERR_PV"` after processing (if Codex was used).
-
----
-
-When constructing the outside voice prompt, include the Developer Persona from Step 0A
-and the Competitive Benchmark from Step 0C. The outside voice should critique the plan
-in the context of who is using it and what they're competing against.
-
-## CRITICAL RULE — How to ask questions
-
-Follow the AskUserQuestion format from the Preamble above. Additional rules for
-DX reviews:
-
-* **One issue = one AskUserQuestion call.** Never combine multiple issues.
-* **Ground every question in evidence.** Reference the persona, competitive benchmark,
-  empathy narrative, or friction trace. Never ask a question in the abstract.
-* **Frame pain from the persona's perspective.** Not "developers would be frustrated"
-  but "[persona from 0A] would hit this at minute [N] of their getting-started flow
-  and [specific consequence: abandon, file an issue, hack a workaround]."
-* Present 2-3 options. For each: effort to fix, impact on developer adoption.
-* **Map to DX First Principles above.** One sentence connecting your recommendation
-  to a specific principle (e.g., "This violates 'zero friction at T0' because
-  [persona] needs 3 extra config steps before their first API call").
-* **Zero findings:** if a section has zero findings, state "No issues, moving on"
-  and proceed. Otherwise, use AskUserQuestion for each gap — a gap with an
-  "obvious fix" is still a gap and still needs user approval before any change
-  lands in the plan.
-* Assume the user hasn't looked at this window in 20 minutes. Re-ground every question.
-
-## Required Outputs
-
-### Developer Persona Card
-The persona card from Step 0A. This goes at the top of the plan's DX section.
-
-### Developer Empathy Narrative
-The first-person narrative from Step 0B, updated with user corrections.
-
-### Competitive DX Benchmark
-The benchmark table from Step 0C, updated with the product's post-review scores.
-
-### Magical Moment Specification
-The chosen delivery vehicle from Step 0D with implementation requirements.
-
-### Developer Journey Map
-The journey map from Step 0F, updated with all friction point resolutions.
-
-### First-Time Developer Confusion Report
-The roleplay report from Step 0G, annotated with which items were addressed.
-
-### "NOT in scope" section
-DX improvements considered and explicitly deferred, with one-line rationale each.
-
-### "What already exists" section
-Existing docs, examples, error handling, and DX patterns that the plan should reuse.
-
-### TODOS.md updates
-After all review passes are complete, present each potential TODO as its own individual
-AskUserQuestion. Never batch. For DX debt: missing error messages, unspecified upgrade
-paths, documentation gaps, missing SDK languages. Each TODO gets:
-* **What:** One-line description
-* **Why:** The concrete developer pain it causes
-* **Pros:** What you gain (adoption, retention, satisfaction)
-* **Cons:** Cost, complexity, or risks
-* **Context:** Enough detail for someone to pick this up in 3 months
-* **Depends on / blocked by:** Prerequisites
-
-Options: **A)** Add to TODOS.md **B)** Skip **C)** Build it now
-
-### DX Scorecard
-
-```
-+====================================================================+
-|              DX PLAN REVIEW — SCORECARD                             |
-+====================================================================+
-| Dimension            | Score  | Prior  | Trend  |
-|----------------------|--------|--------|--------|
-| Getting Started      | __/10  | __/10  | __ ↑↓  |
-| API/CLI/SDK          | __/10  | __/10  | __ ↑↓  |
-| Error Messages       | __/10  | __/10  | __ ↑↓  |
-| Documentation        | __/10  | __/10  | __ ↑↓  |
-| Upgrade Path         | __/10  | __/10  | __ ↑↓  |
-| Dev Environment      | __/10  | __/10  | __ ↑↓  |
-| Community            | __/10  | __/10  | __ ↑↓  |
-| DX Measurement       | __/10  | __/10  | __ ↑↓  |
-+--------------------------------------------------------------------+
-| TTHW                 | __ min | __ min | __ ↑↓  |
-| Competitive Rank     | [Champion/Competitive/Needs Work/Red Flag]   |
-| Magical Moment       | [designed/missing] via [delivery vehicle]    |
-| Product Type         | [type]                                      |
-| Mode                 | [EXPANSION/POLISH/TRIAGE]                    |
-| Overall DX           | __/10  | __/10  | __ ↑↓  |
-+====================================================================+
-| DX PRINCIPLE COVERAGE                                               |
-| Zero Friction      | [covered/gap]                                  |
-| Learn by Doing     | [covered/gap]                                  |
-| Fight Uncertainty  | [covered/gap]                                  |
-| Opinionated + Escape Hatches | [covered/gap]                       |
-| Code in Context    | [covered/gap]                                  |
-| Magical Moments    | [covered/gap]                                  |
-+====================================================================+
-```
-
-If all passes 8+: "DX plan is solid. Developers will have a good experience."
-If any below 6: Flag as critical DX debt with specific impact on adoption.
-If TTHW > 10 min: Flag as blocking issue.
-
-### DX Implementation Checklist
-
-```
-DX IMPLEMENTATION CHECKLIST
-============================
-[ ] Time to hello world < [target from 0C]
-[ ] Installation is one command
-[ ] First run produces meaningful output
-[ ] Magical moment delivered via [vehicle from 0D]
-[ ] Every error message has: problem + cause + fix + docs link
-[ ] API/CLI naming is guessable without docs
-[ ] Every parameter has a sensible default
-[ ] Docs have copy-paste examples that actually work
-[ ] Examples show real use cases, not just hello world
-[ ] Upgrade path documented with migration guide
-[ ] Breaking changes have deprecation warnings + codemods
-[ ] TypeScript types included (if applicable)
-[ ] Works in CI/CD without special configuration
-[ ] Free tier available, no credit card required
-[ ] Changelog exists and is maintained
-[ ] Search works in documentation
-[ ] Community channel exists and is monitored
-```
-
-## Implementation Tasks
-
-Before closing this review, synthesize the findings above into a flat list of
-build-actionable tasks. Each task derives from a specific finding — no padding.
-Emit the markdown section AND write a JSONL artifact that `/autoplan` can
-aggregate across phases.
-
-### Markdown section (always emit)
-
-```markdown
-## Implementation Tasks
-Synthesized from this review's findings. Each task derives from a specific
-finding above. Run with Claude Code or Codex; checkbox as you ship.
-
-- [ ] **T1 (P1, human: ~2h / CC: ~15min)** — <component> — <imperative title>
-  - Surfaced by: <section name> — <specific finding text or line reference>
-  - Files: <paths to touch>
-  - Verify: <test command or manual check>
-- [ ] **T2 (P2, human: ~30min / CC: ~5min)** — ...
-```
-
-Rules:
-- P1 blocks ship; P2 should land same branch; P3 is a follow-up TODO.
-- If a finding produced no actionable task, do not invent one.
-- If a section had zero findings, emit `_No new tasks from <section>._`
-- Effort uses the AI-compression table from CLAUDE.md.
-
-### JSONL artifact (always write, even if zero tasks)
-
-`/autoplan` reads this file to aggregate across phases. Build each line with
-`jq -nc` so titles and source findings containing quotes, newlines, or
-backslashes serialize cleanly — never use hand-rolled `echo` / `printf`.
-
-```bash
-eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)"
-TASKS_DIR="${HOME}/.gstack/projects/${SLUG:-unknown}"
-mkdir -p "$TASKS_DIR"
-TASKS_FILE="$TASKS_DIR/tasks-devex-review-$(date +%Y%m%d-%H%M%S).jsonl"
-COMMIT=$(git rev-parse HEAD 2>/dev/null || echo unknown)
-BRANCH=$(git branch --show-current 2>/dev/null || echo unknown)
-RUN_ID="$(date -u +%Y%m%dT%H%M%SZ)-$$"
-
-# Repeat ONE jq invocation per task identified during this review.
-# Substitute the placeholders inline with shell variables you set per task:
-#   TASK_ID (T1, T2, ...), PRIORITY (P1/P2/P3), COMPONENT, TITLE,
-#   SOURCE_FINDING, EFFORT_HUMAN, EFFORT_CC, FILES_JSON (a JSON array literal
-#   like '["browse/src/sanitize.ts","browse/src/server.ts"]').
-jq -nc \
-  --arg phase 'devex-review' \
-  --arg run_id "$RUN_ID" \
-  --arg branch "$BRANCH" \
-  --arg commit "$COMMIT" \
-  --arg id "$TASK_ID" \
-  --arg priority "$PRIORITY" \
-  --arg component "$COMPONENT" \
-  --arg effort_human "$EFFORT_HUMAN" \
-  --arg effort_cc "$EFFORT_CC" \
-  --arg title "$TITLE" \
-  --arg source_finding "$SOURCE_FINDING" \
-  --argjson files "$FILES_JSON" \
-  '{phase:$phase, run_id:$run_id, branch:$branch, commit:$commit, id:$id, priority:$priority, component:$component, files:$files, effort_human:$effort_human, effort_cc:$effort_cc, title:$title, source_finding:$source_finding}' \
-  >> "$TASKS_FILE"
-```
-
-If `jq` is not installed, fall back to skipping the JSONL write and warn
-the user to install jq for autoplan aggregation. Never hand-roll JSONL.
-
-If zero tasks were identified in this review, still touch the JSONL file
-(`: > "$TASKS_FILE"`) so the aggregator sees that the phase produced output
-this run (an empty file means "ran, no findings" — distinct from "didn't run").
-
-
-### Unresolved Decisions
-If any AskUserQuestion goes unanswered, note here. Never silently default.
-
-## Review Readiness Dashboard
-
-After completing the review, read the review log and config to display the dashboard.
-
-```bash
-~/.claude/skills/gstack/bin/gstack-review-read
-```
-
-Parse the output. Find the most recent entry for each skill (plan-ceo-review, plan-eng-review, review, plan-design-review, design-review-lite, adversarial-review, codex-review, codex-plan-review). Ignore entries with timestamps older than 7 days. For the Eng Review row, show whichever is more recent between `review` (diff-scoped pre-landing review) and `plan-eng-review` (plan-stage architecture review). Append "(DIFF)" or "(PLAN)" to the status to distinguish. For the Adversarial row, show whichever is more recent between `adversarial-review` (new auto-scaled) and `codex-review` (legacy). For Design Review, show whichever is more recent between `plan-design-review` (full visual audit) and `design-review-lite` (code-level check). Append "(FULL)" or "(LITE)" to the status to distinguish. For the Outside Voice row, show the most recent `codex-plan-review` entry — this captures outside voices from both /plan-ceo-review and /plan-eng-review.
-
-**Source attribution:** If the most recent entry for a skill has a \`"via"\` field, append it to the status label in parentheses. Examples: `plan-eng-review` with `via:"autoplan"` shows as "CLEAR (PLAN via /autoplan)". `review` with `via:"ship"` shows as "CLEAR (DIFF via /ship)". Entries without a `via` field show as "CLEAR (PLAN)" or "CLEAR (DIFF)" as before.
-
-Note: `autoplan-voices` and `design-outside-voices` entries are audit-trail-only (forensic data for cross-model consensus analysis). They do not appear in the dashboard and are not checked by any consumer.
-
-Display:
-
-```
-+====================================================================+
-|                    REVIEW READINESS DASHBOARD                       |
-+====================================================================+
-| Review          | Runs | Last Run            | Status    | Required |
-|-----------------|------|---------------------|-----------|----------|
-| Eng Review      |  1   | 2026-03-16 15:00    | CLEAR     | YES      |
-| CEO Review      |  0   | —                   | —         | no       |
-| Design Review   |  0   | —                   | —         | no       |
-| Adversarial     |  0   | —                   | —         | no       |
-| Outside Voice   |  0   | —                   | —         | no       |
-+--------------------------------------------------------------------+
-| VERDICT: CLEARED — Eng Review passed                                |
-+====================================================================+
-```
-
-**Review tiers:**
-- **Eng Review (required by default):** The only review that gates shipping. Covers architecture, code quality, tests, performance. Can be disabled globally with \`gstack-config set skip_eng_review true\` (the "don't bother me" setting).
-- **CEO Review (optional):** Use your judgment. Recommend it for big product/business changes, new user-facing features, or scope decisions. Skip for bug fixes, refactors, infra, and cleanup.
-- **Design Review (optional):** Use your judgment. Recommend it for UI/UX changes. Skip for backend-only, infra, or prompt-only changes.
-- **Adversarial Review (automatic):** Always-on for every review. Every diff gets both Claude adversarial subagent and Codex adversarial challenge. Large diffs (200+ lines) additionally get Codex structured review with P1 gate. No configuration needed.
-- **Outside Voice (optional):** Independent plan review from a different AI model. Offered after all review sections complete in /plan-ceo-review and /plan-eng-review. Falls back to Claude subagent if Codex is unavailable. Never gates shipping.
-
-**Verdict logic:**
-- **CLEARED**: Eng Review has >= 1 entry within 7 days from either \`review\` or \`plan-eng-review\` with status "clean" (or \`skip_eng_review\` is \`true\`)
-- **NOT CLEARED**: Eng Review missing, stale (>7 days), or has open issues
-- CEO, Design, and Codex reviews are shown for context but never block shipping
-- If \`skip_eng_review\` config is \`true\`, Eng Review shows "SKIPPED (global)" and verdict is CLEARED
-
-**Staleness detection:** After displaying the dashboard, check if any existing reviews may be stale:
-- Parse the \`---HEAD---\` section from the bash output to get the current HEAD commit hash
-- For each review entry that has a \`commit\` field: compare it against the current HEAD. If different, count elapsed commits: \`git rev-list --count STORED_COMMIT..HEAD\`. Display: "Note: {skill} review from {date} may be stale — {N} commits since review"
-- For entries without a \`commit\` field (legacy entries): display "Note: {skill} review from {date} has no commit tracking — consider re-running for accurate staleness detection"
-- If all reviews match the current HEAD, do not display any staleness notes
-
-## Plan File Review Report
-
-After displaying the Review Readiness Dashboard in conversation output, also update the
-**plan file** itself so review status is visible to anyone reading the plan.
-
-### Detect the plan file
-
-1. Check if there is an active plan file in this conversation (the host provides plan file
-   paths in system messages — look for plan file references in the conversation context).
-2. If not found, skip this section silently — not every review runs in plan mode.
-
-### Generate the report
-
-Read the review log output you already have from the Review Readiness Dashboard step above.
-Parse each JSONL entry. Each skill logs different fields:
-
-- **plan-ceo-review**: \`status\`, \`unresolved\`, \`critical_gaps\`, \`mode\`, \`scope_proposed\`, \`scope_accepted\`, \`scope_deferred\`, \`commit\`
-  → Findings: "{scope_proposed} proposals, {scope_accepted} accepted, {scope_deferred} deferred"
-  → If scope fields are 0 or missing (HOLD/REDUCTION mode): "mode: {mode}, {critical_gaps} critical gaps"
-- **plan-eng-review**: \`status\`, \`unresolved\`, \`critical_gaps\`, \`issues_found\`, \`mode\`, \`commit\`
-  → Findings: "{issues_found} issues, {critical_gaps} critical gaps"
-- **plan-design-review**: \`status\`, \`initial_score\`, \`overall_score\`, \`unresolved\`, \`decisions_made\`, \`commit\`
-  → Findings: "score: {initial_score}/10 → {overall_score}/10, {decisions_made} decisions"
-- **plan-devex-review**: \`status\`, \`initial_score\`, \`overall_score\`, \`product_type\`, \`tthw_current\`, \`tthw_target\`, \`mode\`, \`persona\`, \`competitive_tier\`, \`unresolved\`, \`commit\`
-  → Findings: "score: {initial_score}/10 → {overall_score}/10, TTHW: {tthw_current} → {tthw_target}"
-- **devex-review**: \`status\`, \`overall_score\`, \`product_type\`, \`tthw_measured\`, \`dimensions_tested\`, \`dimensions_inferred\`, \`boomerang\`, \`commit\`
-  → Findings: "score: {overall_score}/10, TTHW: {tthw_measured}, {dimensions_tested} tested/{dimensions_inferred} inferred"
-- **codex-review**: \`status\`, \`gate\`, \`findings\`, \`findings_fixed\`
-  → Findings: "{findings} findings, {findings_fixed}/{findings} fixed"
-
-All fields needed for the Findings column are now present in the JSONL entries.
-For the review you just completed, you may use richer details from your own Completion
-Summary. For prior reviews, use the JSONL fields directly — they contain all required data.
-
-Produce this markdown table:
-
-\`\`\`markdown
-## GSTACK REVIEW REPORT
-
-| Review | Trigger | Why | Runs | Status | Findings |
-|--------|---------|-----|------|--------|----------|
-| CEO Review | \`/plan-ceo-review\` | Scope & strategy | {runs} | {status} | {findings} |
-| Codex Review | \`/codex review\` | Independent 2nd opinion | {runs} | {status} | {findings} |
-| Eng Review | \`/plan-eng-review\` | Architecture & tests (required) | {runs} | {status} | {findings} |
-| Design Review | \`/plan-design-review\` | UI/UX gaps | {runs} | {status} | {findings} |
-| DX Review | \`/plan-devex-review\` | Developer experience gaps | {runs} | {status} | {findings} |
-\`\`\`
-
-Below the table, add these lines (omit any that are empty/not applicable):
-
-- **CODEX:** (only if codex-review ran) — one-line summary of codex fixes
-- **CROSS-MODEL:** (only if both Claude and Codex reviews exist) — overlap analysis
-- **UNRESOLVED:** total unresolved decisions across all reviews
-- **VERDICT:** list reviews that are CLEAR (e.g., "CEO + ENG CLEARED — ready to implement").
-  If Eng Review is not CLEAR and not skipped globally, append "eng review required".
-
-### Write to the plan file
-
-**PLAN MODE EXCEPTION — ALWAYS RUN:** This writes to the plan file, which is the one
-file you are allowed to edit in plan mode. The plan file review report is part of the
-plan's living status.
-
-The report must always be the LAST section of the plan file — never mid-file.
-Use a single delete-then-append flow:
-
-1. Read the plan file (Read tool) to see its full current content. Search the read
-   output for a \`## GSTACK REVIEW REPORT\` heading anywhere in the file.
-2. If found, use the Edit tool to DELETE the entire existing section. Match from
-   \`## GSTACK REVIEW REPORT\` through either the next \`## \` heading or end of
-   file, whichever comes first. Replace with the empty string. This applies
-   regardless of where the section currently lives — mid-file deletion is
-   intentional, not a special case. If the Edit fails (e.g., concurrent edit
-   changed the content), re-read the plan file and retry once.
-3. After the delete (or skipped, if no section existed), append the new
-   \`## GSTACK REVIEW REPORT\` section at the END of the file. Use the Edit
-   tool to match the file's current last paragraph and add the section after it,
-   or use Write to re-emit the whole file with the section at the end.
-4. Verify with the Read tool that \`## GSTACK REVIEW REPORT\` is the last
-   \`## \` heading in the file before continuing. If it isn't, repeat steps
-   2-3 once.
-
-Do NOT replace the section in place. The "replace mid-file" path is what allowed
-prior versions to leave the report mid-file when an older report already lived
-there — the user then sees a plan whose review report is not at the bottom and
-(correctly) rejects it.
-
-## Capture Learnings
-
-If you discovered a non-obvious pattern, pitfall, or architectural insight during
-this session, log it for future sessions:
-
-```bash
-~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"plan-devex-review","type":"TYPE","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"SOURCE","files":["path/to/relevant/file"]}'
-```
-
-**Types:** `pattern` (reusable approach), `pitfall` (what NOT to do), `preference`
-(user stated), `architecture` (structural decision), `tool` (library/framework insight),
-`operational` (project environment/CLI/workflow knowledge).
-
-**Sources:** `observed` (you found this in the code), `user-stated` (user told you),
-`inferred` (AI deduction), `cross-model` (both Claude and Codex agree).
-
-**Confidence:** 1-10. Be honest. An observed pattern you verified in the code is 8-9.
-An inference you're not sure about is 4-5. A user preference they explicitly stated is 10.
-
-**files:** Include the specific file paths this learning references. This enables
-staleness detection: if those files are later deleted, the learning can be flagged.
-
-**Only log genuine discoveries.** Don't log obvious things. Don't log things the user
-already knows. A good test: would this insight save time in a future session? If yes, log it.
-
-
-
-## Brain Calibration Write-Back (Phase 2 / gated)
-
-When the skill makes a typed prediction worth tracking (scope decision,
-TTHW target, architectural bet, wedge commitment), it MAY write a
-`kind=bet` take to the brain so a calibration profile builds over time.
-
-**Gated on two things:**
-1. Brain trust policy for the active endpoint is `personal` (check via
-   `~/.claude/skills/gstack/bin/gstack-config get brain_trust_policy@<endpoint-hash>`).
-   Shared brains skip write-back to avoid polluting team calibration.
-2. Feature flag `BRAIN_CALIBRATION_WRITEBACK` is set (today: false; flips
-   to true when upstream gbrain v0.42+ ships `takes_add` MCP op).
-
-When both gates pass, the write-back path uses `mcp__gbrain__takes_add`
-to record a take with weight 0.6 (per SKILL_CALIBRATION_WEIGHTS).
-If the MCP op is unavailable, fall back to `mcp__gbrain__put_page` with
-a gstack:takes fence block (documented but uglier path).
-
-Mandatory take frontmatter shape:
-```yaml
-kind: bet
-holder: <user identity from whoami>
-claim: <one-line prediction the skill is making>
-weight: 0.6
-since_date: <today's date>
-expected_resolution: <date in 1-3 months depending on skill>
-source_skill: plan-devex-review
-```
-
-After write, invalidate the affected digests so the next preflight reflects
-the new state:
-
-```bash
-eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true
-  ~/.claude/skills/gstack/bin/gstack-brain-cache invalidate developer-persona --project "$SLUG" 2>/dev/null || true
-```
-
-
-## Brain Cache Background Refresh
-
-After the skill's work completes (and telemetry has logged), kick a
-background refresh of any cache digest that's getting close to its TTL.
-This is non-blocking — the user doesn't wait. Next invocation benefits
-from the warm cache.
-
-```bash
-eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true
-(~/.claude/skills/gstack/bin/gstack-brain-cache refresh --project "$SLUG" 2>/dev/null &) || true
-```
-
-
-## Next Steps — Review Chaining
-
-After displaying the Review Readiness Dashboard, recommend next reviews:
-
-**Recommend /plan-eng-review if eng review is not skipped globally** — DX issues often
-have architectural implications. If this DX review found API design problems, error
-handling gaps, or CLI ergonomics issues, eng review should validate the fixes.
-
-**Suggest /plan-design-review if user-facing UI exists** — DX review focuses on
-developer-facing surfaces; design review covers end-user-facing UI.
-
-**Recommend /devex-review after implementation** — the boomerang. Plan said TTHW would
-be [target from 0C]. Did reality match? Run /devex-review on the live product to find
-out. This is where the competitive benchmark pays off: you have a concrete target to
-measure against.
-
-Use AskUserQuestion with applicable options:
-- **A)** Run /plan-eng-review next (required gate)
-- **B)** Run /plan-design-review (only if UI scope detected)
-- **C)** Ready to implement, run /devex-review after shipping
-- **D)** Skip, I'll handle next steps manually
-
-## Mode Quick Reference
-```
-             | DX EXPANSION     | DX POLISH          | DX TRIAGE
-Scope        | Push UP (opt-in) | Maintain           | Critical only
-Posture      | Enthusiastic     | Rigorous           | Surgical
-Competitive  | Full benchmark   | Full benchmark     | Skip
-Magical      | Full design      | Verify exists      | Skip
-Journey      | All stages +     | All stages         | Install + Hello
-             | best-in-class    |                    | World only
-Passes       | All 8, expanded  | All 8, standard    | Pass 1 + 3 only
-Outside voice| Recommended      | Recommended        | Skip
-```
-
-## Formatting Rules
-
-* NUMBER issues (1, 2, 3...) and LETTERS for options (A, B, C...).
-* Label with NUMBER + LETTER (e.g., "3A", "3B").
-* One sentence max per option.
-* After each pass, pause and wait for feedback before moving on.
-* Rate before and after each pass for scannability.
 
 ## EXIT PLAN MODE GATE (BLOCKING)
 

plan-devex-review/SKILL.md.tmpl

@@ -138,6 +138,11 @@ Note the product type; it influences which persona options are offered in Step 0
 
 {{BRAIN_PREFLIGHT}}
 
+---
+{{SECTION_INDEX:plan-devex-review}}
+---
+
+
 ## Step 0: DX Investigation (before scoring)
 
 The core principle: **gather evidence and force decisions BEFORE scoring, not during
@@ -447,395 +452,10 @@ Pattern:
 - **DX TRIAGE:** Only flag gaps that would block adoption (score below 5). Skip gaps
   that are nice-to-have (score 5-7).
 
-## Review Sections (8 passes, after Step 0 is complete)
+{{SECTION:review-sections}}
 
-**Anti-skip rule:** Never condense, abbreviate, or skip any review pass (1-8) regardless of plan type (strategy, spec, code, infra). Every pass in this skill exists for a reason. "This is a strategy doc so DX passes don't apply" is always wrong — DX gaps are where adoption breaks down. If a pass genuinely has zero findings, say "No issues found" and move on — but you must evaluate it.
+## Section self-check (before you finish)
 
-{{ANTI_SHORTCUT_CLAUSE}}
+Confirm you Read the review section the Section index named, and executed all 8 DX passes, the required outputs, and the review report in full. If you produced findings or the review report from memory without Reading `sections/review-sections.md`, stop and Read it now.
-
-{{LEARNINGS_SEARCH}}
-
-### DX Trend Check
-
-Before starting review passes, check for prior DX reviews on this project:
-
-```bash
-eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)"
-~/.claude/skills/gstack/bin/gstack-review-read 2>/dev/null | grep plan-devex-review || echo "NO_PRIOR_DX_REVIEWS"
-```
-
-If prior reviews exist, display the trend:
-```
-DX TREND (prior reviews):
-  Dimension        | Prior Score | Notes
-  Getting Started  | 4/10        | from 2026-03-15
-  ...
-```
-
-### Pass 1: Getting Started Experience (Zero Friction)
-
-Rate 0-10: Can a developer go from zero to hello world in under 5 minutes?
-
-**Evidence recall:** Reference the competitive benchmark from 0C (target tier), the
-magical moment from 0D (delivery vehicle), and any Install/Hello World friction
-points from 0F.
-
-Load reference: Read the "## Pass 1" section from `~/.claude/skills/gstack/plan-devex-review/dx-hall-of-fame.md`.
-
-Evaluate:
-- **Installation**: One command? One click? No prerequisites?
-- **First run**: Does the first command produce visible, meaningful output?
-- **Sandbox/Playground**: Can developers try before installing?
-- **Free tier**: No credit card, no sales call, no company email?
-- **Quick start guide**: Copy-paste complete? Shows real output?
-- **Auth/credential bootstrapping**: How many steps between "I want to try" and "it works"?
-- **Magical moment delivery**: Is the vehicle chosen in 0D actually in the plan?
-- **Competitive gap**: How far is the TTHW from the target tier chosen in 0C?
-
-FIX TO 10: Write the ideal getting started sequence. Specify exact commands,
-expected output, and time budget per step. Target: 3 steps or fewer, under the
-time chosen in 0C.
-
-Stripe test: Can a [persona from 0A] go from "never heard of this" to "it worked"
-in one terminal session without leaving the terminal?
-
-**STOP.** AskUserQuestion once per issue. Recommend + WHY. Reference the persona.
-
-### Pass 2: API/CLI/SDK Design (Usable + Useful)
-
-Rate 0-10: Is the interface intuitive, consistent, and complete?
-
-**Evidence recall:** Does the API surface match [persona from 0A]'s mental model?
-A YC founder expects `tool.do(thing)`. A platform engineer expects
-`tool.configure(options).execute(thing)`.
-
-Load reference: Read the "## Pass 2" section from `~/.claude/skills/gstack/plan-devex-review/dx-hall-of-fame.md`.
-
-Evaluate:
-- **Naming**: Guessable without docs? Consistent grammar?
-- **Defaults**: Every parameter has a sensible default? Simplest call gives useful result?
-- **Consistency**: Same patterns across the entire API surface?
-- **Completeness**: 100% coverage or do devs drop to raw HTTP for edge cases?
-- **Discoverability**: Can devs explore from CLI/playground without docs?
-- **Reliability/trust**: Latency, retries, rate limits, idempotency, offline behavior?
-- **Progressive disclosure**: Simple case is production-ready, complexity revealed gradually?
-- **Persona fit**: Does the interface match how [persona] thinks about the problem?
-
-Good API design test: Can a [persona] use this API correctly after seeing one example?
-
-**STOP.** AskUserQuestion once per issue. Recommend + WHY.
-
-### Pass 3: Error Messages & Debugging (Fight Uncertainty)
-
-Rate 0-10: When something goes wrong, does the developer know what happened, why,
-and how to fix it?
-
-**Evidence recall:** Reference any error-related friction points from 0F and confusion
-points from 0G.
-
-Load reference: Read the "## Pass 3" section from `~/.claude/skills/gstack/plan-devex-review/dx-hall-of-fame.md`.
-
-**Trace 3 specific error paths** from the plan or codebase. For each, evaluate against
-the three-tier system from the Hall of Fame:
-- **Tier 1 (Elm):** Conversational, first person, exact location, suggested fix
-- **Tier 2 (Rust):** Error code links to tutorial, primary + secondary labels, help section
-- **Tier 3 (Stripe API):** Structured JSON with type, code, message, param, doc_url
-
-For each error path, show what the developer currently sees vs. what they should see.
-
-Also evaluate:
-- **Permission/sandbox/safety model**: What can go wrong? How clear is the blast radius?
-- **Debug mode**: Verbose output available?
-- **Stack traces**: Useful or internal framework noise?
-
-**STOP.** AskUserQuestion once per issue. Recommend + WHY.
-
-### Pass 4: Documentation & Learning (Findable + Learn by Doing)
-
-Rate 0-10: Can a developer find what they need and learn by doing?
-
-**Evidence recall:** Does the docs architecture match [persona from 0A]'s learning
-style? A YC founder needs copy-paste examples front and center. A platform engineer
-needs architecture docs and API reference.
-
-Load reference: Read the "## Pass 4" section from `~/.claude/skills/gstack/plan-devex-review/dx-hall-of-fame.md`.
-
-Evaluate:
-- **Information architecture**: Find what they need in under 2 minutes?
-- **Progressive disclosure**: Beginners see simple, experts find advanced?
-- **Code examples**: Copy-paste complete? Work as-is? Real context?
-- **Interactive elements**: Playgrounds, sandboxes, "try it" buttons?
-- **Versioning**: Docs match the version dev is using?
-- **Tutorials vs references**: Both exist?
-
-**STOP.** AskUserQuestion once per issue. Recommend + WHY.
-
-### Pass 5: Upgrade & Migration Path (Credible)
-
-Rate 0-10: Can developers upgrade without fear?
-
-Load reference: Read the "## Pass 5" section from `~/.claude/skills/gstack/plan-devex-review/dx-hall-of-fame.md`.
-
-Evaluate:
-- **Backward compatibility**: What breaks? Blast radius limited?
-- **Deprecation warnings**: Advance notice? Actionable? ("use newMethod() instead")
-- **Migration guides**: Step-by-step for every breaking change?
-- **Codemods**: Automated migration scripts?
-- **Versioning strategy**: Semantic versioning? Clear policy?
-
-**STOP.** AskUserQuestion once per issue. Recommend + WHY.
-
-### Pass 6: Developer Environment & Tooling (Valuable + Accessible)
-
-Rate 0-10: Does this integrate into developers' existing workflows?
-
-**Evidence recall:** Does local dev setup work for [persona from 0A]'s typical
-environment?
-
-Load reference: Read the "## Pass 6" section from `~/.claude/skills/gstack/plan-devex-review/dx-hall-of-fame.md`.
-
-Evaluate:
-- **Editor integration**: Language server? Autocomplete? Inline docs?
-- **CI/CD**: Works in GitHub Actions, GitLab CI? Non-interactive mode?
-- **TypeScript support**: Types included? Good IntelliSense?
-- **Testing support**: Easy to mock? Test utilities?
-- **Local development**: Hot reload? Watch mode? Fast feedback?
-- **Cross-platform**: Mac, Linux, Windows? Docker? ARM/x86?
-- **Local env reproducibility**: Works across OS, package managers, containers, proxies?
-- **Observability/testability**: Dry-run mode? Verbose output? Sample apps? Fixtures?
-
-**STOP.** AskUserQuestion once per issue. Recommend + WHY.
-
-### Pass 7: Community & Ecosystem (Findable + Desirable)
-
-Rate 0-10: Is there a community, and does the plan invest in ecosystem health?
-
-Load reference: Read the "## Pass 7" section from `~/.claude/skills/gstack/plan-devex-review/dx-hall-of-fame.md`.
-
-Evaluate:
-- **Open source**: Code open? Permissive license?
-- **Community channels**: Where do devs ask questions? Someone answering?
-- **Examples**: Real-world, runnable? Not just hello world?
-- **Plugin/extension ecosystem**: Can devs extend it?
-- **Contributing guide**: Process clear?
-- **Pricing transparency**: No surprise bills?
-
-**STOP.** AskUserQuestion once per issue. Recommend + WHY.
-
-### Pass 8: DX Measurement & Feedback Loops (Implement + Refine)
-
-Rate 0-10: Does the plan include ways to measure and improve DX over time?
-
-Load reference: Read the "## Pass 8" section from `~/.claude/skills/gstack/plan-devex-review/dx-hall-of-fame.md`.
-
-Evaluate:
-- **TTHW tracking**: Can you measure getting started time? Is it instrumented?
-- **Journey analytics**: Where do devs drop off?
-- **Feedback mechanisms**: Bug reports? NPS? Feedback button?
-- **Friction audits**: Periodic reviews planned?
-- **Boomerang readiness**: Will /devex-review be able to measure reality vs. plan?
-
-**STOP.** AskUserQuestion once per issue. Recommend + WHY.
-
-### Appendix: Claude Code Skill DX Checklist
-
-**Conditional: only run when product type includes "Claude Code skill".**
-
-This is NOT a scored pass. It's a checklist of proven patterns from gstack's own DX.
-
-Load reference: Read the "## Claude Code Skill DX Checklist" section from
-`~/.claude/skills/gstack/plan-devex-review/dx-hall-of-fame.md`.
-
-Check each item. For any unchecked item, explain what's missing and suggest the fix.
-
-**STOP.** AskUserQuestion for any item that requires a design decision.
-
-{{CODEX_PLAN_REVIEW}}
-
-When constructing the outside voice prompt, include the Developer Persona from Step 0A
-and the Competitive Benchmark from Step 0C. The outside voice should critique the plan
-in the context of who is using it and what they're competing against.
-
-## CRITICAL RULE — How to ask questions
-
-Follow the AskUserQuestion format from the Preamble above. Additional rules for
-DX reviews:
-
-* **One issue = one AskUserQuestion call.** Never combine multiple issues.
-* **Ground every question in evidence.** Reference the persona, competitive benchmark,
-  empathy narrative, or friction trace. Never ask a question in the abstract.
-* **Frame pain from the persona's perspective.** Not "developers would be frustrated"
-  but "[persona from 0A] would hit this at minute [N] of their getting-started flow
-  and [specific consequence: abandon, file an issue, hack a workaround]."
-* Present 2-3 options. For each: effort to fix, impact on developer adoption.
-* **Map to DX First Principles above.** One sentence connecting your recommendation
-  to a specific principle (e.g., "This violates 'zero friction at T0' because
-  [persona] needs 3 extra config steps before their first API call").
-* **Zero findings:** if a section has zero findings, state "No issues, moving on"
-  and proceed. Otherwise, use AskUserQuestion for each gap — a gap with an
-  "obvious fix" is still a gap and still needs user approval before any change
-  lands in the plan.
-* Assume the user hasn't looked at this window in 20 minutes. Re-ground every question.
-
-## Required Outputs
-
-### Developer Persona Card
-The persona card from Step 0A. This goes at the top of the plan's DX section.
-
-### Developer Empathy Narrative
-The first-person narrative from Step 0B, updated with user corrections.
-
-### Competitive DX Benchmark
-The benchmark table from Step 0C, updated with the product's post-review scores.
-
-### Magical Moment Specification
-The chosen delivery vehicle from Step 0D with implementation requirements.
-
-### Developer Journey Map
-The journey map from Step 0F, updated with all friction point resolutions.
-
-### First-Time Developer Confusion Report
-The roleplay report from Step 0G, annotated with which items were addressed.
-
-### "NOT in scope" section
-DX improvements considered and explicitly deferred, with one-line rationale each.
-
-### "What already exists" section
-Existing docs, examples, error handling, and DX patterns that the plan should reuse.
-
-### TODOS.md updates
-After all review passes are complete, present each potential TODO as its own individual
-AskUserQuestion. Never batch. For DX debt: missing error messages, unspecified upgrade
-paths, documentation gaps, missing SDK languages. Each TODO gets:
-* **What:** One-line description
-* **Why:** The concrete developer pain it causes
-* **Pros:** What you gain (adoption, retention, satisfaction)
-* **Cons:** Cost, complexity, or risks
-* **Context:** Enough detail for someone to pick this up in 3 months
-* **Depends on / blocked by:** Prerequisites
-
-Options: **A)** Add to TODOS.md **B)** Skip **C)** Build it now
-
-### DX Scorecard
-
-```
-+====================================================================+
-|              DX PLAN REVIEW — SCORECARD                             |
-+====================================================================+
-| Dimension            | Score  | Prior  | Trend  |
-|----------------------|--------|--------|--------|
-| Getting Started      | __/10  | __/10  | __ ↑↓  |
-| API/CLI/SDK          | __/10  | __/10  | __ ↑↓  |
-| Error Messages       | __/10  | __/10  | __ ↑↓  |
-| Documentation        | __/10  | __/10  | __ ↑↓  |
-| Upgrade Path         | __/10  | __/10  | __ ↑↓  |
-| Dev Environment      | __/10  | __/10  | __ ↑↓  |
-| Community            | __/10  | __/10  | __ ↑↓  |
-| DX Measurement       | __/10  | __/10  | __ ↑↓  |
-+--------------------------------------------------------------------+
-| TTHW                 | __ min | __ min | __ ↑↓  |
-| Competitive Rank     | [Champion/Competitive/Needs Work/Red Flag]   |
-| Magical Moment       | [designed/missing] via [delivery vehicle]    |
-| Product Type         | [type]                                      |
-| Mode                 | [EXPANSION/POLISH/TRIAGE]                    |
-| Overall DX           | __/10  | __/10  | __ ↑↓  |
-+====================================================================+
-| DX PRINCIPLE COVERAGE                                               |
-| Zero Friction      | [covered/gap]                                  |
-| Learn by Doing     | [covered/gap]                                  |
-| Fight Uncertainty  | [covered/gap]                                  |
-| Opinionated + Escape Hatches | [covered/gap]                       |
-| Code in Context    | [covered/gap]                                  |
-| Magical Moments    | [covered/gap]                                  |
-+====================================================================+
-```
-
-If all passes 8+: "DX plan is solid. Developers will have a good experience."
-If any below 6: Flag as critical DX debt with specific impact on adoption.
-If TTHW > 10 min: Flag as blocking issue.
-
-### DX Implementation Checklist
-
-```
-DX IMPLEMENTATION CHECKLIST
-============================
-[ ] Time to hello world < [target from 0C]
-[ ] Installation is one command
-[ ] First run produces meaningful output
-[ ] Magical moment delivered via [vehicle from 0D]
-[ ] Every error message has: problem + cause + fix + docs link
-[ ] API/CLI naming is guessable without docs
-[ ] Every parameter has a sensible default
-[ ] Docs have copy-paste examples that actually work
-[ ] Examples show real use cases, not just hello world
-[ ] Upgrade path documented with migration guide
-[ ] Breaking changes have deprecation warnings + codemods
-[ ] TypeScript types included (if applicable)
-[ ] Works in CI/CD without special configuration
-[ ] Free tier available, no credit card required
-[ ] Changelog exists and is maintained
-[ ] Search works in documentation
-[ ] Community channel exists and is monitored
-```
-
-{{TASKS_SECTION_EMIT:devex-review}}
-
-### Unresolved Decisions
-If any AskUserQuestion goes unanswered, note here. Never silently default.
-
-{{REVIEW_DASHBOARD}}
-
-{{PLAN_FILE_REVIEW_REPORT}}
-
-{{LEARNINGS_LOG}}
-
-{{GBRAIN_SAVE_RESULTS}}
-
-{{BRAIN_WRITE_BACK}}
-
-{{BRAIN_CACHE_REFRESH}}
-
-## Next Steps — Review Chaining
-
-After displaying the Review Readiness Dashboard, recommend next reviews:
-
-**Recommend /plan-eng-review if eng review is not skipped globally** — DX issues often
-have architectural implications. If this DX review found API design problems, error
-handling gaps, or CLI ergonomics issues, eng review should validate the fixes.
-
-**Suggest /plan-design-review if user-facing UI exists** — DX review focuses on
-developer-facing surfaces; design review covers end-user-facing UI.
-
-**Recommend /devex-review after implementation** — the boomerang. Plan said TTHW would
-be [target from 0C]. Did reality match? Run /devex-review on the live product to find
-out. This is where the competitive benchmark pays off: you have a concrete target to
-measure against.
-
-Use AskUserQuestion with applicable options:
-- **A)** Run /plan-eng-review next (required gate)
-- **B)** Run /plan-design-review (only if UI scope detected)
-- **C)** Ready to implement, run /devex-review after shipping
-- **D)** Skip, I'll handle next steps manually
-
-## Mode Quick Reference
-```
-             | DX EXPANSION     | DX POLISH          | DX TRIAGE
-Scope        | Push UP (opt-in) | Maintain           | Critical only
-Posture      | Enthusiastic     | Rigorous           | Surgical
-Competitive  | Full benchmark   | Full benchmark     | Skip
-Magical      | Full design      | Verify exists      | Skip
-Journey      | All stages +     | All stages         | Install + Hello
-             | best-in-class    |                    | World only
-Passes       | All 8, expanded  | All 8, standard    | Pass 1 + 3 only
-Outside voice| Recommended      | Recommended        | Skip
-```
-
-## Formatting Rules
-
-* NUMBER issues (1, 2, 3...) and LETTERS for options (A, B, C...).
-* Label with NUMBER + LETTER (e.g., "3A", "3B").
-* One sentence max per option.
-* After each pass, pause and wait for feedback before moving on.
-* Rate before and after each pass for scannability.
 
 {{EXIT_PLAN_MODE_GATE}}

plan-devex-review/sections/manifest.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://gstack.dev/schemas/section-manifest.json",
+  "skill": "plan-devex-review",
+  "version": 1,
+  "note": "PASSIVE registry (v2 plan T9 / CM2). id/file/title/trigger text ONLY. The skeleton's decision-tree prose decides WHEN to read. See docs/designs/v2_PLAN.md.",
+  "sections": [
+    { "id": "review-sections", "file": "review-sections.md", "title": "8 DX passes, required outputs + review report", "trigger": "running the 8 DX passes, required outputs, and review report (only after Step 0 investigation is complete)" }
+  ]
+}

plan-devex-review/sections/review-sections.md

@@ -0,0 +1,836 @@
+<!-- AUTO-GENERATED from review-sections.md.tmpl — do not edit directly -->
+<!-- Regenerate: bun run gen:skill-docs -->
+## Review Sections (8 passes, after Step 0 is complete)
+
+**Anti-skip rule:** Never condense, abbreviate, or skip any review pass (1-8) regardless of plan type (strategy, spec, code, infra). Every pass in this skill exists for a reason. "This is a strategy doc so DX passes don't apply" is always wrong — DX gaps are where adoption breaks down. If a pass genuinely has zero findings, say "No issues found" and move on — but you must evaluate it.
+
+**Anti-shortcut clause:** The plan file is the OUTPUT of the interactive review, not a substitute for it. Writing every finding into one plan write and calling ExitPlanMode without firing AskUserQuestion is the precise failure mode of the May 2026 transcript bug — the model explored, found issues, and dumped them into a deliverable rather than walking the user through them. If you have ANY non-trivial finding in any review section, the path from finding to ExitPlanMode goes THROUGH AskUserQuestion. Zero findings in every section is the only path to ExitPlanMode that bypasses AskUserQuestion. If you find yourself wanting to write a plan with findings before asking, stop and call AskUserQuestion now — that's the bug, recognize it.
+
+## Prior Learnings
+
+Search for relevant learnings from previous sessions:
+
+```bash
+_CROSS_PROJ=$(~/.claude/skills/gstack/bin/gstack-config get cross_project_learnings 2>/dev/null || echo "unset")
+echo "CROSS_PROJECT: $_CROSS_PROJ"
+if [ "$_CROSS_PROJ" = "true" ]; then
+  ~/.claude/skills/gstack/bin/gstack-learnings-search --limit 10 --cross-project 2>/dev/null || true
+else
+  ~/.claude/skills/gstack/bin/gstack-learnings-search --limit 10 2>/dev/null || true
+fi
+```
+
+If `CROSS_PROJECT` is `unset` (first time): Use AskUserQuestion:
+
+> gstack can search learnings from your other projects on this machine to find
+> patterns that might apply here. This stays local (no data leaves your machine).
+> Recommended for solo developers. Skip if you work on multiple client codebases
+> where cross-contamination would be a concern.
+
+Options:
+- A) Enable cross-project learnings (recommended)
+- B) Keep learnings project-scoped only
+
+If A: run `~/.claude/skills/gstack/bin/gstack-config set cross_project_learnings true`
+If B: run `~/.claude/skills/gstack/bin/gstack-config set cross_project_learnings false`
+
+Then re-run the search with the appropriate flag.
+
+If learnings are found, incorporate them into your analysis. When a review finding
+matches a past learning, display:
+
+**"Prior learning applied: [key] (confidence N/10, from [date])"**
+
+This makes the compounding visible. The user should see that gstack is getting
+smarter on their codebase over time.
+
+### DX Trend Check
+
+Before starting review passes, check for prior DX reviews on this project:
+
+```bash
+eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)"
+~/.claude/skills/gstack/bin/gstack-review-read 2>/dev/null | grep plan-devex-review || echo "NO_PRIOR_DX_REVIEWS"
+```
+
+If prior reviews exist, display the trend:
+```
+DX TREND (prior reviews):
+  Dimension        | Prior Score | Notes
+  Getting Started  | 4/10        | from 2026-03-15
+  ...
+```
+
+### Pass 1: Getting Started Experience (Zero Friction)
+
+Rate 0-10: Can a developer go from zero to hello world in under 5 minutes?
+
+**Evidence recall:** Reference the competitive benchmark from 0C (target tier), the
+magical moment from 0D (delivery vehicle), and any Install/Hello World friction
+points from 0F.
+
+Load reference: Read the "## Pass 1" section from `~/.claude/skills/gstack/plan-devex-review/dx-hall-of-fame.md`.
+
+Evaluate:
+- **Installation**: One command? One click? No prerequisites?
+- **First run**: Does the first command produce visible, meaningful output?
+- **Sandbox/Playground**: Can developers try before installing?
+- **Free tier**: No credit card, no sales call, no company email?
+- **Quick start guide**: Copy-paste complete? Shows real output?
+- **Auth/credential bootstrapping**: How many steps between "I want to try" and "it works"?
+- **Magical moment delivery**: Is the vehicle chosen in 0D actually in the plan?
+- **Competitive gap**: How far is the TTHW from the target tier chosen in 0C?
+
+FIX TO 10: Write the ideal getting started sequence. Specify exact commands,
+expected output, and time budget per step. Target: 3 steps or fewer, under the
+time chosen in 0C.
+
+Stripe test: Can a [persona from 0A] go from "never heard of this" to "it worked"
+in one terminal session without leaving the terminal?
+
+**STOP.** AskUserQuestion once per issue. Recommend + WHY. Reference the persona.
+
+### Pass 2: API/CLI/SDK Design (Usable + Useful)
+
+Rate 0-10: Is the interface intuitive, consistent, and complete?
+
+**Evidence recall:** Does the API surface match [persona from 0A]'s mental model?
+A YC founder expects `tool.do(thing)`. A platform engineer expects
+`tool.configure(options).execute(thing)`.
+
+Load reference: Read the "## Pass 2" section from `~/.claude/skills/gstack/plan-devex-review/dx-hall-of-fame.md`.
+
+Evaluate:
+- **Naming**: Guessable without docs? Consistent grammar?
+- **Defaults**: Every parameter has a sensible default? Simplest call gives useful result?
+- **Consistency**: Same patterns across the entire API surface?
+- **Completeness**: 100% coverage or do devs drop to raw HTTP for edge cases?
+- **Discoverability**: Can devs explore from CLI/playground without docs?
+- **Reliability/trust**: Latency, retries, rate limits, idempotency, offline behavior?
+- **Progressive disclosure**: Simple case is production-ready, complexity revealed gradually?
+- **Persona fit**: Does the interface match how [persona] thinks about the problem?
+
+Good API design test: Can a [persona] use this API correctly after seeing one example?
+
+**STOP.** AskUserQuestion once per issue. Recommend + WHY.
+
+### Pass 3: Error Messages & Debugging (Fight Uncertainty)
+
+Rate 0-10: When something goes wrong, does the developer know what happened, why,
+and how to fix it?
+
+**Evidence recall:** Reference any error-related friction points from 0F and confusion
+points from 0G.
+
+Load reference: Read the "## Pass 3" section from `~/.claude/skills/gstack/plan-devex-review/dx-hall-of-fame.md`.
+
+**Trace 3 specific error paths** from the plan or codebase. For each, evaluate against
+the three-tier system from the Hall of Fame:
+- **Tier 1 (Elm):** Conversational, first person, exact location, suggested fix
+- **Tier 2 (Rust):** Error code links to tutorial, primary + secondary labels, help section
+- **Tier 3 (Stripe API):** Structured JSON with type, code, message, param, doc_url
+
+For each error path, show what the developer currently sees vs. what they should see.
+
+Also evaluate:
+- **Permission/sandbox/safety model**: What can go wrong? How clear is the blast radius?
+- **Debug mode**: Verbose output available?
+- **Stack traces**: Useful or internal framework noise?
+
+**STOP.** AskUserQuestion once per issue. Recommend + WHY.
+
+### Pass 4: Documentation & Learning (Findable + Learn by Doing)
+
+Rate 0-10: Can a developer find what they need and learn by doing?
+
+**Evidence recall:** Does the docs architecture match [persona from 0A]'s learning
+style? A YC founder needs copy-paste examples front and center. A platform engineer
+needs architecture docs and API reference.
+
+Load reference: Read the "## Pass 4" section from `~/.claude/skills/gstack/plan-devex-review/dx-hall-of-fame.md`.
+
+Evaluate:
+- **Information architecture**: Find what they need in under 2 minutes?
+- **Progressive disclosure**: Beginners see simple, experts find advanced?
+- **Code examples**: Copy-paste complete? Work as-is? Real context?
+- **Interactive elements**: Playgrounds, sandboxes, "try it" buttons?
+- **Versioning**: Docs match the version dev is using?
+- **Tutorials vs references**: Both exist?
+
+**STOP.** AskUserQuestion once per issue. Recommend + WHY.
+
+### Pass 5: Upgrade & Migration Path (Credible)
+
+Rate 0-10: Can developers upgrade without fear?
+
+Load reference: Read the "## Pass 5" section from `~/.claude/skills/gstack/plan-devex-review/dx-hall-of-fame.md`.
+
+Evaluate:
+- **Backward compatibility**: What breaks? Blast radius limited?
+- **Deprecation warnings**: Advance notice? Actionable? ("use newMethod() instead")
+- **Migration guides**: Step-by-step for every breaking change?
+- **Codemods**: Automated migration scripts?
+- **Versioning strategy**: Semantic versioning? Clear policy?
+
+**STOP.** AskUserQuestion once per issue. Recommend + WHY.
+
+### Pass 6: Developer Environment & Tooling (Valuable + Accessible)
+
+Rate 0-10: Does this integrate into developers' existing workflows?
+
+**Evidence recall:** Does local dev setup work for [persona from 0A]'s typical
+environment?
+
+Load reference: Read the "## Pass 6" section from `~/.claude/skills/gstack/plan-devex-review/dx-hall-of-fame.md`.
+
+Evaluate:
+- **Editor integration**: Language server? Autocomplete? Inline docs?
+- **CI/CD**: Works in GitHub Actions, GitLab CI? Non-interactive mode?
+- **TypeScript support**: Types included? Good IntelliSense?
+- **Testing support**: Easy to mock? Test utilities?
+- **Local development**: Hot reload? Watch mode? Fast feedback?
+- **Cross-platform**: Mac, Linux, Windows? Docker? ARM/x86?
+- **Local env reproducibility**: Works across OS, package managers, containers, proxies?
+- **Observability/testability**: Dry-run mode? Verbose output? Sample apps? Fixtures?
+
+**STOP.** AskUserQuestion once per issue. Recommend + WHY.
+
+### Pass 7: Community & Ecosystem (Findable + Desirable)
+
+Rate 0-10: Is there a community, and does the plan invest in ecosystem health?
+
+Load reference: Read the "## Pass 7" section from `~/.claude/skills/gstack/plan-devex-review/dx-hall-of-fame.md`.
+
+Evaluate:
+- **Open source**: Code open? Permissive license?
+- **Community channels**: Where do devs ask questions? Someone answering?
+- **Examples**: Real-world, runnable? Not just hello world?
+- **Plugin/extension ecosystem**: Can devs extend it?
+- **Contributing guide**: Process clear?
+- **Pricing transparency**: No surprise bills?
+
+**STOP.** AskUserQuestion once per issue. Recommend + WHY.
+
+### Pass 8: DX Measurement & Feedback Loops (Implement + Refine)
+
+Rate 0-10: Does the plan include ways to measure and improve DX over time?
+
+Load reference: Read the "## Pass 8" section from `~/.claude/skills/gstack/plan-devex-review/dx-hall-of-fame.md`.
+
+Evaluate:
+- **TTHW tracking**: Can you measure getting started time? Is it instrumented?
+- **Journey analytics**: Where do devs drop off?
+- **Feedback mechanisms**: Bug reports? NPS? Feedback button?
+- **Friction audits**: Periodic reviews planned?
+- **Boomerang readiness**: Will /devex-review be able to measure reality vs. plan?
+
+**STOP.** AskUserQuestion once per issue. Recommend + WHY.
+
+### Appendix: Claude Code Skill DX Checklist
+
+**Conditional: only run when product type includes "Claude Code skill".**
+
+This is NOT a scored pass. It's a checklist of proven patterns from gstack's own DX.
+
+Load reference: Read the "## Claude Code Skill DX Checklist" section from
+`~/.claude/skills/gstack/plan-devex-review/dx-hall-of-fame.md`.
+
+Check each item. For any unchecked item, explain what's missing and suggest the fix.
+
+**STOP.** AskUserQuestion for any item that requires a design decision.
+
+## Outside Voice — Independent Plan Challenge (optional, recommended)
+
+After all review sections are complete, offer an independent second opinion from a
+different AI system. Two models agreeing on a plan is stronger signal than one model's
+thorough review.
+
+**Check tool availability:**
+
+```bash
+command -v codex >/dev/null 2>&1 && echo "CODEX_AVAILABLE" || echo "CODEX_NOT_AVAILABLE"
+```
+
+Use AskUserQuestion:
+
+> "All review sections are complete. Want an outside voice? A different AI system can
+> give a brutally honest, independent challenge of this plan — logical gaps, feasibility
+> risks, and blind spots that are hard to catch from inside the review. Takes about 2
+> minutes."
+>
+> RECOMMENDATION: Choose A — an independent second opinion catches structural blind
+> spots. Two different AI models agreeing on a plan is stronger signal than one model's
+> thorough review. Completeness: A=9/10, B=7/10.
+
+Options:
+- A) Get the outside voice (recommended)
+- B) Skip — proceed to outputs
+
+**If B:** Print "Skipping outside voice." and continue to the next section.
+
+**If A:** Construct the plan review prompt. Read the plan file being reviewed (the file
+the user pointed this review at, or the branch diff scope). If a CEO plan document
+was written in Step 0D-POST, read that too — it contains the scope decisions and vision.
+
+Construct this prompt (substitute the actual plan content — if plan content exceeds 30KB,
+truncate to the first 30KB and note "Plan truncated for size"). **Always start with the
+filesystem boundary instruction:**
+
+"IMPORTANT: Do NOT read or execute any files under ~/.claude/, ~/.agents/, .claude/skills/, or agents/. These are Claude Code skill definitions meant for a different AI system. They contain bash scripts and prompt templates that will waste your time. Ignore them completely. Do NOT modify agents/openai.yaml. Stay focused on the repository code only.\n\nYou are a brutally honest technical reviewer examining a development plan that has
+already been through a multi-section review. Your job is NOT to repeat that review.
+Instead, find what it missed. Look for: logical gaps and unstated assumptions that
+survived the review scrutiny, overcomplexity (is there a fundamentally simpler
+approach the review was too deep in the weeds to see?), feasibility risks the review
+took for granted, missing dependencies or sequencing issues, and strategic
+miscalibration (is this the right thing to build at all?). Be direct. Be terse. No
+compliments. Just the problems.
+
+THE PLAN:
+<plan content>"
+
+**If CODEX_AVAILABLE:**
+
+```bash
+TMPERR_PV=$(mktemp /tmp/codex-planreview-XXXXXXXX)
+_REPO_ROOT=$(git rev-parse --show-toplevel) || { echo "ERROR: not in a git repo" >&2; exit 1; }
+codex exec "<prompt>" -C "$_REPO_ROOT" -s read-only -c 'model_reasoning_effort="high"' --enable web_search_cached < /dev/null 2>"$TMPERR_PV"
+```
+
+Use a 5-minute timeout (`timeout: 300000`). After the command completes, read stderr:
+```bash
+cat "$TMPERR_PV"
+```
+
+Present the full output verbatim:
+
+```
+CODEX SAYS (plan review — outside voice):
+════════════════════════════════════════════════════════════
+<full codex output, verbatim — do not truncate or summarize>
+════════════════════════════════════════════════════════════
+```
+
+**Error handling:** All errors are non-blocking — the outside voice is informational.
+- Auth failure (stderr contains "auth", "login", "unauthorized"): "Codex auth failed. Run \`codex login\` to authenticate."
+- Timeout: "Codex timed out after 5 minutes."
+- Empty response: "Codex returned no response."
+
+On any Codex error, fall back to the Claude adversarial subagent.
+
+**If CODEX_NOT_AVAILABLE (or Codex errored):**
+
+Dispatch via the Agent tool. The subagent has fresh context — genuine independence.
+
+Subagent prompt: same plan review prompt as above.
+
+Present findings under an `OUTSIDE VOICE (Claude subagent):` header.
+
+If the subagent fails or times out: "Outside voice unavailable. Continuing to outputs."
+
+**Cross-model tension:**
+
+After presenting the outside voice findings, note any points where the outside voice
+disagrees with the review findings from earlier sections. Flag these as:
+
+```
+CROSS-MODEL TENSION:
+  [Topic]: Review said X. Outside voice says Y. [Present both perspectives neutrally.
+  State what context you might be missing that would change the answer.]
+```
+
+**User Sovereignty:** Do NOT auto-incorporate outside voice recommendations into the plan.
+Present each tension point to the user. The user decides. Cross-model agreement is a
+strong signal — present it as such — but it is NOT permission to act. You may state
+which argument you find more compelling, but you MUST NOT apply the change without
+explicit user approval.
+
+For each substantive tension point, use AskUserQuestion:
+
+> "Cross-model disagreement on [topic]. The review found [X] but the outside voice
+> argues [Y]. [One sentence on what context you might be missing.]"
+>
+> RECOMMENDATION: Choose [A or B] because [one-line reason explaining which argument
+> is more compelling and why]. Completeness: A=X/10, B=Y/10.
+
+Options:
+- A) Accept the outside voice's recommendation (I'll apply this change)
+- B) Keep the current approach (reject the outside voice)
+- C) Investigate further before deciding
+- D) Add to TODOS.md for later
+
+Wait for the user's response. Do NOT default to accepting because you agree with the
+outside voice. If the user chooses B, the current approach stands — do not re-argue.
+
+If no tension points exist, note: "No cross-model tension — both reviewers agree."
+
+**Persist the result:**
+```bash
+~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"codex-plan-review","timestamp":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'","status":"STATUS","source":"SOURCE","commit":"'"$(git rev-parse --short HEAD)"'"}'
+```
+
+Substitute: STATUS = "clean" if no findings, "issues_found" if findings exist.
+SOURCE = "codex" if Codex ran, "claude" if subagent ran.
+
+**Cleanup:** Run `rm -f "$TMPERR_PV"` after processing (if Codex was used).
+
+---
+
+When constructing the outside voice prompt, include the Developer Persona from Step 0A
+and the Competitive Benchmark from Step 0C. The outside voice should critique the plan
+in the context of who is using it and what they're competing against.
+
+## CRITICAL RULE — How to ask questions
+
+Follow the AskUserQuestion format from the Preamble above. Additional rules for
+DX reviews:
+
+* **One issue = one AskUserQuestion call.** Never combine multiple issues.
+* **Ground every question in evidence.** Reference the persona, competitive benchmark,
+  empathy narrative, or friction trace. Never ask a question in the abstract.
+* **Frame pain from the persona's perspective.** Not "developers would be frustrated"
+  but "[persona from 0A] would hit this at minute [N] of their getting-started flow
+  and [specific consequence: abandon, file an issue, hack a workaround]."
+* Present 2-3 options. For each: effort to fix, impact on developer adoption.
+* **Map to DX First Principles above.** One sentence connecting your recommendation
+  to a specific principle (e.g., "This violates 'zero friction at T0' because
+  [persona] needs 3 extra config steps before their first API call").
+* **Zero findings:** if a section has zero findings, state "No issues, moving on"
+  and proceed. Otherwise, use AskUserQuestion for each gap — a gap with an
+  "obvious fix" is still a gap and still needs user approval before any change
+  lands in the plan.
+* Assume the user hasn't looked at this window in 20 minutes. Re-ground every question.
+
+## Required Outputs
+
+### Developer Persona Card
+The persona card from Step 0A. This goes at the top of the plan's DX section.
+
+### Developer Empathy Narrative
+The first-person narrative from Step 0B, updated with user corrections.
+
+### Competitive DX Benchmark
+The benchmark table from Step 0C, updated with the product's post-review scores.
+
+### Magical Moment Specification
+The chosen delivery vehicle from Step 0D with implementation requirements.
+
+### Developer Journey Map
+The journey map from Step 0F, updated with all friction point resolutions.
+
+### First-Time Developer Confusion Report
+The roleplay report from Step 0G, annotated with which items were addressed.
+
+### "NOT in scope" section
+DX improvements considered and explicitly deferred, with one-line rationale each.
+
+### "What already exists" section
+Existing docs, examples, error handling, and DX patterns that the plan should reuse.
+
+### TODOS.md updates
+After all review passes are complete, present each potential TODO as its own individual
+AskUserQuestion. Never batch. For DX debt: missing error messages, unspecified upgrade
+paths, documentation gaps, missing SDK languages. Each TODO gets:
+* **What:** One-line description
+* **Why:** The concrete developer pain it causes
+* **Pros:** What you gain (adoption, retention, satisfaction)
+* **Cons:** Cost, complexity, or risks
+* **Context:** Enough detail for someone to pick this up in 3 months
+* **Depends on / blocked by:** Prerequisites
+
+Options: **A)** Add to TODOS.md **B)** Skip **C)** Build it now
+
+### DX Scorecard
+
+```
++====================================================================+
+|              DX PLAN REVIEW — SCORECARD                             |
++====================================================================+
+| Dimension            | Score  | Prior  | Trend  |
+|----------------------|--------|--------|--------|
+| Getting Started      | __/10  | __/10  | __ ↑↓  |
+| API/CLI/SDK          | __/10  | __/10  | __ ↑↓  |
+| Error Messages       | __/10  | __/10  | __ ↑↓  |
+| Documentation        | __/10  | __/10  | __ ↑↓  |
+| Upgrade Path         | __/10  | __/10  | __ ↑↓  |
+| Dev Environment      | __/10  | __/10  | __ ↑↓  |
+| Community            | __/10  | __/10  | __ ↑↓  |
+| DX Measurement       | __/10  | __/10  | __ ↑↓  |
++--------------------------------------------------------------------+
+| TTHW                 | __ min | __ min | __ ↑↓  |
+| Competitive Rank     | [Champion/Competitive/Needs Work/Red Flag]   |
+| Magical Moment       | [designed/missing] via [delivery vehicle]    |
+| Product Type         | [type]                                      |
+| Mode                 | [EXPANSION/POLISH/TRIAGE]                    |
+| Overall DX           | __/10  | __/10  | __ ↑↓  |
++====================================================================+
+| DX PRINCIPLE COVERAGE                                               |
+| Zero Friction      | [covered/gap]                                  |
+| Learn by Doing     | [covered/gap]                                  |
+| Fight Uncertainty  | [covered/gap]                                  |
+| Opinionated + Escape Hatches | [covered/gap]                       |
+| Code in Context    | [covered/gap]                                  |
+| Magical Moments    | [covered/gap]                                  |
++====================================================================+
+```
+
+If all passes 8+: "DX plan is solid. Developers will have a good experience."
+If any below 6: Flag as critical DX debt with specific impact on adoption.
+If TTHW > 10 min: Flag as blocking issue.
+
+### DX Implementation Checklist
+
+```
+DX IMPLEMENTATION CHECKLIST
+============================
+[ ] Time to hello world < [target from 0C]
+[ ] Installation is one command
+[ ] First run produces meaningful output
+[ ] Magical moment delivered via [vehicle from 0D]
+[ ] Every error message has: problem + cause + fix + docs link
+[ ] API/CLI naming is guessable without docs
+[ ] Every parameter has a sensible default
+[ ] Docs have copy-paste examples that actually work
+[ ] Examples show real use cases, not just hello world
+[ ] Upgrade path documented with migration guide
+[ ] Breaking changes have deprecation warnings + codemods
+[ ] TypeScript types included (if applicable)
+[ ] Works in CI/CD without special configuration
+[ ] Free tier available, no credit card required
+[ ] Changelog exists and is maintained
+[ ] Search works in documentation
+[ ] Community channel exists and is monitored
+```
+
+## Implementation Tasks
+
+Before closing this review, synthesize the findings above into a flat list of
+build-actionable tasks. Each task derives from a specific finding — no padding.
+Emit the markdown section AND write a JSONL artifact that `/autoplan` can
+aggregate across phases.
+
+### Markdown section (always emit)
+
+```markdown
+## Implementation Tasks
+Synthesized from this review's findings. Each task derives from a specific
+finding above. Run with Claude Code or Codex; checkbox as you ship.
+
+- [ ] **T1 (P1, human: ~2h / CC: ~15min)** — <component> — <imperative title>
+  - Surfaced by: <section name> — <specific finding text or line reference>
+  - Files: <paths to touch>
+  - Verify: <test command or manual check>
+- [ ] **T2 (P2, human: ~30min / CC: ~5min)** — ...
+```
+
+Rules:
+- P1 blocks ship; P2 should land same branch; P3 is a follow-up TODO.
+- If a finding produced no actionable task, do not invent one.
+- If a section had zero findings, emit `_No new tasks from <section>._`
+- Effort uses the AI-compression table from CLAUDE.md.
+
+### JSONL artifact (always write, even if zero tasks)
+
+`/autoplan` reads this file to aggregate across phases. Build each line with
+`jq -nc` so titles and source findings containing quotes, newlines, or
+backslashes serialize cleanly — never use hand-rolled `echo` / `printf`.
+
+```bash
+eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)"
+TASKS_DIR="${HOME}/.gstack/projects/${SLUG:-unknown}"
+mkdir -p "$TASKS_DIR"
+TASKS_FILE="$TASKS_DIR/tasks-devex-review-$(date +%Y%m%d-%H%M%S).jsonl"
+COMMIT=$(git rev-parse HEAD 2>/dev/null || echo unknown)
+BRANCH=$(git branch --show-current 2>/dev/null || echo unknown)
+RUN_ID="$(date -u +%Y%m%dT%H%M%SZ)-$$"
+
+# Repeat ONE jq invocation per task identified during this review.
+# Substitute the placeholders inline with shell variables you set per task:
+#   TASK_ID (T1, T2, ...), PRIORITY (P1/P2/P3), COMPONENT, TITLE,
+#   SOURCE_FINDING, EFFORT_HUMAN, EFFORT_CC, FILES_JSON (a JSON array literal
+#   like '["browse/src/sanitize.ts","browse/src/server.ts"]').
+jq -nc \
+  --arg phase 'devex-review' \
+  --arg run_id "$RUN_ID" \
+  --arg branch "$BRANCH" \
+  --arg commit "$COMMIT" \
+  --arg id "$TASK_ID" \
+  --arg priority "$PRIORITY" \
+  --arg component "$COMPONENT" \
+  --arg effort_human "$EFFORT_HUMAN" \
+  --arg effort_cc "$EFFORT_CC" \
+  --arg title "$TITLE" \
+  --arg source_finding "$SOURCE_FINDING" \
+  --argjson files "$FILES_JSON" \
+  '{phase:$phase, run_id:$run_id, branch:$branch, commit:$commit, id:$id, priority:$priority, component:$component, files:$files, effort_human:$effort_human, effort_cc:$effort_cc, title:$title, source_finding:$source_finding}' \
+  >> "$TASKS_FILE"
+```
+
+If `jq` is not installed, fall back to skipping the JSONL write and warn
+the user to install jq for autoplan aggregation. Never hand-roll JSONL.
+
+If zero tasks were identified in this review, still touch the JSONL file
+(`: > "$TASKS_FILE"`) so the aggregator sees that the phase produced output
+this run (an empty file means "ran, no findings" — distinct from "didn't run").
+
+
+### Unresolved Decisions
+If any AskUserQuestion goes unanswered, note here. Never silently default.
+
+## Review Readiness Dashboard
+
+After completing the review, read the review log and config to display the dashboard.
+
+```bash
+~/.claude/skills/gstack/bin/gstack-review-read
+```
+
+Parse the output. Find the most recent entry for each skill (plan-ceo-review, plan-eng-review, review, plan-design-review, design-review-lite, adversarial-review, codex-review, codex-plan-review). Ignore entries with timestamps older than 7 days. For the Eng Review row, show whichever is more recent between `review` (diff-scoped pre-landing review) and `plan-eng-review` (plan-stage architecture review). Append "(DIFF)" or "(PLAN)" to the status to distinguish. For the Adversarial row, show whichever is more recent between `adversarial-review` (new auto-scaled) and `codex-review` (legacy). For Design Review, show whichever is more recent between `plan-design-review` (full visual audit) and `design-review-lite` (code-level check). Append "(FULL)" or "(LITE)" to the status to distinguish. For the Outside Voice row, show the most recent `codex-plan-review` entry — this captures outside voices from both /plan-ceo-review and /plan-eng-review.
+
+**Source attribution:** If the most recent entry for a skill has a \`"via"\` field, append it to the status label in parentheses. Examples: `plan-eng-review` with `via:"autoplan"` shows as "CLEAR (PLAN via /autoplan)". `review` with `via:"ship"` shows as "CLEAR (DIFF via /ship)". Entries without a `via` field show as "CLEAR (PLAN)" or "CLEAR (DIFF)" as before.
+
+Note: `autoplan-voices` and `design-outside-voices` entries are audit-trail-only (forensic data for cross-model consensus analysis). They do not appear in the dashboard and are not checked by any consumer.
+
+Display:
+
+```
++====================================================================+
+|                    REVIEW READINESS DASHBOARD                       |
++====================================================================+
+| Review          | Runs | Last Run            | Status    | Required |
+|-----------------|------|---------------------|-----------|----------|
+| Eng Review      |  1   | 2026-03-16 15:00    | CLEAR     | YES      |
+| CEO Review      |  0   | —                   | —         | no       |
+| Design Review   |  0   | —                   | —         | no       |
+| Adversarial     |  0   | —                   | —         | no       |
+| Outside Voice   |  0   | —                   | —         | no       |
++--------------------------------------------------------------------+
+| VERDICT: CLEARED — Eng Review passed                                |
++====================================================================+
+```
+
+**Review tiers:**
+- **Eng Review (required by default):** The only review that gates shipping. Covers architecture, code quality, tests, performance. Can be disabled globally with \`gstack-config set skip_eng_review true\` (the "don't bother me" setting).
+- **CEO Review (optional):** Use your judgment. Recommend it for big product/business changes, new user-facing features, or scope decisions. Skip for bug fixes, refactors, infra, and cleanup.
+- **Design Review (optional):** Use your judgment. Recommend it for UI/UX changes. Skip for backend-only, infra, or prompt-only changes.
+- **Adversarial Review (automatic):** Always-on for every review. Every diff gets both Claude adversarial subagent and Codex adversarial challenge. Large diffs (200+ lines) additionally get Codex structured review with P1 gate. No configuration needed.
+- **Outside Voice (optional):** Independent plan review from a different AI model. Offered after all review sections complete in /plan-ceo-review and /plan-eng-review. Falls back to Claude subagent if Codex is unavailable. Never gates shipping.
+
+**Verdict logic:**
+- **CLEARED**: Eng Review has >= 1 entry within 7 days from either \`review\` or \`plan-eng-review\` with status "clean" (or \`skip_eng_review\` is \`true\`)
+- **NOT CLEARED**: Eng Review missing, stale (>7 days), or has open issues
+- CEO, Design, and Codex reviews are shown for context but never block shipping
+- If \`skip_eng_review\` config is \`true\`, Eng Review shows "SKIPPED (global)" and verdict is CLEARED
+
+**Staleness detection:** After displaying the dashboard, check if any existing reviews may be stale:
+- Parse the \`---HEAD---\` section from the bash output to get the current HEAD commit hash
+- For each review entry that has a \`commit\` field: compare it against the current HEAD. If different, count elapsed commits: \`git rev-list --count STORED_COMMIT..HEAD\`. Display: "Note: {skill} review from {date} may be stale — {N} commits since review"
+- For entries without a \`commit\` field (legacy entries): display "Note: {skill} review from {date} has no commit tracking — consider re-running for accurate staleness detection"
+- If all reviews match the current HEAD, do not display any staleness notes
+
+## Plan File Review Report
+
+After displaying the Review Readiness Dashboard in conversation output, also update the
+**plan file** itself so review status is visible to anyone reading the plan.
+
+### Detect the plan file
+
+1. Check if there is an active plan file in this conversation (the host provides plan file
+   paths in system messages — look for plan file references in the conversation context).
+2. If not found, skip this section silently — not every review runs in plan mode.
+
+### Generate the report
+
+Read the review log output you already have from the Review Readiness Dashboard step above.
+Parse each JSONL entry. Each skill logs different fields:
+
+- **plan-ceo-review**: \`status\`, \`unresolved\`, \`critical_gaps\`, \`mode\`, \`scope_proposed\`, \`scope_accepted\`, \`scope_deferred\`, \`commit\`
+  → Findings: "{scope_proposed} proposals, {scope_accepted} accepted, {scope_deferred} deferred"
+  → If scope fields are 0 or missing (HOLD/REDUCTION mode): "mode: {mode}, {critical_gaps} critical gaps"
+- **plan-eng-review**: \`status\`, \`unresolved\`, \`critical_gaps\`, \`issues_found\`, \`mode\`, \`commit\`
+  → Findings: "{issues_found} issues, {critical_gaps} critical gaps"
+- **plan-design-review**: \`status\`, \`initial_score\`, \`overall_score\`, \`unresolved\`, \`decisions_made\`, \`commit\`
+  → Findings: "score: {initial_score}/10 → {overall_score}/10, {decisions_made} decisions"
+- **plan-devex-review**: \`status\`, \`initial_score\`, \`overall_score\`, \`product_type\`, \`tthw_current\`, \`tthw_target\`, \`mode\`, \`persona\`, \`competitive_tier\`, \`unresolved\`, \`commit\`
+  → Findings: "score: {initial_score}/10 → {overall_score}/10, TTHW: {tthw_current} → {tthw_target}"
+- **devex-review**: \`status\`, \`overall_score\`, \`product_type\`, \`tthw_measured\`, \`dimensions_tested\`, \`dimensions_inferred\`, \`boomerang\`, \`commit\`
+  → Findings: "score: {overall_score}/10, TTHW: {tthw_measured}, {dimensions_tested} tested/{dimensions_inferred} inferred"
+- **codex-review**: \`status\`, \`gate\`, \`findings\`, \`findings_fixed\`
+  → Findings: "{findings} findings, {findings_fixed}/{findings} fixed"
+
+All fields needed for the Findings column are now present in the JSONL entries.
+For the review you just completed, you may use richer details from your own Completion
+Summary. For prior reviews, use the JSONL fields directly — they contain all required data.
+
+Produce this markdown table:
+
+\`\`\`markdown
+## GSTACK REVIEW REPORT
+
+| Review | Trigger | Why | Runs | Status | Findings |
+|--------|---------|-----|------|--------|----------|
+| CEO Review | \`/plan-ceo-review\` | Scope & strategy | {runs} | {status} | {findings} |
+| Codex Review | \`/codex review\` | Independent 2nd opinion | {runs} | {status} | {findings} |
+| Eng Review | \`/plan-eng-review\` | Architecture & tests (required) | {runs} | {status} | {findings} |
+| Design Review | \`/plan-design-review\` | UI/UX gaps | {runs} | {status} | {findings} |
+| DX Review | \`/plan-devex-review\` | Developer experience gaps | {runs} | {status} | {findings} |
+\`\`\`
+
+Below the table, add these lines (omit any that are empty/not applicable):
+
+- **CODEX:** (only if codex-review ran) — one-line summary of codex fixes
+- **CROSS-MODEL:** (only if both Claude and Codex reviews exist) — overlap analysis
+- **UNRESOLVED:** total unresolved decisions across all reviews
+- **VERDICT:** list reviews that are CLEAR (e.g., "CEO + ENG CLEARED — ready to implement").
+  If Eng Review is not CLEAR and not skipped globally, append "eng review required".
+
+### Write to the plan file
+
+**PLAN MODE EXCEPTION — ALWAYS RUN:** This writes to the plan file, which is the one
+file you are allowed to edit in plan mode. The plan file review report is part of the
+plan's living status.
+
+The report must always be the LAST section of the plan file — never mid-file.
+Use a single delete-then-append flow:
+
+1. Read the plan file (Read tool) to see its full current content. Search the read
+   output for a \`## GSTACK REVIEW REPORT\` heading anywhere in the file.
+2. If found, use the Edit tool to DELETE the entire existing section. Match from
+   \`## GSTACK REVIEW REPORT\` through either the next \`## \` heading or end of
+   file, whichever comes first. Replace with the empty string. This applies
+   regardless of where the section currently lives — mid-file deletion is
+   intentional, not a special case. If the Edit fails (e.g., concurrent edit
+   changed the content), re-read the plan file and retry once.
+3. After the delete (or skipped, if no section existed), append the new
+   \`## GSTACK REVIEW REPORT\` section at the END of the file. Use the Edit
+   tool to match the file's current last paragraph and add the section after it,
+   or use Write to re-emit the whole file with the section at the end.
+4. Verify with the Read tool that \`## GSTACK REVIEW REPORT\` is the last
+   \`## \` heading in the file before continuing. If it isn't, repeat steps
+   2-3 once.
+
+Do NOT replace the section in place. The "replace mid-file" path is what allowed
+prior versions to leave the report mid-file when an older report already lived
+there — the user then sees a plan whose review report is not at the bottom and
+(correctly) rejects it.
+
+## Capture Learnings
+
+If you discovered a non-obvious pattern, pitfall, or architectural insight during
+this session, log it for future sessions:
+
+```bash
+~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"plan-devex-review","type":"TYPE","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"SOURCE","files":["path/to/relevant/file"]}'
+```
+
+**Types:** `pattern` (reusable approach), `pitfall` (what NOT to do), `preference`
+(user stated), `architecture` (structural decision), `tool` (library/framework insight),
+`operational` (project environment/CLI/workflow knowledge).
+
+**Sources:** `observed` (you found this in the code), `user-stated` (user told you),
+`inferred` (AI deduction), `cross-model` (both Claude and Codex agree).
+
+**Confidence:** 1-10. Be honest. An observed pattern you verified in the code is 8-9.
+An inference you're not sure about is 4-5. A user preference they explicitly stated is 10.
+
+**files:** Include the specific file paths this learning references. This enables
+staleness detection: if those files are later deleted, the learning can be flagged.
+
+**Only log genuine discoveries.** Don't log obvious things. Don't log things the user
+already knows. A good test: would this insight save time in a future session? If yes, log it.
+
+
+
+## Brain Calibration Write-Back (Phase 2 / gated)
+
+When the skill makes a typed prediction worth tracking (scope decision,
+TTHW target, architectural bet, wedge commitment), it MAY write a
+`kind=bet` take to the brain so a calibration profile builds over time.
+
+**Gated on two things:**
+1. Brain trust policy for the active endpoint is `personal` (check via
+   `~/.claude/skills/gstack/bin/gstack-config get brain_trust_policy@<endpoint-hash>`).
+   Shared brains skip write-back to avoid polluting team calibration.
+2. Feature flag `BRAIN_CALIBRATION_WRITEBACK` is set (today: false; flips
+   to true when upstream gbrain v0.42+ ships `takes_add` MCP op).
+
+When both gates pass, the write-back path uses `mcp__gbrain__takes_add`
+to record a take with weight 0.6 (per SKILL_CALIBRATION_WEIGHTS).
+If the MCP op is unavailable, fall back to `mcp__gbrain__put_page` with
+a gstack:takes fence block (documented but uglier path).
+
+Mandatory take frontmatter shape:
+```yaml
+kind: bet
+holder: <user identity from whoami>
+claim: <one-line prediction the skill is making>
+weight: 0.6
+since_date: <today's date>
+expected_resolution: <date in 1-3 months depending on skill>
+source_skill: plan-devex-review
+```
+
+After write, invalidate the affected digests so the next preflight reflects
+the new state:
+
+```bash
+eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true
+  ~/.claude/skills/gstack/bin/gstack-brain-cache invalidate developer-persona --project "$SLUG" 2>/dev/null || true
+```
+
+
+## Brain Cache Background Refresh
+
+After the skill's work completes (and telemetry has logged), kick a
+background refresh of any cache digest that's getting close to its TTL.
+This is non-blocking — the user doesn't wait. Next invocation benefits
+from the warm cache.
+
+```bash
+eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true
+(~/.claude/skills/gstack/bin/gstack-brain-cache refresh --project "$SLUG" 2>/dev/null &) || true
+```
+
+
+## Next Steps — Review Chaining
+
+After displaying the Review Readiness Dashboard, recommend next reviews:
+
+**Recommend /plan-eng-review if eng review is not skipped globally** — DX issues often
+have architectural implications. If this DX review found API design problems, error
+handling gaps, or CLI ergonomics issues, eng review should validate the fixes.
+
+**Suggest /plan-design-review if user-facing UI exists** — DX review focuses on
+developer-facing surfaces; design review covers end-user-facing UI.
+
+**Recommend /devex-review after implementation** — the boomerang. Plan said TTHW would
+be [target from 0C]. Did reality match? Run /devex-review on the live product to find
+out. This is where the competitive benchmark pays off: you have a concrete target to
+measure against.
+
+Use AskUserQuestion with applicable options:
+- **A)** Run /plan-eng-review next (required gate)
+- **B)** Run /plan-design-review (only if UI scope detected)
+- **C)** Ready to implement, run /devex-review after shipping
+- **D)** Skip, I'll handle next steps manually
+
+## Mode Quick Reference
+```
+             | DX EXPANSION     | DX POLISH          | DX TRIAGE
+Scope        | Push UP (opt-in) | Maintain           | Critical only
+Posture      | Enthusiastic     | Rigorous           | Surgical
+Competitive  | Full benchmark   | Full benchmark     | Skip
+Magical      | Full design      | Verify exists      | Skip
+Journey      | All stages +     | All stages         | Install + Hello
+             | best-in-class    |                    | World only
+Passes       | All 8, expanded  | All 8, standard    | Pass 1 + 3 only
+Outside voice| Recommended      | Recommended        | Skip
+```
+
+## Formatting Rules
+
+* NUMBER issues (1, 2, 3...) and LETTERS for options (A, B, C...).
+* Label with NUMBER + LETTER (e.g., "3A", "3B").
+* One sentence max per option.
+* After each pass, pause and wait for feedback before moving on.
+* Rate before and after each pass for scannability.
+

plan-devex-review/sections/review-sections.md.tmpl

@@ -0,0 +1,391 @@
+## Review Sections (8 passes, after Step 0 is complete)
+
+**Anti-skip rule:** Never condense, abbreviate, or skip any review pass (1-8) regardless of plan type (strategy, spec, code, infra). Every pass in this skill exists for a reason. "This is a strategy doc so DX passes don't apply" is always wrong — DX gaps are where adoption breaks down. If a pass genuinely has zero findings, say "No issues found" and move on — but you must evaluate it.
+
+{{ANTI_SHORTCUT_CLAUSE}}
+
+{{LEARNINGS_SEARCH}}
+
+### DX Trend Check
+
+Before starting review passes, check for prior DX reviews on this project:
+
+```bash
+eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)"
+~/.claude/skills/gstack/bin/gstack-review-read 2>/dev/null | grep plan-devex-review || echo "NO_PRIOR_DX_REVIEWS"
+```
+
+If prior reviews exist, display the trend:
+```
+DX TREND (prior reviews):
+  Dimension        | Prior Score | Notes
+  Getting Started  | 4/10        | from 2026-03-15
+  ...
+```
+
+### Pass 1: Getting Started Experience (Zero Friction)
+
+Rate 0-10: Can a developer go from zero to hello world in under 5 minutes?
+
+**Evidence recall:** Reference the competitive benchmark from 0C (target tier), the
+magical moment from 0D (delivery vehicle), and any Install/Hello World friction
+points from 0F.
+
+Load reference: Read the "## Pass 1" section from `~/.claude/skills/gstack/plan-devex-review/dx-hall-of-fame.md`.
+
+Evaluate:
+- **Installation**: One command? One click? No prerequisites?
+- **First run**: Does the first command produce visible, meaningful output?
+- **Sandbox/Playground**: Can developers try before installing?
+- **Free tier**: No credit card, no sales call, no company email?
+- **Quick start guide**: Copy-paste complete? Shows real output?
+- **Auth/credential bootstrapping**: How many steps between "I want to try" and "it works"?
+- **Magical moment delivery**: Is the vehicle chosen in 0D actually in the plan?
+- **Competitive gap**: How far is the TTHW from the target tier chosen in 0C?
+
+FIX TO 10: Write the ideal getting started sequence. Specify exact commands,
+expected output, and time budget per step. Target: 3 steps or fewer, under the
+time chosen in 0C.
+
+Stripe test: Can a [persona from 0A] go from "never heard of this" to "it worked"
+in one terminal session without leaving the terminal?
+
+**STOP.** AskUserQuestion once per issue. Recommend + WHY. Reference the persona.
+
+### Pass 2: API/CLI/SDK Design (Usable + Useful)
+
+Rate 0-10: Is the interface intuitive, consistent, and complete?
+
+**Evidence recall:** Does the API surface match [persona from 0A]'s mental model?
+A YC founder expects `tool.do(thing)`. A platform engineer expects
+`tool.configure(options).execute(thing)`.
+
+Load reference: Read the "## Pass 2" section from `~/.claude/skills/gstack/plan-devex-review/dx-hall-of-fame.md`.
+
+Evaluate:
+- **Naming**: Guessable without docs? Consistent grammar?
+- **Defaults**: Every parameter has a sensible default? Simplest call gives useful result?
+- **Consistency**: Same patterns across the entire API surface?
+- **Completeness**: 100% coverage or do devs drop to raw HTTP for edge cases?
+- **Discoverability**: Can devs explore from CLI/playground without docs?
+- **Reliability/trust**: Latency, retries, rate limits, idempotency, offline behavior?
+- **Progressive disclosure**: Simple case is production-ready, complexity revealed gradually?
+- **Persona fit**: Does the interface match how [persona] thinks about the problem?
+
+Good API design test: Can a [persona] use this API correctly after seeing one example?
+
+**STOP.** AskUserQuestion once per issue. Recommend + WHY.
+
+### Pass 3: Error Messages & Debugging (Fight Uncertainty)
+
+Rate 0-10: When something goes wrong, does the developer know what happened, why,
+and how to fix it?
+
+**Evidence recall:** Reference any error-related friction points from 0F and confusion
+points from 0G.
+
+Load reference: Read the "## Pass 3" section from `~/.claude/skills/gstack/plan-devex-review/dx-hall-of-fame.md`.
+
+**Trace 3 specific error paths** from the plan or codebase. For each, evaluate against
+the three-tier system from the Hall of Fame:
+- **Tier 1 (Elm):** Conversational, first person, exact location, suggested fix
+- **Tier 2 (Rust):** Error code links to tutorial, primary + secondary labels, help section
+- **Tier 3 (Stripe API):** Structured JSON with type, code, message, param, doc_url
+
+For each error path, show what the developer currently sees vs. what they should see.
+
+Also evaluate:
+- **Permission/sandbox/safety model**: What can go wrong? How clear is the blast radius?
+- **Debug mode**: Verbose output available?
+- **Stack traces**: Useful or internal framework noise?
+
+**STOP.** AskUserQuestion once per issue. Recommend + WHY.
+
+### Pass 4: Documentation & Learning (Findable + Learn by Doing)
+
+Rate 0-10: Can a developer find what they need and learn by doing?
+
+**Evidence recall:** Does the docs architecture match [persona from 0A]'s learning
+style? A YC founder needs copy-paste examples front and center. A platform engineer
+needs architecture docs and API reference.
+
+Load reference: Read the "## Pass 4" section from `~/.claude/skills/gstack/plan-devex-review/dx-hall-of-fame.md`.
+
+Evaluate:
+- **Information architecture**: Find what they need in under 2 minutes?
+- **Progressive disclosure**: Beginners see simple, experts find advanced?
+- **Code examples**: Copy-paste complete? Work as-is? Real context?
+- **Interactive elements**: Playgrounds, sandboxes, "try it" buttons?
+- **Versioning**: Docs match the version dev is using?
+- **Tutorials vs references**: Both exist?
+
+**STOP.** AskUserQuestion once per issue. Recommend + WHY.
+
+### Pass 5: Upgrade & Migration Path (Credible)
+
+Rate 0-10: Can developers upgrade without fear?
+
+Load reference: Read the "## Pass 5" section from `~/.claude/skills/gstack/plan-devex-review/dx-hall-of-fame.md`.
+
+Evaluate:
+- **Backward compatibility**: What breaks? Blast radius limited?
+- **Deprecation warnings**: Advance notice? Actionable? ("use newMethod() instead")
+- **Migration guides**: Step-by-step for every breaking change?
+- **Codemods**: Automated migration scripts?
+- **Versioning strategy**: Semantic versioning? Clear policy?
+
+**STOP.** AskUserQuestion once per issue. Recommend + WHY.
+
+### Pass 6: Developer Environment & Tooling (Valuable + Accessible)
+
+Rate 0-10: Does this integrate into developers' existing workflows?
+
+**Evidence recall:** Does local dev setup work for [persona from 0A]'s typical
+environment?
+
+Load reference: Read the "## Pass 6" section from `~/.claude/skills/gstack/plan-devex-review/dx-hall-of-fame.md`.
+
+Evaluate:
+- **Editor integration**: Language server? Autocomplete? Inline docs?
+- **CI/CD**: Works in GitHub Actions, GitLab CI? Non-interactive mode?
+- **TypeScript support**: Types included? Good IntelliSense?
+- **Testing support**: Easy to mock? Test utilities?
+- **Local development**: Hot reload? Watch mode? Fast feedback?
+- **Cross-platform**: Mac, Linux, Windows? Docker? ARM/x86?
+- **Local env reproducibility**: Works across OS, package managers, containers, proxies?
+- **Observability/testability**: Dry-run mode? Verbose output? Sample apps? Fixtures?
+
+**STOP.** AskUserQuestion once per issue. Recommend + WHY.
+
+### Pass 7: Community & Ecosystem (Findable + Desirable)
+
+Rate 0-10: Is there a community, and does the plan invest in ecosystem health?
+
+Load reference: Read the "## Pass 7" section from `~/.claude/skills/gstack/plan-devex-review/dx-hall-of-fame.md`.
+
+Evaluate:
+- **Open source**: Code open? Permissive license?
+- **Community channels**: Where do devs ask questions? Someone answering?
+- **Examples**: Real-world, runnable? Not just hello world?
+- **Plugin/extension ecosystem**: Can devs extend it?
+- **Contributing guide**: Process clear?
+- **Pricing transparency**: No surprise bills?
+
+**STOP.** AskUserQuestion once per issue. Recommend + WHY.
+
+### Pass 8: DX Measurement & Feedback Loops (Implement + Refine)
+
+Rate 0-10: Does the plan include ways to measure and improve DX over time?
+
+Load reference: Read the "## Pass 8" section from `~/.claude/skills/gstack/plan-devex-review/dx-hall-of-fame.md`.
+
+Evaluate:
+- **TTHW tracking**: Can you measure getting started time? Is it instrumented?
+- **Journey analytics**: Where do devs drop off?
+- **Feedback mechanisms**: Bug reports? NPS? Feedback button?
+- **Friction audits**: Periodic reviews planned?
+- **Boomerang readiness**: Will /devex-review be able to measure reality vs. plan?
+
+**STOP.** AskUserQuestion once per issue. Recommend + WHY.
+
+### Appendix: Claude Code Skill DX Checklist
+
+**Conditional: only run when product type includes "Claude Code skill".**
+
+This is NOT a scored pass. It's a checklist of proven patterns from gstack's own DX.
+
+Load reference: Read the "## Claude Code Skill DX Checklist" section from
+`~/.claude/skills/gstack/plan-devex-review/dx-hall-of-fame.md`.
+
+Check each item. For any unchecked item, explain what's missing and suggest the fix.
+
+**STOP.** AskUserQuestion for any item that requires a design decision.
+
+{{CODEX_PLAN_REVIEW}}
+
+When constructing the outside voice prompt, include the Developer Persona from Step 0A
+and the Competitive Benchmark from Step 0C. The outside voice should critique the plan
+in the context of who is using it and what they're competing against.
+
+## CRITICAL RULE — How to ask questions
+
+Follow the AskUserQuestion format from the Preamble above. Additional rules for
+DX reviews:
+
+* **One issue = one AskUserQuestion call.** Never combine multiple issues.
+* **Ground every question in evidence.** Reference the persona, competitive benchmark,
+  empathy narrative, or friction trace. Never ask a question in the abstract.
+* **Frame pain from the persona's perspective.** Not "developers would be frustrated"
+  but "[persona from 0A] would hit this at minute [N] of their getting-started flow
+  and [specific consequence: abandon, file an issue, hack a workaround]."
+* Present 2-3 options. For each: effort to fix, impact on developer adoption.
+* **Map to DX First Principles above.** One sentence connecting your recommendation
+  to a specific principle (e.g., "This violates 'zero friction at T0' because
+  [persona] needs 3 extra config steps before their first API call").
+* **Zero findings:** if a section has zero findings, state "No issues, moving on"
+  and proceed. Otherwise, use AskUserQuestion for each gap — a gap with an
+  "obvious fix" is still a gap and still needs user approval before any change
+  lands in the plan.
+* Assume the user hasn't looked at this window in 20 minutes. Re-ground every question.
+
+## Required Outputs
+
+### Developer Persona Card
+The persona card from Step 0A. This goes at the top of the plan's DX section.
+
+### Developer Empathy Narrative
+The first-person narrative from Step 0B, updated with user corrections.
+
+### Competitive DX Benchmark
+The benchmark table from Step 0C, updated with the product's post-review scores.
+
+### Magical Moment Specification
+The chosen delivery vehicle from Step 0D with implementation requirements.
+
+### Developer Journey Map
+The journey map from Step 0F, updated with all friction point resolutions.
+
+### First-Time Developer Confusion Report
+The roleplay report from Step 0G, annotated with which items were addressed.
+
+### "NOT in scope" section
+DX improvements considered and explicitly deferred, with one-line rationale each.
+
+### "What already exists" section
+Existing docs, examples, error handling, and DX patterns that the plan should reuse.
+
+### TODOS.md updates
+After all review passes are complete, present each potential TODO as its own individual
+AskUserQuestion. Never batch. For DX debt: missing error messages, unspecified upgrade
+paths, documentation gaps, missing SDK languages. Each TODO gets:
+* **What:** One-line description
+* **Why:** The concrete developer pain it causes
+* **Pros:** What you gain (adoption, retention, satisfaction)
+* **Cons:** Cost, complexity, or risks
+* **Context:** Enough detail for someone to pick this up in 3 months
+* **Depends on / blocked by:** Prerequisites
+
+Options: **A)** Add to TODOS.md **B)** Skip **C)** Build it now
+
+### DX Scorecard
+
+```
++====================================================================+
+|              DX PLAN REVIEW — SCORECARD                             |
++====================================================================+
+| Dimension            | Score  | Prior  | Trend  |
+|----------------------|--------|--------|--------|
+| Getting Started      | __/10  | __/10  | __ ↑↓  |
+| API/CLI/SDK          | __/10  | __/10  | __ ↑↓  |
+| Error Messages       | __/10  | __/10  | __ ↑↓  |
+| Documentation        | __/10  | __/10  | __ ↑↓  |
+| Upgrade Path         | __/10  | __/10  | __ ↑↓  |
+| Dev Environment      | __/10  | __/10  | __ ↑↓  |
+| Community            | __/10  | __/10  | __ ↑↓  |
+| DX Measurement       | __/10  | __/10  | __ ↑↓  |
++--------------------------------------------------------------------+
+| TTHW                 | __ min | __ min | __ ↑↓  |
+| Competitive Rank     | [Champion/Competitive/Needs Work/Red Flag]   |
+| Magical Moment       | [designed/missing] via [delivery vehicle]    |
+| Product Type         | [type]                                      |
+| Mode                 | [EXPANSION/POLISH/TRIAGE]                    |
+| Overall DX           | __/10  | __/10  | __ ↑↓  |
++====================================================================+
+| DX PRINCIPLE COVERAGE                                               |
+| Zero Friction      | [covered/gap]                                  |
+| Learn by Doing     | [covered/gap]                                  |
+| Fight Uncertainty  | [covered/gap]                                  |
+| Opinionated + Escape Hatches | [covered/gap]                       |
+| Code in Context    | [covered/gap]                                  |
+| Magical Moments    | [covered/gap]                                  |
++====================================================================+
+```
+
+If all passes 8+: "DX plan is solid. Developers will have a good experience."
+If any below 6: Flag as critical DX debt with specific impact on adoption.
+If TTHW > 10 min: Flag as blocking issue.
+
+### DX Implementation Checklist
+
+```
+DX IMPLEMENTATION CHECKLIST
+============================
+[ ] Time to hello world < [target from 0C]
+[ ] Installation is one command
+[ ] First run produces meaningful output
+[ ] Magical moment delivered via [vehicle from 0D]
+[ ] Every error message has: problem + cause + fix + docs link
+[ ] API/CLI naming is guessable without docs
+[ ] Every parameter has a sensible default
+[ ] Docs have copy-paste examples that actually work
+[ ] Examples show real use cases, not just hello world
+[ ] Upgrade path documented with migration guide
+[ ] Breaking changes have deprecation warnings + codemods
+[ ] TypeScript types included (if applicable)
+[ ] Works in CI/CD without special configuration
+[ ] Free tier available, no credit card required
+[ ] Changelog exists and is maintained
+[ ] Search works in documentation
+[ ] Community channel exists and is monitored
+```
+
+{{TASKS_SECTION_EMIT:devex-review}}
+
+### Unresolved Decisions
+If any AskUserQuestion goes unanswered, note here. Never silently default.
+
+{{REVIEW_DASHBOARD}}
+
+{{PLAN_FILE_REVIEW_REPORT}}
+
+{{LEARNINGS_LOG}}
+
+{{GBRAIN_SAVE_RESULTS}}
+
+{{BRAIN_WRITE_BACK}}
+
+{{BRAIN_CACHE_REFRESH}}
+
+## Next Steps — Review Chaining
+
+After displaying the Review Readiness Dashboard, recommend next reviews:
+
+**Recommend /plan-eng-review if eng review is not skipped globally** — DX issues often
+have architectural implications. If this DX review found API design problems, error
+handling gaps, or CLI ergonomics issues, eng review should validate the fixes.
+
+**Suggest /plan-design-review if user-facing UI exists** — DX review focuses on
+developer-facing surfaces; design review covers end-user-facing UI.
+
+**Recommend /devex-review after implementation** — the boomerang. Plan said TTHW would
+be [target from 0C]. Did reality match? Run /devex-review on the live product to find
+out. This is where the competitive benchmark pays off: you have a concrete target to
+measure against.
+
+Use AskUserQuestion with applicable options:
+- **A)** Run /plan-eng-review next (required gate)
+- **B)** Run /plan-design-review (only if UI scope detected)
+- **C)** Ready to implement, run /devex-review after shipping
+- **D)** Skip, I'll handle next steps manually
+
+## Mode Quick Reference
+```
+             | DX EXPANSION     | DX POLISH          | DX TRIAGE
+Scope        | Push UP (opt-in) | Maintain           | Critical only
+Posture      | Enthusiastic     | Rigorous           | Surgical
+Competitive  | Full benchmark   | Full benchmark     | Skip
+Magical      | Full design      | Verify exists      | Skip
+Journey      | All stages +     | All stages         | Install + Hello
+             | best-in-class    |                    | World only
+Passes       | All 8, expanded  | All 8, standard    | Pass 1 + 3 only
+Outside voice| Recommended      | Recommended        | Skip
+```
+
+## Formatting Rules
+
+* NUMBER issues (1, 2, 3...) and LETTERS for options (A, B, C...).
+* Label with NUMBER + LETTER (e.g., "3A", "3B").
+* One sentence max per option.
+* After each pass, pause and wait for feedback before moving on.
+* Rate before and after each pass for scannability.
+

plan-eng-review/SKILL.md

@@ -370,25 +370,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 
@@ -820,6 +807,18 @@ rm -f /tmp/.gstack-brain-context-$$.md 2>/dev/null || true
 `gstack/`, `concepts/` only). Personal/family/therapy content never leaks here.
 
 
+---
+## Section index — Read each section when its situation applies
+
+This skill is a decision-tree skeleton. The steps below point to on-demand
+sections. Read a section in full before doing its step; do not work from memory.
+
+| When | Read this section |
+|------|-------------------|
+| running the 4-section review, outside voice, required outputs, and review report (only after Step 0 scope is agreed) | `sections/review-sections.md` |
+---
+
+
 ## BEFORE YOU START:
 
 ### Design Doc Check
@@ -923,904 +922,12 @@ Always work through the full interactive review: one section at a time (Architec
 
 **Critical: Once the user accepts or rejects a scope reduction recommendation, commit fully.** Do not re-argue for smaller scope during later review sections. Do not silently reduce scope or skip planned components.
 
-## Review Sections (after scope is agreed)
+> **STOP.** Before running the 4-section review, outside voice, required outputs, and review report (only after Step 0 scope is agreed), Read `~/.claude/skills/gstack/plan-eng-review/sections/review-sections.md` and execute it
+> in full. Do not work from memory — that section is the source of truth for this step.
 
-**Anti-skip rule:** Never condense, abbreviate, or skip any review section (1-4) regardless of plan type (strategy, spec, code, infra). Every section in this skill exists for a reason. "This is a strategy doc so implementation sections don't apply" is always wrong — implementation details are where strategy breaks down. If a section genuinely has zero findings, say "No issues found" and move on — but you must evaluate it.
+## Section self-check (before you finish)
 
-**Anti-shortcut clause:** The plan file is the OUTPUT of the interactive review, not a substitute for it. Writing every finding into one plan write and calling ExitPlanMode without firing AskUserQuestion is the precise failure mode of the May 2026 transcript bug — the model explored, found issues, and dumped them into a deliverable rather than walking the user through them. If you have ANY non-trivial finding in any review section, the path from finding to ExitPlanMode goes THROUGH AskUserQuestion. Zero findings in every section is the only path to ExitPlanMode that bypasses AskUserQuestion. If you find yourself wanting to write a plan with findings before asking, stop and call AskUserQuestion now — that's the bug, recognize it.
+Confirm you Read the review section the Section index named, and executed every review section (Architecture, Code Quality, Tests, Performance), the outside voice, and the required outputs in full. If you produced findings or the review report from memory without Reading `sections/review-sections.md`, stop and Read it now.
-
-## Prior Learnings
-
-Search for relevant learnings from previous sessions:
-
-```bash
-_CROSS_PROJ=$(~/.claude/skills/gstack/bin/gstack-config get cross_project_learnings 2>/dev/null || echo "unset")
-echo "CROSS_PROJECT: $_CROSS_PROJ"
-if [ "$_CROSS_PROJ" = "true" ]; then
-  ~/.claude/skills/gstack/bin/gstack-learnings-search --limit 10 --cross-project 2>/dev/null || true
-else
-  ~/.claude/skills/gstack/bin/gstack-learnings-search --limit 10 2>/dev/null || true
-fi
-```
-
-If `CROSS_PROJECT` is `unset` (first time): Use AskUserQuestion:
-
-> gstack can search learnings from your other projects on this machine to find
-> patterns that might apply here. This stays local (no data leaves your machine).
-> Recommended for solo developers. Skip if you work on multiple client codebases
-> where cross-contamination would be a concern.
-
-Options:
-- A) Enable cross-project learnings (recommended)
-- B) Keep learnings project-scoped only
-
-If A: run `~/.claude/skills/gstack/bin/gstack-config set cross_project_learnings true`
-If B: run `~/.claude/skills/gstack/bin/gstack-config set cross_project_learnings false`
-
-Then re-run the search with the appropriate flag.
-
-If learnings are found, incorporate them into your analysis. When a review finding
-matches a past learning, display:
-
-**"Prior learning applied: [key] (confidence N/10, from [date])"**
-
-This makes the compounding visible. The user should see that gstack is getting
-smarter on their codebase over time.
-
-### 1. Architecture review
-Evaluate:
-* Overall system design and component boundaries.
-* Dependency graph and coupling concerns.
-* Data flow patterns and potential bottlenecks.
-* Scaling characteristics and single points of failure.
-* Security architecture (auth, data access, API boundaries).
-* Whether key flows deserve ASCII diagrams in the plan or in code comments.
-* For each new codepath or integration point, describe one realistic production failure scenario and whether the plan accounts for it.
-* **Distribution architecture:** If this introduces a new artifact (binary, package, container), how does it get built, published, and updated? Is the CI/CD pipeline part of the plan or deferred?
-
-For each issue found in this section, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Do NOT batch multiple issues into one AskUserQuestion. Use the preamble's AskUserQuestion Format section. The AskUserQuestion call is a tool_use, not prose — call the tool directly.
-
-**STOP.** Do NOT proceed to the next review section, edit the plan file with the proposed fix, or call ExitPlanMode until the user responds. An issue with an "obvious fix" is still an issue and still needs explicit user approval before it lands in the plan. Loading the AskUserQuestion schema via ToolSearch and then writing the recommendation as chat prose is the failure mode this gate exists to prevent.
-
-## Confidence Calibration
-
-Every finding MUST include a confidence score (1-10):
-
-| Score | Meaning | Display rule |
-|-------|---------|-------------|
-| 9-10 | Verified by reading specific code. Concrete bug or exploit demonstrated. | Show normally |
-| 7-8 | High confidence pattern match. Very likely correct. | Show normally |
-| 5-6 | Moderate. Could be a false positive. | Show with caveat: "Medium confidence, verify this is actually an issue" |
-| 3-4 | Low confidence. Pattern is suspicious but may be fine. | Suppress from main report. Include in appendix only. |
-| 1-2 | Speculation. | Only report if severity would be P0. |
-
-**Finding format:**
-
-\`[SEVERITY] (confidence: N/10) file:line — description\`
-
-Example:
-\`[P1] (confidence: 9/10) app/models/user.rb:42 — SQL injection via string interpolation in where clause\`
-\`[P2] (confidence: 5/10) app/controllers/api/v1/users_controller.rb:18 — Possible N+1 query, verify with production logs\`
-
-### Pre-emit verification gate (#1539 — kills the "field doesn't exist" FP class)
-
-Before any finding is promoted to the report, the gate requires:
-
-1. **Quote the specific code line that motivates the finding** — file:line plus
-   the verbatim text of the line(s) that triggered it. If the finding is "field
-   X doesn't exist on model Y", quote the lines of class Y where the field
-   would live. If "dict.get() might return None", quote the dict initialization.
-   If "race condition between A and B", quote both A and B.
-
-2. **If you cannot quote the motivating line(s), the finding is unverified.**
-   Force its confidence to 4-5 (suppressed from the main report). It still goes
-   into the appendix so reviewers can audit calibration, but the user does NOT
-   see it in the critical-pass output. Do not work around this by inventing
-   speculative confidence 7+ — that defeats the gate.
-
-**Framework-meta nudge:** When the symbol is generated by a framework
-metaclass, descriptor, ORM Meta inner-class, or migration history (Django
-`Meta`, Rails `has_many`/`scope`, SQLAlchemy `relationship`/`Column`,
-TypeORM decorators, Sequelize `init`/`belongsTo`, Prisma generated client),
-quote the meta-construct (the `Meta` block, the migration, the decorator,
-the schema file) instead of expecting the literal name in the class body.
-The verification is "I read the source that creates this symbol", not "I
-grep'd for the name and didn't find it." Deeper framework-aware verification
-(model introspection, migration-history-aware checks, ORM dialect detection)
-is deliberately out of scope for the lighter gate — see the deferred
-`~/.gstack-dev/plans/1539-framework-aware-review.md` design doc.
-
-The FP classes the gate kills (measured against Django Sprint 2.5 #1539):
-
-| FP class | Why the gate catches it |
-|---|---|
-| "field doesn't exist on model" | Requires quoting the model class body or Meta; the field's absence becomes obvious |
-| "dict.get() might be None" | Requires quoting the dict initialization (e.g. Django form's `cleaned_data` is `{}`-initialized) |
-| "save() might lose fields" | Requires quoting the ORM signature or model definition |
-| "update_fields might miss X" | Requires quoting the field set; if X doesn't exist, the FP is self-evident |
-
-**Calibration learning:** If you report a finding with confidence < 7 and the user
-confirms it IS a real issue, that is a calibration event. Your initial confidence was
-too low. Log the corrected pattern as a learning so future reviews catch it with
-higher confidence.
-
-### 2. Code quality review
-Evaluate:
-* Code organization and module structure.
-* DRY violations—be aggressive here.
-* Error handling patterns and missing edge cases (call these out explicitly).
-* Technical debt hotspots.
-* Areas that are over-engineered or under-engineered relative to my preferences.
-* Existing ASCII diagrams in touched files — are they still accurate after this change?
-
-For each issue found in this section, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Do NOT batch multiple issues into one AskUserQuestion. Use the preamble's AskUserQuestion Format section. The AskUserQuestion call is a tool_use, not prose — call the tool directly.
-
-**STOP.** Do NOT proceed to the next review section, edit the plan file with the proposed fix, or call ExitPlanMode until the user responds. An issue with an "obvious fix" is still an issue and still needs explicit user approval before it lands in the plan. Loading the AskUserQuestion schema via ToolSearch and then writing the recommendation as chat prose is the failure mode this gate exists to prevent.
-
-### 3. Test review
-
-100% coverage is the goal. Evaluate every codepath in the plan and ensure the plan includes tests for each one. If the plan is missing tests, add them — the plan should be complete enough that implementation includes full test coverage from the start.
-
-### Test Framework Detection
-
-Before analyzing coverage, detect the project's test framework:
-
-1. **Read CLAUDE.md** — look for a `## Testing` section with test command and framework name. If found, use that as the authoritative source.
-2. **If CLAUDE.md has no testing section, auto-detect:**
-
-```bash
-setopt +o nomatch 2>/dev/null || true  # zsh compat
-# Detect project runtime
-[ -f Gemfile ] && echo "RUNTIME:ruby"
-[ -f package.json ] && echo "RUNTIME:node"
-[ -f requirements.txt ] || [ -f pyproject.toml ] && echo "RUNTIME:python"
-[ -f go.mod ] && echo "RUNTIME:go"
-[ -f Cargo.toml ] && echo "RUNTIME:rust"
-# Check for existing test infrastructure
-ls jest.config.* vitest.config.* playwright.config.* cypress.config.* .rspec pytest.ini phpunit.xml 2>/dev/null
-ls -d test/ tests/ spec/ __tests__/ cypress/ e2e/ 2>/dev/null
-```
-
-3. **If no framework detected:** still produce the coverage diagram, but skip test generation.
-
-**Step 1. Trace every codepath in the plan:**
-
-Read the plan document. For each new feature, service, endpoint, or component described, trace how data will flow through the code — don't just list planned functions, actually follow the planned execution:
-
-1. **Read the plan.** For each planned component, understand what it does and how it connects to existing code.
-2. **Trace data flow.** Starting from each entry point (route handler, exported function, event listener, component render), follow the data through every branch:
-   - Where does input come from? (request params, props, database, API call)
-   - What transforms it? (validation, mapping, computation)
-   - Where does it go? (database write, API response, rendered output, side effect)
-   - What can go wrong at each step? (null/undefined, invalid input, network failure, empty collection)
-3. **Diagram the execution.** For each changed file, draw an ASCII diagram showing:
-   - Every function/method that was added or modified
-   - Every conditional branch (if/else, switch, ternary, guard clause, early return)
-   - Every error path (try/catch, rescue, error boundary, fallback)
-   - Every call to another function (trace into it — does IT have untested branches?)
-   - Every edge: what happens with null input? Empty array? Invalid type?
-
-This is the critical step — you're building a map of every line of code that can execute differently based on input. Every branch in this diagram needs a test.
-
-**Step 2. Map user flows, interactions, and error states:**
-
-Code coverage isn't enough — you need to cover how real users interact with the changed code. For each changed feature, think through:
-
-- **User flows:** What sequence of actions does a user take that touches this code? Map the full journey (e.g., "user clicks 'Pay' → form validates → API call → success/failure screen"). Each step in the journey needs a test.
-- **Interaction edge cases:** What happens when the user does something unexpected?
-  - Double-click/rapid resubmit
-  - Navigate away mid-operation (back button, close tab, click another link)
-  - Submit with stale data (page sat open for 30 minutes, session expired)
-  - Slow connection (API takes 10 seconds — what does the user see?)
-  - Concurrent actions (two tabs, same form)
-- **Error states the user can see:** For every error the code handles, what does the user actually experience?
-  - Is there a clear error message or a silent failure?
-  - Can the user recover (retry, go back, fix input) or are they stuck?
-  - What happens with no network? With a 500 from the API? With invalid data from the server?
-- **Empty/zero/boundary states:** What does the UI show with zero results? With 10,000 results? With a single character input? With maximum-length input?
-
-Add these to your diagram alongside the code branches. A user flow with no test is just as much a gap as an untested if/else.
-
-**Step 3. Check each branch against existing tests:**
-
-Go through your diagram branch by branch — both code paths AND user flows. For each one, search for a test that exercises it:
-- Function `processPayment()` → look for `billing.test.ts`, `billing.spec.ts`, `test/billing_test.rb`
-- An if/else → look for tests covering BOTH the true AND false path
-- An error handler → look for a test that triggers that specific error condition
-- A call to `helperFn()` that has its own branches → those branches need tests too
-- A user flow → look for an integration or E2E test that walks through the journey
-- An interaction edge case → look for a test that simulates the unexpected action
-
-Quality scoring rubric:
-- ★★★  Tests behavior with edge cases AND error paths
-- ★★   Tests correct behavior, happy path only
-- ★    Smoke test / existence check / trivial assertion (e.g., "it renders", "it doesn't throw")
-
-### E2E Test Decision Matrix
-
-When checking each branch, also determine whether a unit test or E2E/integration test is the right tool:
-
-**RECOMMEND E2E (mark as [→E2E] in the diagram):**
-- Common user flow spanning 3+ components/services (e.g., signup → verify email → first login)
-- Integration point where mocking hides real failures (e.g., API → queue → worker → DB)
-- Auth/payment/data-destruction flows — too important to trust unit tests alone
-
-**RECOMMEND EVAL (mark as [→EVAL] in the diagram):**
-- Critical LLM call that needs a quality eval (e.g., prompt change → test output still meets quality bar)
-- Changes to prompt templates, system instructions, or tool definitions
-
-**STICK WITH UNIT TESTS:**
-- Pure function with clear inputs/outputs
-- Internal helper with no side effects
-- Edge case of a single function (null input, empty array)
-- Obscure/rare flow that isn't customer-facing
-
-### REGRESSION RULE (mandatory)
-
-**IRON RULE:** When the coverage audit identifies a REGRESSION — code that previously worked but the diff broke — a regression test is added to the plan as a critical requirement. No AskUserQuestion. No skipping. Regressions are the highest-priority test because they prove something broke.
-
-A regression is when:
-- The diff modifies existing behavior (not new code)
-- The existing test suite (if any) doesn't cover the changed path
-- The change introduces a new failure mode for existing callers
-
-When uncertain whether a change is a regression, err on the side of writing the test.
-
-**Step 4. Output ASCII coverage diagram:**
-
-Include BOTH code paths and user flows in the same diagram. Mark E2E-worthy and eval-worthy paths:
-
-```
-CODE PATHS                                            USER FLOWS
-[+] src/services/billing.ts                           [+] Payment checkout
-  ├── processPayment()                                  ├── [★★★ TESTED] Complete purchase — checkout.e2e.ts:15
-  │   ├── [★★★ TESTED] happy + declined + timeout      ├── [GAP] [→E2E] Double-click submit
-  │   ├── [GAP]         Network timeout                 └── [GAP]        Navigate away mid-payment
-  │   └── [GAP]         Invalid currency
-  └── refundPayment()                                 [+] Error states
-      ├── [★★  TESTED] Full refund — :89                ├── [★★  TESTED] Card declined message
-      └── [★   TESTED] Partial (non-throw only) — :101  └── [GAP]        Network timeout UX
-
-LLM integration: [GAP] [→EVAL] Prompt template change — needs eval test
-
-COVERAGE: 5/13 paths tested (38%)  |  Code paths: 3/5 (60%)  |  User flows: 2/8 (25%)
-QUALITY: ★★★:2 ★★:2 ★:1  |  GAPS: 8 (2 E2E, 1 eval)
-```
-
-Legend: ★★★ behavior + edge + error  |  ★★ happy path  |  ★ smoke check
-[→E2E] = needs integration test  |  [→EVAL] = needs LLM eval
-
-**Fast path:** All paths covered → "Test review: All new code paths have test coverage ✓" Continue.
-
-**Step 5. Add missing tests to the plan:**
-
-For each GAP identified in the diagram, add a test requirement to the plan. Be specific:
-- What test file to create (match existing naming conventions)
-- What the test should assert (specific inputs → expected outputs/behavior)
-- Whether it's a unit test, E2E test, or eval (use the decision matrix)
-- For regressions: flag as **CRITICAL** and explain what broke
-
-The plan should be complete enough that when implementation begins, every test is written alongside the feature code — not deferred to a follow-up.
-
-### Test Plan Artifact
-
-After producing the coverage diagram, write a test plan artifact to the project directory so `/qa` and `/qa-only` can consume it as primary test input:
-
-```bash
-eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" && mkdir -p ~/.gstack/projects/$SLUG
-USER=$(whoami)
-DATETIME=$(date +%Y%m%d-%H%M%S)
-```
-
-Write to `~/.gstack/projects/{slug}/{user}-{branch}-eng-review-test-plan-{datetime}.md`:
-
-```markdown
-# Test Plan
-Generated by /plan-eng-review on {date}
-Branch: {branch}
-Repo: {owner/repo}
-
-## Affected Pages/Routes
-- {URL path} — {what to test and why}
-
-## Key Interactions to Verify
-- {interaction description} on {page}
-
-## Edge Cases
-- {edge case} on {page}
-
-## Critical Paths
-- {end-to-end flow that must work}
-```
-
-This file is consumed by `/qa` and `/qa-only` as primary test input. Include only the information that helps a QA tester know **what to test and where** — not implementation details.
-
-For LLM/prompt changes: check the "Prompt/LLM changes" file patterns listed in CLAUDE.md. If this plan touches ANY of those patterns, state which eval suites must be run, which cases should be added, and what baselines to compare against. Then use AskUserQuestion to confirm the eval scope with the user.
-
-For each issue found in this section, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Do NOT batch multiple issues into one AskUserQuestion. Use the preamble's AskUserQuestion Format section. The AskUserQuestion call is a tool_use, not prose — call the tool directly.
-
-**STOP.** Do NOT proceed to the next review section, edit the plan file with the proposed fix, or call ExitPlanMode until the user responds. An issue with an "obvious fix" is still an issue and still needs explicit user approval before it lands in the plan. Loading the AskUserQuestion schema via ToolSearch and then writing the recommendation as chat prose is the failure mode this gate exists to prevent.
-
-### 4. Performance review
-Evaluate:
-* N+1 queries and database access patterns.
-* Memory-usage concerns.
-* Caching opportunities.
-* Slow or high-complexity code paths.
-
-For each issue found in this section, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Do NOT batch multiple issues into one AskUserQuestion. Use the preamble's AskUserQuestion Format section. The AskUserQuestion call is a tool_use, not prose — call the tool directly.
-
-**STOP.** Do NOT proceed to the next review section, edit the plan file with the proposed fix, or call ExitPlanMode until the user responds. An issue with an "obvious fix" is still an issue and still needs explicit user approval before it lands in the plan. Loading the AskUserQuestion schema via ToolSearch and then writing the recommendation as chat prose is the failure mode this gate exists to prevent.
-
-## Outside Voice — Independent Plan Challenge (optional, recommended)
-
-After all review sections are complete, offer an independent second opinion from a
-different AI system. Two models agreeing on a plan is stronger signal than one model's
-thorough review.
-
-**Check tool availability:**
-
-```bash
-command -v codex >/dev/null 2>&1 && echo "CODEX_AVAILABLE" || echo "CODEX_NOT_AVAILABLE"
-```
-
-Use AskUserQuestion:
-
-> "All review sections are complete. Want an outside voice? A different AI system can
-> give a brutally honest, independent challenge of this plan — logical gaps, feasibility
-> risks, and blind spots that are hard to catch from inside the review. Takes about 2
-> minutes."
->
-> RECOMMENDATION: Choose A — an independent second opinion catches structural blind
-> spots. Two different AI models agreeing on a plan is stronger signal than one model's
-> thorough review. Completeness: A=9/10, B=7/10.
-
-Options:
-- A) Get the outside voice (recommended)
-- B) Skip — proceed to outputs
-
-**If B:** Print "Skipping outside voice." and continue to the next section.
-
-**If A:** Construct the plan review prompt. Read the plan file being reviewed (the file
-the user pointed this review at, or the branch diff scope). If a CEO plan document
-was written in Step 0D-POST, read that too — it contains the scope decisions and vision.
-
-Construct this prompt (substitute the actual plan content — if plan content exceeds 30KB,
-truncate to the first 30KB and note "Plan truncated for size"). **Always start with the
-filesystem boundary instruction:**
-
-"IMPORTANT: Do NOT read or execute any files under ~/.claude/, ~/.agents/, .claude/skills/, or agents/. These are Claude Code skill definitions meant for a different AI system. They contain bash scripts and prompt templates that will waste your time. Ignore them completely. Do NOT modify agents/openai.yaml. Stay focused on the repository code only.\n\nYou are a brutally honest technical reviewer examining a development plan that has
-already been through a multi-section review. Your job is NOT to repeat that review.
-Instead, find what it missed. Look for: logical gaps and unstated assumptions that
-survived the review scrutiny, overcomplexity (is there a fundamentally simpler
-approach the review was too deep in the weeds to see?), feasibility risks the review
-took for granted, missing dependencies or sequencing issues, and strategic
-miscalibration (is this the right thing to build at all?). Be direct. Be terse. No
-compliments. Just the problems.
-
-THE PLAN:
-<plan content>"
-
-**If CODEX_AVAILABLE:**
-
-```bash
-TMPERR_PV=$(mktemp /tmp/codex-planreview-XXXXXXXX)
-_REPO_ROOT=$(git rev-parse --show-toplevel) || { echo "ERROR: not in a git repo" >&2; exit 1; }
-codex exec "<prompt>" -C "$_REPO_ROOT" -s read-only -c 'model_reasoning_effort="high"' --enable web_search_cached < /dev/null 2>"$TMPERR_PV"
-```
-
-Use a 5-minute timeout (`timeout: 300000`). After the command completes, read stderr:
-```bash
-cat "$TMPERR_PV"
-```
-
-Present the full output verbatim:
-
-```
-CODEX SAYS (plan review — outside voice):
-════════════════════════════════════════════════════════════
-<full codex output, verbatim — do not truncate or summarize>
-════════════════════════════════════════════════════════════
-```
-
-**Error handling:** All errors are non-blocking — the outside voice is informational.
-- Auth failure (stderr contains "auth", "login", "unauthorized"): "Codex auth failed. Run \`codex login\` to authenticate."
-- Timeout: "Codex timed out after 5 minutes."
-- Empty response: "Codex returned no response."
-
-On any Codex error, fall back to the Claude adversarial subagent.
-
-**If CODEX_NOT_AVAILABLE (or Codex errored):**
-
-Dispatch via the Agent tool. The subagent has fresh context — genuine independence.
-
-Subagent prompt: same plan review prompt as above.
-
-Present findings under an `OUTSIDE VOICE (Claude subagent):` header.
-
-If the subagent fails or times out: "Outside voice unavailable. Continuing to outputs."
-
-**Cross-model tension:**
-
-After presenting the outside voice findings, note any points where the outside voice
-disagrees with the review findings from earlier sections. Flag these as:
-
-```
-CROSS-MODEL TENSION:
-  [Topic]: Review said X. Outside voice says Y. [Present both perspectives neutrally.
-  State what context you might be missing that would change the answer.]
-```
-
-**User Sovereignty:** Do NOT auto-incorporate outside voice recommendations into the plan.
-Present each tension point to the user. The user decides. Cross-model agreement is a
-strong signal — present it as such — but it is NOT permission to act. You may state
-which argument you find more compelling, but you MUST NOT apply the change without
-explicit user approval.
-
-For each substantive tension point, use AskUserQuestion:
-
-> "Cross-model disagreement on [topic]. The review found [X] but the outside voice
-> argues [Y]. [One sentence on what context you might be missing.]"
->
-> RECOMMENDATION: Choose [A or B] because [one-line reason explaining which argument
-> is more compelling and why]. Completeness: A=X/10, B=Y/10.
-
-Options:
-- A) Accept the outside voice's recommendation (I'll apply this change)
-- B) Keep the current approach (reject the outside voice)
-- C) Investigate further before deciding
-- D) Add to TODOS.md for later
-
-Wait for the user's response. Do NOT default to accepting because you agree with the
-outside voice. If the user chooses B, the current approach stands — do not re-argue.
-
-If no tension points exist, note: "No cross-model tension — both reviewers agree."
-
-**Persist the result:**
-```bash
-~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"codex-plan-review","timestamp":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'","status":"STATUS","source":"SOURCE","commit":"'"$(git rev-parse --short HEAD)"'"}'
-```
-
-Substitute: STATUS = "clean" if no findings, "issues_found" if findings exist.
-SOURCE = "codex" if Codex ran, "claude" if subagent ran.
-
-**Cleanup:** Run `rm -f "$TMPERR_PV"` after processing (if Codex was used).
-
----
-
-### Outside Voice Integration Rule
-
-Outside voice findings are INFORMATIONAL until the user explicitly approves each one.
-Do NOT incorporate outside voice recommendations into the plan without presenting each
-finding via AskUserQuestion and getting explicit approval. This applies even when you
-agree with the outside voice. Cross-model consensus is a strong signal — present it as
-such — but the user makes the decision.
-
-## CRITICAL RULE — How to ask questions
-Follow the AskUserQuestion format from the Preamble above. Additional rules for plan reviews:
-* **One issue = one AskUserQuestion call.** Never combine multiple issues into one question.
-* Describe the problem concretely, with file and line references.
-* Present 2-3 options, including "do nothing" where that's reasonable.
-* For each option, specify in one line: effort (human: ~X / CC: ~Y), risk, and maintenance burden. If the complete option is only marginally more effort than the shortcut with CC, recommend the complete option.
-* **Map the reasoning to my engineering preferences above.** One sentence connecting your recommendation to a specific preference (DRY, explicit > clever, minimal diff, etc.).
-* Label with issue NUMBER + option LETTER (e.g., "3A", "3B").
-* **Coverage vs kind:** for every per-issue AskUserQuestion you raise in this review, decide whether the options differ in coverage or in kind. If coverage (e.g., more tests vs fewer, complete error handling vs happy-path-only, full edge-case coverage vs shortcut), include `Completeness: N/10` on each option. If kind (e.g., architectural choice between two different systems, posture-over-posture, A/B/C where each is a different kind of thing), skip the score and add one line: `Note: options differ in kind, not coverage — no completeness score.` Do NOT fabricate scores on kind-differentiated questions — filler scores are worse than no score.
-* **Zero findings:** if a section has zero findings, state "No issues, moving on" and proceed. Otherwise, use AskUserQuestion for each finding — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan.
-
-## Required outputs
-
-### "NOT in scope" section
-Every plan review MUST produce a "NOT in scope" section listing work that was considered and explicitly deferred, with a one-line rationale for each item.
-
-### "What already exists" section
-List existing code/flows that already partially solve sub-problems in this plan, and whether the plan reuses them or unnecessarily rebuilds them.
-
-### TODOS.md updates
-After all review sections are complete, present each potential TODO as its own individual AskUserQuestion. Never batch TODOs — one per question. Never silently skip this step. Follow the format in `.claude/skills/review/TODOS-format.md`.
-
-For each TODO, describe:
-* **What:** One-line description of the work.
-* **Why:** The concrete problem it solves or value it unlocks.
-* **Pros:** What you gain by doing this work.
-* **Cons:** Cost, complexity, or risks of doing it.
-* **Context:** Enough detail that someone picking this up in 3 months understands the motivation, the current state, and where to start.
-* **Depends on / blocked by:** Any prerequisites or ordering constraints.
-
-Then present options: **A)** Add to TODOS.md **B)** Skip — not valuable enough **C)** Build it now in this PR instead of deferring.
-
-Do NOT just append vague bullet points. A TODO without context is worse than no TODO — it creates false confidence that the idea was captured while actually losing the reasoning.
-
-### Diagrams
-The plan itself should use ASCII diagrams for any non-trivial data flow, state machine, or processing pipeline. Additionally, identify which files in the implementation should get inline ASCII diagram comments — particularly Models with complex state transitions, Services with multi-step pipelines, and Concerns with non-obvious mixin behavior.
-
-### Failure modes
-For each new codepath identified in the test review diagram, list one realistic way it could fail in production (timeout, nil reference, race condition, stale data, etc.) and whether:
-1. A test covers that failure
-2. Error handling exists for it
-3. The user would 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
-
-Analyze the plan's implementation steps for parallel execution opportunities. This helps the user split work across git worktrees (via Claude Code's Agent tool with `isolation: "worktree"` or parallel workspaces).
-
-**Skip if:** all steps touch the same primary module, or the plan has fewer than 2 independent workstreams. In that case, write: "Sequential implementation, no parallelization opportunity."
-
-**Otherwise, produce:**
-
-1. **Dependency table** — for each implementation step/workstream:
-
-| Step | Modules touched | Depends on |
-|------|----------------|------------|
-| (step name) | (directories/modules, NOT specific files) | (other steps, or —) |
-
-Work at the module/directory level, not file level. Plans describe intent ("add API endpoints"), not specific files. Module-level ("controllers/, models/") is reliable; file-level is guesswork.
-
-2. **Parallel lanes** — group steps into lanes:
-   - Steps with no shared modules and no dependency go in separate lanes (parallel)
-   - Steps sharing a module directory go in the same lane (sequential)
-   - Steps depending on other steps go in later lanes
-
-Format: `Lane A: step1 → step2 (sequential, shared models/)` / `Lane B: step3 (independent)`
-
-3. **Execution order** — which lanes launch in parallel, which wait. Example: "Launch A + B in parallel worktrees. Merge both. Then C."
-
-4. **Conflict flags** — if two parallel lanes touch the same module directory, flag it: "Lanes X and Y both touch module/ — potential merge conflict. Consider sequential execution or careful coordination."
-
-## Implementation Tasks
-
-Before closing this review, synthesize the findings above into a flat list of
-build-actionable tasks. Each task derives from a specific finding — no padding.
-Emit the markdown section AND write a JSONL artifact that `/autoplan` can
-aggregate across phases.
-
-### Markdown section (always emit)
-
-```markdown
-## Implementation Tasks
-Synthesized from this review's findings. Each task derives from a specific
-finding above. Run with Claude Code or Codex; checkbox as you ship.
-
-- [ ] **T1 (P1, human: ~2h / CC: ~15min)** — <component> — <imperative title>
-  - Surfaced by: <section name> — <specific finding text or line reference>
-  - Files: <paths to touch>
-  - Verify: <test command or manual check>
-- [ ] **T2 (P2, human: ~30min / CC: ~5min)** — ...
-```
-
-Rules:
-- P1 blocks ship; P2 should land same branch; P3 is a follow-up TODO.
-- If a finding produced no actionable task, do not invent one.
-- If a section had zero findings, emit `_No new tasks from <section>._`
-- Effort uses the AI-compression table from CLAUDE.md.
-
-### JSONL artifact (always write, even if zero tasks)
-
-`/autoplan` reads this file to aggregate across phases. Build each line with
-`jq -nc` so titles and source findings containing quotes, newlines, or
-backslashes serialize cleanly — never use hand-rolled `echo` / `printf`.
-
-```bash
-eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)"
-TASKS_DIR="${HOME}/.gstack/projects/${SLUG:-unknown}"
-mkdir -p "$TASKS_DIR"
-TASKS_FILE="$TASKS_DIR/tasks-eng-review-$(date +%Y%m%d-%H%M%S).jsonl"
-COMMIT=$(git rev-parse HEAD 2>/dev/null || echo unknown)
-BRANCH=$(git branch --show-current 2>/dev/null || echo unknown)
-RUN_ID="$(date -u +%Y%m%dT%H%M%SZ)-$$"
-
-# Repeat ONE jq invocation per task identified during this review.
-# Substitute the placeholders inline with shell variables you set per task:
-#   TASK_ID (T1, T2, ...), PRIORITY (P1/P2/P3), COMPONENT, TITLE,
-#   SOURCE_FINDING, EFFORT_HUMAN, EFFORT_CC, FILES_JSON (a JSON array literal
-#   like '["browse/src/sanitize.ts","browse/src/server.ts"]').
-jq -nc \
-  --arg phase 'eng-review' \
-  --arg run_id "$RUN_ID" \
-  --arg branch "$BRANCH" \
-  --arg commit "$COMMIT" \
-  --arg id "$TASK_ID" \
-  --arg priority "$PRIORITY" \
-  --arg component "$COMPONENT" \
-  --arg effort_human "$EFFORT_HUMAN" \
-  --arg effort_cc "$EFFORT_CC" \
-  --arg title "$TITLE" \
-  --arg source_finding "$SOURCE_FINDING" \
-  --argjson files "$FILES_JSON" \
-  '{phase:$phase, run_id:$run_id, branch:$branch, commit:$commit, id:$id, priority:$priority, component:$component, files:$files, effort_human:$effort_human, effort_cc:$effort_cc, title:$title, source_finding:$source_finding}' \
-  >> "$TASKS_FILE"
-```
-
-If `jq` is not installed, fall back to skipping the JSONL write and warn
-the user to install jq for autoplan aggregation. Never hand-roll JSONL.
-
-If zero tasks were identified in this review, still touch the JSONL file
-(`: > "$TASKS_FILE"`) so the aggregator sees that the phase produced output
-this run (an empty file means "ran, no findings" — distinct from "didn't run").
-
-
-### Completion summary
-At the end of the review, fill in and display this summary so the user can see all findings at a glance:
-- 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
-- Outside voice: ran (codex/claude) / skipped
-- Parallelization: ___ lanes, ___ parallel / ___ sequential
-- Lake Score: X/Y recommendations chose complete option
-
-## Retrospective learning
-Check the git log for this branch. If there are prior commits suggesting a previous review cycle (e.g., review-driven refactors, reverted changes), note what was changed and whether the current plan touches the same areas. Be more aggressive reviewing areas that were previously problematic.
-
-## Formatting rules
-* NUMBER issues (1, 2, 3...) and LETTERS for options (A, B, C...).
-* Label with NUMBER + LETTER (e.g., "3A", "3B").
-* One sentence max per option. Pick in under 5 seconds.
-* After each review section, pause and ask for feedback before moving on.
-
-## Review Log
-
-After producing the Completion Summary above, persist the review result.
-
-**PLAN MODE EXCEPTION — ALWAYS RUN:** This command writes review metadata to
-`~/.gstack/` (user config directory, not project files). The skill preamble
-already writes to `~/.gstack/sessions/` and `~/.gstack/analytics/` — this is
-the same pattern. The review dashboard depends on this data. Skipping this
-command breaks the review readiness dashboard in /ship.
-
-```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"}'
-```
-
-Substitute values from the Completion Summary:
-- **TIMESTAMP**: current ISO 8601 datetime
-- **STATUS**: "clean" if 0 unresolved decisions AND 0 critical gaps; otherwise "issues_open"
-- **unresolved**: number from "Unresolved decisions" count
-- **critical_gaps**: number from "Failure modes: ___ critical gaps flagged"
-- **issues_found**: total issues found across all review sections (Architecture + Code Quality + Performance + Test gaps)
-- **MODE**: FULL_REVIEW / SCOPE_REDUCED
-- **COMMIT**: output of `git rev-parse --short HEAD`
-
-## Review Readiness Dashboard
-
-After completing the review, read the review log and config to display the dashboard.
-
-```bash
-~/.claude/skills/gstack/bin/gstack-review-read
-```
-
-Parse the output. Find the most recent entry for each skill (plan-ceo-review, plan-eng-review, review, plan-design-review, design-review-lite, adversarial-review, codex-review, codex-plan-review). Ignore entries with timestamps older than 7 days. For the Eng Review row, show whichever is more recent between `review` (diff-scoped pre-landing review) and `plan-eng-review` (plan-stage architecture review). Append "(DIFF)" or "(PLAN)" to the status to distinguish. For the Adversarial row, show whichever is more recent between `adversarial-review` (new auto-scaled) and `codex-review` (legacy). For Design Review, show whichever is more recent between `plan-design-review` (full visual audit) and `design-review-lite` (code-level check). Append "(FULL)" or "(LITE)" to the status to distinguish. For the Outside Voice row, show the most recent `codex-plan-review` entry — this captures outside voices from both /plan-ceo-review and /plan-eng-review.
-
-**Source attribution:** If the most recent entry for a skill has a \`"via"\` field, append it to the status label in parentheses. Examples: `plan-eng-review` with `via:"autoplan"` shows as "CLEAR (PLAN via /autoplan)". `review` with `via:"ship"` shows as "CLEAR (DIFF via /ship)". Entries without a `via` field show as "CLEAR (PLAN)" or "CLEAR (DIFF)" as before.
-
-Note: `autoplan-voices` and `design-outside-voices` entries are audit-trail-only (forensic data for cross-model consensus analysis). They do not appear in the dashboard and are not checked by any consumer.
-
-Display:
-
-```
-+====================================================================+
-|                    REVIEW READINESS DASHBOARD                       |
-+====================================================================+
-| Review          | Runs | Last Run            | Status    | Required |
-|-----------------|------|---------------------|-----------|----------|
-| Eng Review      |  1   | 2026-03-16 15:00    | CLEAR     | YES      |
-| CEO Review      |  0   | —                   | —         | no       |
-| Design Review   |  0   | —                   | —         | no       |
-| Adversarial     |  0   | —                   | —         | no       |
-| Outside Voice   |  0   | —                   | —         | no       |
-+--------------------------------------------------------------------+
-| VERDICT: CLEARED — Eng Review passed                                |
-+====================================================================+
-```
-
-**Review tiers:**
-- **Eng Review (required by default):** The only review that gates shipping. Covers architecture, code quality, tests, performance. Can be disabled globally with \`gstack-config set skip_eng_review true\` (the "don't bother me" setting).
-- **CEO Review (optional):** Use your judgment. Recommend it for big product/business changes, new user-facing features, or scope decisions. Skip for bug fixes, refactors, infra, and cleanup.
-- **Design Review (optional):** Use your judgment. Recommend it for UI/UX changes. Skip for backend-only, infra, or prompt-only changes.
-- **Adversarial Review (automatic):** Always-on for every review. Every diff gets both Claude adversarial subagent and Codex adversarial challenge. Large diffs (200+ lines) additionally get Codex structured review with P1 gate. No configuration needed.
-- **Outside Voice (optional):** Independent plan review from a different AI model. Offered after all review sections complete in /plan-ceo-review and /plan-eng-review. Falls back to Claude subagent if Codex is unavailable. Never gates shipping.
-
-**Verdict logic:**
-- **CLEARED**: Eng Review has >= 1 entry within 7 days from either \`review\` or \`plan-eng-review\` with status "clean" (or \`skip_eng_review\` is \`true\`)
-- **NOT CLEARED**: Eng Review missing, stale (>7 days), or has open issues
-- CEO, Design, and Codex reviews are shown for context but never block shipping
-- If \`skip_eng_review\` config is \`true\`, Eng Review shows "SKIPPED (global)" and verdict is CLEARED
-
-**Staleness detection:** After displaying the dashboard, check if any existing reviews may be stale:
-- Parse the \`---HEAD---\` section from the bash output to get the current HEAD commit hash
-- For each review entry that has a \`commit\` field: compare it against the current HEAD. If different, count elapsed commits: \`git rev-list --count STORED_COMMIT..HEAD\`. Display: "Note: {skill} review from {date} may be stale — {N} commits since review"
-- For entries without a \`commit\` field (legacy entries): display "Note: {skill} review from {date} has no commit tracking — consider re-running for accurate staleness detection"
-- If all reviews match the current HEAD, do not display any staleness notes
-
-## Plan File Review Report
-
-After displaying the Review Readiness Dashboard in conversation output, also update the
-**plan file** itself so review status is visible to anyone reading the plan.
-
-### Detect the plan file
-
-1. Check if there is an active plan file in this conversation (the host provides plan file
-   paths in system messages — look for plan file references in the conversation context).
-2. If not found, skip this section silently — not every review runs in plan mode.
-
-### Generate the report
-
-Read the review log output you already have from the Review Readiness Dashboard step above.
-Parse each JSONL entry. Each skill logs different fields:
-
-- **plan-ceo-review**: \`status\`, \`unresolved\`, \`critical_gaps\`, \`mode\`, \`scope_proposed\`, \`scope_accepted\`, \`scope_deferred\`, \`commit\`
-  → Findings: "{scope_proposed} proposals, {scope_accepted} accepted, {scope_deferred} deferred"
-  → If scope fields are 0 or missing (HOLD/REDUCTION mode): "mode: {mode}, {critical_gaps} critical gaps"
-- **plan-eng-review**: \`status\`, \`unresolved\`, \`critical_gaps\`, \`issues_found\`, \`mode\`, \`commit\`
-  → Findings: "{issues_found} issues, {critical_gaps} critical gaps"
-- **plan-design-review**: \`status\`, \`initial_score\`, \`overall_score\`, \`unresolved\`, \`decisions_made\`, \`commit\`
-  → Findings: "score: {initial_score}/10 → {overall_score}/10, {decisions_made} decisions"
-- **plan-devex-review**: \`status\`, \`initial_score\`, \`overall_score\`, \`product_type\`, \`tthw_current\`, \`tthw_target\`, \`mode\`, \`persona\`, \`competitive_tier\`, \`unresolved\`, \`commit\`
-  → Findings: "score: {initial_score}/10 → {overall_score}/10, TTHW: {tthw_current} → {tthw_target}"
-- **devex-review**: \`status\`, \`overall_score\`, \`product_type\`, \`tthw_measured\`, \`dimensions_tested\`, \`dimensions_inferred\`, \`boomerang\`, \`commit\`
-  → Findings: "score: {overall_score}/10, TTHW: {tthw_measured}, {dimensions_tested} tested/{dimensions_inferred} inferred"
-- **codex-review**: \`status\`, \`gate\`, \`findings\`, \`findings_fixed\`
-  → Findings: "{findings} findings, {findings_fixed}/{findings} fixed"
-
-All fields needed for the Findings column are now present in the JSONL entries.
-For the review you just completed, you may use richer details from your own Completion
-Summary. For prior reviews, use the JSONL fields directly — they contain all required data.
-
-Produce this markdown table:
-
-\`\`\`markdown
-## GSTACK REVIEW REPORT
-
-| Review | Trigger | Why | Runs | Status | Findings |
-|--------|---------|-----|------|--------|----------|
-| CEO Review | \`/plan-ceo-review\` | Scope & strategy | {runs} | {status} | {findings} |
-| Codex Review | \`/codex review\` | Independent 2nd opinion | {runs} | {status} | {findings} |
-| Eng Review | \`/plan-eng-review\` | Architecture & tests (required) | {runs} | {status} | {findings} |
-| Design Review | \`/plan-design-review\` | UI/UX gaps | {runs} | {status} | {findings} |
-| DX Review | \`/plan-devex-review\` | Developer experience gaps | {runs} | {status} | {findings} |
-\`\`\`
-
-Below the table, add these lines (omit any that are empty/not applicable):
-
-- **CODEX:** (only if codex-review ran) — one-line summary of codex fixes
-- **CROSS-MODEL:** (only if both Claude and Codex reviews exist) — overlap analysis
-- **UNRESOLVED:** total unresolved decisions across all reviews
-- **VERDICT:** list reviews that are CLEAR (e.g., "CEO + ENG CLEARED — ready to implement").
-  If Eng Review is not CLEAR and not skipped globally, append "eng review required".
-
-### Write to the plan file
-
-**PLAN MODE EXCEPTION — ALWAYS RUN:** This writes to the plan file, which is the one
-file you are allowed to edit in plan mode. The plan file review report is part of the
-plan's living status.
-
-The report must always be the LAST section of the plan file — never mid-file.
-Use a single delete-then-append flow:
-
-1. Read the plan file (Read tool) to see its full current content. Search the read
-   output for a \`## GSTACK REVIEW REPORT\` heading anywhere in the file.
-2. If found, use the Edit tool to DELETE the entire existing section. Match from
-   \`## GSTACK REVIEW REPORT\` through either the next \`## \` heading or end of
-   file, whichever comes first. Replace with the empty string. This applies
-   regardless of where the section currently lives — mid-file deletion is
-   intentional, not a special case. If the Edit fails (e.g., concurrent edit
-   changed the content), re-read the plan file and retry once.
-3. After the delete (or skipped, if no section existed), append the new
-   \`## GSTACK REVIEW REPORT\` section at the END of the file. Use the Edit
-   tool to match the file's current last paragraph and add the section after it,
-   or use Write to re-emit the whole file with the section at the end.
-4. Verify with the Read tool that \`## GSTACK REVIEW REPORT\` is the last
-   \`## \` heading in the file before continuing. If it isn't, repeat steps
-   2-3 once.
-
-Do NOT replace the section in place. The "replace mid-file" path is what allowed
-prior versions to leave the report mid-file when an older report already lived
-there — the user then sees a plan whose review report is not at the bottom and
-(correctly) rejects it.
-
-## Capture Learnings
-
-If you discovered a non-obvious pattern, pitfall, or architectural insight during
-this session, log it for future sessions:
-
-```bash
-~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"plan-eng-review","type":"TYPE","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"SOURCE","files":["path/to/relevant/file"]}'
-```
-
-**Types:** `pattern` (reusable approach), `pitfall` (what NOT to do), `preference`
-(user stated), `architecture` (structural decision), `tool` (library/framework insight),
-`operational` (project environment/CLI/workflow knowledge).
-
-**Sources:** `observed` (you found this in the code), `user-stated` (user told you),
-`inferred` (AI deduction), `cross-model` (both Claude and Codex agree).
-
-**Confidence:** 1-10. Be honest. An observed pattern you verified in the code is 8-9.
-An inference you're not sure about is 4-5. A user preference they explicitly stated is 10.
-
-**files:** Include the specific file paths this learning references. This enables
-staleness detection: if those files are later deleted, the learning can be flagged.
-
-**Only log genuine discoveries.** Don't log obvious things. Don't log things the user
-already knows. A good test: would this insight save time in a future session? If yes, log it.
-
-
-
-## Brain Calibration Write-Back (Phase 2 / gated)
-
-When the skill makes a typed prediction worth tracking (scope decision,
-TTHW target, architectural bet, wedge commitment), it MAY write a
-`kind=bet` take to the brain so a calibration profile builds over time.
-
-**Gated on two things:**
-1. Brain trust policy for the active endpoint is `personal` (check via
-   `~/.claude/skills/gstack/bin/gstack-config get brain_trust_policy@<endpoint-hash>`).
-   Shared brains skip write-back to avoid polluting team calibration.
-2. Feature flag `BRAIN_CALIBRATION_WRITEBACK` is set (today: false; flips
-   to true when upstream gbrain v0.42+ ships `takes_add` MCP op).
-
-When both gates pass, the write-back path uses `mcp__gbrain__takes_add`
-to record a take with weight 0.7 (per SKILL_CALIBRATION_WEIGHTS).
-If the MCP op is unavailable, fall back to `mcp__gbrain__put_page` with
-a gstack:takes fence block (documented but uglier path).
-
-Mandatory take frontmatter shape:
-```yaml
-kind: bet
-holder: <user identity from whoami>
-claim: <one-line prediction the skill is making>
-weight: 0.7
-since_date: <today's date>
-expected_resolution: <date in 1-3 months depending on skill>
-source_skill: plan-eng-review
-```
-
-After write, invalidate the affected digests so the next preflight reflects
-the new state:
-
-```bash
-eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true
-  # (no per-skill invalidation targets configured)
-```
-
-
-## Brain Cache Background Refresh
-
-After the skill's work completes (and telemetry has logged), kick a
-background refresh of any cache digest that's getting close to its TTL.
-This is non-blocking — the user doesn't wait. Next invocation benefits
-from the warm cache.
-
-```bash
-eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true
-(~/.claude/skills/gstack/bin/gstack-brain-cache refresh --project "$SLUG" 2>/dev/null &) || true
-```
-
-
-## Next Steps — Review Chaining
-
-After displaying the Review Readiness Dashboard, check if additional reviews would be valuable. Read the dashboard output to see which reviews have already been run and whether they are stale.
-
-**Suggest /plan-design-review if UI changes exist and no design review has been run** — detect from the test diagram, architecture review, or any section that touched frontend components, CSS, views, or user-facing interaction flows. If an existing design review's commit hash shows it predates significant changes found in this eng review, note that it may be stale.
-
-**Mention /plan-ceo-review if this is a significant product change and no CEO review exists** — this is a soft suggestion, not a push. CEO review is optional. Only mention it if the plan introduces new user-facing features, changes product direction, or expands scope substantially.
-
-**Note staleness** of existing CEO or design reviews if this eng review found assumptions that contradict them, or if the commit hash shows significant drift.
-
-**If no additional reviews are needed** (or `skip_eng_review` is `true` in the dashboard config, meaning this eng review was optional): state "All relevant reviews complete. Run /ship when ready."
-
-Use AskUserQuestion with only the applicable options:
-- **A)** Run /plan-design-review (only if UI scope detected and no design review exists)
-- **B)** Run /plan-ceo-review (only if significant product change and no CEO review exists)
-- **C)** Ready to implement — run /ship when done
-
-## Unresolved decisions
-If the user does not respond to an AskUserQuestion or interrupts to move on, note which decisions were left unresolved. At the end of the review, list these as "Unresolved decisions that may bite you later" — never silently default to an option.
 
 ## EXIT PLAN MODE GATE (BLOCKING)
 

plan-eng-review/SKILL.md.tmpl

@@ -77,6 +77,11 @@ When evaluating architecture, think "boring by default." When reviewing tests, t
 
 {{BRAIN_PREFLIGHT}}
 
+---
+{{SECTION_INDEX:plan-eng-review}}
+---
+
+
 ## BEFORE YOU START:
 
 ### Design Doc Check
@@ -125,226 +130,10 @@ Always work through the full interactive review: one section at a time (Architec
 
 **Critical: Once the user accepts or rejects a scope reduction recommendation, commit fully.** Do not re-argue for smaller scope during later review sections. Do not silently reduce scope or skip planned components.
 
-## Review Sections (after scope is agreed)
+{{SECTION:review-sections}}
 
-**Anti-skip rule:** Never condense, abbreviate, or skip any review section (1-4) regardless of plan type (strategy, spec, code, infra). Every section in this skill exists for a reason. "This is a strategy doc so implementation sections don't apply" is always wrong — implementation details are where strategy breaks down. If a section genuinely has zero findings, say "No issues found" and move on — but you must evaluate it.
+## Section self-check (before you finish)
 
-{{ANTI_SHORTCUT_CLAUSE}}
+Confirm you Read the review section the Section index named, and executed every review section (Architecture, Code Quality, Tests, Performance), the outside voice, and the required outputs in full. If you produced findings or the review report from memory without Reading `sections/review-sections.md`, stop and Read it now.
-
-{{LEARNINGS_SEARCH}}
-
-### 1. Architecture review
-Evaluate:
-* Overall system design and component boundaries.
-* Dependency graph and coupling concerns.
-* Data flow patterns and potential bottlenecks.
-* Scaling characteristics and single points of failure.
-* Security architecture (auth, data access, API boundaries).
-* Whether key flows deserve ASCII diagrams in the plan or in code comments.
-* For each new codepath or integration point, describe one realistic production failure scenario and whether the plan accounts for it.
-* **Distribution architecture:** If this introduces a new artifact (binary, package, container), how does it get built, published, and updated? Is the CI/CD pipeline part of the plan or deferred?
-
-For each issue found in this section, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Do NOT batch multiple issues into one AskUserQuestion. Use the preamble's AskUserQuestion Format section. The AskUserQuestion call is a tool_use, not prose — call the tool directly.
-
-**STOP.** Do NOT proceed to the next review section, edit the plan file with the proposed fix, or call ExitPlanMode until the user responds. An issue with an "obvious fix" is still an issue and still needs explicit user approval before it lands in the plan. Loading the AskUserQuestion schema via ToolSearch and then writing the recommendation as chat prose is the failure mode this gate exists to prevent.
-
-{{CONFIDENCE_CALIBRATION}}
-
-### 2. Code quality review
-Evaluate:
-* Code organization and module structure.
-* DRY violations—be aggressive here.
-* Error handling patterns and missing edge cases (call these out explicitly).
-* Technical debt hotspots.
-* Areas that are over-engineered or under-engineered relative to my preferences.
-* Existing ASCII diagrams in touched files — are they still accurate after this change?
-
-For each issue found in this section, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Do NOT batch multiple issues into one AskUserQuestion. Use the preamble's AskUserQuestion Format section. The AskUserQuestion call is a tool_use, not prose — call the tool directly.
-
-**STOP.** Do NOT proceed to the next review section, edit the plan file with the proposed fix, or call ExitPlanMode until the user responds. An issue with an "obvious fix" is still an issue and still needs explicit user approval before it lands in the plan. Loading the AskUserQuestion schema via ToolSearch and then writing the recommendation as chat prose is the failure mode this gate exists to prevent.
-
-### 3. Test review
-
-{{TEST_COVERAGE_AUDIT_PLAN}}
-
-For LLM/prompt changes: check the "Prompt/LLM changes" file patterns listed in CLAUDE.md. If this plan touches ANY of those patterns, state which eval suites must be run, which cases should be added, and what baselines to compare against. Then use AskUserQuestion to confirm the eval scope with the user.
-
-For each issue found in this section, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Do NOT batch multiple issues into one AskUserQuestion. Use the preamble's AskUserQuestion Format section. The AskUserQuestion call is a tool_use, not prose — call the tool directly.
-
-**STOP.** Do NOT proceed to the next review section, edit the plan file with the proposed fix, or call ExitPlanMode until the user responds. An issue with an "obvious fix" is still an issue and still needs explicit user approval before it lands in the plan. Loading the AskUserQuestion schema via ToolSearch and then writing the recommendation as chat prose is the failure mode this gate exists to prevent.
-
-### 4. Performance review
-Evaluate:
-* N+1 queries and database access patterns.
-* Memory-usage concerns.
-* Caching opportunities.
-* Slow or high-complexity code paths.
-
-For each issue found in this section, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Do NOT batch multiple issues into one AskUserQuestion. Use the preamble's AskUserQuestion Format section. The AskUserQuestion call is a tool_use, not prose — call the tool directly.
-
-**STOP.** Do NOT proceed to the next review section, edit the plan file with the proposed fix, or call ExitPlanMode until the user responds. An issue with an "obvious fix" is still an issue and still needs explicit user approval before it lands in the plan. Loading the AskUserQuestion schema via ToolSearch and then writing the recommendation as chat prose is the failure mode this gate exists to prevent.
-
-{{CODEX_PLAN_REVIEW}}
-
-### Outside Voice Integration Rule
-
-Outside voice findings are INFORMATIONAL until the user explicitly approves each one.
-Do NOT incorporate outside voice recommendations into the plan without presenting each
-finding via AskUserQuestion and getting explicit approval. This applies even when you
-agree with the outside voice. Cross-model consensus is a strong signal — present it as
-such — but the user makes the decision.
-
-## CRITICAL RULE — How to ask questions
-Follow the AskUserQuestion format from the Preamble above. Additional rules for plan reviews:
-* **One issue = one AskUserQuestion call.** Never combine multiple issues into one question.
-* Describe the problem concretely, with file and line references.
-* Present 2-3 options, including "do nothing" where that's reasonable.
-* For each option, specify in one line: effort (human: ~X / CC: ~Y), risk, and maintenance burden. If the complete option is only marginally more effort than the shortcut with CC, recommend the complete option.
-* **Map the reasoning to my engineering preferences above.** One sentence connecting your recommendation to a specific preference (DRY, explicit > clever, minimal diff, etc.).
-* Label with issue NUMBER + option LETTER (e.g., "3A", "3B").
-* **Coverage vs kind:** for every per-issue AskUserQuestion you raise in this review, decide whether the options differ in coverage or in kind. If coverage (e.g., more tests vs fewer, complete error handling vs happy-path-only, full edge-case coverage vs shortcut), include `Completeness: N/10` on each option. If kind (e.g., architectural choice between two different systems, posture-over-posture, A/B/C where each is a different kind of thing), skip the score and add one line: `Note: options differ in kind, not coverage — no completeness score.` Do NOT fabricate scores on kind-differentiated questions — filler scores are worse than no score.
-* **Zero findings:** if a section has zero findings, state "No issues, moving on" and proceed. Otherwise, use AskUserQuestion for each finding — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan.
-
-## Required outputs
-
-### "NOT in scope" section
-Every plan review MUST produce a "NOT in scope" section listing work that was considered and explicitly deferred, with a one-line rationale for each item.
-
-### "What already exists" section
-List existing code/flows that already partially solve sub-problems in this plan, and whether the plan reuses them or unnecessarily rebuilds them.
-
-### TODOS.md updates
-After all review sections are complete, present each potential TODO as its own individual AskUserQuestion. Never batch TODOs — one per question. Never silently skip this step. Follow the format in `.claude/skills/review/TODOS-format.md`.
-
-For each TODO, describe:
-* **What:** One-line description of the work.
-* **Why:** The concrete problem it solves or value it unlocks.
-* **Pros:** What you gain by doing this work.
-* **Cons:** Cost, complexity, or risks of doing it.
-* **Context:** Enough detail that someone picking this up in 3 months understands the motivation, the current state, and where to start.
-* **Depends on / blocked by:** Any prerequisites or ordering constraints.
-
-Then present options: **A)** Add to TODOS.md **B)** Skip — not valuable enough **C)** Build it now in this PR instead of deferring.
-
-Do NOT just append vague bullet points. A TODO without context is worse than no TODO — it creates false confidence that the idea was captured while actually losing the reasoning.
-
-### Diagrams
-The plan itself should use ASCII diagrams for any non-trivial data flow, state machine, or processing pipeline. Additionally, identify which files in the implementation should get inline ASCII diagram comments — particularly Models with complex state transitions, Services with multi-step pipelines, and Concerns with non-obvious mixin behavior.
-
-### Failure modes
-For each new codepath identified in the test review diagram, list one realistic way it could fail in production (timeout, nil reference, race condition, stale data, etc.) and whether:
-1. A test covers that failure
-2. Error handling exists for it
-3. The user would 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
-
-Analyze the plan's implementation steps for parallel execution opportunities. This helps the user split work across git worktrees (via Claude Code's Agent tool with `isolation: "worktree"` or parallel workspaces).
-
-**Skip if:** all steps touch the same primary module, or the plan has fewer than 2 independent workstreams. In that case, write: "Sequential implementation, no parallelization opportunity."
-
-**Otherwise, produce:**
-
-1. **Dependency table** — for each implementation step/workstream:
-
-| Step | Modules touched | Depends on |
-|------|----------------|------------|
-| (step name) | (directories/modules, NOT specific files) | (other steps, or —) |
-
-Work at the module/directory level, not file level. Plans describe intent ("add API endpoints"), not specific files. Module-level ("controllers/, models/") is reliable; file-level is guesswork.
-
-2. **Parallel lanes** — group steps into lanes:
-   - Steps with no shared modules and no dependency go in separate lanes (parallel)
-   - Steps sharing a module directory go in the same lane (sequential)
-   - Steps depending on other steps go in later lanes
-
-Format: `Lane A: step1 → step2 (sequential, shared models/)` / `Lane B: step3 (independent)`
-
-3. **Execution order** — which lanes launch in parallel, which wait. Example: "Launch A + B in parallel worktrees. Merge both. Then C."
-
-4. **Conflict flags** — if two parallel lanes touch the same module directory, flag it: "Lanes X and Y both touch module/ — potential merge conflict. Consider sequential execution or careful coordination."
-
-{{TASKS_SECTION_EMIT:eng-review}}
-
-### Completion summary
-At the end of the review, fill in and display this summary so the user can see all findings at a glance:
-- 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
-- Outside voice: ran (codex/claude) / skipped
-- Parallelization: ___ lanes, ___ parallel / ___ sequential
-- Lake Score: X/Y recommendations chose complete option
-
-## Retrospective learning
-Check the git log for this branch. If there are prior commits suggesting a previous review cycle (e.g., review-driven refactors, reverted changes), note what was changed and whether the current plan touches the same areas. Be more aggressive reviewing areas that were previously problematic.
-
-## Formatting rules
-* NUMBER issues (1, 2, 3...) and LETTERS for options (A, B, C...).
-* Label with NUMBER + LETTER (e.g., "3A", "3B").
-* One sentence max per option. Pick in under 5 seconds.
-* After each review section, pause and ask for feedback before moving on.
-
-## Review Log
-
-After producing the Completion Summary above, persist the review result.
-
-**PLAN MODE EXCEPTION — ALWAYS RUN:** This command writes review metadata to
-`~/.gstack/` (user config directory, not project files). The skill preamble
-already writes to `~/.gstack/sessions/` and `~/.gstack/analytics/` — this is
-the same pattern. The review dashboard depends on this data. Skipping this
-command breaks the review readiness dashboard in /ship.
-
-```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"}'
-```
-
-Substitute values from the Completion Summary:
-- **TIMESTAMP**: current ISO 8601 datetime
-- **STATUS**: "clean" if 0 unresolved decisions AND 0 critical gaps; otherwise "issues_open"
-- **unresolved**: number from "Unresolved decisions" count
-- **critical_gaps**: number from "Failure modes: ___ critical gaps flagged"
-- **issues_found**: total issues found across all review sections (Architecture + Code Quality + Performance + Test gaps)
-- **MODE**: FULL_REVIEW / SCOPE_REDUCED
-- **COMMIT**: output of `git rev-parse --short HEAD`
-
-{{REVIEW_DASHBOARD}}
-
-{{PLAN_FILE_REVIEW_REPORT}}
-
-{{LEARNINGS_LOG}}
-
-{{GBRAIN_SAVE_RESULTS}}
-
-{{BRAIN_WRITE_BACK}}
-
-{{BRAIN_CACHE_REFRESH}}
-
-## Next Steps — Review Chaining
-
-After displaying the Review Readiness Dashboard, check if additional reviews would be valuable. Read the dashboard output to see which reviews have already been run and whether they are stale.
-
-**Suggest /plan-design-review if UI changes exist and no design review has been run** — detect from the test diagram, architecture review, or any section that touched frontend components, CSS, views, or user-facing interaction flows. If an existing design review's commit hash shows it predates significant changes found in this eng review, note that it may be stale.
-
-**Mention /plan-ceo-review if this is a significant product change and no CEO review exists** — this is a soft suggestion, not a push. CEO review is optional. Only mention it if the plan introduces new user-facing features, changes product direction, or expands scope substantially.
-
-**Note staleness** of existing CEO or design reviews if this eng review found assumptions that contradict them, or if the commit hash shows significant drift.
-
-**If no additional reviews are needed** (or `skip_eng_review` is `true` in the dashboard config, meaning this eng review was optional): state "All relevant reviews complete. Run /ship when ready."
-
-Use AskUserQuestion with only the applicable options:
-- **A)** Run /plan-design-review (only if UI scope detected and no design review exists)
-- **B)** Run /plan-ceo-review (only if significant product change and no CEO review exists)
-- **C)** Ready to implement — run /ship when done
-
-## Unresolved decisions
-If the user does not respond to an AskUserQuestion or interrupts to move on, note which decisions were left unresolved. At the end of the review, list these as "Unresolved decisions that may bite you later" — never silently default to an option.
 
 {{EXIT_PLAN_MODE_GATE}}

plan-eng-review/sections/manifest.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://gstack.dev/schemas/section-manifest.json",
+  "skill": "plan-eng-review",
+  "version": 1,
+  "note": "PASSIVE registry (v2 plan T9 / CM2). id/file/title/trigger text ONLY. The skeleton's decision-tree prose decides WHEN to read. No machine predicate here — see docs/designs/v2_PLAN.md.",
+  "sections": [
+    {
+      "id": "review-sections",
+      "file": "review-sections.md",
+      "title": "Architecture/Code/Test/Performance review, outside voice, required outputs + review report",
+      "trigger": "running the 4-section review, outside voice, required outputs, and review report (only after Step 0 scope is agreed)"
+    }
+  ]
+}

plan-eng-review/sections/review-sections.md

@@ -0,0 +1,901 @@
+<!-- AUTO-GENERATED from review-sections.md.tmpl — do not edit directly -->
+<!-- Regenerate: bun run gen:skill-docs -->
+## Review Sections (after scope is agreed)
+
+**Anti-skip rule:** Never condense, abbreviate, or skip any review section (1-4) regardless of plan type (strategy, spec, code, infra). Every section in this skill exists for a reason. "This is a strategy doc so implementation sections don't apply" is always wrong — implementation details are where strategy breaks down. If a section genuinely has zero findings, say "No issues found" and move on — but you must evaluate it.
+
+**Anti-shortcut clause:** The plan file is the OUTPUT of the interactive review, not a substitute for it. Writing every finding into one plan write and calling ExitPlanMode without firing AskUserQuestion is the precise failure mode of the May 2026 transcript bug — the model explored, found issues, and dumped them into a deliverable rather than walking the user through them. If you have ANY non-trivial finding in any review section, the path from finding to ExitPlanMode goes THROUGH AskUserQuestion. Zero findings in every section is the only path to ExitPlanMode that bypasses AskUserQuestion. If you find yourself wanting to write a plan with findings before asking, stop and call AskUserQuestion now — that's the bug, recognize it.
+
+## Prior Learnings
+
+Search for relevant learnings from previous sessions:
+
+```bash
+_CROSS_PROJ=$(~/.claude/skills/gstack/bin/gstack-config get cross_project_learnings 2>/dev/null || echo "unset")
+echo "CROSS_PROJECT: $_CROSS_PROJ"
+if [ "$_CROSS_PROJ" = "true" ]; then
+  ~/.claude/skills/gstack/bin/gstack-learnings-search --limit 10 --cross-project 2>/dev/null || true
+else
+  ~/.claude/skills/gstack/bin/gstack-learnings-search --limit 10 2>/dev/null || true
+fi
+```
+
+If `CROSS_PROJECT` is `unset` (first time): Use AskUserQuestion:
+
+> gstack can search learnings from your other projects on this machine to find
+> patterns that might apply here. This stays local (no data leaves your machine).
+> Recommended for solo developers. Skip if you work on multiple client codebases
+> where cross-contamination would be a concern.
+
+Options:
+- A) Enable cross-project learnings (recommended)
+- B) Keep learnings project-scoped only
+
+If A: run `~/.claude/skills/gstack/bin/gstack-config set cross_project_learnings true`
+If B: run `~/.claude/skills/gstack/bin/gstack-config set cross_project_learnings false`
+
+Then re-run the search with the appropriate flag.
+
+If learnings are found, incorporate them into your analysis. When a review finding
+matches a past learning, display:
+
+**"Prior learning applied: [key] (confidence N/10, from [date])"**
+
+This makes the compounding visible. The user should see that gstack is getting
+smarter on their codebase over time.
+
+### 1. Architecture review
+Evaluate:
+* Overall system design and component boundaries.
+* Dependency graph and coupling concerns.
+* Data flow patterns and potential bottlenecks.
+* Scaling characteristics and single points of failure.
+* Security architecture (auth, data access, API boundaries).
+* Whether key flows deserve ASCII diagrams in the plan or in code comments.
+* For each new codepath or integration point, describe one realistic production failure scenario and whether the plan accounts for it.
+* **Distribution architecture:** If this introduces a new artifact (binary, package, container), how does it get built, published, and updated? Is the CI/CD pipeline part of the plan or deferred?
+
+For each issue found in this section, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Do NOT batch multiple issues into one AskUserQuestion. Use the preamble's AskUserQuestion Format section. The AskUserQuestion call is a tool_use, not prose — call the tool directly.
+
+**STOP.** Do NOT proceed to the next review section, edit the plan file with the proposed fix, or call ExitPlanMode until the user responds. An issue with an "obvious fix" is still an issue and still needs explicit user approval before it lands in the plan. Loading the AskUserQuestion schema via ToolSearch and then writing the recommendation as chat prose is the failure mode this gate exists to prevent.
+
+## Confidence Calibration
+
+Every finding MUST include a confidence score (1-10):
+
+| Score | Meaning | Display rule |
+|-------|---------|-------------|
+| 9-10 | Verified by reading specific code. Concrete bug or exploit demonstrated. | Show normally |
+| 7-8 | High confidence pattern match. Very likely correct. | Show normally |
+| 5-6 | Moderate. Could be a false positive. | Show with caveat: "Medium confidence, verify this is actually an issue" |
+| 3-4 | Low confidence. Pattern is suspicious but may be fine. | Suppress from main report. Include in appendix only. |
+| 1-2 | Speculation. | Only report if severity would be P0. |
+
+**Finding format:**
+
+\`[SEVERITY] (confidence: N/10) file:line — description\`
+
+Example:
+\`[P1] (confidence: 9/10) app/models/user.rb:42 — SQL injection via string interpolation in where clause\`
+\`[P2] (confidence: 5/10) app/controllers/api/v1/users_controller.rb:18 — Possible N+1 query, verify with production logs\`
+
+### Pre-emit verification gate (#1539 — kills the "field doesn't exist" FP class)
+
+Before any finding is promoted to the report, the gate requires:
+
+1. **Quote the specific code line that motivates the finding** — file:line plus
+   the verbatim text of the line(s) that triggered it. If the finding is "field
+   X doesn't exist on model Y", quote the lines of class Y where the field
+   would live. If "dict.get() might return None", quote the dict initialization.
+   If "race condition between A and B", quote both A and B.
+
+2. **If you cannot quote the motivating line(s), the finding is unverified.**
+   Force its confidence to 4-5 (suppressed from the main report). It still goes
+   into the appendix so reviewers can audit calibration, but the user does NOT
+   see it in the critical-pass output. Do not work around this by inventing
+   speculative confidence 7+ — that defeats the gate.
+
+**Framework-meta nudge:** When the symbol is generated by a framework
+metaclass, descriptor, ORM Meta inner-class, or migration history (Django
+`Meta`, Rails `has_many`/`scope`, SQLAlchemy `relationship`/`Column`,
+TypeORM decorators, Sequelize `init`/`belongsTo`, Prisma generated client),
+quote the meta-construct (the `Meta` block, the migration, the decorator,
+the schema file) instead of expecting the literal name in the class body.
+The verification is "I read the source that creates this symbol", not "I
+grep'd for the name and didn't find it." Deeper framework-aware verification
+(model introspection, migration-history-aware checks, ORM dialect detection)
+is deliberately out of scope for the lighter gate — see the deferred
+`~/.gstack-dev/plans/1539-framework-aware-review.md` design doc.
+
+The FP classes the gate kills (measured against Django Sprint 2.5 #1539):
+
+| FP class | Why the gate catches it |
+|---|---|
+| "field doesn't exist on model" | Requires quoting the model class body or Meta; the field's absence becomes obvious |
+| "dict.get() might be None" | Requires quoting the dict initialization (e.g. Django form's `cleaned_data` is `{}`-initialized) |
+| "save() might lose fields" | Requires quoting the ORM signature or model definition |
+| "update_fields might miss X" | Requires quoting the field set; if X doesn't exist, the FP is self-evident |
+
+**Calibration learning:** If you report a finding with confidence < 7 and the user
+confirms it IS a real issue, that is a calibration event. Your initial confidence was
+too low. Log the corrected pattern as a learning so future reviews catch it with
+higher confidence.
+
+### 2. Code quality review
+Evaluate:
+* Code organization and module structure.
+* DRY violations—be aggressive here.
+* Error handling patterns and missing edge cases (call these out explicitly).
+* Technical debt hotspots.
+* Areas that are over-engineered or under-engineered relative to my preferences.
+* Existing ASCII diagrams in touched files — are they still accurate after this change?
+
+For each issue found in this section, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Do NOT batch multiple issues into one AskUserQuestion. Use the preamble's AskUserQuestion Format section. The AskUserQuestion call is a tool_use, not prose — call the tool directly.
+
+**STOP.** Do NOT proceed to the next review section, edit the plan file with the proposed fix, or call ExitPlanMode until the user responds. An issue with an "obvious fix" is still an issue and still needs explicit user approval before it lands in the plan. Loading the AskUserQuestion schema via ToolSearch and then writing the recommendation as chat prose is the failure mode this gate exists to prevent.
+
+### 3. Test review
+
+100% coverage is the goal. Evaluate every codepath in the plan and ensure the plan includes tests for each one. If the plan is missing tests, add them — the plan should be complete enough that implementation includes full test coverage from the start.
+
+### Test Framework Detection
+
+Before analyzing coverage, detect the project's test framework:
+
+1. **Read CLAUDE.md** — look for a `## Testing` section with test command and framework name. If found, use that as the authoritative source.
+2. **If CLAUDE.md has no testing section, auto-detect:**
+
+```bash
+setopt +o nomatch 2>/dev/null || true  # zsh compat
+# Detect project runtime
+[ -f Gemfile ] && echo "RUNTIME:ruby"
+[ -f package.json ] && echo "RUNTIME:node"
+[ -f requirements.txt ] || [ -f pyproject.toml ] && echo "RUNTIME:python"
+[ -f go.mod ] && echo "RUNTIME:go"
+[ -f Cargo.toml ] && echo "RUNTIME:rust"
+# Check for existing test infrastructure
+ls jest.config.* vitest.config.* playwright.config.* cypress.config.* .rspec pytest.ini phpunit.xml 2>/dev/null
+ls -d test/ tests/ spec/ __tests__/ cypress/ e2e/ 2>/dev/null
+```
+
+3. **If no framework detected:** still produce the coverage diagram, but skip test generation.
+
+**Step 1. Trace every codepath in the plan:**
+
+Read the plan document. For each new feature, service, endpoint, or component described, trace how data will flow through the code — don't just list planned functions, actually follow the planned execution:
+
+1. **Read the plan.** For each planned component, understand what it does and how it connects to existing code.
+2. **Trace data flow.** Starting from each entry point (route handler, exported function, event listener, component render), follow the data through every branch:
+   - Where does input come from? (request params, props, database, API call)
+   - What transforms it? (validation, mapping, computation)
+   - Where does it go? (database write, API response, rendered output, side effect)
+   - What can go wrong at each step? (null/undefined, invalid input, network failure, empty collection)
+3. **Diagram the execution.** For each changed file, draw an ASCII diagram showing:
+   - Every function/method that was added or modified
+   - Every conditional branch (if/else, switch, ternary, guard clause, early return)
+   - Every error path (try/catch, rescue, error boundary, fallback)
+   - Every call to another function (trace into it — does IT have untested branches?)
+   - Every edge: what happens with null input? Empty array? Invalid type?
+
+This is the critical step — you're building a map of every line of code that can execute differently based on input. Every branch in this diagram needs a test.
+
+**Step 2. Map user flows, interactions, and error states:**
+
+Code coverage isn't enough — you need to cover how real users interact with the changed code. For each changed feature, think through:
+
+- **User flows:** What sequence of actions does a user take that touches this code? Map the full journey (e.g., "user clicks 'Pay' → form validates → API call → success/failure screen"). Each step in the journey needs a test.
+- **Interaction edge cases:** What happens when the user does something unexpected?
+  - Double-click/rapid resubmit
+  - Navigate away mid-operation (back button, close tab, click another link)
+  - Submit with stale data (page sat open for 30 minutes, session expired)
+  - Slow connection (API takes 10 seconds — what does the user see?)
+  - Concurrent actions (two tabs, same form)
+- **Error states the user can see:** For every error the code handles, what does the user actually experience?
+  - Is there a clear error message or a silent failure?
+  - Can the user recover (retry, go back, fix input) or are they stuck?
+  - What happens with no network? With a 500 from the API? With invalid data from the server?
+- **Empty/zero/boundary states:** What does the UI show with zero results? With 10,000 results? With a single character input? With maximum-length input?
+
+Add these to your diagram alongside the code branches. A user flow with no test is just as much a gap as an untested if/else.
+
+**Step 3. Check each branch against existing tests:**
+
+Go through your diagram branch by branch — both code paths AND user flows. For each one, search for a test that exercises it:
+- Function `processPayment()` → look for `billing.test.ts`, `billing.spec.ts`, `test/billing_test.rb`
+- An if/else → look for tests covering BOTH the true AND false path
+- An error handler → look for a test that triggers that specific error condition
+- A call to `helperFn()` that has its own branches → those branches need tests too
+- A user flow → look for an integration or E2E test that walks through the journey
+- An interaction edge case → look for a test that simulates the unexpected action
+
+Quality scoring rubric:
+- ★★★  Tests behavior with edge cases AND error paths
+- ★★   Tests correct behavior, happy path only
+- ★    Smoke test / existence check / trivial assertion (e.g., "it renders", "it doesn't throw")
+
+### E2E Test Decision Matrix
+
+When checking each branch, also determine whether a unit test or E2E/integration test is the right tool:
+
+**RECOMMEND E2E (mark as [→E2E] in the diagram):**
+- Common user flow spanning 3+ components/services (e.g., signup → verify email → first login)
+- Integration point where mocking hides real failures (e.g., API → queue → worker → DB)
+- Auth/payment/data-destruction flows — too important to trust unit tests alone
+
+**RECOMMEND EVAL (mark as [→EVAL] in the diagram):**
+- Critical LLM call that needs a quality eval (e.g., prompt change → test output still meets quality bar)
+- Changes to prompt templates, system instructions, or tool definitions
+
+**STICK WITH UNIT TESTS:**
+- Pure function with clear inputs/outputs
+- Internal helper with no side effects
+- Edge case of a single function (null input, empty array)
+- Obscure/rare flow that isn't customer-facing
+
+### REGRESSION RULE (mandatory)
+
+**IRON RULE:** When the coverage audit identifies a REGRESSION — code that previously worked but the diff broke — a regression test is added to the plan as a critical requirement. No AskUserQuestion. No skipping. Regressions are the highest-priority test because they prove something broke.
+
+A regression is when:
+- The diff modifies existing behavior (not new code)
+- The existing test suite (if any) doesn't cover the changed path
+- The change introduces a new failure mode for existing callers
+
+When uncertain whether a change is a regression, err on the side of writing the test.
+
+**Step 4. Output ASCII coverage diagram:**
+
+Include BOTH code paths and user flows in the same diagram. Mark E2E-worthy and eval-worthy paths:
+
+```
+CODE PATHS                                            USER FLOWS
+[+] src/services/billing.ts                           [+] Payment checkout
+  ├── processPayment()                                  ├── [★★★ TESTED] Complete purchase — checkout.e2e.ts:15
+  │   ├── [★★★ TESTED] happy + declined + timeout      ├── [GAP] [→E2E] Double-click submit
+  │   ├── [GAP]         Network timeout                 └── [GAP]        Navigate away mid-payment
+  │   └── [GAP]         Invalid currency
+  └── refundPayment()                                 [+] Error states
+      ├── [★★  TESTED] Full refund — :89                ├── [★★  TESTED] Card declined message
+      └── [★   TESTED] Partial (non-throw only) — :101  └── [GAP]        Network timeout UX
+
+LLM integration: [GAP] [→EVAL] Prompt template change — needs eval test
+
+COVERAGE: 5/13 paths tested (38%)  |  Code paths: 3/5 (60%)  |  User flows: 2/8 (25%)
+QUALITY: ★★★:2 ★★:2 ★:1  |  GAPS: 8 (2 E2E, 1 eval)
+```
+
+Legend: ★★★ behavior + edge + error  |  ★★ happy path  |  ★ smoke check
+[→E2E] = needs integration test  |  [→EVAL] = needs LLM eval
+
+**Fast path:** All paths covered → "Test review: All new code paths have test coverage ✓" Continue.
+
+**Step 5. Add missing tests to the plan:**
+
+For each GAP identified in the diagram, add a test requirement to the plan. Be specific:
+- What test file to create (match existing naming conventions)
+- What the test should assert (specific inputs → expected outputs/behavior)
+- Whether it's a unit test, E2E test, or eval (use the decision matrix)
+- For regressions: flag as **CRITICAL** and explain what broke
+
+The plan should be complete enough that when implementation begins, every test is written alongside the feature code — not deferred to a follow-up.
+
+### Test Plan Artifact
+
+After producing the coverage diagram, write a test plan artifact to the project directory so `/qa` and `/qa-only` can consume it as primary test input:
+
+```bash
+eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" && mkdir -p ~/.gstack/projects/$SLUG
+USER=$(whoami)
+DATETIME=$(date +%Y%m%d-%H%M%S)
+```
+
+Write to `~/.gstack/projects/{slug}/{user}-{branch}-eng-review-test-plan-{datetime}.md`:
+
+```markdown
+# Test Plan
+Generated by /plan-eng-review on {date}
+Branch: {branch}
+Repo: {owner/repo}
+
+## Affected Pages/Routes
+- {URL path} — {what to test and why}
+
+## Key Interactions to Verify
+- {interaction description} on {page}
+
+## Edge Cases
+- {edge case} on {page}
+
+## Critical Paths
+- {end-to-end flow that must work}
+```
+
+This file is consumed by `/qa` and `/qa-only` as primary test input. Include only the information that helps a QA tester know **what to test and where** — not implementation details.
+
+For LLM/prompt changes: check the "Prompt/LLM changes" file patterns listed in CLAUDE.md. If this plan touches ANY of those patterns, state which eval suites must be run, which cases should be added, and what baselines to compare against. Then use AskUserQuestion to confirm the eval scope with the user.
+
+For each issue found in this section, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Do NOT batch multiple issues into one AskUserQuestion. Use the preamble's AskUserQuestion Format section. The AskUserQuestion call is a tool_use, not prose — call the tool directly.
+
+**STOP.** Do NOT proceed to the next review section, edit the plan file with the proposed fix, or call ExitPlanMode until the user responds. An issue with an "obvious fix" is still an issue and still needs explicit user approval before it lands in the plan. Loading the AskUserQuestion schema via ToolSearch and then writing the recommendation as chat prose is the failure mode this gate exists to prevent.
+
+### 4. Performance review
+Evaluate:
+* N+1 queries and database access patterns.
+* Memory-usage concerns.
+* Caching opportunities.
+* Slow or high-complexity code paths.
+
+For each issue found in this section, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Do NOT batch multiple issues into one AskUserQuestion. Use the preamble's AskUserQuestion Format section. The AskUserQuestion call is a tool_use, not prose — call the tool directly.
+
+**STOP.** Do NOT proceed to the next review section, edit the plan file with the proposed fix, or call ExitPlanMode until the user responds. An issue with an "obvious fix" is still an issue and still needs explicit user approval before it lands in the plan. Loading the AskUserQuestion schema via ToolSearch and then writing the recommendation as chat prose is the failure mode this gate exists to prevent.
+
+## Outside Voice — Independent Plan Challenge (optional, recommended)
+
+After all review sections are complete, offer an independent second opinion from a
+different AI system. Two models agreeing on a plan is stronger signal than one model's
+thorough review.
+
+**Check tool availability:**
+
+```bash
+command -v codex >/dev/null 2>&1 && echo "CODEX_AVAILABLE" || echo "CODEX_NOT_AVAILABLE"
+```
+
+Use AskUserQuestion:
+
+> "All review sections are complete. Want an outside voice? A different AI system can
+> give a brutally honest, independent challenge of this plan — logical gaps, feasibility
+> risks, and blind spots that are hard to catch from inside the review. Takes about 2
+> minutes."
+>
+> RECOMMENDATION: Choose A — an independent second opinion catches structural blind
+> spots. Two different AI models agreeing on a plan is stronger signal than one model's
+> thorough review. Completeness: A=9/10, B=7/10.
+
+Options:
+- A) Get the outside voice (recommended)
+- B) Skip — proceed to outputs
+
+**If B:** Print "Skipping outside voice." and continue to the next section.
+
+**If A:** Construct the plan review prompt. Read the plan file being reviewed (the file
+the user pointed this review at, or the branch diff scope). If a CEO plan document
+was written in Step 0D-POST, read that too — it contains the scope decisions and vision.
+
+Construct this prompt (substitute the actual plan content — if plan content exceeds 30KB,
+truncate to the first 30KB and note "Plan truncated for size"). **Always start with the
+filesystem boundary instruction:**
+
+"IMPORTANT: Do NOT read or execute any files under ~/.claude/, ~/.agents/, .claude/skills/, or agents/. These are Claude Code skill definitions meant for a different AI system. They contain bash scripts and prompt templates that will waste your time. Ignore them completely. Do NOT modify agents/openai.yaml. Stay focused on the repository code only.\n\nYou are a brutally honest technical reviewer examining a development plan that has
+already been through a multi-section review. Your job is NOT to repeat that review.
+Instead, find what it missed. Look for: logical gaps and unstated assumptions that
+survived the review scrutiny, overcomplexity (is there a fundamentally simpler
+approach the review was too deep in the weeds to see?), feasibility risks the review
+took for granted, missing dependencies or sequencing issues, and strategic
+miscalibration (is this the right thing to build at all?). Be direct. Be terse. No
+compliments. Just the problems.
+
+THE PLAN:
+<plan content>"
+
+**If CODEX_AVAILABLE:**
+
+```bash
+TMPERR_PV=$(mktemp /tmp/codex-planreview-XXXXXXXX)
+_REPO_ROOT=$(git rev-parse --show-toplevel) || { echo "ERROR: not in a git repo" >&2; exit 1; }
+codex exec "<prompt>" -C "$_REPO_ROOT" -s read-only -c 'model_reasoning_effort="high"' --enable web_search_cached < /dev/null 2>"$TMPERR_PV"
+```
+
+Use a 5-minute timeout (`timeout: 300000`). After the command completes, read stderr:
+```bash
+cat "$TMPERR_PV"
+```
+
+Present the full output verbatim:
+
+```
+CODEX SAYS (plan review — outside voice):
+════════════════════════════════════════════════════════════
+<full codex output, verbatim — do not truncate or summarize>
+════════════════════════════════════════════════════════════
+```
+
+**Error handling:** All errors are non-blocking — the outside voice is informational.
+- Auth failure (stderr contains "auth", "login", "unauthorized"): "Codex auth failed. Run \`codex login\` to authenticate."
+- Timeout: "Codex timed out after 5 minutes."
+- Empty response: "Codex returned no response."
+
+On any Codex error, fall back to the Claude adversarial subagent.
+
+**If CODEX_NOT_AVAILABLE (or Codex errored):**
+
+Dispatch via the Agent tool. The subagent has fresh context — genuine independence.
+
+Subagent prompt: same plan review prompt as above.
+
+Present findings under an `OUTSIDE VOICE (Claude subagent):` header.
+
+If the subagent fails or times out: "Outside voice unavailable. Continuing to outputs."
+
+**Cross-model tension:**
+
+After presenting the outside voice findings, note any points where the outside voice
+disagrees with the review findings from earlier sections. Flag these as:
+
+```
+CROSS-MODEL TENSION:
+  [Topic]: Review said X. Outside voice says Y. [Present both perspectives neutrally.
+  State what context you might be missing that would change the answer.]
+```
+
+**User Sovereignty:** Do NOT auto-incorporate outside voice recommendations into the plan.
+Present each tension point to the user. The user decides. Cross-model agreement is a
+strong signal — present it as such — but it is NOT permission to act. You may state
+which argument you find more compelling, but you MUST NOT apply the change without
+explicit user approval.
+
+For each substantive tension point, use AskUserQuestion:
+
+> "Cross-model disagreement on [topic]. The review found [X] but the outside voice
+> argues [Y]. [One sentence on what context you might be missing.]"
+>
+> RECOMMENDATION: Choose [A or B] because [one-line reason explaining which argument
+> is more compelling and why]. Completeness: A=X/10, B=Y/10.
+
+Options:
+- A) Accept the outside voice's recommendation (I'll apply this change)
+- B) Keep the current approach (reject the outside voice)
+- C) Investigate further before deciding
+- D) Add to TODOS.md for later
+
+Wait for the user's response. Do NOT default to accepting because you agree with the
+outside voice. If the user chooses B, the current approach stands — do not re-argue.
+
+If no tension points exist, note: "No cross-model tension — both reviewers agree."
+
+**Persist the result:**
+```bash
+~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"codex-plan-review","timestamp":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'","status":"STATUS","source":"SOURCE","commit":"'"$(git rev-parse --short HEAD)"'"}'
+```
+
+Substitute: STATUS = "clean" if no findings, "issues_found" if findings exist.
+SOURCE = "codex" if Codex ran, "claude" if subagent ran.
+
+**Cleanup:** Run `rm -f "$TMPERR_PV"` after processing (if Codex was used).
+
+---
+
+### Outside Voice Integration Rule
+
+Outside voice findings are INFORMATIONAL until the user explicitly approves each one.
+Do NOT incorporate outside voice recommendations into the plan without presenting each
+finding via AskUserQuestion and getting explicit approval. This applies even when you
+agree with the outside voice. Cross-model consensus is a strong signal — present it as
+such — but the user makes the decision.
+
+## CRITICAL RULE — How to ask questions
+Follow the AskUserQuestion format from the Preamble above. Additional rules for plan reviews:
+* **One issue = one AskUserQuestion call.** Never combine multiple issues into one question.
+* Describe the problem concretely, with file and line references.
+* Present 2-3 options, including "do nothing" where that's reasonable.
+* For each option, specify in one line: effort (human: ~X / CC: ~Y), risk, and maintenance burden. If the complete option is only marginally more effort than the shortcut with CC, recommend the complete option.
+* **Map the reasoning to my engineering preferences above.** One sentence connecting your recommendation to a specific preference (DRY, explicit > clever, minimal diff, etc.).
+* Label with issue NUMBER + option LETTER (e.g., "3A", "3B").
+* **Coverage vs kind:** for every per-issue AskUserQuestion you raise in this review, decide whether the options differ in coverage or in kind. If coverage (e.g., more tests vs fewer, complete error handling vs happy-path-only, full edge-case coverage vs shortcut), include `Completeness: N/10` on each option. If kind (e.g., architectural choice between two different systems, posture-over-posture, A/B/C where each is a different kind of thing), skip the score and add one line: `Note: options differ in kind, not coverage — no completeness score.` Do NOT fabricate scores on kind-differentiated questions — filler scores are worse than no score.
+* **Zero findings:** if a section has zero findings, state "No issues, moving on" and proceed. Otherwise, use AskUserQuestion for each finding — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan.
+
+## Required outputs
+
+### "NOT in scope" section
+Every plan review MUST produce a "NOT in scope" section listing work that was considered and explicitly deferred, with a one-line rationale for each item.
+
+### "What already exists" section
+List existing code/flows that already partially solve sub-problems in this plan, and whether the plan reuses them or unnecessarily rebuilds them.
+
+### TODOS.md updates
+After all review sections are complete, present each potential TODO as its own individual AskUserQuestion. Never batch TODOs — one per question. Never silently skip this step. Follow the format in `.claude/skills/review/TODOS-format.md`.
+
+For each TODO, describe:
+* **What:** One-line description of the work.
+* **Why:** The concrete problem it solves or value it unlocks.
+* **Pros:** What you gain by doing this work.
+* **Cons:** Cost, complexity, or risks of doing it.
+* **Context:** Enough detail that someone picking this up in 3 months understands the motivation, the current state, and where to start.
+* **Depends on / blocked by:** Any prerequisites or ordering constraints.
+
+Then present options: **A)** Add to TODOS.md **B)** Skip — not valuable enough **C)** Build it now in this PR instead of deferring.
+
+Do NOT just append vague bullet points. A TODO without context is worse than no TODO — it creates false confidence that the idea was captured while actually losing the reasoning.
+
+### Diagrams
+The plan itself should use ASCII diagrams for any non-trivial data flow, state machine, or processing pipeline. Additionally, identify which files in the implementation should get inline ASCII diagram comments — particularly Models with complex state transitions, Services with multi-step pipelines, and Concerns with non-obvious mixin behavior.
+
+### Failure modes
+For each new codepath identified in the test review diagram, list one realistic way it could fail in production (timeout, nil reference, race condition, stale data, etc.) and whether:
+1. A test covers that failure
+2. Error handling exists for it
+3. The user would 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
+
+Analyze the plan's implementation steps for parallel execution opportunities. This helps the user split work across git worktrees (via Claude Code's Agent tool with `isolation: "worktree"` or parallel workspaces).
+
+**Skip if:** all steps touch the same primary module, or the plan has fewer than 2 independent workstreams. In that case, write: "Sequential implementation, no parallelization opportunity."
+
+**Otherwise, produce:**
+
+1. **Dependency table** — for each implementation step/workstream:
+
+| Step | Modules touched | Depends on |
+|------|----------------|------------|
+| (step name) | (directories/modules, NOT specific files) | (other steps, or —) |
+
+Work at the module/directory level, not file level. Plans describe intent ("add API endpoints"), not specific files. Module-level ("controllers/, models/") is reliable; file-level is guesswork.
+
+2. **Parallel lanes** — group steps into lanes:
+   - Steps with no shared modules and no dependency go in separate lanes (parallel)
+   - Steps sharing a module directory go in the same lane (sequential)
+   - Steps depending on other steps go in later lanes
+
+Format: `Lane A: step1 → step2 (sequential, shared models/)` / `Lane B: step3 (independent)`
+
+3. **Execution order** — which lanes launch in parallel, which wait. Example: "Launch A + B in parallel worktrees. Merge both. Then C."
+
+4. **Conflict flags** — if two parallel lanes touch the same module directory, flag it: "Lanes X and Y both touch module/ — potential merge conflict. Consider sequential execution or careful coordination."
+
+## Implementation Tasks
+
+Before closing this review, synthesize the findings above into a flat list of
+build-actionable tasks. Each task derives from a specific finding — no padding.
+Emit the markdown section AND write a JSONL artifact that `/autoplan` can
+aggregate across phases.
+
+### Markdown section (always emit)
+
+```markdown
+## Implementation Tasks
+Synthesized from this review's findings. Each task derives from a specific
+finding above. Run with Claude Code or Codex; checkbox as you ship.
+
+- [ ] **T1 (P1, human: ~2h / CC: ~15min)** — <component> — <imperative title>
+  - Surfaced by: <section name> — <specific finding text or line reference>
+  - Files: <paths to touch>
+  - Verify: <test command or manual check>
+- [ ] **T2 (P2, human: ~30min / CC: ~5min)** — ...
+```
+
+Rules:
+- P1 blocks ship; P2 should land same branch; P3 is a follow-up TODO.
+- If a finding produced no actionable task, do not invent one.
+- If a section had zero findings, emit `_No new tasks from <section>._`
+- Effort uses the AI-compression table from CLAUDE.md.
+
+### JSONL artifact (always write, even if zero tasks)
+
+`/autoplan` reads this file to aggregate across phases. Build each line with
+`jq -nc` so titles and source findings containing quotes, newlines, or
+backslashes serialize cleanly — never use hand-rolled `echo` / `printf`.
+
+```bash
+eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)"
+TASKS_DIR="${HOME}/.gstack/projects/${SLUG:-unknown}"
+mkdir -p "$TASKS_DIR"
+TASKS_FILE="$TASKS_DIR/tasks-eng-review-$(date +%Y%m%d-%H%M%S).jsonl"
+COMMIT=$(git rev-parse HEAD 2>/dev/null || echo unknown)
+BRANCH=$(git branch --show-current 2>/dev/null || echo unknown)
+RUN_ID="$(date -u +%Y%m%dT%H%M%SZ)-$$"
+
+# Repeat ONE jq invocation per task identified during this review.
+# Substitute the placeholders inline with shell variables you set per task:
+#   TASK_ID (T1, T2, ...), PRIORITY (P1/P2/P3), COMPONENT, TITLE,
+#   SOURCE_FINDING, EFFORT_HUMAN, EFFORT_CC, FILES_JSON (a JSON array literal
+#   like '["browse/src/sanitize.ts","browse/src/server.ts"]').
+jq -nc \
+  --arg phase 'eng-review' \
+  --arg run_id "$RUN_ID" \
+  --arg branch "$BRANCH" \
+  --arg commit "$COMMIT" \
+  --arg id "$TASK_ID" \
+  --arg priority "$PRIORITY" \
+  --arg component "$COMPONENT" \
+  --arg effort_human "$EFFORT_HUMAN" \
+  --arg effort_cc "$EFFORT_CC" \
+  --arg title "$TITLE" \
+  --arg source_finding "$SOURCE_FINDING" \
+  --argjson files "$FILES_JSON" \
+  '{phase:$phase, run_id:$run_id, branch:$branch, commit:$commit, id:$id, priority:$priority, component:$component, files:$files, effort_human:$effort_human, effort_cc:$effort_cc, title:$title, source_finding:$source_finding}' \
+  >> "$TASKS_FILE"
+```
+
+If `jq` is not installed, fall back to skipping the JSONL write and warn
+the user to install jq for autoplan aggregation. Never hand-roll JSONL.
+
+If zero tasks were identified in this review, still touch the JSONL file
+(`: > "$TASKS_FILE"`) so the aggregator sees that the phase produced output
+this run (an empty file means "ran, no findings" — distinct from "didn't run").
+
+
+### Completion summary
+At the end of the review, fill in and display this summary so the user can see all findings at a glance:
+- 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
+- Outside voice: ran (codex/claude) / skipped
+- Parallelization: ___ lanes, ___ parallel / ___ sequential
+- Lake Score: X/Y recommendations chose complete option
+
+## Retrospective learning
+Check the git log for this branch. If there are prior commits suggesting a previous review cycle (e.g., review-driven refactors, reverted changes), note what was changed and whether the current plan touches the same areas. Be more aggressive reviewing areas that were previously problematic.
+
+## Formatting rules
+* NUMBER issues (1, 2, 3...) and LETTERS for options (A, B, C...).
+* Label with NUMBER + LETTER (e.g., "3A", "3B").
+* One sentence max per option. Pick in under 5 seconds.
+* After each review section, pause and ask for feedback before moving on.
+
+## Review Log
+
+After producing the Completion Summary above, persist the review result.
+
+**PLAN MODE EXCEPTION — ALWAYS RUN:** This command writes review metadata to
+`~/.gstack/` (user config directory, not project files). The skill preamble
+already writes to `~/.gstack/sessions/` and `~/.gstack/analytics/` — this is
+the same pattern. The review dashboard depends on this data. Skipping this
+command breaks the review readiness dashboard in /ship.
+
+```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"}'
+```
+
+Substitute values from the Completion Summary:
+- **TIMESTAMP**: current ISO 8601 datetime
+- **STATUS**: "clean" if 0 unresolved decisions AND 0 critical gaps; otherwise "issues_open"
+- **unresolved**: number from "Unresolved decisions" count
+- **critical_gaps**: number from "Failure modes: ___ critical gaps flagged"
+- **issues_found**: total issues found across all review sections (Architecture + Code Quality + Performance + Test gaps)
+- **MODE**: FULL_REVIEW / SCOPE_REDUCED
+- **COMMIT**: output of `git rev-parse --short HEAD`
+
+## Review Readiness Dashboard
+
+After completing the review, read the review log and config to display the dashboard.
+
+```bash
+~/.claude/skills/gstack/bin/gstack-review-read
+```
+
+Parse the output. Find the most recent entry for each skill (plan-ceo-review, plan-eng-review, review, plan-design-review, design-review-lite, adversarial-review, codex-review, codex-plan-review). Ignore entries with timestamps older than 7 days. For the Eng Review row, show whichever is more recent between `review` (diff-scoped pre-landing review) and `plan-eng-review` (plan-stage architecture review). Append "(DIFF)" or "(PLAN)" to the status to distinguish. For the Adversarial row, show whichever is more recent between `adversarial-review` (new auto-scaled) and `codex-review` (legacy). For Design Review, show whichever is more recent between `plan-design-review` (full visual audit) and `design-review-lite` (code-level check). Append "(FULL)" or "(LITE)" to the status to distinguish. For the Outside Voice row, show the most recent `codex-plan-review` entry — this captures outside voices from both /plan-ceo-review and /plan-eng-review.
+
+**Source attribution:** If the most recent entry for a skill has a \`"via"\` field, append it to the status label in parentheses. Examples: `plan-eng-review` with `via:"autoplan"` shows as "CLEAR (PLAN via /autoplan)". `review` with `via:"ship"` shows as "CLEAR (DIFF via /ship)". Entries without a `via` field show as "CLEAR (PLAN)" or "CLEAR (DIFF)" as before.
+
+Note: `autoplan-voices` and `design-outside-voices` entries are audit-trail-only (forensic data for cross-model consensus analysis). They do not appear in the dashboard and are not checked by any consumer.
+
+Display:
+
+```
++====================================================================+
+|                    REVIEW READINESS DASHBOARD                       |
++====================================================================+
+| Review          | Runs | Last Run            | Status    | Required |
+|-----------------|------|---------------------|-----------|----------|
+| Eng Review      |  1   | 2026-03-16 15:00    | CLEAR     | YES      |
+| CEO Review      |  0   | —                   | —         | no       |
+| Design Review   |  0   | —                   | —         | no       |
+| Adversarial     |  0   | —                   | —         | no       |
+| Outside Voice   |  0   | —                   | —         | no       |
++--------------------------------------------------------------------+
+| VERDICT: CLEARED — Eng Review passed                                |
++====================================================================+
+```
+
+**Review tiers:**
+- **Eng Review (required by default):** The only review that gates shipping. Covers architecture, code quality, tests, performance. Can be disabled globally with \`gstack-config set skip_eng_review true\` (the "don't bother me" setting).
+- **CEO Review (optional):** Use your judgment. Recommend it for big product/business changes, new user-facing features, or scope decisions. Skip for bug fixes, refactors, infra, and cleanup.
+- **Design Review (optional):** Use your judgment. Recommend it for UI/UX changes. Skip for backend-only, infra, or prompt-only changes.
+- **Adversarial Review (automatic):** Always-on for every review. Every diff gets both Claude adversarial subagent and Codex adversarial challenge. Large diffs (200+ lines) additionally get Codex structured review with P1 gate. No configuration needed.
+- **Outside Voice (optional):** Independent plan review from a different AI model. Offered after all review sections complete in /plan-ceo-review and /plan-eng-review. Falls back to Claude subagent if Codex is unavailable. Never gates shipping.
+
+**Verdict logic:**
+- **CLEARED**: Eng Review has >= 1 entry within 7 days from either \`review\` or \`plan-eng-review\` with status "clean" (or \`skip_eng_review\` is \`true\`)
+- **NOT CLEARED**: Eng Review missing, stale (>7 days), or has open issues
+- CEO, Design, and Codex reviews are shown for context but never block shipping
+- If \`skip_eng_review\` config is \`true\`, Eng Review shows "SKIPPED (global)" and verdict is CLEARED
+
+**Staleness detection:** After displaying the dashboard, check if any existing reviews may be stale:
+- Parse the \`---HEAD---\` section from the bash output to get the current HEAD commit hash
+- For each review entry that has a \`commit\` field: compare it against the current HEAD. If different, count elapsed commits: \`git rev-list --count STORED_COMMIT..HEAD\`. Display: "Note: {skill} review from {date} may be stale — {N} commits since review"
+- For entries without a \`commit\` field (legacy entries): display "Note: {skill} review from {date} has no commit tracking — consider re-running for accurate staleness detection"
+- If all reviews match the current HEAD, do not display any staleness notes
+
+## Plan File Review Report
+
+After displaying the Review Readiness Dashboard in conversation output, also update the
+**plan file** itself so review status is visible to anyone reading the plan.
+
+### Detect the plan file
+
+1. Check if there is an active plan file in this conversation (the host provides plan file
+   paths in system messages — look for plan file references in the conversation context).
+2. If not found, skip this section silently — not every review runs in plan mode.
+
+### Generate the report
+
+Read the review log output you already have from the Review Readiness Dashboard step above.
+Parse each JSONL entry. Each skill logs different fields:
+
+- **plan-ceo-review**: \`status\`, \`unresolved\`, \`critical_gaps\`, \`mode\`, \`scope_proposed\`, \`scope_accepted\`, \`scope_deferred\`, \`commit\`
+  → Findings: "{scope_proposed} proposals, {scope_accepted} accepted, {scope_deferred} deferred"
+  → If scope fields are 0 or missing (HOLD/REDUCTION mode): "mode: {mode}, {critical_gaps} critical gaps"
+- **plan-eng-review**: \`status\`, \`unresolved\`, \`critical_gaps\`, \`issues_found\`, \`mode\`, \`commit\`
+  → Findings: "{issues_found} issues, {critical_gaps} critical gaps"
+- **plan-design-review**: \`status\`, \`initial_score\`, \`overall_score\`, \`unresolved\`, \`decisions_made\`, \`commit\`
+  → Findings: "score: {initial_score}/10 → {overall_score}/10, {decisions_made} decisions"
+- **plan-devex-review**: \`status\`, \`initial_score\`, \`overall_score\`, \`product_type\`, \`tthw_current\`, \`tthw_target\`, \`mode\`, \`persona\`, \`competitive_tier\`, \`unresolved\`, \`commit\`
+  → Findings: "score: {initial_score}/10 → {overall_score}/10, TTHW: {tthw_current} → {tthw_target}"
+- **devex-review**: \`status\`, \`overall_score\`, \`product_type\`, \`tthw_measured\`, \`dimensions_tested\`, \`dimensions_inferred\`, \`boomerang\`, \`commit\`
+  → Findings: "score: {overall_score}/10, TTHW: {tthw_measured}, {dimensions_tested} tested/{dimensions_inferred} inferred"
+- **codex-review**: \`status\`, \`gate\`, \`findings\`, \`findings_fixed\`
+  → Findings: "{findings} findings, {findings_fixed}/{findings} fixed"
+
+All fields needed for the Findings column are now present in the JSONL entries.
+For the review you just completed, you may use richer details from your own Completion
+Summary. For prior reviews, use the JSONL fields directly — they contain all required data.
+
+Produce this markdown table:
+
+\`\`\`markdown
+## GSTACK REVIEW REPORT
+
+| Review | Trigger | Why | Runs | Status | Findings |
+|--------|---------|-----|------|--------|----------|
+| CEO Review | \`/plan-ceo-review\` | Scope & strategy | {runs} | {status} | {findings} |
+| Codex Review | \`/codex review\` | Independent 2nd opinion | {runs} | {status} | {findings} |
+| Eng Review | \`/plan-eng-review\` | Architecture & tests (required) | {runs} | {status} | {findings} |
+| Design Review | \`/plan-design-review\` | UI/UX gaps | {runs} | {status} | {findings} |
+| DX Review | \`/plan-devex-review\` | Developer experience gaps | {runs} | {status} | {findings} |
+\`\`\`
+
+Below the table, add these lines (omit any that are empty/not applicable):
+
+- **CODEX:** (only if codex-review ran) — one-line summary of codex fixes
+- **CROSS-MODEL:** (only if both Claude and Codex reviews exist) — overlap analysis
+- **UNRESOLVED:** total unresolved decisions across all reviews
+- **VERDICT:** list reviews that are CLEAR (e.g., "CEO + ENG CLEARED — ready to implement").
+  If Eng Review is not CLEAR and not skipped globally, append "eng review required".
+
+### Write to the plan file
+
+**PLAN MODE EXCEPTION — ALWAYS RUN:** This writes to the plan file, which is the one
+file you are allowed to edit in plan mode. The plan file review report is part of the
+plan's living status.
+
+The report must always be the LAST section of the plan file — never mid-file.
+Use a single delete-then-append flow:
+
+1. Read the plan file (Read tool) to see its full current content. Search the read
+   output for a \`## GSTACK REVIEW REPORT\` heading anywhere in the file.
+2. If found, use the Edit tool to DELETE the entire existing section. Match from
+   \`## GSTACK REVIEW REPORT\` through either the next \`## \` heading or end of
+   file, whichever comes first. Replace with the empty string. This applies
+   regardless of where the section currently lives — mid-file deletion is
+   intentional, not a special case. If the Edit fails (e.g., concurrent edit
+   changed the content), re-read the plan file and retry once.
+3. After the delete (or skipped, if no section existed), append the new
+   \`## GSTACK REVIEW REPORT\` section at the END of the file. Use the Edit
+   tool to match the file's current last paragraph and add the section after it,
+   or use Write to re-emit the whole file with the section at the end.
+4. Verify with the Read tool that \`## GSTACK REVIEW REPORT\` is the last
+   \`## \` heading in the file before continuing. If it isn't, repeat steps
+   2-3 once.
+
+Do NOT replace the section in place. The "replace mid-file" path is what allowed
+prior versions to leave the report mid-file when an older report already lived
+there — the user then sees a plan whose review report is not at the bottom and
+(correctly) rejects it.
+
+## Capture Learnings
+
+If you discovered a non-obvious pattern, pitfall, or architectural insight during
+this session, log it for future sessions:
+
+```bash
+~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"plan-eng-review","type":"TYPE","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"SOURCE","files":["path/to/relevant/file"]}'
+```
+
+**Types:** `pattern` (reusable approach), `pitfall` (what NOT to do), `preference`
+(user stated), `architecture` (structural decision), `tool` (library/framework insight),
+`operational` (project environment/CLI/workflow knowledge).
+
+**Sources:** `observed` (you found this in the code), `user-stated` (user told you),
+`inferred` (AI deduction), `cross-model` (both Claude and Codex agree).
+
+**Confidence:** 1-10. Be honest. An observed pattern you verified in the code is 8-9.
+An inference you're not sure about is 4-5. A user preference they explicitly stated is 10.
+
+**files:** Include the specific file paths this learning references. This enables
+staleness detection: if those files are later deleted, the learning can be flagged.
+
+**Only log genuine discoveries.** Don't log obvious things. Don't log things the user
+already knows. A good test: would this insight save time in a future session? If yes, log it.
+
+
+
+## Brain Calibration Write-Back (Phase 2 / gated)
+
+When the skill makes a typed prediction worth tracking (scope decision,
+TTHW target, architectural bet, wedge commitment), it MAY write a
+`kind=bet` take to the brain so a calibration profile builds over time.
+
+**Gated on two things:**
+1. Brain trust policy for the active endpoint is `personal` (check via
+   `~/.claude/skills/gstack/bin/gstack-config get brain_trust_policy@<endpoint-hash>`).
+   Shared brains skip write-back to avoid polluting team calibration.
+2. Feature flag `BRAIN_CALIBRATION_WRITEBACK` is set (today: false; flips
+   to true when upstream gbrain v0.42+ ships `takes_add` MCP op).
+
+When both gates pass, the write-back path uses `mcp__gbrain__takes_add`
+to record a take with weight 0.7 (per SKILL_CALIBRATION_WEIGHTS).
+If the MCP op is unavailable, fall back to `mcp__gbrain__put_page` with
+a gstack:takes fence block (documented but uglier path).
+
+Mandatory take frontmatter shape:
+```yaml
+kind: bet
+holder: <user identity from whoami>
+claim: <one-line prediction the skill is making>
+weight: 0.7
+since_date: <today's date>
+expected_resolution: <date in 1-3 months depending on skill>
+source_skill: plan-eng-review
+```
+
+After write, invalidate the affected digests so the next preflight reflects
+the new state:
+
+```bash
+eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true
+  # (no per-skill invalidation targets configured)
+```
+
+
+## Brain Cache Background Refresh
+
+After the skill's work completes (and telemetry has logged), kick a
+background refresh of any cache digest that's getting close to its TTL.
+This is non-blocking — the user doesn't wait. Next invocation benefits
+from the warm cache.
+
+```bash
+eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true
+(~/.claude/skills/gstack/bin/gstack-brain-cache refresh --project "$SLUG" 2>/dev/null &) || true
+```
+
+
+## Next Steps — Review Chaining
+
+After displaying the Review Readiness Dashboard, check if additional reviews would be valuable. Read the dashboard output to see which reviews have already been run and whether they are stale.
+
+**Suggest /plan-design-review if UI changes exist and no design review has been run** — detect from the test diagram, architecture review, or any section that touched frontend components, CSS, views, or user-facing interaction flows. If an existing design review's commit hash shows it predates significant changes found in this eng review, note that it may be stale.
+
+**Mention /plan-ceo-review if this is a significant product change and no CEO review exists** — this is a soft suggestion, not a push. CEO review is optional. Only mention it if the plan introduces new user-facing features, changes product direction, or expands scope substantially.
+
+**Note staleness** of existing CEO or design reviews if this eng review found assumptions that contradict them, or if the commit hash shows significant drift.
+
+**If no additional reviews are needed** (or `skip_eng_review` is `true` in the dashboard config, meaning this eng review was optional): state "All relevant reviews complete. Run /ship when ready."
+
+Use AskUserQuestion with only the applicable options:
+- **A)** Run /plan-design-review (only if UI scope detected and no design review exists)
+- **B)** Run /plan-ceo-review (only if significant product change and no CEO review exists)
+- **C)** Ready to implement — run /ship when done
+
+## Unresolved decisions
+If the user does not respond to an AskUserQuestion or interrupts to move on, note which decisions were left unresolved. At the end of the review, list these as "Unresolved decisions that may bite you later" — never silently default to an option.
+

plan-eng-review/sections/review-sections.md.tmpl

@@ -0,0 +1,222 @@
+## Review Sections (after scope is agreed)
+
+**Anti-skip rule:** Never condense, abbreviate, or skip any review section (1-4) regardless of plan type (strategy, spec, code, infra). Every section in this skill exists for a reason. "This is a strategy doc so implementation sections don't apply" is always wrong — implementation details are where strategy breaks down. If a section genuinely has zero findings, say "No issues found" and move on — but you must evaluate it.
+
+{{ANTI_SHORTCUT_CLAUSE}}
+
+{{LEARNINGS_SEARCH}}
+
+### 1. Architecture review
+Evaluate:
+* Overall system design and component boundaries.
+* Dependency graph and coupling concerns.
+* Data flow patterns and potential bottlenecks.
+* Scaling characteristics and single points of failure.
+* Security architecture (auth, data access, API boundaries).
+* Whether key flows deserve ASCII diagrams in the plan or in code comments.
+* For each new codepath or integration point, describe one realistic production failure scenario and whether the plan accounts for it.
+* **Distribution architecture:** If this introduces a new artifact (binary, package, container), how does it get built, published, and updated? Is the CI/CD pipeline part of the plan or deferred?
+
+For each issue found in this section, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Do NOT batch multiple issues into one AskUserQuestion. Use the preamble's AskUserQuestion Format section. The AskUserQuestion call is a tool_use, not prose — call the tool directly.
+
+**STOP.** Do NOT proceed to the next review section, edit the plan file with the proposed fix, or call ExitPlanMode until the user responds. An issue with an "obvious fix" is still an issue and still needs explicit user approval before it lands in the plan. Loading the AskUserQuestion schema via ToolSearch and then writing the recommendation as chat prose is the failure mode this gate exists to prevent.
+
+{{CONFIDENCE_CALIBRATION}}
+
+### 2. Code quality review
+Evaluate:
+* Code organization and module structure.
+* DRY violations—be aggressive here.
+* Error handling patterns and missing edge cases (call these out explicitly).
+* Technical debt hotspots.
+* Areas that are over-engineered or under-engineered relative to my preferences.
+* Existing ASCII diagrams in touched files — are they still accurate after this change?
+
+For each issue found in this section, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Do NOT batch multiple issues into one AskUserQuestion. Use the preamble's AskUserQuestion Format section. The AskUserQuestion call is a tool_use, not prose — call the tool directly.
+
+**STOP.** Do NOT proceed to the next review section, edit the plan file with the proposed fix, or call ExitPlanMode until the user responds. An issue with an "obvious fix" is still an issue and still needs explicit user approval before it lands in the plan. Loading the AskUserQuestion schema via ToolSearch and then writing the recommendation as chat prose is the failure mode this gate exists to prevent.
+
+### 3. Test review
+
+{{TEST_COVERAGE_AUDIT_PLAN}}
+
+For LLM/prompt changes: check the "Prompt/LLM changes" file patterns listed in CLAUDE.md. If this plan touches ANY of those patterns, state which eval suites must be run, which cases should be added, and what baselines to compare against. Then use AskUserQuestion to confirm the eval scope with the user.
+
+For each issue found in this section, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Do NOT batch multiple issues into one AskUserQuestion. Use the preamble's AskUserQuestion Format section. The AskUserQuestion call is a tool_use, not prose — call the tool directly.
+
+**STOP.** Do NOT proceed to the next review section, edit the plan file with the proposed fix, or call ExitPlanMode until the user responds. An issue with an "obvious fix" is still an issue and still needs explicit user approval before it lands in the plan. Loading the AskUserQuestion schema via ToolSearch and then writing the recommendation as chat prose is the failure mode this gate exists to prevent.
+
+### 4. Performance review
+Evaluate:
+* N+1 queries and database access patterns.
+* Memory-usage concerns.
+* Caching opportunities.
+* Slow or high-complexity code paths.
+
+For each issue found in this section, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Do NOT batch multiple issues into one AskUserQuestion. Use the preamble's AskUserQuestion Format section. The AskUserQuestion call is a tool_use, not prose — call the tool directly.
+
+**STOP.** Do NOT proceed to the next review section, edit the plan file with the proposed fix, or call ExitPlanMode until the user responds. An issue with an "obvious fix" is still an issue and still needs explicit user approval before it lands in the plan. Loading the AskUserQuestion schema via ToolSearch and then writing the recommendation as chat prose is the failure mode this gate exists to prevent.
+
+{{CODEX_PLAN_REVIEW}}
+
+### Outside Voice Integration Rule
+
+Outside voice findings are INFORMATIONAL until the user explicitly approves each one.
+Do NOT incorporate outside voice recommendations into the plan without presenting each
+finding via AskUserQuestion and getting explicit approval. This applies even when you
+agree with the outside voice. Cross-model consensus is a strong signal — present it as
+such — but the user makes the decision.
+
+## CRITICAL RULE — How to ask questions
+Follow the AskUserQuestion format from the Preamble above. Additional rules for plan reviews:
+* **One issue = one AskUserQuestion call.** Never combine multiple issues into one question.
+* Describe the problem concretely, with file and line references.
+* Present 2-3 options, including "do nothing" where that's reasonable.
+* For each option, specify in one line: effort (human: ~X / CC: ~Y), risk, and maintenance burden. If the complete option is only marginally more effort than the shortcut with CC, recommend the complete option.
+* **Map the reasoning to my engineering preferences above.** One sentence connecting your recommendation to a specific preference (DRY, explicit > clever, minimal diff, etc.).
+* Label with issue NUMBER + option LETTER (e.g., "3A", "3B").
+* **Coverage vs kind:** for every per-issue AskUserQuestion you raise in this review, decide whether the options differ in coverage or in kind. If coverage (e.g., more tests vs fewer, complete error handling vs happy-path-only, full edge-case coverage vs shortcut), include `Completeness: N/10` on each option. If kind (e.g., architectural choice between two different systems, posture-over-posture, A/B/C where each is a different kind of thing), skip the score and add one line: `Note: options differ in kind, not coverage — no completeness score.` Do NOT fabricate scores on kind-differentiated questions — filler scores are worse than no score.
+* **Zero findings:** if a section has zero findings, state "No issues, moving on" and proceed. Otherwise, use AskUserQuestion for each finding — a finding with an "obvious fix" is still a finding and still needs user approval before any change lands in the plan.
+
+## Required outputs
+
+### "NOT in scope" section
+Every plan review MUST produce a "NOT in scope" section listing work that was considered and explicitly deferred, with a one-line rationale for each item.
+
+### "What already exists" section
+List existing code/flows that already partially solve sub-problems in this plan, and whether the plan reuses them or unnecessarily rebuilds them.
+
+### TODOS.md updates
+After all review sections are complete, present each potential TODO as its own individual AskUserQuestion. Never batch TODOs — one per question. Never silently skip this step. Follow the format in `.claude/skills/review/TODOS-format.md`.
+
+For each TODO, describe:
+* **What:** One-line description of the work.
+* **Why:** The concrete problem it solves or value it unlocks.
+* **Pros:** What you gain by doing this work.
+* **Cons:** Cost, complexity, or risks of doing it.
+* **Context:** Enough detail that someone picking this up in 3 months understands the motivation, the current state, and where to start.
+* **Depends on / blocked by:** Any prerequisites or ordering constraints.
+
+Then present options: **A)** Add to TODOS.md **B)** Skip — not valuable enough **C)** Build it now in this PR instead of deferring.
+
+Do NOT just append vague bullet points. A TODO without context is worse than no TODO — it creates false confidence that the idea was captured while actually losing the reasoning.
+
+### Diagrams
+The plan itself should use ASCII diagrams for any non-trivial data flow, state machine, or processing pipeline. Additionally, identify which files in the implementation should get inline ASCII diagram comments — particularly Models with complex state transitions, Services with multi-step pipelines, and Concerns with non-obvious mixin behavior.
+
+### Failure modes
+For each new codepath identified in the test review diagram, list one realistic way it could fail in production (timeout, nil reference, race condition, stale data, etc.) and whether:
+1. A test covers that failure
+2. Error handling exists for it
+3. The user would 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
+
+Analyze the plan's implementation steps for parallel execution opportunities. This helps the user split work across git worktrees (via Claude Code's Agent tool with `isolation: "worktree"` or parallel workspaces).
+
+**Skip if:** all steps touch the same primary module, or the plan has fewer than 2 independent workstreams. In that case, write: "Sequential implementation, no parallelization opportunity."
+
+**Otherwise, produce:**
+
+1. **Dependency table** — for each implementation step/workstream:
+
+| Step | Modules touched | Depends on |
+|------|----------------|------------|
+| (step name) | (directories/modules, NOT specific files) | (other steps, or —) |
+
+Work at the module/directory level, not file level. Plans describe intent ("add API endpoints"), not specific files. Module-level ("controllers/, models/") is reliable; file-level is guesswork.
+
+2. **Parallel lanes** — group steps into lanes:
+   - Steps with no shared modules and no dependency go in separate lanes (parallel)
+   - Steps sharing a module directory go in the same lane (sequential)
+   - Steps depending on other steps go in later lanes
+
+Format: `Lane A: step1 → step2 (sequential, shared models/)` / `Lane B: step3 (independent)`
+
+3. **Execution order** — which lanes launch in parallel, which wait. Example: "Launch A + B in parallel worktrees. Merge both. Then C."
+
+4. **Conflict flags** — if two parallel lanes touch the same module directory, flag it: "Lanes X and Y both touch module/ — potential merge conflict. Consider sequential execution or careful coordination."
+
+{{TASKS_SECTION_EMIT:eng-review}}
+
+### Completion summary
+At the end of the review, fill in and display this summary so the user can see all findings at a glance:
+- 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
+- Outside voice: ran (codex/claude) / skipped
+- Parallelization: ___ lanes, ___ parallel / ___ sequential
+- Lake Score: X/Y recommendations chose complete option
+
+## Retrospective learning
+Check the git log for this branch. If there are prior commits suggesting a previous review cycle (e.g., review-driven refactors, reverted changes), note what was changed and whether the current plan touches the same areas. Be more aggressive reviewing areas that were previously problematic.
+
+## Formatting rules
+* NUMBER issues (1, 2, 3...) and LETTERS for options (A, B, C...).
+* Label with NUMBER + LETTER (e.g., "3A", "3B").
+* One sentence max per option. Pick in under 5 seconds.
+* After each review section, pause and ask for feedback before moving on.
+
+## Review Log
+
+After producing the Completion Summary above, persist the review result.
+
+**PLAN MODE EXCEPTION — ALWAYS RUN:** This command writes review metadata to
+`~/.gstack/` (user config directory, not project files). The skill preamble
+already writes to `~/.gstack/sessions/` and `~/.gstack/analytics/` — this is
+the same pattern. The review dashboard depends on this data. Skipping this
+command breaks the review readiness dashboard in /ship.
+
+```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"}'
+```
+
+Substitute values from the Completion Summary:
+- **TIMESTAMP**: current ISO 8601 datetime
+- **STATUS**: "clean" if 0 unresolved decisions AND 0 critical gaps; otherwise "issues_open"
+- **unresolved**: number from "Unresolved decisions" count
+- **critical_gaps**: number from "Failure modes: ___ critical gaps flagged"
+- **issues_found**: total issues found across all review sections (Architecture + Code Quality + Performance + Test gaps)
+- **MODE**: FULL_REVIEW / SCOPE_REDUCED
+- **COMMIT**: output of `git rev-parse --short HEAD`
+
+{{REVIEW_DASHBOARD}}
+
+{{PLAN_FILE_REVIEW_REPORT}}
+
+{{LEARNINGS_LOG}}
+
+{{GBRAIN_SAVE_RESULTS}}
+
+{{BRAIN_WRITE_BACK}}
+
+{{BRAIN_CACHE_REFRESH}}
+
+## Next Steps — Review Chaining
+
+After displaying the Review Readiness Dashboard, check if additional reviews would be valuable. Read the dashboard output to see which reviews have already been run and whether they are stale.
+
+**Suggest /plan-design-review if UI changes exist and no design review has been run** — detect from the test diagram, architecture review, or any section that touched frontend components, CSS, views, or user-facing interaction flows. If an existing design review's commit hash shows it predates significant changes found in this eng review, note that it may be stale.
+
+**Mention /plan-ceo-review if this is a significant product change and no CEO review exists** — this is a soft suggestion, not a push. CEO review is optional. Only mention it if the plan introduces new user-facing features, changes product direction, or expands scope substantially.
+
+**Note staleness** of existing CEO or design reviews if this eng review found assumptions that contradict them, or if the commit hash shows significant drift.
+
+**If no additional reviews are needed** (or `skip_eng_review` is `true` in the dashboard config, meaning this eng review was optional): state "All relevant reviews complete. Run /ship when ready."
+
+Use AskUserQuestion with only the applicable options:
+- **A)** Run /plan-design-review (only if UI scope detected and no design review exists)
+- **B)** Run /plan-ceo-review (only if significant product change and no CEO review exists)
+- **C)** Ready to implement — run /ship when done
+
+## Unresolved decisions
+If the user does not respond to an AskUserQuestion or interrupts to move on, note which decisions were left unresolved. At the end of the review, list these as "Unresolved decisions that may bite you later" — never silently default to an option.
+

plan-tune/SKILL.md

@@ -375,25 +375,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

qa-only/SKILL.md

@@ -365,25 +365,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

qa/SKILL.md

@@ -371,25 +371,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

retro/SKILL.md

@@ -382,25 +382,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

review/SKILL.md

@@ -367,25 +367,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

scrape/SKILL.md

@@ -363,25 +363,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

scripts/resolvers/preamble/generate-ask-user-format.ts

@@ -75,25 +75,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 \`docs/askuserquestion-split.md\` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \\u-escape.** When any
+**Non-ASCII characters — write directly, never \\u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as \`\\uXXXX\` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only \`\\n\`,
-    as \`\\uXXXX\`.** Claude Code's tool parameter pipe is UTF-8 native
+\`\\t\`, \`\\"\`, \`\\\\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+\`docs/askuserquestion-cjk.md\`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes \`\\u3103\` thinking it is 管 U+7BA1, but \`\\u3103\` is
-    actually ㄃, so the user sees \`管理工具\` rendered as \`㄃3用箱\`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: \`"question": "請選擇\\uXXXX\\uXXXX\\uXXXX\\uXXXX"\`
-    Right: \`"question": "請選擇管理工具"\`
-
-    Only JSON-mandatory escapes remain allowed: \`\\n\`, \`\\t\`, \`\\"\`, \`\\\\\`.
 
 ### Self-check before emitting
 

setup-deploy/SKILL.md

@@ -366,25 +366,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

setup-gbrain/SKILL.md

@@ -365,25 +365,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

ship/SKILL.md

@@ -367,25 +367,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

skillify/SKILL.md

@@ -363,25 +363,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

spec/SKILL.md

@@ -364,25 +364,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 
@@ -1375,25 +1362,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

sync-gbrain/SKILL.md

@@ -365,25 +365,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

test/auq-format-always-loaded.test.ts

@@ -0,0 +1,185 @@
+/**
+ * AUQ format is ALWAYS-LOADED — the token-reduction safety net (gate, free).
+ *
+ * The anxiety this kills: carving a skill into a small skeleton + on-demand
+ * `sections/*.md` could strand the AskUserQuestion decision-brief format (or a
+ * per-skill AUQ rule) in a section that is NOT in context when a question
+ * fires. The user would then see an AUQ with no ELI10, no Recommendation, no
+ * Pros/Cons — exactly the degradation we must guarantee never happens.
+ *
+ * The guarantee, made mechanical and per-PR:
+ *   1. UNIVERSAL — every interactive skill (anything that ships the
+ *      `## AskUserQuestion Format` block, i.e. preamble tier >= 2) carries the
+ *      FULL format spec in its always-loaded `SKILL.md` skeleton, NOT only in a
+ *      section. The preamble is always in context, so the format spec is present
+ *      the instant ANY question fires — Step 0, mode select, or a review finding.
+ *   2. REGRESSION — a known roster of interactive skills MUST still ship the
+ *      block. A botched carve that drops `{{PREAMBLE}}` from a skeleton fails
+ *      here in milliseconds instead of surfacing as a garbled question weeks
+ *      later.
+ *   3. CARVE-SAFETY — for skills that ARE carved (have a `sections/` dir), the
+ *      format block must live in `SKILL.md`, and any per-skill review-cadence
+ *      rule that moved into a section must still exist somewhere in the
+ *      skeleton+sections union (dropped-entirely is the failure).
+ *
+ * This is deterministic and free, so it runs on every `bun test`. It is the
+ * floor under the paid behavioral/substance/consistency E2Es.
+ */
+import { describe, test, expect } from 'bun:test';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const ROOT = path.resolve(__dirname, '..');
+
+/** Mandatory elements of the AskUserQuestion decision-brief format. Each is a
+ * label/marker the preamble resolver emits (generate-ask-user-format.ts) and
+ * that the model needs in context to render a compliant question. */
+const MANDATORY: Array<{ name: string; re: RegExp }> = [
+  { name: '## AskUserQuestion Format header', re: /##\s*AskUserQuestion Format/i },
+  { name: 'ELI10 label', re: /ELI10\s*:/i },
+  { name: 'Stakes-if-we-pick-wrong line', re: /Stakes if we pick wrong/i },
+  { name: 'Recommendation line (mandatory)', re: /Recommendation\s*:/i },
+  { name: '(recommended) label', re: /\(recommended\)/i },
+  { name: 'Pros / cons header', re: /Pros\s*\/\s*cons/i },
+  { name: '✅ pro bullet', re: /✅/ },
+  { name: '❌ con bullet', re: /❌/ },
+  { name: 'Net: synthesis line', re: /Net\s*:/i },
+  { name: 'Completeness coverage rule', re: /Completeness\s*:/i },
+  { name: 'kind-vs-coverage rule', re: /options differ in kind/i },
+  { name: 'Self-check checklist', re: /Self-check before emitting/i },
+];
+
+/** Per-skill AUQ rules that govern review-finding cadence. A carve may move
+ * these into a section (they fire only once the section is loaded), but they
+ * must never be DROPPED. Asserted against the skeleton+sections union. */
+const PER_SKILL_RULES: Record<string, RegExp[]> = {
+  'plan-ceo-review': [/One issue = one AskUserQuestion call/i],
+  'plan-eng-review': [/One issue = one AskUserQuestion call/i],
+  'plan-design-review': [/One issue = one AskUserQuestion call/i],
+  'plan-devex-review': [/One issue = one AskUserQuestion call/i],
+  // /codex emits its recommendation as prose; the instruction MUST stay in the
+  // always-loaded skeleton because codex has no on-demand section.
+  codex: [/Synthesis recommendation \(REQUIRED\)/i, /Recommendation\s*:\s*<action>\s*because/i],
+};
+
+/** Discover every repo-root skill dir that ships a generated SKILL.md. */
+function discoverSkills(): Array<{ skill: string; skillMd: string; sectionsDir: string | null }> {
+  return fs
+    .readdirSync(ROOT, { withFileTypes: true })
+    .filter(d => d.isDirectory())
+    .map(d => d.name)
+    .filter(skill => fs.existsSync(path.join(ROOT, skill, 'SKILL.md')))
+    .map(skill => {
+      const sectionsDir = path.join(ROOT, skill, 'sections');
+      return {
+        skill,
+        skillMd: path.join(ROOT, skill, 'SKILL.md'),
+        sectionsDir: fs.existsSync(sectionsDir) ? sectionsDir : null,
+      };
+    });
+}
+
+const skills = discoverSkills();
+/** A skill is "interactive" if its always-loaded SKILL.md ships the format
+ * block. That is the population that must be fully compliant. */
+const interactive = skills.filter(s =>
+  /##\s*AskUserQuestion Format/i.test(fs.readFileSync(s.skillMd, 'utf-8')),
+);
+
+/** Roster guard: these interactive skills MUST keep shipping the format block.
+ * If a carve/refactor drops it, this list still expects them and the membership
+ * test below fails. Derived from "fires AUQ at the user" — the plan/review/
+ * advisory skills plus codex. */
+const EXPECTED_INTERACTIVE = [
+  'plan-ceo-review',
+  'plan-eng-review',
+  'plan-design-review',
+  'plan-devex-review',
+  'office-hours',
+  'ship',
+  'review',
+  'qa',
+  'qa-only',
+  'codex',
+  'autoplan',
+  'cso',
+  'investigate',
+  'retro',
+  'design-review',
+  'design-consultation',
+  'spec',
+  'land-and-deploy',
+];
+
+describe('AUQ format is always-loaded (token-reduction safety net)', () => {
+  test('discovered a sane number of interactive skills', () => {
+    // Guards against a glob/path regression that would make the per-skill
+    // loop vacuously pass with zero skills.
+    expect(interactive.length).toBeGreaterThanOrEqual(15);
+  });
+
+  test('every expected interactive skill still ships the AUQ format block', () => {
+    const names = new Set(interactive.map(s => s.skill));
+    const missing = EXPECTED_INTERACTIVE.filter(s => !names.has(s));
+    if (missing.length > 0) {
+      throw new Error(
+        `These skills lost their always-loaded AskUserQuestion format block ` +
+          `(a carve or refactor likely dropped {{PREAMBLE}} from the skeleton):\n` +
+          missing.map(s => `  - ${s}/SKILL.md`).join('\n'),
+      );
+    }
+  });
+
+  for (const { skill, skillMd } of interactive) {
+    test(`${skill}: full AUQ format spec present in always-loaded SKILL.md`, () => {
+      const body = fs.readFileSync(skillMd, 'utf-8');
+      const gaps = MANDATORY.filter(m => !m.re.test(body));
+      if (gaps.length > 0) {
+        throw new Error(
+          `${skill}/SKILL.md (the always-loaded skeleton) is missing ${gaps.length} ` +
+            `mandatory AUQ format element(s) — a question firing here would degrade:\n` +
+            gaps.map(g => `  - ${g.name} (${g.re.source})`).join('\n'),
+        );
+      }
+    });
+  }
+
+  // CARVE-SAFETY: for carved skills, the format block must be in the SKELETON,
+  // not only a section. (The per-skill loop above already reads SKILL.md, so
+  // this is an explicit, named guard for the exact failure mode.)
+  for (const { skill, skillMd, sectionsDir } of skills.filter(s => s.sectionsDir)) {
+    test(`${skill} (carved): AUQ format block lives in the skeleton, not only sections/`, () => {
+      const body = fs.readFileSync(skillMd, 'utf-8');
+      expect(body).toMatch(/##\s*AskUserQuestion Format/i);
+      expect(body).toMatch(/ELI10\s*:/i);
+      expect(body).toMatch(/Recommendation\s*:/i);
+      // sanity: confirm there really is a section dir we're guarding against
+      expect(fs.readdirSync(sectionsDir!).some(f => f.endsWith('.md'))).toBe(true);
+    });
+  }
+
+  // PER-SKILL RULES: review-cadence rules may move into a section, but must
+  // never be dropped from the skeleton+sections union.
+  for (const [skill, rules] of Object.entries(PER_SKILL_RULES)) {
+    test(`${skill}: per-skill AUQ rules survive in skeleton+sections union`, () => {
+      const skillDir = path.join(ROOT, skill);
+      if (!fs.existsSync(path.join(skillDir, 'SKILL.md'))) {
+        throw new Error(`${skill}/SKILL.md not found — roster is stale`);
+      }
+      let union = fs.readFileSync(path.join(skillDir, 'SKILL.md'), 'utf-8');
+      const secDir = path.join(skillDir, 'sections');
+      if (fs.existsSync(secDir)) {
+        for (const f of fs.readdirSync(secDir).filter(f => f.endsWith('.md') && !f.endsWith('.md.tmpl'))) {
+          union += '\n' + fs.readFileSync(path.join(secDir, f), 'utf-8');
+        }
+      }
+      const dropped = rules.filter(re => !re.test(union));
+      if (dropped.length > 0) {
+        throw new Error(
+          `${skill}: per-skill AUQ rule(s) dropped from skeleton+sections union:\n` +
+            dropped.map(re => `  - ${re.source}`).join('\n'),
+        );
+      }
+    });
+  }
+});

test/codex-e2e-recommendation-substance.test.ts

@@ -0,0 +1,103 @@
+/**
+ * /codex recommendation substance — LIVE grade (periodic, paid, Codex CLI).
+ *
+ * The gap this closes: skill-cross-model-recommendation-emit.test.ts only checks
+ * the /codex TEMPLATE contains the "Recommendation: <action> because <reason>"
+ * instruction (static grep). llm-judge-recommendation.test.ts grades the rubric
+ * against FIXTURES. Nothing runs /codex live and grades the recommendation it
+ * actually emits. The user reports codex recommendations were the least
+ * consistent surface on main — so this is the one that needs live coverage.
+ *
+ * Method: drive the real /codex skill via codex exec (isolated temp HOME) over a
+ * small, deliberately-flawed fixture diff. Capture codex's output, extract its
+ * synthesis "Recommendation: ... because ..." line, and grade it with the same
+ * judgeRecommendation() rubric used everywhere else:
+ *   - present     : a Recommendation line exists
+ *   - commits     : names exactly one action (no hedging)
+ *   - has_because : a because-clause follows
+ *   - substance>=4: the reason is option-specific / names a concrete tradeoff,
+ *                   not boilerplate ("because it's better")
+ *
+ * Periodic tier (Codex non-determinism, ~$2-3/run).
+ */
+import { describe, test, expect } from 'bun:test';
+import * as path from 'node:path';
+import { runCodexSkill } from './helpers/codex-session-runner';
+import { judgeRecommendation } from './helpers/llm-judge';
+
+const ROOT = path.resolve(import.meta.dir, '..');
+
+const CODEX_AVAILABLE = (() => {
+  try {
+    return Bun.spawnSync(['which', 'codex']).exitCode === 0;
+  } catch {
+    return false;
+  }
+})();
+const shouldRun =
+  CODEX_AVAILABLE && !!process.env.EVALS && process.env.EVALS_TIER === 'periodic';
+const describeCodex = shouldRun ? describe : describe.skip;
+
+// A small fixture with two real, comparable problems so a good recommendation
+// must CHOOSE (and justify the choice against the alternative) — the exact
+// shape judgeRecommendation scores >= 4.
+const FIXTURE_DIFF = `
+Review this change. It has more than one issue; finish with a single synthesis
+recommendation line in your skill's required format: "Recommendation: <action>
+because <one-line reason that names the most important finding and why it beats
+the alternative>."
+
+--- a/server/auth.ts
++++ b/server/auth.ts
+@@
+ export function login(req, res) {
+-  const user = db.query("SELECT * FROM users WHERE name = ?", [req.body.name]);
++  const user = db.query("SELECT * FROM users WHERE name = '" + req.body.name + "'");
+   if (user && user.password === req.body.password) {
+     res.cookie('session', user.id);  // no HttpOnly, no Secure, no expiry
+     return res.json({ ok: true });
+   }
+   return res.status(401).json({ ok: false });
+ }
+`;
+
+describeCodex('/codex recommendation substance (live, periodic)', () => {
+  test(
+    'codex emits a committed, substance>=4 synthesis recommendation',
+    async () => {
+      const result = await runCodexSkill({
+        skillDir: path.join(ROOT, 'codex'),
+        skillName: 'codex',
+        prompt: FIXTURE_DIFF,
+        timeoutMs: 300_000,
+      });
+
+      if (result.output.startsWith('SKIP:')) {
+        // codex binary missing — describeCodex already guards, but double-safe.
+        return;
+      }
+
+      const score = await judgeRecommendation(result.output);
+      // eslint-disable-next-line no-console
+      console.log(
+        `[codex-rec] present=${score.present} commits=${score.commits} ` +
+          `has_because=${score.has_because} substance=${score.reason_substance}\n` +
+          `  reason: ${score.reason_text}`,
+      );
+
+      expect(score.present).toBe(true);
+      expect(score.has_because).toBe(true);
+      expect(score.commits).toBe(true);
+      // The named weak spot: substance must clear the boilerplate bar.
+      if (score.reason_substance < 4) {
+        throw new Error(
+          `codex recommendation substance ${score.reason_substance} < 4 (boilerplate/weak):\n` +
+            `  reason: ${score.reason_text}\n` +
+            `  judge: ${score.reasoning}\n` +
+            `--- codex output (last 2KB) ---\n${result.output.slice(-2000)}`,
+        );
+      }
+    },
+    360_000,
+  );
+});

test/fixtures/golden/claude-ship-SKILL.md

@@ -367,25 +367,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

test/fixtures/golden/codex-ship-SKILL.md

@@ -353,25 +353,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

test/fixtures/golden/factory-ship-SKILL.md

@@ -355,25 +355,12 @@ so split chains are never AUTO_DECIDE-eligible — the user's option set is sacr
 **Full rule + worked examples + Hold/dependency semantics:** see
 `docs/askuserquestion-split.md` in the gstack repo. Read on demand when N>4.
 
-**Non-ASCII characters — write directly, never \u-escape.** When any
+**Non-ASCII characters — write directly, never \u-escape.** When any string
-    string field (question, option label, option description) contains
+field contains Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text,
-    Chinese (繁體/簡體), Japanese, Korean, or other non-ASCII text, emit
+emit the literal UTF-8 characters; never escape them as `\uXXXX` (the pipe is
-    the literal UTF-8 characters in the JSON string. **Never escape them
+UTF-8 native, and manual escaping miscodes long CJK strings). Only `\n`,
-    as `\uXXXX`.** Claude Code's tool parameter pipe is UTF-8 native
+`\t`, `\"`, `\\` remain allowed. Full rationale + worked example: see
-    and passes characters through unchanged. Manually escaping requires
+`docs/askuserquestion-cjk.md`. Read on demand when a question contains CJK.
-    recalling each codepoint from training, which is unreliable for long
-    CJK strings — the model regularly emits the wrong codepoint (e.g.
-    writes `\u3103` thinking it is 管 U+7BA1, but `\u3103` is
-    actually ㄃, so the user sees `管理工具` rendered as `㄃3用箱`).
-    The trigger is long, multi-line questions with hundreds of CJK
-    characters: that is exactly when reflexive escaping kicks in and
-    exactly when miscoding is most damaging. Long ≠ escape. Keep
-    characters literal.
-
-    Wrong: `"question": "請選擇\uXXXX\uXXXX\uXXXX\uXXXX"`
-    Right: `"question": "請選擇管理工具"`
-
-    Only JSON-mandatory escapes remain allowed: `\n`, `\t`, `\"`, `\\`.
 
 ### Self-check before emitting
 

test/gbrain-detection-override.test.ts

@@ -105,7 +105,12 @@ describe('gbrain detection override → gen-skill-docs', () => {
   // Single skill probe is enough to assert the override pipeline. The
   // resolver unit test (test/resolvers-gbrain-save-results.test.ts) covers
   // per-skill metadata correctness already.
-  const PROBE_FILES = ['office-hours/SKILL.md'];
+  // office-hours is carved (v2 plan T9): GBRAIN_CONTEXT_LOAD stays in the
+  // skeleton, GBRAIN_SAVE_RESULTS moved into sections/design-and-handoff.md.
+  // Probe the union so the detection override is asserted wherever the blocks land.
+  const PROBE_FILES = ['office-hours/SKILL.md', 'office-hours/sections/design-and-handoff.md'];
+  const probeUnion = (snap: Map<string, string>): string =>
+    (snap.get('office-hours/SKILL.md') ?? '') + '\n' + (snap.get('office-hours/sections/design-and-handoff.md') ?? '');
 
   test('with detected:true, Claude-host SKILL.md gains brain-aware blocks', () => {
     const { tmpHome, cleanup } = makeFixture(
@@ -117,7 +122,7 @@ describe('gbrain detection override → gen-skill-docs', () => {
         tmpHome,
         files: PROBE_FILES,
       });
-      const content = snap.get('office-hours/SKILL.md')!;
+      const content = probeUnion(snap);
 
       // GBRAIN_SAVE_RESULTS un-suppressed → resolver output rendered.
       expect(content).toContain('## Save Results to Brain');
@@ -141,7 +146,7 @@ describe('gbrain detection override → gen-skill-docs', () => {
         tmpHome,
         files: PROBE_FILES,
       });
-      const content = snap.get('office-hours/SKILL.md')!;
+      const content = probeUnion(snap);
 
       // GBRAIN_SAVE_RESULTS suppressed → no rendered block, no gbrain put line.
       expect(content).not.toContain('gbrain put "office-hours/');
@@ -162,7 +167,7 @@ describe('gbrain detection override → gen-skill-docs', () => {
         tmpHome,
         files: PROBE_FILES,
       });
-      const content = snap.get('office-hours/SKILL.md')!;
+      const content = probeUnion(snap);
       expect(content).not.toContain('gbrain put "office-hours/');
     } finally {
       cleanup();
@@ -183,7 +188,7 @@ describe('gbrain detection override → gen-skill-docs', () => {
         tmpHome,
         files: PROBE_FILES,
       });
-      const content = snap.get('office-hours/SKILL.md')!;
+      const content = probeUnion(snap);
       expect(content).not.toContain('gbrain put "office-hours/');
       expect(content).not.toContain('## Save Results to Brain');
     } finally {

test/gen-skill-docs.test.ts

@@ -383,7 +383,7 @@ describe('gen-skill-docs', () => {
   });
 
   test('voice and writing-style preamble sections stay compact', () => {
-    const content = fs.readFileSync(path.join(ROOT, 'plan-eng-review', 'SKILL.md'), 'utf-8');
+    const content = readSkillUnion('plan-eng-review'); // carved: review body moved to section
     const voice = extractMarkdownSection(content, '## Voice');
     const writingStyle = extractMarkdownSection(content, '## Writing Style');
 
@@ -392,7 +392,7 @@ describe('gen-skill-docs', () => {
   });
 
   test('slim voice section preserves the gstack voice contract', () => {
-    const content = fs.readFileSync(path.join(ROOT, 'plan-eng-review', 'SKILL.md'), 'utf-8');
+    const content = readSkillUnion('plan-eng-review'); // carved: review body moved to section
     const voice = extractMarkdownSection(content, '## Voice');
 
     expect(voice).toMatch(/lead with the point|direct/i);
@@ -672,7 +672,7 @@ describe('REVIEW_DASHBOARD resolver', () => {
 
   for (const skill of REVIEW_SKILLS) {
     test(`review dashboard appears in ${skill} generated file`, () => {
-      const content = fs.readFileSync(path.join(ROOT, skill, 'SKILL.md'), 'utf-8');
+      const content = readSkillUnion(skill); // carved skills: union skeleton + sections
       expect(content).toContain('gstack-review');
       expect(content).toContain('REVIEW READINESS DASHBOARD');
     });
@@ -693,13 +693,13 @@ describe('REVIEW_DASHBOARD resolver', () => {
   });
 
   test('shared dashboard propagates review source to plan-eng-review', () => {
-    const content = fs.readFileSync(path.join(ROOT, 'plan-eng-review', 'SKILL.md'), 'utf-8');
+    const content = readSkillUnion('plan-eng-review'); // carved: review body moved to section
     expect(content).toContain('plan-eng-review, review, plan-design-review');
     expect(content).toContain('`review` (diff-scoped pre-landing review)');
   });
 
   test('resolver output contains key dashboard elements', () => {
-    const content = fs.readFileSync(path.join(ROOT, 'plan-ceo-review', 'SKILL.md'), 'utf-8');
+    const content = readSkillUnion('plan-ceo-review'); // carved: dashboard moved to section
     expect(content).toContain('VERDICT');
     expect(content).toContain('CLEARED');
     expect(content).toContain('Eng Review');
@@ -709,25 +709,25 @@ describe('REVIEW_DASHBOARD resolver', () => {
   });
 
   test('dashboard bash block includes git HEAD for staleness detection', () => {
-    const content = fs.readFileSync(path.join(ROOT, 'plan-ceo-review', 'SKILL.md'), 'utf-8');
+    const content = readSkillUnion('plan-ceo-review'); // carved: dashboard moved to section
     expect(content).toContain('git rev-parse --short HEAD');
     expect(content).toContain('---HEAD---');
   });
 
   test('dashboard includes staleness detection prose', () => {
-    const content = fs.readFileSync(path.join(ROOT, 'plan-ceo-review', 'SKILL.md'), 'utf-8');
+    const content = readSkillUnion('plan-ceo-review'); // carved: dashboard moved to section
     expect(content).toContain('Staleness detection');
     expect(content).toContain('commit');
   });
 
   for (const skill of REVIEW_SKILLS) {
     test(`${skill} contains review chaining section`, () => {
-      const content = fs.readFileSync(path.join(ROOT, skill, 'SKILL.md'), 'utf-8');
+      const content = readSkillUnion(skill); // carved skills: union skeleton + sections
       expect(content).toContain('Review Chaining');
     });
 
     test(`${skill} Review Log includes commit field`, () => {
-      const content = fs.readFileSync(path.join(ROOT, skill, 'SKILL.md'), 'utf-8');
+      const content = readSkillUnion(skill); // carved skills: union skeleton + sections
       expect(content).toContain('"commit"');
     });
   }
@@ -739,13 +739,13 @@ describe('REVIEW_DASHBOARD resolver', () => {
   });
 
   test('plan-eng-review chaining mentions design and ceo reviews', () => {
-    const content = fs.readFileSync(path.join(ROOT, 'plan-eng-review', 'SKILL.md'), 'utf-8');
+    const content = readSkillUnion('plan-eng-review'); // carved: review body moved to section
     expect(content).toContain('/plan-design-review');
     expect(content).toContain('/plan-ceo-review');
   });
 
   test('plan-design-review chaining mentions eng, ceo, and design skills', () => {
-    const content = fs.readFileSync(path.join(ROOT, 'plan-design-review', 'SKILL.md'), 'utf-8');
+    const content = readSkillUnion('plan-design-review');
     expect(content).toContain('/plan-eng-review');
     expect(content).toContain('/plan-ceo-review');
     expect(content).toContain('/design-shotgun');
@@ -761,7 +761,7 @@ describe('REVIEW_DASHBOARD resolver', () => {
 // ─── Test Coverage Audit Resolver Tests ─────────────────────
 
 describe('TEST_COVERAGE_AUDIT placeholders', () => {
-  const planSkill = fs.readFileSync(path.join(ROOT, 'plan-eng-review', 'SKILL.md'), 'utf-8');
+  const planSkill = readSkillUnion('plan-eng-review'); // carved
   const shipSkill = readShipUnion();
   const reviewSkill = fs.readFileSync(path.join(ROOT, 'review', 'SKILL.md'), 'utf-8');
 
@@ -969,7 +969,7 @@ describe('PLAN_FILE_REVIEW_REPORT resolver', () => {
   }
 
   test('resolver output contains key report elements', () => {
-    const content = fs.readFileSync(path.join(ROOT, 'plan-ceo-review', 'SKILL.md'), 'utf-8');
+    const content = readSkillUnion('plan-ceo-review'); // carved: report writer moved to section
     expect(content).toContain('Trigger');
     expect(content).toContain('Findings');
     expect(content).toContain('VERDICT');
@@ -1144,7 +1144,7 @@ describe('Retro plan completion section', () => {
 describe('Plan status footer in preamble', () => {
   test('preamble contains plan status footer as neutral forward reference to EXIT PLAN MODE GATE', () => {
     // Read any skill that uses PREAMBLE
-    const content = fs.readFileSync(path.join(ROOT, 'office-hours', 'SKILL.md'), 'utf-8');
+    const content = readSkillUnion('office-hours'); // carved: Phase 5/6 prose moved to section
     expect(content).toContain('Plan Status Footer');
     expect(content).toContain('GSTACK REVIEW REPORT');
     expect(content).toContain('ExitPlanMode');
@@ -1179,7 +1179,7 @@ describe('make-pdf setup ordering', () => {
 
 describe('Skill invocation during plan mode in preamble', () => {
   test('preamble contains skill invocation plan mode section', () => {
-    const content = fs.readFileSync(path.join(ROOT, 'office-hours', 'SKILL.md'), 'utf-8');
+    const content = readSkillUnion('office-hours'); // carved: Phase 5/6 prose moved to section
     expect(content).toContain('Skill Invocation During Plan Mode');
     expect(content).toContain('precedence over generic plan mode behavior');
     expect(content).toContain('Do not continue the workflow');
@@ -1190,7 +1190,7 @@ describe('Skill invocation during plan mode in preamble', () => {
 // --- {{SPEC_REVIEW_LOOP}} resolver tests ---
 
 describe('SPEC_REVIEW_LOOP resolver', () => {
-  const content = fs.readFileSync(path.join(ROOT, 'office-hours', 'SKILL.md'), 'utf-8');
+  const content = readSkillUnion('office-hours'); // carved: Phase 5/6 prose moved to section
 
   test('contains all 5 review dimensions', () => {
     for (const dim of ['Completeness', 'Consistency', 'Clarity', 'Scope', 'Feasibility']) {
@@ -1226,7 +1226,7 @@ describe('SPEC_REVIEW_LOOP resolver', () => {
 // --- {{DESIGN_SKETCH}} resolver tests ---
 
 describe('DESIGN_SKETCH resolver', () => {
-  const content = fs.readFileSync(path.join(ROOT, 'office-hours', 'SKILL.md'), 'utf-8');
+  const content = readSkillUnion('office-hours'); // carved: Phase 5/6 prose moved to section
 
   test('references DESIGN.md for design system constraints', () => {
     expect(content).toContain('DESIGN.md');
@@ -1256,7 +1256,7 @@ describe('DESIGN_SKETCH resolver', () => {
 // --- {{CODEX_SECOND_OPINION}} resolver tests ---
 
 describe('CODEX_SECOND_OPINION resolver', () => {
-  const content = fs.readFileSync(path.join(ROOT, 'office-hours', 'SKILL.md'), 'utf-8');
+  const content = readSkillUnion('office-hours'); // carved: Phase 5/6 prose moved to section
   const codexContent = fs.readFileSync(path.join(ROOT, '.agents', 'skills', 'gstack-office-hours', 'SKILL.md'), 'utf-8');
 
   test('Phase 3.5 section appears in office-hours SKILL.md', () => {
@@ -1369,7 +1369,7 @@ describe('Codex filesystem boundary', () => {
 
 describe('BENEFITS_FROM resolver', () => {
   const ceoContent = fs.readFileSync(path.join(ROOT, 'plan-ceo-review', 'SKILL.md'), 'utf-8');
-  const engContent = fs.readFileSync(path.join(ROOT, 'plan-eng-review', 'SKILL.md'), 'utf-8');
+  const engContent = readSkillUnion('plan-eng-review'); // carved
 
   test('plan-ceo-review contains prerequisite skill offer', () => {
     expect(ceoContent).toContain('Prerequisite Skill Offer');
@@ -1551,7 +1551,7 @@ describe('preamble routing injection', () => {
 
 describe('DESIGN_OUTSIDE_VOICES resolver', () => {
   test('plan-design-review contains outside voices section', () => {
-    const content = fs.readFileSync(path.join(ROOT, 'plan-design-review', 'SKILL.md'), 'utf-8');
+    const content = readSkillUnion('plan-design-review');
     expect(content).toContain('Design Outside Voices');
     expect(content).toContain('CODEX_AVAILABLE');
     expect(content).toContain('LITMUS SCORECARD');
@@ -1570,7 +1570,7 @@ describe('DESIGN_OUTSIDE_VOICES resolver', () => {
   });
 
   test('branches correctly per skillName — different prompts', () => {
-    const planContent = fs.readFileSync(path.join(ROOT, 'plan-design-review', 'SKILL.md'), 'utf-8');
+    const planContent = readSkillUnion('plan-design-review');
     const consultContent = fs.readFileSync(path.join(ROOT, 'design-consultation', 'SKILL.md'), 'utf-8');
     // plan-design-review uses analytical prompt (high reasoning)
     expect(planContent).toContain('model_reasoning_effort="high"');
@@ -1583,7 +1583,7 @@ describe('DESIGN_OUTSIDE_VOICES resolver', () => {
 
 describe('DESIGN_HARD_RULES resolver', () => {
   test('plan-design-review Pass 4 contains hard rules', () => {
-    const content = fs.readFileSync(path.join(ROOT, 'plan-design-review', 'SKILL.md'), 'utf-8');
+    const content = readSkillUnion('plan-design-review');
     expect(content).toContain('Design Hard Rules');
     expect(content).toContain('Classifier');
     expect(content).toContain('MARKETING/LANDING PAGE');
@@ -1596,26 +1596,26 @@ describe('DESIGN_HARD_RULES resolver', () => {
   });
 
   test('includes all 3 rule sets', () => {
-    const content = fs.readFileSync(path.join(ROOT, 'plan-design-review', 'SKILL.md'), 'utf-8');
+    const content = readSkillUnion('plan-design-review');
     expect(content).toContain('Landing page rules');
     expect(content).toContain('App UI rules');
     expect(content).toContain('Universal rules');
   });
 
   test('references shared AI slop blacklist items', () => {
-    const content = fs.readFileSync(path.join(ROOT, 'plan-design-review', 'SKILL.md'), 'utf-8');
+    const content = readSkillUnion('plan-design-review');
     expect(content).toContain('3-column feature grid');
     expect(content).toContain('Purple/violet/indigo');
   });
 
   test('includes OpenAI hard rejection criteria', () => {
-    const content = fs.readFileSync(path.join(ROOT, 'plan-design-review', 'SKILL.md'), 'utf-8');
+    const content = readSkillUnion('plan-design-review');
     expect(content).toContain('Generic SaaS card grid');
     expect(content).toContain('Carousel with no narrative purpose');
   });
 
   test('includes OpenAI litmus checks', () => {
-    const content = fs.readFileSync(path.join(ROOT, 'plan-design-review', 'SKILL.md'), 'utf-8');
+    const content = readSkillUnion('plan-design-review');
     expect(content).toContain('Brand/product unmistakable');
     expect(content).toContain('premium with all decorative shadows removed');
   });
@@ -1624,7 +1624,7 @@ describe('DESIGN_HARD_RULES resolver', () => {
 // --- Extended DESIGN_SKETCH resolver tests ---
 
 describe('DESIGN_SKETCH extended with outside voices', () => {
-  const content = fs.readFileSync(path.join(ROOT, 'office-hours', 'SKILL.md'), 'utf-8');
+  const content = readSkillUnion('office-hours'); // carved: Phase 5/6 prose moved to section
 
   test('contains outside design voices step', () => {
     expect(content).toContain('Outside design voices');
@@ -2649,7 +2649,7 @@ describe('community fixes wave', () => {
 
   // #510 — Context warnings: plan-eng-review has explicit anti-warning
   test('plan-eng-review/SKILL.md contains "Do not preemptively warn"', () => {
-    const content = fs.readFileSync(path.join(ROOT, 'plan-eng-review', 'SKILL.md'), 'utf-8');
+    const content = readSkillUnion('plan-eng-review'); // carved: review body moved to section
     expect(content).toContain('Do not preemptively warn');
   });
 
@@ -3112,7 +3112,9 @@ describe('GSTACK REVIEW REPORT delete-then-append flow', () => {
 
   for (const skill of PLAN_REVIEW_SKILLS) {
     test(`${skill}/SKILL.md prescribes delete-then-append, not in-place replace`, () => {
-      const content = fs.readFileSync(path.join(ROOT, skill, 'SKILL.md'), 'utf-8');
+      // Carved skills (v2 plan Phase B) relocate the review-report prose into
+      // sections/*.md; readSkillUnion follows the content wherever the carve put it.
+      const content = readSkillUnion(skill);
 
       // The new (correct) instruction must be present.
       expect(content).toContain('delete-then-append flow');

test/helpers/auq-sdk-capture.ts

@@ -0,0 +1,280 @@
+/**
+ * SDK-based AUQ capture — the reliable way to grade AskUserQuestion content.
+ *
+ * Real-PTY capture is lossy for plan-mode AUQs: they render every option on one
+ * cursor-positioned logical line that stripAnsi can't reconstruct, so format
+ * predicates (ELI10:, Net:, ✅) silently miss even when the question is
+ * well-formed. This helper instead uses the `claude -p` SDK path (the same one
+ * skill-e2e-plan-format uses): the agent is told to WRITE the verbatim text of
+ * the AskUserQuestion it would have asked to a file. That captures exactly what
+ * the model GENERATES — the surface where carving could degrade quality — with
+ * zero rendering loss. The TTY rendering layer is identical for fat and slim
+ * skills, so it is not where token-reduction degradation can hide.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { runSkillTest } from './session-runner';
+
+const ROOT = path.resolve(__dirname, '..', '..');
+
+/** The 7 decision-brief format elements graded on the captured AUQ text. */
+export const AUQ_FORMAT_ELEMENTS: Array<{ field: string; re: RegExp }> = [
+  { field: 'ELI10:', re: /ELI10\s*:/i },
+  { field: 'Recommendation:', re: /Recommendation\s*:/i },
+  { field: 'Pros / cons:', re: /Pros\s*\/\s*cons/i },
+  { field: '✅', re: /✅/ },
+  { field: '❌', re: /❌/ },
+  { field: 'Net:', re: /Net\s*:/i },
+  { field: '(recommended)', re: /\(recommended\)/i },
+];
+
+export function scoreAuqFormat(text: string): { present: number; total: number; missing: string[] } {
+  const missing = AUQ_FORMAT_ELEMENTS.filter(e => !e.re.test(text)).map(e => e.field);
+  return { present: AUQ_FORMAT_ELEMENTS.length - missing.length, total: AUQ_FORMAT_ELEMENTS.length, missing };
+}
+
+/**
+ * Grade recommendation substance ROBUST to the connective. judgeRecommendation()
+ * keys on the literal "because" (correct for the spec, pinned by
+ * llm-judge-recommendation.test.ts), but skills routinely write equally
+ * substantive reasons as "Recommendation: A. <reason>" / "A — <reason>" /
+ * "A: <reason>". Grading those as substance-1 would make the matrix cry wolf on
+ * genuinely good recommendations. So we normalize a non-"because" connective to
+ * "because" purely for grading, then call the shared judge. We also report
+ * whether the ORIGINAL used the literal "because" — a soft style signal, since
+ * the format spec prefers it and the voice rule forbids the em-dash form.
+ *
+ * This does NOT touch judgeRecommendation or its pinned fixtures.
+ */
+export async function gradeAuqRecommendation(
+  text: string,
+): Promise<{ substance: number; present: boolean; hadLiteralBecause: boolean; reason: string }> {
+  const { judgeRecommendation } = await import('./llm-judge');
+  const recLine = text.match(/^[*_]*\s*recommendation\s*[*_]*\s*:\s*(.+)$/im);
+  const hadLiteralBecause = !!recLine && /\bbecause\s+\S/i.test(recLine[1]);
+
+  let graded = text;
+  if (recLine && !hadLiteralBecause) {
+    // Rewrite "Recommendation: <choice><sep><reason>" → "...<choice> because <reason>"
+    // sep ∈ {". ", " — ", " - ", ": "} right after a short choice token.
+    const normalizedLine = recLine[1].replace(
+      /^([^.:—-]{1,40}?)\s*(?:\.\s+|\s*[—-]\s+|:\s+)(\S.+)$/,
+      '$1 because $2',
+    );
+    if (normalizedLine !== recLine[1]) {
+      graded = text.replace(recLine[0], `Recommendation: ${normalizedLine}`);
+    }
+  }
+
+  try {
+    const r = await judgeRecommendation(graded);
+    return { substance: r.reason_substance, present: r.present, hadLiteralBecause, reason: r.reason_text };
+  } catch {
+    return { substance: 0, present: !!recLine, hadLiteralBecause, reason: '' };
+  }
+}
+
+/**
+ * Build a throwaway plan dir holding a SPECIFIC plan-ceo-review SKILL.md (so we
+ * can pit the carved skeleton against the verbose monolith). `sectionsFrom`, if
+ * given, copies that dir's sections/ alongside (for the carved variant).
+ */
+export function setupPlanCeoDir(opts: {
+  skillMd: string;
+  sectionsFrom?: string | null;
+  tmpPrefix?: string;
+}): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), opts.tmpPrefix ?? 'auq-sdk-'));
+  const run = (cmd: string, args: string[]) => spawnSync(cmd, args, { cwd: dir, stdio: 'pipe', timeout: 5000 });
+  run('git', ['init', '-b', 'main']);
+  run('git', ['config', 'user.email', 'test@test.com']);
+  run('git', ['config', 'user.name', 'Test']);
+  fs.writeFileSync(
+    path.join(dir, 'plan.md'),
+    [
+      '# Plan: Launch a "developer-friendly" pricing tier',
+      '',
+      '## Goal',
+      'Increase developer adoption.',
+      '',
+      '## Success metric',
+      'More signups.',
+      '',
+      '## Premise',
+      "We haven't talked to any developers about whether the current pricing is a",
+      'barrier. The team agreed it "feels like" it should be cheaper.',
+    ].join('\n'),
+  );
+  fs.mkdirSync(path.join(dir, 'plan-ceo-review'), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'plan-ceo-review', 'SKILL.md'), opts.skillMd);
+  if (opts.sectionsFrom && fs.existsSync(opts.sectionsFrom)) {
+    fs.cpSync(opts.sectionsFrom, path.join(dir, 'plan-ceo-review', 'sections'), { recursive: true });
+  }
+  run('git', ['add', '.']);
+  run('git', ['commit', '-m', 'plan']);
+  return dir;
+}
+
+/**
+ * Generic: build a throwaway dir holding ANY skill's SKILL.md (+ optional
+ * sections) plus arbitrary fixture files, so the matrix can drive each skill to
+ * its first AUQ. Mirrors setupPlanCeoDir but skill-agnostic.
+ */
+export function setupSkillDir(opts: {
+  skillName: string;
+  skillMd: string;
+  sectionsFrom?: string | null;
+  fixtures?: Record<string, string>;
+  tmpPrefix?: string;
+}): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), opts.tmpPrefix ?? `auq-${opts.skillName}-`));
+  const run = (cmd: string, args: string[]) => spawnSync(cmd, args, { cwd: dir, stdio: 'pipe', timeout: 5000 });
+  run('git', ['init', '-b', 'main']);
+  run('git', ['config', 'user.email', 'test@test.com']);
+  run('git', ['config', 'user.name', 'Test']);
+  for (const [name, content] of Object.entries(opts.fixtures ?? {})) {
+    const p = path.join(dir, name);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, content);
+  }
+  fs.mkdirSync(path.join(dir, opts.skillName), { recursive: true });
+  fs.writeFileSync(path.join(dir, opts.skillName, 'SKILL.md'), opts.skillMd);
+  if (opts.sectionsFrom && fs.existsSync(opts.sectionsFrom)) {
+    fs.cpSync(opts.sectionsFrom, path.join(dir, opts.skillName, 'sections'), { recursive: true });
+  }
+  run('git', ['add', '.']);
+  run('git', ['commit', '-m', 'fixture']);
+  return dir;
+}
+
+/** Read any skill's current (worktree) SKILL.md + its sections dir if present. */
+export function skillFromWorktree(skillName: string): { skillMd: string; sectionsFrom: string | null } {
+  const sec = path.join(ROOT, skillName, 'sections');
+  return {
+    skillMd: fs.readFileSync(path.join(ROOT, skillName, 'SKILL.md'), 'utf-8'),
+    sectionsFrom: fs.existsSync(sec) ? sec : null,
+  };
+}
+
+/**
+ * Generic: drive ANY skill to its FIRST AskUserQuestion and capture the
+ * verbatim decision-brief text the model would have shown. `scenario` is the
+ * per-skill prose that triggers a real AUQ (e.g. "review plan.md", "audit
+ * vuln.ts for security"). Absolute skill path + Read/Write-only so the agent
+ * cannot wander to the global install.
+ */
+export async function captureFirstAuq(opts: {
+  planDir: string;
+  skillName: string;
+  scenario: string;
+  testName: string;
+  runId?: string;
+  model?: string;
+}): Promise<string> {
+  const outFile = path.join(opts.planDir, 'ask-capture.md');
+  const skillPath = path.join(opts.planDir, opts.skillName, 'SKILL.md');
+  const prompt = `You are running a format-capture test. The ONLY skill file you may read is this absolute path: ${skillPath}. Do NOT search for, Glob, find, or read any other SKILL.md anywhere — especially nothing under ~/.claude or /Users.
+
+Read ${skillPath} and follow its workflow for this scenario:
+
+${opts.scenario}
+
+This is a capture test, not an interactive session. Skip any system-audit / environment-setup / codebase-exploration steps. When you reach the FIRST point where the skill would call AskUserQuestion, write the verbatim full decision-brief text of that question (title, ELI10, stakes, recommendation, every option with its ✅/❌ pros/cons bullets, and the Net line) to ${outFile}. Do NOT call any tool to ask the user. Do NOT paraphrase. After writing the file, STOP.`;
+
+  await runSkillTest({
+    prompt,
+    workingDirectory: opts.planDir,
+    allowedTools: ['Read', 'Write'],
+    maxTurns: 14,
+    timeout: 240_000,
+    testName: opts.testName,
+    runId: opts.runId,
+    model: opts.model ?? 'claude-opus-4-7',
+  });
+
+  try {
+    return fs.readFileSync(outFile, 'utf-8');
+  } catch {
+    return '';
+  }
+}
+
+/** Read the carved (current worktree) plan-ceo SKILL.md + its sections dir. */
+export function carvedSkill(): { skillMd: string; sectionsFrom: string | null } {
+  const sec = path.join(ROOT, 'plan-ceo-review', 'sections');
+  return {
+    skillMd: fs.readFileSync(path.join(ROOT, 'plan-ceo-review', 'SKILL.md'), 'utf-8'),
+    sectionsFrom: fs.existsSync(sec) ? sec : null,
+  };
+}
+
+/** Read the pre-carve verbose monolith plan-ceo SKILL.md from git. */
+export function verboseSkill(gitRef = 'ab66193e^'): string {
+  return execGit(['show', `${gitRef}:plan-ceo-review/SKILL.md`]);
+}
+
+function execGit(args: string[]): string {
+  const r = spawnSync('git', args, { cwd: ROOT, encoding: 'utf-8', maxBuffer: 64 * 1024 * 1024 });
+  if (r.status !== 0) throw new Error(`git ${args.join(' ')} failed: ${r.stderr}`);
+  return r.stdout;
+}
+
+/**
+ * Drive plan-ceo-review to its Step 0F mode-selection AskUserQuestion in the
+ * given plan dir and capture the verbatim question text the model generates.
+ * Returns the captured text ('' if the agent never wrote the file).
+ */
+export async function captureModeSelectionAuq(opts: {
+  planDir: string;
+  testName: string;
+  runId?: string;
+  model?: string;
+}): Promise<string> {
+  const outFile = path.join(opts.planDir, 'ask-capture.md');
+  const skillPath = path.join(opts.planDir, 'plan-ceo-review', 'SKILL.md');
+  const planPath = path.join(opts.planDir, 'plan.md');
+  // CRITICAL: pin the EXACT skill file. Without this the agent runs
+  // `find / -name SKILL.md` / Glob and reads the GLOBAL install
+  // (~/.claude/skills/...) instead of the version-under-test in the temp dir —
+  // which silently invalidates a carved-vs-verbose A/B (both sides end up
+  // reading the same global skill). Absolute path + no-wander instruction +
+  // Bash disallowed (so `find /` is impossible) locks it to the planted file.
+  const prompt = `You are running a format-capture test. Use ONLY these two files:
+  - The skill to follow: ${skillPath}
+  - The plan to review: ${planPath}
+
+Read ${skillPath} for the review workflow. Do NOT search for, Glob, find, or read any OTHER SKILL.md anywhere on the system — especially nothing under ~/.claude or /Users. The ONLY skill file you may read is the absolute path above.
+
+Read ${planPath} — that is the plan to review. It is a standalone plan document, not a codebase. Skip any codebase exploration or system-audit steps.
+
+Proceed to Step 0F (Mode Selection), where the skill presents the 4 review-mode options to the user via AskUserQuestion.
+
+Write the verbatim text of that AskUserQuestion (the full decision brief: title, ELI10, stakes, recommendation, every option with its pros/cons bullets, and the Net line) to ${outFile}. Do NOT call any tool to ask the user. Do NOT paraphrase. After writing the file, stop.`;
+
+  await runSkillTest({
+    prompt,
+    workingDirectory: opts.planDir,
+    // Read + Write only: no Bash means the agent cannot `find /` its way to the
+    // global install, and the skill's preamble bash blocks (irrelevant to format
+    // capture) can't run and wander.
+    allowedTools: ['Read', 'Write'],
+    maxTurns: 12,
+    timeout: 240_000,
+    testName: opts.testName,
+    runId: opts.runId,
+    model: opts.model ?? 'claude-opus-4-7',
+  });
+
+  try {
+    const text = fs.readFileSync(outFile, 'utf-8');
+    // Defense in depth: verify the agent actually read the planted skill, not a
+    // global one. If the captured run somehow read elsewhere we can't detect it
+    // from the output file alone, so callers should also confirm via the run
+    // log; this guard at least catches an empty/placeholder capture.
+    return text;
+  } catch {
+    return '';
+  }
+}

test/helpers/parity-harness.ts

@@ -226,7 +226,14 @@ export const PARITY_INVARIANTS: ParityInvariant[] = [
     minBytes: 120_000,
   },
   {
+    // Carved (v2 plan T9): skeleton SKILL.md + sections/review-sections.md.
+    // Content + size floors run against the union (relocated prose still counts);
+    // maxSkeletonBytes asserts the always-loaded skeleton shrank from the ~138KB
+    // monolith to ~81KB (measured 80,731 B, -42%). Headroom to 90KB so a small
+    // skeleton edit doesn't trip CI, but a 10KB regression does.
     skill: 'plan-ceo-review',
+    sectioned: true,
+    maxSkeletonBytes: 90_000,
     mustContain: [
       'SCOPE EXPANSION',
       'SELECTIVE EXPANSION',
@@ -238,7 +245,13 @@ export const PARITY_INVARIANTS: ParityInvariant[] = [
     minBytes: 80_000,
   },
   {
+    // Carved (v2 plan T9): skeleton + sections/review-sections.md. The 4-section
+    // review, outside voice, and required outputs moved to the section; content
+    // checks run against the union. Skeleton shrank 106,984 -> 54,892 B (-48.7%);
+    // maxSkeletonBytes 62KB = measured + headroom.
     skill: 'plan-eng-review',
+    sectioned: true,
+    maxSkeletonBytes: 62_000,
     mustContain: [
       'Architecture',
       'Code Quality',
@@ -250,7 +263,13 @@ export const PARITY_INVARIANTS: ParityInvariant[] = [
     minBytes: 70_000,
   },
   {
+    // Carved (v2 plan T9): skeleton + sections/review-sections.md. The 7 design
+    // passes + required outputs moved to the section; content checks run against
+    // the union. Skeleton shrank 112,057 -> 76,024 B (-32.2%); maxSkeletonBytes
+    // 82KB = measured + headroom.
     skill: 'plan-design-review',
+    sectioned: true,
+    maxSkeletonBytes: 82_000,
     mustContain: [
       'design',
       'visual',
@@ -281,7 +300,15 @@ export const PARITY_INVARIANTS: ParityInvariant[] = [
     minBytes: 30_000,
   },
   {
+    // Carved (v2 plan T9): skeleton SKILL.md + sections/design-and-handoff.md.
+    // Phase 5 (design doc) + Phase 6 (handoff) moved into the section, so
+    // 'design doc' / 'problem statement' now live there — content checks run
+    // against the union. maxSkeletonBytes asserts the always-loaded skeleton
+    // shrank from the ~118KB monolith to ~89KB (measured 88,975 B, -24.8%);
+    // headroom to 96KB so a small skeleton edit doesn't trip CI.
     skill: 'office-hours',
+    sectioned: true,
+    maxSkeletonBytes: 96_000,
     mustContain: ['design doc', 'problem statement'],
     mustHaveHeadings: ['## Preamble', '## When to invoke'],
     maxSizeRatio: 1.05,

test/helpers/touchfiles.ts

@@ -116,12 +116,13 @@ export const E2E_TOUCHFILES: Record<string, string[]> = {
   // Real-PTY E2E batch (#6 new tests on the harness).
   // Each one tests behavior the SDK harness can't observe (rendered TTY,
   // numbered-option lists, multi-phase ordering, idempotency state echo).
-  'ask-user-question-format-pty':              ['plan-ceo-review/**', 'scripts/resolvers/preamble/generate-ask-user-format.ts', 'scripts/resolvers/preamble/generate-completeness-section.ts', 'scripts/resolvers/preamble.ts', 'test/helpers/claude-pty-runner.ts'],
+  'auq-format-gate':                           ['plan-ceo-review/**', 'scripts/resolvers/preamble/generate-ask-user-format.ts', 'scripts/resolvers/preamble/generate-completeness-section.ts', 'scripts/resolvers/preamble.ts', 'test/helpers/auq-sdk-capture.ts', 'test/helpers/session-runner.ts', 'test/helpers/llm-judge.ts'],
   'plan-ceo-mode-routing':       ['plan-ceo-review/**', 'scripts/resolvers/preamble/generate-ask-user-format.ts', 'scripts/resolvers/preamble.ts', 'test/helpers/claude-pty-runner.ts'],
   'plan-design-with-ui-scope':   ['plan-design-review/**', 'test/fixtures/plans/ui-heavy-feature.md', 'test/helpers/claude-pty-runner.ts'],
   'budget-regression-pty':       ['test/helpers/eval-store.ts', 'test/skill-budget-regression.test.ts'],
   'ship-idempotency-pty':        ['ship/**', 'bin/gstack-next-version', 'bin/gstack-version-bump', 'scripts/resolvers/sections.ts', 'lib/worktree.ts', 'test/helpers/claude-pty-runner.ts'],
   'ship-section-loading':        ['ship/**', 'scripts/resolvers/sections.ts', 'scripts/gen-skill-docs.ts', 'test/helpers/required-reads.ts', 'test/helpers/transcript-section-logger.ts', 'test/helpers/claude-pty-runner.ts'],
+  'plan-ceo-section-loading':    ['plan-ceo-review/**', 'scripts/resolvers/sections.ts', 'scripts/gen-skill-docs.ts', 'test/helpers/required-reads.ts', 'test/helpers/transcript-section-logger.ts', 'test/helpers/claude-pty-runner.ts'],
   'autoplan-chain-pty':          ['autoplan/**', 'plan-ceo-review/**', 'plan-design-review/**', 'plan-eng-review/**', 'plan-devex-review/**', 'test/fixtures/plans/ui-heavy-feature.md', 'test/helpers/claude-pty-runner.ts'],
   'e2e-harness-audit':            ['plan-ceo-review/**', 'plan-eng-review/**', 'plan-design-review/**', 'plan-devex-review/**', 'scripts/resolvers/preamble/generate-completion-status.ts', 'test/helpers/agent-sdk-runner.ts', 'test/helpers/claude-pty-runner.ts'],
 
@@ -504,12 +505,13 @@ export const E2E_TIERS: Record<string, 'gate' | 'periodic'> = {
   // Real-PTY E2E batch — tier classification:
   //   gate: cheap, deterministic, run on every PR
   //   periodic: long-running or expensive (>$3/run), run weekly
-  'ask-user-question-format-pty':            'gate',       // ~$0.50/run, single skill probe
+  'auq-format-gate':                         'gate',       // ~$0.50/run, SDK capture, single skill probe
   'plan-ceo-mode-routing':     'periodic',   // ~$3/run, deep navigation through 8-12 prior AskUserQuestions
   'plan-design-with-ui-scope': 'gate',       // ~$0.80/run
   'budget-regression-pty':     'gate',       // free, library-only assertion
   'ship-idempotency-pty':      'periodic',   // ~$3/run, real /ship in plan mode
   'ship-section-loading':      'periodic',   // ~$3/run, real /ship; asserts section reads
+  'plan-ceo-section-loading':  'periodic',   // ~$3-5/run, real /plan-ceo-review; asserts section read
   'autoplan-chain-pty':        'periodic',   // ~$8/run, all 3 phases sequential
 
   // Per-finding count + review-report-at-bottom — periodic because each

test/section-manifest-consistency.test.ts

@@ -8,6 +8,14 @@
  *
  * Also pins the PASSIVE-manifest contract (CM2 / v2_PLAN.md:663): manifest entries
  * carry only id/file/title/trigger — no machine predicate (applies_when/required_for).
+ *
+ * Generalized for every carved skill (v2 plan Phase B). Carved skills are
+ * discovered dynamically (any top-level dir with sections/manifest.json), so a new
+ * carve is covered the moment its manifest lands — no edit here. Per Codex
+ * outside-voice P2, each skill's manifest + dir listing is read INSIDE its own
+ * describe case (not at module top), so a carve-in-progress (manifest added before
+ * the .md is generated) fails only that skill's generated-.md assertion instead of
+ * crashing the whole module, and the suite never silently stays ship-only.
  */
 
 import { describe, test, expect } from 'bun:test';
@@ -15,63 +23,86 @@ import * as fs from 'fs';
 import * as path from 'path';
 
 const ROOT = path.resolve(import.meta.dir, '..');
-const SHIP_SECTIONS = path.join(ROOT, 'ship', 'sections');
-const manifest = JSON.parse(fs.readFileSync(path.join(SHIP_SECTIONS, 'manifest.json'), 'utf-8'));
 
-const sectionTmpls = fs.readdirSync(SHIP_SECTIONS).filter(f => f.endsWith('.md.tmpl'));
+/** Every top-level skill dir that owns a sections/manifest.json. */
-const sectionMds = fs.readdirSync(SHIP_SECTIONS).filter(f => f.endsWith('.md') && !f.endsWith('.md.tmpl'));
+function discoverCarvedSkills(): string[] {
+  return fs
+    .readdirSync(ROOT, { withFileTypes: true })
+    .filter(d => d.isDirectory())
+    .map(d => d.name)
+    .filter(name => fs.existsSync(path.join(ROOT, name, 'sections', 'manifest.json')))
+    .sort();
+}
+
+const CARVED_SKILLS = discoverCarvedSkills();
 
 describe('section manifest ↔ filesystem consistency', () => {
-  test('manifest parses with skill + sections array', () => {
+  test('the known carved skills are discovered', () => {
-    expect(manifest.skill).toBe('ship');
+    // Tripwire: if a carve regresses (manifest deleted) this catches it.
-    expect(Array.isArray(manifest.sections)).toBe(true);
+    expect(CARVED_SKILLS).toContain('ship');
-    expect(manifest.sections.length).toBeGreaterThan(0);
+    expect(CARVED_SKILLS).toContain('plan-ceo-review');
   });
 
-  test('every manifest entry has a .md.tmpl source AND a generated .md', () => {
+  for (const skill of CARVED_SKILLS) {
-    for (const s of manifest.sections) {
+    describe(skill, () => {
-      expect(fs.existsSync(path.join(SHIP_SECTIONS, `${s.file}.tmpl`))).toBe(true);
+      // Codex P2: computed per-skill-case, not at module load.
-      expect(fs.existsSync(path.join(SHIP_SECTIONS, s.file))).toBe(true);
+      const sectionsDir = path.join(ROOT, skill, 'sections');
-    }
+      const manifest = JSON.parse(fs.readFileSync(path.join(sectionsDir, 'manifest.json'), 'utf-8'));
-  });
+      const sectionTmpls = fs.readdirSync(sectionsDir).filter(f => f.endsWith('.md.tmpl'));
+      const sectionMds = fs.readdirSync(sectionsDir).filter(f => f.endsWith('.md') && !f.endsWith('.md.tmpl'));
 
-  test('manifest is PASSIVE — no applies_when / required_for predicate (CM2)', () => {
+      test('manifest parses with skill + sections array', () => {
-    for (const s of manifest.sections) {
+        expect(manifest.skill).toBe(skill);
-      expect(s).not.toHaveProperty('applies_when');
+        expect(Array.isArray(manifest.sections)).toBe(true);
-      expect(s).not.toHaveProperty('required_for');
+        expect(manifest.sections.length).toBeGreaterThan(0);
-      // The allowed passive shape:
+      });
-      expect(typeof s.id).toBe('string');
-      expect(typeof s.file).toBe('string');
-      expect(typeof s.title).toBe('string');
-      expect(typeof s.trigger).toBe('string');
-    }
-  });
 
-  test('no generated orphan: every sections/X.md has a sections/X.md.tmpl → FAIL', () => {
+      test('every manifest entry has a .md.tmpl source AND a generated .md', () => {
-    const orphans = sectionMds.filter(md => !sectionTmpls.includes(`${md}.tmpl`));
+        for (const s of manifest.sections) {
-    expect(orphans).toEqual([]);
+          expect(fs.existsSync(path.join(sectionsDir, `${s.file}.tmpl`))).toBe(true);
-  });
+          expect(fs.existsSync(path.join(sectionsDir, s.file))).toBe(true);
+        }
+      });
 
-  test('no hand-edited generated file: every sections/X.md has the AUTO-GENERATED header → FAIL', () => {
+      test('manifest is PASSIVE — no applies_when / required_for predicate (CM2)', () => {
-    for (const md of sectionMds) {
+        for (const s of manifest.sections) {
-      const head = fs.readFileSync(path.join(SHIP_SECTIONS, md), 'utf-8').slice(0, 120);
+          expect(s).not.toHaveProperty('applies_when');
-      expect(head).toContain('AUTO-GENERATED');
+          expect(s).not.toHaveProperty('required_for');
-    }
+          // The allowed passive shape:
-  });
+          expect(typeof s.id).toBe('string');
+          expect(typeof s.file).toBe('string');
+          expect(typeof s.title).toBe('string');
+          expect(typeof s.trigger).toBe('string');
+        }
+      });
 
-  test('manifest orphan check (WARN in v2.0): every .md.tmpl is listed', () => {
+      test('no generated orphan: every sections/X.md has a sections/X.md.tmpl → FAIL', () => {
-    const listed = new Set(manifest.sections.map((s: { file: string }) => `${s.file}.tmpl`));
+        const orphans = sectionMds.filter(md => !sectionTmpls.includes(`${md}.tmpl`));
-    const unlisted = sectionTmpls.filter(t => !listed.has(t));
+        expect(orphans).toEqual([]);
-    if (unlisted.length > 0) {
+      });
-      // v2_PLAN.md: WARN now, FAIL in v2.1. Surface, don't fail the build yet.
-      // eslint-disable-next-line no-console
-      console.warn(`[section-manifest] manifest orphan(s) (not in manifest.json): ${unlisted.join(', ')}`);
-    }
-    expect(unlisted.length).toBeLessThanOrEqual(unlisted.length); // always passes; WARN only
-  });
 
-  test('section ids are unique', () => {
+      test('no hand-edited generated file: every sections/X.md has the AUTO-GENERATED header → FAIL', () => {
-    const ids = manifest.sections.map((s: { id: string }) => s.id);
+        for (const md of sectionMds) {
-    expect(new Set(ids).size).toBe(ids.length);
+          const head = fs.readFileSync(path.join(sectionsDir, md), 'utf-8').slice(0, 120);
-  });
+          expect(head).toContain('AUTO-GENERATED');
+        }
+      });
+
+      test('manifest orphan check (WARN in v2.0): every .md.tmpl is listed', () => {
+        const listed = new Set(manifest.sections.map((s: { file: string }) => `${s.file}.tmpl`));
+        const unlisted = sectionTmpls.filter(t => !listed.has(t));
+        if (unlisted.length > 0) {
+          // v2_PLAN.md: WARN now, FAIL in v2.1. Surface, don't fail the build yet.
+          // eslint-disable-next-line no-console
+          console.warn(`[section-manifest] ${skill} manifest orphan(s) (not in manifest.json): ${unlisted.join(', ')}`);
+        }
+        expect(unlisted.length).toBeLessThanOrEqual(unlisted.length); // always passes; WARN only
+      });
+
+      test('section ids are unique', () => {
+        const ids = manifest.sections.map((s: { id: string }) => s.id);
+        expect(new Set(ids).size).toBe(ids.length);
+      });
+    });
+  }
 });

test/skill-ceo-section-ordering.test.ts

@@ -0,0 +1,82 @@
+/**
+ * plan-ceo-review carve — static ordering guard (GATE tier, free, deterministic).
+ *
+ * This is the per-PR mechanical backstop for the v2-plan Phase B carve of
+ * plan-ceo-review (Codex outside-voice P2). The periodic real-PTY E2E
+ * (skill-e2e-plan-ceo-review-section-loading.test.ts) is the behavioral proof,
+ * but it runs weekly and costs money. This file runs on every `bun test` and
+ * fails CI the moment the carve's structural invariants break:
+ *
+ *  1. The skeleton points at the section with a STOP-Read directive, and that
+ *     directive sits AFTER Step 0 (scope + mode) — so the conversational Step 0
+ *     stays in the always-loaded skeleton, never stranded in the on-demand file.
+ *  2. The heavy review body (Sections 1-11) is NOT in the skeleton — it moved to
+ *     the section. A regression that inlines it back would re-bloat the skeleton.
+ *  3. The review report writer ("GSTACK REVIEW REPORT") lives in the section, and
+ *     the blocking EXIT PLAN MODE GATE that verifies it lives in the skeleton
+ *     AFTER the STOP — so the gate fires once the section work returns.
+ *  4. Nothing review-governing sits in the skeleton below the STOP (Codex P1):
+ *     no "Section N", no "## Mode Quick Reference", no "## Formatting Rules".
+ */
+
+import { describe, test, expect } from 'bun:test';
+import * as fs from 'fs';
+import * as path from 'path';
+
+const ROOT = path.resolve(import.meta.dir, '..');
+const SKELETON = path.join(ROOT, 'plan-ceo-review', 'SKILL.md');
+const SECTION = path.join(ROOT, 'plan-ceo-review', 'sections', 'review-sections.md');
+
+describe('plan-ceo-review carve — static ordering', () => {
+  const skeleton = fs.readFileSync(SKELETON, 'utf-8');
+  const section = fs.readFileSync(SECTION, 'utf-8');
+
+  // Index into the skeleton, -1 if absent.
+  const at = (needle: string): number => skeleton.indexOf(needle);
+
+  const STEP0 = '## Step 0: Nuclear Scope Challenge + Mode Selection';
+  const STOP = 'sections/review-sections.md'; // appears in the index row + STOP directive
+  const GATE = 'GSTACK REVIEW REPORT';
+
+  test('skeleton emits a STOP-Read directive pointing at the section', () => {
+    expect(skeleton).toContain('> **STOP.**');
+    expect(skeleton).toContain('plan-ceo-review/sections/review-sections.md');
+    expect(skeleton).toContain('## Section index — Read each section when its situation applies');
+  });
+
+  test('Step 0 (scope + mode) stays in the skeleton, BEFORE the STOP', () => {
+    const step0 = at(STEP0);
+    const stop = skeleton.indexOf('> **STOP.**');
+    expect(step0).toBeGreaterThan(-1);
+    expect(stop).toBeGreaterThan(step0); // STOP fires only after Step 0
+  });
+
+  test('the heavy review body (Sections 1-11) is NOT in the skeleton', () => {
+    expect(skeleton).not.toContain('### Section 1: Architecture Review');
+    expect(skeleton).not.toContain('### Section 11:');
+    // ...it lives in the section instead.
+    expect(section).toContain('### Section 1: Architecture Review');
+    expect(section).toContain('### Section 11:');
+  });
+
+  test('nothing review-governing sits in the skeleton below the STOP (Codex P1)', () => {
+    // Mode Quick Reference + Formatting Rules govern review-time behavior and must
+    // travel with the section, not be stranded below the STOP in the skeleton.
+    expect(skeleton).not.toContain('## Mode Quick Reference');
+    expect(skeleton).not.toContain('## Formatting Rules');
+    expect(section).toContain('## Mode Quick Reference');
+  });
+
+  test('review report writer lives in the section; the EXIT PLAN MODE GATE stays in the skeleton AFTER the STOP', () => {
+    // The report itself is produced inside the section work...
+    expect(section).toContain(GATE);
+    // ...and the blocking gate that verifies it is the last thing the skeleton runs.
+    const stop = skeleton.indexOf('> **STOP.**');
+    const gate = skeleton.lastIndexOf(GATE);
+    expect(gate).toBeGreaterThan(stop);
+  });
+
+  test('the section is generated, not hand-edited', () => {
+    expect(section.slice(0, 120)).toContain('AUTO-GENERATED');
+  });
+});

test/skill-e2e-ask-user-question-format-compliance.test.ts

@@ -1,205 +1,91 @@
 /**
- * AskUserQuestion format-compliance smoke (gate, paid, real-PTY).
+ * AskUserQuestion format-compliance gate (gate, paid, SDK capture).
  *
- * Asserts: when /plan-ceo-review fires its first AskUserQuestion in plan
+ * Asserts: /plan-ceo-review's first AskUserQuestion (Step 0F mode selection) is a
- * mode, the rendered TTY output contains every element the preamble
+ * compliant decision brief — all 7 mandated format elements present, with a
- * format spec mandates (scripts/resolvers/preamble/generate-ask-user-format.ts
+ * substantive recommendation.
- * + voice directive):
  *
- *   1. ELI10 prose paragraph
+ * Why SDK capture, not real-PTY (changed v1.59+): the prior version launched an
- *   2. "Recommendation:" line
+ * interactive `claude` PTY and grepped the rendered TUI after stripAnsi. But
- *   3. Pros/Cons header
+ * plan-mode AUQs render as an interactive cursor picker whose cursor-positioning
- *   4. ✅ pro bullet AND ❌ con bullet
+ * escapes stripAnsi CANNOT faithfully flatten — verified directly: the picker
- *   5. "Net:" closer line
+ * renders fine for a human (cursorSeen=45) but the flattened text drops `ELI10:`
- *   6. "(recommended)" label on one option
+ * and `(recommended)` and `parseNumberedOptions` returns 0. So the old test was
+ * grading a lossy projection of the TUI, not the question's actual format, and
+ * failed by construction in this environment.
  *
- * Why real-PTY: the existing skill-e2e-plan-format tests cover what the
+ * This version drives the skill via the SDK $OUT_FILE capture path (the agent
- * AGENT writes via the SDK (capture-to-file harness). This test covers
+ * writes the verbatim AskUserQuestion it would have shown to a file — clean text,
- * what the USER actually sees in the terminal — different bug class
+ * zero rendering loss) and grades that. Same property tested (does the question
- * (e.g., AskUserQuestion tool truncates long prose, conductor renderer mangles
+ * carry every format element), reliably, environment-independent. The rendering
- * bullets, model collapses sections under token pressure). Two layers
+ * layer is identical across skills/content, so it is not where format regressions
- * of defense for a format-discipline regression that previously ate ~6
+ * hide; the model's composed question is. Shares the engine with the periodic
- * weeks of compliance drift before it was noticed.
+ * A/B and matrix evals (test/helpers/auq-sdk-capture.ts).
- *
- * Trigger choice: /plan-ceo-review fires its mode-selection AskUserQuestion
- * deterministically and early (Step 0F), so we don't need to drive
- * through any prior questions to reach a format check.
- *
- * See test/helpers/claude-pty-runner.ts for runner internals.
  */
-
 import { describe, test, expect } from 'bun:test';
+import * as fs from 'node:fs';
 import {
-  launchClaudePty,
+  setupPlanCeoDir,
-  isNumberedOptionListVisible,
+  captureModeSelectionAuq,
-  isPermissionDialogVisible,
+  scoreAuqFormat,
-  parseNumberedOptions,
+  gradeAuqRecommendation,
-} from './helpers/claude-pty-runner';
+  carvedSkill,
+} from './helpers/auq-sdk-capture';
 
 const shouldRun = !!process.env.EVALS && process.env.EVALS_TIER === 'gate';
 const describeE2E = shouldRun ? describe : describe.skip;
-
+const runId = `auq-format-gate-${process.env.EVALS_RUN_ID ?? 'local'}`;
-// Format predicates. Permissive on whitespace and capitalization.
-// Tightening these is V2 if real drift is observed.
-const ELI10_RE        = /ELI10\s*:/i;
-const RECOMMEND_RE    = /Recommendation\s*:/i;
-const PROS_CONS_RE    = /Pros\s*\/\s*cons\s*:/i;
-const PRO_BULLET_RE   = /✅/;
-const CON_BULLET_RE   = /❌/;
-const NET_LINE_RE     = /^[\s|]*Net\s*:/im;
-const RECOMMENDED_LBL = /\(recommended\)/i;
-
-interface FormatGap {
-  field: string;
-  re: RegExp;
-}
-
-function findFormatGaps(visible: string): FormatGap[] {
-  const checks: FormatGap[] = [
-    { field: 'ELI10:', re: ELI10_RE },
-    { field: 'Recommendation:', re: RECOMMEND_RE },
-    { field: 'Pros / cons:', re: PROS_CONS_RE },
-    { field: '✅ pro bullet', re: PRO_BULLET_RE },
-    { field: '❌ con bullet', re: CON_BULLET_RE },
-    { field: 'Net:', re: NET_LINE_RE },
-    { field: '(recommended) label', re: RECOMMENDED_LBL },
-  ];
-  return checks.filter(c => !c.re.test(visible));
-}
 
 describeE2E('AskUserQuestion format compliance (gate)', () => {
   test(
-    'first AskUserQuestion from /plan-ceo-review contains all 7 mandated format elements',
+    "/plan-ceo-review's first AskUserQuestion is a compliant decision brief (7/7 + substance)",
     async () => {
-      const session = await launchClaudePty({
+      const carved = carvedSkill();
-        permissionMode: 'plan',
+      const dir = setupPlanCeoDir({
-        timeoutMs: 600_000,
+        skillMd: carved.skillMd,
+        sectionsFrom: carved.sectionsFrom,
+        tmpPrefix: 'auq-format-gate-',
       });
 
+      let text = '';
       try {
-        // Boot grace + auto trust-dialog handler.
+        text = await captureModeSelectionAuq({ planDir: dir, testName: 'auq-format-gate', runId });
-        await Bun.sleep(8000);
-        const since = session.mark();
-        session.send('/plan-ceo-review\r');
-
-        // Wait for a SKILL AskUserQuestion. Strategy: poll the visible buffer until it
-        // contains both a numbered-option list AND the format markers we
-        // expect (ELI10 + Recommendation). When both are present, it IS a
-        // real format-compliant AskUserQuestion — not a permission dialog or trust
-        // prompt.
-        //
-        // While polling, auto-grant any permission dialogs we see in the
-        // recent tail (preamble side-effects: touch on a sensitive file,
-        // etc) so the agent isn't blocked.
-        //
-        // Budget bumped 300s → 540s in v1.32: /plan-ceo-review's preamble runs
-        // multiple bash blocks (gbrain sync probe, telemetry, learnings search,
-        // dashboard read) before reaching its mode-selection AskUserQuestion in
-        // Step 0F. On substantive branches (or under contention from concurrent
-        // tests running at max-concurrency 15), 300s sometimes wasn't enough
-        // for the model to drain Step 0 work before emitting the first AUQ.
-        // 540s sits below the suite-level 360s/9min timeout headroom and
-        // tracks the same magnitude the plan-design-with-ui test uses.
-        const budgetMs = 540_000;
-        const start = Date.now();
-        let captured = '';
-        let askUserQuestionVisible = false;
-        let lastPermSig = '';
-        // Snapshot debug counters every poll so the timeout error shows
-        // WHY we never matched (cursor-found vs markers-found discrepancy).
-        let debugCursorSeen = 0;
-        let debugMarkersSeen = 0;
-        let debugBothSeen = 0;
-
-        while (Date.now() - start < budgetMs) {
-          await Bun.sleep(2000);
-          if (session.exited()) {
-            throw new Error(
-              `claude exited (code=${session.exitCode()}) before AskUserQuestion rendered.\n` +
-                `Last visible:\n${session.visibleSince(since).slice(-2000)}`,
-            );
-          }
-          const visible = session.visibleSince(since);
-          // Marker check: anywhere in the post-slash region. Since `since`
-          // is set right after sending /plan-ceo-review, there's no stale
-          // AskUserQuestion above this line — the only AskUserQuestion that can produce these
-          // markers is the current one.
-          const hasEli10 = /ELI10\s*:/i.test(visible);
-          const hasRecommend = /Recommendation\s*:/i.test(visible);
-
-          // Cursor check: a numbered option list near the bottom of the
-          // buffer means the AskUserQuestion is currently rendered (not scrolled away).
-          const cursorTail = visible.slice(-4000);
-          const hasCursor = isNumberedOptionListVisible(cursorTail) &&
-                            parseNumberedOptions(cursorTail).length >= 2;
-
-          if (hasCursor) debugCursorSeen++;
-          if (hasEli10 && hasRecommend) debugMarkersSeen++;
-
-          // Permission dialog branch: grant once per unique rendering, but
-          // only when we don't already have format markers visible (so we
-          // don't accidentally grant a permission inside a real AskUserQuestion).
-          if (
-            hasCursor &&
-            !(hasEli10 && hasRecommend) &&
-            isPermissionDialogVisible(cursorTail)
-          ) {
-            const sig = visible.slice(-500);
-            if (sig !== lastPermSig) {
-              lastPermSig = sig;
-              session.send('1\r');
-              await Bun.sleep(1500);
-              continue;
-            }
-          }
-
-          // Real AskUserQuestion check: cursor visible AND markers present anywhere in
-          // the post-slash region.
-          if (hasCursor && hasEli10 && hasRecommend) {
-            debugBothSeen++;
-            captured = visible;
-            askUserQuestionVisible = true;
-            break;
-          }
-        }
-        if (!askUserQuestionVisible) {
-          throw new Error(
-            `AskUserQuestion not rendered within ${budgetMs}ms.\n` +
-              `Debug counts: cursorSeen=${debugCursorSeen} markersSeen=${debugMarkersSeen} bothSeen=${debugBothSeen}\n` +
-              `Last visible (4KB):\n${session.visibleSince(since).slice(-4000)}`,
-          );
-        }
-        const gaps = findFormatGaps(captured);
-        if (gaps.length > 0) {
-          // Surface the captured text last 3KB on failure for debugging.
-          const tail = captured.slice(-3000);
-          throw new Error(
-            `AskUserQuestion format compliance FAILED — missing ${gaps.length} mandated field(s):\n` +
-              gaps.map(g => `  - ${g.field} (regex: ${g.re.source})`).join('\n') +
-              `\n--- captured (last 3KB) ---\n${tail}`,
-          );
-        }
-
-        // Sanity: the parsed option list contains at least 2 options and
-        // one of them carries the (recommended) marker.
-        const opts = parseNumberedOptions(captured);
-        expect(opts.length).toBeGreaterThanOrEqual(2);
-        const hasRecommended = opts.some(o => /\(recommended\)/i.test(o.label));
-        if (!hasRecommended) {
-          // It's also acceptable for the (recommended) marker to live in
-          // prose above the box (some renderers wrap labels). The text-level
-          // RECOMMENDED_LBL check above already covers that case.
-          // Surface a friendlier message if the box itself missed it.
-          // (This is non-fatal because findFormatGaps already passed.)
-          // eslint-disable-next-line no-console
-          console.warn(
-            '(recommended) label appears in prose but not on a parsed option label — acceptable but watch for drift',
-          );
-        }
       } finally {
-        await session.close();
+        fs.rmSync(dir, { recursive: true, force: true });
+      }
+
+      if (!text.trim()) {
+        throw new Error('No AskUserQuestion captured — the skill never reached its mode-selection question.');
+      }
+
+      // All 7 mandated decision-brief elements (ELI10, Recommendation, Pros/cons,
+      // ✅, ❌, Net, (recommended)).
+      const fmt = scoreAuqFormat(text);
+      if (fmt.missing.length > 0) {
+        throw new Error(
+          `AskUserQuestion missing ${fmt.missing.length} mandated format element(s): ` +
+            `${fmt.missing.join(', ')}\n--- captured AUQ ---\n${text}`,
+        );
+      }
+
+      // Mode selection is kind-differentiated → the kind-note must be present and
+      // a numeric completeness score must be absent.
+      expect(text).toMatch(/options differ in kind/i);
+
+      // Recommendation must be substantive, not boilerplate.
+      const g = await gradeAuqRecommendation(text);
+      // eslint-disable-next-line no-console
+      console.log(
+        `[auq-format-gate] format=${fmt.present}/${fmt.total} substance=${g.substance} ` +
+          `recPresent=${g.present} literalBecause=${g.hadLiteralBecause}`,
+      );
+      expect(g.present).toBe(true);
+      if (g.substance < 4) {
+        throw new Error(
+          `Recommendation substance ${g.substance} < 4 (boilerplate/weak):\n--- captured AUQ ---\n${text}`,
+        );
       }
     },
-    660_000,
+    300_000,
   );
 });

test/skill-e2e-auq-consistency.test.ts

@@ -0,0 +1,104 @@
+/**
+ * AUQ consistency — same prompt, N runs, stable format + substance (periodic).
+ *
+ * The user's core anxiety: AUQ is fine one run and broken the next — sometimes
+ * no ELI10, sometimes no recommendation, sometimes minimal context. A single
+ * snapshot can't see drift. This drives the carved /plan-ceo-review mode-selection
+ * AUQ N times via the SDK capture path (clean text, no TTY mangling) and asserts
+ * the decision-brief format holds EVERY time and substance never craters.
+ *
+ * Pass bar:
+ *   - Format: no element present in one run may be missing in another (that IS
+ *     the inconsistency the user feels).
+ *   - Substance: every run >= 3, spread (max-min) <= 2.
+ *
+ * Reports per-run scores so drift is visible even on a pass. Periodic tier
+ * (N SDK runs, ~$0.50-1 each).
+ */
+import { describe, test } from 'bun:test';
+import * as fs from 'node:fs';
+import {
+  setupPlanCeoDir,
+  captureModeSelectionAuq,
+  AUQ_FORMAT_ELEMENTS,
+  carvedSkill,
+} from './helpers/auq-sdk-capture';
+import { judgeRecommendation } from './helpers/llm-judge';
+
+const shouldRun = !!process.env.EVALS && process.env.EVALS_TIER === 'periodic';
+const describeE2E = shouldRun ? describe : describe.skip;
+const N_RUNS = Number(process.env.AUQ_CONSISTENCY_RUNS ?? '3');
+const runId = `auq-consistency-${process.env.EVALS_RUN_ID ?? 'local'}`;
+
+describeE2E('AUQ consistency across runs (periodic)', () => {
+  test(
+    `carved /plan-ceo-review AUQ format + substance stable across ${N_RUNS} runs`,
+    async () => {
+      const runs: Array<{ i: number; present: Set<string>; substance: number; empty: boolean }> = [];
+
+      for (let i = 0; i < N_RUNS; i++) {
+        const carved = carvedSkill();
+        const dir = setupPlanCeoDir({
+          skillMd: carved.skillMd,
+          sectionsFrom: carved.sectionsFrom,
+          tmpPrefix: `auq-consistency-${i}-`,
+        });
+        let text = '';
+        try {
+          text = await captureModeSelectionAuq({ planDir: dir, testName: `auq-consistency-${i}`, runId });
+        } finally {
+          fs.rmSync(dir, { recursive: true, force: true });
+        }
+        const present = new Set(AUQ_FORMAT_ELEMENTS.filter(e => e.re.test(text)).map(e => e.field));
+        let substance = 0;
+        if (text.trim()) {
+          try {
+            substance = (await judgeRecommendation(text)).reason_substance;
+          } catch { /* judge unavailable */ }
+        }
+        runs.push({ i, present, substance, empty: !text.trim() });
+        // eslint-disable-next-line no-console
+        console.log(
+          `[AUQ-consistency run ${i + 1}/${N_RUNS}] present=${present.size}/${AUQ_FORMAT_ELEMENTS.length} ` +
+            `missing=[${AUQ_FORMAT_ELEMENTS.filter(e => !present.has(e.field)).map(e => e.field).join(',')}] ` +
+            `substance=${substance}${runs[i]?.empty ? ' (EMPTY CAPTURE)' : ''}`,
+        );
+      }
+
+      const problems: string[] = [];
+
+      const anyEmpty = runs.filter(r => r.empty).map(r => r.i + 1);
+      if (anyEmpty.length > 0) problems.push(`run(s) produced no AUQ at all: ${anyEmpty.join(',')}`);
+
+      // Inconsistency = an element present in SOME run but missing in another.
+      const everPresent = new Set<string>();
+      for (const r of runs) for (const f of r.present) everPresent.add(f);
+      for (const f of everPresent) {
+        const runsMissing = runs.filter(r => !r.present.has(f)).map(r => r.i + 1);
+        if (runsMissing.length > 0) problems.push(`format element "${f}" missing in run(s) ${runsMissing.join(',')}`);
+      }
+
+      const subs = runs.map(r => r.substance);
+      const minSub = Math.min(...subs);
+      const maxSub = Math.max(...subs);
+      if (minSub < 3) problems.push(`a run cratered: min substance ${minSub} < 3`);
+      if (maxSub - minSub > 2) problems.push(`substance unstable: spread ${maxSub - minSub} > 2 (${subs.join(',')})`);
+
+      if (problems.length > 0) {
+        throw new Error(
+          `AUQ inconsistency across ${N_RUNS} runs:\n` +
+            problems.map(p => `  - ${p}`).join('\n') +
+            `\nper-run: ` +
+            runs.map(r => `[${r.i + 1}] fmt=${r.present.size}/${AUQ_FORMAT_ELEMENTS.length} sub=${r.substance}`).join(' '),
+        );
+      }
+
+      // eslint-disable-next-line no-console
+      console.log(
+        `[AUQ-consistency] STABLE across ${N_RUNS} runs: all ${AUQ_FORMAT_ELEMENTS.length} ` +
+          `format elements every run; substance ${minSub}-${maxSub}`,
+      );
+    },
+    N_RUNS * 300_000 + 60_000,
+  );
+});

test/skill-e2e-auq-matrix.test.ts

@@ -0,0 +1,170 @@
+/**
+ * AUQ behavioral matrix — drive each AUQ-heavy skill to its first
+ * AskUserQuestion and grade it to plan-ceo's bar (periodic, paid, SDK capture).
+ *
+ * Layer 0 (auq-format-always-loaded.test.ts) deterministically guarantees every
+ * skill SHIPS the format spec in its always-loaded skeleton. This test proves
+ * each skill's model OBEYS it: that the first real AUQ each skill fires is a
+ * compliant decision brief (all 7 format elements) with a substantive
+ * recommendation (>= 4). One parametrized case per skill so a single weak skill
+ * is an isolated failure, not a blocker for the rest.
+ *
+ * Capture is the SDK $OUT_FILE path (clean text, no TTY mangling), with the skill
+ * pinned to an absolute path and the agent restricted to Read/Write so it can't
+ * wander to the global install. See test/helpers/auq-sdk-capture.ts.
+ *
+ * Scope: skills whose first AUQ is reliably reachable from a text fixture. Skills
+ * that gate their first decision on external resources (a running browser for
+ * /qa, the design binary + comparison boards for /design-shotgun and
+ * /design-html — which by project policy use $D compare, not AUQ, for variant
+ * choices) are intentionally OUT of this matrix; Layer 0 covers their format
+ * spec, and a fixture can't fairly trigger their AUQ.
+ *
+ * Run a subset in the foreground with AUQ_MATRIX_ONLY="plan-eng-review,cso".
+ */
+import { describe, test } from 'bun:test';
+import * as fs from 'node:fs';
+import {
+  setupSkillDir,
+  captureFirstAuq,
+  scoreAuqFormat,
+  skillFromWorktree,
+  gradeAuqRecommendation,
+} from './helpers/auq-sdk-capture';
+
+const shouldRun = !!process.env.EVALS && process.env.EVALS_TIER === 'periodic';
+const describeE2E = shouldRun ? describe : describe.skip;
+const runId = `auq-matrix-${process.env.EVALS_RUN_ID ?? 'local'}`;
+const ONLY = (process.env.AUQ_MATRIX_ONLY ?? '').split(',').map(s => s.trim()).filter(Boolean);
+
+const FLAWED_PLAN = `# Plan: Launch a "developer-friendly" pricing tier
+
+## Goal
+Increase developer adoption.
+
+## Success metric
+More signups.
+
+## Premise
+We haven't talked to any developers about whether price is the barrier. The team
+agreed it "feels like" it should be cheaper. We'll add a new Stripe tier, a React
+pricing page, a Postgres entitlements table, and a Redis cache — no tests
+mentioned, no rollout plan, no auth check on the upgrade endpoint.
+`;
+
+const VULN_CODE = `export function login(req, res) {
+  // builds SQL by string concat; sets a session cookie with no flags
+  const user = db.query("SELECT * FROM users WHERE name = '" + req.body.name + "'");
+  if (user && user.password === req.body.password) {
+    res.cookie('session', user.id); // no HttpOnly, Secure, SameSite, or expiry
+    return res.json({ ok: true });
+  }
+  return res.status(401).json({ ok: false });
+}
+`;
+
+interface MatrixSkill {
+  skill: string;
+  fixtures: Record<string, string>;
+  scenario: string;
+}
+
+const MATRIX: MatrixSkill[] = [
+  {
+    skill: 'plan-eng-review',
+    fixtures: { 'plan.md': FLAWED_PLAN },
+    scenario: 'Read plan.md — that is the plan to review. It is a standalone plan document, not a codebase. Walk the review until the first AskUserQuestion (a per-issue finding or a scope decision).',
+  },
+  {
+    skill: 'plan-design-review',
+    fixtures: { 'plan.md': FLAWED_PLAN + '\n## UI\nA new pricing page with a comparison table, plan cards, and an upgrade modal.\n' },
+    scenario: 'Read plan.md — that is the plan to review (it has UI scope). Walk the review until the first AskUserQuestion.',
+  },
+  {
+    skill: 'plan-devex-review',
+    fixtures: { 'plan.md': FLAWED_PLAN + '\n## CLI\nShip a `mytool pricing` command and a setup wizard for the new tier.\n' },
+    scenario: 'Read plan.md — that is the plan to review (developer-experience scope). Walk the review until the first AskUserQuestion.',
+  },
+  {
+    skill: 'office-hours',
+    fixtures: {},
+    scenario: 'The founder says: "I am building an AI tool that auto-writes unit tests for any repo. I think it is a great idea but I have zero users. Should I build it, and how do I get my first users?" Run the office-hours diagnostic until the first AskUserQuestion.',
+  },
+  {
+    skill: 'cso',
+    fixtures: { 'server/auth.js': VULN_CODE },
+    scenario: 'Audit the code in this repo (server/auth.js) for security issues. Walk the audit until the first AskUserQuestion (scope/stack confirmation or first finding).',
+  },
+  {
+    skill: 'spec',
+    fixtures: {},
+    scenario: 'Turn this vague intent into a precise spec: "add email notifications when a task is assigned to someone." Walk the spec workflow until the first AskUserQuestion.',
+  },
+  {
+    skill: 'design-consultation',
+    fixtures: { 'product.md': '# Product\nA terminal-first task manager for developers. Audience: senior engineers. Stage: pre-launch.\n' },
+    scenario: 'Read product.md. Run the design consultation for this product until the first AskUserQuestion.',
+  },
+];
+
+const selected = ONLY.length ? MATRIX.filter(m => ONLY.includes(m.skill)) : MATRIX;
+
+describeE2E('AUQ behavioral matrix (periodic)', () => {
+  for (const m of selected) {
+    test(
+      `${m.skill}: first AUQ is a compliant decision brief (7/7 format, substance >=4)`,
+      async () => {
+        const wt = skillFromWorktree(m.skill);
+        const dir = setupSkillDir({
+          skillName: m.skill,
+          skillMd: wt.skillMd,
+          sectionsFrom: wt.sectionsFrom,
+          fixtures: m.fixtures,
+          tmpPrefix: `auq-matrix-${m.skill}-`,
+        });
+        let text = '';
+        try {
+          text = await captureFirstAuq({
+            planDir: dir,
+            skillName: m.skill,
+            scenario: m.scenario,
+            testName: `auq-matrix-${m.skill}`,
+            runId,
+          });
+        } finally {
+          fs.rmSync(dir, { recursive: true, force: true });
+        }
+
+        const fmt = scoreAuqFormat(text);
+        let substance = 0;
+        let recPresent = false;
+        let hadBecause = false;
+        if (text.trim()) {
+          const g = await gradeAuqRecommendation(text);
+          substance = g.substance;
+          recPresent = g.present;
+          hadBecause = g.hadLiteralBecause;
+        }
+        // eslint-disable-next-line no-console
+        console.log(
+          `[AUQ-matrix ${m.skill}] captured=${text.length}B format=${fmt.present}/${fmt.total} ` +
+            `missing=[${fmt.missing.join(',')}] recPresent=${recPresent} substance=${substance} ` +
+            `literalBecause=${hadBecause}`,
+        );
+
+        if (!text.trim()) {
+          throw new Error(`${m.skill}: agent produced NO AUQ capture (never reached a question in budget).`);
+        }
+        const problems: string[] = [];
+        if (fmt.missing.length > 0) problems.push(`missing format element(s): ${fmt.missing.join(', ')}`);
+        if (substance < 4) problems.push(`recommendation substance ${substance} < 4 (boilerplate/weak)`);
+        if (problems.length > 0) {
+          throw new Error(
+            `${m.skill} AUQ not at plan-ceo bar:\n  - ${problems.join('\n  - ')}\n--- captured AUQ ---\n${text}`,
+          );
+        }
+      },
+      300_000,
+    );
+  }
+});

test/skill-e2e-auq-verbose-vs-carved-ab.test.ts

@@ -0,0 +1,114 @@
+/**
+ * AUQ no-degradation A/B: verbose (full-token) vs carved (slimmed) — periodic,
+ * paid, SDK capture.
+ *
+ * The keystone empirical proof behind the token-reduction work: carving
+ * /plan-ceo-review into an 80KB skeleton + on-demand section did NOT degrade the
+ * AskUserQuestion it shows the user. Layer 0 (auq-format-always-loaded.test.ts)
+ * proves the format SPEC is present in both skeletons deterministically; this
+ * proves the model still GENERATES an equal-quality question with the smaller
+ * context.
+ *
+ * Method — identical prompt, two SKILL.md versions, compare:
+ *   - CARVED  : this branch's plan-ceo-review/SKILL.md (80KB skeleton) + sections.
+ *   - VERBOSE : the pre-carve monolith (137KB) read from git (ab66193e^).
+ * Both are driven to Step 0F mode selection via the SDK $OUT_FILE capture path
+ * (clean text, no TTY mangling). We score the 7 decision-brief format elements
+ * and grade recommendation substance, then assert the carved version is NOT
+ * WORSE than verbose. Relative parity is the bar (absolute compliance is the
+ * format-compliance gate test's job).
+ *
+ * Expectation: carved >= verbose. At the mode-selection AUQ the carved skeleton
+ * carries the same {{PREAMBLE}} format spec + Step 0 prose as verbose, with
+ * strictly less unrelated review-section text in context.
+ */
+import { describe, test } from 'bun:test';
+import * as fs from 'node:fs';
+import {
+  setupPlanCeoDir,
+  captureModeSelectionAuq,
+  scoreAuqFormat,
+  carvedSkill,
+  verboseSkill,
+} from './helpers/auq-sdk-capture';
+import { judgeRecommendation } from './helpers/llm-judge';
+
+const shouldRun = !!process.env.EVALS && process.env.EVALS_TIER === 'periodic';
+const describeE2E = shouldRun ? describe : describe.skip;
+const runId = `auq-ab-${process.env.EVALS_RUN_ID ?? 'local'}`;
+
+async function grade(label: string, dir: string) {
+  const text = await captureModeSelectionAuq({ planDir: dir, testName: `auq-ab-${label}`, runId });
+  const fmt = scoreAuqFormat(text);
+  let substance = 0;
+  let present = false;
+  if (text.trim()) {
+    try {
+      const r = await judgeRecommendation(text);
+      substance = r.reason_substance;
+      present = r.present;
+    } catch { /* judge unavailable */ }
+  }
+  // eslint-disable-next-line no-console
+  console.log(
+    `[AUQ-AB ${label}] captured=${text.length}B format=${fmt.present}/${fmt.total} ` +
+      `missing=[${fmt.missing.join(',')}] recPresent=${present} substance=${substance}`,
+  );
+  return { text, fmt, substance };
+}
+
+describeE2E('AUQ no-degradation: verbose vs carved (periodic)', () => {
+  test(
+    'carved plan-ceo-review AUQ is not worse than verbose on the same prompt',
+    async () => {
+      const carved = carvedSkill();
+      const carvedDir = setupPlanCeoDir({
+        skillMd: carved.skillMd,
+        sectionsFrom: carved.sectionsFrom,
+        tmpPrefix: 'auq-ab-carved-',
+      });
+      const verboseDir = setupPlanCeoDir({
+        skillMd: verboseSkill(),
+        tmpPrefix: 'auq-ab-verbose-',
+      });
+
+      let c, v;
+      try {
+        c = await grade('CARVED', carvedDir);
+        v = await grade('VERBOSE', verboseDir);
+      } finally {
+        fs.rmSync(carvedDir, { recursive: true, force: true });
+        fs.rmSync(verboseDir, { recursive: true, force: true });
+      }
+
+      const summary = [
+        `CARVED : format ${c.fmt.present}/${c.fmt.total}, substance ${c.substance}`,
+        `VERBOSE: format ${v.fmt.present}/${v.fmt.total}, substance ${v.substance}`,
+      ].join('\n');
+
+      // Both must have actually produced a question, else the comparison is
+      // vacuous — fail loud with the captures.
+      if (!c.text.trim() || !v.text.trim()) {
+        throw new Error(
+          `A/B inconclusive — a side produced no AUQ capture:\n${summary}\n` +
+            `--- carved ---\n${c.text.slice(0, 2000)}\n--- verbose ---\n${v.text.slice(0, 2000)}`,
+        );
+      }
+
+      const formatRegressed = c.fmt.present < v.fmt.present;
+      const substanceRegressed = c.substance < v.substance - 1; // 1-pt judge tolerance
+      if (formatRegressed || substanceRegressed) {
+        throw new Error(
+          `AUQ DEGRADATION carving plan-ceo-review:\n${summary}` +
+            (formatRegressed ? `\n  -> carved dropped: [${c.fmt.missing.join(',')}]` : '') +
+            (substanceRegressed ? `\n  -> carved substance regressed >1 pt` : '') +
+            `\n--- carved AUQ ---\n${c.text}\n--- verbose AUQ ---\n${v.text}`,
+        );
+      }
+
+      // eslint-disable-next-line no-console
+      console.log('[AUQ-AB] NO DEGRADATION:\n' + summary);
+    },
+    600_000,
+  );
+});

test/skill-e2e-design.test.ts

@@ -326,6 +326,7 @@ describeIfSelected('Plan Design Review E2E', ['plan-design-review-plan-mode', 'p
       path.join(ROOT, 'plan-design-review', 'SKILL.md'),
       path.join(dir, 'plan-design-review', 'SKILL.md'),
     );
+    { const _sec = path.join(ROOT, 'plan-design-review', 'sections'); if (fs.existsSync(_sec)) fs.cpSync(_sec, path.join(dir, 'plan-design-review', 'sections'), { recursive: true }); }
 
     return dir;
   }

test/skill-e2e-office-hours-brain-writeback.test.ts

@@ -104,6 +104,13 @@ describeIfSelected(
       );
       const skillPath = join(ROOT, 'office-hours', 'SKILL.md');
       const originalSkill = readFileSync(skillPath, 'utf-8');
+      // office-hours is carved (v2 plan T9): GBRAIN_SAVE_RESULTS moved into
+      // sections/design-and-handoff.md. Regen rewrites BOTH the skeleton and the
+      // section, so we snapshot + restore + ship both, and check the UNION for
+      // the gbrain put block.
+      const sectionPath = join(ROOT, 'office-hours', 'sections', 'design-and-handoff.md');
+      const hasSection = existsSync(sectionPath);
+      const originalSection = hasSection ? readFileSync(sectionPath, 'utf-8') : null;
       try {
         execFileSync(
           'bun',
@@ -122,17 +129,23 @@ describeIfSelected(
           },
         );
         const brainAwareSkill = readFileSync(skillPath, 'utf-8');
-        if (!brainAwareSkill.includes('gbrain put "office-hours/')) {
+        const brainAwareSection = hasSection ? readFileSync(sectionPath, 'utf-8') : '';
+        if (!(brainAwareSkill + brainAwareSection).includes('gbrain put "office-hours/')) {
           throw new Error(
-            'Regenerated office-hours/SKILL.md does not contain gbrain put block. ' +
+            'Regenerated office-hours skeleton+section does not contain gbrain put block. ' +
               'Detection override may be broken — see test/gbrain-detection-override.test.ts.',
           );
         }
         mkdirSync(join(workDir, 'office-hours'), { recursive: true });
         writeFileSync(join(workDir, 'office-hours', 'SKILL.md'), brainAwareSkill);
+        if (hasSection) {
+          mkdirSync(join(workDir, 'office-hours', 'sections'), { recursive: true });
+          writeFileSync(join(workDir, 'office-hours', 'sections', 'design-and-handoff.md'), brainAwareSection);
+        }
       } finally {
-        // Always restore the canonical SKILL.md so the working tree stays clean.
+        // Always restore the canonical skeleton + section so the working tree stays clean.
         writeFileSync(skillPath, originalSkill);
+        if (hasSection && originalSection !== null) writeFileSync(sectionPath, originalSection);
         rmSync(tmpHome, { recursive: true, force: true });
       }
 

test/skill-e2e-office-hours.test.ts

@@ -53,6 +53,7 @@ describeIfSelected('Office Hours Forcing Energy E2E', ['office-hours-forcing-ene
       path.join(ROOT, 'office-hours', 'SKILL.md'),
       path.join(workDir, 'office-hours', 'SKILL.md'),
     );
+    { const _sec = path.join(ROOT, 'office-hours', 'sections'); if (fs.existsSync(_sec)) fs.cpSync(_sec, path.join(workDir, 'office-hours', 'sections'), { recursive: true }); }
   });
 
   afterAll(() => {
@@ -124,6 +125,7 @@ describeIfSelected('Office Hours Builder Wildness E2E', ['office-hours-builder-w
       path.join(ROOT, 'office-hours', 'SKILL.md'),
       path.join(workDir, 'office-hours', 'SKILL.md'),
     );
+    { const _sec = path.join(ROOT, 'office-hours', 'sections'); if (fs.existsSync(_sec)) fs.cpSync(_sec, path.join(workDir, 'office-hours', 'sections'), { recursive: true }); }
   });
 
   afterAll(() => {

test/skill-e2e-plan-ceo-review-section-loading.test.ts

@@ -0,0 +1,191 @@
+/**
+ * /plan-ceo-review section-loading E2E (periodic, paid, real-PTY) — v2 plan
+ * Phase B carve backstop. The per-PR guard is the free static test
+ * skill-ceo-section-ordering.test.ts; THIS is the behavioral proof that a real
+ * agent actually Reads the carved section instead of working from memory.
+ *
+ * After the carve, plan-ceo-review is a skeleton whose single STOP-Read directive
+ * (fired after Step 0 mode selection) points at sections/review-sections.md. This
+ * test runs the REAL /plan-ceo-review skill in plan mode against a fixture branch
+ * that has a plan worth reviewing, drives Step 0 to HOLD SCOPE (the simplest mode
+ * that still requires all 11 review sections), and asserts the agent Read
+ * review-sections.md before producing the review report.
+ *
+ * Codex outside-voice P1 fixes vs the naive port of the ship test:
+ *  - REFRESH THE INSTALL FIRST. The skill loads from the installed copy at
+ *    ~/.claude/skills/gstack/plan-ceo-review (a real copy on dev machines, fresh
+ *    on CI). A test that didn't refresh would assert against the pre-carve
+ *    monolith and trivially "pass" with zero section reads. beforeAll copies the
+ *    freshly-generated skeleton + sections into the install; afterAll restores the
+ *    prior state so a local run doesn't leave the active skill mutated.
+ *  - HANDLE THE FULL STEP 0. plan-ceo's Step 0 can fire a system audit, WebSearch,
+ *    and several AskUserQuestion calls before mode selection — the answer loop
+ *    replies to every permission dialog / numbered list, not just two.
+ *
+ * Plan-mode framing keeps the agent from editing/committing. Cost: ~$3-5/run.
+ * Periodic tier.
+ */
+
+import { describe, test, expect } from 'bun:test';
+import { spawnSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import {
+  launchClaudePty,
+  isPermissionDialogVisible,
+  isNumberedOptionListVisible,
+} from './helpers/claude-pty-runner';
+
+const shouldRun = !!process.env.EVALS && process.env.EVALS_TIER === 'periodic';
+const describeE2E = shouldRun ? describe : describe.skip;
+
+const REPO_ROOT = path.resolve(import.meta.dir, '..');
+const INSTALL_DIR = path.join(os.homedir(), '.claude', 'skills', 'gstack', 'plan-ceo-review');
+
+// Sections every plan-ceo-review run must consult after Step 0.
+const REQUIRED_SECTIONS = ['review-sections.md'];
+
+/** Copy the freshly-generated skeleton + sections into the installed skill so the
+ *  PTY agent loads the carve under test. Returns a restore() that puts the install
+ *  back exactly as it was (content of SKILL.md + presence/content of sections/). */
+function refreshInstall(): () => void {
+  const repoSkill = path.join(REPO_ROOT, 'plan-ceo-review', 'SKILL.md');
+  const repoSections = path.join(REPO_ROOT, 'plan-ceo-review', 'sections');
+  const installSkill = path.join(INSTALL_DIR, 'SKILL.md');
+  const installSections = path.join(INSTALL_DIR, 'sections');
+
+  // Snapshot prior state for restore.
+  const priorSkill = fs.existsSync(installSkill) ? fs.readFileSync(installSkill) : null;
+  const hadSections = fs.existsSync(installSections);
+  const priorSections: Record<string, Buffer> = {};
+  if (hadSections) {
+    for (const f of fs.readdirSync(installSections)) {
+      priorSections[f] = fs.readFileSync(path.join(installSections, f));
+    }
+  }
+
+  // Apply: skeleton + every generated section file (.md) + manifest.
+  fs.mkdirSync(INSTALL_DIR, { recursive: true });
+  fs.copyFileSync(repoSkill, installSkill);
+  fs.mkdirSync(installSections, { recursive: true });
+  for (const f of fs.readdirSync(repoSections)) {
+    if (f.endsWith('.md.tmpl')) continue; // install carries generated files, not templates
+    fs.copyFileSync(path.join(repoSections, f), path.join(installSections, f));
+  }
+
+  return function restore(): void {
+    try {
+      if (priorSkill) fs.writeFileSync(installSkill, priorSkill);
+      if (hadSections) {
+        // Restore the prior section files; drop any we added.
+        for (const f of fs.readdirSync(installSections)) {
+          if (!(f in priorSections)) fs.rmSync(path.join(installSections, f), { force: true });
+        }
+        for (const [f, buf] of Object.entries(priorSections)) {
+          fs.writeFileSync(path.join(installSections, f), buf);
+        }
+      } else {
+        fs.rmSync(installSections, { recursive: true, force: true });
+      }
+    } catch { /* best-effort restore */ }
+  };
+}
+
+/** Fixture: a feature branch with a real change + a plan file worth reviewing. */
+function buildPlanFixture(): { workTree: string; root: string } {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-ceo-secload-'));
+  const workTree = path.join(root, 'workspace');
+  const bareRemote = path.join(root, 'origin.git');
+  fs.mkdirSync(workTree, { recursive: true });
+  const sh = (cmd: string, cwd: string): void => {
+    const r = spawnSync('bash', ['-c', cmd], { cwd, stdio: 'pipe', timeout: 15_000 });
+    if (r.status !== 0) throw new Error(`fixture setup failed at "${cmd}":\n${r.stderr?.toString()}`);
+  };
+  sh(`git init --bare "${bareRemote}"`, root);
+  sh('git init -b main', workTree);
+  sh('git config user.email "t@t.com" && git config user.name "T" && git config commit.gpgsign false', workTree);
+  fs.writeFileSync(path.join(workTree, 'app.js'), '// base\n');
+  sh('git add -A && git commit -m "chore: initial"', workTree);
+  sh(`git remote add origin "${bareRemote}" && git push -u origin main`, workTree);
+  // Feature branch with a real change + a plan describing it (something to review).
+  sh('git checkout -b feat/cache-layer', workTree);
+  fs.writeFileSync(
+    path.join(workTree, 'PLAN.md'),
+    [
+      '# Plan: add an in-memory cache layer',
+      '',
+      '## Context',
+      'Reads hit the DB on every request. Add a process-local LRU cache in front of',
+      'the read path to cut DB load.',
+      '',
+      '## Approach',
+      '- Wrap the read repository in a cache that stores the last 1000 keys.',
+      '- Invalidate on write.',
+      '',
+      '## Out of scope',
+      'Distributed cache, cross-process coherence.',
+      '',
+    ].join('\n'),
+  );
+  fs.writeFileSync(path.join(workTree, 'app.js'), '// base\nexport function read(k) { return db.get(k); }\n');
+  sh('git add -A && git commit -m "feat: cache layer plan + stub"', workTree);
+  sh('git push -u origin feat/cache-layer', workTree);
+  return { workTree, root };
+}
+
+describeE2E('/plan-ceo-review section-loading E2E (periodic, real-PTY, installed skill)', () => {
+  test(
+    'a real review Reads the carved section before producing the report',
+    async () => {
+      const restore = refreshInstall();
+      const { workTree, root } = buildPlanFixture();
+      const session = await launchClaudePty({
+        permissionMode: 'plan',
+        cwd: workTree,
+        timeoutMs: 900_000,
+        env: { NO_COLOR: '1' },
+      });
+
+      const readSections = new Set<string>();
+      let reportReady = false;
+      try {
+        await Bun.sleep(8000);
+        const since = session.mark();
+        // HOLD SCOPE = simplest mode that still walks all 11 review sections.
+        session.send('/plan-ceo-review review PLAN.md, hold scope\r');
+        const start = Date.now();
+        let lastPermSig = '';
+        while (Date.now() - start < 780_000) {
+          await Bun.sleep(3000);
+          if (session.exited()) break;
+          const visible = session.visibleSince(since);
+          const tail = visible.slice(-1500);
+          // Answer EVERY permission dialog / numbered option list (system audit,
+          // WebSearch, and the several Step 0 questions) by taking option 1.
+          if (isNumberedOptionListVisible(tail) && isPermissionDialogVisible(tail)) {
+            const sig = visible.slice(-500);
+            if (sig !== lastPermSig) { lastPermSig = sig; session.send('1\r'); await Bun.sleep(1500); continue; }
+          }
+          for (const m of visible.matchAll(/sections\/([A-Za-z0-9._-]+\.md)/g)) readSections.add(m[1]);
+          if (/GSTACK REVIEW REPORT|COMPLETION SUMMARY|ready to execute/i.test(visible)) {
+            reportReady = true;
+            break;
+          }
+        }
+      } finally {
+        await session.close();
+        try { fs.rmSync(root, { recursive: true, force: true }); } catch { /* ignore */ }
+        restore();
+      }
+
+      const missing = REQUIRED_SECTIONS.filter(s => !readSections.has(s));
+      expect({ reportReady, read: [...readSections], missing }).toEqual({
+        reportReady: true,
+        read: expect.any(Array),
+        missing: [],
+      });
+    },
+    1_020_000,
+  );
+});

test/skill-e2e-plan.test.ts

@@ -61,6 +61,8 @@ We're building a new user dashboard that shows recent activity, notifications, a
       path.join(ROOT, 'plan-ceo-review', 'SKILL.md'),
       path.join(planDir, 'plan-ceo-review', 'SKILL.md'),
     );
+    // Carved skills (v2 plan T9): copy sections/ so the review workflow + report template are present.
+    { const _sec = path.join(ROOT, 'plan-ceo-review', 'sections'); if (fs.existsSync(_sec)) fs.cpSync(_sec, path.join(planDir, 'plan-ceo-review', 'sections'), { recursive: true }); }
   });
 
   afterAll(() => {
@@ -145,6 +147,8 @@ We're building a new user dashboard that shows recent activity, notifications, a
       path.join(ROOT, 'plan-ceo-review', 'SKILL.md'),
       path.join(planDir, 'plan-ceo-review', 'SKILL.md'),
     );
+    // Carved skills (v2 plan T9): copy sections/ so the review workflow + report template are present.
+    { const _sec = path.join(ROOT, 'plan-ceo-review', 'sections'); if (fs.existsSync(_sec)) fs.cpSync(_sec, path.join(planDir, 'plan-ceo-review', 'sections'), { recursive: true }); }
   });
 
   afterAll(() => {
@@ -213,6 +217,8 @@ describeIfSelected('Plan CEO Review Expansion Energy E2E', ['plan-ceo-review-exp
       path.join(ROOT, 'plan-ceo-review', 'SKILL.md'),
       path.join(planDir, 'plan-ceo-review', 'SKILL.md'),
     );
+    // Carved skills (v2 plan T9): copy sections/ so the review workflow + report template are present.
+    { const _sec = path.join(ROOT, 'plan-ceo-review', 'sections'); if (fs.existsSync(_sec)) fs.cpSync(_sec, path.join(planDir, 'plan-ceo-review', 'sections'), { recursive: true }); }
   });
 
   afterAll(() => {
@@ -319,6 +325,8 @@ Replace session-cookie auth with JWT tokens. Currently using express-session + R
       path.join(ROOT, 'plan-eng-review', 'SKILL.md'),
       path.join(planDir, 'plan-eng-review', 'SKILL.md'),
     );
+    // Carved skills (v2 plan T9): copy sections/ so the review workflow + report template are present.
+    { const _sec = path.join(ROOT, 'plan-eng-review', 'sections'); if (fs.existsSync(_sec)) fs.cpSync(_sec, path.join(planDir, 'plan-eng-review', 'sections'), { recursive: true }); }
   });
 
   afterAll(() => {
@@ -415,6 +423,8 @@ export function main() { return Dashboard(); }
       path.join(ROOT, 'plan-eng-review', 'SKILL.md'),
       path.join(planDir, 'plan-eng-review', 'SKILL.md'),
     );
+    // Carved skills (v2 plan T9): copy sections/ so the review workflow + report template are present.
+    { const _sec = path.join(ROOT, 'plan-eng-review', 'sections'); if (fs.existsSync(_sec)) fs.cpSync(_sec, path.join(planDir, 'plan-eng-review', 'sections'), { recursive: true }); }
 
     // Set up remote-slug shim and browse shims (plan-eng-review uses remote-slug for artifact path)
     setupBrowseShims(planDir);
@@ -520,6 +530,7 @@ describeIfSelected('Office Hours Spec Review E2E', ['office-hours-spec-review'],
       path.join(ROOT, 'office-hours', 'SKILL.md'),
       path.join(ohDir, 'office-hours', 'SKILL.md'),
     );
+    { const _sec = path.join(ROOT, 'office-hours', 'sections'); if (fs.existsSync(_sec)) fs.cpSync(_sec, path.join(ohDir, 'office-hours', 'sections'), { recursive: true }); }
   });
 
   afterAll(() => {
@@ -580,6 +591,7 @@ describeIfSelected('Plan CEO Review Benefits-From E2E', ['plan-ceo-review-benefi
       path.join(ROOT, 'plan-ceo-review', 'SKILL.md'),
       path.join(benefitsDir, 'plan-ceo-review', 'SKILL.md'),
     );
+    { const _sec = path.join(ROOT, 'plan-ceo-review', 'sections'); if (fs.existsSync(_sec)) fs.cpSync(_sec, path.join(benefitsDir, 'plan-ceo-review', 'sections'), { recursive: true }); }
   });
 
   afterAll(() => {
@@ -663,6 +675,8 @@ We're building a real-time notification system for our SaaS app.
       path.join(ROOT, 'plan-eng-review', 'SKILL.md'),
       path.join(planDir, 'plan-eng-review', 'SKILL.md'),
     );
+    // Carved skills (v2 plan T9): copy sections/ so the review workflow + report template are present.
+    { const _sec = path.join(ROOT, 'plan-eng-review', 'sections'); if (fs.existsSync(_sec)) fs.cpSync(_sec, path.join(planDir, 'plan-eng-review', 'sections'), { recursive: true }); }
   });
 
   afterAll(() => {
@@ -760,6 +774,10 @@ describeIfSelected('Codex Offering E2E', [
         path.join(ROOT, skill, 'SKILL.md'),
         path.join(testDir, skill, 'SKILL.md'),
       );
+      // Carved skills (v2 plan T9): copy sections/ so codex/outside-voice content
+      // (carved into review-sections.md) is present for the search.
+      const _sec = path.join(ROOT, skill, 'sections');
+      if (fs.existsSync(_sec)) fs.cpSync(_sec, path.join(testDir, skill, 'sections'), { recursive: true });
     }
   });
 

test/skill-e2e.test.ts

@@ -890,6 +890,7 @@ We're building a new user dashboard that shows recent activity, notifications, a
       path.join(ROOT, 'plan-ceo-review', 'SKILL.md'),
       path.join(planDir, 'plan-ceo-review', 'SKILL.md'),
     );
+    { const _sec = path.join(ROOT, 'plan-ceo-review', 'sections'); if (fs.existsSync(_sec)) fs.cpSync(_sec, path.join(planDir, 'plan-ceo-review', 'sections'), { recursive: true }); }
   });
 
   afterAll(() => {
@@ -974,6 +975,7 @@ We're building a new user dashboard that shows recent activity, notifications, a
       path.join(ROOT, 'plan-ceo-review', 'SKILL.md'),
       path.join(planDir, 'plan-ceo-review', 'SKILL.md'),
     );
+    { const _sec = path.join(ROOT, 'plan-ceo-review', 'sections'); if (fs.existsSync(_sec)) fs.cpSync(_sec, path.join(planDir, 'plan-ceo-review', 'sections'), { recursive: true }); }
   });
 
   afterAll(() => {
@@ -1068,6 +1070,7 @@ Replace session-cookie auth with JWT tokens. Currently using express-session + R
       path.join(ROOT, 'plan-eng-review', 'SKILL.md'),
       path.join(planDir, 'plan-eng-review', 'SKILL.md'),
     );
+    { const _sec = path.join(ROOT, 'plan-eng-review', 'sections'); if (fs.existsSync(_sec)) fs.cpSync(_sec, path.join(planDir, 'plan-eng-review', 'sections'), { recursive: true }); }
   });
 
   afterAll(() => {
@@ -1450,6 +1453,7 @@ export function main() { return Dashboard(); }
       path.join(ROOT, 'plan-eng-review', 'SKILL.md'),
       path.join(planDir, 'plan-eng-review', 'SKILL.md'),
     );
+    { const _sec = path.join(ROOT, 'plan-eng-review', 'sections'); if (fs.existsSync(_sec)) fs.cpSync(_sec, path.join(planDir, 'plan-eng-review', 'sections'), { recursive: true }); }
 
     // Set up remote-slug shim and browse shims (plan-eng-review uses remote-slug for artifact path)
     setupBrowseShims(planDir);
@@ -2256,6 +2260,7 @@ describeIfSelected('Plan Design Review E2E', ['plan-design-review-plan-mode', 'p
       path.join(ROOT, 'plan-design-review', 'SKILL.md'),
       path.join(reviewDir, 'plan-design-review', 'SKILL.md'),
     );
+    { const _sec = path.join(ROOT, 'plan-design-review', 'sections'); if (fs.existsSync(_sec)) fs.cpSync(_sec, path.join(reviewDir, 'plan-design-review', 'sections'), { recursive: true }); }
 
     // Create a plan file with intentional design gaps
     fs.writeFileSync(path.join(reviewDir, 'plan.md'), `# Plan: User Dashboard
@@ -3158,6 +3163,7 @@ describeIfSelected('Office Hours Spec Review E2E', ['office-hours-spec-review'],
       path.join(ROOT, 'office-hours', 'SKILL.md'),
       path.join(ohDir, 'office-hours', 'SKILL.md'),
     );
+    { const _sec = path.join(ROOT, 'office-hours', 'sections'); if (fs.existsSync(_sec)) fs.cpSync(_sec, path.join(ohDir, 'office-hours', 'sections'), { recursive: true }); }
   });
 
   afterAll(() => {
@@ -3220,6 +3226,7 @@ describeIfSelected('Plan CEO Review Benefits-From E2E', ['plan-ceo-review-benefi
       path.join(ROOT, 'plan-ceo-review', 'SKILL.md'),
       path.join(benefitsDir, 'plan-ceo-review', 'SKILL.md'),
     );
+    { const _sec = path.join(ROOT, 'plan-ceo-review', 'sections'); if (fs.existsSync(_sec)) fs.cpSync(_sec, path.join(benefitsDir, 'plan-ceo-review', 'sections'), { recursive: true }); }
   });
 
   afterAll(() => {

test/skill-llm-eval.test.ts

@@ -540,7 +540,19 @@ async function runWorkflowJudge(opts: {
   const defaults = { clarity: 4, completeness: 3, actionability: 4 };
   const thresholds = { ...defaults, ...opts.thresholds };
 
-  const content = fs.readFileSync(path.join(ROOT, opts.skillPath), 'utf-8');
+  // Read the skeleton + sections UNION so carved skills (v2 plan T9) still
+  // expose markers that moved into sections/*.md (e.g. plan-eng's "## Review
+  // Sections" + "## CRITICAL RULE", plan-design's 7 passes). Without this the
+  // slice markers vanish from the skeleton and the judge scores empty content.
+  let content = fs.readFileSync(path.join(ROOT, opts.skillPath), 'utf-8');
+  const secDir = path.join(ROOT, path.dirname(opts.skillPath), 'sections');
+  if (fs.existsSync(secDir)) {
+    for (const f of fs.readdirSync(secDir).sort()) {
+      if (f.endsWith('.md') && !f.endsWith('.md.tmpl')) {
+        content += '\n' + fs.readFileSync(path.join(secDir, f), 'utf-8');
+      }
+    }
+  }
   const startIdx = content.indexOf(opts.startMarker);
   if (startIdx === -1) throw new Error(`Start marker not found in ${opts.skillPath}: "${opts.startMarker}"`);
 

test/skill-size-budget.test.ts

@@ -146,11 +146,14 @@ describe('SKILL.md size budget regression (gate, free)', () => {
    * skill, so this is a comfortable ceiling that still catches accidental
    * mass deletion (e.g., a refactor that strips the body of a skill).
    *
-   * v2.0.0.0 will introduce the sections/ pattern for 5 heavyweights
+   * v2.0.0.0 introduces the sections/ pattern for 5 heavyweights
    * (ship, plan-ceo-review, office-hours, plan-eng-review,
-   * plan-design-review). Those skills will legitimately shrink to ~15 KB
+   * plan-design-review). Carved so far: ship (skeleton ~83 KB) and
-   * skeletons. When that lands, add them to SECTIONS_EXTRACTED so the floor
+   * plan-ceo-review (skeleton ~81 KB, down from the 138 KB monolith). Those
-   * relaxes for them.
+   * skeletons legitimately fall below the 80% body-strip floor, so each carved
+   * skill is added to SECTIONS_EXTRACTED; its union is guarded instead by the
+   * sectioned invariant in parity-harness.ts (minBytes on skeleton+sections).
+   * Add the remaining three here as they carve.
    */
   test('no skill shrinks past 80% of v1.47.0.0 baseline (catches accidental body strip)', () => {
     const baseline: ParityBaseline = JSON.parse(fs.readFileSync(BASELINE_PATH, 'utf-8'));
@@ -160,7 +163,7 @@ describe('SKILL.md size budget regression (gate, free)', () => {
     // because prose moved into sections/*.md. The union size is guarded instead
     // by the sectioned ship invariant in parity-harness.ts (minBytes on the
     // skeleton+sections union), so exempt the skeleton from the body-strip floor.
-    const SECTIONS_EXTRACTED = new Set<string>(['ship']);
+    const SECTIONS_EXTRACTED = new Set<string>(['ship', 'plan-ceo-review', 'office-hours', 'plan-eng-review', 'plan-design-review', 'plan-devex-review']);
 
     const undershoots: Array<{
       skill: string; beforeBytes: number; afterBytes: number; ratio: number;

test/skill-validation.test.ts

@@ -7,14 +7,13 @@ import * as path from 'path';
 
 const ROOT = path.resolve(import.meta.dir, '..');
 
-// Carved-skill aware (v2 plan T9): ship is a skeleton SKILL.md + sections/*.md.
+// Carved-skill aware (v2 plan T9 / Phase B): a carved skill is a skeleton SKILL.md
-// Read the union so validations of content that moved into a section still hold.
+// plus sections/*.md. Read the union so validations of content that moved into a
-// `_SHIP_MD` is a distinct path expression so a mechanical read-replace can't
+// section still hold. For an uncarved skill (no sections dir) this is just the
-// recurse into this helper.
+// skeleton, so readSkillUnion is safe to use everywhere.
-const _SHIP_MD = path.join(ROOT, 'ship', 'SKILL.md');
+function readSkillUnion(skill: string): string {
-function readShipUnion(): string {
+  let t = fs.readFileSync(path.join(ROOT, skill, 'SKILL.md'), 'utf-8');
-  let t = fs.readFileSync(_SHIP_MD, 'utf-8');
+  const secDir = path.join(ROOT, skill, 'sections');
-  const secDir = path.join(ROOT, 'ship', 'sections');
   if (fs.existsSync(secDir)) {
     for (const f of fs.readdirSync(secDir).sort()) {
       if (f.endsWith('.md')) t += '\n' + fs.readFileSync(path.join(secDir, f), 'utf-8');
@@ -22,6 +21,9 @@ function readShipUnion(): string {
   }
   return t;
 }
+function readShipUnion(): string {
+  return readSkillUnion('ship');
+}
 
 describe('SKILL.md command validation', () => {
   test('all $B commands in SKILL.md are valid browse commands', () => {
@@ -548,8 +550,8 @@ describe('TODOS-format.md reference consistency', () => {
 
   test('skills that write TODOs reference TODOS-format.md', () => {
     const shipContent = readShipUnion();
-    const ceoPlanContent = fs.readFileSync(path.join(ROOT, 'plan-ceo-review', 'SKILL.md'), 'utf-8');
+    const ceoPlanContent = readSkillUnion('plan-ceo-review'); // carved: TODOS-format ref moved to section
-    const engPlanContent = fs.readFileSync(path.join(ROOT, 'plan-eng-review', 'SKILL.md'), 'utf-8');
+    const engPlanContent = readSkillUnion('plan-eng-review');
 
     expect(shipContent).toContain('TODOS-format.md');
     expect(ceoPlanContent).toContain('TODOS-format.md');
@@ -621,7 +623,10 @@ describe('v0.4.1 preamble features', () => {
 // --- Structural tests for new skills ---
 
 describe('office-hours skill structure', () => {
-  const content = fs.readFileSync(path.join(ROOT, 'office-hours', 'SKILL.md'), 'utf-8');
+  // Carved (v2 plan T9): Phase 5 (Design Doc) + Phase 6 (handoff) moved into
+  // sections/design-and-handoff.md, so structural phrases now live there — read
+  // the skeleton+sections union.
+  const content = readSkillUnion('office-hours');
 
   // Original structural assertions
   for (const section of ['Phase 1', 'Phase 2', 'Phase 3', 'Phase 4', 'Phase 5', 'Phase 6',
@@ -912,8 +917,10 @@ describe('CEO review mode validation', () => {
   });
 
   test('has docs/designs promotion section', () => {
-    expect(content).toContain('docs/designs');
+    // Carved (v2 plan Phase B): the promotion block moved into the review section.
-    expect(content).toContain('PROMOTED');
+    const union = readSkillUnion('plan-ceo-review');
+    expect(union).toContain('docs/designs');
+    expect(union).toContain('PROMOTED');
   });
 
   test('mode quick reference has four columns', () => {

test/touchfiles.test.ts

@@ -94,7 +94,7 @@ describe('selectTests', () => {
     expect(result.selected).toContain('plan-review-prosons-hardstop-neg');
     expect(result.selected).toContain('plan-review-prosons-neutral-neg');
     // v1.13.x real-PTY E2E batch entries that also depend on plan-ceo-review/**
-    expect(result.selected).toContain('ask-user-question-format-pty');
+    expect(result.selected).toContain('auq-format-gate');
     expect(result.selected).toContain('plan-ceo-mode-routing');
     expect(result.selected).toContain('autoplan-chain-pty');
     // Per-finding count + review-report-at-bottom (v1.21.x)
@@ -109,8 +109,10 @@ describe('selectTests', () => {
     // E2E test also depends on plan-ceo-review/** (5-option scope decision
     // regression for the "drop to fit 4 options" failure mode).
     expect(result.selected).toContain('plan-ceo-split-overflow');
-    expect(result.selected.length).toBe(22);
+    // v2 plan Phase B carve: the section-loading E2E depends on plan-ceo-review/**.
-    expect(result.skipped.length).toBe(Object.keys(E2E_TOUCHFILES).length - 22);
+    expect(result.selected).toContain('plan-ceo-section-loading');
+    expect(result.selected.length).toBe(23);
+    expect(result.skipped.length).toBe(Object.keys(E2E_TOUCHFILES).length - 23);
   });
 
   test('global touchfile triggers ALL tests', () => {