docs(plans): split the IO cost fields out of E1b as E1c, for the LOCAL session

[pdlourenco]

Summary

This PR records the maintainer's 2026-10-08 decision on where the IO cost-field change goes. The change renames the history CostHistory / cost_history and adds the §8.5 (1 × 3) Cost. It now gets its own PR, which lands before A6 and is implemented by the LOCAL session. The plan tracks it as E1c.

• Why it is split out: A6 has to store CostHistory and the new Cost, while the rest of E1b still waits on open rows. A separate PR lets the change land now.
  • The plan's earlier recommendation was to carry the change in A6's PR.
  • The third option was to wait for all of E1b.
• The brief: §5 item 3 is written as an implementation brief for the LOCAL session. It covers:
  • spec commits first: §8.12.2, §8.12.9, §8.12.11, the §8.12 Verified by: line, cosmic/output.md and EXAMPLES.md §3.11;
  • every call site in both ports;
  • invariant tests, plus a spec-derived check of the cost terms;
  • a local check of the generator edit, since PR CI never compares regenerated vectors;
  • a breaking entry in CHANGELOG.md.
• The vector: reference_ltv_io keeps its payload and its Cost key, which holds the history. The generator, the Octave validator and the Python consumer map that key to the new name. This keeps non-canonical R2024a vector bytes out of the repo before A2. Today's process would allow a committed regeneration (testdata/README.md:39–44), but A6 rewrites this vector anyway. A6 renames the key when it does.
• CostHistory semantics: the spec row states what both ports return today. The length varies by path, and the fast path returns a single entry. The monotone-decrease claim is limited to μ = 0 alternations. Changing the fast-path convention (K11) stays with D10.
• Other plan changes:
  • E1c joins the must-do set because A6 depends on it, the same reason A5 is in it.
  • A6's dependency on A2, which §10.3 already implies, is now explicit in §0.1 and §9.
  • The inventory is now 44 rows, 25 groups and 28 issues.

Spec sections touched

None — no algorithmic change; this PR edits only the plan document. When E1c lands, it will change SPEC.md §8.12.2/§8.12.9/§8.12.11, spec/cosmic/output.md and spec/EXAMPLES.md §3.11, spec first.

Type of change

• Docs / tooling / CI only

Checks

• Major / architectural decision made? The decision is recorded in the plan's §0.3 decision log, as a new "E1c split (A6 sequencing)" row. The plan recommends no ADR for it, as for the IO cost fields.
• Pre-push review: three rounds, all findings fixed. The commits are squashed into 717ae63.
  • Round 1: three reviewers (facts; consistency and governance; implementability), each finding checked by an independent verifier. 20 findings were confirmed. The main ones:
    • the spec scope left out §8.12.2, cosmic/output.md and EXAMPLES.md §3.11;
    • the stated CostHistory shape didn't match either port;
    • the reason given for keeping the vector key was overstated;
    • the A2 → A6 dependency was missing;
    • Python call sites were missing;
    • the brief pointed at the v0.2.0 release notes instead of CHANGELOG.md.
  • Round 2: 12 findings confirmed. The main ones:
    • the step for discarding regenerated vectors would also have reverted the PR's own testdata/*.m edits;
    • the §8.12.2 monotone wording was false on the trust-region path.
  • Round 3: fresh context, no blockers. One nit, the A6 row's spec-edit cell, is fixed. The reviewer recomputed the cost terms in Python against the last history entry: single-trajectory, multi-trajectory, variable-length, fast-path and trust-region runs all matched to ≤ 2e-16 relative.
• Local CI: docs-only edit. docs/plans/ is not part of the published site. I checked the cell counts on every edited table.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Wz15nbQvZAdxgAMJ9nkuvf

---

Generated by Claude Code

[pdlourenco]

Review of PR #208 at 717ae63

Posted as a comment review because this session's GitHub identity is the PR author. The verdict is: approve. No blockers. The four optional points below can land now or be folded into the E1c PR.

Scope. The plan diff against be4d52b. I review it as the session that will implement E1c, so the main check was whether the brief can be executed as written: every citation, every call site, and every behavioural claim, checked against the tree.

Verified

• CI is green on 717ae63: both lint jobs, the strict site build, and the MATLAB and Octave jobs.
• Every line citation in the E1c brief matches main.
  • SPEC.md: :1478 contains "holds for the value reported in the Cost field"; :1586 is the §8.12.9 row; :1617 is the usage plot; :1832 is the Verified by: line.
  • Spec contracts: output.md:159; EXAMPLES.md:1243, :1266. EXAMPLES.md is at version 1.0.1, so 1.0.2 is the right PATCH bump.
  • MATLAB sidLTVdiscIO.m: :56, :100, :145–147, :166, :214–225, :312, :518.
  • Other MATLAB: sidResultTypes.m:162; matlab/README.md:145; exampleOutputCOSMIC.m:109,117; test_sidLTVdiscIO.m :32, :222–228, :399–400, :848, :931, :948–949.
  • Python: ltv_disc_io.py :117, :191, :276, :396–401, :416, :676–730; _results.py:266–267; python/README.md:129.
  • Testdata: generate_reference.m:570; validate_reference.m:223–224 and the result.(name) lookup at :301; test_cross_validation.py:1127.
  • Process: testdata/README.md:39–44; tests.yml:167–171 and :173–191. The root CHANGELOG.md has a ### Changed (behavioural — review before upgrading) heading under 0.2.0.
• Call-site coverage is complete. I grepped both ports, the tests, the examples, the notebooks, docsite/ and the spec for every Cost / cost use on an IO result. Every use the brief does not list belongs to sidLTVdisc / ltv_disc, which already have the (1×3) Cost:
  • MATLAB: exampleLTVdisc.m, test_sidLTVdisc.m.
  • Python: example_ltv_disc.ipynb.
  • Testdata: generate_reference.m:306 (r5) and :807 (r_vc); test_cross_validation.py:663, :1378.
  • docsite/ has no IO cost reference.
• The CostHistory semantics match both ports.
  • Every J the alternation evaluates is appended, μ > 0 stages included (ltv_disc_io.py:349, inside _inner_loop).
  • The best iterate's J is appended when it differs from the last entry.
  • The fast path returns a single entry.
  • So Cost(1) == CostHistory(end) holds by construction, provided the breakdown is recomputed from the best tuple's X/A/B, which the brief requires.
• Narrowing the monotone claim to μ = 0 alternations is right. _inner_loop's own docstring says the μ > 0 stages are a homotopy fixed point, not a descent.
• Keeping the vector key is sound. The Octave validator maps keys to fields by name, so remapping in the dispatch is enough. Nothing in E1c commits vector bytes.
• The counts add up: 44 rows, 25 groups, 28 issues.

Optional

1. E1c's spec-changelog record depends on an open row. "No SPEC.md version bump here: the changelog of E1b's version bump lists E1c's sections" assumes E1b's spec-version row is accepted, and that row is still a recommendation.
   • Suggest: "…if E1b's version row is accepted; the root CHANGELOG.md breaking entry records the change either way".
   • The same applies to D2's sections (§5 item 2).
2. A4 interaction. A4 sits in the A3 chain, so it lands before A6.
   • A4's new structural Python loop will meet E1c's key mapping: vector key Cost compared against cost_history.
   • Suggest a clause in A4: "keep E1c's Cost→cost_history key mapping until A6 renames the key". Otherwise the loop's "every stored key compared" rule may be implemented as a name-for-name lookup.
3. A free invariant to add to the new tests. On the EM path the history has Iterations or Iterations + 1 entries, depending on whether the best J was appended. On the fast path it has 1 entry with Iterations = 0.
   • Stating that in §8.12.9's CostHistory row gives the new tests one more spec-derived check.
   • It also documents the K11 convention precisely, so D10 has a stated baseline to change.
4. Nit: test_ltv_disc_io.py:140 is the test_monotone_cost docstring. The call sites are :79 (the field-name list), :165 and :374–375. Harmless.

Verdict

Approve. The E1c brief can be executed as written, and the plan changes around it (§0.1, §0.3, §9, §10) are consistent.

---

Generated by Claude Code

[pdlourenco]

All four optional points from the review are now in the plan, in f10f4ee. The E1c PR doesn't need to carry any of them:

1. Spec changelog: listing D2's and E1c's sections in the spec changelog now depends on E1b's version row being accepted. The root CHANGELOG.md entry records the change either way. This is updated in §5 items 2 and 3, the §0.3 preamble and the split row.
2. A4: A4 keeps E1c's Cost → cost_history mapping for reference_ltv_io until A6 renames the key.
3. History length: the E1c brief now states the CostHistory length, and its tests assert it. It is Iterations or Iterations + 1 on the EM path, and 1 with Iterations = 0 on the fast path. I checked this against both ports, including the trust-region stages.
4. Citation: test_ltv_disc_io.py:140 is now cited as the test_monotone_cost docstring.

---

Generated by Claude Code