diff --git a/docs/branch-review-ledger.md b/docs/branch-review-ledger.md index 048ef3faec..68ebb231b8 100644 --- a/docs/branch-review-ledger.md +++ b/docs/branch-review-ledger.md @@ -322,3 +322,7 @@ Records before 2026-07-28 were written by hand and had drifted: 146 lines carrie | 2026-07-30 | claude/capture-session-followups | 6bd0c3f85743c5406d49474bb7a92956fa44c0d2 | PR #1490 merge conflict | merged origin/main; resolved outstanding-issues against #1508 IDs; kept pre-snapshot wording | check:outstanding-issues,docs:check-links | | 2026-07-30 | claude/capture-session-followups | bdd27597e9b9d72d56940cd9a55c8000f9bbe1fc | PR #1490 merge conflict | merged origin/main; resolved outstanding-issues against #1508 IDs; kept pre-snapshot wording | check:outstanding-issues,docs:check-links | | 2026-07-30 | claude/capture-session-followups | e47c9d410a2eaaffd73af9e41dc57113f8cc9ef1 | PR #1490 merge conflict | merged origin/main; resolved outstanding-issues against #1508 IDs; kept pre-snapshot wording | check:outstanding-issues,docs:check-links | +| 2026-07-30 | codex/computed-style-assertions | 229b0d396decd0ad7f7779b57631ae1f137752d7 | archive completed rendered-style contract task #094 | APPROVED — no findings; docs-only archive move matches landed computed-style, forced-colors, tap-size, and unlayered-class registry evidence. | check:outstanding-issues PASS (148 rows; 42 open, 106 archived); git diff --check PASS; implementation commits verified ancestral to origin/main | +| 2026-07-30 | codex/computed-style-assertions | 1f431caa8d80660b8f6d90f557e4b8ea5d82560c | post-sync archive completed rendered-style contract task #094 | APPROVED — no findings after exact current-main sync; archive move and prior review record only. | check:outstanding-issues PASS (151 rows; 44 open, 107 archived); branch-review-ledger PASS (254 live, 1206 archived); git diff --check PASS; merge-tree 9ab802e9ec73132e4a7231b9060bf95be090b9d2 | +| 2026-07-30 | codex/computed-style-assertions | a8ee3315f2c9959025b7d652c0b7ea45432ca6be | post-#121 sync archive rendered-style task #094 | APPROVED — no findings; #121 main merge preserved and #094 remains the only issue-state change. | outstanding-issues PASS (151 rows; 43 open, 108 archived); branch-review-ledger PASS (261 live, 1206 archived); diff check PASS; merge-tree 2c567bcbb60f5d3f36eb18b6f7d7f6ee2a7a788b | +| 2026-07-30 | codex/computed-style-assertions | a18085a15339f280fff76cad15fafcf1a80084fe | post-#1490 sync archive rendered-style task #094 | APPROVED — no findings; current-main issue additions are preserved and #094 is the sole state change. | outstanding-issues PASS (151 rows; 43 open, 108 archived); branch-review-ledger PASS (271 live, 1206 archived); diff check PASS; merge-tree ab18c4319fcca6c915d340bdea286481caa8ea43 | diff --git a/docs/outstanding-issues.md b/docs/outstanding-issues.md index bda933edd6..6d02fa4ca2 100644 --- a/docs/outstanding-issues.md +++ b/docs/outstanding-issues.md @@ -126,7 +126,6 @@ removed after current-main verification; it is not missing recommended work. | #086 | P3 | task | Repository maturity backlog — remaining structural work | **Outcome:** the deferred repository-maturity backlog ships as verified draft PRs, one per structural change. **Canonical runbook:** [`docs/maturity-backlog-workorders.md`](maturity-backlog-workorders.md). **Remaining:** X3 `rag.ts` decomposition (in progress); X7 finish the `src/lib` domain reorg; X6 clinical/retrieval/answer coverage floors; X5 ACL-migration consolidation (provider-gated); L1 archive the retired `backfill:*` one-shots + the dead `ci-change-scope` token; M1 repo-host hardening (maintainer, audit §8). **Shipped:** L4 ledger rotation (#1418 — `ledger:rotate`, live/archive corpus, `merge=ledger`). **X3 progress:** the evidence coverage gate shipped as `src/lib/rag/rag-coverage-gate.ts` (PR #1454, squashed `102bb1f`) — `evaluateEvidenceCoverageGate` + `applyCoverageGateTelemetry` moved byte-identically, `rag.ts` 5,030 → 4,780, budget ratcheted to 4,780, no back-edge, `evaluateEvidenceCoverageGate` still re-exported from `@/lib/rag/rag`. **Hydration unit SHIPPED (X3 hydration; PR #1463, squashed as `dba7356f`):** `src/lib/rag/rag-hydration.ts` now owns the hydration cluster is `createDocumentRankingMetadataCache` / `attachDocumentRankingMetadata` / `withCachedIndexQuality` / `attachIndexQualityMetadata` / `attachPageVisualEvidence` plus the `DocumentRankingMetadataCache` type (byte-identical move; `rag.ts` 4,780 → 4,543, budget ratcheted to 4,543). **It did NOT on its own unblock `prepareCoverageGateResults`**, exactly as the 2026-07-30 Codex finding on PR #1461 predicted (the original claim that it re-homed all five dependencies was wrong, and shipping it confirmed that). That function needs five `rag.ts`-only runtime symbols, and hydration accounts for only two of them (`attachDocumentRankingMetadata`, `attachPageVisualEvidence`). The other three sit outside the cluster and are a separate seam: `selectRankedRetrievalResults` (`rag.ts:1825`, retrieval selection), `applySecondStageRerankIfNeeded` (`rag.ts:679`, second-stage ranking), and `measureSearchPhase` (`rag.ts:1975`, the shared pipeline timing wrapper — 21 references across the file, of which only `metadata_hydration` and `visual_hydration` are hydration phases, so it belongs with the search orchestrator/telemetry, not with hydration). So `prepareCoverageGateResults` can only move after BOTH hydration and that ranking/timing seam are re-homed; it stayed in `rag.ts` for #086 because a back-edge and a signature change were both refused. Verify with a symbol-location plus call-site search before planning the boundary — do not treat hydration alone as sufficient. **Next:** remaining X3 units on user go-ahead. **Stop:** RAG/retrieval items need the flag + go-ahead; X5 is live-DB provider-gated. | `docs/maturity-backlog-workorders.md`; audit §8/§10; session 2026-07-28 | 2026-07-28 | | #090 | P2 | task | Upgrade the eslint ecosystem to clear remaining dev-scoped high advisories | **Outcome:** full `npm audit` reports zero high advisories from the eslint toolchain. **Blocked 2026-07-30:** the stable ecosystem still has no compatible ESLint 10 set. `eslint-config-next@16.2.12` permits ESLint 10 but bundles `eslint-plugin-react@7.37.5`, `eslint-plugin-import@2.32.0`, and `eslint-plugin-jsx-a11y@6.10.2`; each plugin's published peer range still ends at ESLint 9, and the React plugin retains the previously reproduced removed-context-API crash. Keep the Dependabot major hold and ESLint `9.39.5`; do not force an invalid peer graph merely to make the audit report green. **Next:** recheck after those three plugins publish stable ESLint 10 support, then upgrade eslint and the complete plugin/config set together. Residual highs (`@eslint/config-array`, `@eslint/eslintrc`, `eslint`, `eslint-config-next`, `eslint-plugin-import`, `eslint-plugin-jsx-a11y`, plus the advisory's numeric `<=5.0.7` hit on the unused `brace-expansion@1.1.16` / `2.1.2` maintenance lines that still ship an unpatched `main`) cascade from this dev-only toolchain. **Success:** peer-valid install, `npm run lint` clean, `verify:cheap` green, full-audit highs cleared, no rule-config regressions. **Stop:** do not use `npm audit fix --force` or override plugin peer ranges. Production `npm audit --omit=dev` is already clean after the exceljs `archiver@8` / `unzipper@0.12.5` overrides on PR #1314. | stable npm metadata recheck 2026-07-30; session 2026-07-28 brace-expansion triage (PR #1314) | 2026-07-30 | | #093 | P2 | issue | Next streaming `S:` clone causes Playwright strict-mode violations under CI load | **Outcome:** duplicate-element strict-mode failures stop appearing on loaded CI runs. **Detail:** under full-suite CI load Next.js leaves a hidden duplicate page root in the stream, so a `getByTestId` that is unique locally resolves to 2 elements in CI (seen as `differentials-search-results` on PR #1316, and previously noted on PR #1294 against main). It does not reproduce in isolation, on a single spec, or locally. The documented workaround is to scope the locator to the visible root. **Reproduced locally 2026-07-28** (isolated _production_ build via `run-playwright.mjs`, full `verify:ui`): `ui-tools.spec.ts:563` duplicated `forms-home` and `ui-smoke.spec.ts:3001` duplicated `favourite-row-lithium-monitoring-guideline`; in both, copy 1 is nested under `mobile-composer-reserve-pad`. Both pass when run alone, so it is load/order-dependent, not build-mode dependent — this also corrects an earlier note that CI uses `next dev`; it does not. **Strongest evidence (CI run `30345484316`, 2026-07-28): `ui-overlap.spec.ts:199` on `/` asserted `toHaveCount(1)` successfully and then the same `header#search` locator resolved to 2 a statement later, one of them hidden.** A duplicate that appears _after_ a passing count assertion is a stream/hydration artifact by construction, not a static double mount and not something a CSS or component change can cause. That makes four distinct testids across four specs with the identical shape. **Mitigated, not fixed, on `main` (2026-07-28):** `3a8edb93` rewrapped `gotoHome` in `tests/ui-overlap.spec.ts` to retry count-and-visibility together via `toPass`, so a transient second header no longer trips strict mode there — its own note says "checking count then immediately calling waitFor races that flicker into a strict-mode violation". That hardens one helper; the duplicate root itself is unchanged and other specs remain exposed. **Confirmed pre-existing:** at `631d90d2`, the commit before PR #1316's first commit, that spec already documented "two `header#search` nodes" and "a second transient `header#search` can exist briefly" — so this predates that branch. **Next:** with a full-suite repro now available, bisect the preceding specs to find the state that triggers the second mount, then either scope the shared helpers to the visible root once or fix the mount. **Stop:** do not paper over new occurrences with `.first()` before the duplicate itself is explained. | PR #1316 CI runs; PR #1294 note on main; session 2026-07-28 | 2026-07-28 | -| #094 | P2 | rec | Design-system gates assert structure, not rendered effect | **Outcome:** a style contract cannot pass while the style is inert. **Detail:** PR #1316's accent rail shipped inert because `.search-band` sat in `@layer components`, which loses to Tailwind's utilities layer regardless of specificity — and the test asserted `toHaveClass("search-band")`, i.e. class presence, not effect. Computed style showed `1px rgb(229,231,235)` where `2px rgb(11,111,134)` was intended. The same shape of gap let a rail-colour assertion compare a colour against a width and pass unconditionally. **Next:** for contracts where the visual IS the requirement (rails, forced-colors thickness, tap targets), assert `getComputedStyle` in a Playwright case rather than class names in a DOM test, and add the unlayered-component convention to the design-system contract check. **Stop:** do not convert existing passing DOM tests wholesale; add computed-style proof only where the effect carries the meaning. | PR #1316 Codex P2 finding; session 2026-07-28 | 2026-07-28 | | #098 | P2 | task | Offline round-trip budget harness for the hot routes | **Outcome:** per-scenario Supabase round-trip counts are pinned by a test, so an extra round trip on a hot path is a red gate rather than an inference. **Done 2026-07-29:** the measurement gap is closed — `Server-Timing` now covers `auth`/`ratelimit`/`scope` on `/api/answer`, `auth`/`ratelimit`/`search`/`total` on `/api/search`, and `auth`/`ratelimit` on `/api/answer/stream` (previously the route the UI actually calls emitted no header at all). Headers flush before the first SSE frame, so in-stream stages cannot reach a header and must NOT be routed through the governed `progress`/`final` contract. `tests/answer-route-preamble.test.ts` pins admission-before-scope (no scope call while the limiter is pending or after a deny) and the client-disconnect abort signal. **Done 2026-07-30 (PR #1450, `1bff4c78`):** the counting proxy exists and the answer path is budgeted. `tests/helpers/supabase-round-trip-counter.ts` counts on **execution, not construction** — a builder that is never awaited costs zero, one awaited twice costs two — which is the distinction that makes the count mean "requests issued". `tests/rag-round-trip-budget.test.ts` pins two offline answer-path scenarios (a single-source source-only answer, and that trips do not scale with the number of retrieved sources) plus three self-tests of the counter, and is registered in `scripts/fixtures/rag-offline-contract-tests.json` so it runs inside the offline contract rather than only on demand. Verified locally, provider-free: `Test Files 1 passed (1)`, `Tests 5 passed (5)`. Its documented blind spot is worth repeating before anyone cites a budget as total cost: it sees only traffic through the wrapped client, so a trip issued via another client instance, a direct `fetch`, or a provider SDK is invisible to it. **Done 2026-07-30 (PR #1450, `1bff4c78`):** the counting proxy exists and the answer path is budgeted. `tests/helpers/supabase-round-trip-counter.ts` counts on **execution, not construction** — a builder that is never awaited costs zero, one awaited twice costs two. `tests/rag-round-trip-budget.test.ts` pins two offline answer-path scenarios plus three self-tests of the counter, registered in `scripts/fixtures/rag-offline-contract-tests.json`. Its documented blind spot: it sees only traffic through the wrapped client, so a trip via another client instance, a direct `fetch`, or a provider SDK is invisible to it. **Done 2026-07-30 (search *retrieval core*, not the endpoint):** `tests/search-round-trip-budget.test.ts` pins `searchChunksWithTelemetry` — what `/api/search` calls to retrieve — registered in both the contract fixture and `scripts/rag-offline-contract.mjs`. **Corrected after Codex review on PR #1464:** an earlier version of this row and the test itself claimed to pin `/api/search`. They do not. The route's auth, rate limiting, scope resolution, related-document enrichment and telemetry write are all invisible to this suite, so a round trip added to any of them leaves it green — and the refusal budget below is about *retrieval*, not about an adversarial HTTP request, which still pays the route preamble. **The measured shape is itself the finding:** one search costs **11 round trips** — `rag_aliases` 1, `match_document_chunks_text_v2` **3**, `match_document_table_facts_text_v2` **3**, `get_related_document_metadata_v2` 1, `document_index_quality` 1, `document_images` 2 — so the two text RPCs are each issued three times per search. Pinned by total *and* breakdown, because a refactor swapping one probe for an unrelated query would keep the total at 11 while changing the traffic. Deterministic across three consecutive runs. The refusal budget asserts **zero** Supabase traffic, matching `rag.ts`'s claim that prompt-injection intent is refused before any query issues, and was proven against the broken shape: with a non-refused query it fails on the round-trip assertion (`expected 11 to be +0`), which is why that assertion is ordered ahead of the results assertion. **Next:** (a) add the route-level budget this suite does not provide — drive `POST` from `src/app/api/search/route.ts` with counted clients, following the `tests/answer-route-preamble.test.ts` pattern, so a round trip added to the route preamble or post-processing is a red gate; (b) decide whether `match_document_chunks_text_v2` ×3 and `match_document_table_facts_text_v2` ×3 per search are intended or a probe that should be collapsed — a latency question this budget surfaced but does not answer, and one that touches retrieval, so any change needs the usual RAG gate. (c) `scripts/eval-rag-offline.mjs` and `scripts/test-rag-offline.mjs` remain unwired; the offline contract runner is now the de-facto single home for budgets, so either adopt that explicitly here or wire them. | `docs/audit/latency-audit-2026-07-28.md` measurement plan; `src/lib/server-timing.ts`; `src/lib/answer-stream-contract.ts:18-21` | 2026-07-29 | | #099 | P2 | task | Remove the remaining fixed per-request round trips | **Outcome:** the answer path stops paying avoidable per-request Supabase round trips. **Done 2026-07-29:** shared-cache-hit promotion deferred off the response path with its mid-request staleness guard intact and documented (`rag.ts:3234`, `rag-cache.ts`); scope resolution overlapped with the rate-limit RPC, signal threaded so a client disconnect finally cancels its paginated queries (`answer/route.ts`). **REFUTED on PR #1377 review — do not retry:** the same pass also overlapped scope with the rate-limit RPC and aborted it on deny, claiming the limiter could "deny for free". It cannot. With caller-supplied `filters` or explicit ids, scope passes its zero-query early returns (`search-scope.ts:242,253`) into the paginated `documents` loop at `:269`, and an `AbortSignal` cancels the client request without un-executing a statement Postgres already began — so throttled traffic kept burning database capacity while collecting 429s, against `capacity-review.md:106-113`'s first-soft-failure warning. Scope is behind admission again, pinned by `tests/answer-route-preamble.test.ts`. Re-attempting the overlap requires a non-database admission gate ahead of the durable limiter first. **Remaining:** (a) the 8 `setCachedSearch` awaits — deferring changes `throwIfAborted` semantics and widens a real mutation window because the clone happens after an `await`, so each branch needs discharging individually; (b) batch the anonymous subject+global rate-limit pair, which needs a NEW atomic RPC modelled on `consume_summary_rate_limits_atomic` and cannot be called until the operator applies it — `Promise.all` is the WRONG fix because it consumes the global bucket even when the subject bucket already denied; (c) stop the proxy and route handler resolving identity twice per authenticated request — no in-process memo can do this (different `Request` objects), so the proxy must forward unspoofable verified claims via a header it controls. Cross-references #011: halving auth resolutions eases the ~10-connection Auth cap that `capacity-review.md:106-113` calls the first hard failure. | `docs/audit/latency-audit-2026-07-28.md` L1-1/L1-3/L1-4; `src/lib/api-rate-limit.ts:276-282`; `src/proxy.ts:125` | 2026-07-29 | | #100 | P2 | rec | Buffered answer generation has no incremental verified delivery | **Design complete; runtime work remains provider-gated.** [`verified-answer-incremental-delivery-design.md`](verified-answer-incremental-delivery-design.md) records the clinical-governance decision and staged contract: keep the `progress`/`final`/`error` allowlist; disclose bounded, owner-scoped evidence only after the canonical danger-level source-governance refusal permits it, then emit complete answer sections only after each reuses the full production verification boundary; reconcile every preview byte-for-byte with the authoritative `final`; discard all previews on error/cancel/retry; deploy behind separate parse/emission/render flags. Phase 0 contract proof and Phase 1 evidence preview can be developed offline, but visible rollout still needs clinical/browser proof. Phase 2 changes generation architecture and requires explicit approval for answer-quality evals plus a baseline/post live canary pair. **Naive token streaming remains REFUTED:** never re-land `token`, `revising`, provisional prose, or a weaker stream-only verifier. Cross-references #021. | `docs/verified-answer-incremental-delivery-design.md`; `docs/audit/latency-audit-2026-07-28.md` L0-1; `src/lib/answer-stream-contract.ts:18-21` | 2026-07-30 | @@ -166,6 +165,7 @@ Move resolved rows here with the resolution date and a one-line outcome. Keep th | #145 | issue | Branch syncs could repeatedly cancel healthy in-flight CI | Resolved 2026-07-30. The operator helper now queries Actions for the current head and skips `update-branch` when the required CI workflow is queued or in progress; focused tests cover queued, running, completed, and unrelated workflows. The open-PR sync, CI-speed, and canonical Run PR procedures all require one late sync after review/fix work is assembled. `cancel-in-progress` remains enabled. | 2026-07-30 | | #137 | rec | Advisory UI ran mockup tests for unrelated UI changes | Resolved 2026-07-30. `advisory_ui_changed` now runs the lane only for mockup-surface changes or when the flake ledger contains a quarantine. The scope self-test covers both directions, unreadable-ledger fail-open behavior, and parity for all five advisory specs; current-main `check:ci-scope` and `check:gate-manifest` pass. | 2026-07-30 | | #139 | rec | Change scope exposed dead outputs and appeared to over-trigger coverage | Resolved 2026-07-30. Unconsumed `source_changed`, `workflow_changed`, and `changed_files` job outputs were removed. The remaining coverage breadth is now an explicit fail-safe policy: every non-documentation change, including workflow-only edits, runs unit coverage because those files can alter test setup or the gate itself. Self-tests pin both cases; narrower signals still scope build, UI, database, and container work. | 2026-07-30 | +| #094 | rec | Design-system gates asserted structure, not rendered effect | Resolved 2026-07-30. The required Chromium style-contract lane now reads computed styles for the search-band accent rail, its forced-colors thickness, and rendered tap-size floors; moving the rail back into a cascade layer makes the proof fail. The accompanying registry inventories every unlayered visual class and requires either a rendered-effect contract or a reasoned exemption, so new unlayered component rules cannot enter unnoticed. Existing DOM tests remain narrow rather than being converted wholesale. Landed in `2b2102310`, hardened in `5e7efad1b`, and consolidated in `84c1f6d83`. | 2026-07-30 | | #129 | issue | GitHub update-branch ignored the custom ledger merge driver | Resolved 2026-07-30 by constraining the operation rather than trusting it as a conflict oracle. The branch-sync procedure requires `git merge-tree --write-tree` first, permits only a human-authenticated update, and directs clean custom-driver false conflicts to a local `git merge origin/main` plus ordinary push. | 2026-07-30 | | #132 | issue | Client-side push guards could be bypassed in agent environments | Resolved 2026-07-30 under the row's explicit-limitation outcome. AGENTS.md names the missing-hook and missing-`gh` fail-open paths as load-bearing operator rules; ordinary PR CI enforces formatting server-side, while the tested local sentinel remains an early auto-merge race guard where `gh` is available. No privileged `pull_request_target` execution of PR code was added. | 2026-07-30 | | #121 | issue | Container Playwright browser build lagged the pinned client | Resolved 2026-07-30 at the repository runner boundary. Managed Playwright browsers remain preferred; only the designated download-disabled `/opt/pw-browsers` image root can select the newest platform- and architecture-compatible preinstalled headless shell and pass that exact executable to the Playwright child. The fallback is unit-pinned and was launch-proven with a simulated older container revision; generic shared or stale developer caches still fail closed. | 2026-07-30 |