@isparling/engram-coach 0.1.0 → 0.2.0

package/skills/adapt-plan/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: adapt-plan
+description: Use when a key workout has been completed and you need to analyze it against the prescription, gather subjective experience, and adapt the next planned workout. Requires Intervals.icu MCP tools and config.json with coaching_docs_dir and prescriptions_dir configured.
+---
+
+# Adapt Plan
+
+## Overview
+
+Rigid five-phase workflow for post-workout analysis and prescription adaptation. Integrates objective execution data with subjective athlete experience and training block context to make evidence-based adjustments to the next workout prescription. All reasoning is recorded as persistent knowledge in the coaching docs directory.
+
+**This skill is RIGID — phases execute in exact order. Do not skip, reorder, or combine phases.**
+
+## Workflow
+
+```dot
+digraph adapt_plan {
+    "Phase 1: Orient" [shape=box];
+    "Phase 2: Gather" [shape=box];
+    "Phase 3: Synthesize" [shape=box];
+    "Phase 4: Propose" [shape=box];
+    "Athlete approves?" [shape=diamond];
+    "Phase 5: Apply" [shape=box];
+
+    "Phase 1: Orient" -> "Phase 2: Gather";
+    "Phase 2: Gather" -> "Phase 3: Synthesize";
+    "Phase 3: Synthesize" -> "Phase 4: Propose";
+    "Phase 4: Propose" -> "Athlete approves?";
+    "Athlete approves?" -> "Phase 5: Apply" [label="yes"];
+    "Athlete approves?" -> "Phase 4: Propose" [label="revise"];
+}
+```
+
+---
+
+### Pre-Phase Setup _(no user input — run silently)_
+
+Follow **`${CLAUDE_PLUGIN_ROOT}/shared/setup.md`** — the shared configuration
+preamble (paths, config, profile, persona, athlete profile).
+
+**Optional steps this skill declares:** PRESCRIPTIONS, SEASON, MCP, MONITORING
+
+Do not proceed past a stop condition defined there.
+
+
+### Phase 1 — Orient _(no user input)_
+
+Read and search silently before asking anything:
+
+1. **Active prescription/plan** — List all YAML files in `prescriptions_dir`. For each file, find the maximum session_date. The active block is the file whose most recent session_date is on or before today. If ambiguous (multiple files with recent sessions), ask: "I found multiple prescription files with recent sessions: [list]. Which block are you currently in?" Read the full prescription file for the active block and the surrounding block context (week number, phase, upcoming sessions).
+
+2. **Execution data** — retrieve completed workout from Intervals.icu MCP tools. Note the prescription vs. actual delta: power targets met/missed, duration completed, interval count, HR behavior, any visible fade or drift. Retrieve HRV and wellness data via Intervals.icu MCP tools (get_wellness). If this call fails or returns no data, continue Phase 1 without HRV context and annotate in the Orient summary: "[HRV data unavailable — MCP wellness tool returned no data. Orient proceeds without HRV context.]"
+
+2b. **Stream analysis** — read the active persona's `analyses` config from the loaded persona JSON. If the persona has no `analyses` field, skip this step entirely and proceed to step 3.
+
+   For each analysis entry where `enabled` is `true` (or `enabled` is absent, since default is `true`):
+   - Check if the current training phase (determined in step 1) matches the analysis's `phases` array. If `phases` is `null` or absent, the analysis runs in all phases. If the current phase is not in the `phases` array, skip this analysis.
+   - Consult `${CLAUDE_PLUGIN_ROOT}/analyses/catalog.md` for the analysis's data source and prerequisites.
+   - Check data prerequisites against the completed workout from step 2: does the activity have the required data (power, HR, pace)? Does it meet minimum duration requirements? Is it the right session type (e.g., steady-state for decoupling, intervals for execution quality)?
+   - Route the analysis to the correct data source using the table below.
+   - Classify the result against the persona's configured thresholds for this analysis.
+   - Store the result (metric value, classification, any notable details) for use in Phase 3 — Synthesize.
+
+   **Analysis routing table:**
+
+   | Analysis Key | Stream-dependent? | Data Source |
+   |---|---|---|
+   | `aerobic_decoupling` | Yes | `stream-analyze --analyses decoupling` |
+   | `hr_recovery_curve` | Yes | `stream-analyze --analyses hr_recovery` |
+   | `interval_execution_quality` | Partial | Fade/compliance: `get_activity_intervals` MCP; CV: `stream-analyze --analyses interval_cv` |
+   | `time_in_zones` | No | `get_power_histogram` + `get_hr_histogram` MCP |
+   | `power_curve_trend` | No | `get_power_curves` MCP |
+   | `hr_at_power_trend` | No | MCP tools (compact endpoints) |
+   | `resting_hr_trend` | No | `get_wellness` MCP |
+   | `hrv_trend` | No | `npx tsx ${CLAUDE_PLUGIN_ROOT}/analysis-analysis-tools/hrv-trend.ts --config {config_path} --date {target_date}` |
+
+   **`hrv_trend` — dedicated CLI tool:** When `hrv_trend` is enabled in the persona:
+   1. Run: `npx tsx ${CLAUDE_PLUGIN_ROOT}/analysis-analysis-tools/hrv-trend.ts --config {config_path} --date {today_YYYY-MM-DD}`. Pass persona-configured windows if present: `--short-window {short_window_days} --long-window {long_window_days} --metric {metric}`.
+   2. Parse the JSON output. If `classification.label` is `amber-red` or `red`, surface it prominently in the Orient announcement with the full `reasoning` string.
+   3. Store the complete output object as `hrv_trend_result` for use in Phase 3 — Synthesize and Phase 4 — Propose.
+   4. If the tool exits non-zero or the output is malformed, annotate: "[hrv_trend unavailable — {error}. Proceeding without.]" and continue.
+
+   **Stream-dependent analyses** — batch all applicable stream-dependent analysis keys into a single CLI call rather than calling separately per analysis:
+
+   1. Read `intervals_icu` config from `{config_path}`. If the `intervals_icu` block is missing or incomplete, skip all stream-dependent analyses and annotate: "[Stream analyses unavailable — intervals_icu config not found in config.json. See SETUP.md.]"
+   2. Run the CLI tool:
+      ```bash
+      npx tsx ${CLAUDE_PLUGIN_ROOT}/analysis-analysis-tools/stream-analyze.ts \
+        --activity-id {activity_id} \
+        --analyses {comma_separated_keys} \
+        --config {config_path}
+      ```
+      Where `{comma_separated_keys}` is the union of all stream-dependent analyses enabled for this session (e.g., `decoupling,hr_recovery,interval_cv`).
+   3. Parse the JSON output. For each analysis in the result, classify against persona thresholds. If an analysis appears in the `errors` field, skip it and annotate: "[{analysis_key} unavailable — {error_message}. Proceeding without.]"
+
+   **MCP-native analyses** — call the specified MCP tool(s) directly. These endpoints return compact structured data that enters the conversation context efficiently.
+
+   If the activity lacks required data for an analysis (e.g., no power meter, session too short, no identifiable intervals), skip that analysis silently — it is not applicable to this session type.
+
+   After processing all applicable analyses, include a brief summary in the Orient announcement: which analyses ran, which were skipped and why, and any results that immediately stand out (e.g., a red-classified result).
+
+2c. **TSB projection** — after retrieving the completed workout's TSS (from step 2), call the TSB prediction tool:
+
+   ```bash
+   npx tsx ${CLAUDE_PLUGIN_ROOT}/analysis-analysis-tools/tsb-predict.ts --ctl {current_ctl} --atl {current_atl} --tss {tss_sequence}
+   ```
+
+   Where `{tss_sequence}` is a comma-separated list of estimated daily TSS values for the upcoming days, derived from:
+   - Today's completed session TSS (from step 2, actual value)
+   - Upcoming prescribed sessions: estimate TSS from the prescription's power targets and duration. Use the athlete's historical TSS for similar session types as calibration when available.
+   - Rest/walk days: use 0 or a small fixed value (30-40) based on typical walk TSS from recent data.
+
+   Include the projection output in the Orient announcement:
+   - Predicted next-morning CTL/ATL/TSB
+   - Multi-day trajectory through the end of the current week
+   - Flag any day where projected TSB crosses a persona threshold (push/moderate/easy/rest)
+
+   If the tool is not installed (npm dependencies missing in analysis-tools/), skip this step and annotate: "[TSB projection unavailable — run `npm install` in analysis-tools/.]"
+
+3. **Training block context** — determine current phase (base/build/peak/recovery), position within the week, and upcoming workouts that may be affected by today's adaptation. After identifying the active block from step 1, resolve the block name to a template file name by stripping any date prefix and normalizing to lowercase with hyphens (e.g., "Build 1" → "build-1", "Base" → "base", "Race Specificity" → "race-specificity"). Then read `${CLAUDE_PLUGIN_ROOT}/templates/{block-name}.md` as additional context. This file describes the block's intent, session patterns, weekly structure, and success signals. If the file is missing: continue without it and annotate in the Orient summary: "[Block template {block-name}.md not found — proceeding without block template context.]"
+
+4. **Retrieval — find precedent.** Follow `${CLAUDE_PLUGIN_ROOT}/shared/retrieval.md`.
+   Build 2-3 queries from *this session's specifics* — the session type, the numbers
+   actually observed, and any anomaly worth explaining — never from this skill's name
+   or topic. Cover both levels the policy describes: durable pattern, and session
+   precedent. Report honestly when nothing relevant is found.
+
+Announce what you found before asking anything. If past decisions are relevant (e.g., "Last time RPE was high on week 2 sub-LT2, we reduced interval count by one"), surface them explicitly.
+
+---
+
+### Phase 2 — Gather _(one question at a time)_
+
+Ask only what execution data cannot answer. Adapt to what the data shows — if a specific pattern is visible (e.g., power fade >10% on final interval), ask specifically about that observation rather than generically.
+
+Core question domains:
+
+1. **Overall RPE** — rate the full session 1–10
+2. **Interval progression** — how did intervals feel early vs. late? (effort drift, fade, or build)
+3. **Physical sensations** — leg heaviness, HR behavior, breathing quality, any discomfort or unusual response
+4. **Recovery context** — sleep quality the night before, life stress, sense of accumulated fatigue going into the session
+5. **In-session modifications** — anything deliberately changed in the moment and why
+
+**Ask one question at a time. Wait for each answer before asking the next.**
+
+---
+
+### Phase 3 — Synthesize _(shown to athlete)_
+
+Reason aloud before proposing anything. Cover:
+
+- Prescription vs. execution delta — what happened vs. what was planned
+- Stream analysis results — for each analysis that produced a result in step 2b, state: the metric value, its threshold classification (green/amber/red per persona thresholds), and how it interacts with the existing signal picture (TSB/HRV/CTL). Consult the persona's monitoring.md `## Analysis Interpretation` section for the interpretation framework and coaching voice for each analysis. Higher-weight analyses (as configured in the persona's `analyses` config) receive more reasoning space; lower-weight analyses are mentioned briefly. Analyses that **reinforce** the existing signal picture (e.g., decoupling green while TSB is in push zone) are noted concisely. Analyses that **contradict** the existing signal picture (e.g., decoupling red while TSB is in push zone) are called out explicitly with the specific signal interaction from the monitoring.md — these contradictions are the high-value findings that may change the recommendation.
+- Subjective data weighted against objective data (e.g., low RPE despite power fade → pacing issue, not fitness gap)
+- Training block position — implications differ between early build (accumulate) and peak week (preserve)
+- Upcoming workout demands — does the next session's intensity change the calculus?
+- Relevant patterns from QMD history — call out if this matches a prior situation
+- **HRV trend (when `hrv_trend` fired):** State the statistical position — z_long, percentile, consecutive days below long mean — not just the raw value. Reference the analog lookup: "In N prior instances at or below this value, the median rebound was X days [and prior episodes did/did not show sustained suppression]." This positions the recommendation on the personal distribution rather than an absolute threshold.
+
+This phase is **explanatory only**. No changes proposed yet. The athlete can push back on any part of the reasoning before you proceed.
+
+Alongside the reasoning above, assemble the typed domain input for this adaptation as a `StructuredChangeSet`. Emit **one state change** containing:
+
+- `entity_type: "prescription"` with `key_components` carrying `arc_id` and the durable `session_id` of the NEXT session being adapted
+- the effective date of the change
+- a concise statement of what changes and why
+- the COMPLETE updated prescription session value — never a prose patch. The value must carry every field of the session: `sessionId`, `sessionDate`, `sessionName`, block metadata (`blockName`, `week`, `day`), `order`, `effortZone`, warmup/cooldown power bands, and the full `intervals` array (each with `durationMin`, `powerLowPct`, `powerHighPct`, `count`, `recoveryMin`)
+- the artifact relative path (e.g. `prescriptions/{arc_id}.yaml`)
+
+Also emit **one workout-adaptation event** containing:
+
+- the completed workout: name, date, and the source activity ID from Intervals.icu
+- the objective deltas — prescription vs. execution metrics gathered in Phase 1 (power targets met/missed, duration completed, fade/drift)
+- the subjective inputs gathered in Phase 2 (RPE, sensations, recovery context, in-session modifications)
+- the approved rationale linking the Phase 3 evidence to the change
+- the stream-analysis results: for each analysis that ran in step 2b, the metric value and its threshold classification (green/amber/red per persona thresholds)
+- the signal interactions noted during Synthesize — how the analyses combined with TSB/HRV/CTL to inform the recommendation
+- `action_targets`: the session IDs the adaptation acts on
+- the compatibility path of the adaptation log (e.g. `coaching/adaptations.md`)
+
+If Phase 3 concludes no prescription change is warranted, the change set carries only the workout-adaptation event.
+
+**Monitoring contributions (merged BEFORE Phase 4)**
+
+Before Phase 4 begins, collect due monitoring contributions so ONE preview
+covers everything:
+
+1. Invoke the `monitoring-rollup` skill in **CONTRIBUTION MODE** with
+   `source = adapt:{block}-{week}-{session}` and the session context already
+   gathered. It reads `{coaching_docs_dir}/tracking/concerns.yaml`, gathers
+   any DUE active concern, and RETURNS typed `state_changes` (keyed
+   `monitoring:<concern-id>:<signal>` current state) and append-only
+   `events` — it never previews, never applies, and never writes.
+2. Merge both arrays into THIS change set. The merged change set is what
+   Phase 4 previews: one plan hash and one approval cover the prescription
+   adaptation, the workout-adaptation event, and all due monitoring changes
+   together.
+3. If no concern is active or due, monitoring-rollup returns EMPTY arrays.
+   Merge them and continue — the parent's single preview stands; never
+   produce a second preview for monitoring.
+
+---
+
+
+### Phase 4 — Propose _(requires explicit approval)_
+
+Propose specific changes to the next workout. For each change state explicitly:
+
+- **What** changes — interval count, duration, intensity target, rest period, structure
+- **Why** — the specific reasoning from Phase 3 that drives this change
+- **Tradeoffs** — what will have to change (other sessions in the plan, recovery, or anything outside the plan) to support this change.
+
+Example format:
+
+> "Reduce next sub-LT2 session from 4×12 to 3×12 — RPE 8.5 on the final interval with visible HR drift suggests cumulative fatigue is higher than block average. Week 3 Thursday is a harder session; preserving freshness outweighs hitting volume today."
+
+**When `hrv_trend` fired and `hrv_trend_result` is available:** Express HRV gates in baseline-relative terms. Example:
+
+> **GO** if tomorrow's HRV ≥ `long_mean − 0.5×long_sd` (≈ {computed value} based on today's baseline)
+> **MODIFIED** if `long_mean − 1.5×long_sd ≤ HRV < long_mean − 0.5×long_sd`
+> **STAND DOWN** if `HRV < long_mean − 1.5×long_sd` OR {consecutive_days_below_long_mean}+ consecutive days below long mean
+
+Compute the numeric approximations from `hrv_trend_result.baselines.long_mean` and `hrv_trend_result.baselines.long_sd`. This recalibrates gates automatically as the baseline drifts.
+
+**Before presenting anything**, call `engram_capture_preview` with the Phase 3 merged `StructuredChangeSet` — the single preview covers the prescription adaptation, the workout-adaptation event, and any due monitoring contributions as one plan.
+
+If the preview returns blocked, STOP: Phase 4 cannot proceed until the input is corrected and a preview succeeds.
+
+Present TOGETHER, in one message:
+
+1. The human coaching proposal: for each change, **What** changes, **Why**, and any **Tradeoffs** (including the HRV gates above when they fired).
+2. The record plan from the preview: which records will be created, refined, superseded, or retired.
+3. The generated compatibility artifact paths that will regenerate (e.g. `prescriptions/{arc_id}.yaml`, `coaching/adaptations.md`).
+4. The exact `plan_hash` from the preview result.
+
+Ask for approval. Approval must explicitly cover BOTH the coaching action AND the record/artifact plan identified by that exact `plan_hash` — approving the adaptation approves the durable mutation of the same content.
+
+Wait for **explicit approval, rejection, or modification**. On modification, rebuild the change set, re-run `engram_capture_preview`, and present the new hash.
+
+---
+
+### Phase 5 — Apply _(with approved hash)_
+
+Call `engram_capture_apply` with ONLY the exact `plan_hash` the athlete approved. Never edit any file directly and never invoke indexing tools by hand — every prescription YAML, the adaptation log, and the index are updated by the apply pipeline (records → guarded index refresh → regenerated compatibility views).
+
+Outcome handling:
+
+- **stale**: the records changed since preview. Return to Phase 4: re-run `engram_capture_preview`, present the fresh record plan and new `plan_hash`, and obtain fresh athlete approval before applying again.
+- **apply failure**: stop Phase 5. No compatibility view is written and none may be edited by hand; diagnose and retry through the tools.
+- **committed with a stale index or stale views**: the records ARE authoritative — report the authoritative record IDs to the athlete together with the materialized paths and the exact retry state: re-calling `engram_capture_apply` with the SAME committed `plan_hash` in the same session reruns only materialization and never re-approves or re-applies the record mutations.
+- **committed clean**: report the applied record IDs and the regenerated compatibility view paths.
+
+---
+
+## Key Constraints
+
+| Rule                       | Detail                                                                                              |
+| -------------------------- | --------------------------------------------------------------------------------------------------- |
+| Rigid phases               | Execute in order — no skipping, reordering, or combining                                            |
+| Approval gate              | Nothing written until Phase 4 explicitly approved                                                   |
+| One question at a time     | Phase 2 never batches questions                                                                     |
+| Reasoning before proposing | Phase 3 must complete before Phase 4 begins                                                         |
+| Knowledge compounds        | Every adaptation recorded in `{coaching_docs_dir}/{season}/`; future Orient phases benefit from past decisions |

package/skills/block-review/SKILL.md

@@ -0,0 +1,275 @@
+---
+name: block-review
+description: Use at the end of a training block (or retroactively for past blocks) to synthesize block-level metrics and narrative into a SUMMARY.md. Requires Intervals.icu MCP tools and config.json with coaching_docs_dir and prescriptions_dir configured.
+---
+
+# Block Review
+
+## Overview
+
+Rigid four-phase workflow for end-of-block synthesis. Combines MCP-derived fitness metrics with QMD-retrieved narrative excerpts and athlete reflection to produce a `SUMMARY.md` document — the canonical block-level reference for all future Orient phases. Works at block boundaries and retroactively for past blocks.
+
+**This skill is RIGID — phases execute in exact order. Do not skip, reorder, or combine phases.**
+
+## Workflow
+
+```dot
+digraph block_review {
+    "Phase 1: Orient" [shape=box];
+    "Phase 2: Gather" [shape=box];
+    "Phase 3: Draft" [shape=box];
+    "Athlete approves?" [shape=diamond];
+    "Phase 4: Write" [shape=box];
+
+    "Phase 1: Orient" -> "Phase 2: Gather";
+    "Phase 2: Gather" -> "Phase 3: Draft";
+    "Phase 3: Draft" -> "Athlete approves?";
+    "Athlete approves?" -> "Phase 4: Write" [label="yes"];
+    "Athlete approves?" -> "Phase 3: Draft" [label="revise"];
+}
+```
+
+---
+
+### Pre-Phase Setup _(no user input — run silently)_
+
+Follow **`${CLAUDE_PLUGIN_ROOT}/shared/setup.md`** — the shared configuration
+preamble (paths, config, profile, persona, athlete profile).
+
+**Optional steps this skill declares:** SEASON, MCP
+
+Do not proceed past a stop condition defined there.
+
+
+### Phase 1 — Orient _(no user input)_
+
+Pull all data silently, then announce findings before asking anything.
+
+**MCP calls** — all scoped to the block date window:
+
+1. `get_wellness_data(days_back={block_duration_days + 1})` — CTL/ATL/TSB, HRV rMSSD,
+   RHR per day across the full block. Scope to dates between `block_start` and `block_end`.
+
+2. `get_recent_activities(days_back={block_duration_days + 1}, limit=50)` — per-session
+   TSS, activity name, type, date. Filter to dates within the block window.
+
+3. `get_power_curves(days_back=28)` and `get_power_curves(days_back=90)` — power at
+   persona-configured durations for block vs. 90-day baseline comparison.
+   If these calls return an API error (known recurring issue), skip and annotate:
+   "[Power curve data unavailable — MCP API error. Proceeding without power curve section.]"
+
+**Compute and extract from MCP data:**
+
+- **CTL trajectory:** value at `block_start`, value at `block_end`, peak value and date,
+  delta (end minus start), peak ramp rate (largest single-day CTL increase)
+- **ATL trajectory:** peak value and date, value at `block_end`
+- **TSB trajectory:** lowest point and date, value at `block_end`
+- **HRV rMSSD:** block average (mean of all daily readings), first-week average vs.
+  last-week average (trend direction), lowest reading and date
+- **RHR:** block average, first-week average vs. last-week average (trend direction)
+- **Volume by week:** sum TSS per calendar week within the block window
+- **Power curve:** % change at persona-configured durations
+  (block 28-day best vs. 90-day best; positive = improving, negative = declining)
+
+**QMD queries** — narrative and decision context:
+
+```bash
+qmd query "{block_name} key session progression"
+qmd query "{block_name} adaptation decisions"
+qmd vsearch "{block_name}"
+
+Follow `${CLAUDE_PLUGIN_ROOT}/shared/retrieval.md` when constructing these — parameterize with the specifics below, and add queries for whatever this particular block actually raises.
+```
+
+Extract from QMD results:
+- Key session metric progressions (power/HR/RPE across W1→W2→W3 for each key
+  session type: threshold intervals, over-under intervals, long ride)
+- Notable adaptation decisions and their reasoning
+- Patterns flagged in "Patterns for Future Orient Phases" sections
+
+**Announce** what was found. Cover:
+- Block dates, duration, total TSS
+- CTL trajectory summary (start → end, delta, peak ramp rate)
+- HRV and RHR trend direction over the block
+- Key session progressions surfaced by QMD
+- Power curve trend if available
+- Any data gaps (missing HRV days, power curve API errors, etc.)
+- Any immediately notable findings (e.g., highest ramp rate of the training year,
+  HRV suppression pattern, power curve decline despite CTL growth)
+
+---
+
+### Phase 2 — Gather _(one question at a time)_
+
+Ask exactly three questions, in order. Wait for each answer before asking the next.
+
+1. **Block surprise:** "Looking at the block as a whole — what surprised you most,
+   positively or negatively?"
+
+2. **Forward confidence:** "What's your confidence going into [next block name]?
+   What feels strongest, and what feels like the biggest unknown?"
+
+3. **Off-record context:** "Is there anything that happened during this block —
+   training or life — that the adaptation records might not fully capture?"
+
+---
+
+### Phase 3 — Draft _(shown to athlete)_
+
+Present the complete `SUMMARY.md` content as a draft. The athlete can request
+changes before anything is written. Iterate until explicitly approved.
+
+**Explicit report conclusions:** alongside the narrative sections, distill
+the block's atomic, explicitly approved conclusions — facts that bear on
+existing keyed state (thresholds, persona signals, monitoring concerns).
+Each conclusion is recorded as an entry of the `report_claims` array in
+the structured change set (`StructuredReportClaim`) with ALL of:
+- `entity_type`: `block-conclusion`
+- `key_components`: the exact canonical state entity it bears on
+  (`entity_type` plus its durable identity components)
+- `effective_at`: the effective time of the conclusion
+- `statement`: one-sentence human-readable claim
+- `source_document`: the relative path of the `SUMMARY.md` this conclusion
+  comes from
+- `details`: the structured value of the conclusion
+
+Narrative stays in the document; only these atomic conclusions become
+records.
+
+**Record preview — one combined approval:** alongside the full `SUMMARY.md`
+draft, call `engram_capture_preview({ change_set })` with the change set
+containing those `report_claims`. Show the complete report AND the record
+preview (the exact plan hash, each record's role/classification) together.
+The athlete approves BOTH under ONE approval; the approved plan hash is
+bound to this exact content. Iterate until explicitly approved. If the
+preview is blocked, fix the change set and re-preview — this phase cannot
+complete without a ready plan hash.
+
+**Document structure:**
+
+```markdown
+# {Block Display Name} — Block Summary
+**Dates:** {block_start} → {block_end}
+**Persona:** {active_persona display name}
+**Block goal:** {one sentence from template, or inferred from block name if template missing}
+
+## Fitness Metrics
+| Metric | Block Start | Block End | Change |
+|--------|------------|-----------|--------|
+| CTL | | | |
+| ATL (peak) | {date} | | |
+| TSB (low point) | {date} | | |
+| HRV rMSSD (block avg) | — | — | {first week avg} → {last week avg} |
+| RHR (block avg) | — | — | {first week avg} → {last week avg} |
+| Peak ramp rate | — | — | {value} TSS/day |
+
+## Volume
+| Week | Actual TSS | Key sessions completed |
+|------|-----------|----------------------|
+| W1 | | |
+| W2 | | |
+| W3 | | |
+| Total | | |
+
+## Key Session Progressions
+{One table per key session type present in the block}
+
+Example for threshold intervals:
+| | W1 | W2 | W3 |
+|---|---|---|---|
+| Structure | 3×10min | 3×12min | 4×12min |
+| Avg power | | | |
+| Avg HR | | | |
+| RPE | | | |
+| Notes | | | |
+
+## Power Curve
+{Skip section if data unavailable — annotate why}
+| Duration | Block best | vs. 90-day best | Trend |
+|----------|-----------|-----------------|-------|
+| 20min (1200s) | | | |
+| 60min (3600s) | | | |
+
+## Block Assessment
+Narrative: how block goals (from template) compare to actual outcomes.
+What the data says worked. What the data says didn't. How the block's
+execution compared to the template's "signals this block should produce."
+Reference the active persona's stated decision signals — the volume policy
+prioritizes CTL trajectory, while the conservative policy weights freshness and HRV more heavily.
+
+## Athlete Perspective
+Narrative from Phase 2 Gather — surprises (positive and negative),
+qualitative feel of the block, what the athlete would do differently.
+Written in the athlete's voice, not paraphrased into coaching language.
+
+## Calibration Points for Future Blocks
+Bullet list of concrete, queryable facts discovered during the block:
+- Session ceilings (e.g., "surge ceiling: 2 full + partial third at 5+ hours")
+- Recovery patterns (e.g., "big Saturday → 72hr to rebound to HRV 40+")
+- Fueling discoveries
+- Equipment notes
+- External stress interaction patterns
+- Anything flagged in individual adaptation records under "Patterns for Future Orient Phases"
+
+## Entering {Next Block Name}
+Confidence level (from Gather). Specific watchpoints for the first week
+of the next block based on how this one ended — what to monitor, what
+the first key session should confirm, and what would trigger a reassessment.
+```
+
+---
+
+### Phase 4 — Write _(with approval)_
+
+Write, in this exact order:
+
+**1. Block summary document — FIRST**
+
+Write `{coaching_docs_dir}/{season}/{block}/SUMMARY.md` with the approved
+content. Create the directory if it does not exist:
+```bash
+mkdir -p {coaching_docs_dir}/{season}/{block}/
+```
+
+This is the authoritative canonical block summary — it is never regenerated
+from records. **If this write fails for any reason, STOP: do not apply any
+records; report the failure to the athlete.**
+
+**2. Apply the approved capture plan**
+
+Only after the document write succeeded, call
+`engram_capture_apply({ plan_hash })` with the exact plan hash approved in
+Phase 3.
+- `status: "stale"` → the pending preview was discarded; return to Phase 3,
+  re-preview, and get fresh approval.
+- Report any index or compatibility-view staleness from the result to the
+  athlete (records remain authoritative either way); a stale index refresh
+  is retried via the guarded mechanism, never by editing generated views.
+
+**3. Auto-tail lessons-rollup — only after BOTH succeed**
+
+Invoke the `lessons-rollup` skill ONLY after BOTH the `SUMMARY.md` write AND
+the report claims apply succeeded:
+- `--source=block-review:{normalized-block-name}`
+- The bullets from the just-written SUMMARY.md's
+  `## Calibration Points for Future Blocks` section as the append list.
+
+The rollup keeps its own harness-backed claim gate; the report is never
+reconstructed from the captured claims. Non-additive diffs gate on athlete
+approval before writing.
+
+---
+
+## Key Constraints
+
+| Rule | Detail |
+|------|--------|
+| Rigid phases | Execute in order — no skipping, reordering, or combining |
+| Approval gate | Nothing written until Phase 3 draft explicitly approved — report text and capture plan approved together under one approval |
+| One question at a time | Phase 2 never batches questions |
+| No full file reads | MCP for metrics, QMD for narrative — no prescription YAML reads beyond frontmatter, no full adaptation record reads |
+| Retroactive-safe | Works on past blocks; block date window comes from prescription YAML frontmatter, not "today" |
+| Data gaps are acceptable | Missing power curves, HRV gaps, or QMD misses are annotated and the skill continues — a partial summary is better than no summary |
+| Canonical report first | Phase 4 writes `SUMMARY.md` FIRST; a failed document write stops before any record apply |
+| Explicit conclusions only | Only the atomic `report_claims` from the approved change set become records; narrative stays in the document |
+| Auto-tail rollup | lessons-rollup runs only after BOTH the document write and claims apply succeed |