Skip to content

Docs: mark M4 complete, and move the "what it turned out to mean" out of the roadmap - #30

Merged
kjpatel merged 2 commits into
mainfrom
docs/roadmap-is-a-plan-not-a-changelog
Jul 31, 2026
Merged

Docs: mark M4 complete, and move the "what it turned out to mean" out of the roadmap#30
kjpatel merged 2 commits into
mainfrom
docs/roadmap-is-a-plan-not-a-changelog

Conversation

@kjpatel

@kjpatel kjpatel commented Jul 31, 2026

Copy link
Copy Markdown
Owner

The roadmap had become a changelog. This marks M4 complete and moves the accumulated detail somewhere it belongs.

The drift, measured

Milestone Words
M0–M3 (complete) 46, 132, 151, 210
M4 (before) 730
M4 (after) 189

The shape of it is legible inside M4 itself: the four bullets ticked before this milestone's habit took hold run 10–19 words; the five ticked during it run 50–174. A plan that records outcomes stops being scannable as a plan — which is the job the roadmap is the only document doing.

The v1.2 what-if bullet got the same treatment: 143 → 37 words.

v1.3+ is still 503 words across three bullets, but that is unshipped work where the length is design rationale rather than accumulated results. Different problem; left alone.

The detail is moved, not deleted

New CHANGELOG.md carries what each release turned out to mean — the material a reader wants when asking why is this the way it is, and exactly the wrong material to meet them in a list of what comes next:

  • the DMN acceptance criterion that was unachievable as written ("same decision and receipt" — a receipt pins its pack's identity, so two packs cannot match)
  • the equivalence proof that turned out fixture-bounded, and why that motivated pack equivalence in the verifier
  • the what-if guard that proves answer-checking alone is insufficient — the kernel confirms the wrong date a broken encoding produces; only the boundary check catches it
  • prove's non-zero exit being a differential check between two proof systems, not a routine gate
  • the three architecture claims the work sharpened, and the two-halves-of-a-pack distinction
  • the corpus never being regenerated once across twenty-one PRs

Older releases get short back-fill entries so the file is complete rather than starting mid-history.

An error caught while condensing

My first draft gave M4 a tenth bullet for what-if queries. What-if is a v1.2 item that shipped early and was already ticked there — M4 legitimately has nine. That is the same mistake that produced the duplicate OR-Tools bullet earlier today: assuming where an item lives instead of checking. Found by counting bullets before and after rather than trusting the edit.

Verification

Docs only. demo/tests 28 passed. Zero orphaned docs, zero broken links or anchors — and a check that every link removed from the roadmap is still reachable from either the README or the changelog, so condensing lost no reference.

CHANGELOG.md is linked from the roadmap intro and from CLAUDE.md's documentation map, so it does not repeat the discoverability failure that #24 and #25 had to clean up.

kjpatel and others added 2 commits July 30, 2026 17:41
… of the roadmap

The roadmap had become a changelog. M4 ran to 730 words against 46/132/151/210
for M0–M3, and the shape of the drift is legible in the bullets themselves: the
four ticked before this milestone's habit took hold run 10–19 words, the five I
ticked run 50–174. A plan that records outcomes stops being scannable as a plan.

M4 is marked complete and its bullets are one line each, matching the density of
every milestone before it — 730 words to 189. The v1.2 what-if bullet gets the
same treatment (143 to 37).

The detail is moved, not deleted. CHANGELOG.md now carries what each release
turned out to mean: the acceptance criterion that was unachievable as written,
the equivalence proof that turned out to be fixture-bounded, the guard that
proves answer-checking alone is insufficient, the three architecture claims the
work sharpened, and the corpus never being regenerated once across twenty-one
PRs. That is the material a reader wants when asking why something is the way
it is, and it was the wrong material to meet them in a list of what is next.

Caught while condensing: my draft added a tenth M4 bullet for what-if, which is
a v1.2 item that shipped early and was already ticked there. That is the same
error that produced the duplicate OR-Tools bullet — assuming where an item lives
rather than checking. Removed; M4 has nine.

Docs only. Zero orphaned docs, zero broken links or anchors; every link removed
from the roadmap is still reachable from the README or the changelog.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
pyproject.toml has stayed at 0.0.1 through v0.1.0, v0.2.0, and v0.3.0 — the
tags mark milestones, and nothing is published. Worth stating in the changelog
rather than leaving a reader to infer a distribution that does not exist:
installable packaging is an M5 item, and a tag says "this milestone is done and
here is what it meant", not "the contract is stable".

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@kjpatel
kjpatel merged commit caf0eb2 into main Jul 31, 2026
2 checks passed
@kjpatel
kjpatel deleted the docs/roadmap-is-a-plan-not-a-changelog branch July 31, 2026 00:45
kjpatel added a commit that referenced this pull request Jul 31, 2026
The changelog said twenty-one and the v0.4.0 release notes said twenty-three;
the actual count between the tags is twenty-five, #6 through #30. Both numbers
were guesses from PR numbers rather than counts of the commit range, and they
disagreed with each other, which is how the error surfaced.

`git log v0.3.0..v0.4.0 --oneline | grep -cE "\(#[0-9]+\)"` is the number. It
is higher than a count of "M4 work" would suggest because v0.3.0 was tagged
retroactively at #5, so the range legitimately includes the roadmap
restructure, the authoring guide, and the corpus-coverage work that preceded
the milestone proper.

The published release notes are corrected to match.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant