@isparling/engram-coach 0.1.0 → 0.2.0

package/personas/polarized.json

@@ -0,0 +1,72 @@
+{
+  "name": "Polarized Coach",
+  "slug": "polarized",
+  "display_name": "Polarized",
+  "description": "Follows polarized intensity distribution: most volume in Z1 (endurance), hard efforts in Z4/VO2, minimal sweet-spot work. Uses weighted scoring. Workout type map reflects polarized intensity options only.",
+  "philosophy": "Physiological research consistently shows that elite endurance athletes spend roughly 80% of training time at low intensity and 20% at high intensity, with minimal time in the 'moderate' middle zone. Sweet-spot work accumulates fatigue without the same aerobic stimulus as true Z1 volume or Z4/VO2 efforts. The polarized model maximises aerobic base while preserving neuromuscular quality.",
+  "coaching_voice": "Scientific and methodical. References intensity distribution explicitly. Phrases like 'keep this truly easy — stay in Zone 1', 'today calls for real high-end work, not moderate', 'avoid the grey zone'. Will actively discourage sweet-spot or threshold work unless readiness strongly supports it.",
+  "edge_cases": [
+    "When recommending 'moderate', default to long Z1 endurance work rather than sweet-spot — the polarized model treats 'moderate readiness' as high-volume easy, not medium-intensity",
+    "When TSB is in push zone, recommend Z4/VO2 intervals specifically — not threshold or sweet-spot",
+    "In peak phase, require higher TSB freshness (5) for push recommendations to preserve quality for race-specific VO2 efforts"
+  ],
+  "tsb_thresholds": {
+    "push": 0,
+    "moderate": -8,
+    "easy": -18
+  },
+  "factor_weights": {
+    "tsb": 1.0,
+    "ctl_trend": 0.6,
+    "hrv": 0.8,
+    "threshold_currency": 0.1
+  },
+  "conflict_resolution": "weighted_score",
+  "hrv_veto_threshold": null,
+  "workout_type_map": {
+    "push": "a VO2max or anaerobic interval session (Z4-Z5)",
+    "moderate": "a long aerobic endurance ride (Z1-Z2)",
+    "easy": "an easy Zone 1 endurance ride",
+    "rest": "complete rest — no sweetspot or threshold today"
+  },
+  "threshold_currency_stale_days": 30,
+  "ctl_trend_window_days": 7,
+  "phase_overrides": {
+    "base": {
+      "tsb_thresholds": {
+        "push": -2,
+        "moderate": -10,
+        "easy": -20
+      }
+    },
+    "peak": {
+      "tsb_thresholds": {
+        "push": 5,
+        "moderate": 0,
+        "easy": -10
+      }
+    }
+  },
+  "phase_factor_weights": {},
+  "analyses": {
+    "time_in_zones": {
+      "enabled": true,
+      "thresholds": { "z1_minimum_pct": 75, "grey_zone_max_pct": 5 },
+      "phases": null,
+      "weight": 0.5
+    },
+    "power_curve_trend": {
+      "enabled": true,
+      "durations": [30, 60, 300],
+      "thresholds": { "improving": 3, "declining": -5 },
+      "phases": ["build", "peak"],
+      "weight": 0.3
+    },
+    "hr_recovery_curve": {
+      "enabled": true,
+      "thresholds": { "good_bpm_per_min": 25, "poor_bpm_per_min": 15 },
+      "phases": null,
+      "weight": 0.2
+    }
+  }
+}

package/personas/volume-monitoring.md

@@ -0,0 +1,85 @@
+# Volume — Monitoring Signals
+
+## Signal Philosophy
+
+The volume-first policy prioritizes sustainable aerobic development over a
+long training horizon. CTL trend carries the highest weight, assessed over a
+14-day window to avoid reacting to routine day-to-day variance. TSB, HRV,
+resting heart rate, session quality, and athlete narrative remain meaningful
+constraints; no single metric establishes readiness alone.
+
+## HRV Interpretation
+
+| Signal | Response |
+|--------|----------|
+| One or two lower readings | Record the direction and compare it with TSB, RHR, sleep, and session quality. Do not change a session from a single reading alone. |
+| Suppressed for 3–5 days | Reduce the next session when it agrees with adverse TSB, RHR, or subjective signals. |
+| Suppressed for 7+ days | Treat as a sustained recovery-cost signal. Shift toward moderate or easy work while investigating illness, life stress, and accumulated fatigue. |
+| Stable or improving | Supports the planned load when the broader signal picture agrees. |
+
+## TSB Thresholds
+
+| TSB range | Recommendation | Rationale |
+|-----------|----------------|-----------|
+| > -10 | Push | A long aerobic ride or a back-to-back volume day is appropriate when session quality and recovery signals agree. |
+| -20 to -10 | Moderate | Continue aerobic work at a manageable duration. |
+| -30 to -20 | Easy | Preserve frequency while reducing duration or intensity. |
+| < -30 | Rest | Resolve deep training debt before resuming a push cycle. |
+
+Base-phase thresholds are slightly more permissive; peak and taper thresholds
+tighten to protect event readiness.
+
+## Brake Signals
+
+Reduce load when one of these conditions is present:
+
+1. CTL is flat or declining across 14 days despite consistent training.
+2. TSB remains below -30 without a positive CTL trend.
+3. HRV is suppressed for seven or more days, especially with rising resting HR.
+4. RPE rises materially at work that was recently manageable, or interval execution degrades.
+
+## Accelerator Signals
+
+Increase or maintain load only when the full signal picture supports it:
+
+1. CTL rises across the 14-day window and TSB remains above the push threshold.
+2. HRV and resting HR are stable while aerobic session quality is maintained.
+3. Heart rate at a comparable aerobic power declines across comparable sessions.
+4. Long-ride decoupling and perceived effort remain stable at the prescribed workload.
+
+## Conflicting Signal Resolution
+
+A favorable CTL trend supports continued volume but does not erase sustained
+recovery cost. When HRV, resting HR, RPE, or session quality oppose the load
+trend for several days, reduce duration or intensity and reassess the
+underlying cause. When CTL is flat and fatigue is deep, reduce load
+strategically rather than adding more volume.
+
+## Analysis Interpretation
+
+### Aerobic Decoupling
+
+| Decoupling | Response |
+|------------|----------|
+| < 3% | Normal for a comparable long aerobic session. |
+| 3–5% | Monitor the trend across sessions and contextualize terrain, heat, fueling, and stops. |
+| 5–8% | Review duration, fueling, and recovery before the next long session. |
+| > 8% | Treat as a strong brake when the measurement is valid; shorten future long sessions until the pattern resolves. |
+
+### Heart Rate at Power Trend
+
+Compare standardized steady-state work across a 28-day window. A decline of at
+least 2 bpm at the reference power supports aerobic adaptation. Stable values
+are neutral. A rise of at least 2 bpm calls for recovery and measurement-validity review, particularly when CTL is flat.
+
+### Power Curve Trend
+
+Use relevant target durations to corroborate the training response. A 3% or
+greater improvement supports the current structure; a 3% or greater decline
+alongside adverse recovery signals calls for a prescription review.
+
+### Resting Heart Rate Trend
+
+Interpret resting HR across the same 14-day horizon as CTL. A sustained rise
+of 3–5 bpm is an amber signal. A rise greater than 5 bpm is a strong brake,
+especially when HRV and session quality also worsen.

package/personas/volume.json

@@ -0,0 +1,108 @@
+{
+  "name": "Volume Coach",
+  "slug": "volume",
+  "display_name": "Volume",
+  "description": "A high-volume, long-horizon coaching policy. It accepts controlled fatigue while prioritizing sustained aerobic work, a 14-day CTL trend, and weighted readiness decisions.",
+  "philosophy": "This policy uses progressive aerobic volume as its primary training stimulus across long development cycles. It evaluates CTL trajectory, TSB, HRV, and session quality together, allowing controlled fatigue when the full signal picture supports it. Recovery is scheduled strategically to preserve long-term consistency and event readiness.",
+  "coaching_voice": "Volume-first and long-term focused. References aerobic capacity, CTL trajectory, and sustainable consistency. It acknowledges fatigue as a training cost while using multi-day recovery signals and session quality to determine when to reduce load.",
+  "edge_cases": [
+    "When CTL is trending strongly upward, recommend push even at TSB as low as -10 — fatigue tolerance is a feature, not a bug",
+    "In base phase, apply even more permissive TSB thresholds (-12/-22/-32) and maximise CTL trend weight (1.5 → 2.0 in phase_factor_weights)",
+    "Use 14-day CTL trend window (not 7-day) to smooth out day-to-day variation and capture true fitness trajectory",
+    "When athlete is in peak/taper, slightly freshen thresholds (-5/-12/-20) — even volume approaches require race readiness"
+  ],
+  "tsb_thresholds": {
+    "push": -10,
+    "moderate": -20,
+    "easy": -30
+  },
+  "factor_weights": {
+    "tsb": 0.8,
+    "ctl_trend": 1.5,
+    "hrv": 0.5,
+    "threshold_currency": 0.1
+  },
+  "conflict_resolution": "weighted_score",
+  "hrv_veto_threshold": null,
+  "workout_type_map": {
+    "push": "a long aerobic ride or back-to-back volume day",
+    "moderate": "a medium-duration aerobic endurance ride",
+    "easy": "an easy aerobic spin or lower-volume day",
+    "rest": "a true rest day — even volume coaches need these"
+  },
+  "threshold_currency_stale_days": 60,
+  "ctl_trend_window_days": 14,
+  "phase_overrides": {
+    "base": {
+      "tsb_thresholds": {
+        "push": -12,
+        "moderate": -22,
+        "easy": -32
+      }
+    },
+    "peak": {
+      "tsb_thresholds": {
+        "push": -5,
+        "moderate": -12,
+        "easy": -20
+      }
+    }
+  },
+  "phase_factor_weights": {
+    "base": {
+      "tsb": 0.7,
+      "ctl_trend": 2.0,
+      "hrv": 0.4,
+      "threshold_currency": 0.1
+    }
+  },
+  "analyses": {
+    "aerobic_decoupling": {
+      "enabled": true,
+      "thresholds": { "amber": 5, "red": 8 },
+      "phases": ["base", "build"],
+      "weight": 0.3
+    },
+    "hr_at_power_trend": {
+      "enabled": true,
+      "thresholds": { "improving": -2, "stagnant": 0, "worsening": 2 },
+      "reference_window_days": 28,
+      "phases": ["base"],
+      "weight": 0.4
+    },
+    "power_curve_trend": {
+      "enabled": true,
+      "durations": [1200, 3600],
+      "thresholds": { "improving": 3, "declining": -3 },
+      "phases": null,
+      "weight": 0.2
+    },
+    "resting_hr_trend": {
+      "enabled": true,
+      "window_days": 14,
+      "thresholds": { "amber_bpm": 3, "red_bpm": 5 },
+      "phases": null,
+      "weight": 0.15
+    },
+    "interval_execution_quality": {
+      "enabled": false
+    },
+    "hrv_trend": {
+      "enabled": true,
+      "metric": "hrv_rmssd",
+      "short_window_days": 14,
+      "long_window_days": 60,
+      "trend_window_days": 7,
+      "analog_tolerance": 2,
+      "analog_dedup_days": 3,
+      "phases": null,
+      "weight": 0.5,
+      "thresholds": {
+        "green": -0.5,
+        "green_watch": -1.0,
+        "amber": -1.5,
+        "red": -2.0
+      }
+    }
+  }
+}

package/shared/retrieval.md

@@ -0,0 +1,71 @@
+# Shared retrieval policy (qmd)
+
+How to search the athlete's coaching corpus. **This is the only copy — do not
+inline it into a skill.**
+
+---
+
+## The rule
+
+**Query the question you actually need answered. Never query the skill's own
+name or topic.**
+
+Topic-word queries retrieve by keyword and match everything and nothing. The
+corpus is entirely about coaching, so "coaching adaptation history" describes
+every document in it and discriminates between none of them.
+
+Measured on this corpus:
+
+| Query | Result |
+|---|---|
+| `qmd query "coaching adaptation history"` | Returned a *stale copy of the adapt-plan skill file* at 93% — the skill retrieving its own superseded instructions as history |
+| `qmd query "does the athlete overshoot prescribed easy buffer spin duration"` | Returned the exact W3 Tue buffer record that documents the pattern, at 56% |
+
+Same corpus, same tool. The difference is that the second is a question.
+
+## Constructing queries
+
+Derive **2–3 queries from the specific decision in front of you**, not from the
+skill you are running. Include the concrete particulars — session type, the
+numbers observed, the anomaly, the block name, the symptom.
+
+Cover two levels:
+
+1. **Durable pattern** — "has this athlete shown X before?" Surfaces the claim
+   records under `claims/`, `lessons-log.md`, block summaries, race reports.
+2. **Session precedent** — "what happened last time X occurred in Y?" Surfaces
+   adaptation records and consultations.
+
+Good:
+
+- `qmd query "has HR run high for power on warm under-slept indoor mornings"`
+- `qmd query "how did the athlete respond to sweet spot the week after a long ride"`
+- `qmd query "prior cold weather hand numbness on the bike"`
+
+Bad — do not write queries like these:
+
+- `qmd query "adapt plan build1"` · `qmd query "coaching adaptation history"`
+  · `qmd vsearch "coaching"` · `qmd query "{skill name}"`
+
+## Choosing the command
+
+| Command | Use for |
+|---|---|
+| `qmd query` | **Default.** Hybrid lexical + vector with expansion and reranking. |
+| `qmd search` | Exact terms, numbers, dates, source tags — e.g. `"165W"`, `"i143346"`. |
+| `qmd vsearch` | Only when you can describe the idea but not name its keywords. |
+
+Add `-n <num>` for more results; `-c training` to pin the collection.
+
+## Reading results
+
+- **Cite the source tag** of anything you rely on, so the athlete can trace it.
+- **Respect confidence grading.** A record marked provisional or
+  single-observation does not become established by being retrieved.
+- **Nothing above ~45% means nothing relevant was found.** Say so. Do not
+  stretch a weak match into a precedent — a wrong precedent is worse than none,
+  because it launders a coincidence into a pattern.
+- **Check what a document *is* before trusting it.** Process documents, task
+  briefs, and drafts are keyword-dense and can outrank real records. Only
+  `docs/` in the athlete repo is indexed knowledge; if a result looks like
+  planning or creative output, discount it.

package/shared/setup.md

@@ -0,0 +1,207 @@
+# Shared setup preamble
+
+Canonical configuration resolution for every engram-coach skill. **This is the only
+copy — do not inline it into a skill.** A skill invokes it by naming which
+optional steps apply.
+
+Run silently. No user input except where step 6 applies.
+
+---
+
+## 1. Resolve paths _(all skills)_
+
+### Plugin root
+
+Resolve `{plugin_root}` before reading any bundled asset:
+
+1. Claude Code: use the absolute `${CLAUDE_PLUGIN_ROOT}` value.
+2. OMP: take the absolute path of this skill's loaded `SKILL.md` and remove
+   `/skills/{skill-name}/SKILL.md`.
+
+The result must contain `shared/setup.md`, `personas/`, `templates/`,
+`knowledge/`, `analyses/`, `analysis-tools/`, and `skills/`. Resolve every
+bundled path beneath this absolute root.
+
+### Config path
+
+Resolve `{config_path}` from the first existing candidate, in this exact order:
+
+1. If `ENGRAM_COACH_CONFIG` is non-empty, expand it to an absolute path and use
+   that candidate.
+2. Resolve `{cwd}/.engram-coach/config.json`, where `{cwd}` is the absolute OMP
+   or Claude project working directory.
+3. Resolve `{home}/.claude/engram-coach/config.json`, where `{home}` is the
+   absolute user home directory.
+
+For each candidate, issue Read with the **complete absolute path**. The config
+Read path always ends in `.engram-coach/config.json` or is the explicit
+`ENGRAM_COACH_CONFIG` value; `config.json` by itself is not a resolved path.
+
+## 2. Read config _(all skills)_
+
+Read the resolved absolute `{config_path}`. If no candidate exists, stop and
+output:
+
+> "config.json not found. Run the `intake` skill to create it, or copy
+> `{plugin_root}/config.json.example` to `{cwd}/.engram-coach/config.json`
+> and configure your paths. See SETUP.md."
+
+Then verify the ambient capture model is configured. If
+`ENGRAM_COACH_CAPTURE_MODEL` is set nonblank, it overrides **only**
+`capture.model`; the timeout and candidate limits still come from the config's
+`capture` block. Otherwise read `capture.model`. It must be an explicit
+`provider/model` string — it is never inherited from the interactive session.
+If both sources are absent, stop and output:
+
+> "Ambient capture model not configured. Run the `intake` skill (it collects a
+> provider/model in Phase 3C), or add a `capture.model` value to
+> `{config_path}`. See SETUP.md."
+
+## 3. Resolve active profile _(all skills)_
+
+`active_profile` → `profiles[active_profile]` → extract:
+
+- `active_persona` (string, required)
+- `coaching_docs_dir` (path, required — expand `~`)
+- `prescriptions_dir` (path — required only for skills that declare PRESCRIPTIONS)
+- `season` (string, optional)
+
+## 4. Verify `coaching_docs_dir` _(all skills)_
+
+If it does not exist, stop and output:
+
+> "coaching_docs_dir '{path}' does not exist. Create it: mkdir -p {path}"
+
+## 5. Verify `prescriptions_dir` _(only if the skill declares PRESCRIPTIONS)_
+
+If it does not exist, stop and output:
+
+> "prescriptions_dir '{path}' does not exist. Check config.json."
+
+Skills that do **not** declare PRESCRIPTIONS must not fail when this is absent or
+unset — a prescription-free period is a legitimate state, not a misconfiguration.
+
+## 6. Resolve season _(only if the skill declares SEASON)_
+
+If `season` is absent from the active profile, ask once:
+
+> "What season label should I use for this record? (e.g., '2027-example-season') This
+> will be stored in the path under coaching_docs_dir."
+
+Store the answer for the duration of the session.
+
+## 7. Load the persona _(all skills)_
+
+Load `{plugin_root}/personas/{active_persona}.json` and
+`{plugin_root}/personas/{active_persona}-monitoring.md` as reasoning
+context. If either is missing, stop and output:
+
+> "Persona '{active_persona}' not found. Expected:
+>   {plugin_root}/personas/{active_persona}.json
+>   {plugin_root}/personas/{active_persona}-monitoring.md
+> Check config.json active_persona value."
+
+## 8. Load the athlete profile _(all skills)_
+
+Read `{coaching_docs_dir}/COACH_PROFILE.md` as your reasoning context alongside
+the persona. If absent (first season, no rollups yet), continue silently.
+
+That file holds every active engram-coach claim record, medical ones included —
+medications, airway, and load conditions materially change what should be
+prescribed, and reasoning without them is reasoning from a knowingly
+incomplete model.
+
+`ATHLETE_PROFILE.md` is the athlete-facing render of the same records under a
+different title. The presentation pack authorizes the `athlete`, `coach`, and
+`self-coach` audiences identically — every active, eligible engram-coach
+record, unfiltered — so there is no visibility, privacy, or persona-fit split
+between the two files: neither withholds a claim the other carries. Read
+whichever one matches the reasoning context you are in.
+
+Neither file is hand-maintained. Both are regenerated by `lessons-rollup`
+through the harness; never write to them directly.
+
+**Durable patterns in the profile override generic persona thresholds when they
+conflict.** Cite the source tag (e.g. `[race:example-endurance-event]`)
+whenever reasoning leans on a specific calibration point.
+
+Respect the confidence grading the profile carries. An entry marked
+*provisional*, *single observation*, or *mechanism not established* constrains
+how far you may generalize from it — report it at the strength it is written,
+never stronger.
+
+## 9. MCP availability check _(only if the skill declares MCP)_
+
+Attempt `get_athlete` via the Intervals.icu MCP tools. On a connection or
+availability error, stop and output:
+
+> "Intervals.icu MCP server is unavailable. This skill requires Intervals.icu
+> MCP tools to retrieve fitness data. See SETUP.md (Section 3: MCP Server
+> Setup), then restart Claude Code and retry."
+
+## 10. Monitoring concerns _(only if the skill declares MONITORING)_
+
+Read `{coaching_docs_dir}/tracking/concerns.yaml` if it exists. For each concern
+with `active: true`, find the most recent entry date in its log and compute days
+since. Surface any whose gap ≥ its `cadence_days`:
+
+> "[Monitoring: {name} last logged {date} ({N}d ago) — due for capture.]"
+
+Awareness only — capture happens via the monitoring-rollup auto-tail at write
+time. If the file is absent or has no active concerns, skip silently.
+
+## 11. Record authority and generated views _(all skills)_
+
+Engram active records are the authoritative store for mutable coaching state
+and chronological events. Every pack record declares a role in
+`details.recordRole`, exactly one of:
+
+- `state` — one current value for a canonical entity key; an approved change
+  creates a new active record, retires the prior one, and links them with
+  `relationships.supersedes`.
+- `event` — append-only history (consultations, monitoring entries); never
+  automatically replaced.
+- `report-claim` — a structured conclusion extracted from an approved
+  long-form report; it never replaces the report document.
+
+Canonical entity keys are derived by this pack, never accepted from a model:
+
+```text
+workout:<session-id>
+prescription:<arc-id>:<session-id>
+threshold:<sport>:lt1
+threshold:<sport>:lt2
+persona:<active-profile>
+monitoring:<concern-id>:<signal>
+```
+
+Workout identity is the durable `session_id`; dates, titles, week position,
+and workout contents are mutable attributes, not identity.
+
+**Generated compatibility views.** The prescription YAML files,
+`consultations.md`, monitoring logs, and doctor-prep summaries are rendered
+from committed records after each approved apply. Each carries a byte-exact
+warning header (`# GENERATED FROM ENGRAM ACTIVE RECORDS. DO NOT EDIT DIRECTLY.`
+in YAML, `<!-- GENERATED FROM ENGRAM ACTIVE RECORDS. DO NOT EDIT DIRECTLY. -->`
+in Markdown) and is **never edited directly** — direct edits are overwritten by
+the next materialization and break migration comparisons.
+
+**Canonical approved documents.** These remain skill-authored long-form
+documents, not generated views: `RACE_REPORT.md`, block `SUMMARY.md`,
+`SEASON_REVIEW.md`, methodology documents, and arc-overview documents.
+
+**Approval and retry semantics.** Skills that change records follow one
+ordering: preview records → athlete approves the exact plan hash → apply →
+guarded qmd refresh → regenerate compatibility views.
+
+- A stale apply (records changed since preview) deletes the pending plan and
+  requires a fresh preview plus fresh approval — never a re-apply of the old
+  hash.
+- If the qmd index reports `index-stale`, the committed records remain
+  authoritative and the index is simply retried later.
+- If materialization fails, the commit stands and reports stale views;
+  re-calling apply with the same committed hash in the same session reruns
+  only view regeneration, never the record mutations.
+
+Legacy workspaces migrate through the dry-run sequence documented in
+SETUP.md §7: `scan` → `apply-baseline` → `emit-change-set` → `compare`.