Rich notifications: review gates you can answer from a phone #26

Closed
opened 2026-09-14 11:17:30 -04:00 by cmoriarty · 6 comments
Owner

What happens today

  • Nothing notifies. Email is the only channel, and production does not send it: its container has no mail credentials.
  • Nobody reviews. Production keeps 64 gates from 25 runs. Auto-approve answered 62 of them. A person answered one, a two-option question, 9 h 41 min after it was asked.
  • The proposal gate asks for 50 minutes of reading. Run 195's was 11,720 words, shown as a diff. The 15 decisions its explore step wrote for the reviewer sat in one of that diff's files, and the gate pointed at another.
  • The merge gate shows no proof. Its card has the pull request's title and whether it can merge. Run 195 had recorded 84 passed tests, 19 passed looks with 8 screenshots and 22 review notes left. None of it was on the gate.
  • The merge gate has no diff. Braid's one diff viewer is on the proposal gate. It lists a folder tree and takes a note from a line number 40 px wide.

What we want

A gate decided from a phone in a few minutes, because Braid shows what it checked instead of the files.

The notification, the proposal review and the change review on a phone

  • A notification that carries the verdict and opens the gate's page. A plain choice (an agent's question, the archive) is answered on the notification itself. This part is now the phone app, #538.
  • Proposal review: what Braid understood, what it will build, the calls it made for you, what is left out, and six checks. Scripts read all of it from the change. No model writes the page, and no step is added to a run.
  • Change review: screenshots with the scenarios they stand for, proof for each part, the tests, and what is left for you. Later: a fix shown failing before and passing after, and the app itself to try.
  • The diff, for an occasional look: what merges, sorted by the task group that wrote each file, with what the change adds besides code (packages, scripts, outside addresses) listed first. Lines wrap on a phone, and a rewritten file reads side by side on a desktop.

Try it: https://claude.ai/artifact/W6EpFqxmbDfGzWtgVHcMyp (opens for the owner only; the screens are run 195's own records).

Order of work

Slice What is new
1 Proposal page: shipped 2026-11-14, #537 in pull request #539 The page, and three small checks
2 Proof page at the merge gate The page, and proof joined up for each part
3 A push through the owner's ntfy server, beside email Dropped 2026-11-14 after a test on an iPhone. The push is now the phone app, #538
4 Auto-approve stops for you when a check wants a look Today it stops only for a thin review
5 Fix first; merge and archive as one decision Two changes to the landing gates
6 The diff, on a phone and a desktop A map of the change, a reader for both widths, one check
7 Tests it wrote were run; a fix fails before and passes after Two checks that run code
8 Try it: the app, live Braid serves the build to your network

Yours to decide

  1. Where the push goes. An ntfy server of the owner's own was tested on their iPhone on 2026-11-13 and dropped on 2026-11-14: see the comment on the phone test. The push will come from the phone app, #538.
  2. Should a run on auto-approve stop for you when a check wants a look (slice 4)?
  3. Merge and archive as one decision?
  4. The diff's lines: Braid's own renderer, improved, or a library that colours every language and adds about 165 kB to a 238 kB console.

Done when

On a real run, from a phone: a push arrives for the proposal and for the merge, each is answered from its page without opening a file, and an agent's question is answered from its notification inside the hour. A look at that change's diff on the phone needs no sideways scroll.

From an audit on 2026-11-13 of the code, production's records and run 195. The audit and the design's detail are in the comments. The diff was added the same day, after the owner's review. ntfy was dropped on 2026-11-14, after a test on a phone.

The original request (2026-09-14)

Currently we have email notifications, although I haven't seen one in a while. Either way, this ticket is to take the next step and implement optional ntfy notifications, assuming they can fulfill the job of asking a user questions in a well-designed way, so the user doesn't need to also open the braid web app to answer to human gates.

**What happens today** - **Nothing notifies.** Email is the only channel, and production does not send it: its container has no mail credentials. - **Nobody reviews.** Production keeps 64 gates from 25 runs. Auto-approve answered 62 of them. A person answered one, a two-option question, 9 h 41 min after it was asked. - **The proposal gate asks for 50 minutes of reading.** Run 195's was 11,720 words, shown as a diff. The 15 decisions its explore step wrote for the reviewer sat in one of that diff's files, and the gate pointed at another. - **The merge gate shows no proof.** Its card has the pull request's title and whether it can merge. Run 195 had recorded 84 passed tests, 19 passed looks with 8 screenshots and 22 review notes left. None of it was on the gate. - **The merge gate has no diff.** Braid's one diff viewer is on the proposal gate. It lists a folder tree and takes a note from a line number 40 px wide. **What we want** A gate decided from a phone in a few minutes, because Braid shows what it checked instead of the files. ![The notification, the proposal review and the change review on a phone](/attachments/0f8aa379-6b88-4eb7-9685-b0f799cba405) - **A notification that carries the verdict** and opens the gate's page. A plain choice (an agent's question, the archive) is answered on the notification itself. This part is now the phone app, #538. - **Proposal review:** what Braid understood, what it will build, the calls it made for you, what is left out, and six checks. Scripts read all of it from the change. No model writes the page, and no step is added to a run. - **Change review:** screenshots with the scenarios they stand for, proof for each part, the tests, and what is left for you. Later: a fix shown failing before and passing after, and the app itself to try. - **The diff, for an occasional look:** what merges, sorted by the task group that wrote each file, with what the change adds besides code (packages, scripts, outside addresses) listed first. Lines wrap on a phone, and a rewritten file reads side by side on a desktop. **Try it:** https://claude.ai/artifact/W6EpFqxmbDfGzWtgVHcMyp (opens for the owner only; the screens are run 195's own records). **Order of work** | | Slice | What is new | |---|---|---| | 1 | Proposal page: shipped 2026-11-14, #537 in pull request #539 | The page, and three small checks | | 2 | Proof page at the merge gate | The page, and proof joined up for each part | | 3 | ~~A push through the owner's ntfy server, beside email~~ | Dropped 2026-11-14 after a test on an iPhone. The push is now the phone app, #538 | | 4 | Auto-approve stops for you when a check wants a look | Today it stops only for a thin review | | 5 | Fix first; merge and archive as one decision | Two changes to the landing gates | | 6 | The diff, on a phone and a desktop | A map of the change, a reader for both widths, one check | | 7 | Tests it wrote were run; a fix fails before and passes after | Two checks that run code | | 8 | Try it: the app, live | Braid serves the build to your network | **Yours to decide** 1. ~~Where the push goes.~~ An ntfy server of the owner's own was tested on their iPhone on 2026-11-13 and dropped on 2026-11-14: see the comment on the phone test. The push will come from the phone app, #538. 2. Should a run on auto-approve stop for you when a check wants a look (slice 4)? 3. Merge and archive as one decision? 4. The diff's lines: Braid's own renderer, improved, or a library that colours every language and adds about 165 kB to a 238 kB console. **Done when** On a real run, from a phone: a push arrives for the proposal and for the merge, each is answered from its page without opening a file, and an agent's question is answered from its notification inside the hour. A look at that change's diff on the phone needs no sideways scroll. *From an audit on 2026-11-13 of the code, production's records and run 195. The audit and the design's detail are in the comments. The diff was added the same day, after the owner's review. ntfy was dropped on 2026-11-14, after a test on a phone.* <details><summary>The original request (2026-09-14)</summary> Currently we have email notifications, although I haven't seen one in a while. Either way, this ticket is to take the next step and implement optional ntfy notifications, assuming they can fulfill the job of asking a user questions in a well-designed way, so the user doesn't need to also open the braid web app to answer to human gates. </details>
cmoriarty changed title from Rich notifications that allow user to answer questions from mobile to Rich notifications: review gates you can answer from a phone 2026-11-13 11:38:51 -05:00
Author
Owner

The audit: every gate today

Gate Pipelines What a person is shown On a phone
Review the proposal (up to 3 rounds) thorough, solo, git-flow The change as a diff, a token estimate, "read gate-brief.md in the diff first" Three tabs: Decide, Files, Diff. Request changes wants a comment on a line
Review the plan (up to 3 rounds) plan PLAN.md, which is held to a minute's reading Reads well already
Merge the pull request all Title, branches, whether the forge will merge it, a link to the forge Fits, and proves nothing
Archive the change thorough, git-flow One sentence and a confirm Fits
File the bugs found all, when a run noted bugs Each drafted ticket: file, edit or dismiss Fits
File the plan, Start the work plan A question with two or three options Fits
An agent's question any agent step The question and its options Fits. Lapses after an hour
Recovery: a stalled step, a stopped fix loop, a change no model looked at any One sentence and two options Fits. None of the failure is shown

What the records say

  • Notifications. The policy is built: which events notify, one message per run per 30 s, quiet hours, reminders at 1 h, 4 h and a day. The only channel is email. Production's health page reads "disabled, no SMTP credentials", and the guide lists Gmail as unverified. A gate reaches a person only while the console is open.
  • What an email would say. "Needs you: Review the proposal", the question, a link. No summary, no check, no picture.
  • Who answers. 64 gates in 25 runs: auto-approve answered 25 proposal reviews, 18 merges, 18 archives and 1 bug filing. One agent's question lapsed at an hour, was asked again, and was answered 8 h 41 min later. That is every answer a person gave.
  • Reach. The console answers on the private network only, and anyone on it is the operator: there is no sign-in. Away from home the phone needs the VPN. Nothing here changes that.
  • Run 195's proposal gate. 11,720 words: proposal 1,564, design 2,252, tasks 2,207, eight specs 5,697. 65 requirements, 114 scenarios, 34 tasks. About 50 minutes at reading speed.
  • The decisions nobody sees. The explore step is told to write its open calls "where the reviewer will see it and can overrule it". Run 195 wrote 15, in plain words. They are one file in the diff; the gate's text names another.
  • Run 195's merge gate. Recorded and not shown: 71 unit and 13 browser tests passed; of 114 scenarios, 100 have a passing test, 11 were seen by the Visual check, 2 were left untested on purpose and 1 has nothing; the Visual check passed 19 of 19 with 8 screenshots and played a round; the code review found 27, fixed 5 and left 22; no CI.
  • What the gate could have said. 13 of the 19 test files that run wrote ran in no lane. That was found by reading the run afterwards (braid#505) and its cause is fixed (braid#506). The count was in the records when the gate opened.
  • The pull request's "How to review" begins with git checkout.
  • The summary can be read from the change. Of the 19 proposals still on production, all 19 have a Why, a capability list and the explore decisions; 18 have risks and 17 have non-goals.
  • Left over. Three gate kinds are defined and never opened (too_big, budget_stuck, new_project), and a gate's expiry has no code that acts on it.
## The audit: every gate today | Gate | Pipelines | What a person is shown | On a phone | |---|---|---|---| | Review the proposal (up to 3 rounds) | thorough, solo, git-flow | The change as a diff, a token estimate, "read gate-brief.md in the diff first" | Three tabs: Decide, Files, Diff. Request changes wants a comment on a line | | Review the plan (up to 3 rounds) | plan | PLAN.md, which is held to a minute's reading | Reads well already | | Merge the pull request | all | Title, branches, whether the forge will merge it, a link to the forge | Fits, and proves nothing | | Archive the change | thorough, git-flow | One sentence and a confirm | Fits | | File the bugs found | all, when a run noted bugs | Each drafted ticket: file, edit or dismiss | Fits | | File the plan, Start the work | plan | A question with two or three options | Fits | | An agent's question | any agent step | The question and its options | Fits. Lapses after an hour | | Recovery: a stalled step, a stopped fix loop, a change no model looked at | any | One sentence and two options | Fits. None of the failure is shown | ## What the records say - **Notifications.** The policy is built: which events notify, one message per run per 30 s, quiet hours, reminders at 1 h, 4 h and a day. The only channel is email. Production's health page reads "disabled, no SMTP credentials", and the guide lists Gmail as unverified. A gate reaches a person only while the console is open. - **What an email would say.** "Needs you: Review the proposal", the question, a link. No summary, no check, no picture. - **Who answers.** 64 gates in 25 runs: auto-approve answered 25 proposal reviews, 18 merges, 18 archives and 1 bug filing. One agent's question lapsed at an hour, was asked again, and was answered 8 h 41 min later. That is every answer a person gave. - **Reach.** The console answers on the private network only, and anyone on it is the operator: there is no sign-in. Away from home the phone needs the VPN. Nothing here changes that. - **Run 195's proposal gate.** 11,720 words: proposal 1,564, design 2,252, tasks 2,207, eight specs 5,697. 65 requirements, 114 scenarios, 34 tasks. About 50 minutes at reading speed. - **The decisions nobody sees.** The explore step is told to write its open calls "where the reviewer will see it and can overrule it". Run 195 wrote 15, in plain words. They are one file in the diff; the gate's text names another. - **Run 195's merge gate.** Recorded and not shown: 71 unit and 13 browser tests passed; of 114 scenarios, 100 have a passing test, 11 were seen by the Visual check, 2 were left untested on purpose and 1 has nothing; the Visual check passed 19 of 19 with 8 screenshots and played a round; the code review found 27, fixed 5 and left 22; no CI. - **What the gate could have said.** 13 of the 19 test files that run wrote ran in no lane. That was found by reading the run afterwards (braid#505) and its cause is fixed (braid#506). The count was in the records when the gate opened. - **The pull request's "How to review"** begins with `git checkout`. - **The summary can be read from the change.** Of the 19 proposals still on production, all 19 have a Why, a capability list and the explore decisions; 18 have risks and 17 have non-goals. - **Left over.** Three gate kinds are defined and never opened (`too_big`, `budget_stuck`, `new_project`), and a gate's expiry has no code that acts on it.
Author
Owner

The design in detail

A call with a note on it, proof for each part, the merge sheet and an agent's question

One record per gate. When a gate opens, a script reads the run's worktree and Braid's own records into one record: the summary, the checks, the proof. The page and the notification both read it, so they cannot disagree. Its check results are kept with the answer, so the log says what the person was shown.

The verdict. "Ready" when every check passes. Otherwise "N things to look at", listed first. Braid orders what you read. It does not decide for you.

Proposal review

On the page Read from Today
What Braid understood The proposal's Why written
What it will build The proposal's capability list; counts from the delta specs written
Calls it made for you The explore step's decisions written, not shown
Not included, risks The design's non-goals and risks written
A note on a call Sent to the reviser beside the call, as a line comment is new control
Check What it reads Today
Valid OpenSpec's strict check, after the last revision recorded
Complete Every part has requirements, scenarios and a task group new
Existing behaviour Requirements added, changed and removed, the last two by name new
Reviewed Lenses that read it, findings raised and resolved, a thin reading said recorded
Size Each task group against one step's allowance recorded
Clear of other work No other open change or active run on the same parts new

Change review

On the page Read from Today
See it The Visual check's screenshots, each with its scenarios recorded, shown only under that step
It was used The Visual check's session recorded
Proof by part Each scenario: a passing test, seen in the browser, left out on purpose, or nothing the join is new
Tests The lanes' record and CI's jobs recorded
Left for you Review notes left, the summary's "Not done" recorded
The change itself The pull request's diff, sorted by who wrote each file. Its own comment has the detail new at this gate
Fix first A third answer; your words go to the next fix round, as at a stopped fix loop new
Try it Braid starts the run's build and serves it to your network for a set time new
Check What it reads Today
Tests, Seen working, Code review, Tasks, Can merge The run's records recorded
Scenarios with proof The join above; a scenario with nothing is named new
Same code The code the tests ran on against the code that merges new
Scope What the change adds besides code: packages, scripts, outside addresses, keys, install hooks, skipped tests, removed code new
Tests it wrote were run Every test file the change added, against what each lane ran new; lanes must record files
A fix fails before and passes after The change's own tests on the base, then on the head new; runs code

Notifications

Gate It says Answered on the notification
Proposal review Parts, requirements, checks passed, minutes to read No. It opens the page
Merge Scenarios with proof, things to look at, one screenshot No. It opens the page
Archive Where it merged Archive
An agent's question The question and the time left Up to three options
File the bugs, recovery What was found, or what stopped No. It opens the page

A review opens a page because a notification holds one picture, three buttons and 4,096 bytes (ntfy's limits, read in its documentation). A button answers with the gate's own reply token, which the API accepts already and nothing sends today. An answered gate's notification is cleared.

To settle in the proposal

  • A stale call. A revision can overturn a call the explore step listed. The page shows the calls, then what each revision changed.
  • Evidence reads like a log. The Visual check writes "grounded true, runnerY 0 -> 5". The page shows it as written. A plain line for each screenshot would be a change to its brief.
  • What counts as a look. 22 minor notes should not stop a run. The thresholds want real runs before slice 4.
  • Try it runs the agent's code in your browser, the one place that holds your authority, and the API accepts any request from the private network. It must refuse other origins first.
  • Screenshots are 1280 px wide. A phone-width capture of the same pages comes later.
## The design in detail ![A call with a note on it, proof for each part, the merge sheet and an agent's question](/attachments/8edfb940-1b5d-4b79-b30f-42cf24ae6d2f) **One record per gate.** When a gate opens, a script reads the run's worktree and Braid's own records into one record: the summary, the checks, the proof. The page and the notification both read it, so they cannot disagree. Its check results are kept with the answer, so the log says what the person was shown. **The verdict.** "Ready" when every check passes. Otherwise "N things to look at", listed first. Braid orders what you read. It does not decide for you. ### Proposal review | On the page | Read from | Today | |---|---|---| | What Braid understood | The proposal's Why | written | | What it will build | The proposal's capability list; counts from the delta specs | written | | Calls it made for you | The explore step's decisions | written, not shown | | Not included, risks | The design's non-goals and risks | written | | A note on a call | Sent to the reviser beside the call, as a line comment is | new control | | Check | What it reads | Today | |---|---|---| | Valid | OpenSpec's strict check, after the last revision | recorded | | Complete | Every part has requirements, scenarios and a task group | new | | Existing behaviour | Requirements added, changed and removed, the last two by name | new | | Reviewed | Lenses that read it, findings raised and resolved, a thin reading said | recorded | | Size | Each task group against one step's allowance | recorded | | Clear of other work | No other open change or active run on the same parts | new | ### Change review | On the page | Read from | Today | |---|---|---| | See it | The Visual check's screenshots, each with its scenarios | recorded, shown only under that step | | It was used | The Visual check's session | recorded | | Proof by part | Each scenario: a passing test, seen in the browser, left out on purpose, or nothing | the join is new | | Tests | The lanes' record and CI's jobs | recorded | | Left for you | Review notes left, the summary's "Not done" | recorded | | The change itself | The pull request's diff, sorted by who wrote each file. Its own comment has the detail | new at this gate | | Fix first | A third answer; your words go to the next fix round, as at a stopped fix loop | new | | Try it | Braid starts the run's build and serves it to your network for a set time | new | | Check | What it reads | Today | |---|---|---| | Tests, Seen working, Code review, Tasks, Can merge | The run's records | recorded | | Scenarios with proof | The join above; a scenario with nothing is named | new | | Same code | The code the tests ran on against the code that merges | new | | Scope | What the change adds besides code: packages, scripts, outside addresses, keys, install hooks, skipped tests, removed code | new | | Tests it wrote were run | Every test file the change added, against what each lane ran | new; lanes must record files | | A fix fails before and passes after | The change's own tests on the base, then on the head | new; runs code | ### Notifications | Gate | It says | Answered on the notification | |---|---|---| | Proposal review | Parts, requirements, checks passed, minutes to read | No. It opens the page | | Merge | Scenarios with proof, things to look at, one screenshot | No. It opens the page | | Archive | Where it merged | Archive | | An agent's question | The question and the time left | Up to three options | | File the bugs, recovery | What was found, or what stopped | No. It opens the page | A review opens a page because a notification holds one picture, three buttons and 4,096 bytes (ntfy's limits, read in its documentation). A button answers with the gate's own reply token, which the API accepts already and nothing sends today. An answered gate's notification is cleared. ### To settle in the proposal - **A stale call.** A revision can overturn a call the explore step listed. The page shows the calls, then what each revision changed. - **Evidence reads like a log.** The Visual check writes "grounded true, runnerY 0 -> 5". The page shows it as written. A plain line for each screenshot would be a change to its brief. - **What counts as a look.** 22 minor notes should not stop a run. The thresholds want real runs before slice 4. - **Try it runs the agent's code in your browser**, the one place that holds your authority, and the API accepts any request from the private network. It must refuse other origins first. - **Screenshots are 1280 px wide.** A phone-width capture of the same pages comes later.
Author
Owner

The diff: checking that nothing extra came along

Added 2026-11-13, after the owner's review: the design had no place to read the code. The diff is not the main way to decide a gate. It is for the occasional look that confirms a change holds only what was asked for.

The diff on a phone: the change before any line, files by the group that wrote them, rewritten lines, a note on a line

What happens today

  • One viewer, on the proposal gate. The merge gate has none. Its card links to the pull request on the forge.
  • Braid's diff route serves the worktree, not what merges. Asked for run 195's whole change it returns 144 files and 19,238 lines, and 43 of those files are Braid's own records. The pull request held 101 files and 16,116 lines.
  • A folder tree, in one response. Nothing says which files are worth opening, and all 833 KB arrive before a line draws.
  • On a phone: a note starts from a line number 40 px wide. Notes live in the page's memory and are gone when the phone drops the tab. A new file is a wall of green, and a lockfile is 2,295 lines like any other.
  • Two things already work and stay. Lines wrap, so nothing runs off the screen. A note on a line becomes the request for changes.

What we want

On the page Read from Today
What merges The pull request's diff at the merge gate, the change's own files at the proposal gate the worktree
Where the lines went Paths: the app, its tests, lockfiles, the plan, files Braid's scripts write new
What it adds besides code Scripts over the added lines (next table) new
Files by the group that wrote them Each apply step's own diff, from the checkpoints recorded, the sorting is new
After the groups What the code review and each fix round rewrote recorded, shown nowhere
Not for reading The plan, Braid's own files and lockfiles, folded new
A file A new file is shown as the file. A rewritten one shows old and new lines with the changed words marked and unchanged lines folded a new file is drawn as added lines
A note on a line A tap on the line, kept on the server, sent back with Fix first from the line number, in memory
Seen A mark for each file, kept on the server new
What it adds Run 195
Packages 13. The plan's text does not mention websockets or jsdom
Scripts that can be run 1: scripts/services.sh, from group 9, whose title names it
Outside addresses None in the code, one link in the README
Keys or passwords None
Runs by itself: an install hook, a CI workflow, a container file None
Tests skipped or narrowed to one None
Existing code changed or removed None

Run 195's 16,116 lines: the app 6,981, its tests 4,680, lockfiles 2,740, the plan 1,266, Braid's own files 449.

The second table becomes one check on the merge gate, Scope. It asks for a look when a change reaches outside, holds a key, runs by itself, skips a test or removes existing code. A package the plan does not mention is listed, and does not ask for a look by itself.

On a phone

  • One column. Lines wrap with a hanging indent, so no line hides its end off the screen. Of the app's and tests' 11,661 lines, 73% fit a phone's 45 characters and 3% are longer than 80.
  • One narrow number column, a bar and a sign for added and removed, indents drawn at 60% width.
  • Previous, Seen and Next sit under the thumb. A file's lines load when it is opened.

On a desktop

The same page on a desktop: the map, a rewritten file side by side, your notes

The same page in three columns: the map, the file, your notes. A rewritten file can be read side by side. Keys: j k for the next and previous file, x for seen, s for side by side.

Drawing the lines: ours or a library

Tried on four of run 195's patches, at 390 px and at 1280 px.

Braid's own rows, improved @pierre/diffs 1.6.4 @git-diff-view/react 0.1.8
At 390 px As in the mock Reads well. Wrapped lines lose their indent Breaks words mid-letter, two number columns
Side by side at 1280 px To build, as in the mock Very good Good
Colour 6 languages by pattern, 87% of run 195's lines Every language Every language
Changed words marked, folds that open To build, as in the mock Built in Built in
Added to the console, 238 kB compressed today Nothing About 165 kB, loaded when a diff opens About 325 kB

Recommended: Braid's own rows. The parser, the notes and the wrapping exist, the mock shows the rest is small, and the phone layout stays ours. Adding CSS and HTML to the colouring takes it to 95% of run 195's lines. @pierre/diffs is the fallback if side by side or colour turns out costly. It goes in behind one component.

To settle in the proposal

  • A run that applied in one step. Every file then has one author, and the map sorts by folder under the same headings.
  • A change to existing code. Run 195 built from nothing. On an existing project the page leads with what was changed and removed. The first run of that kind is the real test.
  • "Not in the plan" is a text match. It found websockets, which the code explains in a comment. It informs and does not gate.
  • Notes at the merge gate need Fix first (slice 5). Until then they work at the proposal gate, as today.
  • Since you last looked. After Fix first the page should open on what that round changed. The checkpoints hold it.
## The diff: checking that nothing extra came along Added 2026-11-13, after the owner's review: the design had no place to read the code. The diff is not the main way to decide a gate. It is for the occasional look that confirms a change holds only what was asked for. ![The diff on a phone: the change before any line, files by the group that wrote them, rewritten lines, a note on a line](/attachments/81a85ea8-ce7a-48c1-926d-9a856559c372) **What happens today** - **One viewer, on the proposal gate.** The merge gate has none. Its card links to the pull request on the forge. - **Braid's diff route serves the worktree, not what merges.** Asked for run 195's whole change it returns 144 files and 19,238 lines, and 43 of those files are Braid's own records. The pull request held 101 files and 16,116 lines. - **A folder tree, in one response.** Nothing says which files are worth opening, and all 833 KB arrive before a line draws. - **On a phone:** a note starts from a line number 40 px wide. Notes live in the page's memory and are gone when the phone drops the tab. A new file is a wall of green, and a lockfile is 2,295 lines like any other. - **Two things already work and stay.** Lines wrap, so nothing runs off the screen. A note on a line becomes the request for changes. **What we want** | On the page | Read from | Today | |---|---|---| | What merges | The pull request's diff at the merge gate, the change's own files at the proposal gate | the worktree | | Where the lines went | Paths: the app, its tests, lockfiles, the plan, files Braid's scripts write | new | | What it adds besides code | Scripts over the added lines (next table) | new | | Files by the group that wrote them | Each apply step's own diff, from the checkpoints | recorded, the sorting is new | | After the groups | What the code review and each fix round rewrote | recorded, shown nowhere | | Not for reading | The plan, Braid's own files and lockfiles, folded | new | | A file | A new file is shown as the file. A rewritten one shows old and new lines with the changed words marked and unchanged lines folded | a new file is drawn as added lines | | A note on a line | A tap on the line, kept on the server, sent back with Fix first | from the line number, in memory | | Seen | A mark for each file, kept on the server | new | | What it adds | Run 195 | |---|---| | Packages | 13. The plan's text does not mention `websockets` or `jsdom` | | Scripts that can be run | 1: `scripts/services.sh`, from group 9, whose title names it | | Outside addresses | None in the code, one link in the README | | Keys or passwords | None | | Runs by itself: an install hook, a CI workflow, a container file | None | | Tests skipped or narrowed to one | None | | Existing code changed or removed | None | Run 195's 16,116 lines: the app 6,981, its tests 4,680, lockfiles 2,740, the plan 1,266, Braid's own files 449. The second table becomes one check on the merge gate, **Scope**. It asks for a look when a change reaches outside, holds a key, runs by itself, skips a test or removes existing code. A package the plan does not mention is listed, and does not ask for a look by itself. **On a phone** - One column. Lines wrap with a hanging indent, so no line hides its end off the screen. Of the app's and tests' 11,661 lines, 73% fit a phone's 45 characters and 3% are longer than 80. - One narrow number column, a bar and a sign for added and removed, indents drawn at 60% width. - Previous, Seen and Next sit under the thumb. A file's lines load when it is opened. **On a desktop** ![The same page on a desktop: the map, a rewritten file side by side, your notes](/attachments/8e9e9a63-b054-4131-b5b2-5eca12089df5) The same page in three columns: the map, the file, your notes. A rewritten file can be read side by side. Keys: `j` `k` for the next and previous file, `x` for seen, `s` for side by side. **Drawing the lines: ours or a library** Tried on four of run 195's patches, at 390 px and at 1280 px. | | Braid's own rows, improved | `@pierre/diffs` 1.6.4 | `@git-diff-view/react` 0.1.8 | |---|---|---|---| | At 390 px | As in the mock | Reads well. Wrapped lines lose their indent | Breaks words mid-letter, two number columns | | Side by side at 1280 px | To build, as in the mock | Very good | Good | | Colour | 6 languages by pattern, 87% of run 195's lines | Every language | Every language | | Changed words marked, folds that open | To build, as in the mock | Built in | Built in | | Added to the console, 238 kB compressed today | Nothing | About 165 kB, loaded when a diff opens | About 325 kB | Recommended: Braid's own rows. The parser, the notes and the wrapping exist, the mock shows the rest is small, and the phone layout stays ours. Adding CSS and HTML to the colouring takes it to 95% of run 195's lines. `@pierre/diffs` is the fallback if side by side or colour turns out costly. It goes in behind one component. **To settle in the proposal** - **A run that applied in one step.** Every file then has one author, and the map sorts by folder under the same headings. - **A change to existing code.** Run 195 built from nothing. On an existing project the page leads with what was changed and removed. The first run of that kind is the real test. - **"Not in the plan" is a text match.** It found `websockets`, which the code explains in a comment. It informs and does not gate. - **Notes at the merge gate need Fix first** (slice 5). Until then they work at the proposal gate, as today. - **Since you last looked.** After Fix first the page should open on what that round changed. The checkpoints hold it.
Author
Owner

The phone test, and why ntfy is dropped

What was tested (2026-11-13)

Five real notifications on the owner's iPhone, through their own ntfy server, one for each kind of review: a proposal, a merge with a screenshot, an app to try, a diff, and an archive with an answer button. All five arrived and opened their pages. The proposal was approved from its page on the phone.

What an iPhone shows

  • A title, plain text, one picture, and a tap that opens a page.
  • Buttons that give no sign they worked. A second notification, "Answer received", went out 0.17 s after the press. The owner: "The answer came quick, but it's just not going to cut it."
  • A late or repeated press is refused by Braid, and the phone shows nothing for that either.
  • No formatted text, and a sent notification cannot be changed or removed.

Decided (owner, 2026-11-14)

ntfy is not pursued. The notification becomes a phone app, #538. The pages are unaffected: the proposal summary (#537), the proof and the diff.

## The phone test, and why ntfy is dropped **What was tested (2026-11-13)** Five real notifications on the owner's iPhone, through their own ntfy server, one for each kind of review: a proposal, a merge with a screenshot, an app to try, a diff, and an archive with an answer button. All five arrived and opened their pages. The proposal was approved from its page on the phone. **What an iPhone shows** - A title, plain text, one picture, and a tap that opens a page. - Buttons that give no sign they worked. A second notification, "Answer received", went out 0.17 s after the press. The owner: "The answer came quick, but it's just not going to cut it." - A late or repeated press is refused by Braid, and the phone shows nothing for that either. - No formatted text, and a sent notification cannot be changed or removed. **Decided (owner, 2026-11-14)** ntfy is not pursued. The notification becomes a phone app, #538. The pages are unaffected: the proposal summary (#537), the proof and the diff.
Author
Owner

Slice 1 shipped: the proposal summary, #537, in pull request #539. The phone app that will open it is #538.

Slice 1 shipped: the proposal summary, #537, in pull request #539. The phone app that will open it is #538.
Author
Owner

Closing: everything here has shipped or moved to another issue.

  • Slice 1, the proposal summary, shipped in braid#537 (pull request 539).
  • The phone side is braid#538, the app. ntfy was dropped on 2026-11-14.
  • Slices 2 to 8 (the merge gate's proof, auto-approve stopping on a check, the diff, Fix first, Try it) are braid#548. The audit and design comments above stay here as its reference.
Closing: everything here has shipped or moved to another issue. - Slice 1, the proposal summary, shipped in braid#537 (pull request 539). - The phone side is braid#538, the app. ntfy was dropped on 2026-11-14. - Slices 2 to 8 (the merge gate's proof, auto-approve stopping on a check, the diff, Fix first, Try it) are braid#548. The audit and design comments above stay here as its reference.
Sign in to join this conversation.
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
cmoriarty/braid#26
No description provided.