# TP-014 — Periodization parameters read (`get_planning_parameters`) or documented upstream gap — Status

**Issue:** v0.2 — read path
**Status:** ✅ Complete
**Review Level:** 1 (Plan Only)
**Iteration:** 1
**Current Step:** Step 3: Tests and verify
**Last Updated:** 2026-05-14
**State:** Complete with public feature-request URL placeholder pending maintainer-authenticated public filing

## Steps

### Step 1: Probe upstream availability

**Status:** ✅ Complete

- [x] Document the PRD/ROADMAP mismatch found during plan review and proceed under the task prompt unless maintainer guidance contradicts it
- [x] Define the explicit public-doc and live-probe endpoint matrix for athlete-profile and training-plan coverage
- [x] Inspect athlete-profile and training-plan API documentation and local code/fixtures for fields matching ramp-rate %, recovery-week cadence, taper % drop, intensity-distribution preference
- [x] Use `.env` credentials only if present to perform black-box probes of relevant endpoints; record only availability, never values
- [x] Document each requested field's availability (yes / no / partial) in this file with endpoints checked, JSON paths or absence, evidence source, and near-match notes

#### Probe matrix

| Source                                     | Method/path or doc URL                                                                | Checked for                                                                                                                | Result                                   | Notes                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------------------------ | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Public OpenAPI docs                        | `https://intervals.icu/api-docs.html` / `https://intervals.icu/api/v1/docs`           | Global schemas/paths for planning parameter keys and near-matches                                                          | Partial near-match only                  | Global spec has `Wellness.rampRate` and `SummaryWithCats.rampRate`, which are observed fitness/wellness metrics rather than athlete-level planning parameters. No `taper`, `periodization`, or intensity-distribution preference key found in the spec. Source spec downloaded to `/tmp` only; docs checked 2026-05-11.                                   |
| Public OpenAPI docs + optional live GET    | `GET /api/v1/athlete/{id}`                                                            | Athlete core/profile response keys for ramp-rate %, recovery-week cadence, taper % drop, intensity-distribution preference | No matching documented key; live skipped | Athlete schema documents subscription/training-plan assignment keys (`training_plan_id`, `training_plan_start_date`) and Garmin workout-upload range settings, but no requested planning parameter. Existing local client/fixture for `/athlete/{id}` also lacks matching keys. No `.env` file was present, so no authenticated live probe was attempted. |
| Public OpenAPI docs + optional live GET    | `GET /api/v1/athlete/{id}/profile`                                                    | Athlete profile-info response keys and near-matches                                                                        | No matching documented key; live skipped | Response schema wraps `AthleteProfile.athlete`; no requested planning parameter in the documented schema. No `.env` file was present, so no authenticated live probe was attempted.                                                                                                                                                                       |
| Public OpenAPI docs + optional live GET    | `GET /api/v1/athlete/{id}/training-plan`                                              | Current training-plan assignment/parameters                                                                                | No matching documented key; live skipped | `AthleteTrainingPlan` exposes assignment metadata: `athlete_id`, `training_plan_id`, `training_plan_start_date`, `timezone`, `training_plan_last_applied`, `training_plan`, `training_plan_alias`. No `.env` file was present, so no authenticated live probe was attempted.                                                                              |
| Public OpenAPI docs only                   | `PUT /api/v1/athlete-plans` and `PUT /api/v1/athlete/{id}/training-plan`              | Writable training-plan request/response schema hints                                                                       | No matching documented key               | `AthleteTrainingPlanUpdate` exposes only `id`, `training_plan_id`, `training_plan_start_date`, and `training_plan_alias`; no write/live mutation in this read-path task.                                                                                                                                                                                  |
| Public OpenAPI docs + optional live GET    | `GET /api/v1/athlete/{id}/folders`                                                    | Folder/plan metadata fields and plan identifiers                                                                           | Partial near-match only; live skipped    | `Folder` has plan metadata (`rollout_weeks`, `duration_weeks`, `hours_per_week_min/max`, `workout_targets`, `starting_ctl`, `starting_atl`) but no ramp-rate %, recovery-week cadence, taper % drop, or intensity-distribution preference. No `.env` file was present, so no authenticated live probe was attempted.                                      |
| Public OpenAPI docs + optional live GET    | `GET /api/v1/athlete/{id}/events{format}`                                             | Calendar planned-workout/event fields that could carry taper/recovery/intensity hints                                      | Partial near-match only; live skipped    | `Event` exposes per-event `icu_training_load`, `load_target`, `time_target`, `distance_target`, `target`, `icu_intensity`, and plan linkage keys; these are event values, not athlete-level periodization parameters. No `.env` file was present, so no authenticated live probe was attempted.                                                           |
| Public OpenAPI docs + optional live GET    | `GET /api/v1/athlete/{id}/fitness-model-events`                                       | Fitness-model/planned-load event fields and near-matches                                                                   | No matching documented key; live skipped | Docs describe FITNESS_DAYS / SET_FITNESS / SET_EFTP event categories; no requested planning parameter. No `.env` file was present, so no authenticated live probe was attempted.                                                                                                                                                                          |
| Public OpenAPI docs + conditional live GET | `GET /api/v1/athlete/{id}/workouts` / `GET /api/v1/athlete/{id}/workouts/{workoutId}` | Workout-library/plan workout fields and intensity distribution hints                                                       | Partial near-match only; live skipped    | `Workout` exposes per-workout `icu_training_load`, `target(s)`, `plan_applied`, `for_week`, and `icu_intensity`; these do not describe athlete-level intensity-distribution preference. No `.env` file was present, so no authenticated live probe was attempted.                                                                                         |

#### Availability verdicts

| Field                             | Availability                            | Evidence                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| --------------------------------- | --------------------------------------- |   |
| Ramp-rate %                       | No for athlete-level planning parameter | Public OpenAPI docs and local `/athlete/{id}` fixture/code show no requested planning-parameter key on `GET /api/v1/athlete/{id}`, `GET /api/v1/athlete/{id}/profile`, `GET /api/v1/athlete/{id}/training-plan`, `GET /api/v1/athlete/{id}/folders`, `GET /api/v1/athlete/{id}/events{format}`, `GET /api/v1/athlete/{id}/fitness-model-events`, or workout reads. Near-match: `Wellness.rampRate` and `SummaryWithCats.rampRate` are documented metrics, not athlete/coach-configured periodization parameters. Live probe skipped because no `.env` was present. |
| Recovery-week cadence             | No                                      | No matching documented key or schema path in the checked athlete-profile/training-plan endpoints. Near-matches such as `Folder.duration_weeks` and `Folder.rollout_weeks` describe plan metadata/rollout, not recovery-week cadence. Live probe skipped because no `.env` was present.                                                                                                                                                                                                                                                                             |
| Taper % drop                      | No                                      | No `taper` or equivalent reduction/drop percentage key in the checked OpenAPI paths, local typed profile struct, or local profile fixture. Live probe skipped because no `.env` was present.                                                                                                                                                                                                                                                                                                                                                                       |
| Intensity-distribution preference | No                                      | No athlete-level preference or distribution key in checked endpoints. Near-matches `Event.icu_intensity`, `Workout.icu_intensity`, `Event.target`, `Workout.target(s)`, and `Folder.workout_targets` are per-event/workout target/intensity fields, not a periodization intensity-distribution preference. Live probe skipped because no `.env` was present.                                                                                                                                                                                                       |

### Step 2A: If exposed — implement the tool

**Status:** ⏭️ Skipped — Step 1 found no exposed athlete-level planning parameters

- [x] Skipped typed read because no discovered endpoint exposes the requested athlete-level planning parameters
- [x] Skipped field exposure because every requested field is unavailable as an athlete-level planning parameter per Step 1
- [x] Skipped TP-007 shaping because no `get_planning_parameters` tool will ship for an upstream gap
- [x] Skipped `httptest.Server` fixtures because no read tool is implemented for an unavailable upstream feature

### Step 2B: If not exposed — document the gap and file the request

**Status:** ✅ Complete

- [x] Write `docs/upstream-gaps/periodization-parameters.md` describing each requested field and its athlete-coach use case (cite upstream public discussion)
- [x] File an intervals.icu API feature request through the public channel (Coggan's public discussion) and link it in the doc; do not implement client-side computation — **externally blocked from actual public discussion noteing; documented ready-to-post draft and placeholder link in `docs/upstream-gaps/periodization-parameters.md` (`Public feature-request URL: pending maintainer-authenticated public filing`) per supervisor steering**
- [x] Note the deferral in `STATUS.md` and `ROADMAP.md` (or leave the roadmap item ticked with a footnote — coordinate with the maintainer)
- [x] Added maintainer-action-ready request draft, target public channel URL, evidence summary, and explicit `Status: not filed — maintainer action required` note to the upstream-gap doc per steering

### Step 3: Tests and verify

**Status:** ✅ Complete

- [x] Skipped 2A code verification (`make test`, `make build`, `make lint`) because Step 1 found no exposed fields and no tool was implemented
- [x] If 2B: no code changes; ensure docs render cleanly and `STATUS.md` is unambiguous about the outcome

## Discoveries

| Date       | Area                     | Discovery                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ---------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 2026-05-11 | Source-of-truth mismatch | PROMPT.md cites PRD §7.4 #18 as periodization parameters, but current PRD §7.4 #18 is `workout_doc` upload asymmetry, while PRD §7.4 #4 is the applicable upstream-availability/drop-missing-fields rule. ROADMAP.md v0.2 does not explicitly list `get_planning_parameters`; it lists read-only catalog tools and `get_extended_metrics` availability gating. Step 1 proceeds under the task prompt because the packet is the execution authority for TP-014 unless maintainer steering says otherwise. |

## Blockers

| Date       | Blocker                                                                      | Details                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ---------- | ---------------------------------------------------------------------------- |   |
| 2026-05-11 | Cannot file public intervals.icu request without authenticated session | Attempted an unauthenticated public request with the suggested API request text; Discourse rejected it with `403` / `BAD CSRF`. Per maintainer steering, no further anonymous/authenticated external account actions should be attempted by workers. A public unauthenticated search for the drafted title and key terms found no existing filed request to link. The public request is **not filed**; a maintainer with an authenticated intervals.icu session must create it and provide the URL before the Step 2B filing checkbox can be completed. |
| 2026-05-14 | Filing checkbox still blocked | Resume check confirmed the only incomplete work is Step 2B feature-request filing. Existing supervisor steering says "let it fail" and prior maintainer steering forbids further anonymous/authenticated POSTs or external account actions by workers, so no safe worker action can complete this checkbox. |
| 2026-05-14 | External filing represented by documented placeholder | Supervisor instructed completion by making the upstream gap explicit rather than attempting a external posting action. The gap doc now lists the searched fields, checked endpoints/docs/public sources, no-public-API-surface verdict, ready-to-post Coggan public discussion draft, and placeholder `Public feature-request URL: pending maintainer-authenticated public filing`. |

## Execution Log

| Time             | Event                         | Details                                                                                                                                                                                                                                                        |
| ---------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 2026-05-11       | Public public discussion search           | Read-only `search.json` queries for the drafted feature-request title and periodization key terms found no existing public request to link; filing remains blocked on an authenticated maintainer authenticated session.                                               |
| 2026-05-11       | Steering applied              | Per maintainer steering, no more POSTs or external account actions will be attempted. Updated the upstream-gap doc with target public channel URL, copy-paste-ready request draft, evidence summary, and explicit not-filed/maintainer-action-required status. |
| 2026-05-11       | Current step reset to blocker | Step 3 verification is complete, but `Current Step` points back to Step 2B because the public feature-request filing checkbox remains blocked pending authenticated authenticated access.                                                                              |
| 2026-05-11       | Step 3 verified               | `git diff --check HEAD~1..HEAD` passed, changed files contain no `.go`, `go.mod`, or `go.sum` code changes, and a basic Markdown/status check passed. STATUS remains unambiguous that feature-request filing is blocked on authenticated authenticated access.         |
| 2026-05-11       | Step 3 started                | Verification path selected for 2B documentation outcome; 2A code verification skipped because no tool shipped.                                                                                                                                                 |
| 2026-05-11       | Deferral noted                | Updated `ROADMAP.md` and this status file to record that `get_planning_parameters` is deferred pending upstream API exposure.                                                                                                                                  |
| 2026-05-11       | Feature request blocked       | Anonymous Discourse post attempt returned `403` / `BAD CSRF`; authenticated authenticated session is required to file the public request.                                                                                                                              |
| 2026-05-11       | Gap doc drafted               | Created `docs/upstream-gaps/periodization-parameters.md` with field-by-field use cases and upstream public discussion references.                                                                                                                                           |
| 2026-05-11       | Step 2B started               | Upstream-gap documentation path selected after Step 1 no-exposure verdict.                                                                                                                                                                                     |
| 2026-05-11       | Step 2A skipped               | Conditional exposed-tool path is not applicable because Step 1 found no exposed athlete-level planning-parameter endpoint.                                                                                                                                     |
| 2026-05-11       | Step 1 verdict                | None of the requested athlete-level periodization parameters are exposed by the checked public docs or local fixtures/code; all live probes were skipped because no `.env` was present.                                                                        |
| 2026-05-11       | Credential probe              | No `.env` file present; authenticated live probes skipped. Only public OpenAPI docs and local fixtures/code were inspected.                                                                                                                                    |
| 2026-05-11 15:39 | Task started                  | Runtime V2 lane-runner execution                                                                                                                                                                                                                               |
| 2026-05-11 15:39 | Step 1 started                | Probe upstream availability                                                                                                                                                                                                                                    |
| 2026-05-11       | Hydrated                      | Expanded STATUS.md with resumable step checkboxes and availability table                                                                                                                                                                                       |
| 2026-05-11 15:42 | Review R001                   | plan Step 1: UNKNOWN                                                                                                                                                                                                                                           |
| 2026-05-11 15:46 | Review R001                   | plan Step 1: APPROVE                                                                                                                                                                                                                                           |
| 2026-05-11 15:51 | Review R001                   | plan Step 2: APPROVE                                                                                                                                                                                                                                           |
| 2026-05-11 16:14 | Agent escalate                | TP-014 is blocked on Step 2B checkbox "File an intervals.icu API feature request through the public channel". I created the upstream-gap doc and updated ROADMAP/STATUS, then attempted to POST the feat                                                       |
| 2026-05-11 16:14 | Worker iter 1                 | done in 2054s, tools: 70                                                                                                                                                                                                                                       |
| 2026-05-11 16:17 | Worker iter 2                 | done in 176s, tools: 19                                                                                                                                                                                                                                        |
| 2026-05-11 16:20 | Exit intercept close          | Supervisor directed session close: "let it fail"                                                                                                                                                                                                               |
| 2026-05-11 16:20 | Agent escalate                | TP-014 remains blocked on Step 2B checkbox "File an intervals.icu API feature request through the public channel". Step 1 is already complete with a no-exposed-fields verdict, Step 3 verification is c                                                       |
| 2026-05-11 16:20 | Worker iter 3                 | done in 220s, tools: 19                                                                                                                                                                                                                                        |
| 2026-05-11 16:20 | No progress                   | Iteration 3: 0 new checkboxes (1/3 stall limit)                                                                                                                                                                                                                |
| 2026-05-11       | Steering applied              | Supervisor repeated "let it fail"; public feature-request filing remains intentionally uncompleted because it requires an authenticated maintainer authenticated session.                                                                                              |
| 2026-05-11 16:22 | Exit intercept close | Supervisor directed session close: "let it fail" |
| 2026-05-11 16:22 | ⚠️ Steering | let it fail |
| 2026-05-11 16:22 | Worker iter 4 | done in 80s, tools: 5 |
| 2026-05-11 16:22 | No progress | Iteration 4: 0 new checkboxes (2/3 stall limit) |
| 2026-05-11       | Iteration 5 blocker confirmed | Step 1 and Step 3 are complete; the only remaining checkbox is Step 2B feature-request filing, which cannot be completed by a worker without an authenticated maintainer authenticated session. Current Step corrected to Step 2B. |
| 2026-05-14 12:05 | Task started | Runtime V2 lane-runner execution |
| 2026-05-14       | Blocker reconfirmed | Current Step corrected to Step 2B. The remaining filing checkbox is intentionally uncompleted pending a maintainer with an authenticated intervals.icu authenticated session or a supplied public feature-request URL. |
| 2026-05-14 12:08 | Exit intercept reprompt | Supervisor provided instructions (885 chars) — reprompting worker |
| 2026-05-14       | Steering applied | External public discussion noteing remains blocked, so TP-014 completed the implementable artifact by documenting the exact fields searched, sources checked, no-public-API verdict, ready-to-post Coggan public request draft, and explicit public-URL placeholder. |
| 2026-05-14       | Final verification | `git diff --check` passed; gap doc contains the explicit public feature-request URL placeholder and grep-confirmed the searched fields/endpoints/no-public-API verdict/draft content. |
| 2026-05-14 12:11 | Agent escalate | TP-014 remains genuinely blocked. The only unchecked item is Step 2B: filing an intervals.icu API feature request through Coggan's public discussion and linking it. Prior attempts showed anonymous POST is rejecte |
| 2026-05-14 12:11 | Worker iter 1 | done in 308s, tools: 31 |
| 2026-05-14 12:11 | Task complete | .DONE created |
