metrics: adopt METRICS_JSON HTML comment as primary format

Plan, document, and finalize prompts now emit a single
<!-- METRICS_JSON {...} --> block with all structured fields. Collector
parses these directly and keeps the old prose/table parsing as fallback.

Also adds a per-task complexity check to the document prompt:
split tasks with 3+ complexity signals (5+ logic branches, 2+
integration points, shared interface mutation, etc.), combine
adjacent trivial tasks.

src/plan2code-1--plan.md

@@ -221,7 +221,14 @@ State assessment and ask user to confirm.
 1. Save PLAN-CONVERSATION (see template below) — transcript + decision summary tables
 2. Create PLAN-DRAFT (see template below) using same date
 3. Verify: re-read conversation as source of truth, cross-reference against PLAN-DRAFT sections (Reqs→2.1/2.2, Tech→3, Architecture→4, Risks→6, Assumptions→9, Criteria→7). Add gaps with `<!-- VERIFICATION -->` comments. Output verification summary table.
-4. Append `## Planning Metrics` to PLAN-DRAFT with these exact fields: `confidence: [0-100]`, `clarification_rounds: [N]`, `functional_requirements_count: [N]`, `non_functional_requirements_count: [N]`, `risk_count: [N]`, `phase_count: [N]`, `verification_gaps_found: [N]`. Use exact field names — the metrics pipeline parses this section.
+4. Append `## Planning Metrics` to PLAN-DRAFT with a `<!-- METRICS_JSON {...} -->` HTML comment. The metrics pipeline parses this — use exact format:
+
+```
+## Planning Metrics
+<!-- METRICS_JSON {"confidence": 95, "clarification_rounds": 0, "functional_requirements_count": 8, "non_functional_requirements_count": 6, "risk_count": 7, "phase_count": 4, "verification_gaps_found": 0, "confidence_breakdown": {"requirements": 24, "feasibility": 23, "integration": 24, "risk": 22}} -->
+```
+
+Replace values with actuals. Optionally add plain `key: value` lines below for readability (no bold/markdown).
 
 ## Templates
 
@@ -275,20 +282,11 @@ When complete (PLAN-DRAFT created), tell user:
 > `/plan2code-2--document`
 > ```"
 
-## Abort Handling
+## Abort / Recovery
 
-If user says "abort", "cancel", "start over":
-1. Confirm: "Abort planning? Progress will not be saved."
-2. If confirmed, state files created that may need cleanup
-3. Stop workflow
-
-## Recovery
-
-| Issue | Solution |
-|-------|----------|
-| Lost context | Attach PLAN-DRAFT, state phase |
-| Unclear answers | One follow-up, max 3 rounds |
-| Confidence stuck <90% | List blockers, ask targeted questions |
+- **Abort:** Confirm with user, list files needing cleanup, stop workflow
+- **Lost context:** Attach PLAN-DRAFT, state phase
+- **Confidence stuck <90%:** List blockers, ask targeted questions
 
 ## Reminders
 
@@ -296,5 +294,5 @@ If user says "abort", "cancel", "start over":
 - Do NOT implement - design and present plan only
 - Responses start with: `🤔 [PLANNING PHASE X: Name]`
 - **Workflow:** Plan -> Document -> Implement -> Finalize. After planning: `/plan2code-2--document`
-- Save conversation log (7A) before PLAN-DRAFT (7B)
+- Save conversation log (7A) before PLAN-DRAFT (7B), run verification (7C) after
 - Run verification (7C) after PLAN-DRAFT - conversation log is source of truth

src/plan2code-2--document.md

@@ -54,12 +54,14 @@ If no plan exists and user wants to skip:
 
 | Criterion | Description |
 |-----------|-------------|
-| Time-boxed | 15-60 minutes |
+| Time-boxed | 15-60 min. Split if 5+ logic branches, 2+ integration points, or shared interface mutation. Combine adjacent trivial tasks that form a cohesive unit. |
 | Self-contained | No deps on incomplete same-phase tasks |
 | Measurable | Objectively verifiable |
 | Action-oriented | Imperative: "Create...", "Implement..." |
 | Specific | File paths, function names, exact requirements |
 
+**Complexity check** — before finalizing each task, consider: logic branches, distinct behaviors, integration points, shared interface impact, and error/edge cases. Tasks that are complex on 3+ of these signals should be split.
+
 **Examples:**
 
 | Bad | Good |
@@ -83,7 +85,7 @@ If no plan exists and user wants to skip:
    - Success Criteria (plain bullet list, no checkboxes) (section 7)
    - Phase Checklist (Implementation Phases)
    - Quick Reference (Key Files, Environment Variables, External Dependencies)
-7. **Write** each `phase-X.md` with detailed tasks
+7. **Write** each `phase-X.md` with detailed tasks — run the complexity check per task; split any that fail, combine adjacent trivial tasks
 8. **Analyze** parallel execution eligibility
 9. **Verify** all PLAN-DRAFT requirements covered:
    - 9A: Re-read PLAN-DRAFT as source of truth
@@ -193,6 +195,14 @@ Total tasks: Y
 Parallel Execution: [Groups or "None - sequential only"]
 ```
 
+Also append a machine-parseable metrics comment to the END of `overview.md` for the metrics pipeline:
+
+```
+<!-- METRICS_JSON {"step": "document", "total_tasks": 28, "tasks_per_phase": [7, 7, 7, 7], "phase_count": 4, "parallel_groups_identified": 2, "verification_items_added": 3} -->
+```
+
+Replace values with actuals. `verification_items_added` = total Added column from the Verification Summary table.
+
 **Tell user:**
 1. What was created (spec files list)
 2. Path for next session: `specs/<feature-name>/overview.md`

src/plan2code-4--finalize.md

@@ -268,6 +268,10 @@ specs--completed/
 - **Completion Rate:** [X]% ([Y]/[Z] tasks)
 - **Archived To:** `specs--completed/<feature-name>/`
 
+<!-- METRICS_JSON {"step": "finalize", "completion_rate_at_audit": 0.95, "tasks_completed": 19, "tasks_total": 20, "verification_failures_found": 1, "documentation_updates_needed": 2} -->
+
+Replace METRICS_JSON values with actuals. `completion_rate_at_audit` = Y/Z as decimal (e.g., 19/20 = 0.95).
+
 ### Finalization Steps Completed
 - [x] Step 1: Task Completion Audit
 - [x] Step 2: Implementation Verification