fix(stop+validator): phase-aware stop docs + required_iter_root v2 (#198 + #199)

[sriumcp]

Summary

Closes #198
Closes #199

Two related but independently-scoped fixes that close the post-#189 paper-burst friction tracker (#203) for the stop and validator surfaces.

Discovery context

While auditing #198 / #199 status I found that the behavioral halves of both were already shipped in earlier PRs — but neither issue had been closed because the closing PRs used Closes: **#N** (colon + bold) which doesn't match GitHub's auto-close regex. This PR delivers the remaining lagging deltas plus the explicit stretch-goal scope from #199's body, then closes both with proper auto-close keywords.

#198 — phase-aware nous stop documentation

The engine-side fix is in place: orchestrator/iteration.py:_enter_phase honours the STOP sentinel before every phase transition (DESIGN / HUMAN_DESIGN_GATE / EXECUTE_ANALYZE / HUMAN_FINDINGS_GATE), with comprehensive test coverage in TestEnterPhaseHonorsSentinel and TestRunIterationHaltsAtPhaseBoundary.

What lagged: two user-facing strings still said "iteration boundary":

• orchestrator/cli.py:416 — schema-doc render's See-also section.
• orchestrator/cli.py:879 — argparse help= for nous stop.

This PR updates both, adds an argparse description= so nous stop --help shows the full phase-aware explanation, and pins both against the legacy phrasing in TestStopDocumentationReflectsPhaseAwareness.

#199 v2 — required_iter_root

The v1 (iter_root_extensions) was already shipped — campaigns can declare additional iter-root files that don't trigger "unexpected file" rejection. This PR adds the explicit stretch goal from the issue body: campaigns can also declare files that MUST exist at iter root after EXECUTE_ANALYZE, with structured required iter-root file missing: X errors when they're absent.

# campaign.yaml
validation:
  required_iter_root:
    - "probe_report.md"
    - "manifest.json"
  iter_root_extensions:
    - "analysis_summary.json"

Semantics:

• Required ⊆ allowed. A file in required_iter_root is also implicitly allowed at iter-root — no need to list it in both blocks.
• validate_execution enforces presence. Sister to Better diagnostic when DESIGN exits without bundle.yaml/problem.md/handoff_snapshot.md #187's DesignIncompleteError and ExecuteAnalyzeIncompleteError analog of #187 for the EXECUTE phase #200's ExecuteAnalyzeIncompleteError: turn silent omissions into structured failures the operator can act on.
• validate_design does NOT enforce presence. Required artifacts are typically EXECUTE-phase outputs (e.g. probe_report.md); checking at design time would surface false negatives. Design does merge required into the allowed-set so a campaign that writes the file during DESIGN doesn't get rejected by the unexpected-file check.
• Backward compatible. Campaigns without a required_iter_root block behave exactly as before.

Files

• orchestrator/cli.py — phase-boundary wording + new argparse description= for nous stop.
• orchestrator/schemas/campaign.schema.yaml — new validation.required_iter_root field.
• orchestrator/validate.py — _campaign_required_iter_root helper, _check_required_iter_root, integration into validate_design (allowed-merge only) and validate_execution (allowed-merge + enforce-presence).
• tests/test_nous_stop.py — TestStopDocumentationReflectsPhaseAwareness (2 tests).
• tests/test_validate.py — TestRequiredIterRoot (7 tests).

Test plan

• TDD red-green cycle verified for both fixes. 8 of 9 new tests fail before implementation; all 9 pass after.
• nous stop should honor phase boundaries, not just iteration boundaries #198 polish: argparse nous stop --help and schema-doc render both contain "phase boundary" and don't contain "iteration boundary".
• Validator's iter-root whitelist needs a per-campaign extension mechanism #199 v2: missing required → fail; present required → pass; required implicitly allowed at iter root; required-listed-alongside-other-errors; required+extensions combined; backward-compat with no required_iter_root block; jsonschema accepts the new field.
• No live LLM calls. All tests use tmp_path fixtures and the existing block_live_llm_calls autouse fixture in conftest.py.
• Full suite green. uv run pytest -q → 1245 passed, 1 skipped (+9 vs upstream/reflective baseline of 1236), 0 failures.

🤖 Generated with Claude Code