@isparling/engram-coach 0.1.0 → 0.2.0

package/skills/lactate-analyze/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: lactate-analyze
+description: Query lactate analysis results for an athlete. Use this when you need LT1/LT2/FTP/FTHR values and their confidence intervals for training decisions. Also use when analyzing spot test results or comparing to historical tests.
+---
+
+# Lactate Analysis
+
+## Overview
+
+This skill provides access to the lactate analysis subsystem for querying threshold values, FTP/FTHR estimates, and spot test analysis. Engram Coach uses this during Orient phase to inform training decisions.
+
+## Data Flow
+
+```
+Prescription YAML (spot test orders)
+         │
+         ▼
+   Athlete performs test
+         │
+         ▼
+   lactate import (CLI)
+         │
+         ▼
+   Analysis Engine (multiple methods + CI)
+         │
+         ▼
+   Results stored in JSON
+         │
+         ▼
+   lactate query (CLI or API)
+         │
+         ▼
+   Engram Coach adapts training
+```
+
+## Usage
+
+### Import Ramp Test Data
+
+```bash
+cd lactate
+npm install
+npm run build
+
+# Import a ramp test from CSV
+lactate import -f /path/to/test.csv -t ramp -d 2026-03-01 -s cycling
+
+# CSV format:
+# power,heartrate,lactate
+# 150,120,1.2
+# 175,135,1.5
+# 200,150,2.1
+# ...
+```
+
+### Query Latest Analysis
+
+```bash
+lactate query --latest
+lactate query --latest --compare  # Compare to previous test
+```
+
+### Query via API (for Engram Coach integration)
+
+```typescript
+import { createLactateAPI } from './lactate';
+
+// Create API instance
+const api = createLactateAPI('athlete-id', '/path/to/data/dir');
+
+// Query latest analysis
+const result = await api.query({ compareToPrevious: true });
+
+console.log(result.currentAnalysis.lt2.power);       // e.g., 235
+console.log(result.currentAnalysis.ftp.value);      // e.g., 248
+console.log(result.currentAnalysis.lt2.ci80);       // e.g., [228, 242]
+console.log(result.comparison?.interpretation);      // "LT2 improved by 10W"
+```
+
+## Spot Test Workflow
+
+### 1. Coach Orders Spot Test (in Prescription YAML)
+
+```yaml
+sessions:
+  - week: 3
+    day: Thu
+    session_name: W3_SweetSpot
+    total_duration_min: 120
+    intervals:
+      - duration_min: 20
+        power_low_pct: 88
+        power_high_pct: 92
+        count: 3
+        recovery_min: 8
+    spot_tests:
+      - interval_ref: 2
+        sample_times_min: [10, 20]
+        reason: "Verify sweet spot intensity is below LT2"
+```
+
+### 2. Athlete Performs Test and Imports Results
+
+```bash
+# After the session, athlete imports spot readings
+lactate import -f spot_readings.csv -t spot -r "W3_SweetSpot-interval2"
+
+# CSV format:
+# power,heartrate,lactate
+# 220,155,1.8
+# 225,160,2.1
+```
+
+### 3. Analyze Spot Test
+
+```typescript
+const spotAnalysis = await api.analyzeSpotTest(
+  [
+    { power: 220, heartrate: 155, lactate: 1.8 },
+    { power: 225, heartrate: 160, lactate: 2.1 }
+  ]
+);
+
+console.log(spotAnalysis.trend);        // 'improving', 'stable', 'declining'
+console.log(spotAnalysis.comparisonToBaseline.delta);  // e.g., -0.5
+```
+
+## Output Format
+
+### LactateAnalysis Response
+
+```json
+{
+  "athleteId": "default",
+  "testId": "abc-123",
+  "testType": "ramp",
+  "testDate": "2026-03-01",
+  "sport": "cycling",
+  "lt1": {
+    "power": 185,
+    "heartrate": 142,
+    "lactate": 1.8,
+    "ci80": [178, 192],
+    "ci95": [170, 198],
+    "method": "log-log",
+    "methodType": "primary"
+  },
+  "lt2": {
+    "power": 235,
+    "heartrate": 165,
+    "lactate": 4.2,
+    "ci80": [228, 242],
+    "ci95": [220, 250],
+    "method": "dmax",
+    "methodType": "primary"
+  },
+  "ftp": {
+    "value": 248,
+    "ci80": [240, 255],
+    "ci95": [235, 262],
+    "method": "lt2-derived"
+  },
+  "fthr": {
+    "value": 168,
+    "ci80": [162, 172],
+    "method": "lt2-hr"
+  },
+  "testQuality": "good",
+  "confidence": "high",
+  "methodsUsed": ["dmax", "obla_4", "log-log"],
+  "dataQualityNotes": []
+}
+```
+
+## Analysis Methods
+
+The analyzer runs multiple detection methods and provides confidence intervals:
+
+| Method | Best For | Primary Target |
+|--------|----------|----------------|
+| Log-log | LT1 detection | LT1 |
+| Dmax | Full curves | LT2 |
+| Modified Dmax | Noisy data | LT2 |
+| OBLA 4.0 | Fixed threshold | LT2 |
+| OBLA 2.0 | Fixed threshold | LT1 |
+| Baseline+ | Drift correction | LT1 |
+
+**Confidence Intervals:**
+- 80% CI: Likely range for training decisions
+- 95% CI: Bounds for conservative planning
+- Wider CI for marginal/poor data quality
+
+## Integration Points
+
+### During adapt-plan Orient Phase
+
+1. Check if lactate data exists: `await api.query()`
+2. If available, incorporate thresholds into signal synthesis:
+   - Use LT1 power for upper Z2 boundary
+   - Use LT2 power for threshold zone (Z4)
+   - Use FTP for training zones
+   - Reference confidence intervals for decision uncertainty
+3. If spot tests available, analyze trend
+
+### QMD Knowledge Integration
+
+After significant analysis results (new baseline test), create a knowledge record:
+
+```
+{coaching_docs_dir}/lactate/YYYY-MM-DD-ramp-analysis.md
+```
+
+Include:
+- LT1/LT2 power and HR with CIs
+- FTP/FTHR values
+- Comparison to previous test
+- Methods used
+- Data quality notes
+
+---
+
+## Error Handling
+
+| Scenario | Response |
+|----------|----------|
+| No tests found | Return null, skip lactate analysis in orient |
+| Only 1-2 points | Reduce confidence to medium/low, warn user |
+| LT1 not detected | Use OBLA 2.0 as fallback |
+| LT2 not detected | Use OBLA 4.0 as fallback |
+| CI unavailable | Report point estimate only, note reduced confidence |

package/skills/lessons-rollup/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: lessons-rollup
+description: Append calibration points to lessons-log.md, then propose claim records and re-render ATHLETE_PROFILE.md and COACH_PROFILE.md through the engram harness rollup gate. Auto-tails block-review, race-analysis, and season-retrospective; can also run standalone for re-curation. Requires config.json configured and a registered harness space.
+---
+
+# Lessons Rollup
+
+## Overview
+
+Rigid four-phase workflow for maintaining the athlete-lifetime learning record. Appends new calibration points to an append-only log, proposes claim records for the changes, and re-renders the `ATHLETE_PROFILE.md` and `COACH_PROFILE.md` working summaries that `adapt-plan`, `consult`, `block-review`, and `season-retrospective` read as reasoning context. Diffing, the approval gate, sequential application, and the qmd refresh/embedding pass belong to the harness; this skill supplies coaching judgment and nothing else.
+
+**This skill is RIGID — phases execute in exact order. Do not skip, reorder, or combine phases.**
+
+## Workflow
+
+```dot
+digraph lessons_rollup {
+    "Phase 1: Append to log" [shape=box];
+    "Phase 2: Propose candidates" [shape=box];
+    "Phase 3: rollup preview" [shape=box];
+    "approval_required?" [shape=diamond];
+    "Show diff to athlete" [shape=box];
+    "Approved?" [shape=diamond];
+    "Phase 3: rollup approve" [shape=box];
+    "Phase 4: Re-render profiles" [shape=box];
+    "Skip write" [shape=box];
+
+    "Phase 1: Append to log" -> "Phase 2: Propose candidates";
+    "Phase 2: Propose candidates" -> "Phase 3: rollup preview";
+    "Phase 3: rollup preview" -> "approval_required?";
+    "approval_required?" -> "Show diff to athlete" [label="yes"];
+    "approval_required?" -> "Phase 3: rollup approve" [label="no (additive)"];
+    "Show diff to athlete" -> "Approved?";
+    "Approved?" -> "Phase 3: rollup approve" [label="yes"];
+    "Approved?" -> "Skip write" [label="no"];
+    "Phase 3: rollup approve" -> "Phase 4: Re-render profiles";
+}
+```
+
+---
+
+## Invocation Modes
+
+This skill is called in two modes:
+
+**Auto-tail (called by other skills):** Caller passes `--source={tag}` (e.g., `block-review:example-build`, `race:example-endurance-event`, `season:2027-example-season`) and an optional explicit list of bullets to append. Non-additive diffs still gate on approval.
+
+**Standalone (manual):** No `--source` flag. Skips Phase 1 (no append), runs Phase 2 only — re-curates the profile from the existing log. Use after manually editing `lessons-log.md` or after a persona change.
+
+---
+
+### 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:** none — config, persona, and athlete profile only
+
+Do not proceed past a stop condition defined there.
+
+
+### Phase 1 — Append to log _(skipped in standalone mode)_
+
+For each new bullet provided by the caller, append a new entry to `lessons-log.md` in this format:
+
+```markdown
+## {YYYY-MM-DD} — {source-tag}
+- {bullet 1}
+- {bullet 2}
+- {bullet 3}
+```
+
+Use today's date. Source tag is the exact value passed in (e.g., `race:gravel-classic-2026`).
+
+The append is literal — never rewrite or merge with prior entries. Multiple invocations on the same day under the same source tag append multiple sections (the curation step in Phase 2 dedupes the working profile).
+
+Announce: "Appended {N} bullets to lessons-log.md under {source-tag}."
+
+---
+
+### Phase 2 — Propose claim candidates
+
+Read the entire `lessons-log.md`. The profile is no longer hand-written: it is a
+**rendered artifact** produced from claim records under `{coaching_docs_dir}/claims/`.
+This phase produces *candidates*; the harness owns diffing, approval, and writing.
+
+Reason across all log entries to decide what should change:
+
+1. **Group by theme:** the space's configured theme vocabulary, read from
+   `{coaching_docs_dir}/pack-config.json`. Adding a theme is a configuration change,
+   not a prose change.
+
+2. **Dedupe with source merging:** when 2+ entries express the same pattern, propose one
+   claim carrying every source tag. A `supersede` candidate inherits the retired claim's
+   sources automatically — never restate them by hand.
+
+3. **Supersede contradicted entries:** when a newer entry contradicts an older one,
+   propose `disposition: "supersede"` naming the predecessor. The harness retires the
+   predecessor and keeps its trace; there is no `## Retired` section to maintain.
+
+4. **Persona-fit is special:** the bridge between data and persona-change decisions.
+   Write each as: pattern observed → does it match the active persona's expectations →
+   recommendation.
+
+Emit one batch file of candidate envelopes:
+
+```json
+{ "schema_version": 0, "candidates": [ { "id": "...", "kind": "claim", "disposition": "new" } ] }
+```
+
+---
+
+### Phase 3 — Review and approve through the harness
+
+The diff gate, the additive/non-additive classification, and the approval binding are the
+harness's, not this skill's. Preview the batch:
+
+```bash
+engram rollup preview --bullets {batch}.json
+```
+
+Show the athlete the rendered diff. `approval_required: true` means the batch is
+non-additive and needs an explicit yes. On approval, re-supply the same batch file with
+the previewed hash:
+
+```bash
+engram rollup approve --bullets {batch}.json --expect {rollup_hash}
+```
+
+Approval is stateless and bound to the plan: if any record changed since the preview, the
+approval is refused as `stale_approval` and nothing is written. A batch is fail-stop, not
+atomic — earlier commits stand, and the response names the stopping candidate and every
+untried one. Re-preview before retrying.
+
+Never run `qmd update` or `qmd embed` here. The harness refreshes the bound collection and
+runs exactly one embedding pass after any durable write, scoped to this space. A bare qmd
+command indexes every collection on the machine and is prohibited.
+
+---
+
+### Phase 4 — Re-render the profiles
+
+Both profiles are generated from the same claim records; neither is edited by hand.
+
+```bash
+engram render --view athlete-profile --audience athlete \
+  --delivery profile-markdown --model orchestrator/manual
+engram render --view athlete-profile --audience coach \
+  --delivery profile-markdown --model orchestrator/manual
+```
+
+Write the athlete render to `{coaching_docs_dir}/ATHLETE_PROFILE.md` and the coach render
+to `{coaching_docs_dir}/COACH_PROFILE.md`.
+
+There is no privacy, visibility, or persona-fit split between these renders. The
+presentation pack authorizes `athlete`, `coach`, and `self-coach` identically — every
+active, retrieval-eligible engram-coach record, unfiltered — and projects the same facts,
+uncertainty, actions, and recommendation IDs into all three. `ATHLETE_PROFILE.md` and
+`COACH_PROFILE.md` are the same content under a different title. `self-coach` is that same
+audience again, for an athlete acting as their own coach; this skill does not keep it as a
+standing file, but it renders on demand identically to the other two:
+
+```bash
+engram render --view athlete-profile --audience self-coach \
+  --delivery profile-markdown --model orchestrator/manual
+```
+
+A fourth audience, `clinician`, is the only one that actually filters: monitoring
+captures, lactate tests, and any record (workout adaptations included) carrying a
+health-relevant training signal (HRV, resting HR, lactate threshold, sleep, stress,
+illness, injury). It is rendered on demand rather than kept as a standing file, because a
+doctor-prep summary is episodic:
+
+```bash
+engram render --view athlete-profile --audience clinician \
+  --delivery profile-markdown --model orchestrator/manual
+```
+
+The clinician render carries the same facts/uncertainty/actions shape as the other three,
+narrowed to that health-relevant record set. There is no configurable clinical-theme list
+and no dedicated persona-fit field: any authorized persona-fit record is rendered as a
+normal record-derived fact.
+
+---
+
+## Key Constraints
+
+| Rule | Detail |
+|------|--------|
+| Append-only log | `lessons-log.md` is never rewritten or pruned by this skill |
+| Source tagging | Every log entry carries `source-tag`; the harness renders a claim's merged sources into the profile, so tags are never typed by hand |
+| Non-additive gate | Enforced by `rollup preview`/`approve`, not by this skill; approval is bound to the previewed plan and refused as `stale_approval` if anything moved |
+| Standalone is read-only on log | Standalone mode skips Phase 1 — no append, only re-curation |
+| Profiles are generated | `ATHLETE_PROFILE.md` and `COACH_PROFILE.md` are rendered artifacts; hand edits are overwritten by the next render. Change a claim record, not the file |
+| Profiles are identical | `ATHLETE_PROFILE.md` and `COACH_PROFILE.md` carry the same record-derived content — the `athlete`, `coach`, and `self-coach` audiences authorize identically, so there is no private-vs-full split to reconcile |
+| qmd is the harness's | Never run `qmd update`/`qmd embed`; a bare invocation indexes every collection on the machine |

package/skills/monitoring-rollup/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: monitoring-rollup
+description: Capture due monitoring-concern observations as typed Engram records and let the apply pipeline regenerate each concern's monitoring log and Doctor-Prep Summary. Runs in CONTRIBUTION mode (returns state_changes/events to a parent skill's single change set) or STANDALONE mode (its own preview → approval → apply). Requires config.json and a tracking/concerns.yaml registry.
+---
+
+# Monitoring Rollup
+
+## Overview
+
+Rigid phased workflow for longitudinal tracking of declared **monitoring
+concerns** — chronic symptoms/issues tracked over time so an eventual
+clinician visit is well-armed with data. Observations are captured as
+structured Engram records; each concern's monitoring log and its curated
+Doctor-Prep Summary are **generated compatibility views** that the apply
+pipeline renders deterministically from those records.
+
+**Generic:** all athlete-specific declarations live in
+`{coaching_docs_dir}/tracking/concerns.yaml`. Each entry declares at minimum:
+`id`, `active`, `cadence_days`, the concern's `log` view path, `fields`
+(the controlled columns for entries), optional `record_negatives`, and
+optional `escalation_triggers`. This skill contains no concern-specific
+knowledge.
+
+**This skill is RIGID — phases execute in exact order. Do not skip, reorder,
+or combine phases.**
+
+Monitoring logs and Doctor-Prep Summaries carry the byte-exact warning header
+(`GENERATED FROM ENGRAM ACTIVE RECORDS. DO NOT EDIT DIRECTLY.`) and are never
+edited directly by this skill or any other. The ONLY durable mutation path is
+an approved capture plan applied through the tools.
+
+## Invocation Modes
+
+Pick exactly one:
+
+1. **CONTRIBUTION MODE** — invoked by a parent skill (`consult`,
+   `adapt-plan`) during that parent's Phase 3. Read the registry, gather due
+   concerns, and **return typed monitoring items only**. Never previews,
+   never applies, never writes.
+2. **STANDALONE MODE** — manual invocation (athlete asks to "log monitoring"
+   or run a roll-up). Iterate all active concerns regardless of staleness and
+   run the full preview → approval → apply protocol itself.
+3. **RE-CURATE** — athlete asks to re-curate after reviewing data. Read-only
+   on records: no capture, no new items. Regeneration happens through
+   materialization only (see Re-curate below).
+
+---
+
+### 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:** MONITORING
+
+Do not proceed past a stop condition defined there.
+
+### Phase 1 — Detect _(all modes except RE-CURATE)_
+
+For each ACTIVE concern in the registry, find the most recent observation
+date among its records (or its generated log view) and compute
+`days_since = today − last_date`.
+
+Mark a concern **due** when EITHER `days_since ≥ cadence_days`, OR the skill
+is in STANDALONE mode.
+
+Announce one line per concern:
+`{name}: last logged {date} ({N}d ago) — {DUE | current}`.
+
+If no concern is active or due, CONTRIBUTION MODE returns empty arrays to the
+caller (see below); STANDALONE MODE exits cleanly as a no-op.
+
+### Phase 2 — Gather _(skipped in RE-CURATE; one question at a time)_
+
+For each **due** concern (STANDALONE: all active), ask `concern.prompt`.
+Capture structured values for `concern.fields`, using the log view's legend
+as the soft vocabulary.
+
+Branches:
+- **Nothing to report** and `record_negatives: true` → record a negative
+  observation: date = today, status/note = "checked — asymptomatic".
+- **Notable flare** → capture the full row; fold extra detail into the note.
+
+**Ask one question at a time. Wait for each answer before asking the next.**
+
+---
+
+### Contribution Mode
+
+Used by `consult` and `adapt-plan` inside their Phase 3. After Phase 2
+gathering, convert every captured observation into typed items and **return
+them to the caller** — nothing else. This mode never previews, never
+applies, and never writes any file. Return two arrays:
+
+1. **Current state — one per due concern/signal pair** (`state_changes`):
+   - `entity_type`: `"monitoring"`
+   - `key_components`: `{ "concern_id": "<registry id>", "signal": "<field>" }`
+     — the pack derives the canonical key `monitoring:<concern-id>:<signal>`
+   - `effective_at`: the observation date
+   - `statement`: concise current-status sentence
+   - `details`: `{ concernId, signal, status, note }`
+
+2. **Observation history — one per captured observation** (`events`):
+   - `entity_type`: `"monitoring-event"`
+   - `effective_at`: the observation's effective time
+   - `statement`: what was observed
+   - `action_targets`: `[]`
+   - `details`: `{ concernId, signal, status?, note?, source, observedAt }`
+     where `source` is the caller tag (e.g. `consult:2026-06-17`,
+     `adapt:build-1-w3-thu`) and `observedAt` the effective time
+
+These are **append-only monitoring events**: they never replace or supersede
+anything. Only the keyed state item participates in supersession.
+
+The parent merges both arrays into ITS OWN `StructuredChangeSet` BEFORE its
+Phase 4 preview, so ONE plan hash and ONE approval cover the prescription
+change, the coaching event, and all due monitoring changes together. If no
+concern is active or due, return EMPTY arrays — the parent merges them and
+continues with a single preview; no second preview is ever produced.
+
+---
+
+### Standalone Mode
+
+#### Phase 3 — Preview
+
+Assemble the gathered items into one `StructuredChangeSet` using exactly the
+shapes documented under Contribution Mode (same `entity_type`, key
+components, statement, and details contracts). Then call
+`engram_capture_preview` with it.
+
+If the preview returns blocked, STOP: Phase 4 cannot proceed until the input
+is corrected and a preview succeeds.
+
+#### Phase 4 — Approval _(requires explicit approval)_
+
+Present TOGETHER, in one message:
+
+1. What was captured — per concern: the observation(s) and the resulting
+   current status.
+2. The record plan from the preview: which monitoring states will be created
+   or superseded, which events will append.
+3. The generated compatibility view paths that will regenerate (the concern
+   logs and the Doctor-Prep Summary).
+4. The exact `plan_hash` from the preview result.
+
+Ask for approval. Approval must explicitly cover BOTH the recorded
+observations AND the record/artifact plan identified by that exact
+`plan_hash`.
+
+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 approved `plan_hash`. Never
+edit any file directly — the apply pipeline commits the records, refreshes
+the guarded index, and regenerates every monitoring log view and the
+Doctor-Prep Summary.
+
+Outcome handling:
+
+- **stale**: the records changed since preview. Return to Phase 3:
+  re-run `engram_capture_preview`, present the fresh plan and new
+  `plan_hash`, and obtain fresh approval before applying again.
+- **apply failure**: stop. No view is written and none may be edited by
+  hand; diagnose and retry through the tools.
+- **committed with stale views**: the records ARE authoritative. Re-calling
+  `engram_capture_apply` with the SAME committed `plan_hash` in the same
+  session reruns ONLY materialization — it never re-approves or re-applies
+  record mutations.
+- **committed clean**: report the applied record IDs and regenerated paths.
+
+#### Escalation scan _(both contribution and standalone, after capture)_
+
+Evaluate each declared trigger in `escalation_triggers` generically against
+the concern's recent observations: trend triggers flag when a numeric field
+moves adversely across recent points (fewer than three parseable points → no
+flag, never a false alarm); boolean/observed triggers flag when any recent
+observation reports the condition. Surface any MET trigger prominently:
+`⚠ {concern}: {trigger} — consider clinical evaluation.` The scan informs
+the announcement only; the Doctor-Prep Summary itself is rendered
+deterministically from the committed records.
+
+### RE-CURATE
+
+Read-only on records. There is nothing to hand-edit: views regenerate from
+records on every apply. If views are stale (e.g. a prior apply reported
+stale artifacts), re-run `engram_capture_apply` with that session's last
+committed `plan_hash` — materialization retries idempotently. Never rewrite
+a log or summary by hand.
+
+---
+
+## Key Constraints
+
+| Rule | Detail |
+|------|--------|
+| Generic skill | No concern-specific knowledge here; everything is driven by `concerns.yaml` |
+| No-op safety | Absent/empty registry or nothing due → clean no-op; never blocks a calling skill |
+| Contribution mode returns, never writes | Typed `state_changes`/`events` go back to the caller; no preview, no apply, no file writes |
+| One approval | Parent-skill contributions merge into the parent's SINGLE change set — one preview, one `plan_hash` |
+| Keyed state + append-only events | Due signals use `monitoring:<concern-id>:<signal>` for current state plus distinct append-only monitoring events carrying source and effective time |
+| Generated views | Monitoring logs and Doctor-Prep Summaries are regenerated compatibility views; never edited directly |
+| Record negatives | When `record_negatives: true`, "checked — asymptomatic" observations are logged (clinically meaningful) |
+| One question at a time | Phase 2 never batches questions |
+| Stale apply | Always returns to preview for a fresh hash and fresh approval |