diff --git a/scripts/question-registry.ts b/scripts/question-registry.ts index 3d90222a..bae5950c 100644 --- a/scripts/question-registry.ts +++ b/scripts/question-registry.ts @@ -261,45 +261,6 @@ export const QUESTIONS = { description: "Approve the design doc, revise sections, or start over?", }, - // ----------------------------------------------------------------------- - // Plan-mode handshake — fires at the top of any interactive review skill - // when the user is in plan mode. Safety-critical, always asked regardless - // of user's tuning preferences. See scripts/resolvers/preamble/generate- - // plan-mode-handshake.ts. - // ----------------------------------------------------------------------- - 'plan-ceo-review-plan-mode-handshake': { - id: 'plan-ceo-review-plan-mode-handshake', - skill: 'plan-ceo-review', - category: 'routing', - door_type: 'one-way', - options: ['exit-and-rerun', 'cancel'], - description: "Plan mode detected — exit and rerun interactively, or cancel?", - }, - 'plan-eng-review-plan-mode-handshake': { - id: 'plan-eng-review-plan-mode-handshake', - skill: 'plan-eng-review', - category: 'routing', - door_type: 'one-way', - options: ['exit-and-rerun', 'cancel'], - description: "Plan mode detected — exit and rerun interactively, or cancel?", - }, - 'plan-design-review-plan-mode-handshake': { - id: 'plan-design-review-plan-mode-handshake', - skill: 'plan-design-review', - category: 'routing', - door_type: 'one-way', - options: ['exit-and-rerun', 'cancel'], - description: "Plan mode detected — exit and rerun interactively, or cancel?", - }, - 'plan-devex-review-plan-mode-handshake': { - id: 'plan-devex-review-plan-mode-handshake', - skill: 'plan-devex-review', - category: 'routing', - door_type: 'one-way', - options: ['exit-and-rerun', 'cancel'], - description: "Plan mode detected — exit and rerun interactively, or cancel?", - }, - // ----------------------------------------------------------------------- // /plan-ceo-review — scope & strategy // ----------------------------------------------------------------------- diff --git a/scripts/resolvers/preamble.ts b/scripts/resolvers/preamble.ts index ac32f4a9..b866e90b 100644 --- a/scripts/resolvers/preamble.ts +++ b/scripts/resolvers/preamble.ts @@ -22,9 +22,11 @@ import { generateQuestionTuning } from './question-tuning'; // Core bootstrap import { generatePreambleBash } from './preamble/generate-preamble-bash'; -import { generatePlanModeHandshake } from './preamble/generate-plan-mode-handshake'; import { generateUpgradeCheck } from './preamble/generate-upgrade-check'; -import { generateCompletionStatus } from './preamble/generate-completion-status'; +import { + generateCompletionStatus, + generatePlanModeInfo, +} from './preamble/generate-completion-status'; // One-time onboarding prompts import { generateLakeIntro } from './preamble/generate-lake-intro'; @@ -79,13 +81,12 @@ export function generatePreamble(ctx: TemplateContext): string { } const sections = [ generatePreambleBash(ctx), - // Plan-mode handshake at position 1: after bash (so _SESSION_ID / _BRANCH / - // _TEL env vars are live for the synchronous telemetry write) and before - // all onboarding AskUserQuestion gates (so fresh-install users in plan mode - // see the handshake first, not drowned in telemetry / proactive / routing - // prompts). Host-scoped to Claude + interactive-frontmatter-scoped inside - // the resolver — no-op for every other skill/host combination. - generatePlanModeHandshake(ctx), + // Plan-mode-skill semantics at position 1: after bash (so _SESSION_ID / + // _BRANCH / _TEL env vars are live) and before all onboarding gates so + // models read the authoritative "AskUserQuestion satisfies plan mode's + // end-of-turn" rule before any other instruction. Renders for all skills + // (not interactive-gated); the text applies universally. + generatePlanModeInfo(ctx), generateUpgradeCheck(ctx), generateWritingStyleMigration(ctx), generateLakeIntro(), diff --git a/scripts/resolvers/preamble/generate-completion-status.ts b/scripts/resolvers/preamble/generate-completion-status.ts index bbaac9c9..11d1c368 100644 --- a/scripts/resolvers/preamble/generate-completion-status.ts +++ b/scripts/resolvers/preamble/generate-completion-status.ts @@ -1,5 +1,41 @@ import type { TemplateContext } from '../types'; +/** + * Plan-mode-skill semantics block. + * + * Lives at the TOP of the preamble (position 1) so models read the authoritative + * plan-mode rule before any other instructions. Replaces the vestigial + * generate-plan-mode-handshake.ts that used to sit at this position and told + * interactive review skills to emit an exit-and-rerun handshake instead of + * running their interactive STOP-Ask workflow. + * + * Text is the same "Plan Mode Safe Operations" + "Skill Invocation During Plan + * Mode" blocks that previously lived at the tail of generateCompletionStatus(). + * Only the position changes. All skills (not just interactive: true) see this. + * + * Composition position: index 1 in scripts/resolvers/preamble.ts — after + * generatePreambleBash (so _SESSION_ID / _BRANCH / _TEL env vars exist before + * any plan-mode-aware telemetry) and before generateUpgradeCheck + onboarding + * gates. See ceo-plan 2026-04-24 "remove vestigial plan-mode handshake" for + * the full rationale. + */ +export function generatePlanModeInfo(_ctx: TemplateContext): string { + return `## Plan Mode Safe Operations + +In plan mode, these are always allowed (they inform the plan, don't modify source): +\`$B\` (browse), \`$D\` (design), \`codex exec\`/\`codex review\`, writes to \`~/.gstack/\`, +writes to the plan file, \`open\` for generated artifacts. + +## Skill Invocation During Plan Mode + +If the user invokes a skill in plan mode, that skill takes precedence over generic plan mode behavior. Treat it as executable instructions, not reference. Follow step +by step. AskUserQuestion calls satisfy plan mode's end-of-turn requirement. At a STOP +point, stop immediately. Do not continue the workflow past a STOP point and do not call ExitPlanMode there. Commands marked "PLAN +MODE EXCEPTION — ALWAYS RUN" execute. Other writes need to be already permitted +above or explicitly exception-marked. Call ExitPlanMode only after the skill +workflow completes — only then call ExitPlanMode (or if the user tells you to cancel the skill or leave plan mode).`; +} + export function generateCompletionStatus(ctx: TemplateContext): string { return `## Completion Status Protocol @@ -81,21 +117,6 @@ success/error/abort, and \`USED_BROWSE\` with true/false based on whether \`$B\` If you cannot determine the outcome, use "unknown". The local JSONL always logs. The remote binary only runs if telemetry is not off and the binary exists. -## Plan Mode Safe Operations - -In plan mode, these are always allowed (they inform the plan, don't modify source): -\`$B\` (browse), \`$D\` (design), \`codex exec\`/\`codex review\`, writes to \`~/.gstack/\`, -writes to the plan file, \`open\` for generated artifacts. - -## Skill Invocation During Plan Mode - -If the user invokes a skill in plan mode, that skill takes precedence over generic plan mode behavior. Treat it as executable instructions, not reference. Follow step -by step. AskUserQuestion calls satisfy plan mode's end-of-turn requirement. At a STOP -point, stop immediately. Do not continue the workflow past a STOP point and do not call ExitPlanMode there. Commands marked "PLAN -MODE EXCEPTION — ALWAYS RUN" execute. Other writes need to be already permitted -above or explicitly exception-marked. Call ExitPlanMode only after the skill -workflow completes — only then call ExitPlanMode (or if the user tells you to cancel the skill or leave plan mode). - ## Plan Status Footer In plan mode, before ExitPlanMode: if the plan file lacks a \`## GSTACK REVIEW REPORT\` diff --git a/scripts/resolvers/preamble/generate-plan-mode-handshake.ts b/scripts/resolvers/preamble/generate-plan-mode-handshake.ts deleted file mode 100644 index e1b81a05..00000000 --- a/scripts/resolvers/preamble/generate-plan-mode-handshake.ts +++ /dev/null @@ -1,141 +0,0 @@ -/** - * Plan-mode handshake resolver. - * - * Emits a STOP-Ask gate at the very top of the preamble that fires when a user - * invokes an interactive review skill while their Claude Code session is in - * plan mode. Without this gate, plan mode's "This supercedes any other - * instructions you have received" system-reminder wins against the skill's - * interactive STOP-Ask workflow and the skill silently writes a plan file - * instead of running the per-finding AskUserQuestion loop (v1.10.2.0 bug fix). - * - * Host scope - * ---------- - * Only renders for Claude host (ctx.host === 'claude'). Other hosts use - * different plan-mode semantics (Codex, OpenClaw, etc.) and should not see - * Claude-specific ExitPlanMode / esc-esc prose. - * - * Opt-in - * ------ - * Only renders when the consuming skill's frontmatter has `interactive: true`. - * That flag is a generator-only input parsed by scripts/gen-skill-docs.ts - * from the skill's .tmpl frontmatter and passed through TemplateContext. - * Currently used by: plan-ceo-review, plan-eng-review, plan-design-review, - * plan-devex-review. - * - * Composition position - * -------------------- - * Inserted at index 1 in scripts/resolvers/preamble.ts — after - * generatePreambleBash (so _SESSION_ID, _BRANCH, _TEL env vars are live for - * the synchronous telemetry write) and before generateUpgradeCheck and all - * onboarding AskUserQuestion gates (so fresh-install users in plan mode see - * the handshake first, not drowned in telemetry / proactive / routing - * prompts). - * - * One-way door - * ------------ - * The handshake question_id `plan-mode-handshake` is classified door_type - * one-way in scripts/question-registry.ts. gstack-question-preference --check - * always returns ASK_NORMALLY for it, so a user who set `never-ask` on - * another question cannot accidentally suppress this safety gate. - */ - -import type { TemplateContext } from '../types'; - -export function generatePlanModeHandshake(ctx: TemplateContext): string { - if (ctx.host !== 'claude') return ''; - if (!ctx.interactive) return ''; - - return `## Plan Mode Handshake — FIRST, BEFORE ANY ANALYSIS - -**Check every \`\` in this turn for the literal phrase:** - -> \`Plan mode is active. The user indicated that they do not want you to execute yet\` - -If that phrase is **absent**: proceed normally. This section is a no-op. - -If that phrase is **present**, the user is in plan mode. Plan mode's system -reminder says "This supercedes any other instructions you have received," -which conflicts with this skill's interactive STOP-Ask workflow. You MUST -resolve the conflict via AskUserQuestion BEFORE reading any files, running -any bash, or composing any plan content. - -### What to do when plan mode is detected - -Before emitting the AskUserQuestion, run this bash block synchronously to -log that the handshake fired (captures A-exit and C-cancel outcomes that -would terminate the skill before end-of-skill telemetry runs): - -\`\`\`bash -# PLAN MODE EXCEPTION — ALWAYS RUN (telemetry-only write to ~/.gstack/) -mkdir -p ~/.gstack/analytics -echo '{"skill":"'"\${_SKILL_NAME:-unknown}"'","event":"plan_mode_handshake","outcome":"fired","branch":"'"\${_BRANCH:-unknown}"'","session":"'"\${_SESSION_ID:-unknown}"'","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true -\`\`\` - -Then emit exactly **one** AskUserQuestion with \`question_id: "\${SKILL_NAME}-plan-mode-handshake"\` -(e.g., \`plan-ceo-review-plan-mode-handshake\`, using the current skill's name) -and these two options. The question is classified \`door_type: one-way\` in -the question registry for every interactive skill, so question-tuning -preferences (\`never-ask\`, \`always-ask\`) do NOT apply — this gate always fires. - -**Question body (follow the AskUserQuestion Format section below):** - -> This skill runs an interactive review that stops at every finding to ask -> you a question. Plan mode's default workflow is "read files, write plan, -> exit" — that silently bypasses every STOP gate in this skill. How do you -> want to proceed? -> -> **Recommendation: A** because this skill was designed for back-and-forth. -> Each scope call and each per-section finding needs your decision before it -> lands in the plan. Exiting plan mode and running the skill normally is the -> only path that preserves the interactive contract. -> -> *Note: options differ in kind (workflow shape), not coverage — no -> completeness score.* -> -> **A) Exit plan mode and run interactively (recommended)** -> ✅ Every STOP gate in this skill fires as designed — you approve each -> scope call, each per-section finding, each cross-model tension before any -> decision lands in the plan. No silent bypass. -> ✅ Matches the skill's documented workflow. Each AskUserQuestion has a -> clear recommendation, pros/cons, and net line you can skim in ~5 seconds. -> ❌ Two-step: press esc-esc to exit plan mode, then rerun -> \`/plan-{skill-name}\`. Slight context-switch friction, but the alternative -> is shipping a rubber-stamp review. -> -> **C) Cancel — I meant to run something else** -> ✅ Clean exit, no partial state, no plan file written, no findings -> recorded. Use this if you invoked the skill by mistake. -> ❌ No output at all — no review, no plan file. Fine if that's what you -> want; otherwise pick A. -> -> **Net.** Plan mode is incompatible with this skill's per-finding STOP -> gates. A is the right choice for any real review; C is the bail-out. - -### Routing the user's answer - -**If the user picks A (exit and rerun):** - -1. Append the outcome to the telemetry log (synchronous, before ExitPlanMode): - \`\`\`bash - echo '{"skill":"'"\${_SKILL_NAME:-unknown}"'","event":"plan_mode_handshake","outcome":"A-exit","branch":"'"\${_BRANCH:-unknown}"'","session":"'"\${_SESSION_ID:-unknown}"'","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true - \`\`\` -2. Respond to the user: "Press **esc-esc** to exit plan mode, then rerun - \`/{skill-name}\`. The skill will run interactively with every STOP gate - firing as designed." -3. Call \`ExitPlanMode\` with an empty plan body (plan mode requires - turn-end via AskUserQuestion or ExitPlanMode; there is no plan to - approve, so ExitPlanMode with an empty message is the correct exit). - -**If the user picks C (cancel):** - -1. Append the outcome: - \`\`\`bash - echo '{"skill":"'"\${_SKILL_NAME:-unknown}"'","event":"plan_mode_handshake","outcome":"C-cancel","branch":"'"\${_BRANCH:-unknown}"'","session":"'"\${_SESSION_ID:-unknown}"'","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true - \`\`\` -2. Tell the user: "Cancelled. No plan written." -3. Call \`ExitPlanMode\` with an empty message noting the user cancelled. - -**After the handshake completes (either A or C),** do NOT continue with the -rest of this skill's workflow. The handshake is terminal for this turn. -`; -}