fix(methodology): close all 5 subissues of tracker #225 (post-#218 follow-up)

Lands v1 scope of every methodology subissue revealed by the post-#218
paper-burst rerun (2026-05-27). Each subissue has a concrete fix that
materially improves the rehearsal/real iteration loop and prepares the
codebase for cross-run knowledge propagation.

Closes #221 — Render iteration_mode + execute_mode_guidance in
  EXECUTE_ANALYZE prompt context. The DESIGN-phase agent (post-#212)
  honors rehearsal scope-shrink for probes, but the bundle it authors
  declares the full experimental design, and the EXECUTE_ANALYZE-phase
  agent (which had no mode signal) dutifully fanned out the full
  bundle anyway. New ``execute_mode_guidance_for(mode)`` returns
  rehearsal/real text distinct from the design-phase helper. Plumbed
  through ``_build_context`` for ``phase == "execute-analyze"``;
  rendered into ``execute_analyze.md`` + ``execute_analyze_thin.md``
  with ``{{iteration_mode}}`` + ``{{mode_guidance}}`` placeholders.
  Test parametrized over ``with_claude_md`` (production thin path).

Closes #222 — bundle.experiment_spec gains a structured
  ``rehearsal_subset`` field (seeds, arms, extra_validation_only).
  Schema-locked enum so a typo'd field name fails validation. The
  DESIGN methodology instructs agents to populate it when iter is
  rehearsal; EXECUTE_ANALYZE honors it (per #221's mode_guidance).
  Composes with #221: prose-only scope-shrink was unreliable; a
  structured field is enforceable.

Closes #223 v1 — structured ``brief_amendments.jsonl`` schema +
  REPORT-context renderer. New ``brief_amendments.schema.json`` with
  required fields (``id, brief_section, problem, fix, priority``)
  and an enumerated priority. New
  ``_format_brief_amendments_summary(work_dir)`` helper renders
  amendments grouped by priority into the REPORT prompt. CLI
  ``nous brief apply-amendments`` deferred to v2.

Closes #224 v1 — deterministic
  ``promote_gate.evaluate_promote_gate(work_dir, iteration) -> dict``
  function. Pure Python; reads findings.json, brief_amendments.jsonl,
  applied_amendments.jsonl. Decision rule: missing/invalid findings →
  ``abort``; unapplied BLOCKING amendment → ``revise``; else →
  ``promote``. Engine state-machine integration (the actual halting
  behavior at iter boundaries) deferred to v2 — this PR lands the
  decision logic so it's testable in isolation before any engine
  state changes.

Closes #226 — bundle.experiment_spec gains a structured
  ``timing_observations`` block (per-policy expected wall-time +
  recommended_turn_silence_threshold_seconds). ``SDKDispatcher.dispatch``
  reads the prior iter's bundle for the recommended threshold and
  applies it as a per-call override; restores the campaign default
  after. Resolution chain: bundle override > campaign default >
  factory default (600s). Methodology prescribes that rehearsal-mode
  agents record per-policy timing observations during feasibility
  probes — the recurring ``externality-credit`` slowness across
  three reruns becomes structural data instead of folklore.

Refs #225 (tracker — five children covered).

Tests: +44 new (1133 passed, 1 skipped, 0 regressions). Behavioral
throughout: assertions on resolved ctx values, on-disk artifacts,
schema validation. Per CLAUDE.md "no live LLM calls" — all tests
use existing seam-injected fakes.

Compaction-safe plan at ``docs/plans/methodology-improvements-pr.md``
captures the full implementation map; memory entries at
``project_methodology_pr_in_flight.md`` and
``project_paper_burst_workload_divergence.md`` carry session
context across compactions.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: sriumcp

orchestrator/iteration_mode.py

@@ -105,7 +105,7 @@ def iteration_mode_for(campaign: dict, iteration: int) -> Mode:
 
 
 def mode_guidance_for(mode: Mode) -> str:
-    """Return the prompt block that guides the agent for ``mode``.
+    """Return the DESIGN-phase prompt block that guides the agent for ``mode``.
 
     Raises ``ValueError`` on an unknown mode value. Silently defaulting
     to REAL_GUIDANCE was the prior behavior; that's the more dangerous
@@ -119,3 +119,89 @@ def mode_guidance_for(mode: Mode) -> str:
     raise ValueError(
         f"unknown iteration mode {mode!r}; expected one of {VALID_MODES}"
     )
+
+
+# ─── Execute-phase mode guidance (#221) ──────────────────────────────────
+#
+# The DESIGN agent's mode_guidance shaped how it scope-shrunk probes /
+# bundle authoring. EXECUTE_ANALYZE needs its OWN mode-aware guidance
+# so it doesn't fan out the bundle at full scope when iter is rehearsal.
+# Without this, post-#212 paper-burst reruns observed the DESIGN agent
+# honoring rehearsal scope while EXECUTE_ANALYZE dutifully ran the full
+# 50-arm experiment anyway — defeating the cost asymmetry that was the
+# entire economic argument for #212.
+
+EXECUTE_REHEARSAL_GUIDANCE = """\
+This iteration is in **REHEARSAL** mode (#212). The DESIGN agent's
+bundle declares the full experimental design (so iter-2 / future runs
+can run it untouched). YOUR JOB this iter:
+
+1. **Honor the rehearsal scope.** If the bundle's
+   ``experiment_spec.rehearsal_subset`` is populated (#222), execute
+   ONLY that subset (typically: 1 seed × the contrast-pair arms).
+   Do NOT fan out the full ``experiment_spec`` — that's iter-2's job.
+   If ``rehearsal_subset`` is missing, default to: first canonical
+   seed + ``h-main`` and ``h-control-negative`` arms only.
+
+2. **Validate the analysis pipeline.** Schema-pass at least one
+   result through the analysis_summary.json computation. If the
+   analysis script fails or returns null where data is present,
+   fix the script (or surface the issue) before iter-2 runs.
+
+3. **Append per-policy timing observations** (#226). During the
+   feasibility / contrast-pair runs, measure wall-clock per policy.
+   Record into ``experiment_spec.timing_observations``:
+   ``expected_wall_time_seconds_per_policy: { ea-wfq: 25, wfq: 23, ... }``
+   and a derived ``recommended_turn_silence_threshold_seconds``
+   (~3× the slowest observed policy + buffer). iter-2's watchdog
+   reads these to calibrate.
+
+4. **Emit ``brief_amendments.jsonl``** (post-#223 structured form) at
+   ``runs/iter-N/inputs/brief_amendments.jsonl`` if you find any
+   campaign-spec friction (workload params, timing claims, missing
+   flags, etc.). One JSON object per line; required fields: ``id``
+   (pattern ``BA-N``), ``brief_section``, ``problem``, ``fix``,
+   ``priority`` (BLOCKING / HIGH / MEDIUM / LOW / INFO). Optional
+   ``evidence``, ``impact``.
+
+5. **Append to ``bundle_amendments.jsonl``** (#211) when you override
+   any parameter from ``experiment_spec.verified_parameters``.
+
+6. **Write findings.json with ``mode: rehearsal``** in the outcome,
+   noting that scientific claims are deferred to iter-2. The
+   ``experiment_valid: true`` flag means "the apparatus works" —
+   not "the hypothesis is confirmed/refuted."
+
+**Do NOT:**
+- Fan out the full bundle's seeds × policies grid.
+- Mark h-main as CONFIRMED / REFUTED based on rehearsal data.
+- Skip writing ``brief_amendments.jsonl`` if you discovered
+  campaign-spec friction.
+"""
+
+EXECUTE_REAL_GUIDANCE = """\
+This iteration is in **REAL** mode (#212). Run the full experiment_spec
+at the bundle's prescribed scope: all arms, full seed list. If a prior
+``rehearsal`` iter emitted ``brief_amendments.jsonl``, read it before
+launching the experiment — if any ``priority: BLOCKING`` amendments
+exist that haven't been applied to the brief, halt with a
+``failure_note.md`` (promotion-gate logic, #224). Otherwise run the
+full bundle, write ``findings.json`` with ``mode: real`` and a CONFIRMED /
+REFUTED / NULL status per arm, and append ``bundle_amendments.jsonl``
+(#211) for any parameter overrides observed during execution.
+"""
+
+
+def execute_mode_guidance_for(mode: Mode) -> str:
+    """Return the EXECUTE_ANALYZE-phase prompt block for ``mode`` (#221).
+
+    Distinct from ``mode_guidance_for`` (which targets the DESIGN agent).
+    Raises ``ValueError`` on unknown modes for the same fail-loud reason.
+    """
+    if mode == "rehearsal":
+        return EXECUTE_REHEARSAL_GUIDANCE
+    if mode == "real":
+        return EXECUTE_REAL_GUIDANCE
+    raise ValueError(
+        f"unknown iteration mode {mode!r}; expected one of {VALID_MODES}"
+    )

orchestrator/llm_dispatch.py

@@ -133,6 +133,91 @@ def _format_results_summary(work_dir: Path) -> str:
     return "\n".join(lines)
 
 
+def _format_brief_amendments_summary(work_dir: Path) -> str:
+    """#223: surface structured ``brief_amendments.jsonl`` entries to
+    the REPORT extractor.
+
+    Each amendment is a JSON object with required fields
+    ``id, brief_section, problem, fix, priority``. Optional
+    ``evidence``, ``impact``. The schema lives at
+    ``orchestrator/schemas/brief_amendments.schema.json``.
+
+    Walks ``runs/iter-*/inputs/brief_amendments.jsonl``, schema-validates
+    rows individually (skipping malformed with a visible warning), and
+    renders a per-iter listing grouped by priority. The REPORT extractor
+    can use this to: (a) cite which amendments shaped the iteration's
+    findings, (b) flag which BLOCKING amendments still need applying
+    to the upstream brief (the cross-run learning loop).
+    """
+    runs_dir = work_dir / "runs"
+    if not runs_dir.is_dir():
+        return "(no iteration directories — no brief amendments to report.)"
+    iter_dirs = sorted(
+        (d for d in runs_dir.iterdir()
+         if d.is_dir() and d.name.startswith("iter-")),
+        key=lambda d: d.name,
+    )
+    sections: list[str] = []
+    total = 0
+    for iter_dir in iter_dirs:
+        log = iter_dir / "inputs" / "brief_amendments.jsonl"
+        if not log.exists():
+            continue
+        try:
+            text = log.read_text()
+        except OSError as exc:
+            sections.append(
+                f"- {iter_dir.name}: brief_amendments.jsonl unreadable "
+                f"({type(exc).__name__})"
+            )
+            continue
+        rows: list[dict] = []
+        skipped_malformed = 0
+        for line in text.splitlines():
+            if not line.strip():
+                continue
+            try:
+                rows.append(json.loads(line))
+            except json.JSONDecodeError:
+                skipped_malformed += 1
+        if not rows and skipped_malformed == 0:
+            continue
+        # Group by priority for at-a-glance triage. BLOCKING first, then
+        # HIGH / MEDIUM / LOW / INFO. Unknown priorities sort last.
+        priority_order = {
+            "BLOCKING": 0, "HIGH": 1, "MEDIUM": 2, "LOW": 3, "INFO": 4,
+        }
+        rows_sorted = sorted(
+            rows,
+            key=lambda r: priority_order.get(
+                str(r.get("priority", "")).upper(), 99
+            ),
+        )
+        header = f"- {iter_dir.name}: {len(rows)} amendment(s)"
+        if skipped_malformed:
+            header += f" + {skipped_malformed} malformed line(s) skipped"
+        sections.append(header)
+        total += len(rows)
+        cap = 20
+        for r in rows_sorted[:cap]:
+            aid = r.get("id", "?")
+            prio = r.get("priority", "?")
+            section = r.get("brief_section", "?")
+            problem = r.get("problem", "")
+            sections.append(
+                f"  - [{prio}] {aid} (target: {section}) — "
+                + (problem[:160] + "..." if len(problem) > 160 else problem)
+            )
+        if len(rows_sorted) > cap:
+            sections.append(f"  - ... and {len(rows_sorted) - cap} more")
+    if not sections:
+        return (
+            "(no brief_amendments.jsonl entries — the campaign brief was "
+            "consistent with the agent's runs; no amendments queued.)"
+        )
+    return "\n".join(sections)
+
+
 def _format_bundle_amendments_summary(work_dir: Path) -> str:
     """#211: surface bundle_amendments.jsonl entries to the REPORT extractor.
 
@@ -594,6 +679,19 @@ def _build_context(
                     "No design handoff available — explore the system directly."
                 )
 
+            # #221: per-iteration mode signal in EXECUTE_ANALYZE too. The
+            # post-#212 paper-burst rerun observed the DESIGN agent
+            # honoring rehearsal scope-shrink while EXECUTE_ANALYZE
+            # dutifully fanned out the full bundle anyway — because the
+            # mode signal only flowed to DESIGN. Rendering it in execute
+            # too closes that gap.
+            from orchestrator.iteration_mode import (
+                iteration_mode_for, execute_mode_guidance_for,
+            )
+            mode = iteration_mode_for(self.campaign, iteration)
+            ctx["iteration_mode"] = mode
+            ctx["mode_guidance"] = execute_mode_guidance_for(mode)
+
         if perspective is not None:
             ctx["perspective_name"] = perspective
 
@@ -656,6 +754,14 @@ def _build_context(
             ctx["bundle_amendments_summary"] = (
                 _format_bundle_amendments_summary(self.work_dir)
             )
+            # #223: structured brief_amendments — propagate to REPORT
+            # so the extractor can cite which amendments shaped the
+            # iteration's findings AND surface BLOCKING amendments
+            # that haven't been applied to the upstream brief yet
+            # (cross-run learning loop).
+            ctx["brief_amendments_summary"] = (
+                _format_brief_amendments_summary(self.work_dir)
+            )
 
         return ctx