Clarify Assemble

Step 4: Assemble and Write preferences.json

Assemble all interpreted answers into the final $MIGRATION_DIR/preferences.json from the current session’s answers. Set metadata.timestamp to the current time.

Write $MIGRATION_DIR/preferences.json:

Do not write a workshop object from Clarify. The what-if workshop (references/phases/workshop/) creates/patches preferences.workshop later (cpu_architecture, active, active_scenario_id, last_sheet_at). See references/shared/schema-workshop-scenarios.md.

Schema Rules

1. The sources object records how each question was answered: "user" (explicitly answered, or corrected on the Assumption Sheet), "extracted" (resolved from the inventory — Detected sheet row), "default" (system default applied, including skipped questions, sheet-confirmed defaults, and “use defaults for the rest”).
2. defaults_applied is the array of question IDs that received default values.
3. metadata.questions_skipped_not_applicable records questions skipped because their triggering condition was not met (e.g., Q6 skipped because no Postgres). metadata.questions_skipped_extracted records questions resolved from the inventory (interview Step 2.5 Extraction Rules); the raw signal goes in metadata.inventory_clarifications (e.g. {"database_ha": "plan:premium-0"}).
4. Only write keys with non-null values. Omit sections/keys that are entirely null.
5. global.fir_intent is null when no Fir apps detected (Q11 not fired).
6. network.existing_vpc_id and network.subnet_ids are null/empty when no Private Space peering exists.
7. data.database_ha, data.redis_ha, data.kafka_retention_days are omitted entirely when those services are not present in the inventory.
8. design_constraints.compute_target uses the structured Q12c shape (default, overrides, chosen_by, recommendation). Existing reused preferences with legacy compute_target.value may be read by Design for backward compatibility, but newly assembled preferences MUST write the structured shape.
9. design_constraints.eb_deploy_method is required when the resolved compute plan includes at least one Elastic Beanstalk formation; omit it for all-Fargate or all-EKS targets.
10. Omit workshop on Clarify assemble — workshop mode owns that object.

Validation Checklist

Before handing off to Design:

• Not done: preferences.json written to $MIGRATION_DIR/
• Not done: global.target_region is populated with a valid AWS region code
• Not done: global.availability is populated
• Not done: If Postgres in inventory → data.database_ha is populated
• Not done: If Postgres in inventory → global.migration_approach is populated
• Not done: If Postgres in inventory → data.migration_method is populated
• Not done: If migration_approach is interim_cutover_data_first → global.target_exit_date is a valid future ISO date
• Not done: If migration_approach is interim_cutover_data_first → global.interim_cutover is true
• Not done: If Private Space peering detected → network.subnet_ids contains 1–6 valid IDs
• Not done: If peering detected and VPC ID needed → network.existing_vpc_id is populated
• Not done: If Fir apps detected → global.fir_intent is populated (not null)
• Not done: operational.containerization_status is populated
• Not done: design_constraints.compute_target.default is one of: "elastic_beanstalk", "ecs-fargate", "eks-managed", "eks-or-ecs"
• Not done: design_constraints.compute_target.chosen_by is one of: "user", "system_recommended", "default"
• Not done: design_constraints.compute_target.overrides[] entries, when present, have formation, value, reason, and chosen_by
• Not done: design_constraints.compute_target.overrides[].value is one of: "elastic_beanstalk", "ecs-fargate"
• Not done: design_constraints.compute_target.overrides[].chosen_by is one of: "user", "system_forced"
• Not done: design_constraints.compute_target.recommendation.value is one of: "elastic_beanstalk", "ecs-fargate", "eks-managed", "eks-or-ecs", "mixed"
• Not done: design_constraints.compute_target.recommendation.confidence is one of: "high", "medium", "low"
• Not done: design_constraints.compute_target.recommendation.reasons is a non-empty array
• Not done: If the resolved compute plan includes Elastic Beanstalk → design_constraints.eb_deploy_method.value is one of: "github_actions", "codepipeline", "manual"
• Not done: If design_constraints.eb_deploy_method is present → design_constraints.eb_deploy_method.chosen_by is "user" or "default"
• Not done: All entries in sources have a value of "user" or "default"
• Not done: metadata.clarify_mode is set to "fast_path" or "full"
• Not done: Only keys with non-null values are present
• Not done: Output is valid JSON

Completion Handoff Gate (Fail Closed)

The completion checks are declared in this phase’s _postconditions frontmatter and enforced per INTERPRETER.md § Gate protocol: re-read preferences.json from disk, run the mechanical checks (_check_file_exists / _validate_json) and the _assert judgment checks (all Validation Checklist items; the Postgres/interim-cutover/Fir/ private-space conditionals), then emit GATE_FAIL (STOP; do not patch artifacts) or HANDOFF_OK | phase=clarify | artifacts=preferences.json and advance.

Step 5: Update Phase Status and Hand Off

Only after HANDOFF_OK, apply the phase-status update protocol (INTERPRETER.md § The interpreter loop) — mark phases.clarify completed and advance per _advances_to — in the same turn as the output message below.

Output to user: “Phase 2 of 6 complete (Clarify). Remaining: Design → Estimate → Generate (+ optional Feedback). Next artifact: aws-design.json. Proceeding to Phase 3: Design AWS Architecture.”

Emit this breadcrumb only after HANDOFF_OK — never on a failed gate.