buildanything 1.8.0 → 2.0.0

package/protocols/metric-loop.md

@@ -19,6 +19,8 @@ Metric: [what you're measuring, in one sentence]
 How to measure: [what the measurement agent should do — run tests, audit code, check criteria, etc.]
 Target: [score 0-100 at which you stop]
 Max iterations: [hard cap, default 5]
+Scoring Criteria Checklist: [extracted in Step 0.5 — see .build-state.json]
+Extraction method: [mechanical | one-shot-dispatch | mixed]
 ```
 
 Then create a score log table:
@@ -36,11 +38,53 @@ Sub-step: [5.1 Implement | 5.1b Cleanup | 5.2 Metric Loop | 5.3 Loop Exit | 5.4
 ```
 This tells the orchestrator exactly where to resume after context compaction.
 
+## Step 0.5: Extract Scoring Criteria
+
+Before the first measurement, extract a **Scoring Criteria Checklist** from the stable reference docs. This checklist is the critic's scoring input for every iteration — it replaces raw doc injection.
+
+### Why
+
+Reference docs (DNA cards, design specs, architecture docs, acceptance criteria) do not change during the loop. Pre-injecting them into every critic prompt wastes ~20-30K tokens per iteration. The checklist extracts the exact scoring values once and passes ~1-2K tokens instead.
+
+### Extraction mechanism (per doc type)
+
+Use the cheapest mechanism that preserves fidelity:
+
+| Source doc type | Structure | Extraction mechanism | Cost |
+|-----------------|-----------|---------------------|------|
+| Structured (named fields with explicit values) — e.g., `visual-dna.md` DNA card, `sprint-tasks.md` Behavioral Test field, `ios-design-board.md` named sections | YAML/markdown with named axes, fields, or sections | **Mechanical** — orchestrator parses and copies the values directly. No LLM reasoning. | ~0 tokens |
+| Semi-structured (values spread across prose sections) — e.g., `visual-design-spec.md`, Phase 5 audit findings | Long-form with explicit values in multiple sections | **One-shot extractor dispatch** — single agent call reads the full doc once and outputs the structured checklist. | ~20-25K one-time |
+| Unstructured (visual references, screenshots, mood boards) — e.g., `design-references.md` | Screenshot URLs, visual comps | **Not extracted.** Referenced by path in the checklist. Iteration 1 MAY read on-demand; iteration 2+ MUST NOT unless diagnosis explicitly flags a visual-reference gap. | 0 tokens |
+
+**Rule: if the source doc has named fields with explicit values, extraction is mechanical (no dispatch). If values are spread across prose sections, use a one-shot extractor dispatch. Never use orchestrator LLM reasoning for extraction — it burns the tokens you're trying to save.**
+
+### Persist the checklist
+
+Write the checklist to `.build-state.json` under `active_metric_loop.scoring_criteria_checklist`. Record the extraction method in `active_metric_loop.extraction_method` (one of: `mechanical`, `one-shot-dispatch`, `mixed`). The rendered `.build-state.md` view reflects it automatically.
+
+### Checklist format
+
+```
+Scoring Criteria Checklist
+Source docs: [list of source doc paths]
+Extracted at: [timestamp]
+Extraction method: [mechanical | one-shot-dispatch | mixed]
+
+[Structured criteria with exact values, organized by scoring dimension]
+
+Reference Anchors:
+- [path] (iteration 1 MAY read; iteration 2+ MUST NOT unless diagnosis flags gap)
+```
+
+The format is flexible — adapt it to the phase and artifact. The protocol gives a template, not a rigid schema. What matters: exact values, not summaries; organized by scoring dimension; reference anchors for unstructured docs.
+
 ## Step 1: MEASURE
 
 Call the Agent tool — description: "Measure [metric]" — prompt:
 
-"[How to measure, from your metric definition]. Score the current state 0-100. Return your response with a clear SCORE: [number] line, a list of FINDINGS, and the single TOP ISSUE most likely to improve the score if fixed."
+"SCORING CRITERIA CHECKLIST: [paste the checklist from Step 0.5 — NOT the raw reference docs]. [How to measure, from your metric definition]. Score the current state 0-100 against the checklist criteria. Return your response with a clear SCORE: [number] line, a list of FINDINGS, and the single TOP ISSUE most likely to improve the score if fixed."
+
+> **Pass the Scoring Criteria Checklist (from Step 0.5) to the measurement agent. Do NOT paste full reference docs into the prompt. The agent retains Read access for on-demand lookups if the checklist doesn't cover a specific detail, but the prompt must not pre-inject stable docs.**
 
 Read the agent's response. You need: the SCORE, the TOP ISSUE, and the file paths for diagnosis in Step 3. Record the score to `docs/plans/.build-state.md`. The full findings list is useful for diagnosis but does NOT need to persist in your context across iterations — once you've picked the top issue, the details of lower-priority findings can go. Append a row to the score log in `docs/plans/.build-state.md`:
 
@@ -52,12 +96,19 @@ Read the agent's response. You need: the SCORE, the TOP ISSUE, and the file path
 Stop the loop if ANY of these:
 
 - **Score >= target** → done. Log "Target met at iteration [N]."
+- **Iter-1 short-circuit: score >= target + 10 on the first measurement** → done. Log "Short-circuit at iteration 1. Score: [N]." and record `exit_reason: "short_circuit_iter1"` in the loop state.
 - **Iteration >= max** → done. Log "Max iterations reached. Final score: [N]."
 - **Stall: last 2 scores show no improvement** (delta <= 0 twice in a row) → done. Log "Stalled at score [N]."
 
+### Early exit — iter-1 short-circuit
+If the first measurement (iter-1) scores >= `target + 10`, exit the loop immediately and commit the iter-1 output. Log `exit_reason: "short_circuit_iter1"` in the loop state. The 10-point margin guards against measurement noise at the boundary; a genuinely excellent first pass does not need rework.
+
 On stall or max iterations:
 - **Interactive mode:** present score history + top remaining issue to user. Ask for direction.
-- **Autonomous mode:** if score >= 60% of target, accept with warning. Otherwise skip. Log to `docs/plans/build-log.md`.
+- **Autonomous mode:**
+  - If score >= target: done (this branch is already handled in Step 2's exit conditions; included here for completeness).
+  - If score >= 60% of target AND no CRITICAL issues remain in the measurement: accept with WARNING. Log to `docs/plans/build-log.md` with the warning text and the score history. The orchestrator may proceed to the next phase, but the warning MUST be surfaced in the Phase 7 Completion Report's "Verification Gap" section.
+  - If score < 60% of target OR any CRITICAL issue remains: HALT. Do NOT skip. Log "METRIC LOOP: BLOCKED" to `docs/plans/.build-state.md` with the score history and the unresolved issues. Either (a) re-dispatch the fix agent with the unresolved issues, OR (b) abort the build with a directive to the user. The orchestrator may NOT silently proceed past a metric loop that did not converge.
 
 If not exiting, continue to Step 3.
 
@@ -73,6 +124,11 @@ Call the Agent tool — description: "Fix [top issue]" — mode: "bypassPermissi
 
 > **Do NOT pass the measurement agent's full findings to this agent. Only pass the single diagnosed issue and relevant file paths.**
 
+### Iteration-aware context rule
+
+- **Iteration 1 generator** receives the full phase context header + task description (the generator needs full context for its first pass).
+- **Iteration 2+ generator** receives ONLY: (a) the single top issue from diagnosis, (b) the relevant file paths, (c) the specific criteria values from the Scoring Criteria Checklist that relate to the top issue. The full `[CONTEXT header above]` preamble is NOT re-injected. The generator already has the codebase from iteration 1 — it only needs the delta.
+
 ## Step 5: LOOP
 
 Return to Step 1. Re-measure the artifact after the fix.
@@ -91,3 +147,7 @@ AUTHOR-BIAS ELIMINATION: The measurement agent and the fix agent must NEVER shar
 - Track ALL scores in `docs/plans/.build-state.md` so the history survives context compaction.
 - If context was compacted mid-loop: read `docs/plans/.build-state.md`, find the Active Metric Loop section, resume from the last recorded iteration.
 - CONTEXT HYGIENE: Measurement agents are analysis agents — read their full output for diagnosis. But once you've picked the top issue (Step 3) and dispatched the fix (Step 4), the detailed findings from THAT iteration are spent. Don't accumulate findings across iterations — each measurement is fresh.
+<STABLE-CONTEXT-RULE>
+STABLE CONTEXT RULE: Reference docs that do not change during the loop (design specs, DNA cards, architecture docs, acceptance criteria) MUST be extracted into the Scoring Criteria Checklist at Step 0.5 and passed as the checklist — never re-injected as raw content into iteration 2+ prompts. Fresh artifacts (screenshots, test results, rendered output) are fetched each iteration. This is the primary token-saving mechanism: ~1-2K checklist vs ~20-30K raw docs per iteration.
+</STABLE-CONTEXT-RULE>
+- CHECKLIST FALLBACK: If no Scoring Criteria Checklist is provided (Step 0.5 was skipped or caller did not pass one), the critic falls back to raw doc reads. The orchestrator MUST log a WARN to `docs/plans/build-log.md`: "Metric loop iteration [N]: no scoring criteria checklist provided, falling back to raw doc reads." Callers SHOULD always provide a checklist. New callers that omit it will trigger the WARN, making silent regressions visible.

package/protocols/smoke-test.md

@@ -19,7 +19,15 @@ Check that `agent-browser` is available:
 which agent-browser
 ```
 
-If not installed, log "SMOKE: SKIPPED -- agent-browser not available" to `docs/plans/.build-state.md` and return. Do not block the build.
+**If installed:** proceed to Step 1.
+
+**If not installed AND the task has a non-N/A Behavioral Test field in `docs/plans/sprint-tasks.md`:**
+1. Dispatch an installer agent: "Install agent-browser via `npm install -g agent-browser`. Verify `which agent-browser` returns a path. Report PASS/FAIL." MAX 2 attempts.
+2. If installation succeeds, proceed to Step 1.
+3. If installation fails after 2 attempts, hard-fail the smoke test with directive: "agent-browser installation failed. Either (a) install manually and re-run, or (b) explicitly downgrade this task's Behavioral Test field to N/A in `sprint-tasks.md` to acknowledge the gap. The orchestrator may NOT proceed silently."
+4. Log "SMOKE: BLOCKED -- agent-browser unavailable, task [task-name] has Behavioral Test [field text]" to `docs/plans/.build-state.md`. Do NOT log SKIPPED. Do NOT log PASS. Return BLOCKED.
+
+**If not installed AND the task has Behavioral Test field = N/A:** log "SMOKE: SKIPPED -- task acknowledged as no-behavioral-coverage" with the task name. Return SKIPPED. (This is the only legal silent skip path, and it requires the spec to have explicitly declared N/A.)
 
 ## Step 1: Start Dev Server
 

package/protocols/state-schema.json

@@ -0,0 +1,388 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$comment": "Schema version migration table: schema_version 1 = Stages 1-3; schema_version 2 = Stage 4 (adds backward_routing_count, backward_routing_count_by_target_phase, in_flight_backward_edge, mode_transitions); schema_version 3 = Stage 5 (adds lrr_cycle_state); schema_version 4 = Stage 6 (adds current_sprint_context_hash). --- Runtime validation rules (not encodable in JSON Schema, require code): Rule 5 — step prefix must match current phase number; Rule 6 — mode/autonomous consistency (mode==='autonomous' iff autonomous===true); Rule 7 — iOS fields gating (app_name, bundle_id, xcodeproj_path, ios_features, phase_progress.phase_minus_1 exist iff project_type==='ios'); Rule 10 — pending/in-progress disjoint (in_progress_task.task_id not in pending_tasks or completed_tasks); Rule 11 — resume_point.phase/step must not be ahead of top-level phase/step; Rule 12 — timestamps monotonic (session_last_saved >= session_started).",
+  "title": ".build-state.json",
+  "description": "Typed source of truth for BuildAnything build state. Validated by the PreToolUse schema lint hook (W2-2). additionalProperties: false enforces fail-closed per A8 SSOT rule.",
+  "type": "object",
+  "additionalProperties": false,
+
+  "$defs": {
+    "completed_task": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["task_id", "task_name", "status", "evidence_files", "completed_at"],
+      "properties": {
+        "task_id":        { "type": "string" },
+        "task_name":      { "type": "string" },
+        "status":         { "type": "string", "enum": ["done", "skipped", "deferred"] },
+        "evidence_files": { "type": "array", "items": { "type": "string" } },
+        "completed_at":   { "type": "string", "format": "date-time" }
+      }
+    },
+
+    "in_progress_task": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["task_id", "task_name", "started_at"],
+      "properties": {
+        "task_id":    { "type": "string" },
+        "task_name":  { "type": "string" },
+        "started_at": { "type": "string", "format": "date-time" }
+      }
+    },
+
+    "metric_loop_entry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["phase", "iteration", "score", "target", "top_issue", "timestamp"],
+      "properties": {
+        "phase":     { "type": "integer" },
+        "iteration": { "type": "integer" },
+        "score":     { "type": "number" },
+        "target":    { "type": "number" },
+        "top_issue": { "type": "string" },
+        "timestamp": { "type": "string", "format": "date-time" },
+        "scoring_criteria_checklist": { "type": "string" },
+        "extraction_method": {
+          "type": "string",
+          "enum": ["mechanical", "one-shot-dispatch", "mixed"]
+        }
+      }
+    },
+
+    "active_metric_loop": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["phase", "artifact", "metric", "target", "max_iterations", "current_iteration"],
+      "properties": {
+        "phase":             { "type": "integer" },
+        "artifact":          { "type": "string" },
+        "metric":            { "type": "string" },
+        "target":            { "type": "number" },
+        "max_iterations":    { "type": "integer" },
+        "current_iteration": { "type": "integer" },
+        "scoring_criteria_checklist": { "type": "string" },
+        "extraction_method": {
+          "type": "string",
+          "enum": ["mechanical", "one-shot-dispatch", "mixed"]
+        }
+      }
+    },
+
+    "blocker": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "description", "surfaced_at", "type"],
+      "properties": {
+        "id":          { "type": "string" },
+        "description": { "type": "string" },
+        "surfaced_at": { "type": "string", "format": "date-time" },
+        "type":        { "type": "string", "enum": ["build", "design", "dep", "external"] }
+      }
+    },
+
+    "dispatch_counter": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["dispatches_since_save", "last_save_phase"],
+      "properties": {
+        "dispatches_since_save": { "type": "integer", "minimum": 0 },
+        "last_save_phase":       { "type": "string" }
+      }
+    },
+
+    "resume_point": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["phase", "step", "autonomous", "completed_summary", "git_branch"],
+      "properties": {
+        "phase":             { "type": "integer", "enum": [-1, 0, 1, 2, 3, 4, 5, 6, 7] },
+        "step":              { "type": "string" },
+        "autonomous":        { "type": "boolean" },
+        "completed_summary": { "type": "string" },
+        "git_branch":        { "type": "string" }
+      }
+    },
+
+    "verification": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["last_verify_result", "last_verify_timestamp"],
+      "properties": {
+        "last_verify_result": {
+          "oneOf": [
+            { "type": "string", "enum": ["PRODUCTION_READY", "NEEDS_WORK", "BLOCKED"] },
+            { "type": "null" }
+          ]
+        },
+        "last_verify_timestamp": {
+          "oneOf": [
+            { "type": "string", "format": "date-time" },
+            { "type": "null" }
+          ]
+        }
+      }
+    },
+
+    "ios_features": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "widgets", "liveActivities", "appIntents", "foundationModels",
+        "storekit", "healthkit", "push", "cloudkit",
+        "siri", "location", "background", "cameraPhoto",
+        "microphone", "contacts", "calendar", "appleWatch"
+      ],
+      "properties": {
+        "widgets":          { "type": "boolean" },
+        "liveActivities":   { "type": "boolean" },
+        "appIntents":       { "type": "boolean" },
+        "foundationModels": { "type": "boolean" },
+        "storekit":         { "type": "boolean" },
+        "healthkit":        { "type": "boolean" },
+        "push":             { "type": "boolean" },
+        "cloudkit":         { "type": "boolean" },
+        "siri":             { "type": "boolean" },
+        "location":         { "type": "boolean" },
+        "background":       { "type": "boolean" },
+        "cameraPhoto":      { "type": "boolean" },
+        "microphone":       { "type": "boolean" },
+        "contacts":         { "type": "boolean" },
+        "calendar":         { "type": "boolean" },
+        "appleWatch":       { "type": "boolean" }
+      }
+    },
+
+    "phase_progress": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "phase_0", "phase_1", "phase_2", "phase_3",
+        "phase_4", "phase_5", "phase_6", "phase_7"
+      ],
+      "properties": {
+        "phase_minus_1": { "type": "boolean" },
+        "phase_0":       { "type": "boolean" },
+        "phase_1":       { "type": "boolean" },
+        "phase_2":       { "type": "boolean" },
+        "phase_3":       { "type": "boolean" },
+        "phase_4":       { "type": "boolean" },
+        "phase_5":       { "type": "boolean" },
+        "phase_6":       { "type": "boolean" },
+        "phase_7":       { "type": "boolean" }
+      }
+    },
+
+    "in_flight_backward_edge": {
+      "$comment": "Stage 4+ (schema_version >= 2). Written atomically with counter increment on backward-route dispatch. Cleared by target phase on re-entry. Stale edges (>60s) trigger counter decrement on --resume.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["decision_id", "target_phase", "counter_value", "started_at"],
+      "properties": {
+        "decision_id":   { "type": "string" },
+        "target_phase":  { "type": "string" },
+        "counter_value": { "type": "integer", "minimum": 0 },
+        "started_at":    { "type": "string", "format": "date-time" }
+      }
+    },
+
+    "mode_transition": {
+      "$comment": "Stage 4+ (schema_version >= 2). Records SDK/markdown flag-flip events. Each entry captures which flag changed, the prior and new values, a full post-flip snapshot of all tracked flags, the session_id when known, and a timestamp.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["flag", "old_value", "new_value", "timestamp"],
+      "properties": {
+        "flag":       { "type": "string", "description": "Env-var name (e.g., BUILDANYTHING_SDK)." },
+        "old_value":  { "type": "string" },
+        "new_value":  { "type": "string" },
+        "post_flags": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Snapshot of all tracked flag values AFTER this flip." },
+        "session_id": { "type": ["string", "null"] },
+        "timestamp":  { "type": "string", "format": "date-time" }
+      }
+    }
+  },
+
+  "required": [
+    "schema_version",
+    "project_type",
+    "phase",
+    "step",
+    "session_id",
+    "session_started",
+    "session_last_saved",
+    "autonomous",
+    "mode",
+    "build_request",
+    "context_level",
+    "git_branch",
+    "completed_tasks",
+    "pending_tasks",
+    "phase_artifacts",
+    "metric_loop_history",
+    "dispatch_counter",
+    "phase_progress",
+    "resume_point",
+    "verification"
+  ],
+
+  "properties": {
+    "schema_version": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 4,
+      "description": "Currently 1 (Stages 1-3). Bumped to 2 at Stage 4, 3 at Stage 5, 4 at Stage 6."
+    },
+    "project_type": {
+      "type": "string",
+      "enum": ["ios", "web"],
+      "description": "Drives mode-branch routing."
+    },
+    "phase": {
+      "type": "integer",
+      "enum": [-1, 0, 1, 2, 3, 4, 5, 6, 7],
+      "description": "Current phase. -1 is iOS bootstrap only."
+    },
+    "step": {
+      "type": "string",
+      "description": "Dotted step identifier within the phase (e.g. '5.3b', '6.4', '-1.1')."
+    },
+    "session_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "UUID generated at session start; stable across compactions within a session."
+    },
+    "session_started": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when the current session began."
+    },
+    "session_last_saved": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of the most recent state write. Must be >= session_started."
+    },
+    "autonomous": {
+      "type": "boolean",
+      "description": "Whether --autonomous was passed. Must agree with mode field."
+    },
+    "mode": {
+      "type": "string",
+      "enum": ["interactive", "autonomous"],
+      "description": "interactive iff autonomous === false."
+    },
+    "build_request": {
+      "type": "string",
+      "description": "Original user prompt that initiated the build."
+    },
+    "context_level": {
+      "type": "string",
+      "enum": ["raw_idea", "decision_brief", "partial_context", "full_design"],
+      "description": "Richness of the initial context provided."
+    },
+    "git_branch": {
+      "type": "string",
+      "description": "Current branch; 'main' if uninitialized."
+    },
+    "completed_tasks": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/completed_task" },
+      "description": "Tasks finished. May be empty []."
+    },
+    "pending_tasks": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "task_ids still to be dispatched. May be empty []."
+    },
+    "phase_artifacts": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Paths to persisted phase outputs. All properties optional; empty {} is valid."
+    },
+    "metric_loop_history": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/metric_loop_entry" },
+      "description": "Scored iterations across all phases. May be empty []."
+    },
+    "dispatch_counter": {
+      "$ref": "#/$defs/dispatch_counter",
+      "description": "Used by the 'save every N dispatches' heuristic."
+    },
+    "phase_progress": {
+      "$ref": "#/$defs/phase_progress",
+      "description": "Boolean per phase. phase_minus_1 is optional (iOS only)."
+    },
+    "resume_point": {
+      "$ref": "#/$defs/resume_point",
+      "description": "Snapshot used by Phase-0 resume logic."
+    },
+    "verification": {
+      "$ref": "#/$defs/verification",
+      "description": "Last verify result and timestamp."
+    },
+
+    "app_name": {
+      "type": "string",
+      "description": "iOS only. App display name."
+    },
+    "bundle_id": {
+      "type": "string",
+      "description": "iOS only. Bundle identifier."
+    },
+    "xcodeproj_path": {
+      "type": "string",
+      "description": "iOS only. Absolute path to .xcodeproj."
+    },
+    "ios_features": {
+      "$ref": "#/$defs/ios_features",
+      "description": "iOS only. Exactly 16 boolean feature flags."
+    },
+    "in_progress_task": {
+      "$ref": "#/$defs/in_progress_task",
+      "description": "Task currently executing. Present only while a task is in flight."
+    },
+    "active_metric_loop": {
+      "$ref": "#/$defs/active_metric_loop",
+      "description": "Present only while a metric loop is running. Removed when loop completes."
+    },
+    "blockers": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/blocker" },
+      "description": "Open blockers. Omitted when empty."
+    },
+    "decisions_next_id": {
+      "type": "object",
+      "additionalProperties": { "type": "integer", "minimum": 0 },
+      "description": "Keyed by phase number string. Integer values = next sequence. Deprecated under Stage 2 (scribe owns ID allocation); scheduled for removal at Stage 4 A7."
+    },
+
+    "backward_routing_count": {
+      "type": "object",
+      "additionalProperties": { "type": "integer", "minimum": 0 },
+      "description": "Stage 4+ (schema_version >= 2). Per-decision backward routing counter: decision_id -> count."
+    },
+    "backward_routing_count_by_target_phase": {
+      "type": "object",
+      "additionalProperties": { "type": "integer", "minimum": 0 },
+      "description": "Stage 4+ (schema_version >= 2). Per-target-phase backward routing counter: phase -> count."
+    },
+    "in_flight_backward_edge": {
+      "$ref": "#/$defs/in_flight_backward_edge",
+      "description": "Stage 4+ (schema_version >= 2). Present only while a backward-routing edge is in flight."
+    },
+    "mode_transitions": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/mode_transition" },
+      "description": "Stage 4+ (schema_version >= 2). Records SDK/markdown flag-flip events."
+    },
+
+    "lrr_cycle_state": {
+      "type": "object",
+      "description": "Stage 5+ (schema_version >= 3). LRR cycle state and aggregator output fields."
+    },
+
+    "current_sprint_context_hash": {
+      "type": "string",
+      "description": "Stage 6+ (schema_version >= 4). Hash of sprint-scoped shared context; triggers re-render only on sprint boundary."
+    }
+  }
+}