@wattsonclub/wattson-cli 0.1.0 → 0.1.1

package/skill/references/workout-text-format.md

@@ -1,460 +1,122 @@
-# Workout text format
+# Workout text output (implemented renderer, not input syntax)
 
-This doc proposes a **chat-friendly, mostly lossless text representation** for workouts.
+`packages/domain/src/index.ts` implements:
 
-Goal:
-- make workouts easy to review in chat
-- give agents a stable text representation for reasoning and diffs
-- make structured validation feedback easier to map back to something human-readable
-- prepare for future renderer/parser work without pretending it already exists
-
-Important status note:
-- a first renderer now exists in `packages/domain` via `renderWorkoutText(...)`
-- this is still **not** a fully implemented parser contract yet
-- canonical source of truth is still the structured workout schema in `packages/domain`
-
-Related docs:
-- `workout-building-blocks.md`
-- `commands.md`
-
----
-
-## 1. Why this exists
-
-Schema is necessary, but schema alone is not enough for chat interfaces.
-
-We need a middle representation that is:
-- readable by humans
-- easy for agents to reason about
-- compact enough for chat
-- stable enough to reference in validation/revision feedback
-- structured enough that it could later become a real render/parse layer
-
-This doc proposes **three textual views** of the same workout:
-
-1. **Expanded canonical text**
-   - most explicit
-   - preferred for careful review
-   - closest to a future reversible representation
-
-2. **Compact text summary**
-   - shorter
-   - good for chat replies
-   - still structurally legible
-
-3. **Chat-visual preview**
-   - highly readable preview
-   - best for quick inspection
-   - not necessarily fully lossless on its own
-
----
-
-## 2. Design principles
-
-A good workout text format should be:
-
-### Deterministic
-The same structured workout should render the same way every time.
-
-### Block-oriented
-Blocks and interval steps should stay visible as blocks/steps.
-Do not flatten everything into prose.
-
-### Stable enough for references
-Validation should be able to say things like:
-- `block 2`
-- `block 2 > step 1`
-- `line 6`
-
-### Honest about precision
-If a target is explicit, show it explicitly.
-If it is open, show that too.
-
-### Friendly to diffs
-If a workout changes, the text representation should make the change obvious.
-
----
-
-## 3. Expanded canonical text format
-
-This is the best candidate for a future canonical text representation.
-
-## 3.1 Header fields
-Suggested header fields:
-- `Workout:`
-- `Objective:`
-- `Sport:`
-- `Execution:`
-- optionally `Constraints:`
-- optionally `Rationale:`
-
-Example:
-
-```text
-Workout: VO2 20
-Objective: vo2max
-Sport: cycling_indoor
-Execution: erg
-Constraints: indoorOnly, maxPctFtp=1.2
-Rationale: short hard day with 3 repeat efforts
+```ts
+renderWorkoutText(workout, { mode: 'canonical' | 'compact' | 'chat' })
+describeWorkoutPath(path)
+renderValidationIssues(validation)
 ```
 
-Note:
-- `maxPctFtp` is fractional
-- use `1.2` for `120% FTP`, not `120`
+The default mode is `compact`. **No reverse parser exists.** None of these renderings is lossless, even the one named `canonical`. Structured `WorkoutDefinition` JSON remains canonical for editing, storage, validation and compilation. Do not send text notation to draft/validate/save as if it were a workout payload. See [workout-building-blocks.md](workout-building-blocks.md) for exact fields and a complete draft-edit-validate-save workflow.
 
-## 3.2 Block lines
-Each top-level block gets an ordinal prefix.
+## Canonical mode
 
-### Simple block form
-```text
-1. warmup 5:00 @ 55-70% FTP
-```
-
-Or, when more explicit:
-```text
-1. warmup 5:00 target=ramp_pct_ftp(0.55->0.70)
-```
-
-### Interval-set form
-```text
-2. interval_set x3
-  2.1 work 2:00 @ 115% FTP
-  2.2 recovery 2:00 @ 50% FTP
-```
+This is an implemented review view, not a proposed future format. For the structured example in the building-blocks reference, the exact renderer output is:
 
-### Note block form
 ```text
-3. note "Stay relaxed through the shoulders"
-```
-
-## 3.3 Optional inline annotations
-Add only when present:
-- cadence
-- HR constraints
-- instructions
-
-Example:
-```text
-1. steady 8:00 @ 88% FTP cadence=90-95 note="Stay seated"
-```
-
-Or:
-```text
-1. steady 8:00 @ 88% FTP hr<=165 instructions=["Relax shoulders", "No sprint starts"]
-```
-
-## 3.4 Canonical-ish example
-
-```text
-Workout: VO2 20
+Workout: Controlled VO2 20
 Objective: vo2max
 Sport: cycling_indoor
 Execution: erg
-Constraints: indoorOnly, maxPctFtp=1.2
-
-1. warmup 5:00 target=ramp_pct_ftp(0.55->0.70)
-2. interval_set x3
-  2.1 work 2:00 target=pct_ftp(1.15)
-  2.2 recovery 2:00 target=pct_ftp(0.50)
-3. cooldown 3:00 target=ramp_pct_ftp(0.55->0.45)
-```
-
-This format is not implemented yet, but it is the right target shape.
-
----
-
-## 4. Compact text summary
-
-This is the shorter chat-friendly view.
-
-Example:
-
-```text
-WU 5m @55->70%
-3x [2m @115% / 2m @50%]
-CD 3m @55->45%
-```
-
-Or, with title/objective:
-
-```text
-VO2 20 — vo2max
-WU 5m @55->70%
-3x [2m @115% / 2m @50%]
-CD 3m @55->45%
-```
-
-This is great for:
-- quick chat confirmation
-- draft previews
-- revision summaries
-
-It is weaker for:
-- exact validation references
-- complex cadence/HR/instruction details
-- future lossless round-tripping
-
-So this should usually be considered a **preview**, not the only representation.
-
----
-
-## 5. Chat-visual preview
-
-This is the “looks good in a message thread” version.
-
-## 5.1 Linear block preview
-
-```text
-VO2 20
-[WU 5m] [WORK 2m] [REC 2m] [WORK 2m] [REC 2m] [WORK 2m] [REC 2m] [CD 3m]
- 55-70%    115%      50%      115%      50%      115%      50%     55-45%
-```
+Constraints: indoorOnly, maxPctFtp=1.2, maxDuration=20:00, maxContinuousWork=2:00
+Rationale: Three controlled two-minute VO2 efforts with equal recovery.
 
-## 5.2 Table-like list preview
-
-```text
-VO2 20
-1. Warmup    5:00  55-70%
-2. Work      2:00  115%
-3. Recovery  2:00  50%
-4. Work      2:00  115%
-5. Recovery  2:00  50%
-6. Work      2:00  115%
-7. Recovery  2:00  50%
-8. Cooldown  3:00  55-45%
+1. warmup 5:00 target=ramp_pct_ftp(0.55->0.7) instructions=["Build smoothly"]
+2. interval_set x3 cadence=85-105 instructions=["Stay seated"]
+  2.1 work 2:00 target=pct_ftp(1.15) instructions=["Do not sprint the start"]
+  2.2 recovery 2:00 target=pct_ftp(0.5)
+3. cooldown 3:00 target=ramp_pct_ftp(0.55->0.45) instructions=["Ease down gradually"]
 ```
 
-This is the best format when the user mainly wants to inspect whether the shape “looks right.”
+Header behavior:
 
----
+- Always emits `Workout`, `Objective`, `Sport`, `Execution`, `Rationale` (summary only).
+- `Execution` lists allowed modes, comma-separated; it is **not** a per-step mode declaration. An empty allowed list displays `erg` as a renderer fallback, although semantic validation still disallows non-open steps.
+- `Constraints` emits indoorOnly when true, maxPctFtp, maxDuration, maxContinuousWork, maxHrBpm when present, in that order. It omits `disallowStanding` and `avoidSprintStarts`.
 
-## 6. Mapping from structure -> text
+Blocks are numbered from 1, including notes. Interval children show `block.step`, once per pattern (not once per repetition). Simple blocks and interval sets show optional title as JSON-quoted `title=...`; interval **step titles are omitted**. Target is absent if not authored. Optional cadence, HR and nonempty instructions follow. Instruction arrays use JSON quoting. Notes render `N. note "quoted text"` and do not execute.
 
-## 6.1 Simple block mapping
+Climb output example:
 
-### Example structured block
-```json
-{
-  "id": "block-1",
-  "type": "steady",
-  "durationSec": 600,
-  "target": { "mode": "pct_ftp", "value": 0.88 },
-  "cadence": { "min": 90, "max": 95 },
-  "instructions": ["Stay seated"]
-}
-```
-
-### Expanded canonical render
 ```text
-1. steady 10:00 target=pct_ftp(0.88) cadence=90-95 instructions=["Stay seated"]
+2. climb course="Practice hill" distance=2km ascent=100m avg=5% pacing=0.85
 ```
 
-### Compact render
-```text
-Steady 10m @88% cadence 90-95
-```
+A climb can additionally show title, cadence, HR, instructions. Pacing is a **fraction**, default .85. It does not print a fake timed duration; only chat mode shows the estimated duration. Course segments, geometry, source/attribution and most other course metadata are omitted.
 
-## 6.2 Interval-set mapping
-
-### Example structured block
-```json
-{
-  "id": "block-2",
-  "type": "interval_set",
-  "repeat": 3,
-  "steps": [
-    {
-      "id": "step-1",
-      "type": "work",
-      "durationSec": 120,
-      "target": { "mode": "pct_ftp", "value": 1.15 }
-    },
-    {
-      "id": "step-2",
-      "type": "recovery",
-      "durationSec": 120,
-      "target": { "mode": "pct_ftp", "value": 0.50 }
-    }
-  ]
-}
-```
+## Compact mode
 
-### Expanded canonical render
-```text
-2. interval_set x3
-  2.1 work 2:00 target=pct_ftp(1.15)
-  2.2 recovery 2:00 target=pct_ftp(0.50)
-```
+Exact compact output for the same example:
 
-### Compact render
 ```text
-3x [2m @115% / 2m @50%]
+Controlled VO2 20 — vo2max
+WU 5m @55->70% FTP
+3x [2m @115% FTP / 2m @50% FTP]
+CD 3m @55->45% FTP
 ```
 
----
-
-## 7. Human-friendly target rendering rules
-
-To make chat output readable, we should prefer these human renderings:
-
-- `pct_ftp(0.55)` -> `55% FTP`
-- `ramp_pct_ftp(0.55->0.70)` -> `55-70% FTP`
-- `watts(300)` -> `300W`
-- `ramp_watts(180->260)` -> `180->260W`
-- `zone(z2)` -> `Z2`
-- `open` -> `open`
-- `resistance_level(35)` -> `resistance 35`
-- `grade_percent(4)` -> `grade 4%`
+Simple labels: `WU`, `STEADY`, `REC`, `CD`, `RAMP`, `OPEN` (free_ride), `CAD`, `REST`. Whole-minute durations use `Nm`; other durations use clock notation. Simple blocks can append `(cad 85-105, hr<=165)` hints. Instructions and titles are omitted. Interval output includes only count, step durations and targets—not step types, cadence, HR, titles, parent cues or instructions. Notes render `NOTE text`.
 
-Structured payload rule:
-- `%FTP` values are fractional
-- use `pct_ftp(0.55)` for `55% FTP`
-- use `pct_ftp(1.15)` for `115% FTP`
-- never send `pct_ftp(55)` or `pct_ftp(115)`
+Climb compact form is `CLIMB <name> <distance> <ascent>m avg <grade>% @<pacing-percent>% FTP est`; `est` marks the pacing assumption, not an exact ride time. It omits cadence/HR/instructions. Compact previews are useful for conversation, not safety review or preserving metadata.
 
-This matters because:
-- humans do not want to read raw JSON
-- agents still need a stable rendering convention
+## Chat mode
 
----
-
-## 8. Validation feedback and text references
-
-Current validation issues already include:
-- `code`
-- `message`
-- `path[]`
-- `severity`
-
-That is a good foundation.
-
-The text format should help translate issue paths into human-facing references like:
-- `block 2`
-- `block 2 > step 1`
-- `line 6`
-
-### Good future validation examples
+Chat mode flattens repetitions and omits notes, using sequential executable-step ordinals. Its numbering is **not** canonical block numbering. Example (two spaces separate fields):
 
 ```text
-error: block 2 > step 1 exceeds maxPctFtp constraint
-warning: block 1 cadence cue is underspecified for cadence_drill
-error: interval_set x3 causes total duration to exceed requested duration
-warning: cooldown is unusually short for threshold objective
+Controlled VO2 20 — vo2max
+1. Warmup  5:00  55->70% FTP
+2. Work  2:00  115% FTP  cad 85-105
+3. Recovery  2:00  50% FTP  cad 85-105
+4. Work  2:00  115% FTP  cad 85-105
+5. Recovery  2:00  50% FTP  cad 85-105
+6. Work  2:00  115% FTP  cad 85-105
+7. Recovery  2:00  50% FTP  cad 85-105
+8. Cooldown  3:00  55->45% FTP
 ```
 
-That would make the validate/revise loop much better in chat.
-
----
-
-## 9. Recommended representation strategy
+Cadence/HR reflect merged set/step values. Chat output omits instructions and titles, and uses source type labels (`Cadence Drill`, `Free Ride`, etc.). Climb fields are `Climb`, course name/distance/ascent, `~M:SS` estimated time, `avg grade N%`, then cadence/HR when present. The rider ends a climb by completing its virtual distance, not by waiting for that estimate.
 
-Use all three, with different purposes:
+## Exact target notation
 
-### Structured schema
-Use for:
-- storage
-- validation
-- revision
-- runtime compilation
+| Structured target | Canonical fragment | Compact/chat human target |
+| --- | --- | --- |
+| `{"mode":"open"}` | `target=open` | `open` |
+| `{"mode":"watts","value":200}` | `target=watts(200)` | `200W` |
+| `{"mode":"pct_ftp","value":0.88}` | `target=pct_ftp(0.88)` | `88% FTP` |
+| `{"mode":"zone","value":"z2"}` | `target=zone(z2)` | `Z2` |
+| `{"mode":"ramp_watts","start":100,"end":180}` | `target=ramp_watts(100->180)` | `100->180W` |
+| `{"mode":"ramp_pct_ftp","start":0.55,"end":0.7}` | `target=ramp_pct_ftp(0.55->0.7)` | `55->70% FTP` |
+| `{"mode":"resistance_level","value":35}` | `target=resistance_level(35)` | `resistance 35` |
+| `{"mode":"grade_percent","value":4}` | `target=grade_percent(4)` | `grade 4%` |
 
-### Expanded canonical text
-Use for:
-- careful review
-- agent reasoning
-- diffing
-- future parser/renderer contract
+Compact prefixes target text with `@`; chat does not. Missing target prints no fragment; explicit open prints `open`. Values use fractions in JSON, not whole percentages. Formatting rounds general numeric values to at most two decimal places and distances to one decimal km; it is not an exact numeric serialization. Clock durations use M:SS below one hour and H:MM:SS above it.
 
-### Compact/chat-visual render
-Use for:
-- chat previews
-- quick approval loops
-- human readability
+Cadence rendering selects `min-max`, `min+`, `<=max`, then cue text, then literal `cue` for an empty object. When numerical bounds exist, cue text is not shown. HR rendering chooses `hr<=capBpm` when present, otherwise `hrSoft<=softCapBpm`; **it does not display both**, whereas compilation uses the lower of both as a safety bound. Review structured HR before execution.
 
----
+## Validation references
 
-## 10. Practical examples for chat interfaces
-
-## 10.1 User says: "Create me a 20 min session with 3 hard intervals"
-
-Agent could reply with:
+`describeWorkoutPath(["blocks","1","steps","0","repeat","2","hr"])` returns:
 
 ```text
-Draft preview — VO2 20
-WU 5m @55->70%
-3x [2m @115% / 2m @50%]
-CD 3m @55->45%
+block 2 > step 1 > repeat 3 > hr
 ```
 
-And optionally also keep the canonical-ish version for internal validation/revision.
-
-## 10.2 User says: "Make it slightly easier"
-
-Agent could show a diff-like preview:
+Indices in issue paths are zero-based strings; display ordinals are one-based. Empty path renders `workout`. Non-block paths become dot-separated (`constraints.maxDurationSec`). `renderValidationIssues` returns an array of lines:
 
 ```text
-Before:
-3x [2m @115% / 2m @50%]
-
-After:
-3x [2m @110% / 2m @50%]
+- error [block 2 > step 1 > repeat 3] target.intensity.exceeds_max_pct_ftp: Target intensity 130% FTP exceeds maxPctFtp 120%.
 ```
 
-That makes revision feel concrete.
-
-## 10.3 User says: "Too long — shorten it"
-
-Agent could show:
-
-```text
-Before:
-WU 5m
-3x [2m @115% / 2m @50%]
-CD 3m
-
-After:
-WU 4m
-3x [2m @112% / 90s @50%]
-CD 2m
-```
-
-That is much easier to approve in chat than raw JSON.
-
----
-
-## 11. Recommended next implementation follow-on
-
-The next practical code step after this doc should probably be:
-
-1. add a renderer helper that turns structured workouts into:
-   - expanded canonical text
-   - compact text summary
-   - chat-visual preview
-2. use that renderer in CLI/docs/tests
-3. later decide whether we want a reverse parser for a canonical text form
-
-Important sequencing point:
-- renderer first
-- parser later, only if it proves valuable
-
----
-
-## 12. Current implementation status
-
-Currently implemented:
-- `renderWorkoutText(workout, { mode: "compact" | "canonical" | "chat" })` in `packages/domain`
-- compact preview is now used in planner CLI workout summaries where a full structured workout is available
-
-Not implemented yet:
-- reverse parser from text -> workout structure
-- line-stable validation references in CLI output
-- richer diff renderers for workout revisions
+Human-friendly references already exist; line-stable references and a general revision-diff renderer/parser are not implemented. Use actual issue code/message/path, not invented coaching warnings (there is no general “cooldown too short” or “cadence drill underspecified” check).
 
-## 13. Bottom line
+## Review workflow
 
-The workout schema should stay canonical.
-But for chat interfaces, agents need a stable text form that sits between:
-- raw JSON
-- vague prose
+1. Keep structured candidate JSON, including full metadata, constraints and course attribution.
+2. Render canonical for block review; compact for a short user preview; chat for expanded execution order.
+3. Validate the structured candidate and inspect computed duration plus runtime plan. Renderer functions do not validate or recompute stale artifacts.
+4. Make edits in structured JSON or supported revision operations; render again if useful.
+5. Save the reviewed JSON with validation/version guards. Text previews are never a substitute for the saved definition.
 
-That is the real leverage point.
+Do not round-trip through any text view: all omit IDs, version/actor timestamps, tags, athlete context and important details. There is no implemented plain-text input grammar, no automatic text-to-workout import, and no promise of lossless text diffs.