8000 Obelus v1.3: the page and the mark, plus the backlog by kiran-brahma · Pull Request #90 · kiran-brahma/writing-tool · GitHub
[go: up one dir, main page]

Skip to content

Obelus v1.3: the page and the mark, plus the backlog - #90

Merged
kiran-brahma merged 20 commits into
mainfrom
v1.3
Sep 26, 2026
Merged

kiran-brahma merged 20 commits into
mainfrom
v1.3

Conversation

@kiran-brahma
Copy link
Copy Markdown
Owner

Part of #57. The v1.3 tickets (#58–#69) and the backlog bugs (#45–#48, #51–#55), each reviewed and squash-merged into v1.3. Not for auto-merge. It needs a human review first.

On v1.3 at the head: pnpm test (1117), pnpm typecheck, pnpm run gates, pnpm harness (24) and pnpm build all pass. There is no Dexie migration and no DOM test layer. The only new dependency is @fontsource-variable/literata (OFL), bundled and served from Obelus's own origin.

Before you merge: missing docs

v1.3 was branched from main, because docs/v1.3-the-page-and-the-mark was never pushed. So this PR does not contain docs/specs/obelus-v1.3.md, docs/adr/0012-the-judge-is-a-rail-mode.md, docs/decisions/the-page-and-the-mark-goldilocks.md or the v1.3/backlog tables in docs/build-order.md. Workers used the spec text in #57's body. #66 implements what #57 says ADR 0012 decides; the ADR file itself was not written. The build-order "Completed" markings were skipped because those rows don't exist. Push that docs branch, merge it into v1.3, and then this closes #56 as planned.

Tickets and PRs

Ticket PR Notes
#45 Run cache stale on Connection edit #74
#46 Stalled provider holds the lock #76 5-minute request timeout chosen (no value in the issue); please confirm
#47 Unbalanced ) in a link href #71 1 review round: balanced hrefs stay raw so existing Anchors don't move; hrefs with a backslash now escape once
#48 SW cache-name docs #70
#51 Ordinal opening counted as one sentence #72 Per decision: documented in the metrics gloss
#53 Passive pass at note severity #86 Rule passes only; model schema unchanged; "note" flagged for /domain-modeling
#54 Chunked Audit call count #73 Old stored accounts display one call short (no migration allowed)
#55 List-only Document has no Target #75 A cursor anywhere in a list targets its first Paragraph
#58 Colour names #77 1 round: full ~50-name vocabulary + class→name table, so #59–#61 could run in parallel
#59 Editor surface → names, focus rings #79 1 round: save/import errors take failure (red)
#60 Rail → names, focus rings #80 1 round: Run/Reader/Audit/Judge errors take failure; milestone is violet
#61 Other screens → names, type scale, rings #78 1 round: ring offset on ink-filled controls
#62 Dark scheme, Light/Dark/System #81 New palette agent gate
#63 The page: Literata, measure, Status line #83 1 round: word count left the Document menu
#64 The mark: blue pencil #85 1 round: kept the mark token
#65 Margin marks #89
#66 Rail modes #84
#67 Outline in the left margin #88 Re-verified after #69
#68 Header and Callout #82 Also fixed the Document menu being clipped
#69 Narrow layout #87

Handed to a human

  • Decompose useRuns and useDocumentLifecycle further #52 (decompose useRuns): labelled ready-for-human + needs-info. The agent stopped as the Writer's decision instructs. The run-state union would not delete shared state, because Runs of different kinds can run at once. It also found that anyRunInFlight's stated rule (one Run at a time) is not enforced for Reader, Audit and Judge. Options are on the issue.

Acceptance criteria not verified here

Checks were done in headless Chromium only. No WebKit, no real devices, no screen reader, no human at a keyboard.

Worth a look by eye

🤖 Generated with Claude Code

https://claude.ai/code/session_01FjB3Gu8vhg5enkAneTdqga


Generated by Claude Code

kiran-brahma and others added 20 commits September 26, 2026 09:31
#70)

docs/migrations.md and the public/sw.js comment claimed the cache name
is release-keyed and bumped on every deploy, so activate would delete
the previous release's cache. CACHE_NAME has always been a constant and
nothing bumps it. Correct both to name syncShellAssets, run on every
successful online navigation, as what keeps the cache on the current
deploy. No behaviour change.

Closes #48.


Claude-Session: https://claude.ai/code/session_01FjB3Gu8vhg5enkAneTdqga

Co-authored-by: Claude <noreply@anthropic.com>
…ence (#72)

A Paragraph that opens with an ordinal (1984. The year...) escapes to the
same canonical shape as an escaped list marker, so the sentence rule
reads it as one sentence. The Writer accepted the rule (issue #51,
option 1): the metrics gloss now states the limitation, a help content
test asserts it, and a sentences test pins the unchanged segmentation.
The canonical string does not change, so no stored anchor offsets move.

Closes #51.


Claude-Session: https://claude.ai/code/session_01FjB3Gu8vhg5enkAneTdqga

Co-authored-by: Claude <noreply@anthropic.com>
…rs (#74)

A Connection's output ceiling, reasoning effort and extra headers are
edited in place under the same id and all reach the wire, but none was
in the Run cache key, so a re-run after changing one returned the
previous Findings without a Provider call. All three now join the key;
the extra headers are hashed as sorted entries so insertion order
cannot cause a miss and no header value is stored in the key.

Closes #45.


Claude-Session: https://claude.ai/code/session_01FjB3Gu8vhg5enkAneTdqga

Co-authored-by: Claude <noreply@anthropic.com>
A chunked Audit makes one call per Section chunk plus a synthesis call, but
reported only the chunk count. Per the Writer's decision on #54, `chunks` is
how many model calls the Run took (story 131): N chunk calls plus one for the
synthesis. A Document that fits one call still reports 1.

The harness's chunked Audit case now checks the reported count against the
calls the fixture transport recorded, and the Audit report line names both
the chunks and the calls.

Closes #54.


Claude-Session: https://claude.ai/code/session_01FjB3Gu8vhg5enkAneTdqga

Co-authored-by: Claude <noreply@anthropic.com>
A Document written only as a list had no paragraph-scope Target, so every
local Pass refused to run. `canonicalParagraphs` now finds the Paragraphs
inside list items, at any depth, from the same traversal that renders them,
and `passContext` resolves its Target from that list. The interval covers
the Paragraph's prose in the one canonical string, never the list marker,
so Containment is unaffected.

Closes #55.


Claude-Session: https://claude.ai/code/session_01FjB3Gu8vhg5enkAneTdqga

Co-authored-by: Claude <noreply@anthropic.com>
…trip (#71)

* fix: escape parentheses in a link href so the Markdown round-trip holds

canonicalText emitted an href unescaped, so an href with an unbalanced `)`
re-parsed as a shorter link plus a stray `)`. Backslash-escape `\`, `(` and
`)` in an emitted href and unescape them in parseLink. A new fuzz builds
links with adversarial hrefs and asserts the tree survives the round-trip.

Closes #47.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FjB3Gu8vhg5enkAneTdqga

* fix: emit a balanced href raw so existing canonical strings do not move

Escape `\`, `(` and `)` in an href only when its parentheses do not balance
or it holds a backslash, so a Document with a link such as `Obelus_(sign)`
keeps the same canonical string, and its Anchors, after upgrade. Move
isHrefEscapable off isEscapable's doc comment.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FjB3Gu8vhg5enkAneTdqga

---------

Co-authored-by: Claude <noreply@anthropic.com>
… (#76)

A Run holds the single mutation lock while it awaits the Provider, and the
fetch Transport set no timeout, so a Provider that accepted the connection
and then stalled blocked every later status write, rule run and import.

- The fetch Transport now gives each attempt a deadline (default 5 minutes)
  covering both the request and the body read, combined with the caller's
  signal. A stall fails with a readable TimedOutError and is not retried.
- Reader Runs forward the Run's signal to the Transport, and useRuns gives
  Reader and Audit Runs their own controllers, so Cancel run reaches them.
- Tests through the send seam for a Provider that never responds, one that
  ignores its signal, and one that stalls mid-body; storage tests that an
  aborted Reader or Audit Run stores nothing and frees the queue.

The queue ordering is unchanged: a Run still never interleaves with a
status write.


Claude-Session: https://claude.ai/code/session_01FjB3Gu8vhg5enkAneTdqga

Co-authored-by: Claude <noreply@anthropic.com>
* feat: colour names by meaning, with today's colours

Paper, ink, muted ink, rule, mark, current mark, warning, failure and
milestone become Tailwind theme colours whose light values are the
colours the app uses today. The Editor's stylesheet moves onto names,
with five supporting names (the Highlight's underline and hover, the
Current Finding's underline and ring, inline code, links) so it holds no
literal colour. Nothing on screen changes; the palette classes still
work, and no dark values are defined yet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FjB3Gu8vhg5enkAneTdqga

* feat: name every palette colour the app uses, with a mapping table

The three batches that move components onto the names run in parallel,
so the whole vocabulary lands here: surface and ink ladders, rule steps,
a focus ring, warning and failure surfaces and rules, the milestone's
ink, and names for the Judge's agreement and word diff, a Violation, a
passed Connection test and the tool's links. A table maps each palette
class to its name. Light values stay today's colours, and there are
still no dark values.

The Editor's inline code takes `sunk`, which is the same stone-100, and
its links take `prose-link`, because the Editor's blue and the palette's
blue-700 differ today.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FjB3Gu8vhg5enkAneTdqga

---------

Co-authored-by: Claude <noreply@anthropic.com>
* Move the other screens to colour names, type scale and focus rings

Library and Backup, Pass workbench, AI Settings and Connections, How this
works and Privacy now use the colour names from index.css instead of
palette classes, following its table (text on an ink fill is on-ink, text
on the warning fill is warning-surface).

Type on these screens sits on three steps: text-lg for headings, text-sm
for body, text-xs for detail. The section headings of How this works and
Privacy and a Library entry's title move up from text-base; the 11px
details in AI Settings and Connections move to text-xs.

Every control shows focus-visible:ring-2 ring-focus from the keyboard;
controls inside a warning notice use ring-warning-focus. The visually
hidden file inputs put the ring on their label with has-focus-visible.

Part of #57. Closes #61.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FjB3Gu8vhg5enkAneTdqga

* Offset the focus ring on dark-filled controls

A focus-coloured ring flush against an ink fill cannot be seen. The ink
buttons, the active tag chip and the warning-filled Replace library
button now add ring-offset-2, so a band of paper separates the ring
from the fill.

Part of #57. Refs #61.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FjB3Gu8vhg5enkAneTdqga

---------

Co-authored-by: Claude <noreply@anthropic.com>
* Move the Editor surface to colour names, with focus rings

The app shell and header, the Editor and its toolbar, the Callout, the
Document menu, the first-run and Scratchpad notes, and the save, storage
and import banners now use the colour names from index.css instead of
palette classes. The banners take warning rather than amber, so a
failure and a mark no longer share a colour.

Every control in the surface shows a focus ring from the keyboard
(story 209): the toolbar buttons, the notes' action and dismissal, the
Document menu's Import and Export items, and the title field, whose
ring is inset because the field runs edge to edge.

Part of #57. Closes #59.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FjB3Gu8vhg5enkAneTdqga

* Offset the focus ring on ink-filled controls

A ring in the focus colour disappears against an ink fill, so the
current destination in the header and an active toolbar button carry a
ring offset, as t
8000
he shared convention now says.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FjB3Gu8vhg5enkAneTdqga

* Give the save and import errors the failure colour

A save that failed and an import that failed are failures, not
warnings, so their banners take failure-rule, failure-surface and
failure. The storage notice stays a warning.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FjB3Gu8vhg5enkAneTdqga

---------

Co-authored-by: Claude <noreply@anthropic.com>
* Move the Rail to colour names, with focus rings

Every Rail panel now uses the colour names from index.css instead of
palette classes. The Milestone badge takes a violet milestone pair, no
longer the warning amber (story 208). The Raw response and Milestones
only checkboxes, the milestone note and the Rail's tab panel gain the
shared focus ring (story 209).

Part of #57. Closes #60.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FjB3Gu8vhg5enkAneTdqga

* Offset the focus ring on the Rail's ink-filled controls

A ring in the focus colour with no offset disappears against an ink
fill, so Flag this revision, Judge, the active Judge toggles and the
rule config Save button carry ring-offset-2.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FjB3Gu8vhg5enkAneTdqga

* Show the Rail's failed-Run notices in the failure colours

A failed model Run, a failed Reader or Audit Run and a failed Judge call
report something that went wrong, so they take failure rather than
warning (spec #57: amber for warnings, red for failures). Advisory
notices stay warning.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FjB3Gu8vhg5enkAneTdqga

---------

Co-authored-by: Claude <noreply@anthropic.com>
Every colour name gains a dark value: a warm dark paper, not black, with
light ink that is never pure white. The Writer chooses Light, Dark or
System in AI Settings. System is the default: no attribute is set and the
stylesheet follows prefers-color-scheme itself, live and with no flash.
Light or Dark sets data-theme on the root element.

The choice is the colorScheme key in the existing settings store,
normalised on load (unknown -> System), carried in a Backup. No Dexie
migration. resolveColorScheme names the resolved scheme for the two
theme-color metas, which now follow the scheme. The root is the ground
colour, and a focus ring's offset follows paper, so an ink-filled
control's ring in dark has no white band.

A new agent gate fails the build on a raw palette colour class or
palette variable in UI source.

Part of #57. Closes #62.


Claude-Session: https://claude.ai/code/session_01FjB3Gu8vhg5enkAneTdqga

Co-authored-by: Claude <noreply@anthropic.com>
Editor and Library are the header's tabs; the Pass workbench and AI
Settings follow as quieter links; How this works and Privacy sit under one
help control that opens from the keyboard and closes on Escape, returning
focus. Every destination is at most two clicks from every other, tested as
a rule on the destination model. The header wraps instead of scrolling
sideways, so it no longer clips the Document menu.

In the Callout, Addressed is a filled button, Decline an outlined one and
Decline as violation a text link. It carries no key hints (ADR 0011).


Claude-Session: https://claude.ai/code/session_01FjB3Gu8vhg5enkAneTdqga

Co-authored-by: Claude <noreply@anthropic.com>
The Rail opens on Findings each session, with the Band control, All,
the run controls and the queue first; Judge mode holds the Judge with
milestones and Revisions. The queue keys act only in Findings mode and
the modifier step switches to it. The live region sits outside both
modes. The hint bar is one line at the Rail's foot; the full text is on
the shortcuts page. The raw-response option moves to AI Settings as the
stored showRawResponse key. Only the Current Finding's row shows model
and time; the Callout shows them for each Finding. Rail headings step up
to a three-step type scale.


Claude-Session: https://claude.ai/code/session_01FjB3Gu8vhg5enkAneTdqga

Co-authored-by: Claude <noreply@anthropic.com>
* The page: Literata, a reading measure and the Status line (#63)

The Writer's prose is set in Literata, bundled from the OFL
@fontsource-variable/literata package so Vite serves its woff2 from
/assets/ on Obelus's own origin; Georgia is the fallback. The prose is
18px with line-height 1.6, headings scale in em in the same family, and
the column holds about 68 characters, centred.

The Document title moves to the head of the column in the page's
typeface and still commits on blur or Enter. The toolbar aligns with the
column, is quieter, and drops Undo and Redo; the history and Markdown
input rules are StarterKit's, unchanged. A Status line beneath the prose
shows the word count at every width, from the new pure wordCountLabel.
Status line is added to CONTEXT.md.

Part of #57.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FjB3Gu8vhg5enkAneTdqga

* Move the word count out of the Document menu (#63)

The Status line carries the word count at a glance, so the Document
menu keeps only Import and Export (story 200). The prop that served the
menu's count goes with it.

Part of #57.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FjB3Gu8vhg5enkAneTdqga

---------

Co-authored-by: Claude <noreply@anthropic.com>
* The mark: blue pencil, underlined at rest

A Highlight is now an underline in an editor's blue pencil, with no fill
at rest. The Current Finding's Highlight is filled and keeps its outline,
and keeps that fill under the pointer; any other Highlight fills on hover.
The mark tokens and the Current Finding's Rail row move from amber to sky,
a cyan-leaning blue apart from the links' royal blue, in both schemes.
The unused `mark` fill token goes; the underline stays a text decoration
and no Highlight gains a shadow or a radius.

Part of #57. Closes #64.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FjB3Gu8vhg5enkAneTdqga

* Keep the mark token as the blue pencil itself

`mark` is one of the spec's colour names, and Margin marks need a named
blue-pencil colour for the obelus and its count. It returns in both
schemes as a colour legible as text: sky-700 in light (5.9:1 on paper,
5.7:1 on ground) and the dark underline's sky (7.9:1 on paper, 8.3:1 on
ground). No Highlight uses it as a fill; at rest a Highlight is still
only its underline.

Part of #57.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FjB3Gu8vhg5enkAneTdqga

---------

Co-authored-by: Claude <noreply@anthropic.com>
Story 138 asks for the passive pass at note severity. A Finding now carries
an optional `severity: "note"`, set only by the `passive` rule. Orwell's
passive, on the same span, and every other rule pass leave it unset.
Reconciliation takes the severity from the Run, so a stored passive Finding
picks it up on the next save.

The findings schema and its parser are unchanged. The parser reads only the
schema's fields, and a test shows that a model returning `severity` gets no
severity on its Finding.

The Rail's row and the Callout give a note a quiet outlined "Note" label and
a lighter issue weight. They use existing colour names only. Queue order and
Band membership are unchanged.

No Dexie migration: the field is optional and unindexed, and the schema
version is unchanged.


Claude-Session: https://claude.ai/code/session_01FjB3Gu8vhg5enkAneTdqga

Co-authored-by: Claude <noreply@anthropic.com>
Below 1024px the Rail overlays the prose instead of squeezing it, so the
page keeps its full width. One matchMedia subscription gives `wide`, and
railPresentation(wide, collapsed, overlayOpen) returns docked, overlay or
hidden: when wide the stored collapsed preference decides; when narrow only
a local overlay flag, false on every load and never stored, decides.

The Status line offers the Rail with the open-Finding count below 1024px;
the modifier step opens the overlay; Escape or a press outside closes it.
Crossing 1024px switches between overlay and docked without reload.

Stories 251-255. Part of #57.


Claude-Session: https://claude.ai/code/session_01FjB3Gu8vhg5enkAneTdqga

Co-authored-by: Claude <noreply@anthropic.com>
At 1440px and wider the Outline sits in the left margin the capped column
leaves empty, as a quiet list of headings held in view while the prose
scrolls; below that width it stays in the Rail's Reference strip. Both
render and one stylesheet breakpoint shows one, so resizing swaps them
without a reload and no script decides the placement.

Both placements draw their rows from outlineEntries, so they mark the same
current Section and jump to the same heading block.


Claude-Session: https://claude.ai/code/session_01FjB3Gu8vhg5enkAneTdqga

Co-authored-by: Claude <noreply@anthropic.com>
marginMarks(tree, highlights), beside the Callout's pure functions, gives
one entry per top-level block where an open, attached Finding begins. The
Highlight plugin draws each as a zero-height widget between top-level
blocks, with a button hung into the column's right padding: the obelus and
its count in blue pencil, out of the Tab order and labelled with its count.
A click reports its Finding ids through the Highlight-click path, so the
Callout opens and the Current Finding and the Rail stay put (ADR 0011).
Adds Margin mark to CONTEXT.md.

Part of #57.


Claude-Session: ht
C274
tps://claude.ai/code/session_01FjB3Gu8vhg5enkAneTdqga

Co-authored-by: Claude <noreply@anthropic.com>
@chatgpt-codex-connector
chatgpt-codex-connector Bot commented Sep 26, 2026 •
Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
🔒 Security Review ✅ Completed 2026-09-26T11:15:10.971304Z 55b0ad8 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

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.

docs/build-order.md says #37-#44 are unblocked; all eight have landed

1 participant

0