Skip to content

feat: the reader release — write safety, a regeneration gate, and portable decisions - #3

Merged
donaldsteele merged 6 commits into
mainfrom
feat/reader-release
Aug 23, 2026
Merged

donaldsteele merged 6 commits into
mainfrom
feat/reader-release

Conversation

@donaldsteele

Copy link
Copy Markdown
Owner

Nine features from a roadmap review, plus the write-safety work that gates them.

What is here

Feature Where
1 Selecting a tag lists the pages it names left rail
2 Right-click menus, on one head-capability object everywhere
3 --mark, --since, --fail-on-regression CLI
5 Confirm before vault-wide writes; status panel; status-bar slots shell
6 Patch sets — repair planned as a unified diff, never applied Core + CLI
7 Find in page (Ctrl+F) centre pane
8 Start screen, recent vaults, folder drop, five empty states shell
9 Findings scroll to their link; the ledger becomes a control centre pane
10 Rung fourteen becomes a committable file Core, all heads

Rank 4 (SARIF output and a GitHub Action) was cut: it needs a published release tag to
download, and release.yml has still never run.

The three that change a contract

Two files leave .detangle/. The settled-ambiguity map and the marked baseline now sit
at the vault root as .detangle-choices and .detangle-baseline.json. Both are decisions
rather than cache, and the FAQ tells readers they may delete .detangle at any time — which
was true of neither. They are meant to be committed, and detangle-lint and the static
export now read them, so a published site resolves an ambiguous link the way the person who
settled it decided rather than the way the chain would guess.

Both vault-wide writers ask first. Fix all safe and Normalize links in place each
rewrote every markdown file in the vault straight off a click — no confirmation, no list, no
undo — against a stated promise of being non-destructive by default. Both now show how many
links in how many files, list every file, and do nothing until confirmed. There is still no
undo; the list is what stands in for one.

detangle-lint writes one file now. Only --mark, and only when asked. The
documentation's "it never writes to the vault" is corrected rather than quietly broken.

Two bugs found on the way

SearchIndex's tag filter matched any tag merely starting with the value, so tag:llm
claimed llm-ops as a child it is not — and the rail's count and the search's count
disagreed. Both sides now read a tag the same way.

PatchSet.Summary() counted hunks and called them links. Two links on one line coalesce
into one hunk (correct for a diff, since two hunks claiming a line would apply the first
rewrite twice), so --emit-patch was understating multi-link lines. Hunk now records how
many links it covers.

Decisions taken

  • HeadCapabilities is injected at the composition root, not probed. It replaces
    OpenExternal's silent PlatformNotSupportedException swallow — offering a command,
    taking the click, doing nothing — with visibility bound to what the head actually wired.
  • VaultScanner stayed synchronous. Only the shell's call moved off the UI thread, so no
    Core test touches a scheduler.
  • RepairPolicy has no IncludeAnchors. Anchor findings carry a suggested heading and
    the rewriter replaces a link's target, so the flag would have planned nothing.
  • PatchSet.Apply and a GUI review tab are deliberately absent. They want an undo behind
    them.

Still true after this

There is no undo anywhere. It gates anchor repair, mention weaving, and applying a patch
from the application. What changed is that the irreversible actions now show the whole set
before doing any of it.

Checks

Solution and the out-of-solution WASM head both build clean. 811 tests pass — 425 Core, 156
App, 230 Rendering. Every commit builds on its own; verified by checking each out in turn.

🤖 Generated with Claude Code

https://claude.ai/code/session_01RAeEodXFxiedA3tcxoeN1v

donaldsteele and others added 6 commits August 22, 2026 21:46
Four things move into Core so that every head agrees about them.

ChoiceStore takes the fourteenth resolution rung — which document an ambiguous
link was decided to mean — out of Detangle.App and puts it in .detangle-choices
at the vault root. It is the only rung a person writes and the only one a vault
cannot re-derive, so it has to travel with the markdown; until now the desktop
app that settled an ambiguity and the CLI, the exporter, the demo and every test
each resolved that link differently. The format is one sorted line per decision
with the reason as a comment, so it diffs cleanly in a pull request.

BaselineStore does the same for the marked baseline, which used to live under a
key in Detangle.App's own state.json — a file the FAQ describes as a disposable
cache. A baseline is the opposite of a cache: it is what a repository commits so
the next generation run can be measured against it.

VaultRepair plans a repair across a vault and returns a PatchSet that
ToUnifiedDiff can print. Every ingredient was already here, but the only thing
that composed them was a method on an Avalonia view model, so nothing outside
the GUI could repair a wiki it had just been told was broken. RepairPolicy
becomes the one definition of "safe". Two links on one line coalesce into a
single hunk, because emitting two that both claim the line gives a patch which
applies the first rewrite twice; the hunk records how many links it covers, so a
caller reporting "what will change" can say links rather than lines.

TagNode.AllDocuments answers what a tag names, including everything nested under
it, and the search index's tag filter is corrected to agree: the old LIKE
matched any tag merely starting with the value, so tag:llm claimed llm-ops as a
child it is not.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RAeEodXFxiedA3tcxoeN1v
… came from

Three additions to DocumentRenderer, all of them things the shell could not do
because the control tree kept no way back to the source.

A tag chip becomes a button raising TagActivated, so clicking #llm/agents in a
page can show the pages sharing it rather than being decoration.

Every rendered link carries a LinkOrigin — the line and column it was written at
— on its Tag, the same idiom a heading already uses for its slug. A Link Doctor
finding names a line, and nothing connected that to anything on screen, so
selecting a broken link opened the page at the top and left the reader to hunt
for it.

A link's context menu offers to copy the explanation of how it resolved. Which
rung answered a link is the product, and until now it could only be read off a
tooltip, never quoted into an issue or a commit message.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RAeEodXFxiedA3tcxoeN1v
… a diff

A wiki a generator rewrites wholesale is almost never at zero broken links, so
--fail-on error fails on every run once anything is broken and cannot tell the
run that made things worse from the twenty that did not. Core has modelled that
difference since the regeneration diff landed, but only the GUI could mark a
baseline or compare against one, so the loop had no gate.

--mark records the vault as it stands, --since reports what changed as a delta
block, and --fail-on-regression exits 1 when a link broke or now needs a later
rung than it did, whatever the absolute counts are. An already-broken wiki that
did not get worse passes. The delta is taken before the baseline is overwritten,
so --mark --since reports the run being marked rather than an empty comparison
against itself.

--emit-patch writes the repair as a unified diff, with the rung that resolved
each link named above its hunk. The command still writes nothing to the vault,
which is the promise the documentation already made; --patch-policy chooses
between the mechanical rewrites and the edit-distance guesses.

--choices reads settled ambiguities from a named file, and both the CLI and the
headless site exporter now load the vault's own by default. Without that, a
published site resolved an ambiguous link differently from the application that
settled it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RAeEodXFxiedA3tcxoeN1v
…ll could not do

The two commands that rewrite every markdown file in the vault — Fix all safe
and Normalize links in place — each ran straight off a click, with no
confirmation, no list of what would change and no undo, in a product whose
stated promise is that it is non-destructive by default. Both now propose: a
card docked in the Link Doctor's action region names how many links in how many
files, lists every file, and does nothing until confirmed, with Cancel as the
default and Escape as the way out. The plan comes from the same Core planner the
CLI emits patches from, so the card lists exactly what the write does.

The status bar gains a slot model — message left, one transient action centre,
counters right — and an expandable panel that keeps the last fifty messages
untrimmed and selectable, with the full text of an exception whose first line is
all the bar can show. The graph's hover readout moves into the graph pane's own
header, because a mouse crossing the picture was erasing whatever the bar had
just reported.

HeadCapabilities states what each head can do, once, at startup. The pattern it
replaces is OpenExternal's silent PlatformNotSupportedException swallow: offer a
reader a command, take their click, do nothing. Visibility binds to it instead.

Selecting a tag lists the pages it names rather than opening an arbitrary one of
them — the tree showed a count of fourteen and then refused to show the
fourteen. Right-click menus arrive on every list, built on one shared factory.
Selecting a finding scrolls to the offending link and pulses it, and says so
when the line has moved rather than landing at the top of the page and letting
the reader assume. The link ledger becomes a control: clicking a band narrows
the Doctor to that page and that band. Ctrl+F finds in the open page, over the
rendered text rather than the markdown, and defers to the editor's own search
when the editor has focus. First launch shows a start screen with the vaults
opened before instead of three empty panes, folders can be dropped on the
window, and the five other empty states say what an empty pane means.

Opening a vault moves off the UI thread. The scan parses every file in the
folder, which on a large vault is long enough to freeze the window — and the
recent list makes that the first thing a reader meets, every launch. Only the
scan moves; everything after it touches observable collections.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RAeEodXFxiedA3tcxoeN1v
…rm step

A new page for regeneration: marking a baseline, reading a delta, and gating a
pipeline on what got worse rather than on an absolute count. It is the argument
the site has been making since 0.2.0 with no page behind it.

link-resolution gains where rung fourteen actually lives, now that it is a file
beside the markdown rather than something inside one application. detangle-lint
documents the four new flags and stops claiming it never writes to the vault at
all — it writes the baseline, and only when asked.

link-doctor and editing-and-export say that the two vault-wide rewrites ask
first and that there is no undo, which is why the list comes first. The FAQ
distinguishes the two committable files at the vault root from the cache in
.detangle that it still invites you to delete. keyboard adds Ctrl+F and
backfills Ctrl+B, Ctrl+Shift+B and Ctrl+W, which it had never listed.

The site's regeneration section gains the command that gates on it, the Link
Doctor section says the settled choice is committable, and the CI section covers
--emit-patch.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RAeEodXFxiedA3tcxoeN1v
Two usings went in beside the code that needed them rather than in order, which
the compiler does not care about and `dotnet format --verify-no-changes` does.
The Dispatcher call that was fully qualified to work around the missing using
loses the qualification with it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RAeEodXFxiedA3tcxoeN1v
@donaldsteele
donaldsteele merged commit 9f3e25b into main Aug 23, 2026
5 checks passed
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