@isparling/engram-coach 0.1.0

package/README.md

@@ -0,0 +1,116 @@
+# engram-coach
+
+## What it does
+
+engram-coach is a document-driven endurance-coaching plugin for Claude Code. It combines athlete-approved coaching records with Intervals.icu activity and wellness data to adapt training, review blocks and seasons, analyze races, and preserve durable lessons in Markdown.
+
+The plugin provides coaching workflows and deterministic analysis tools. Athlete records, credentials, and local configuration remain outside this repository.
+
+## Included skills
+
+- `adapt-plan` — assess readiness after a key workout and adapt the next prescription.
+- `block-review` — synthesize an end-of-block summary.
+- `consult` — provide advice within an active plan.
+- `intake` — configure a new athlete and coaching workspace.
+- `lactate-analyze` — query lactate tests and threshold estimates.
+- `lessons-rollup` — curate durable patterns from coaching records.
+- `monitoring-rollup` — maintain longitudinal monitoring records.
+- `race-analysis` — synthesize a completed race.
+- `season-retrospective` — review a completed season.
+- `set-goal` — establish a new goal arc and prescriptions.
+
+## Coaching personas
+
+Built-in personas are generic coaching policies, not named-coach reproductions:
+
+- `conservative` — recovery-first with an HRV veto.
+- `aggressive` — progressive overload with weighted readiness.
+- `polarized` — high low-intensity volume plus high-intensity work.
+- `volume` — long-horizon aerobic volume with a 14-day CTL trend.
+
+You can define a custom policy with [`PERSONA_SCHEMA.md`](PERSONA_SCHEMA.md).
+
+## Installation
+
+Follow [`SETUP.md`](SETUP.md) to install the plugin, configure Intervals.icu access, and create a local coaching workspace.
+
+For direct OMP integration, install the published Engram packages and bind the OMP extension:
+
+```sh
+npm install @isparling/engram-coach @isparling/engram-harness @isparling/engram-cli @isparling/engram-omp
+```
+
+```yaml
+extensions:
+  - ./node_modules/@isparling/engram-omp/omp-extension.ts
+```
+
+This does not include core Engram onboarding. The OMP extension resolves
+`engram-coach` by declaring it in the `installed_packs` of a space's binding
+inside an **existing, active Engram binding registry** — with a session-aware
+active space already registered and selected. That registry is an external
+prerequisite; this package neither creates nor configures one. Set one up
+through your own Engram deployment, then add the pack declaration:
+
+```json
+{
+  "installed_packs": [
+    {
+      "id": "engram-coach",
+      "version": "0.1.0",
+      "from": "@isparling/engram-coach",
+      "extract": true
+    }
+  ]
+}
+```
+
+**Set `ENGRAM_BINDING_REGISTRY`** to the absolute path of that binding
+registry file before starting OMP. It is required, not optional: without it
+the adapter disables knowledge capture entirely for the whole session. See
+[`SETUP.md`](SETUP.md#6-install-the-plugin) (Alternative: Direct OMP
+integration) for the full walkthrough.
+
+### Verifying the direct OMP integration
+
+Bind the pack, start an OMP session, and complete one full agent turn — the
+adapter resolves the session's active space and pack only inside its first
+`agent_end` handler, not at session start. After that turn settles, call the
+`engram_status` tool. It reports the binding-selected pack identity and CLI
+mode:
+
+```json
+{ "mode": "cli", "pack_id": "engram-coach", "pack_version": "0.1.0" }
+```
+
+`mode` is always `"cli"` — the adapter shells out to the Engram CLI and
+never injects knowledge directly into context. `pack_id: null` before the
+first turn has settled is expected, not a binding failure — call
+`engram_status` again after a turn completes.
+If `pack_id` is still `null` after that, the active space's
+binding has not resolved `engram-coach`; recheck `ENGRAM_BINDING_REGISTRY`
+and the `installed_packs` declaration above.
+
+## Configuration
+
+Copy [`config.json.example`](config.json.example) to your local configuration path and replace every placeholder. Keep credentials and athlete records outside this repository. The example config defaults to the generic `conservative` persona.
+
+## Privacy boundary
+
+This repository ships no athlete records, medical information, real event data, personal narratives, credentials, or historical coaching artifacts. Examples and fixtures are synthetic. Do not commit local `config.json`, `.env`, generated data, or athlete-owned coaching documents.
+
+## Development
+
+Install tool dependencies and run the public test suite:
+
+```bash
+npm install --prefix tools
+npm test --prefix tools
+```
+
+For the lactate package:
+
+```bash
+npm install --prefix lactate
+npm run build --prefix lactate
+```

package/engram-coach-domain.ts

@@ -0,0 +1,236 @@
+/**
+ * engram-coach domain model — coaching ontology types and constants.
+ *
+ * Captures the LLM-driven semantics of engram-coach's 10 skills as a
+ * structured type system. Used by the pack's extractor, validator, and
+ * reconciler to produce coaching-aware knowledge candidates instead of
+ * generic keyword-match blobs.
+ *
+ * This file has no Engram harness imports — it is a pure domain vocabulary
+ * that the pack module imports and the extension does not need to see.
+ *
+ * @module engram-coach-domain
+ */
+
+// ---------------------------------------------------------------------------
+// Entity types — what kind of coaching artifact or concept this is about.
+// Every extraction candidate carries one entity type in details.entityType.
+// ---------------------------------------------------------------------------
+
+export const ENGRAM_COACH_ENTITY_TYPES = [
+  "workout-adaptation",    // adapt-plan: per-session adjustment
+  "consultation",          // consult: mid-arc advice seeking
+  "block-review",          // block-review: end-of-block SUMMARY.md
+  "race-report",           // race-analysis: post-race RACE_REPORT.md
+  "season-review",         // season-retrospective: SEASON_REVIEW.md
+  "arc-plan",              // set-goal: new training arc definition
+  "lactate-test",          // lactate-analyze: LT1/LT2/FTP/FTHR test
+  "monitoring-capture",    // monitoring-rollup: longitudinal concern row
+  "intake-record",         // intake: one-time coaching setup
+  "prescription",          // prescription YAML file
+  "persona-fit",           // persona selection or change
+  "calibration-point",     // lessons-rollup: durable athlete-specific pattern
+  "methodology",           // set-goal: per-sub-block methodology doc
+  "session-execution",     // raw session data (prescription vs actual)
+] as const;
+
+export type EngramCoachEntityType = (typeof ENGRAM_COACH_ENTITY_TYPES)[number];
+
+// ---------------------------------------------------------------------------
+// Decision kinds — the type of coaching judgment being rendered.
+// ---------------------------------------------------------------------------
+
+export const ENGRAM_COACH_DECISION_KINDS = [
+  "workout-adaptation",    // adjusting a specific session's prescription
+  "consultation-advice",   // mid-arc advisory response
+  "block-restructure",     // changing a block's structure mid-cycle
+  "arc-planning",          // establishing or revising a goal arc
+  "persona-change",        // switching coaching philosophy
+  "recovery-intervention", // pulling back based on signal picture
+  "threshold-update",      // updating FTP/FTHR from lactate data
+  "monitoring-capture",    // recording a monitoring concern row
+  "profile-claim",         // promoting a calibration point to profile
+  "setup-decision",        // intake/configuration decisions
+] as const;
+
+export type EngramCoachDecisionKind = (typeof ENGRAM_COACH_DECISION_KINDS)[number];
+
+// ---------------------------------------------------------------------------
+// Training signals — physiological metrics the skills track and reason about.
+// ---------------------------------------------------------------------------
+
+export const ENGRAM_COACH_TRAINING_SIGNALS = [
+  "ctl",              // chronic training load
+  "atl",              // acute training load
+  "tsb",              // training stress balance
+  "hrv",              // heart rate variability (rMSSD)
+  "rhr",              // resting heart rate
+  "decoupling",       // aerobic decoupling (pace/power drift)
+  "time-in-zones",    // intensity distribution
+  "interval-execution", // interval fade, compliance, CV
+  "power-curve",      // best efforts at standard durations
+  "strength-ratio",   // neuromuscular fatigue indicator
+  "lactate-threshold", // LT1, LT2, OBLA values
+  "rpe",              // rate of perceived exertion
+  "nutrition",        // fueling / hydration
+  "sleep",            // sleep quality and duration
+  "stress",           // external life stress
+  "illness",          // sickness / immune status
+  "injury",           // physical injury / discomfort
+] as const;
+
+export type EngramCoachTrainingSignal = (typeof ENGRAM_COACH_TRAINING_SIGNALS)[number];
+
+// ---------------------------------------------------------------------------
+// Training phases — position within a training cycle.
+// ---------------------------------------------------------------------------
+
+export const ENGRAM_COACH_TRAINING_PHASES = [
+  "base",
+  "build-1",
+  "build-2",
+  "race-specificity",
+  "peak",
+  "recovery",
+  "transition",
+  "unknown",
+] as const;
+
+export type EngramCoachTrainingPhase = (typeof ENGRAM_COACH_TRAINING_PHASES)[number];
+
+// ---------------------------------------------------------------------------
+// Personas — coaching philosophies.
+// ---------------------------------------------------------------------------
+
+export const ENGRAM_COACH_PERSONAS = [
+  "conservative",
+  "aggressive",
+  "polarized",
+  "volume",
+] as const;
+
+export type EngramCoachPersona = (typeof ENGRAM_COACH_PERSONAS)[number];
+
+// ---------------------------------------------------------------------------
+// Skills — the 10 engram-coach skills that generate knowledge.
+// ---------------------------------------------------------------------------
+
+export const ENGRAM_COACH_SKILLS = [
+  "adapt-plan",
+  "consult",
+  "block-review",
+  "race-analysis",
+  "season-retrospective",
+  "lessons-rollup",
+  "monitoring-rollup",
+  "lactate-analyze",
+  "intake",
+  "set-goal",
+] as const;
+
+export type EngramCoachSkill = (typeof ENGRAM_COACH_SKILLS)[number];
+
+// ---------------------------------------------------------------------------
+// Entity-type to skill mapping — which skill produces which entity types.
+// ---------------------------------------------------------------------------
+
+export const ENTITY_TYPE_TO_SKILL: Record<EngramCoachEntityType, EngramCoachSkill> = {
+  "workout-adaptation": "adapt-plan",
+  consultation: "consult",
+  "block-review": "block-review",
+  "race-report": "race-analysis",
+  "season-review": "season-retrospective",
+  "arc-plan": "set-goal",
+  "lactate-test": "lactate-analyze",
+  "monitoring-capture": "monitoring-rollup",
+  "intake-record": "intake",
+  prescription: "set-goal",
+  "persona-fit": "intake",
+  "calibration-point": "lessons-rollup",
+  methodology: "set-goal",
+  "session-execution": "adapt-plan",
+};
+
+// ---------------------------------------------------------------------------
+// EngramCoachDetails — the structured `details` payload carried in every
+// engram-coach extraction candidate.
+// ---------------------------------------------------------------------------
+
+export type EngramCoachDetails = {
+  /** Which engram-coach skill produced this candidate. */
+  skill?: EngramCoachSkill;
+
+  /** What kind of coaching entity. */
+  entityType: EngramCoachEntityType;
+
+  /** The specific coaching decision being made. */
+  decisionKind: EngramCoachDecisionKind;
+
+  /** Physiological signals mentioned or involved. */
+  trainingSignals?: EngramCoachTrainingSignal[];
+
+  /** Training phase context, if identifiable. */
+  trainingPhase?: EngramCoachTrainingPhase;
+
+  /** Active persona at the time of extraction. */
+  persona?: EngramCoachPersona;
+
+  /**
+   * Structured delta — what changed vs. what was planned.
+   * Each skill records a different shape.
+   */
+  delta?: Record<string, unknown>;
+
+  /** Turn index within the session for provenance. */
+  turnIndex: number;
+
+  /** Confidence: "high" when LLM was used, "low" for deterministic fallback. */
+  extractionConfidence: "high" | "low";
+};
+
+// ---------------------------------------------------------------------------
+// Coaching topic hints — expanded set for deterministic fallback extraction.
+// ---------------------------------------------------------------------------
+
+export const COACHING_TOPIC_HINTS = [
+  // Core training metrics
+  "workout", "training", "session", "interval", "recovery",
+  "hrv", "ctl", "atl", "tsb", "ft", "ftp", "fthr",
+  "vo2", "vo2max", "lactate", "lt1", "lt2", "obla",
+  "zone", "z1", "z2", "z3", "z4", "z5",
+  "rpe", "tss", "np", "if", "power", "watt",
+  "heart rate", "hr", "rhr", "resting hr",
+
+  // Health signals
+  "illness", "sick", "injury", "pain", "discomfort",
+  "sleep", "nutrition", "fuel", "hydrat", "stress",
+  "covid", "cold", "fever", "allergy",
+
+  // Coaching domain
+  "block", "phase", "season", "arc", "goal",
+  "target event", "race", "a-race", "b-race",
+  "prescription", "adapt", "modify", "change",
+  "consult", "advice", "concern",
+  "decoupling", "fade", "drift", "strength",
+  "calibration", "pattern", "lesson",
+  "monitoring", "concern", "tracking",
+  "persona", "conservative", "aggressive", "polarized", "volume",
+  "intake", "setup", "configure",
+] as const;
+
+// ---------------------------------------------------------------------------
+// Skill-to-topic mapping — which skill a mention of a topic likely refers to.
+// ---------------------------------------------------------------------------
+
+export const SKILL_TOPIC_MAP: Record<EngramCoachSkill, string[]> = {
+  "adapt-plan": ["adapt", "workout", "session", "prescription", "modify", "delta", "next workout"],
+  consult: ["consult", "advice", "concern", "question", "sick", "illness", "life stress"],
+  "block-review": ["block summary", "summary", "block end", "week progression"],
+  "race-analysis": ["race", "race report", "event", "target event"],
+  "season-retrospective": ["season", "retrospective", "end of season", "year review"],
+  "lessons-rollup": ["calibration", "pattern", "lesson", "profile", "rollup"],
+  "monitoring-rollup": ["monitoring", "concern", "tracking", "symptom"],
+  "lactate-analyze": ["lactate", "lt1", "lt2", "ftp", "threshold", "fthr"],
+  intake: ["intake", "setup", "configure", "onboard", "persona"],
+  "set-goal": ["goal", "arc", "target", "block plan", "methodology"],
+};

package/engram-coach-extractor.ts

@@ -0,0 +1,295 @@
+/**
+ * engram-coach LLM-powered knowledge extractor.
+ *
+ * Implements the KnowledgeExtractor interface using the Engram harness LLM helper
+ * when available. For each turn, the LLM analyzes the conversation and
+ * produces structured coaching-aware candidates classified into engram-coach's
+ * domain ontology (entity types, decision kinds, training signals, phases,
+ * personas). Falls back to deterministic keyword matching when the LLM
+ * helper is absent.
+ *
+ * @module engram-coach-extractor
+ */
+
+import type { TurnContext, PackHelpers } from "@isparling/engram-harness/knowledge-types";
+import {
+  ENGRAM_COACH_ENTITY_TYPES,
+  ENGRAM_COACH_DECISION_KINDS,
+  ENGRAM_COACH_TRAINING_SIGNALS,
+  ENGRAM_COACH_TRAINING_PHASES,
+  ENGRAM_COACH_PERSONAS,
+  COACHING_TOPIC_HINTS,
+  type EngramCoachDetails,
+  type EngramCoachEntityType,
+  type EngramCoachDecisionKind,
+} from "./engram-coach-domain.ts";
+
+export const engramCoachPackId = "engram-coach";
+export const engramCoachPackVersion = "0.1.0";
+
+/**
+ * System prompt for the LLM-powered extractor.
+ *
+ * Instructs the LLM to analyze a conversation turn and produce structured
+ * coaching observations classified into the engram-coach domain ontology.
+ */
+const EXTRACTION_SYSTEM_PROMPT = `You are a coaching domain classifier embedded in the engram-coach coaching system. Your task is to analyze conversation turns and extract structured knowledge candidates about coaching decisions.
+
+## Domain ontology
+
+### Entity types — what kind of coaching artifact or concept this turn is about:
+${ENGRAM_COACH_ENTITY_TYPES.map((t) => `- ${t}`).join("\n")}
+
+### Decision kinds — what type of coaching judgment is being rendered:
+${ENGRAM_COACH_DECISION_KINDS.map((k) => `- ${k}`).join("\n")}
+
+### Training signals — physiological metrics mentioned:
+${ENGRAM_COACH_TRAINING_SIGNALS.map((s) => `- ${s}`).join("\n")}
+
+### Training phases:
+${ENGRAM_COACH_TRAINING_PHASES.map((p) => `- ${p}`).join("\n")}
+
+### Personas:
+${ENGRAM_COACH_PERSONAS.map((p) => `- ${p}`).join("\n")}
+
+## Classification rules
+
+1. Return an empty JSON array \`[]\` if this turn contains no coaching-relevant content. Coaching-relevant means: training data, workout execution, adaptation decisions, race/event planning, consultation/advice, health signals (illness/injury/sleep/nutrition), monitoring concerns, goal/arc planning, coaching setup (intake/persona), lactate analysis, or block/season reviews.
+
+2. Each candidate must be a JSON object with these fields:
+   - \`entityType\`: one of the entity types above
+   - \`decisionKind\`: one of the decision kinds above
+   - \`statement\`: a concise, factual one-sentence statement of what was observed or decided (max 300 chars)
+   - \`trainingSignals\`: array of signal names mentioned (or empty array)
+   - \`trainingPhase\`: training phase if identifiable, else null
+   - \`persona\`: persona if mentioned or obvious from context, else null
+   - \`topics\`: 1-4 topic labels useful for retrieval (e.g., "interval fade", "sweet spot prescription", "LT2 update", "HRV suppression")
+
+3. For \`statement\`, prefer concrete observations over generic ones:
+   - GOOD: "Athlete reported RPE 8.5 on final interval with power fade >10%"
+   - BAD: "Athlete had a hard workout"
+   - GOOD: "Athlete switched persona from conservative to aggressive for build phase"
+   - BAD: "Persona change"
+
+4. Return at most 3 candidates per turn. Prioritize candidates that represent decisions or new observations over routine status updates.
+
+5. Return ONLY the JSON array. No preamble, no explanation, no markdown.`;
+
+/**
+ * Deterministic fallback: check if the turn narrative mentions coaching
+ * topics. Returns the most likely entity type based on matched terms.
+ */
+function coachingRelevantEntityType(text: string): EngramCoachEntityType | null {
+  const lower = text.toLowerCase();
+
+  // Simple greedy: return null if no topic matched
+  if (!COACHING_TOPIC_HINTS.some((hint) => lower.includes(hint))) {
+    return null;
+  }
+
+  // Map topics to entity types
+  // Arc-planning: goal+arc/target is most specific — check first
+  if (
+    (lower.includes("goal") || lower.includes("arc")) &&
+    (lower.includes("target") || lower.includes("methodology"))
+  ) {
+    return "arc-plan";
+  }
+  if (lower.includes("race") && (lower.includes("report") || lower.includes("analysis"))) {
+    return "race-report";
+  }
+  if (lower.includes("block") && (lower.includes("review") || lower.includes("summary"))) {
+    return "block-review";
+  }
+  if (lower.includes("season") && (lower.includes("review") || lower.includes("retrospective"))) {
+    return "season-review";
+  }
+  if (lower.includes("consult") || lower.includes("advice") || lower.includes("question about")) {
+    return "consultation";
+  }
+  if (lower.includes("intake") || lower.includes("setup") || lower.includes("onboard")) {
+    return "intake-record";
+  }
+  if (lower.includes("adapt") || lower.includes("modify") || lower.includes("delta") || lower.includes("prescription")) {
+    return "workout-adaptation";
+  }
+  if (lower.includes("lactate") || lower.includes("threshold") || lower.includes("lt1") || lower.includes("lt2")) {
+    return "lactate-test";
+  }
+  if (lower.includes("monitor") || lower.includes("concern") || lower.includes("symptom") || lower.includes("tracking")) {
+    return "monitoring-capture";
+  }
+  if (lower.includes("persona") || lower.includes("philosophy")) {
+    return "persona-fit";
+  }
+  if (lower.includes("lesson") || lower.includes("calibration") || lower.includes("profile") || lower.includes("rollup")) {
+    return "calibration-point";
+  }
+  if (lower.includes("race") || lower.includes("event")) {
+    return "race-report";
+  }
+
+  // Generic coaching observation
+  return "session-execution";
+}
+
+function deterministicDecisionKind(entityType: EngramCoachEntityType): EngramCoachDecisionKind {
+  const map: Record<EngramCoachEntityType, EngramCoachDecisionKind> = {
+    "workout-adaptation": "workout-adaptation",
+    consultation: "consultation-advice",
+    "block-review": "block-restructure",
+    "race-report": "workout-adaptation",
+    "season-review": "arc-planning",
+    "arc-plan": "arc-planning",
+    "lactate-test": "threshold-update",
+    "monitoring-capture": "monitoring-capture",
+    "intake-record": "setup-decision",
+    prescription: "arc-planning",
+    "persona-fit": "persona-change",
+    "calibration-point": "profile-claim",
+    methodology: "arc-planning",
+    "session-execution": "workout-adaptation",
+  };
+  return map[entityType];
+}
+
+/**
+ * Parse the LLM's JSON response into candidate objects.
+ * Returns empty array on any parse failure.
+ */
+function parseLlmResponse(raw: string): Record<string, unknown>[] {
+  const trimmed = raw.trim();
+
+  // Strip markdown code fences if present
+  const jsonStr = trimmed.replace(/^```(?:json)?\s*\n?/, "").replace(/\n?```\s*$/, "");
+
+  try {
+    const parsed = JSON.parse(jsonStr);
+    if (!Array.isArray(parsed)) return [];
+    return parsed;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The engram-coach extractor facet.
+ *
+ * Uses LLM when available (via PackHelpers.llm.complete) to produce
+ * coaching-aware candidates classified into the domain ontology.
+ * Falls back to deterministic keyword matching without LLM.
+ */
+export const engramCoachExtractor = {
+  id: engramCoachPackId,
+  version: engramCoachPackVersion,
+
+  async extractCandidates(
+    turn: TurnContext,
+    helpers: PackHelpers,
+  ): Promise<Record<string, unknown>[]> {
+    const narrative = turn.narrative?.trim() ?? "";
+    if (!narrative) return [];
+
+    // -------------------------------------------------------------------------
+    // LLM path
+    // -------------------------------------------------------------------------
+    if (helpers.llm?.complete) {
+      try {
+        const raw = await helpers.llm.complete(
+          `Analyze this conversation turn and extract coaching knowledge candidates as JSON:\n\n${narrative}`,
+          { system: EXTRACTION_SYSTEM_PROMPT },
+        );
+
+        const candidates = parseLlmResponse(raw);
+        if (candidates.length > 0) {
+          // Enrich each candidate with pack metadata
+          return candidates.map((c, i) => {
+            const entityType = (c.entityType as EngramCoachEntityType) ?? "session-execution";
+            const decisionKind = (c.decisionKind as EngramCoachDecisionKind) ?? "workout-adaptation";
+            const statement = (c.statement as string) ?? narrative.slice(0, 300);
+            const topics = (c.topics as string[]) ?? ["coaching:observation"];
+
+            const details: EngramCoachDetails = {
+              skill: undefined,
+              entityType,
+              decisionKind,
+              trainingSignals: c.trainingSignals as EngramCoachDetails["trainingSignals"],
+              trainingPhase: c.trainingPhase as EngramCoachDetails["trainingPhase"],
+              persona: c.persona as EngramCoachDetails["persona"],
+              turnIndex: turn.turnIndex,
+              extractionConfidence: "high",
+            };
+
+            return {
+              id: `engram-coach-turn-${turn.turnIndex}-${i}-${Date.now()}`,
+              kind: "decision",
+              status: "candidate",
+              disposition: "new",
+              scope: {
+                space: engramCoachPackId,
+                subjects: [],
+                topics,
+                contexts: [],
+                dimensions: {},
+              },
+              pack: { id: engramCoachPackId, version: engramCoachPackVersion },
+              sources: [
+                { type: "engram-coach-extractor", ref: `session:${turn.session.id}` },
+                { type: "llm-inference", ref: `turn:${turn.turnIndex}` },
+              ],
+              session: turn.session,
+              submittedAt: turn.timestamp,
+              details: details as unknown as Record<string, unknown>,
+              statement: statement.slice(0, 512),
+            };
+          });
+        }
+      } catch {
+        // LLM call failed — fall through to deterministic path
+      }
+    }
+
+    // -------------------------------------------------------------------------
+    // Deterministic fallback path
+    // -------------------------------------------------------------------------
+    if (narrative.length === 0) return [];
+
+    const entityType = coachingRelevantEntityType(narrative);
+    if (!entityType) return [];
+
+    const decisionKind = deterministicDecisionKind(entityType);
+
+    const details: EngramCoachDetails = {
+      skill: undefined,
+      entityType,
+      decisionKind,
+      turnIndex: turn.turnIndex,
+      extractionConfidence: "low",
+    };
+
+    const id = `engram-coach-turn-${turn.turnIndex}-${Date.now()}`;
+    return [
+      {
+        id,
+        kind: "decision",
+        status: "candidate",
+        disposition: "new",
+        scope: {
+          space: engramCoachPackId,
+          subjects: [],
+          topics: ["coaching:observation"],
+          contexts: [],
+          dimensions: {},
+        },
+        pack: { id: engramCoachPackId, version: engramCoachPackVersion },
+        sources: [
+          { type: "engram-coach-extractor", ref: `session:${turn.session.id}` },
+        ],
+        session: turn.session,
+        submittedAt: turn.timestamp,
+        details: details as unknown as Record<string, unknown>,
+        statement: narrative.slice(0, 300),
+      },
+    ];
+  },
+};

package/engram-coach-pack.ts

@@ -0,0 +1,61 @@
+/**
+ * engram-coach federated pack — a self-contained implementation of the
+ * Engram core's external pack interfaces. engram-coach owns its domain
+ * taxonomy, extraction prompts, validation, and reconciliation logic. The
+ * Engram core never needs to know this pack's name at build time: the CLI
+ * resolves it at runtime as an ordinary Node ESM module, imported from the
+ * `from` specifier a space's binding declares for it in `installed_packs`.
+ *
+ * The pack implements:
+ *   - KnowledgeExtractor.extractCandidates — LLM-powered turn-end extraction
+ *     with deterministic fallback when LLM helper is unavailable
+ *   - KnowledgePack.validateEnvelope / reconcile — domain-aware validation
+ *     and semantic reconciliation using the engram-coach coaching ontology
+ *   - PresentationPack — deterministic athlete-profile projection and
+ *     audience authorization, defined in `engram-coach-presentation.ts`
+ *
+ * See `@isparling/engram-harness`'s `harness/docs/pack-interface.md` for the
+ * external pack contract. See `engram-coach-domain.ts` for the coaching
+ * ontology types and constants.
+ */
+
+import type {
+  KnowledgePack,
+  KnowledgeExtractor,
+  KnowledgeRecord,
+  PresentationPack,
+} from "@isparling/engram-harness/knowledge-types";
+import { engramCoachExtractor } from "./engram-coach-extractor.ts";
+import { engramCoachPresentation } from "./engram-coach-presentation.ts";
+import {
+  validateEnvelope,
+  reconcile,
+  relatedQuery,
+} from "./engram-coach-reconciliation.ts";
+
+export const engramCoachPackId = "engram-coach";
+export const engramCoachPackVersion = "0.1.0";
+
+/** The engram-coach pack: KnowledgePack + KnowledgeExtractor + PresentationPack facets. */
+export const engramCoachPack: KnowledgePack & KnowledgeExtractor & PresentationPack = {
+  id: engramCoachPackId,
+  version: engramCoachPackVersion,
+
+  // KnowledgePack facets
+  validateEnvelope,
+  relatedQuery,
+  reconcile,
+
+  // KnowledgeExtractor facets
+  extractCandidates: engramCoachExtractor.extractCandidates,
+
+  // PresentationPack facets
+  retrievalPolicy: engramCoachPresentation.retrievalPolicy,
+  views: engramCoachPresentation.views,
+  audiences: engramCoachPresentation.audiences,
+  deliveries: engramCoachPresentation.deliveries,
+};
+
+export default engramCoachPack;
+
+export type EngramCoachRecord = KnowledgeRecord;

package/engram-coach-presentation.ts

@@ -0,0 +1,187 @@
+/**
+ * engram-coach profile presentation — deterministic, record-derived athlete
+ * profile projection and audience authorization policy.
+ *
+ * Implements the PresentationPack interface: a single retrieval policy that
+ * scopes guarded retrieval to active engram-coach records, one `athlete-profile`
+ * view whose projection is built only from the statements and details already
+ * present on the retrieved records (no inferred facts, diagnoses, or
+ * prescriptions), and four audiences that gate which records each role may
+ * see before that projection is adapted into a delivery draft.
+ *
+ * `athlete`, `coach`, and `self-coach` authorize every record the retrieval
+ * policy accepts. `clinician` is narrower: monitoring captures, lactate
+ * tests, and any record (including workout adaptations) that carries a
+ * health-relevant training signal.
+ *
+ * @module engram-coach-presentation
+ */
+
+import type {
+  KnowledgeRecord,
+  PresentationPack,
+  SemanticProjection,
+  AudienceAdaptationInput,
+  PresentationDraft,
+} from "@isparling/engram-harness/knowledge-types";
+
+// Duplicated locally (mirrors the same constants in `engram-coach-pack.ts`
+// and `engram-coach-extractor.ts`) so this module never needs to import the
+// pack composition module — `engram-coach-pack.ts` imports this module to
+// assemble the full pack, and a reverse import would create a cycle.
+export const engramCoachPackId = "engram-coach";
+export const engramCoachPackVersion = "0.1.0";
+
+// ---------------------------------------------------------------------------
+// Clinician authorization — monitoring captures, lactate tests, and any
+// record (workout adaptations included) carrying a health-relevant signal.
+// `record.details` is an untyped `JsonObject`; every read below narrows via
+// `typeof`/`Array.isArray`/direct literal comparison instead of asserting
+// the payload into the domain's `EngramCoachDetails` shape.
+// ---------------------------------------------------------------------------
+
+const CLINICIAN_TRAINING_SIGNALS: Readonly<Record<string, true>> = {
+  hrv: true,
+  rhr: true,
+  "lactate-threshold": true,
+  sleep: true,
+  stress: true,
+  illness: true,
+  injury: true,
+};
+
+function hasClinicalSignal(record: KnowledgeRecord): boolean {
+  const value = record.details.trainingSignals;
+  if (!Array.isArray(value)) return false;
+  return value.some((signal) => typeof signal === "string" && CLINICIAN_TRAINING_SIGNALS[signal] === true);
+}
+
+// ---------------------------------------------------------------------------
+// Retrieval policy — scope every query and profile enumeration to active
+// engram-coach records only.
+// ---------------------------------------------------------------------------
+
+const retrievalPolicy: PresentationPack["retrievalPolicy"] = {
+  allowedSourceClasses: ["engram-coach"],
+  queryStrategy: ({ query }) => query,
+  classifySource: () => "engram-coach",
+  relevanceThreshold: null,
+  isEligible: (record) =>
+    record.status === "active" && record.pack.id === engramCoachPackId,
+  includePresentations: false,
+};
+
+// ---------------------------------------------------------------------------
+// `athlete-profile` view — deterministic, record-derived projection.
+// ---------------------------------------------------------------------------
+
+function uniqueSorted(values: readonly string[]): string[] {
+  return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+
+function projectAthleteProfile(records: readonly KnowledgeRecord[]): SemanticProjection {
+  const facts = uniqueSorted(records.map((record) => record.statement));
+  const uncertainty = uniqueSorted(
+    records
+      .filter((record) => record.details.extractionConfidence === "low")
+      .map((record) => record.statement),
+  );
+  const activeRecommendations = records.filter(
+    (record) => record.status === "active" && record.kind === "recommendation",
+  );
+  const actions = uniqueSorted(activeRecommendations.map((record) => record.statement));
+  const recommendationIds = uniqueSorted(activeRecommendations.map((record) => record.id));
+
+  return {
+    title: "Engram coach athlete profile",
+    summary:
+      "Deterministic projection of active, retrieval-eligible engram-coach records for the requesting audience.",
+    facts,
+    requiredFacts: [...facts],
+    uncertainty,
+    actions,
+    recommendationIds,
+  };
+}
+
+const athleteProfileView: PresentationPack["views"][number] = {
+  id: "athlete-profile",
+  version: 1,
+  scope: "space",
+  retrievalQuery: (requestedQuery) => requestedQuery ?? "",
+  project: projectAthleteProfile,
+};
+
+// ---------------------------------------------------------------------------
+// Audiences — authorization plus a draft adaptation that carries the
+// projection's facts, uncertainty, actions, and recommendation IDs forward
+// unchanged. No audience adds content the projection did not already derive
+// from the authorized records.
+// ---------------------------------------------------------------------------
+
+function adaptFromProjection(title: string) {
+  return ({ projection }: AudienceAdaptationInput): PresentationDraft => ({
+    title,
+    summary: projection.summary,
+    facts: [...projection.facts],
+    uncertainty: [...projection.uncertainty],
+    actions: [...projection.actions],
+    recommendationIds: [...projection.recommendationIds],
+  });
+}
+
+const athleteAudience: PresentationPack["audiences"][number] = {
+  id: "athlete",
+  version: 1,
+  authorize: retrievalPolicy.isEligible,
+  adapt: adaptFromProjection("Athlete profile"),
+};
+
+const coachAudience: PresentationPack["audiences"][number] = {
+  id: "coach",
+  version: 1,
+  authorize: retrievalPolicy.isEligible,
+  adapt: adaptFromProjection("Coach profile"),
+};
+
+const selfCoachAudience: PresentationPack["audiences"][number] = {
+  id: "self-coach",
+  version: 1,
+  authorize: retrievalPolicy.isEligible,
+  adapt: adaptFromProjection("Self-coach profile"),
+};
+
+const clinicianAudience: PresentationPack["audiences"][number] = {
+  id: "clinician",
+  version: 1,
+  authorize: (record) => {
+    if (!retrievalPolicy.isEligible(record)) return false;
+    const entityType = record.details.entityType;
+    if (entityType === "monitoring-capture" || entityType === "lactate-test") return true;
+    return hasClinicalSignal(record);
+  },
+  adapt: adaptFromProjection("Clinician profile"),
+};
+
+// ---------------------------------------------------------------------------
+// Deliveries
+// ---------------------------------------------------------------------------
+
+const deliveries: PresentationPack["deliveries"] = [
+  { id: "profile-markdown", version: 1, format: "markdown", maxWords: 5000, retain: true },
+];
+
+// ---------------------------------------------------------------------------
+// The engram-coach PresentationPack facet.
+// ---------------------------------------------------------------------------
+
+export const engramCoachPresentation: PresentationPack = {
+  id: engramCoachPackId,
+  version: engramCoachPackVersion,
+  retrievalPolicy,
+  views: [athleteProfileView],
+  audiences: [athleteAudience, coachAudience, selfCoachAudience, clinicianAudience],
+  deliveries,
+};
+
+export default engramCoachPresentation;

package/engram-coach-reconciliation.ts

@@ -0,0 +1,327 @@
+/**
+ * engram-coach domain-aware validation and reconciliation.
+ *
+ * Implements the KnowledgePack facets with full awareness of the coaching
+ * domain ontology defined in engram-coach-domain.ts.
+ *
+ * - validateEnvelope: validates candidates against known entity types,
+ *   decision kinds, statement requirements, and detail structure.
+ * - reconcile: understands semantic relationships between candidates and
+ *   existing knowledge — threshold updates supersede prior thresholds,
+ *   same-block observations support each other, duplicate statements are
+ *   deduped, and identical claims from different sources get merged.
+ *
+ * @module engram-coach-reconciliation
+ */
+
+import type {
+  KnowledgeEnvelope,
+  KnowledgeResult,
+  PackReconciliation,
+  PackReconcileInput,
+  KnowledgeRecord,
+} from "@isparling/engram-harness/knowledge-types";
+import {
+  ENGRAM_COACH_ENTITY_TYPES,
+  ENGRAM_COACH_DECISION_KINDS,
+  ENGRAM_COACH_TRAINING_PHASES,
+  ENGRAM_COACH_PERSONAS,
+  ENTITY_TYPE_TO_SKILL,
+  type EngramCoachDetails,
+  type EngramCoachEntityType,
+} from "./engram-coach-domain.ts";
+
+// ---------------------------------------------------------------------------
+// Known destination topics used when validating scope topics.
+// ---------------------------------------------------------------------------
+
+const KNOWN_TOPIC_PREFIXES = [
+  "coaching:",
+  "training:",
+  "physiology:",
+  "health:",
+  "planning:",
+  "monitoring:",
+  "content:",
+];
+
+/**
+ * Validate an engram-coach knowledge envelope against the domain ontology.
+ *
+ * Checks:
+ * - Statement is non-empty and within length limits
+ * - entityType is a known engram-coach entity type
+ * - decisionKind is a known engram-coach decision kind
+ * - trainingPhase (if present) is a known phase
+ * - persona (if present) is a known persona
+ * - topics use known prefixes
+ */
+export function validateEnvelope(
+  envelope: KnowledgeEnvelope,
+): KnowledgeResult<void> {
+  const errors: Array<{ kind: "validation"; code: string; field?: string; message: string }> = [];
+
+  // --- Statement checks ---
+  const statement = envelope.statement?.trim() ?? "";
+  if (!statement) {
+    errors.push({
+      kind: "validation",
+      code: "empty_statement",
+      field: "statement",
+      message: "statement must not be empty",
+    });
+  }
+  if (statement.length > 5000) {
+    errors.push({
+      kind: "validation",
+      code: "statement_too_long",
+      field: "statement",
+      message: "statement must be at most 5000 characters",
+    });
+  }
+
+  // --- Details checks ---
+  const details = envelope.details as Partial<EngramCoachDetails> | undefined;
+
+  if (details) {
+    const entityType = details.entityType;
+    if (entityType && !((ENGRAM_COACH_ENTITY_TYPES as readonly string[]).includes(entityType))) {
+      errors.push({
+        kind: "validation",
+        code: "unknown_entity_type",
+        field: "details.entityType",
+        message: `"${entityType}" is not a known engram-coach entity type`,
+      });
+    }
+
+    const decisionKind = details.decisionKind;
+    if (decisionKind && !((ENGRAM_COACH_DECISION_KINDS as readonly string[]).includes(decisionKind))) {
+      errors.push({
+        kind: "validation",
+        code: "unknown_decision_kind",
+        field: "details.decisionKind",
+        message: `"${decisionKind}" is not a known engram-coach decision kind`,
+      });
+    }
+
+    const trainingPhase = details.trainingPhase;
+    if (trainingPhase && !((ENGRAM_COACH_TRAINING_PHASES as readonly string[]).includes(trainingPhase))) {
+      errors.push({
+        kind: "validation",
+        code: "unknown_training_phase",
+        field: "details.trainingPhase",
+        message: `"${trainingPhase}" is not a known training phase`,
+      });
+    }
+
+    const persona = details.persona;
+    if (persona && !((ENGRAM_COACH_PERSONAS as readonly string[]).includes(persona))) {
+      errors.push({
+        kind: "validation",
+        code: "unknown_persona",
+        field: "details.persona",
+        message: `"${persona}" is not a known persona`,
+      });
+    }
+  }
+
+  // --- Topic checks ---
+  if (envelope.scope?.topics) {
+    for (const topic of envelope.scope.topics) {
+      const hasKnownPrefix = KNOWN_TOPIC_PREFIXES.some((p) => topic.startsWith(p));
+      if (!hasKnownPrefix) {
+        errors.push({
+          kind: "validation",
+          code: "unknown_topic_prefix",
+          field: "scope.topics",
+          message: `topic "${topic}" does not use a known prefix`,
+        });
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    return { ok: false, errors };
+  }
+
+  return { ok: true, value: undefined };
+}
+
+/**
+ * Infer the entity type from a knowledge record's details.
+ */
+function entityTypeFromRecord(record: KnowledgeRecord): EngramCoachEntityType | null {
+  const details = record.details as Partial<EngramCoachDetails> | undefined;
+  return details?.entityType ?? null;
+}
+
+/**
+ * Domain-aware reconciliation.
+ *
+ * Understands semantic relationships:
+ * - Same entity type + same scope + similar statement → support (refine)
+ * - Threshold update for same athlete → supersede prior threshold
+ * - Identical statement across different sources → support (merge)
+ * - Different entity types → new (independent observation)
+ * - No related records → accept as new
+ */
+export function reconcile(
+  input: PackReconcileInput,
+): KnowledgeResult<PackReconciliation> {
+  const candidate = input.candidate;
+  const related = input.related;
+  const candidateDetails = candidate.details as Partial<EngramCoachDetails> | undefined;
+  const candidateEntityType = candidateDetails?.entityType;
+
+  // No related records → accept as new
+  if (related.length === 0) {
+    return {
+      ok: true,
+      value: {
+        disposition: "new",
+        summary: candidateEntityType
+          ? `engram-coach accepted new ${candidateEntityType} observation`
+          : "engram-coach accepted new coaching observation",
+        mutations: [],
+      },
+    };
+  }
+
+  // --- Semantic matching against related records ---
+  const latest = related[0];
+  const latestDetails = latest.details as Partial<EngramCoachDetails> | undefined;
+  const latestEntityType = latestDetails?.entityType;
+
+  // 1. Identical statement → no-change (dedupe)
+  if (latest.statement === candidate.statement) {
+    return {
+      ok: true,
+      value: {
+        disposition: "no-change",
+        summary: "duplicate of an existing coaching observation",
+        mutations: [],
+      },
+    };
+  }
+
+  // 2. Same entity type — refine or support
+  if (candidateEntityType && candidateEntityType === latestEntityType) {
+    // Threshold updates supersede prior thresholds for the same athlete
+    if (candidateEntityType === "lactate-test") {
+      return {
+        ok: true,
+        value: {
+          disposition: "supersede",
+          summary: `new lactate test result supersedes prior threshold values`,
+          mutations: [
+            {
+              action: "update",
+              record: {
+                ...latest,
+                status: "retired",
+                details: {
+                  ...(latest.details as Record<string, unknown>),
+                  supersededBy: candidate.id,
+                  supersededAt: candidate.submittedAt,
+                },
+              },
+            },
+          ],
+        },
+      };
+    }
+
+    // Persona changes supersede prior persona
+    if (candidateEntityType === "persona-fit") {
+      return {
+        ok: true,
+        value: {
+          disposition: "supersede",
+          summary: `persona decision supersedes prior persona-fit record`,
+          mutations: [
+            {
+              action: "update",
+              record: {
+                ...latest,
+                status: "retired",
+                details: {
+                  ...(latest.details as Record<string, unknown>),
+                  supersededBy: candidate.id,
+                  supersededAt: candidate.submittedAt,
+                },
+              },
+            },
+          ],
+        },
+      };
+    }
+
+    // Same entity type, different statement → refine (new info on same topic)
+    return {
+      ok: true,
+      value: {
+        disposition: "refine",
+        summary: `additional ${candidateEntityType} observation refines prior record`,
+        mutations: [],
+      },
+    };
+  }
+
+  // 3. Different entity types, same outcome scope
+  if (candidateEntityType && latestEntityType && candidateEntityType !== latestEntityType) {
+    // Different entity type but complementary scope → support
+    const skillCandidate = ENTITY_TYPE_TO_SKILL[candidateEntityType];
+    const skillLatest = ENTITY_TYPE_TO_SKILL[latestEntityType];
+
+    if (skillCandidate === skillLatest) {
+      return {
+        ok: true,
+        value: {
+          disposition: "support",
+          summary: `${candidateEntityType} observation supports prior ${latestEntityType} record from same skill`,
+          mutations: [],
+        },
+      };
+    }
+  }
+
+  // 4. Unrelated records → accept as new
+  return {
+    ok: true,
+    value: {
+      disposition: "new",
+      summary: "engram-coach accepted a coaching observation (no direct relationship to prior records)",
+      mutations: [],
+    },
+  };
+}
+
+/**
+ * Build a query string from an envelope for finding related records.
+ */
+export function relatedQuery(envelope: KnowledgeEnvelope): string {
+  const details = envelope.details as Partial<EngramCoachDetails> | undefined;
+  const entityType = details?.entityType;
+  const persona = details?.persona;
+  const trainingPhase = details?.trainingPhase;
+  const trainingSignals = details?.trainingSignals;
+
+  const parts: string[] = [];
+
+  if (entityType) parts.push(entityType);
+  if (persona) parts.push(`persona:${persona}`);
+  if (trainingPhase) parts.push(`phase:${trainingPhase}`);
+  if (trainingSignals && trainingSignals.length > 0) {
+    parts.push(trainingSignals.slice(0, 3).join(" "));
+  }
+
+  // Fall back to statement content
+  const statement = envelope.statement?.trim() ?? "";
+  if (parts.length === 0 && statement) {
+    parts.push(statement.slice(0, 100));
+  } else if (parts.length === 0) {
+    parts.push("coaching observation");
+  }
+
+  return parts.join(" ");
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@isparling/engram-coach",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "Engram external pack for document-driven endurance coaching.",
+  "exports": { ".": { "import": "./engram-coach-pack.ts" } },
+  "files": [
+    "engram-coach-domain.ts",
+    "engram-coach-extractor.ts",
+    "engram-coach-reconciliation.ts",
+    "engram-coach-presentation.ts",
+    "engram-coach-pack.ts",
+    "README.md"
+  ],
+  "peerDependencies": { "@isparling/engram-harness": "^0.1.0" },
+  "devDependencies": {
+    "@isparling/engram-harness": "file:../engram/harness",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "test": "npm test --prefix tools",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "pack:local": "npm pack --json"
+  }
+}