Skip to content

fix(journal): keep prose whole on write, lead with open threads on read - #998

Merged
laynepenney merged 1 commit into
devfrom
fix/journal-prose-and-ordering
Aug 22, 2026
Merged

fix(journal): keep prose whole on write, lead with open threads on read#998
laynepenney merged 1 commit into
devfrom
fix/journal-prose-and-ordering

Conversation

@laynepenney

Copy link
Copy Markdown
Member

Ref #997 — closes at promotion

What this fixes

Two defects in the session journal, unrelated in code and identical in character: both fail toward
looking fine.

Write — the three journal fields were each split on ;, so a semicolon used as ordinary
punctuation fragmented a sentence and stripped its subject. Measured on a real entry: one field
produced seven items, six beginning mid-sentence, one reading in full as the fix is 4d11834e. The
result reads as terse notes rather than as damage, which is why it survived.

Readformat_for_session_start is bounded, and it led with Done. Completed work consumed
the window before open threads were reached. Ordering is taste on an unbounded surface and correctness
on a truncated one.

The change

Splitting prefers newlines and falls back to semicolons only when the text has none — how the fields
are actually written, one item per line — so every existing single-line caller works unchanged and
--done "a; b; c" behaves exactly as before. A single-line field containing prose semicolons is still
ambiguous by construction; the fallback preserves the documented CLI convention, and that trade is
deliberate.

The split existed in six places across two modules, which is its own latent defect: fixing one path
would have left the other mangling prose. It is now one function called from both.

Open threads now lead the bounded read. The unbounded display is reordered to match — nothing forces it
there, but two surfaces that teach different priorities are their own defect, and a human reading a
full entry also reads top-down and stops.

Witnesses

Both assert what the reader receives, not what was written. That distinction is the whole finding:
asserting the written value passes in both the fixed and broken states, which is how two defects
reached a green suite with no test on either behaviour.

Witness Killed by
prose with a semicolon reaches the reader whole restoring the semicolon-only split
open threads precede completed work in the bounded read reversing the ordering tuple

Each mutation kills exactly one witness. The ordering witness also asserts both sections are
present, so it cannot pass by one of them simply being absent. A control witness pins the single-line
semicolon behaviour that existing callers depend on.

Test suite

passed failed
base 2662 4
head 2666 4

Delta +4, exactly the four tests added here. The four failures are identical on both sides, live in a
module this change does not touch, and are reported so they are not mistaken for regressions.

Premium boundary

recall is OSS: local journal storage and formatting. No identity, org, or entitlement behaviour.

Two defects in the journal store, both of which fail toward looking fine.

WRITE. The three journal fields were each split on ";", so a semicolon used
as ordinary punctuation fragmented a sentence and stripped its subject. The
result reads as a list of terse notes rather than as damage, which is why it
survived: nothing looks broken. Measured on a real entry, one field produced
seven items, six of which began mid-sentence, and one read in full as "the
fix on grip dev is 4d11834e" -- true, unattached, meaningless to the reader
it was written for.

Splitting now prefers newlines and falls back to semicolons only when the
text has none. That is how these fields are actually written -- one item per
line -- and it keeps every existing single-line caller working unchanged, so
`--done "a; b; c"` behaves exactly as before. A single-line field containing
prose semicolons is still ambiguous by construction; the fallback is what
preserves the documented CLI convention, and that trade is deliberate.

The split also existed in six places across two modules, which is its own
latent defect: fixing one path would have left the other mangling prose. It
is now one function, called from both.

READ. The session-start read is BOUNDED, and it rendered Done, then
Decisions, then Next -- so completed work consumed the window before open
threads were reached. Ordering is not a matter of taste on a truncated
surface; whatever leads is what survives. Open threads now lead. Completed
work is recoverable from git and the board; an unrecorded open question is
recoverable from nowhere.

The unbounded display is reordered to match. Nothing forces it there, but
two surfaces that teach different priorities are their own defect, and a
human reading a full entry also reads top-down and stops.

DOCUMENTATION. The author-facing text said "Semicolon-separated list" in six
places -- three in the MCP tool description and three in CLI help -- and after
this change that is wrong for the multi-line case and right for the
single-line one. A half-true rule is worse than the original defect, because
it is confidently wrong in one direction. Both surfaces now state the real
behaviour at the point of writing, along with the fact that the session-start
read is truncated and leads with next_steps, since that changes how an author
composes an entry. The two genuinely semicolon-delimited options elsewhere are
left alone.

Both witnesses assert what the READER RECEIVES rather than what was written,
which is the only form that catches this class -- the same move as verifying
a published artifact against what the server serves rather than against what
was uploaded. Each is killed by exactly one mutation: reversing the ordering
tuple reddens the ordering witness alone, and restoring the semicolon-only
split reddens the prose witness alone.

Co-Authored-By: Claude <noreply@anthropic.com>
@laynepenney
laynepenney merged commit 31b0488 into dev Aug 22, 2026
9 of 12 checks passed
@laynepenney
laynepenney deleted the fix/journal-prose-and-ordering branch August 22, 2026 16:28
@github-actions github-actions Bot locked and limited conversation to collaborators Aug 22, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant