Replace the competing README visuals with one lifecycle diagram - #752
Replace the competing README visuals with one lifecycle diagram#752MongLong0214 wants to merge 6 commits into
Conversation
Two SVGs sat above the fold in incompatible art directions -- a warm editorial diagram and an animated dark terminal recording -- so the first screen read as two templates rather than one product. The recording is retired and the hero replaced. The new hero is a static 840x340 diagram: Git history on the left, current context in the middle, next edit on the right, with the active decision reaching the panel and the superseded one stopped by a dashed connector and an X. No animation, no external fetch, no gradient, 35 rendered words. Three departures from the handoff's reference skeleton, each because following it exactly would have shipped something worse: The skeleton put SUPERSEDED in the top slot, and the handoff's own rule says the superseded row must not take the eye first. The hero being replaced already had the active row on top, so copying the skeleton would have broken a property that already held. Newest-first also matches what `git log` shows, so a column labelled GIT HISTORY now reads the way the tool it names does. The skeleton's next-edit column mixed two x positions for one phrase and carried a green dot that competed with the arrow already supplying the accent -- a fourth green mark in the region the handoff ranks fourth for attention. The dot is gone under the "no decorative illustration" rule rather than under "the forbidden list does not mention it", which would be the weaker argument. Its removal is why the three lines needed realigning at all. Panel padding is 16 rather than 22 on both sides. "Checkout pricing only" at 24px lands within about two pixels of the old 284px limit on a wide system font, and this font stack resolves to whatever the reader's OS provides, so the margin was thin on somebody else's machine rather than on mine. `commitlore demo`, its scenario, and its tests are untouched. What is deleted is the README recording asset, the generator that existed only to produce it, and that generator's byte-identity test. Limit: at 375px the README embeds at width="100%", so the 840px canvas scales by 0.446 and the 18px labels land near 8px -- better than the 1200px canvas it replaces (7.5px) and still under the 12px a caption usually needs; three columns and this copy do not fit under a 700px canvas, so the canvas question is unresolved rather than answered Blast: local Undo: easy Certainty: firm Record-Id: r-onevisual Provenance: authored Verified: five negative controls each fail the intended assertion and pass after restore -- restoring the demo block, adding a `set` animation, replacing the alt with an absolute claim, deleting `desc`, and putting the superseded row back on top; 62 tests across the hero and README suites pass, and `git grep` finds no remaining reference to the retired asset or its generator outside historical tickets CommitLore-Version: 2.0.0
CommitLore — record lintTrailers: clean — 6 commits in Trailer violations fail this check. Active constraints are informational — they are what the repository already decided, not a verdict on this PR. |
The visual replacement rewrote every hero alt to remove an absolute claim -- "a coding agent must not revive a decision the repository already reversed" -- because the product does not stop an agent from thinking of an idea again. `readme-positioning.test.ts` then failed in all four languages at once. That phrase was carrying two things. ADR-0022 requires decision-authority framing in the hero, and the phrasings the test accepts include the absolute ones: "must not revive", "되살려서는 안", "蘇らせてはならない", "不得复活". Removing the overclaim removed the positioning with it, and the handoff that asked for the removal did not know the sentence had a second job. Each language's accepted list also has a non-absolute first entry -- "decision authority", "결정 권위", "意思決定の権威", "决策권威" -- so the alt now carries the framing without claiming the product blocks anything. Both contracts hold. The collision is written into `readme-hero.test.ts` next to the assertion that caused it. Two tests that pull against each other pass today and say nothing about why; the next person to rewrite an alt without the authority phrase would fail a test in another file with no explanation of what the wording was for. Limit: the two contracts are still enforced in separate files, so nothing fails if one of them is deleted -- the note is what connects them, and a note is weaker than a check Blast: local Undo: easy Certainty: firm Record-Id: r-heroalt22 Provenance: authored Verified: 31 tests across readme-positioning and readme-hero pass together, and the earlier failure is reproduced by the run this fixes -- four "hero contains decision-authority positioning" cases, one per language, on head 3fc2ca7 CommitLore-Version: 2.0.0
`Reuse for admin quotes` sat in the SUPERSEDED row, stopped by a dashed connector and an X. README:177-181 shows what it actually is:
Limit
[claim] r-price01 87e36511 calculatePrice owns final checkout pricing only
Ruled-out
[claim] r-price01 87e36511 Reuse checkout pricing for admin quotes | ...
One `r-price01`. The ruled-out alternative is a trailer on the record that is still in force, so it is delivered -- and delivering it is the entire point: it is how an agent learns the reuse was already considered and rejected. The first screen was stopping it at an X and saying the opposite of what the product does.
The superseded row is now an earlier, broader Limit that a later one replaced, which is what a superseded record is. The ruled-out line stays in the panel that reaches the next edit, where it already was.
The `<desc>` and all four alts follow, because they were describing the same inversion. A test pins it: the block between the SUPERSEDED label and the panel must not carry the ruled-out text, and the panel must still carry it. Restoring the draft wording fails it.
This is the second time this replacement said something the product does not do. The first was `must not revive` in the alt, which #71 caught by accident because the phrase was also load-bearing for ADR-0022. Neither was a rendering problem, and neither would have been caught by looking at the picture.
Limit: nothing checks that the hero and the payload block below it stay consistent -- the test asserts the inversion is absent, not that the two describe the same record
Blast: local
Undo: easy
Certainty: firm
Record-Id: r-heromeaning
Provenance: authored
Verified: README:177-181 carries both lines under one Record-Id, read in the file this pull request also ships; restoring `Reuse for` to the superseded row fails the new assertion, and 69 tests across the hero, positioning and readme suites pass with the correction
CommitLore-Version: 2.0.0
|
The commits from this branch are in GitHub recorded this as closed rather than merged, and the reason is worth writing down: #760's body contained the sentence "GitHub closes #752, #755, #756, #757, #758 and #759 as merged". A closing keyword binds only to the number immediately after it, so The sentence explaining that they would close as merged is what stopped one of them from doing it. The label is wrong; the code is where it should be. |
A blind refutation round on this branch broke three of the four claims I put to it, and verifying one of them found a defect it had not been looking for. `gh pr create` renders "GitHub closes #123 as merged" into the canonical pull request's body. GitHub binds a closing keyword to the number straight after it, and a pull request closed by keyword is recorded closed with `mergedAt` null -- the opposite of the sentence containing it, and the opposite of what T-1502 accepts. Measured on #752 six hours ago: an integration body said "GitHub closes #752, #755, #756 ... as merged", the keyword bound to #752 alone, and that one was recorded closed while the five with no keyword were recorded merged. There is no API to convert it afterwards. This workflow would have reproduced it on every run, and no test read the body. Two ticket statements were also wrong against the file. "The job never checks out or executes a pull request's head" was borrowed from the rule #723 fixed for `preserve`, which only reads a pull request; this one rebuilds it, and rebuilding somebody's change means running it. Unsatisfiable as written, so it would have been dropped rather than met -- what the job split actually holds is that the runner executing that code has no credential. And the negative control the ticket named, skipping `artifact:manifest`, cannot be performed from a pull request: the step is hard-coded in a workflow loaded from the default branch and the source-only filter refuses workflow edits. A negative control nobody can run is the defect it was written to prevent, so it is replaced with one that can be: edit `dist/` on the pushed canonical branch and watch `ci.yml` go red. Limit: the canonical pull request asks for a merge commit and cannot enforce one -- squash and rebase are both enabled and the button remembers the last method used, which is how #760 closed five of six as merged Blast: module Undo: easy Certainty: firm Record-Id: r-t1502body Provenance: authored Verified: restored the keyword and watched the new test fail naming `closes #123`, then restored the fix and saw 21 tests pass across both workflow test files CommitLore-Version: 2.0.0
The ticket said the method "is not enforceable from here" and handed the choice to the owner. That was wrong in a specific way: it was enforceable, it just was not enforced. `allow_squash_merge` and `allow_rebase_merge` are now off, so a merge commit is the only method GitHub offers on this repository. The canonical pull request depends on its head commit staying an ancestor, and a squash lands new bytes instead -- leaving the source pull request open with nothing to point at. Until now the only thing holding that was a sentence in the body asking for a merge commit, which is a check somebody has to read. #752 is what that costs: during the 1.1.3 release a body sentence failed in the seat next to this one, and there is no API to convert a pull request from closed to merged afterwards. What this moves rather than removes is written down too. The guarantee now lives in a repository setting, which nothing in this repository reads: a future owner can re-enable squash and no test, workflow or gate here will notice -- only a canonical pull request quietly failing to close its source. Limit: nothing in this repository can read the setting, so the only signal that it was reverted is a source pull request left open after a canonical merge Blast: local Undo: easy Certainty: firm Record-Id: r-squashoff818 Provenance: authored Verified: read back from the API after the change -- merge=true squash=false rebase=false CommitLore-Version: 2.0.0
Two SVGs sat above the fold in incompatible art directions — a warm editorial diagram and an animated dark terminal recording — so the first screen read as two templates rather than one product. The recording is retired and the hero replaced.
Reference search, before and after
commitlore demo, its scenario and its tests are untouched. What is deleted is the README recording asset, the generator that existed only to produce it, and that generator's test.Three departures from the reference skeleton
Each because following it exactly would have shipped something worse.
The skeleton put
SUPERSEDEDin the top slot, and §5.2 says the superseded row must not take the eye first. The hero being replaced already had the active row on top:Copying the skeleton would have broken a property that already held. Newest-first also matches what
git logshows, so a column labelledGIT HISTORYnow reads the way the tool it names does. This is a defect in the handoff, not a preference — §5.2 and §7.7 contradict each other.The next-edit column mixed two x positions for one phrase (690 / 674 / 674) and carried a green dot competing with the arrow that already supplies the accent — a fourth green mark in the region §5.2 ranks fourth for attention. The dot is gone under §6's "no decorative illustration" rather than under "the forbidden list does not mention it", which is the weaker argument. Its removal is why the three lines needed realigning at all.
Panel padding is 16 rather than 22 on both sides.
Checkout pricing onlyat 24px lands within ~2px of the old 284px limit on a wide system font, and this stack resolves to whatever the reader's OS provides — so the margin was thin on somebody else's machine, not on mine. Within §12'sspacing ±6px, and symmetric.The alt text was making a claim the product does not
All four translations carried the same claim; all four are corrected. CommitLore does not deliver a superseded record as current guidance — it does not stop an agent from thinking of the idea again.
Negative controls
test/readme-hero.test.tsis new. Each mutation was applied, the suite run, then restored:README.md<set>to the herothe agent cannot revive it<desc>The first version of the "no absolute claim" test failed on a source comment quoting the design rule it was implementing. The test now reads rendered text plus the accessible name and description — what actually reaches a reader — rather than the whole file.
Unresolved, and stated rather than hidden
375px. The README embeds at
width="100%", so a 375px viewport scales the 840px canvas by 0.446:Better than the 1200px canvas it replaces (7.5px) and still short of the floor. §18.2 makes those exact labels a pass criterion, and §9.2's 18px minimum does not reach it — 24px does not either. Three columns and this copy do not fit under a 700px canvas, so the canvas question is deferred rather than answered, and the measurement is recorded in the test file so it is not rediscovered.
Also unresolved: §12's allowed-changes list cannot express the fix for the overflow above — font reduction, line break and panel widening are all outside it.
Not changed
commitlore demoCLI, lifecycle behaviour, capture, protocol, runtime.