@isparling/engram-coach 0.1.0 → 0.2.0

package/skills/set-goal/SKILL.md

@@ -0,0 +1,297 @@
+---
+name: set-goal
+description: Use when establishing a new training arc toward a new goal — typically between major training cycles, after a race, or when goals change. Produces a full arc: canonical arc-overview and methodology documents written directly, plus durable workout identities, structured prescription records, and explicit conclusions captured through the previewed engram capture channel; prescription YAML and consultation logs are generated views produced by materialization. Distinct from intake (one-time athlete setup) and consult (advice within an existing plan). Requires Intervals.icu MCP and config.json configured.
+---
+
+# Set Goal
+
+## Overview
+
+Workflow for establishing a new training arc toward a new goal. An "arc" is the multi-block journey from now to a target event (or fitness-maintenance goal). Decomposes into 2-4 named sub-blocks, each with its own methodology document; prescription state lives as structured records keyed by arc and durable session id. The arc is the unit of season-level planning; sub-blocks are the unit of `adapt-plan` and `block-review`.
+
+**Authority split:** the arc-overview document and every methodology document are canonical, approved documents this skill writes itself. Prescription YAML and consultation logs are GENERATED compatibility views rendered from active Engram records by materialization — never write or edit them directly.
+
+**This skill is RIGID — phases execute in exact order. Do not skip, reorder, or combine phases.**
+
+**When to use this skill vs. others:**
+- `intake` — one-time athlete onboarding (persona, paths, season). Run once per athlete.
+- `set-goal` — recurring "what's next" planning at season transitions, post-race, or when goals change. Produces a full arc with methodology docs plus structured prescription records.
+- `consult` — advisory within an existing plan. Appends a consultation event and targeted prescription edits, not a full arc.
+- `adapt-plan` — per-session post-workout adaptation.
+
+## Workflow
+
+```dot
+digraph set_goal {
+    "Phase 1: Orient" [shape=box];
+    "Phase 2: Gather (goal+constraints)" [shape=box];
+    "Phase 3: Synthesize (arc shape + change set)" [shape=box];
+    "Phase 4: Propose (preview under one hash)" [shape=box];
+    "Athlete approves?" [shape=diamond];
+    "Phase 5: Write docs, apply hash, materialize" [shape=box];
+
+    "Phase 1: Orient" -> "Phase 2: Gather (goal+constraints)";
+    "Phase 2: Gather (goal+constraints)" -> "Phase 3: Synthesize (arc shape + change set)";
+    "Phase 3: Synthesize (arc shape + change set)" -> "Phase 4: Propose (preview under one hash)";
+    "Phase 4: Propose (preview under one hash)" -> "Athlete approves?";
+    "Athlete approves?" -> "Phase 5: Write docs, apply hash, materialize" [label="yes"];
+    "Athlete approves?" -> "Phase 3: Synthesize (arc shape + change set)" [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
+
+Do not proceed past a stop condition defined there.
+
+
+### Phase 1 — Orient _(no user input)_
+
+Read silently and announce findings before asking anything.
+
+1. **Recent block reviews** — find the most recent `SUMMARY.md` files under `{coaching_docs_dir}/{season}/*/SUMMARY.md`. Read up to 3 most recent.
+2. **Recent race reports** — find the most recent `RACE_REPORT.md` files under `{coaching_docs_dir}/{season}/races/*/RACE_REPORT.md`. Read up to 2 most recent.
+3. **Active prescription check** — read the active generated prescription view(s) under `prescriptions_dir`. Find the session with the most recent `session_date`. Note when that block ended (most recent date) and how many days have elapsed since.
+4. **Current fitness state** — call `get_fitness_summary` via Intervals.icu MCP to retrieve current CTL, ATL, TSB.
+5. **QMD history search**:
+   - `qmd query "arc planning"` and `qmd query "next block"` — surface any prior arc-planning records
+   - `qmd query "{persona} {modality}"` — surface persona-modality fit notes from ATHLETE_PROFILE
+
+Follow `${CLAUDE_PLUGIN_ROOT}/shared/retrieval.md` when constructing these — parameterize with the specifics below, and add queries for whatever this particular goal actually raises.
+
+Announce findings before Phase 2. Surface:
+- Days since last race or block-end
+- Current CTL/ATL/TSB
+- Persona-fit notes for likely-relevant modalities
+- Any prior arc-planning patterns from QMD
+
+---
+
+### Phase 2 — Gather _(one question at a time)_
+
+Ask only what cannot be inferred from the orient findings. **Ask one question at a time. Wait for each answer before asking the next.**
+
+Required information by end of Phase 2:
+
+1. **The goal.** Specific event (name + date + modality) OR fitness-maintenance goal (description + horizon).
+2. **Modality specifics.** Bike type / sport / specific equipment if relevant. Locked vs leaning.
+3. **Recovery status.** How the athlete is feeling now. Days since last race; subjective sense of readiness to start.
+4. **Calendar constraints.** Major events, vacations, work-travel, family commitments between now and the target. Both opportunities (3-day weekends, vacation that can absorb volume) and obstacles (travel that blocks training).
+5. **Time budget.** Typical training-week structure. Weekday availability, weekend long-ride capacity, non-negotiables (e.g., recurring group rides, family commitments).
+6. **Lifestyle/modality preferences.** Outdoor vs indoor preference, strong likes/dislikes, anything that should shape the prescription style.
+
+Some of these may be obvious from the Orient findings (e.g., ATHLETE_PROFILE already records modality and persona-fit). If so, confirm rather than ask blind.
+
+---
+
+### Phase 3 — Synthesize _(shown to athlete)_
+
+Reason aloud about arc shape before proposing anything. Cover:
+
+1. **Goal framing.** What the goal requires physiologically (durability, peak power, specific modality stress) and how it differs from prior goals the athlete has trained for.
+2. **Persona-fit.** Whether the active persona is the right tool for this goal. Reference ATHLETE_PROFILE persona-fit notes. If a persona change is warranted, surface it explicitly here (and recommend re-running `intake` if so).
+3. **Calendar mapping.** Map the calendar constraints from Phase 2 onto the time-to-goal window. Identify natural volume opportunities (vacations, long weekends) and structural obstacles.
+4. **Arc shape proposal — sub-block decomposition.** Propose 2-4 named sub-blocks. Each sub-block should be 1-5 weeks. Total arc length matches time-to-goal. Sub-block names should be descriptive (`reengage`, `volume`, `camp`, `taper` or `base`, `build`, `race-specificity`, `taper` — whatever fits the arc).
+5. **Modality split across the arc.** How time/volume distributes across training modalities (e.g., trainer/outdoor, ride/walk, geared/SS).
+6. **Carryover lessons.** Specifically cite ATHLETE_PROFILE entries that should shape the arc (`[race:...]`, `[block-review:...]` tags).
+7. **Key tradeoffs.** What this arc is choosing to NOT do vs. a "textbook" approach for the goal, and why those choices fit this athlete.
+
+This phase is **explanatory** about coaching reasoning — but while reasoning,
+build the complete structured change set IN PARALLEL so Phase 4 can preview it:
+
+**Durable session identity.** Generate each session's durable `session_id` ONCE
+(any stable unique slug, e.g. `ses{year}w{week}{day}`) and reuse that exact
+value in EVERY place the session appears: its prescription state item, its
+workout reference, narrative text, and the arc overview outline. The
+`session_date`, week position, title, and workout contents are MUTABLE
+attributes — rescheduling a session later changes those attributes but never
+its `session_id` or identity.
+
+**The change set.** Assemble ONE `StructuredChangeSet` covering the complete
+graph:
+
+- One prescription state item per planned session. `key_components` MUST carry
+  BOTH `arc_id` (the snake_case arc name) AND that session's durable
+  `session_id`; `details` carries the FULL prescription value for the session
+  (week, day, session date, name, modality, duration, effort zone or interval
+  structure, plus the shared arc goal object). Every session gets a complete
+  value — no placeholders to be filled in later.
+- Optionally one consultation event capturing significant goal-setting
+  reasoning that does not fit the methodology documents (the kickoff note),
+  with `action_targets` naming the affected durable session ids.
+- Explicit report claims for the conclusions embedded in the documents you are
+  about to write: one `arc-conclusion` claim anchored to the arc's first
+  prescription entity, and one `methodology-conclusion` claim per sub-block
+  anchored to a representative session of that sub-block. Each claim carries
+  its intended `source_document` path.
+
+The skill NEVER assigns record IDs, relationships (supersedes/refines/
+supports), statuses, or retirement targets — those are derived and owned by
+the pack during preview. If any session cannot be given a durable, unique
+`session_id`, stop and resolve that here; an unbound session must never reach
+Phase 4.
+
+---
+
+### Phase 4 — Propose _(requires explicit approval of ONE hash)_
+
+Convert Phase 3 reasoning into a concrete arc structure, then bind everything
+to a single approval:
+
+1. **Preview FIRST.** Before presenting anything, call `engram_capture_preview`
+   with the complete change set. The pack derives every canonical entity key,
+   reconciles against active records, and returns the exact mutation plan plus
+   its `plan_hash`.
+2. **Check the preview.** Every prescription key must be bound —
+   `prescription:{arc_id}:{session_id}` with both components present. If ANY
+   session key came back unbound or ambiguous (or the preview is blocked),
+   CORRECT THE GRAPH (fix the `session_id`s / `arc_id`) and call
+   `engram_capture_preview` AGAIN. Never ask for approval against a blocked or
+   partially-bound preview.
+3. **Present together, under one approval:**
+   - For each sub-block: **Block name** (snake_case), **Dates** (start → end),
+     **Duration in weeks**, **Intent**, **Weekly structure outline**, and
+     **Success criteria**.
+   - The proposed **Arc name**, **Goal block**, and the canonical documents to
+     be written: the arc-overview document and each methodology document.
+   - The exact record mutations from the preview: which records will be
+     created (new prescription states, the kickoff consultation event, and the
+     arc/methodology report claims).
+   - The generated compatibility-view paths materialization will produce from
+     those records (the arc's prescription view and the consultation log) —
+     presented as outputs of apply, never as files you will write by hand.
+   - The exact **plan hash**.
+4. Wait for **explicit approval, rejection, or modification**. Approval covers
+   BOTH the coaching proposal AND the record/artifact mutations under that
+   hash. Iterate: any modification returns to Phase 3 to rebuild the change
+   set, re-previews, and presents a NEW hash. Do not write any files until the
+   athlete approves the current hash.
+
+---
+
+### Phase 5 — Write canonical documents, then apply _(with approval)_
+
+Execute in this order.
+
+**1. Arc directory + canonical documents.** Create the arc directory and write
+the two kinds of CANONICAL, approved documents exactly as approved:
+
+**Arc overview doc** — `{coaching_docs_dir}/{season}/{arc_name}/arc-overview.md`
+
+Frontmatter:
+```yaml
+---
+type: arc-overview
+season: {season}
+arc: {arc_name}
+target_event: {event name}
+target_date: {date}
+modality: {modality}
+persona: {active_persona}
+---
+```
+
+Body covers:
+- Why this arc exists; what it differs from prior arcs
+- Arc shape table (sub-block / weeks / dates / intent) — reference sessions by their durable `session_id`
+- Modality split across the arc
+- Success criteria (race outcome + mid-arc fitness markers)
+- Brake signals (arc-level)
+- Carryover lessons embedded in the arc (cite ATHLETE_PROFILE tags)
+- Open questions / mid-arc checkpoints
+- File index (lists the methodology documents and notes that prescription/consultation views generate from records)
+
+**Per-sub-block methodology doc** — for each sub-block, write `{coaching_docs_dir}/{season}/{arc_name}/{sub_block_name}-methodology.md`
+
+Frontmatter:
+```yaml
+---
+type: methodology
+season: {season}
+arc: {arc_name}
+sub_block: {sub_block_name}
+dates: {start} to {end}
+duration_weeks: {N}
+---
+```
+
+Body covers:
+- Context (what state the athlete is in entering this sub-block)
+- Goal (one or two sentences)
+- Why this sub-block is shaped this way (vs. a generic approach for the same role)
+- Weekly structure pattern
+- Progression through the sub-block (if multi-week)
+- Key session rationale
+- Success criteria
+- Brake signals specific to this sub-block
+
+These documents are the skill's direct writes. Do NOT write prescription YAML
+or consultation logs — they are generated compatibility views.
+
+**2. Apply the approved hash.** Call `engram_capture_apply` with the exact
+plan hash the athlete approved. The core commits the active records, retires
+anything superseded, runs the guarded qmd refresh, and invokes the pack
+materializers, which GENERATE the prescription YAML view and the consultation
+log from the newly active records.
+
+- On success, collect the committed record IDs and the regenerated artifact
+  paths for the completion summary.
+- If the apply reports the plan as STALE (records changed after approval), do
+  not retry blindly: return to Phase 4, re-preview the same change set, present
+  the new hash, and obtain fresh approval.
+- Records commit authoritatively even if index refresh or materialization
+  hiccups; report any stale view honestly and retry apply with the SAME hash
+  if only materialization needs a rerun.
+
+**3. Completion summary** — output, with the EXACT record IDs from the applied
+plan and the EXACT generated view paths:
+
+```
+✓ Arc established: {arc_name}
+
+Target:           {event} — {date} ({modality})
+Sub-blocks:       {count} ({list of names})
+Arc dates:        {start} → {end}
+Coaching docs:    {coaching_docs_dir}/{season}/{arc_name}/
+Records created:  {committed record IDs, grouped as states/event/claims}
+Generated views:  {prescription view path}, {consultation log path}
+
+Next steps:
+  1. {first sub-block name} starts {date}
+  2. Invoke engram-coach:adapt-plan after first key session
+  3. Invoke engram-coach:consult mid-{first sub-block} for check-in (or sooner if signals diverge)
+  4. Invoke engram-coach:block-review at each sub-block boundary
+```
+
+---
+
+## Key Constraints
+
+| Rule | Detail |
+|---|---|
+| Rigid phases | Execute in order — no skipping, reordering, or combining |
+| Approval gate | Nothing written until Phase 4 explicitly approves the exact plan hash |
+| One question at a time | Phase 2 never batches questions |
+| Synthesis before proposal | Phase 3 must complete (including the change set) before Phase 4 begins |
+| Sub-block decomposition required | Never prescribe a single multi-month block. Always decompose into 2-4 named sub-blocks of 1-5 weeks each. |
+| Canonical vs generated | Arc-overview and methodology documents are canonical and written by this skill; prescription YAML and consultation logs are generated views produced only by materialization — never write or edit them directly. |
+| Durable session identity | Generate each `session_id` once; reuse it everywhere. Rescheduling mutates dates/titles, never identity. Prescription keys always carry both `arc_id` and `session_id`. |
+| One hash binds all | Documents, record mutations, and generated paths are approved together under one plan hash; a stale apply returns to Phase 4 for a fresh preview and approval. |
+| No record internals | The skill never chooses record IDs, relationships, statuses, or retirement targets — the pack derives them at preview. |
+| Persona-change escalation | If Phase 3 identifies a persona mismatch, recommend re-running `intake` before continuing. Do not silently shift persona. |
+| Knowledge compounds | Arc-overview and methodology docs are durable artifacts; structured claims and consultation events build on them. Future Orient phases benefit from the structured separation. |
+
+---
+
+## When NOT to use this skill
+
+- **For per-session adjustments** → use `adapt-plan` instead. set-goal is for arc-level planning, not session edits.
+- **For mid-arc advice without restructuring** → use `consult` instead. set-goal rewrites the arc; consult appends to it.
+- **For initial athlete onboarding** → use `intake` instead. set-goal assumes config.json + persona + paths are already set.
+- **When the existing arc is still on track** → don't run set-goal "just to refresh." Run it when the goal changes or the prior arc has concluded.

package/templates/base.md

@@ -0,0 +1,55 @@
+# Base Training Block
+
+## Block Goal
+
+Build the aerobic foundation from which all higher-intensity training is built. The primary adaptation target is maximizing mitochondrial density, fat oxidation capacity, and movement economy at low-to-moderate intensity before structured intensity work is introduced.
+
+## Physiological Adaptations Targeted
+
+- **Mitochondrial biogenesis** — increased density of mitochondria within slow-twitch muscle fibers, expanding the cell's capacity to produce ATP aerobically and reducing reliance on glycolysis at moderate intensities.
+- **Enhanced fat oxidation** — improved ability to oxidize fat as a fuel source at aerobic intensities, sparing glycogen stores and extending sustainable duration.
+- **Increased stroke volume and cardiac output** — the heart adapts to sustained aerobic demand by increasing left-ventricular volume, improving the volume of blood delivered per beat at any given heart rate.
+- **Capillary density** — growth of new capillary networks within trained muscle, improving oxygen delivery and metabolite clearance at the cellular level.
+- **Slow-twitch fiber recruitment efficiency** — the nervous system becomes more economical at recruiting Type I fibers for low-intensity work, reducing overall energy cost per unit of output.
+- **Improved movement economy** — repeated aerobic sessions at consistent intensities reinforce biomechanically efficient motor patterns, reducing the metabolic cost of movement at sub-threshold intensities.
+
+## When to Use This Block
+
+The Base block is the first structured training block following a recovery or transition period. Athletes should have a minimum baseline aerobic tolerance — capable of completing moderate-duration aerobic sessions without significant next-day fatigue — before entering a Base block. The Base block sets the aerobic ceiling for all subsequent work: a well-executed Base directly determines how much intensity load the athlete can absorb in Build 1 and beyond.
+
+## Weekly Session Pattern
+
+### Key Sessions
+
+| Session | Typical Day | Type | Purpose |
+|---------|-------------|------|---------|
+| Long Aerobic | Weekend (Sat or Sun) | Zone 2 endurance | Primary aerobic stimulus; builds duration tolerance and fat oxidation at the key adaptation intensity |
+| Moderate Aerobic | Mid-week (Tue or Wed) | Zone 2 aerobic | Volume accumulation at aerobic intensity; reinforces adaptation between long weekend sessions |
+| Optional: LT1 Assessment | Every 2-3 weeks | Sub-threshold or LT1 test | Tracks aerobic development; confirms Zone 2 targets remain calibrated to current fitness |
+
+### Supporting Sessions
+
+Recovery and easy sessions fill the remaining training days, keeping weekly volume high without adding meaningful physiological stress. The emphasis is on volume accumulation at low intensity — every easy session contributes to the aerobic base without creating fatigue that compromises key session quality. No high-intensity work (Zone 4 or above) belongs in a pure Base block. If intensity appears, it should be incidental — a brief climb on a Zone 2 ride — not prescribed.
+
+## Intensity Zone Targets
+
+| Session Type | Zone | % FTP Range | Purpose |
+|-------------|------|-------------|---------|
+| Long Aerobic | Zone 2 | 55-75% FTP | Primary aerobic base development; fat oxidation and mitochondrial stimulus |
+| Moderate Aerobic | Zone 2 | 60-75% FTP | Volume accumulation; reinforce aerobic adaptation mid-week |
+| Recovery Sessions | Zone 1 | Below 55% FTP | Active recovery; blood flow without physiological demand |
+| LT1 Assessment (if included) | Zone 3 | 75-85% FTP | Threshold measurement baseline; calibrate zone targets |
+
+## Volume Progression
+
+Base blocks typically follow a 3+1 pattern: three progressive load weeks followed by one recovery week. Volume increases 5-10% per load week, allowing the athlete's aerobic system to adapt before the next dose is applied. Intensity stays constant throughout — only volume progresses; Zone 2 remains Zone 2 regardless of the week. The recovery week reduces volume to 50-60% of the peak load week, allowing accumulated fatigue to dissipate and aerobic adaptations to consolidate before the next load cycle begins.
+
+## Common Execution Risks
+
+- **Intensity creep** — easy sessions drifting from Zone 2 into Zone 3 due to effort calibration error, ego, or terrain. Detect early by monitoring heart rate: if aerobic sessions consistently trend into Zone 3, recalibrate effort targets. Zone 2 should feel genuinely easy — conversational pace, low perceived effort.
+- **Volume ramp too steep** — increasing weekly volume faster than 10% per week accumulates fatigue faster than aerobic adaptation can occur, blunting the quality of the aerobic stimulus. Detect early by monitoring resting heart rate and subjective fatigue: if morning HR trends upward or sessions feel progressively harder at the same intensity, slow the volume ramp.
+- **Skipping the recovery week** — the recovery week is when aerobic adaptations consolidate. Athletes who extend the load phase because they "feel good" often arrive at Build 1 under-recovered, suppressing the ability to absorb the new intensity stimulus.
+
+## Signals This Block Should Produce
+
+Successful Base block adaptation is visible in the aerobic metrics over 4-6 weeks. Heart rate at a given pace or power should drift lower week-over-week as fat oxidation improves and cardiac efficiency increases — this is the primary signal that Zone 2 training is working. Perceived effort at the same intensities should decline: the same aerobic session that felt moderate in Week 1 should feel easy by Week 4. Recovery quality should improve over the block — resting heart rate trends downward or stabilizes, HRV baseline holds steady or improves. If these signals are absent after 4 weeks, review whether intensity zones are calibrated correctly and whether the recovery week was fully executed.

package/templates/build-1.md

@@ -0,0 +1,57 @@
+# Build 1 Training Block
+
+## Block Goal
+
+Introduce the first structured intensity above Zone 2, developing sub-threshold capacity — the ability to sustain efforts just below LT2 — while maintaining the aerobic base built during the Base block. Build 1 is a controlled transition from pure aerobic volume toward a blend of aerobic maintenance and structured sub-threshold work.
+
+## Physiological Adaptations Targeted
+
+- **Elevated LT2 ceiling** — structured sub-threshold intervals apply targeted stress just below the lactate threshold, progressively raising the power or pace at which lactate accumulation accelerates. A higher LT2 ceiling means more of race intensity sits below the critical threshold.
+- **Improved lactate clearance at moderate intensities** — repeated exposure to the LT1-LT2 intensity range trains the body's lactate shuttle system, improving the rate at which lactate is cleared from working muscle and recycled as fuel.
+- **Threshold power and pace economy** — sustained sub-threshold work recruits both slow-twitch and early-recruited fast-twitch fibers, improving the efficiency of fiber recruitment at moderate-high intensities and reducing oxygen cost per unit of output.
+- **Increased cardiac output at moderate-high efforts** — the cardiovascular system adapts to the higher demand of structured sub-threshold work, improving stroke volume and oxygen delivery efficiency in the Zone 3-4 range.
+- **Aerobic base maintenance** — by preserving Zone 2 volume alongside the intensity introduction, the mitochondrial and fat oxidation adaptations from the Base block are retained rather than eroded.
+- **Recovery capacity between high-demand sessions** — structured intervals and sustained recovery days teach the body to regenerate between efforts, improving inter-session recovery over the course of the block.
+
+## When to Use This Block
+
+Build 1 follows the successful completion of a Base block where the athlete has established stable Zone 2 volume tolerance and demonstrated consistent aerobic session quality. The athlete should be capable of completing multiple-hour aerobic sessions without excessive residual fatigue before sub-threshold intervals are introduced — the aerobic base is the substrate that absorbs the new intensity stimulus. Build 1 prepares the physiological system for the higher intensities of Build 2, where VO2max work or higher-density threshold work may be introduced.
+
+## Weekly Session Pattern
+
+### Key Sessions
+
+| Session | Typical Day | Type | Purpose |
+|---------|-------------|------|---------|
+| Sub-LT2 Intervals | Mid-week (Tue) | 85-92% FTP intervals | Primary intensity stimulus; develops sub-threshold capacity in a controlled, measurable format |
+| Sweet Spot / Sub-Threshold | Mid-week (Thu) | 88-93% FTP sustained efforts | Secondary intensity session; reinforces LT2 ceiling development without the recovery cost of threshold work |
+| Long Aerobic | Weekend (Sat) | Zone 2 endurance with optional surges | Builds aerobic duration tolerance and bike-specific volume; the week's highest-volume session |
+| Aerobic Endurance | Weekend (Sun) | Zone 2-3 blend | Moderate volume day that reinforces aerobic base maintenance while the intensity stimulus from the week integrates |
+
+### Supporting Sessions
+
+Recovery and easy days are placed between key sessions to allow adaptation and prevent cumulative fatigue from compounding across the week. Volume is maintained from the Base block or reduced modestly (5-10%) to accommodate the physiological cost of the new intensity work. Session spacing is deliberate: the highest-stress sessions (intervals and long aerobic) should not run on consecutive days without a recovery session separating them.
+
+## Intensity Zone Targets
+
+| Session Type | Zone | % FTP Range | Purpose |
+|-------------|------|-------------|---------|
+| Sub-LT2 Intervals | Zone 3-4 | 85-92% FTP | Sub-threshold capacity development; primary intensity stimulus |
+| Sweet Spot Efforts | Zone 3-4 | 88-93% FTP | Secondary LT2 ceiling development; physiologically efficient threshold stimulus |
+| Long Aerobic | Zone 2 | 60-75% FTP | Aerobic base maintenance; duration and fat oxidation |
+| Aerobic Endurance | Zone 2-3 | 70-82% FTP | Aerobic volume with light tempo transition; reinforces base while bridging to intensity |
+| Recovery Sessions | Zone 1 | Below 55% FTP | Active recovery; supports adaptation between key sessions |
+
+## Volume Progression
+
+Build 1 follows the same 3+1 pattern as the Base block: three progressive load weeks and one recovery week. The intensity structure holds constant while volume builds — interval sessions extend by one repetition or one to two minutes of interval duration per load week, rather than increasing zone targets. Recovery weeks reduce volume to 50-60% of the peak load week and cut one interval from each key session, allowing accumulated neuromuscular and metabolic fatigue to dissipate. The recovery week is especially important in Build 1 because the athlete is adapting to a new stimulus type, not just more volume.
+
+## Common Execution Risks
+
+- **Starting sub-LT2 intervals too aggressively** — early interval heart rate spiking above threshold (above LT2 zone) indicates the effort target is miscalibrated or residual fatigue from the Base block is higher than expected. Detect early: if RPE during the first interval set feels like a maximum effort rather than controlled hard work, reduce target power by 3-5% and extend recovery intervals before increasing volume.
+- **Neglecting Zone 2 sessions** — the aerobic base built during the Base block is what absorbs and amplifies the intensity stimulus. If Zone 2 volume is sacrificed to make room for more interval work, the foundation erodes and the interval adaptations become unsustainable. Guard Zone 2 sessions as non-negotiable; they are what makes the intervals effective.
+- **Cumulative fatigue from back-to-back intensity days** — scheduling key sessions without adequate recovery between them (e.g., sub-LT2 intervals followed directly by a long aerobic session the next day with no easy day in between) erodes rather than builds capacity. If fatigue signals appear mid-week (HRV declining over 3+ days, elevated resting HR, RPE mismatch at target intensity), convert the next key session to Zone 1 endurance and reassess.
+
+## Signals This Block Should Produce
+
+Successful Build 1 adaptation is visible in the trajectory of interval metrics across the block. RPE at the target zone (85-92% FTP) should decrease week over week for the same interval structure — what felt hard in Week 1 should feel controlled by Week 3. Heart rate drift across a multi-interval set should compress: early intervals and late intervals should show more similar HR responses as the system adapts to clearing lactate efficiently. Recovery between intervals (time to return to baseline HR) should improve over the block. HRV and resting HR should remain stable or trend positively through the load weeks — a declining HRV trend sustained over three or more days is an early signal that the intensity dose is outpacing recovery capacity and warrants backing off the next key session.

package/templates/build-2.md

@@ -0,0 +1,62 @@
+# Build 2 Training Block
+
+## Block Goal
+
+Build 2 extends the intensity developed in Build 1 to work at and above LT2. Primary goals are true threshold development — sustained efforts at LT2-adjacent intensities — and the ability to handle repeated surges above threshold within an aerobic ride context. Where Build 1 transferred and stabilized aerobic capacity, Build 2 stress-tests the ceiling that was raised.
+
+## Physiological Adaptations Targeted
+
+- **LT2 power increase (5-10W typical):** Sustained efforts at 92-100% FTP provide the specific stimulus to shift lactate threshold upward. A higher LT2 means the same absolute power represents a smaller fraction of capacity — lower lactate accumulation at any sub-threshold effort.
+- **Improved lactate buffering capacity at and above threshold:** Over-under intervals train the metabolic system to manage lactate flux — clearing during the "under" segments, accumulating during the "over" segments, and tolerating the oscillation without performance degradation.
+- **Enhanced VO2max utilization:** Threshold work operates at the upper end of the aerobic system, improving the efficiency with which the body delivers and uses oxygen at high intensities. This matters for any multi-hour effort where maintaining threshold-adjacent power is required.
+- **Ability to recover from above-threshold efforts while continuing aerobic work:** The over-under session specifically rehearses surge-and-recover dynamics. The athlete learns to produce a brief above-threshold effort and return to sub-threshold work without cumulative HR ratcheting.
+- **Muscular endurance under accumulated fatigue:** Long ride surges in the later portion of a fatigued ride train the neuromuscular system to produce structured power when glycogen is partially depleted — directly applicable to any event where the hardest moments come late.
+
+## When to Use This Block
+
+Build 2 follows Build 1 — the athlete should have stable sub-threshold aerobic capacity before moving to true threshold work. The transition signal is a consistent ability to execute Sweet Spot intervals (88-93% FTP) across multiple weeks without excessive fatigue accumulation. Build 2 is typically positioned 8-12 weeks out from the target event, providing sufficient recovery time before Race Specificity or a taper block. After Build 2, the next block is Race Specificity (for longer endurance events requiring further durability work) or a direct taper (for shorter events where the fitness ceiling is already adequate).
+
+## Weekly Session Pattern
+
+### Key Sessions
+
+| Session | Typical Day | Type | Purpose |
+|---------|-------------|------|---------|
+| Threshold Intervals | Tuesday | 92-100% FTP, sustained efforts (8-12 min) | LT2 development — accumulate time at threshold with full recovery between reps |
+| Over-Under Intervals | Thursday | 88-92% / 103-107% FTP alternating, continuous blocks (15-20 min) | Lactate clearance under varying power — teach the body to manage flux at the LT2 boundary |
+| Long Ride with Surges | Saturday | Zone 2 (60-75% FTP) base, with 15-min surges at 88-93% FTP in the final third | Muscular endurance under accumulated fatigue — structured power when pre-fatigued |
+
+### Supporting Sessions
+
+Recovery days between key sessions are more critical in Build 2 than Build 1 — over-under and threshold work produces higher metabolic stress and sympathetic nervous system activation than sub-LT2 efforts. Easy Zone 1 sessions fill remaining days; these should be genuinely easy, not moderate. The spacing logic is Tuesday hard → Wednesday easy → Thursday hard → Friday easy → Saturday hard → Sunday/Monday recovery. Compressing key sessions or turning easy days moderate will blunt the threshold adaptation and risk chronic fatigue accumulation.
+
+## Intensity Zone Targets
+
+| Session Type | Zone | % FTP Range | Purpose |
+|-------------|------|-------------|---------|
+| Threshold Intervals | Zone 4 | 92-100% FTP | LT2 development — sustained time at threshold |
+| Over-Under — "Under" segments | Zone 3 | 88-92% FTP | Partial lactate clearance while maintaining power |
+| Over-Under — "Over" segments | Zone 4-5 | 103-107% FTP | Brief lactate accumulation — train clearance response |
+| Surge Efforts (in long ride) | Zone 3-4 | 88-93% FTP | Threshold-adjacent power under accumulated fatigue |
+| Long Ride base | Zone 2 | 60-75% FTP | Aerobic substrate for the surge context; not a training stimulus on its own |
+| Recovery / Easy | Zone 1 | <60% FTP | Metabolic recovery between key sessions |
+
+**Note:** These percentages reference the athlete's own current FTP, not absolute watt values. Zones should be recalculated if FTP changes mid-block.
+
+## Volume Progression
+
+Build 2 uses a 3+1 loading pattern (three load weeks, one recovery week), but intensity is the primary driver rather than volume. Total weekly volume may increase modestly (by 5-15%) across load weeks, but the primary progression comes from increasing interval duration rather than adding more intervals. For threshold intervals, this looks like 3×8 min → 3×10 min → 3×12 min across load weeks. For over-under sets, progression is in the number of rounds: 3×15 min → 3×18 min → 3×20 min. Long ride surges increase in number and the endurance preamble extends. The recovery week drops total volume to 50-60% of peak load week volume and removes all above-threshold work — only easy Zone 1-2 riding and reduced interval volume (light threshold only, no over-unders).
+
+## Common Execution Risks
+
+- **Threshold intervals drifting above 102% FTP:** True threshold work is not VO2max training. Athletes often push above the target on short intervals because it "feels like more effort is better." At 105-110% FTP, the session becomes VO2max work with a much higher fatigue cost and a different adaptation. Pacing discipline — starting conservative and holding — matters more in Build 2 than in Build 1.
+- **Failing to respect recovery days between key sessions:** Over-under work creates cumulative fatigue that compounds without adequate recovery. The risk of turning Wednesday or Friday into a "moderate" day is not just suboptimal performance on the next key session — it's accumulated fatigue that degrades the entire block. Easy days must be genuinely easy.
+- **Using Build 2 structure too close to the target event:** The high metabolic stress of threshold and over-under work requires time to convert into performance gains. Entering Build 2 fewer than 4-5 weeks before the event leaves insufficient time for supercompensation and risks arriving at the event in a fatigued state. Build 2 should conclude at minimum 3-4 weeks before the event.
+- **Saturday long ride becoming a fatigue accumulation session rather than a structured session:** As the endurance preamble extends, there is risk of arriving at the surge block too depleted to execute meaningful work. If surge quality degrades (power falls below 82-85% FTP), shorten the endurance block by 30-60 minutes rather than completing prescribed surges at subthreshold quality.
+
+## Signals This Block Should Produce
+
+- **Stable threshold interval execution with improving HR and RPE:** By the end of the load weeks, the athlete should be completing the longest prescribed intervals (3×12 min) with HR reaching steady state within 3-4 min and RPE improving relative to early-block sessions at shorter durations. If HR is still climbing at the end of a 12-min effort, the athlete is above their true threshold.
+- **Shorter recovery time between over-under efforts:** As the block progresses, the athlete needs less recovery time between over-under sets to begin the next one. This is the primary signal of improved lactate clearance capacity — the physiological goal of the over-under sessions.
+- **Maintained or improving surge quality in the long ride:** The athlete should be able to produce surges at 88-93% FTP even after 4+ hours of Zone 2 riding. A degradation in surge quality across the block (not just day-to-day) suggests the total load is too high.
+- **Stable or improving LT2 power measured mid-block or at block end:** Whether assessed via lactate test, 20-min field test, or ramp test, FTP should be equal to or greater than entry values by the end of Build 2. A flat FTP with improved execution feel is also a positive signal — not all adaptation registers on a test.

package/templates/race-report.md

@@ -0,0 +1,51 @@
+# {Event Name} — Race Report
+**Date:** {YYYY-MM-DD}  **Persona:** {active_persona}  **Block context:** {ending block name}
+**Result:** {finishing time / position / outcome — from athlete}
+**Goal:** {original goal for the race — from intake or athlete}
+
+## Race Context
+{distance, elevation gain, weather, course type — from race-context tool. If weather is null, write "weather data not available for this activity".}
+
+## Performance Summary
+| Metric | Value | Notes |
+|---|---|---|
+| Duration | | |
+| NP / Avg watts / VI | | |
+| Avg HR / Max HR | | |
+| Decoupling | | (or "not computed — duration <45min") |
+| Fade (NP slope per hour) | | |
+
+## Pacing & Fade by Segment
+{Render fade.segments table — columns: label, NP, avg HR, EF, duration_sec.}
+{Narrative: where the largest_drop occurred and what likely caused it. Reference the segment label, not "second half".}
+
+## Time in Zone
+{Render time_in_zone.zones table — columns: zone, pct, seconds.}
+{Narrative: was distribution consistent with the race plan? Reference the prescription's target zones if available.}
+
+## Lap-by-Lap
+{If the activity has laps, render the full lap_trends.laps table — columns: n, sec, avg_w, np, avg_hr, max_hr, is_rest. Do NOT truncate.}
+{Lap-trends summary: power_slope_w_per_lap, hr_drift_bpm_per_lap, fastest_lap, slowest_lap, first/middle/last third averages, regime_breaks.}
+{If no laps in the activity, write "Continuous-effort event — no lap markers." and skip the section.}
+
+## Comparison to Race-Specificity Sims
+{If sim_compare.comparisons is non-empty, render table — columns: sim_date, np_delta_pct, hr_delta_bpm, decoupling_delta_pct, duration_delta_min.}
+{Narrative: did sims predict the race? Where did execution diverge most?}
+{If empty, write "No race-specificity sims found in preceding 6 weeks."}
+
+## Surge Response
+{Render hr_recovery.intervals if present: index, end_hr, drop_60s, drop_120s. Plus the trend.}
+{Narrative: how surge recovery compared to past races / late-block sims.}
+
+## Fueling & Hydration
+{Athlete-provided timeline from Phase 3 question 1 — render as a list with approximate times and intake.}
+{Correlation note: if specific fueling gaps align with fade segments or HR drift, call it out explicitly.}
+
+## Race Intent vs Execution
+{From Phase 3 question 2 — what was the plan, where it held, where it deviated, and why.}
+
+## Athlete Perspective
+{Narrative from Phase 3 questions 3-5 — where it got hard, surprises, off-record context. Written in athlete's voice.}
+
+## Calibration Points for Future Blocks
+{LLM-extracted bullets, 3-7 items max. Each is a durable, queryable lesson — e.g., "fueling protocol of 90g carb/hr validated up to 7h race duration". These are passed verbatim to lessons-rollup.}

package/templates/race-specificity.md

@@ -0,0 +1,62 @@
+# Race Specificity Training Block
+
+## Block Goal
+
+Race Specificity is the final intensity block before a competition taper. The goal is to rehearse and validate race-pace efforts — the athlete should complete this block able to sustain target race intensity for the expected event duration, with evidence that training adaptations are translating to race-ready performance. Unlike Build 1 and Build 2, which develop and stress-test the fitness ceiling, Race Specificity operates under that ceiling: consolidating, validating, and building confidence rather than introducing new stimuli.
+
+## Physiological Adaptations Targeted
+
+- **Race-pace economy and efficiency:** Extended efforts at race-relevant power zones train the neuromuscular and metabolic systems to operate efficiently at the specific intensities the event demands. This is not about raising the ceiling — it is about maximizing how much of the ceiling the athlete can access on race day.
+- **Pacing strategy rehearsal and calibration:** The athlete develops and validates their internal sense of sustainable race effort through repeated practice at target power/pace. By the end of the block, race pace should feel "moderate and controlled" rather than effortful.
+- **Event-specific fueling calibration:** Race Specificity sessions are long enough to require real fueling protocols. The block is the last opportunity to confirm that nutrition and hydration strategies work across the full anticipated event duration without GI distress or energy deficits.
+- **Neuromuscular pattern consolidation at race effort:** Repeated execution of race-specific movement patterns (power output, cadence, pacing rhythm, surge-and-recover dynamics) at the right intensity consolidates those patterns. The athlete arrives at the event with practiced, not improvised, race skills.
+- **Durability validation — sustained power in the final hours:** Structured work embedded in long race-simulation efforts proves that fitness built in earlier blocks survives under accumulated fatigue. This is both a physiological confirmation and a psychological one.
+
+## When to Use This Block
+
+Race Specificity follows Build 2 when threshold power and sub-threshold aerobic capacity are established and stable. The prerequisite is demonstrated recovery from the metabolic debt of Build 2 — if the athlete is still fatigued from threshold work, race-pace execution will be compromised and the block's validation purpose is undermined. Race Specificity is typically positioned 4-8 weeks before the target event depending on event distance: shorter events (under 4 hours) may need only 2-3 weeks of specificity work; longer endurance events (8+ hours) may need 3-4 weeks to accumulate sufficient simulation volume. After Race Specificity comes a taper block — NOT another build. The athlete should not attempt to add fitness after Race Specificity begins.
+
+## Weekly Session Pattern
+
+### Key Sessions
+
+| Session | Typical Day | Type | Purpose |
+|---------|-------------|------|---------|
+| Tempo-Threshold Maintenance | Tuesday | Extended continuous efforts at 88-95% FTP (20-35 min) | Retain threshold sharpness while shifting toward sustained sub-threshold intensities |
+| Race-Pace Simulation with Embedded Surges | Thursday | 60-90 min at target race intensity (70-82% FTP for endurance events) with brief above-threshold surges every 15-20 min | Rehearse actual race rhythm — sustained moderate power punctuated by terrain-driven surges |
+| Event-Distance Long Effort | Saturday | Approaching event duration at race pace, with structured surges in the later portion | Durability validation — the primary proof-of-fitness session for the block |
+
+### Supporting Sessions
+
+Recovery days are critical in Race Specificity — the block involves high-quality execution at near-race intensities, and the athlete must arrive at each key session with sufficient freshness to execute at race pace. Easy sessions between key sessions should be genuinely Zone 1-2, not moderate — this is not the time to add volume on recovery days. The pattern of hard-easy-hard-easy-long-recovery is more important in Race Specificity than in any prior block because fatigue carryover directly compromises the simulation quality that the block is designed to produce.
+
+## Intensity Zone Targets
+
+| Session Type | Zone | % FTP Range | Purpose |
+|-------------|------|-------------|---------|
+| Tempo-Threshold Maintenance | Zone 3-4 | 88-95% FTP | Retain LT2 sharpness without introducing new threshold stress |
+| Race Simulation (endurance events) | Zone 2-3 | 65-82% FTP | Race-pace rehearsal — the intensity the athlete will sustain for most of the event |
+| Race Simulation (shorter/intensity events) | Zone 3-4 | 78-92% FTP | Race-pace rehearsal at higher sustained effort |
+| Embedded Surges | Zone 4-5 | 95-107% FTP | Brief terrain-simulating efforts within race-pace context |
+| Long Effort base | Zone 2 | 65-75% FTP | Aerobic endurance foundation for structured work embedded later |
+| Recovery / Easy | Zone 1 | <60% FTP | Genuine recovery between key sessions |
+
+**Note:** Exact zone targets depend on event type. Shorter events with higher sustained intensities emphasize the upper end of each range; longer endurance events emphasize the lower end at higher volume. These percentages reference the athlete's own current FTP.
+
+## Volume Progression
+
+Race Specificity is not a progressive volume block. Total weekly volume stays roughly constant or slightly decreases across the 2-4 week block while race-pace quality is maintained or improved. The goal is freshness plus specificity, not accumulation — adding volume during Race Specificity risks arriving at the event fatigued from training rather than primed. The primary progression across load weeks is the duration of the Saturday event-distance long effort, which builds toward the longest simulation session of the entire plan. By the final load week, the athlete completes their longest race-simulation effort (the validation session). After that, volume drops sharply as the taper begins — typically a 40-50% reduction in the first taper week.
+
+## Common Execution Risks
+
+- **Turning Race Specificity into more Build 2:** Pushing intensity above race pace or adding threshold intervals "for extra fitness" when the block goal is specificity and confidence, not a new fitness ceiling. The physiological ceiling was built in Build 1 and 2. Race Specificity operates under it — any session that feels like threshold development is a sign the athlete is executing the wrong block.
+- **Fatigue carryover from Build 2:** Entering Race Specificity before recovering from the metabolic debt of threshold and over-under work. Symptoms include poor race-pace execution in early simulation sessions, elevated RPE at moderate intensities, and difficulty completing the prescribed surge structure. If these signs appear, a brief consolidation period (3-5 days of easy riding) before beginning Race Specificity is preferable to executing a compromised block.
+- **Over-relying on HR as a Race Specificity pacing marker:** Race-pace HR for longer endurance events will be meaningfully lower than threshold HR. Using threshold HR targets in simulation efforts creates pacing errors — the athlete either over-rides early (chasing a too-high HR target) or interprets the lower HR as underperformance and pushes harder than intended. RPE and power are more reliable pacing anchors in race simulation sessions.
+- **Over-executing the event-distance long effort:** Riding significantly beyond the planned duration, or attacking surges too hard, creates fatigue that compromises the taper window. The goal is to finish the long effort feeling "I could have continued" — that feeling is the signal you want to carry into the taper. Finishing wrecked produces no additional fitness benefit and risks a compromised taper.
+
+## Signals This Block Should Produce
+
+- **Race-simulation efforts feel increasingly controlled and sustainable:** Not easier — controlled. The athlete is not getting fitter during Race Specificity; they are getting more efficient at race pace. A consistent "hard but controlled" (7/10 RPE) feel that does not worsen across weeks is the signal. If race-pace efforts feel easier at week 3 than week 1, that is a sign of full absorption from Build 2.
+- **Improved pacing execution across the block:** Smaller power variance between effort segments, better surge-and-return timing, and improved ability to predict finishing time based on effort. By the final simulation session, the athlete should know their sustainable race pace with high confidence.
+- **Fueling and hydration strategies tested and confirmed:** No GI distress, no energy deficits, no unexpected fueling failures across long simulation sessions. The athlete arrives at the event having validated their entire nutrition protocol under race-like conditions.
+- **Athlete arrives at taper feeling race-ready, not depleted:** The defining signal of a well-executed Race Specificity block is the athlete who enters the taper with a sense of readiness — evidence from simulation sessions that race demands are within reach — rather than relief that training is over. Entering the taper depleted indicates the block was over-prescribed or the athlete over-executed.