diff --git a/docs/active-work.md b/docs/active-work.md index 4778d4f..8ee9881 100644 --- a/docs/active-work.md +++ b/docs/active-work.md @@ -111,8 +111,10 @@ lesson, §1 for the two framings). are identical on every machine. Remote names are otherwise machine-local: `origin` may name this canonical URL, a release mirror, or something else, and therefore has no authority by name alone. -- Canonical base at this snapshot: **`githubsucks/main` @ `12f2970`** — - the macOS CI signal-integrity registry **#215**, atop `f186253`: +- Canonical base at this snapshot: **`githubsucks/main` @ `db1bbe9`** — + the tree primitive **#217**, atop `2657568` the macOS CI + signal-integrity **Stage 2 #216** (which retired R2 and R4), atop + `12f2970` its Stage 1 registry **#215**, atop `f186253`: bottom-panel Stage 3 **#213**, which completes Arc 7, atop the post-release accuracy pass **#212**, Distribution Stage 1 **#211** (released as **v1.1.0**, the first release with prebuilt binaries), @@ -125,8 +127,9 @@ lesson, §1 for the two framings). `Hello` still advertises v20** — two different facts, and #184 landed only the first. **The recovery floor advances with the base**, so the check below - now requires `12f2970` or newer; a tree at `f186253` no longer - passes. That is deliberate — a check accepting an older commit than + now requires `db1bbe9` or newer; a tree at `12f2970` no longer + passes — it would lack #216 and #217, both of which this file + describes as complete. That is deliberate — a check accepting an older commit than the declared base passes on a tree the rest of this file does not describe. **Lanes below that name an older base have not been re-based; derive @@ -164,21 +167,34 @@ git worktree list git status --short --branch ``` -The `git log` command must expose `12f2970` — the base named above — or a +The `git log` command must expose `db1bbe9` — the base named above — or a newer intentional main. Keep this threshold and the canonical-base line in step: a recovery check that accepts an older commit than the base it declares canonical will pass on a tree the rest of this file does not describe. If it does not, stop and repair the remote/fetch configuration. -**This path was exercised, not asserted, at this snapshot** — ahead of a -machine move. From an empty directory: `git clone` the canonical URL, -add the `githubsucks` alias, `git fetch githubsucks --prune`, confirm -`f186253` is an ancestor of `githubsucks/main`, and recover a lane with -the three-argument `git worktree add -b githubsucks/` -form. All four steps ran clean. **The two-argument form still does not -work** for a remote-only branch (`fatal: invalid reference`), which is -why every lane below spells out the `-b` form. +**This path was exercised, not asserted, at this snapshot** — re-run +from an empty directory on 2026-08-06 when the base advanced to +`db1bbe9`, rather than having its SHA swapped. `git clone` the +canonical URL, add the `githubsucks` alias, `git fetch githubsucks +--prune`, confirm `db1bbe9` is an ancestor of `githubsucks/main`, and +recover a lane with the three-argument `git worktree add -b + githubsucks/` form. All four steps ran clean. + +**Correction, found by re-running it.** This file claimed the +two-argument form fails for a remote-only branch with `fatal: invalid +reference`. **It does not fail.** On git 2.55.0 it *succeeds* and +leaves a **detached HEAD** — no branch, no upstream, `git status` +reporting `## HEAD (no branch)`. + +Still use `-b`, but for the opposite reason to the one recorded: the +danger is not an error that stops you, it is that nothing stops you. +Work committed in that worktree sits on no branch, is not pushed by a +bare `git push`, and is exactly the "uncommitted work does not travel" +hazard in a shape that looks committed. **A documented error message +that never appears is worse than no documentation**, because the reader +waits for a signal that is not coming. ## Docs absorption after #217 — PR #218 OPEN diff --git a/docs/agent-handoff.md b/docs/agent-handoff.md index b34fc5e..e94db13 100644 --- a/docs/agent-handoff.md +++ b/docs/agent-handoff.md @@ -1,11 +1,19 @@ # Agent handoff — cross-machine continuity -**Last updated: 2026-08-05.** The live CI-triage rule in §5 now points -at `docs/ci-red-signatures.md` (**PR #215, merged as `main` @ -`12f2970`**; its Stage 2 hardening is in flight — see -`docs/active-work.md`), which keys on -signature rather than test name; the hazards list this file used to -carry is retired, and its two unevidenced entries are audit notes there. +**Last updated: 2026-08-06.** `main` is **`db1bbe9`** — the tree +primitive **#217**, atop **#216**, which completed the macOS CI +signal-integrity arc by retiring R2 and R4 with discriminating +witnesses, atop **#215**, which built the registry. **That arc is +retired**; its live residue (R1, R3, and the newer R5 and R6) is +re-homed to the async-runtime, reap-ledger, and readiness-helper-audit +lanes in `docs/active-work.md`. + +The live CI-triage rule in §5 points at `docs/ci-red-signatures.md`, +which keys on **signature, not test name** — and, since 2026-08-06, +on **signature plus date**: a red matching a retired row is a +recurrence only if it *postdates* the retirement, and an earlier one +corroborates instead. The hazards list this file used to carry is +retired, and its two unevidenced entries are audit notes there. Previously **2026-08-04, as bottom-panel Stage 3 #213 — the adopter default flip, which COMPLETES ARC 7: omitting `display` now means the panel, and the workbench's panel half is done on both frontends. Beneath @@ -75,9 +83,16 @@ reads it the way you just did. For volatile branches, checkpoints, verification, and recovery commands, read `docs/active-work.md` immediately after this file. -## 1. Where the project stands (2026-08-01) +## 1. Where the project stands (2026-08-06) -- **`main` @ `f186253`.** Bottom-panel Stage 3 **#213** completes Arc 7, +- **`main` @ `db1bbe9`.** The **tree primitive #217** — `listview` rows + take optional `depth`/`id`, collapse is primitive-owned, folding is + **local projection state and not a refresh protocol**, and the LSP + outline is the sole adopter (`COHERENCE.md` §14 ◐; §20 says adoption, + not construction). Atop `2657568` **#216**, which completed the macOS + CI signal-integrity arc, atop `12f2970` **#215**, which built + `docs/ci-red-signatures.md`. Beneath those, `f186253`: bottom-panel + Stage 3 **#213** completes Arc 7, atop the post-release accuracy pass #212 and `000b6cd` / **v1.1.0**. Beneath that, Distribution Stage 1 #211 lands atop the docs absorption #210, the CI CRDT coverage lane #209, @@ -137,13 +152,27 @@ commands, read `docs/active-work.md` immediately after this file. reason the anchor consumer works, because **the outline has no `on_refresh` at all**. A design requiring the consumer to re-supply rows on every fold would have fitted no existing consumer. - - **Identity is consumer-supplied and compared by equality; the - primitive never derives one.** `item` is opaque by design. The - outline uses `line:col`, because the `::` parent chain collides on - overloads and same-named siblings — exactly where a stale expansion - would reattach to the wrong node. **Selection is re-seated by id, - not by line**, since a fold inserts or removes rows above the - cursor. + - **Identity is consumer-supplied and the primitive never derives + one**, but it is **not opaque**: `row.id` must be a **string or + number, unique among rows, and not NaN**, enforced by `check_ids` + where rows enter (`open` and `refresh`). Review narrowed this from + "opaque, compared by equality", which was **two contracts wearing + one name** — selection compares with `==`, honouring `__eq`, while + collapse state stores ids as **table keys**, and Lua indexes tables + by raw identity consulting no metamethod. A table id satisfied one + half and silently failed the other. Uniqueness and not-NaN came + from the same pass: every lookup resolves to the **first** match, + so a duplicate makes selecting the later row toggle the earlier, + and `0/0` is a `number` Lua refuses as a key. The outline uses + `line:col`, because the `::` parent chain collides on overloads and + same-named siblings — exactly where a stale expansion would + reattach to the wrong node. **Selection is re-seated by id, not by + line**, since a fold inserts or removes rows above the cursor. + - **`item` is optional in the API and was mandatory in practice.** + `line_to_item` is sparse when a row omits it, and `seat_cursor` + took `#` of that map — a display-only tree stranded the cursor on + the header. It counts visible rows explicitly now. Every existing + test supplied `item`, so none could reach it. - **`has_children` must read the FULL row array, not the rendered subset.** A collapsed node's children are absent from the rendered map by construction, so asking the view would answer "no" for every diff --git a/docs/ci-red-signatures.md b/docs/ci-red-signatures.md index 669ec5d..66e9949 100644 --- a/docs/ci-red-signatures.md +++ b/docs/ci-red-signatures.md @@ -79,11 +79,26 @@ Main-branch greens are **occurrence evidence** and accumulate toward a rate. They retire nothing by themselves. Retired rows stay in this file with their disposition, so a recurrence is recognisable. -**A red matching a RETIRED row is a recurrence, and it puts the -retirement in question — it is not a known flake.** The claim a -retirement makes is that the mechanism is gone; the same signature -afterwards falsifies that claim, which is a stronger finding than a live -row, not a weaker one. Reopen the row rather than rerunning. +**A red matching a RETIRED row AND POSTDATING ITS RETIREMENT is a +recurrence, and it puts the retirement in question — it is not a known +flake.** The claim a retirement makes is that the mechanism is gone +*from the retirement forward*; the same signature afterwards falsifies +that claim, which is a stronger finding than a live row, not a weaker +one. Reopen the row rather than rerunning. + +**A matching red that PREDATES the retirement corroborates the row +instead.** It is an additional occurrence of the mechanism the fix +removed, so it strengthens the evidence and challenges nothing. Add it +to the row's evidence; do not reopen. This is not a technicality — an +occurrence scan reaches backwards by construction, so most matches it +finds will be of this kind, and treating them as recurrences would +reopen every retired row the first time anyone looked. + +**Both halves need the date, which means a row is unmatchable without +one.** R2's second occurrence (`main` run 30710662474, 2026-08-01, four +days before its 2026-08-05 retirement) is the worked example, and it +also shows the flavor field is not part of matching: R2's first +evidence is macOS / lua54 and that one is macOS / luajit. --- @@ -153,14 +168,6 @@ diagnosis by the process-signal / reap-ledger lanes. --- -## Retired rows - -**These stay here on purpose.** A retirement is a claim that a mechanism -is gone; keeping the signature is what makes a recurrence recognisable -as a falsification of that claim rather than as a fresh mystery. Both -were retired **causally** — the mechanism removed, plus a discriminating -witness that fails without the fix — never by a count of green runs. - ### R5 — async pump deadline exceeded in the supersede close path | field | value | @@ -219,6 +226,14 @@ readiness helpers exist, whether they can be one, and what each promises. Patching this call site alone would leave the same question open under a fourth selector. +## Retired rows + +**These stay here on purpose.** A retirement is a claim that a mechanism +is gone; keeping the signature is what makes a recurrence recognisable +as a falsification of that claim rather than as a fresh mystery. Both +were retired **causally** — the mechanism removed, plus a discriminating +witness that fails without the fix — never by a count of green runs. + ### R2 — USR1 delivered before the trap is installed — RETIRED 2026-08-05 | field | value |