docs(backlog): reconcile the published ledger with the code it describes - #41
Merged
Conversation
…scribed merged code as unbuilt The published docs/BACKLOG.md is a 2026-07-12 snapshot; the code on origin/main is current through 2026-07-28. Eight banners here contradicted the code, and a stale banner is the mechanism by which merged work gets rebuilt. Every citation below was resolved against this worktree before the banner was written -- none was copied from another ledger. - #213 accepts= seam: ~1,500 merged lines were described as an unstarted big bet. Highest double-build risk in the set. - #97 / #117: merged in PR #1220 (2026-07-24), not stranded on lane dg-s5. ADR 0124 is on main, and the #117 x #82 interaction is a WiringError, not a doc. - #82: the banner asserted a "Confirmed gap" that verify_ack_control_id closed. Retracted explicitly rather than silently dropped. - #102 / #223: the DR seed gate has teeth on all three backends; #223's option (a) was declined by the owner, so neither carries a residual. - #142: the cross-backend dedup ledger the banner called missing exists. - #187: ADR 0079 is Accepted with mechanism 2 built; the Kerberos residual is closed. The ad_session_recheck_seconds default flip is flagged as a separate lane, since this one is docs-only by design.
…er the snapshot Same reconcile as the previous commit, on the alerting and IDE surfaces. Each banner cites paths resolved in this worktree. Two of these banners did not merely lag the code, they asserted the opposite of it, so the retraction is explicit rather than a silent rewrite: - #144 read "notify-only"; a validated control-action vocabulary dispatches restart_inbound/restart_outbound before the transport-suppression return. - #145 read "only log at INFO"; leadership and DR transitions are first-class alert events, with the lost/released edges wired as auto-resolving inverses. The rest were simply built: #118 (POST /alerts/test-email), #143 (windowed notification-only suspend, durable on all three backends), #48 (36 snippets + quick-pick), #221 (ADR 0100 native surface), #222 (all three lens phases). #48 keeps its non-status 🔶 note; the ✅ banner leads and marks it historical.
#216 is the sharpest case: its banner said "no existing harness covers it" while harness/load/estate/ (1,342 lines across four modules), harness/config/estate/ and `python -m harness --estate` were all on main. That premise is retracted. Two things are deliberately NOT presented as closed work: - #216's simple_fraction=0.72 and hub_fanout=3 are recorded as still needing OWNER SIGN-OFF, together with the shape discrepancy against the item's own "17% hub, H=20, N=4" text. The instrument is built; the shape is the owner's call. - #209's H=20 rig run is named as bench time against capacity the project does not own, so it cannot reopen the item. #207 closes on ADR 0141, which names it. Recorded honestly: txn/msg is measured, but bytes/msg STAYS REFUSED with copies-per-message shipping as the sizing proxy — an ADR decision, not an unbuilt residual. #220 ships the piecewise same-PID-set CPU sum the item specified.
…e owner ratified These five are measurement/decision items, not builds. Each was already answered; leaving them open invites re-running published experiments, and #215 alone is five 900-second AWS soaks. Required framings, recorded deliberately: - #212 — DECIDED: ships OFF. settings.py:295 already carries default=1, so no code change closes it. Priced at ~+4.7% against the +8% PROCEED bar (ADR 0107). Revisit only on a latency or store-load rationale, never a throughput one. - #211 — characterization-only. Explicitly NOT a licence to flip the claim_mode default (the 1,500-lane claim storm is why the default stands) and NOT a rig ask. - #208 — the residual is OFF-REPO; no in-repo change can close it. Published with no sizing figure at all, since a prior sizing claim was refuted. - #215 — Phase 5 closed, R in [2,3); the m7i.8xlarge upsize is retired at :1719. - #218 — answered DECLINING (1.36x for 4x shards), soft-magnitude caveat carried. #218's C1 json artifacts are not on origin/main, so the banner cites the status document lines and says plainly that the artifacts are held off-repo, rather than printing a path that resolves to nothing.
Each was already ruled on; the published file still showed them open, which is how a declined design gets rebuilt by a session that only reads this file. #231 was the live trap: it still read "🔢 Filed" although it was declined 2026-07-20 against the #26 guardrail. Its "Open question" is now answered in the banner rather than left inviting work. Two declines carry an explicit anti-deletion clause, because reading ⛔ as "remove the code" would destroy shipped work: - #157 — do NOT delete messagefoundry/transports/direct.py; the outbound S/MIME half ships and stays. Only the inbound/HISP/XDR remainder is declined. - #210 — ADR 0114 deliberately PRESERVES the four tempdb table variables in sqlserver.py:702-717; they are load-bearing for per-lane FIFO. Removing them is a rejected design, not an unfinished one. #217 is dead by measurement three times (ADR 0069 -> 0099 -> 0107, which also stamps ADR 0057 DO NOT PROMOTE). #91 is declined with its re-open trigger stated in ADR 0053's own terms rather than left as a standing invitation. #87 is owner- closed recon that ships nothing.
…ledger misprices #185 — closed as SUPERSEDED by the ADR 0115 re-partition into #242-#246. It is an index-only umbrella owning no findings and shipping nothing runnable, so an index whose contents moved has nothing left to index. The banner states explicitly that this is NOT a claim that ASVS is done: the programme continued past this baseline (which ends at #231) and docs/security/ is gitignored post-cutover, so the ASVS state cannot be read off this item in either direction. Four amendments — re-priced, deliberately NOT closed, each with the reason it still cannot be scheduled: - #214 -> stays 🚧. Mechanism merged and tested; exposing transform_concurrency is DECLINED (unmeasured, and inert unless per_lane AND fifo_claim_batch>1 AND not the SQL Server fused path — all three gated at wiring_runner.py:4819). - #105 -> the synthetic-schema blocker is discharged by ADR 0086 §2(a'), but the real gate is #313, which is invisible from this baseline. Not a green light. - #94 -> difficulty 8 -> 5-6, because ADR 0105/#149 shipped the substrate and reserved the deref seam. Still ADR-first, still demand-gated. - #99 -> not a 6/6 build. (g) shipped via #274/ADR 0142; only (e) remains and it is provisioning (a real DC + AD CS + gMSA), gated behind #275. #99 also flags that its own OFF-LOOPBACK-DEPLOYMENT.md links no longer resolve from the public repo, so a reader does not mistake a publishing boundary for rot.
Final commit of the reconcile, deliberately last: rows in both tables sit inside git's 3-line merge context (#169/#179, #96/#141/#180, #208/#211), so touching them earlier would have made every prior commit conflict-prone. This lane is the only writer of docs/BACKLOG.md, so one late pass is safe. merge=union is NOT set — it would duplicate banners and break the one-status rule. 33 rows: 17 in the main table, 16 in the post-re-score addendum. Tier cells now carry the real state (✅ SHIPPED / ✅ CLOSED / ⛔ DECLINED / 🚧 PARTIAL) and each Why cell carries the evidence, so the tables can no longer contradict the banners below them. Four Why cells retract a specific false claim rather than quietly replacing it — #82 ("_check_ack matches MSA-1/MSA-3 only"), #144 ("notify-only"), #145 ("only log at INFO") and #216 ("no existing harness covers it") — because those sentences are what would send a session off to rebuild merged work. Rows for #169, #179, #180, #141 and #96 are untouched: demand-gated, triggers not fired. #94's difficulty moves 8 -> 5-6 but the row stays in place, and the cell says so, rather than silently re-sorting a dated snapshot table. The Distribution/Tiers paragraph above the table is left alone: it is an explicit 2026-07-10 re-score snapshot, and prior shipped items did not recompute it either.
#117 was the one closed item whose leading blockquote still opened with the 2026-07-09 "Decline overturned ... this is an unfired demand-gate" note, with the ✅ underneath. A reader scanning leading banners — which is exactly how the double-build failure mode starts — would have hit "unfired demand-gate" first on an item that shipped in PR #1220. The 🛠 note is retained (it is not a status glyph and the rules allow it to stay), moved below the ✅ and marked historical, with its build-constraints list labelled as met. No wording in either block is otherwise changed. Matches how #48 already reads.
A 13-agent adversarial pass over this reconcile confirmed 24 findings. Every one below was re-verified by hand against the code before editing. Two were the same failure mode this reconcile exists to stop, pointed the other way — a banner stating something false. Materially wrong, now fixed: - #214 said "the residual is one settings field". It is not. The ~40x headline comes from commit-collapse, which is UNBUILT: Store.transform_handoff is strictly single-row (store/base.py:331-334) and the in-repo plan sizes the remainder as a batched multi-row handoff across all 3 backends, XL, new ADR required (BACKLOG-EXECUTION-PLAN-2026-07-24.md:129). The banner now leads with that residual instead of hiding it behind the declined knob. - #91 called the wall "transaction-shaped" citing ADR 0098 and ADR 0107. Both say the opposite: 0098 withdrew that exact phrasing from its own title as WRONG (:3-11) and 0107 measured transaction-reduction elasticity at -0.115 (:57-59). The decline stands on the CPU argument; the false support is gone. - #223 asserted the owner DECLINED option (a) on 2026-07-20. ADR 0102 records it as DEFERRED (:67, :128) and no in-repo record of a decline exists. Now states both, and says not to restate the decline as in-repo fact until an ADR records it. - #231 implied #26 had already declined Block. ADR 0106 (Accepted, :20/:64/:146) DEFERRED it here. The decline is the later owner ruling superseding that. - #82 claimed it "retracted" a false gap while the same claim still stands in the item body, which rule 1 barred me from editing. Now says so explicitly. Citation precision: #142 (honoured at :762-765, not :355), #145 (DrCoordinator fire sites dr.py:281/:341, not the AlertSink Protocol stubs), #217 (ADR 0099 withdrew group-commit superseding ADR 0055 and gated inline fusion), #221 (MEFOR Live lives in liveDebug.ts), #48 (36 total = 32 idioms + 4 scaffolds). Disclosed residuals that were missing: #207 committed_txns is hardcoded 0 on PostgreSQL (postgres.py:793), so both figures degrade there; #144 auto-STOP is declined by design, not pending (ADR 0128:31-32). Table hygiene: #219 row carried P2 over a ✅ BUILT banner; the frozen Distribution/Tiers snapshot now says it is frozen and not a current census.
…erged The first pass closed the 31 items it was handed. A review then found #109, #147 and #177 by accident — which meant the sweep had been incomplete, not that three items were missed. So this swept ALL 78 remaining open items against the code. Method: one pass per item to find merged code, then TWO independent adversarial lenses per candidate — one hunting a missing half, one hunting wrong-thing evidence (stubs, dead code, docstrings, declines misread as ships). Only candidates BOTH lenses failed to refute are closed here. 23 of 31 candidates survived; 8 were refuted and are deliberately left open. That bar earned its keep: #177 was refuted by both lenses. Its API half is merged, but the Scope asks for an endpoint PLUS a console view and no such view exists — I had been about to close it. It stays open, as do #81 #95 #114 #124 #125 #172 #228, each with a real remainder. Every banner discloses what the close does NOT cover, because a close that overstates is the same defect as a banner that understates. Notable: - #67 carries a REAL DEFECT into its close: the `{ ? = CALL proc(:x) }` shape is the canonical example in the docstring, the gate error and the test fixture, but _parse_named_params substitutes only `:name`, so the return-value `?` is never bound. Warrants a new item. - #121 ships the mechanism but defaults to OFF, not the "four hours" the item asked for (ADR 0137:79-83 chose the [retention] keep/off convention). - #147 has a live gap: _start_schedulers runs only from start(), never from config reload, so an edited schedule needs a restart. - #227's secondary ask is off-repo and cannot be produced from this repository. - #168 adds a NEW PHI-at-rest surface (plaintext VS Code workspace storage). - #230 leaves two "optional fast-follow" items unbuilt; they need re-filing. Seven ADR links I first wrote were wrong filenames — the citation audit caught every one before commit. All 121 cited paths and 196 line refs now resolve.
These eight survived the sweep as OPEN — two adversarial lenses each found a real remainder, so none is closed. But every one has a substantial merged half, and an item that reads wholly unbuilt invites rebuilding it. Each banner now names what exists, what is genuinely missing, and where the missing part starts. #177 is the cautionary one. I had been ready to close it on a merged endpoint; both lenses refuted that, and they were right — the Scope says endpoint PLUS console view, and no console route, page card or apiclient wrapper exists. The amendment says so, and says the endpoint must not be rebuilt. Three remainders are worse than "not built yet" and are called out as such: - #124's console half is DEAD CODE — the JS binds [data-mf-msg-export], which no page emits, and fetches /ui/messages/export, which has no route. - #114 silently accepts File(validate_directory=True) on an outbound and ignores it, with no WiringError — an operator gets no fail-fast and no error either. - #95 accepts a `provider` it never reads and always sends the Anthropic wire body, so every other backend fails as an opaque 502 rather than a config error. #125 also records that "save" appears nowhere in ADR 0134, not even its out-of-scope list, so it needs an explicit build-or-decline rather than drift. Two citation errors of mine were caught by the audit before commit: a wrong ADR 0135 filename, and alert_sinks.py:2366-2367, which was really api/app.py.
…177 18 rows flip to a closed tier for the items the sweep closed, and 6 rows gain a PARTIAL note naming the built half so the tables stop reading as fully-unbuilt work. Kept last again, since these rows sit inside git's 3-line merge context. #177's row is a correction, not a re-sync: it advertised SHIPPED over an item the sweep proved is PARTIAL (the endpoint exists; the console view the Scope requires does not). The row now says so and flags that it previously read SHIPPED, because a table that overstates is the same defect as a banner that understates — it just fails in the other direction. Caught in verification: a `cert import|inventory` cell contained a literal pipe and split a markdown row into 9 cells. All main-table and addendum rows re-checked for column count.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The published
docs/BACKLOG.mdwas the one-commit cutover snapshot (9e4e614e, PR #6), frozen at 2026-07-12 while the code moved on. Thirty items carried a banner the code contradicts — and a stale banner is the mechanism by which merged work gets rebuilt. #213'saccepts=seam alone is ~1,500 already-merged lines that sat behind an open 🔢.This is the paperwork lane of docs/releases/BACKLOG-MULTISESSION-PLAN.md. One file, 247 insertions / 195 deletions.
What changed
Verification
scripts/docs/backlog_status_check.py: OK — 229 backlog items, each declaring exactly one status.scripts/security/scan_forbidden.py: exit 0, detectors live (names=7, estate=13, site_prefixes=1) — a real scan, not an empty one. This mattered: the owner's vault ledger fails that gate with 102 hits, so every banner here was written fresh from verified code rather than pasted from vault prose.Note on the diff
git diff origin/main..HEADlists ~100 files. That is an artifact of the branch being 10 commits behind — the three-dot diff (origin/main...HEAD) is one file.