Skip to content

Replace the competing README visuals with one lifecycle diagram - #752

Closed
MongLong0214 wants to merge 6 commits into
mainfrom
readme-one-visual
Closed

Replace the competing README visuals with one lifecycle diagram#752
MongLong0214 wants to merge 6 commits into
mainfrom
readme-one-visual

Conversation

@MongLong0214

Copy link
Copy Markdown
Owner

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

$ git grep -n -e 'commitlore-demo\.svg' -e 'record-demo\.mjs' -e 'T-1016'
before   4 READMEs · the asset · its generator · its byte-identity test · 3 historical ticket/gate docs
after    3 historical ticket/gate docs only

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 SUPERSEDED in 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:

old hero   ACTIVE y=80    SUPERSEDED y=256    satisfies the rule
skeleton   SUPERSEDED     ACTIVE              inverts it

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. 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 only at 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's spacing ±6px, and symmetric.

The alt text was making a claim the product does not

- alt="CommitLore: a coding agent must not revive a decision the repository already reversed."
+ alt="CommitLore delivers the active decision for src/pricing.ts before the next edit, while a
+      superseded decision does not move forward as current guidance."

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.ts is new. Each mutation was applied, the suite run, then restored:

mutation result
restore the demo block to README.md 2 failed
add <set> to the hero 1 failed
replace the alt with the agent cannot revive it 1 failed
delete <desc> 1 failed
put the superseded row back on top 1 failed
restore 24 passed

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:

18px → 8.0px    GIT HISTORY · SUPERSEDED · ACTIVE · CURRENT CONTEXT · Limit · Ruled out · NEXT EDIT
24px → 10.7px   the largest text in the diagram
                    ↑ a caption usually needs 12 CSS px; Apple HIG says 11pt

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 demo CLI, lifecycle behaviour, capture, protocol, runtime.

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
@github-actions

github-actions Bot commented Aug 18, 2026

Copy link
Copy Markdown

CommitLore — record lint

Trailers: clean — 6 commits in origin/main..8dcce526c2371b6235a85e3f29828cf2620a43f3
Active constraints: not read — commitlore: git log --follow accepts exactly one pathspec, so renames are not followed for 9 paths; query one path at a time to follow its rename chain (9 changed paths)

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
@MongLong0214 MongLong0214 mentioned this pull request Aug 18, 2026
@MongLong0214

Copy link
Copy Markdown
Owner Author

The commits from this branch are in main8dcce526 is an ancestor of the 1.1.3 merge commit e3ee9e8, landed by #760 with --no-ff.

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 closes #752 registered as a linked reference and closed this one by keyword, while the other five were detected by ancestry and marked merged.

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.

MongLong0214 added a commit that referenced this pull request Aug 18, 2026
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
MongLong0214 added a commit that referenced this pull request Aug 18, 2026
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
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