init-plan scaffolds fewer fields than the guide's required plan contract; no plan lint before approve

[johnjosephhorton]

Summary

Two related gaps in twin-experiment plan authoring UX:

1. twin-experiment init-plan scaffolds far fewer fields than zwill guide says a plan must specify.
2. There is no way to lint/validate a hand-edited plan before approve/export-plan, so mistakes surface as tracebacks at export time.

Detail

(1) Scaffold vs. documented plan contract

zwill guide (agent-workflow, stage 8) says a twin-experiment plan must specify:

held-out targets, all eligible questions considered, excluded questions and reasons, respondent sample, construction approaches, context fields, leakage exclusions, models/parameters, seed, complete-case or stratification policy, prediction count, cost/time risk, outputs, and decision criteria.

init-plan writes only ~8 keys: plan_id, survey, heldout_questions, primary_metric, defaults (sample/seed/complete_cases/context_question_count/model), arms, approval, prediction_count_estimate. None of the governance/rationale fields (excluded questions + reasons, leakage exclusions, decision criteria, cost/time risk, outputs) are scaffolded. Extra fields added by hand are passed through but not acted upon (e.g. model_params — see the Gemini cap issue).

So the operator must hand-author exactly the fields that most need a template, with no schema to tell them what's read vs. decorative.

(2) No plan validation before approve

zwill twin-experiment plan-status --path plan.json
# error: the following arguments are required: --survey, --plan-id

plan-status only finds records after export. There is no --path dry-check. Combined with the context_questions-as-list crash (separate issue), a malformed plan is only discovered as an AttributeError at export-plan time.

Suggested fixes

• Have init-plan scaffold the full documented contract (with commented/empty placeholders for the rationale fields), or add an init-plan --full variant.
• Add twin-experiment validate --path plan.json that checks the schema, flags unknown/ignored keys, resolves question names against the survey, and reports the exported prediction count — runnable before approve.