8000 docs: the v1.3 spec, ADR 0012 and the build order by kiran-brahma · Pull Request #91 · kiran-brahma/writing-tool · GitHub
[go: up one dir, main page]

Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 17 additions & 21 deletions CONTEXT.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,11 +32,6 @@ One saved point in a Document's history. An *auto-revision* is taken on a deboun
revision* is marked by the Writer as a milestone and carries a note.
_Avoid_: snapshot, version, save, checkpoint

**Status line**:
The line beneath the prose, at every width, that carries the Document's word count. It is the tool's,
not the Writer's, so it is set in the sans.
_Avoid_: status bar, footer, word counter

**Library**:
Every Document held in this browser.
_Avoid_: workspace, project, vault
Expand Down Expand Up @@ -100,17 +95,20 @@ every other, and no Band is gated on another.
_Avoid_: stage, tier, phase, step, section

**Rail**:
The surface beside the prose, in two Rail modes. Findings mode holds the Band control, **All**, the
selected Band's Passes with their Findings and accounts, and the run controls; Judge mode holds the
Judge with milestones and Revisions (ADR 0012). It collapses so the prose has the width. Below 1024px
it overlays the prose instead of sitting beside it, and starts closed on every load.
The surface beside the prose where the Writer works: in one Rail mode the Band control and the
selected Band's Passes with their Findings and accounts; in the other the Judge, with milestones and
Revisions. It collapses so the prose has the width, and overlays the prose on a narrow screen.
_Avoid_: sidebar, panel, drawer, nav

**Rail mode**:
One of the Rail's two views — Findings or Judge — switched at its top. The Rail opens on Findings
each session, and the mode is never stored. The queue keys act only in Findings mode; the modifier
step switches to it first.
_Avoid_: tab, view, page, screen
Which of the Rail's two jobs it is showing: Findings (the Working order) or Judge. A view choice, not
a Band, and not remembered between sessions.
_Avoid_: tab, view, page, section

**Status line**:
The line beneath the prose carrying the Document's word count and, on a narrow screen, the way to the
Rail.
_Avoid_: footer, status bar, toolbar

**Target**:
The text a Run is asked about.
Expand Down Expand Up @@ -142,17 +140,15 @@ The visual rendering of an Anchor. The Current Finding's Highlight is distinguis
_Avoid_: underline, marker

**Callout**:
The popover a click on a Highlight or a Margin mark opens beside the prose: the open Findings on that
text, with the queue's verdicts. It does not change the Current Finding, so the Rail stays where the
Writer left it (ADR 0011).
The popover a click on a Highlight or a Margin mark opens beside the prose: the open Findings on that text, with the
queue's verdicts. It does not change the Current Finding, so the Rail stays where the Writer left it
(ADR 0011).
_Avoid_: tooltip, popup, card

**Margin mark**:
The obelus, with a count, in the right-hand margin beside a Paragraph where open Findings begin. A
Finding is counted once, beside the Paragraph it begins in; an Orphaned Finding has none. A click
opens the Callout with those Findings. Kept although the Anchor entry lists *mark* under _Avoid_: that
avoid is about naming an Anchor, and a Margin mark is not one.
_Avoid_: badge, pin, gutter icon, marker
The obelus in the margin beside a Paragraph where open Findings begin, with their count. One Finding
gives one Margin mark, beside the first Paragraph it concerns; an Orphaned Finding gives none.
_Avoid_: obelus, gutter icon, badge, marker

**Orphaned**:
The condition of a Finding whose quoted text can no longer be found, so it points nowhere. A
10BC8 Expand Down
25 changes: 25 additions & 0 deletions docs/adr/0012-the-judge-is-a-rail-mode.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# The Judge is a Rail mode

ADR 0010 made the Judge "a destination below the Bands" so it would not be read as the Working order's
last step. It is still not a Band, but below the Bands it sat under the whole queue, with milestones
and Revisions under it: a Writer reaching the Judge scrolled past every open Finding, which is the
burial 0010 set out to end. So the Rail gets two **Rail modes**, Findings and Judge, switched at its
top. Findings holds the Band control and everything under it; Judge holds the Judge with milestones and
Revisions, its raw material (story 165). This supersedes 0010's one sentence on where the Judge sits
and nothing else: its four properties are untouched, because the Band control, **All**, and every Run
live whole inside Findings mode.

Two consequences keep it honest. The queue keys act only in Findings mode, so `j`/`k` never move a
selection the Writer cannot see; the modifier step switches to Findings mode, as it already opens a
collapsed Rail. And the mode is not remembered, like **All**: it is a choice made in the moment.

The same increment moves the Outline into the left margin on screens 1440px and wider. That is not the
"two rails" option 0010 rejected. That option took width from the Editor, and the Editor now holds its
prose to a reading measure of about 68 characters, so a wide screen leaves margin the prose cannot
use. The Outline takes that margin, not the prose's width, and returns to the Rail below 1440px.

## Considered Options

- **A top-level destination in the header.** One click away, but the Judge leaves the prose it
compares, and milestones and Revisions either follow it out of the Editor or are split from it.
- **Keep it below the Bands.** Meets 0010's wording; leaves the Judge under the queue.
1 change: 1 addition & 0 deletions docs/agents/issue-tracker.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,7 @@ canonical and the GitHub issue is the publication.**
| `docs/specs/obelus-v1.md` | [#1](https://github.com/kiran-brahma/writing-tool/issues/1) |
| `docs/specs/obelus-v1.1.md` | [#25](https://github.com/kiran-brahma/writing-tool/issues/25) |
| `docs/specs/obelus-v1.2.md` | [#34](https://github.com/kiran-brahma/writing-tool/issues/34) |
| `docs/specs/obelus-v1.3.md` | [#57](https://github.com/kiran-brahma/writing-tool/issues/57) |

- **Sync direction**: edit the file (git diffs it), then republish:
`gh issue edit <n> --body-file docs/specs/<slug>.md`. Never edit the issue body
Expand Down
118 changes: 100 additions & 18 deletions docs/build-order.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,15 +71,17 @@ never the prose. **Every v1 and v1.1 ticket has landed**, and issues #1 and #25
Run-cache behaviour, so it can ship alone as `docs/migrations.md` requires: deploy the migration
commit first, then the behaviour that uses the store.

**v1.2 is the open frontier.** The spec is #34 and the sequence is the v1.2 table below. Its subject
is the surface rather than the analysis: v1.1 made the tool recommend, and v1.2 makes the
recommendation reachable. #35 (The Working order rail) has landed: the rail's top-level control is
the Band — Structure, Paragraph, Word — plus All, a Band shows its Passes together with the Findings
those Passes produced, the Judge is its own destination, the three-tab strip is gone, and the rail
remembers its Band and collapses. #36 (How this works, and first run) has landed: a permanent How
this works destination carries Rule 1, Rule 2, the loop, the glossary and the shortcuts; a
dismissible first-run note sits in the Editor body; and an empty Scratchpad says what to do. With
#35 and #36 both closed, #37–#44 are all unblocked.
**v1.2 has landed.** #35–#44 are all in (`741aaad` through `5e76189`): the Band is the navigation,
How this works and the first-run note exist, the Judge defaults to the last milestone against now,
the Current Finding moves the prose, the queue is reachable from the prose, a Pass's rest can be
declined and any Finding reopened, every panel glosses its nouns, the rail meets the accessibility
bar, a Run's cost sits beside its control, and the header is persistent navigation. The follow-ups
from the Thermos review, #45–#55, are sequenced in the backlog table at the end of this file.

**v1.3 is the open frontier.** The spec is #57 and the sequence is the v1.3 table below. Its subject
is the page and the mark: an identity for the prose and its marks, a dark scheme, the Rail in two
Rail modes, and a layout that works down to tablet width. **#58 can start now, alongside the
unblocked backlog tickets** (#45, #46, #47, #48, #51, #54, #55). The goal is every open issue closed.

## How to work a ticket

Expand Down Expand Up @@ -139,15 +141,14 @@ parallel.
|---|---|---|---|---|
| 23 | **#35** | The Working order rail | — | The Band is the navigation: Structure, Paragraph, Word, All; a Band shows its Passes and their Findings in one view; the Judge is its own destination; the three-tab strip is gone; the rail remembers its Band and collapses | - Completed
| 24 | **#36** | How this works, and first run | — | A permanent page carrying Rule 1, Rule 2, the loop, the terms and the shortcuts; a dismissible first-run note; an empty Scratchpad that says what to do | - Completed
| 25 | **#37** | The Judge's default pair | — | The default comparison is the last flagged Revision against now, not two autosaves |
| 26 | **#38** | The Current Finding | #35 | Selecting a Finding scrolls the prose to it and distinguishes its Highlight |
| 27 | **#39** | Reaching the queue from the prose | #35 | A modifier shortcut that steps the queue while typing; a hint bar that tells the truth; `?` |
| 28 | **#40** | Decline the rest, and reopen | #35 | Declining a whole Pass in one action, and the first path back to `open` — closes audit §5.3 |
| 29 | **#41** | Plain-language glosses | #35, #36 | Every panel explains its own nouns once, linking into How this works |
| 30 | **#42** | Accessibility | #35 | Tab-panel linkage, an announced Run result, 4.5:1 contrast, no text under 12px |
| 31 | **#43** | What a Run will cost | #35 | The estimate beside the control that spends, and a summed estimate for the structural set |
| 32 | **#44** | Header and navigation | #36 | Persistent navigation over six destinations; document actions separated; the three "Back to the Editor" buttons and their state deleted |

| 25 | **#37** | The Judge's default pair | — | The default comparison is the last flagged Revision against now, not two autosaves | - Completed
| 26 | **#38** | The Current Finding | #35 | Selecting a Finding scrolls the prose to it and distinguishes its Highlight | - Completed
| 27 | **#39** | Reaching the queue from the prose | #35 | A modifier shortcut that steps the queue while typing; a hint bar that tells the truth; `?` | - Completed
| 28 | **#40** | Decline the rest, and reopen | #35 | Declining a whole Pass in one action, and the first path back to `open` — closes audit §5.3 | - Completed
| 29 | **#41** | Plain-language glosses | #35, #36 | Every panel explains its own nouns once, linking into How this works | - Completed
| 30 | **#42** | Accessibility | #35 | Tab-panel linkage, an announced Run result, 4.5:1 contrast, no text under 12px | - Completed
| 31 | **#43** | What a Run will cost | #35 | The estimate beside the control that spends, and a summed estimate for the structural set | - Completed
| 32 | **#44** | Header and navigation | #36 | Persistent navigation over six destinations; document actions separated; the three "Back to the Editor" buttons and their state deleted | - Completed
**Why this order.** #35 restructures nearly every file the other nine touch, so it lands before the
tickets that decorate it — otherwise an AFK agent resolves conflicts it cannot see. #36 is in the
first wave rather than beside #44 because the header ticket needs the fourth destination to exist
Expand Down Expand Up @@ -230,3 +231,84 @@ Steps 1 and 2 are the critical path: slice 2 cannot start until the `audit` shap
are settled, or a fresh context window invents a second coordinate system for the account. Steps 3–8
are independent of each other once the shape lands, and 6 needs the rule passes from 3 to have
something to silence.

## The order — v1.3

Parent: **#57**, `docs/specs/obelus-v1.3.md`. The decision is
`docs/adr/0012-the-judge-is-a-rail-mode.md`, and the design was chosen in
`docs/decisions/the-page-and-the-mark-goldilocks.md`.

The colour work is a **wide refactor**, so it runs expand–contract rather than as one slice: #58 adds
colour names with exactly today's light values, #59–#61 move the UI onto them in batches that change
nothing visible, and #62 contracts — dark values go live, the Light | Dark | System choice appears, and
an agent gate forbids raw palette classes. Dark values must not ship before every batch has moved:
System is the default, so a Writer whose OS is dark would otherwise see a half-dark app.

Every ticket is presentation. No prompt changes, **no Dexie migration** (the two new keys,
`colorScheme` and `showRawResponse`, go in the existing settings store), and no DOM test layer.

| Step | # | Ticket | Blocked by | What it makes work |
|---|---|---|---|---|
| 33 | **#58** | Colour names with today's colours | — | Named colours by meaning, light values identical to today; the Editor stylesheet uses them | - Completed
| 34 | **#59** | Move the Editor surface to colour names, with focus rings | #58 | Shell, Editor, toolbar, Callout, banners on names; warnings stop borrowing the mark colour | - Completed
| 35 | **#60** | Move the Rail to colour names, with focus rings | #58 | Every Rail panel on names; the Milestone badge gets its own colour | - Completed
| 36 | **#61** | Move the other screens to colour names, type scale and focus rings | #58 | Library, Workbench, AI Settings, How this works, Privacy | - Completed
| 37 | **#62** | Dark scheme and the Light \| Dark \| System choice | #59, #60, #61 | Dark values, the stored choice, `theme-color`, the gate against raw palette classes | - Completed
| 38 | **#63** | The page | #62 | Bundled Literata, a ~68-character measure, the title in the column, a quieter toolbar, the Status line | - Completed
| 39 | **#64** | The mark | #62 | Blue pencil; underlined at rest, filled for the Current Finding and on hover | - Completed
| 40 | **#65** | Margin marks | #63, #64 | An obelus with a count beside each Paragraph where open Findings begin; a click opens the Callout | - Completed
| 41 | **#66** | Rail modes | #62 | Findings \| Judge; queue keys only in Findings; one-line hint; raw response in AI Settings | - Completed
| 42 | **#67** | The Outline in the left margin | #63 | The Outline beside the page at ≥1440px, in the Rail below | - Completed
| 43 | **#68** | Header destinations and the Callout's verdicts | #62 | Editor and Library as the destinations; Addressed as the Callout's primary action | - Completed
| 44 | **#69** | Narrow layout | #63 | Below 1024px the Rail overlays the prose, opened from the Status line | - Completed

Waves, each workable in parallel:

- **Wave 1:** #58
- **Wave 2:** #59, #60, #61
- **Wave 3:** #62
- **Wave 4:** #63, #64, #66, #68
- **Wave 5:** #65, #67, #69

**Why this order.** #65 waits on #63 as well as #64 because the right margin only exists once the
column is capped; #67 needs the left margin for the same reason, and #69 needs the Status line #63
creates. #66 and #69 both touch the Rail and may conflict on merge, but neither gates the other.

**The standing constraints**, in every ticket: no affordance that inserts model-derived text; ADR
0010's four properties and ADR 0011's Callout rule hold; `CONTEXT.md` terms only (Margin mark, Rail
mode, Status line are new; the Rail is never a "drawer"); the WebKit Highlight budget — no shadow and
no radius on a Highlight, and typing with ~490 Highlights no slower; every markup ticket is checked
by eye in both schemes and at the widths its ticket names.

## The order — backlog

The Thermos review's follow-ups, #45–#55, and the stale-doc report #56. Every one is decided: where an
issue offered options, the Writer's choice is a comment on the issue, and that comment is the
requirement. #56 closes when the v1.3 docs branch merges.

| Step | # | Ticket | Blocked by | Decision / what it makes work |
|---|---|---|---|---|
| 45 | **#45** | Run cache stale after a Connection is reconfigured | — | `maxOutputTokens`, `reasoningEffort` and `extraHeaders` (stably ordered) join the Run cache key | - Completed
| 46 | **#46** | A stalled provider call holds the mutation lock | — | A request timeout in the transport; cancel threaded through Reader and Audit Runs; a timeout test through `send` | - Completed
| 47 | **#47** | Unbalanced `)` in a link href breaks the round-trip | — | Escape `(` `)` in an emitted href; the fuzz test learns to emit links | - Completed
| 48 | **#48** | The service-worker cache claim | — | **Correct the docs**: the navigation-time prune is the mechanism; `CACHE_NAME` stays constant | - Completed
| 49 | **#51** | An opening ordinal counts as one sentence | — | **Accept and document** in the metrics panel's explanation; `sentences.ts` unchanged | - Completed
| 50 | **#54** | A chunked Audit under-reports its call count | — | **True call count**: N chunks + 1 synthesis | - Completed
| 51 | **#55** | A list-only Document has no paragraph-scope Target | — | Resolve the Target to a Paragraph inside a list item; Containment unaffected | - Completed
| 52 | **#53** | The passive pass at note severity | #66 | An optional rule-pass-only `severity: "note"` and a distinct row treatment; the model schema unchanged | - Completed
| 53 | **#52** | Decompose `useRuns` and `useDocumentLifecycle` | #65, #66, #67, #68, #69 | One run-state union replacing the five Run-kind triples; stop if it moves lines without deleting state |

**How it fits v1.3.** Steps 45–51 touch Core, the wire, storage and docs, not the surfaces v1.3
reshapes, so they run in parallel with v1.3's first waves. #53 waits for #66 because Rail modes
rebuilds the Finding row it decorates. #52 goes last: it reshapes the hooks behind the handle that
v1.3 extends with two settings, and landing it first would put every v1.3 ticket on a moving base.

Combined waves for the whole run:

- **Wave 1:** #58, #45, #46, #47, #48, #51, #54, #55
- **Wave 2:** #59, #60, #61
- **Wave 3:** #62
- **Wave 4:** #63, #64, #66, #68
- **Wave 5:** #65, #67, #69, #53
- **Wave 6:** #52

Loading
0