feat(migrate): Clarify assumption-sheet wizard — confirm defaults, ask only essential questions

[herosjourney]

Summary

Make the Clarify phase default to a confirm-or-edit wizard instead of a question-by-question interview. Everything the plugin can extract from discovery or safely default is presented up front as one assumption sheet — each row with its one-line design consequence — and only the questions with no safe default are asked directly.

User-visible result: a typical Terraform-discovered stack goes from ~12–18 questions across 2–3 batches to 1 sheet + 2–7 essential questions, with zero loss of information the user actually needed to provide. The full interview remains one reply away ("ask me everything").

Problem

Evidence from a real GCP-to-AWS run (small dev-tier stack: Cloud Run + Cloud SQL + Gemini):

• The plugin already extracted 8 answers (region, availability, DB size, DB traffic/IO, model, modalities, framework) and defaulted 9 more — yet the flow still walked the user through multi-question batches for values that were about to be defaulted anyway.
• Defaults are invisible until the report: the user never sees "I assumed balanced AI priority → Sonnet-class model" at a moment where correcting it is cheap.
• The existing Step 2.5 Confirm Detected Settings gate shows extracted values only. Defaulted values — the majority of the assumption surface — bypass user review entirely.
• The Defaults Table in clarify.md is incomplete: no rows for Q3.5, Q14, Q19, Q23–Q27, or the Category B billing prompts, so "use defaults for the rest" is under-specified for exactly the questions agents are most likely to improvise on.

Solution

1. Step 2.5 becomes the Assumption Sheet (extracted + defaulted)

Two sections, one gate:

• Detected — extracted values with source (terraform:availability_type=ZONAL, billing:, code:) — unchanged behavior, now merged into the sheet.
• Assumed — documented defaults with a one-line "consequence if left as-is" (e.g., "Assuming 24/7 Cloud Run traffic → conservative (higher) AWS estimate").

User replies "looks good", corrects inline (availability: mission-critical), converts a row to a full question (ask me about ai priority), or opts out entirely (ask me everything).

2. Question Disposition Catalog (new Step 3)

Every question in an active category gets exactly one disposition — DETECTED / PROPOSED / ESSENTIAL / N/A — from a single table in the orchestrator. Essential (never assumed silently):

Question	Why no safe default
Q2 compliance	Gates security baseline, regions, service catalog
Q7 maintenance window	Selects DMS vs pg_dump/pgcopydb and the runbook shape
Q1 region	Only when multi-region inventory makes extraction ambiguous
Q3 GCP spend	Only when no billing data
Q3.5 CUDs	Only fires when billing proves commitments exist
Q15 AI spend	Anchors Bedrock savings + credits tier; no discovery signal
Q23–Q25 agentic	Routes the entire agentic design path
Conflict rows	Multi-instance Cloud SQL disagreements

Category question files (clarify-global.md, clarify-compute.md, clarify-database.md, clarify-ai.md) are not modified — dispositions, defaults, and consequence lines are centralized in the orchestrator, keeping this PR to effectively one file. A maintenance note at the top of the catalog requires same-commit updates when category-file defaults change; co-locating consequence strings in the category files is a possible follow-up to prevent drift long-term.

3. Defaults Table completed (bug fix, stands on its own)

Added rows: Q3.5 (CUDs → none), Q14 (framework → auto-detect/["direct"]), Q19 (model → auto-detect), Q23–Q26 (agentic defaults per clarify-ai.md), Q27 (credits → unknown), and the four Category B billing prompts. Essential questions are annotated so "use defaults for the rest" is fully specified (Q2/Q3 default with a report caveat).

4. Provenance via source field on constraints

• Every constraint with chosen_by: "extracted" carries a source field with the raw provenance signal (e.g. "terraform:availability_type=ZONAL", "ai-profile:integration.pattern=direct_sdk").
• Every constraint with chosen_by: "default" carries source: "default:<Qid>" so report generation can flag unverified assumptions.
• Omit source for "user" and "derived" constraints.
• New clarify_mode: "wizard" (enum now wizard | full | fast_path | simple_hybrid); wizard is the default full flow.
• New wizard_stage draft field for resume (sheet_pending / essentials_pending); legacy batches_completed drafts detected and handled.
• Q9 WebSocket honesty: with no code scan, the sheet row is explicitly marked "unverified — no code scan" rather than presented as detected.
• Generate phase Appendix F renders Source and Source signal columns, flagging default:-prefixed rows as assumptions.

5. Agent-compliance hardening (two-gate flow)

The wizard depends on the agent presenting the sheet, waiting, then asking essentials — never mixing them. Three layers enforce this:

• Step 4 opens with a COMPLIANCE SELF-CHECK: the sheet must have been presented in a previous turn and answered before any question is emitted; sheet and questions must never share a message.
• Handoff gate check 5: questions_asked may not overlap questions_skipped_extracted or questions_defaulted (the "ask me about X" conversion path moves the ID to questions_asked first, so legitimate conversions pass).
• A dedicated test-plan case + proposed eval invariant mirror the gate check.

6. What is intentionally unchanged

• Fast-path (3 questions) and simple hybrid (~6) offers — the wizard slots in as the default flow behind them; agentic hard-block preserved.
• BigQuery specialist advisory, handoff gates (GATE_FAIL/HANDOFF_OK), phase-status protocol, Category E opt-in, answer-combination triggers, early-exit rules, preferences schema shape (value + chosen_by).
• The full question-by-question flow — retained verbatim as the "ask me everything" variant with the same 3-batch structure and draft checkpoints.
• Q23 remains essential except when the existing clarify-ai.md auto-skip rule fires (gateway/LangGraph/CrewAI users).
• The multi-workload confirmation table stays in Step 4 (post-sheet); folding high-confidence workload rows into the sheet itself is a natural follow-up PR.

Question-count impact (replay of the real run above)

Flow	Questions asked	User turns
Current full flow	12 asked across 3 batches (9 more silently defaulted)	4–5
Wizard (this PR)	Sheet + 3 essential (Q2, Q7, Q15)	2
Wizard, user corrects 2 rows	Sheet + corrections + 3 essential	3

Files changed

File	Change
skills/gcp-to-aws/references/phases/clarify/clarify.md	Rewrite: Step 2.5 assumption sheet; Step 3 disposition catalog; Step 4 essentials + full-flow variant; completed Defaults Table; handoff gate checks 4–5; source field on constraints replacing detected_settings array
skills/gcp-to-aws/references/phases/generate/generate-artifacts-report.md	Appendix F renders Source + Source signal columns from constraint source field
skills/gcp-to-aws/SKILL.md	2 copy hunks (error-handling "use defaults" row; scope-notes clarification bullet) + directory-tree comment for clarify-ai.md

Category files, fast-path preview fields, and all other phases: untouched. Downstream phases need no changes — the preferences.json shape is unchanged (source is additive).

Test plan

Draft PR — validation runs pending:

• mise run eval:check — structural directives (FORBIDDEN blocks, BigQuery gate) still present in rewritten clarify.md
• Fixture run: user-preferences — sheet shown before any question; preferences.json schema valid; extracted constraints have source field; clarify_mode: "wizard"
• Fixture run: minimal-cloud-run-sql — end-to-end phases pass with wizard default
• Fixture run: ai-workload-openai — Q15 asked; Q16–Q22 appear as sheet rows; agentic profile forces Q23–Q25 as essentials
• Manual: "ask me everything" reproduces the legacy 3-batch flow with clarify_mode: "full"
• Manual: "use defaults for the rest" completes with Q2/Q3 caveats recorded
• Manual: resume from wizard_stage: "essentials_pending" draft; legacy batches_completed draft triggers the migration prompt
• Two-gate compliance: transcript review across all three fixture runs — sheet is its own turn; no sheet-row question asked unless converted

Proposed new eval invariants (for the user-preferences fixture):

1. metadata.clarify_mode ∈ {wizard, full, fast_path, simple_hybrid}
2. If clarify_mode == "wizard": at least one constraint has a source field prefixed default:
3. Every constraint with chosen_by: "extracted" or chosen_by: "default" has a source field
4. questions_asked ∩ questions_defaulted = ∅ and ∩ questions_skipped_extracted = ∅
5. If clarify_mode == "wizard" and Cloud SQL in inventory: availability.chosen_by ∈ {user, extracted, default} (never absent)
6. questions_asked ∩ (questions_skipped_extracted ∪ questions_defaulted) = ∅ — artifact-level proxy for "sheet and questions were never mixed" (mirrors handoff gate check 5)