diff --git a/.cursorindexingignore b/.cursorindexingignore index 6ba7ac17bb..4f9071e867 100644 --- a/.cursorindexingignore +++ b/.cursorindexingignore @@ -45,7 +45,7 @@ src/components/*mockups.tsx src/components/clinical-dashboard/global-mockup-search-shell.tsx # One-off Codex review prompt dumps (not product code) -codex-cloud-review/ +docs/prompts/codex-cloud-review/ # Generated schema-drift inventory (large JSON) supabase/drift-manifest.json diff --git a/.prettierignore b/.prettierignore index d897f291c5..954ee472d6 100644 --- a/.prettierignore +++ b/.prettierignore @@ -22,4 +22,4 @@ supabase/drift-manifest.json public/therapy-compass-data/ docs/branch-review-ledger.md # Verbatim user-provided prompt inputs retained for cloud review. -codex-cloud-review/ +docs/prompts/codex-cloud-review/ diff --git a/CLAUDE.md b/CLAUDE.md index 75a10d88a4..498b51f8f9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -87,14 +87,18 @@ src/components/ UI; clinical-dashboard/ is the shell, *-mockups.tsx are design src/lib/ ~200 modules — rag/, supabase/, validation/, observability/, extractors/, webhooks/ are the extracted subdirectories src/data/ Static clinical content (DSM, formulation, therapies indexes) +data/ Generated clinical snapshot exports loaded at runtime — regenerate, never hand-edit supabase/ migrations/ (source of truth), schema.sql (mirror), functions/ worker/ Ingestion worker; worker/python/ is the OCR stack scripts/ ~160 files backing 194 npm scripts: gates, eval, reindex, governance, dev tests/ Vitest unit + Playwright E2E, side by side docs/ Runbooks, governance, plans; docs/README.md categorises them eslint-rules/ Repo-specific lint rules (see Conventions below) +mockups/ Notes for the design-scratch routes under src/app/mockups/ +plugins/ plugins/clinical-kb/ Codex plugin manifest and workflow skill .claude/ Claude Code agents, skills, hooks, settings .agents/ Single-word skill catalogue (`npm run skills`) +.githooks/ Installed by `npm install`; pre-push runs scripts/guard-push.mjs ``` Never commit: `.next/`, `node_modules/`, `coverage/`, `.env*`, `sample-documents/`, logs. diff --git a/docs/README.md b/docs/README.md index 4aa11151bd..3aa536f580 100644 --- a/docs/README.md +++ b/docs/README.md @@ -24,6 +24,7 @@ npm run docs:check-links - [frontend-architecture.md](frontend-architecture.md) — shell, routing, dashboard module structure - [wiring-conventions.md](wiring-conventions.md) — page/button wiring conventions and the dead-button / orphan-route gates +- [search-chrome-behaviour.md](search-chrome-behaviour.md) — shared search-chrome contract: composer ownership, phone edge-to-edge dock, hide/reveal reserves - [deployment-architecture.md](deployment-architecture.md) — app/worker/Supabase deployment topology - [ingestion-state-machine.md](ingestion-state-machine.md) — ingestion job lifecycle and states - [design-system.md](design-system.md) — tokens, primitives, styling conventions @@ -31,6 +32,8 @@ npm run docs:check-links - [clinical-badge-system-guide.md](clinical-badge-system-guide.md) — clinical badge semantics - [multi-user-auth-setup.md](multi-user-auth-setup.md) — auth, sessions, owner scoping - [pwa.md](pwa.md) — PWA install assets, privacy-first service worker, offline shell +- [webhooks.md](webhooks.md) — the two inbound webhook receivers and the outbound Actions notifier +- [api-jobs-ops-surface.md](api-jobs-ops-surface.md) — standing decision to keep `GET /api/jobs` as an ops/admin surface ## Operations runbooks @@ -43,11 +46,15 @@ npm run docs:check-links - [staging-setup.md](staging-setup.md) — staging environment bootstrap - [database-drift-detection.md](database-drift-detection.md) — schema drift detection (`npm run check:drift`) - [supabase-migration-reconciliation.md](supabase-migration-reconciliation.md) — migration drift and repair policy +- [db-maintenance.md](db-maintenance.md) — Supabase advisor snapshots and the standing disposition per finding class - [observability-slos.md](observability-slos.md) — health probes, SLO counters, degraded modes - [openai-rag-operations.md](openai-rag-operations.md) — OpenAI/RAG provider operations and modes - [outstanding-issues.md](outstanding-issues.md) — single universal task ledger and repository memory - [operator-backlog.md](operator-backlog.md) — provider/operator runbook detail (status is canonical in the universal ledger) - [deploy-corrector-public-titles.md](deploy-corrector-public-titles.md) — public-title corrector deploy notes +- [operator-apply-performance-latency-remediation.md](operator-apply-performance-latency-remediation.md) — operator apply steps for the performance/latency migration batch +- [reconciliation-playbook.md](reconciliation-playbook.md) — broad chat/worktree reconciliation and archive-safe cleanup (not for ordinary feature work) +- [staging-tenancy-release-evidence.md](staging-tenancy-release-evidence.md) — cross-tenant staging harness as executable owner-boundary proof ## Governance, safety, privacy @@ -83,6 +90,19 @@ npm run docs:check-links - [redesign/](redesign/) — premium redesign plans, decision log, token adoption - [superpowers/](superpowers/) — agent-authored plans and specs +## Subdirectory map + +| Directory | What lives there | +| -------------------------------- | --------------------------------------------------------------------------------------------------------------------- | +| [rag-behaviour/](rag-behaviour/) | Protected retrieval/ranking surface: behaviour map, refuted approaches, safeguards. **Read before touching ranking.** | +| [prompts/](prompts/) | Copy/paste review prompts, including the verbatim `codex-cloud-review/` inputs | +| [codex/](codex/) | Per-lens Codex ultra-review output folders, one per review dimension | +| [evidence/](evidence/) | Captured evidence artifacts backing ledger items (reliability reports, review manifests) | +| [audit/](audit/) | Dated repo, design, accessibility, and latency audits (point-in-time) | +| [redesign/](redesign/) | Premium redesign plans, decision log, token adoption | +| [superpowers/](superpowers/) | Agent-authored plans and specs | +| [archive/](archive/) | Completed phase plans, superseded designs, old progress logs — never current guidance | + ## Point-in-time records (historical — do not update) Dated status reports, reviews, and operator decisions. They describe the repo @@ -91,6 +111,13 @@ as it was on that date; supersede with a new dated document rather than editing. - [audit/](audit/) — repo and UX/accessibility audits - [audit/2026-07-20-repository-maturity.md](audit/2026-07-20-repository-maturity.md) — full repository maturity, mapping, and organisation audit - [audit/latency-audit-2026-07-28.md](audit/latency-audit-2026-07-28.md) — latency audit: server, client, and database findings by tier, with the already-cleared list +- [audit/audit-handover-2026-07-14.md](audit/audit-handover-2026-07-14.md) — multi-skill repository audit findings inventory +- [audit/audit-remediation-plan-2026-07-14.md](audit/audit-remediation-plan-2026-07-14.md) — sequenced remediation plan for the 2026-07-14 audit, with the 2026-07-17 reconciliation +- [audit/design-audit-2026-07-17.md](audit/design-audit-2026-07-17.md) — repository-wide design, accessibility, and interaction audit +- [current-clinical-work-brief.md](current-clinical-work-brief.md) — ledger #063 product/privacy/persistence brief (decision only, no implementation) +- [factsheets-reading-model-brief.md](factsheets-reading-model-brief.md) — ledger #041 reading-model decision (no second Factsheets mode) +- [source-governance-refresh-worklist-2026-07-22.md](source-governance-refresh-worklist-2026-07-22.md) — ledger #022 worklist and BMJ attestation policy status +- `release-source-metadata-debt-2026-06-30.json` — captured source-metadata debt policy, consumed by `npm run audit:source-governance:release` and `npm run eval:quality:release` - [forward-codify-retrieval-rpcs-workorder.md](forward-codify-retrieval-rpcs-workorder.md) — completed retrieval RPC codification workorder - [project-alignment-cleanup.md](archive/project-alignment-cleanup.md) — completed June 2026 repo-alignment record - [capacity-review.md](capacity-review.md), [scale-readiness-review.md](scale-readiness-review.md), [tenancy-defense-in-depth-review.md](tenancy-defense-in-depth-review.md) diff --git a/docs/archive/design-qa-2026-07-15.md b/docs/archive/design-qa-2026-07-15.md index 92684d102e..52197cb031 100644 --- a/docs/archive/design-qa-2026-07-15.md +++ b/docs/archive/design-qa-2026-07-15.md @@ -64,4 +64,4 @@ Blocker: an independent source visual target is required to certify concept fide ## Follow-up audit — 2026-07-17 -The exhaustive line-level design, accessibility, UX, interaction, and route-coverage follow-up is documented in [`docs/design-audit-2026-07-17.md`](../design-audit-2026-07-17.md). It preserves the fixes above, avoids duplicating this pass, and records the new P1/P2/P3 fixes plus the exact local verification limitations. +The exhaustive line-level design, accessibility, UX, interaction, and route-coverage follow-up is documented in [`docs/audit/design-audit-2026-07-17.md`](../audit/design-audit-2026-07-17.md). It preserves the fixes above, avoids duplicating this pass, and records the new P1/P2/P3 fixes plus the exact local verification limitations. diff --git a/docs/rag-scalability-wip-remediation-2026-07-17.md b/docs/archive/rag-scalability-wip-remediation-2026-07-17.md similarity index 98% rename from docs/rag-scalability-wip-remediation-2026-07-17.md rename to docs/archive/rag-scalability-wip-remediation-2026-07-17.md index 04ef319386..dcb911a8a5 100644 --- a/docs/rag-scalability-wip-remediation-2026-07-17.md +++ b/docs/archive/rag-scalability-wip-remediation-2026-07-17.md @@ -6,9 +6,9 @@ > `20260717170000_registry_projection_cleanup.sql` and > `20260717171000_public_title_corrector.sql`. Do not use this report's status or next > steps as current operator guidance. Use -> [operator-apply-performance-latency-remediation.md](operator-apply-performance-latency-remediation.md), -> [deploy-corrector-public-titles.md](deploy-corrector-public-titles.md), and -> [operator-backlog.md](operator-backlog.md) instead. +> [operator-apply-performance-latency-remediation.md](../operator-apply-performance-latency-remediation.md), +> [deploy-corrector-public-titles.md](../deploy-corrector-public-titles.md), and +> [operator-backlog.md](../operator-backlog.md) instead. **Status:** F11 shipped and merged; all correctness findings verified moot on this branch; scalability build recorded and deferred pending go-ahead. diff --git a/docs/rag-scalability-wip-review-handover-2026-07-15.md b/docs/archive/rag-scalability-wip-review-handover-2026-07-15.md similarity index 100% rename from docs/rag-scalability-wip-review-handover-2026-07-15.md rename to docs/archive/rag-scalability-wip-review-handover-2026-07-15.md diff --git a/docs/audit-handover-2026-07-14.md b/docs/audit/audit-handover-2026-07-14.md similarity index 96% rename from docs/audit-handover-2026-07-14.md rename to docs/audit/audit-handover-2026-07-14.md index f63d842553..a969d672ca 100644 --- a/docs/audit-handover-2026-07-14.md +++ b/docs/audit/audit-handover-2026-07-14.md @@ -9,7 +9,7 @@ remediation without re-running discovery. | Audit date | 2026-07-14 | | Mode | Pure review (no app-code fixes applied as part of the audit) | | Remediation plan | [`audit-remediation-plan-2026-07-14.md`](audit-remediation-plan-2026-07-14.md) | -| Ledger rows | [`branch-review-ledger.md`](branch-review-ledger.md) (multi-skill + consolidated rows) | +| Ledger rows | [`branch-review-ledger.md`](../branch-review-ledger.md) (multi-skill + consolidated rows) | | Plan PR | [#673](https://github.com/BigSimmo/Database/pull/673) (`cursor/audit-remediation-plan-0411`) | | Ledger-only PR | [#652](https://github.com/BigSimmo/Database/pull/652) (`cursor/repo-wide-audit-ledger-0411`) | @@ -238,14 +238,14 @@ Full address sketches: Remediation Wave I in the remediation plan. | Doc | Role | | ------------------------------------------------------------------------------ | -------------------------------- | | [`audit-remediation-plan-2026-07-14.md`](audit-remediation-plan-2026-07-14.md) | How to fix, sequenced | -| [`operator-backlog.md`](operator-backlog.md) | Human/provider actions index | -| [`launch-operator-runbook.md`](launch-operator-runbook.md) | Sequenced launch commands | -| [`privacy-impact-assessment.md`](privacy-impact-assessment.md) | PIA register | -| [`openai-cross-border-basis.md`](openai-cross-border-basis.md) | APP 8 checklist | -| [`tenancy-defense-in-depth-review.md`](tenancy-defense-in-depth-review.md) | Tenancy defense notes | -| [`process-hardening.md`](process-hardening.md) | Process & known debts | -| [`codex-review-protocol.md`](codex-review-protocol.md) | Review severity / mutation rules | -| [`branch-review-ledger.md`](branch-review-ledger.md) | Prevent repeat audits | +| [`operator-backlog.md`](../operator-backlog.md) | Human/provider actions index | +| [`launch-operator-runbook.md`](../launch-operator-runbook.md) | Sequenced launch commands | +| [`privacy-impact-assessment.md`](../privacy-impact-assessment.md) | PIA register | +| [`openai-cross-border-basis.md`](../openai-cross-border-basis.md) | APP 8 checklist | +| [`tenancy-defense-in-depth-review.md`](../tenancy-defense-in-depth-review.md) | Tenancy defense notes | +| [`process-hardening.md`](../process-hardening.md) | Process & known debts | +| [`codex-review-protocol.md`](../codex-review-protocol.md) | Review severity / mutation rules | +| [`branch-review-ledger.md`](../branch-review-ledger.md) | Prevent repeat audits | --- diff --git a/docs/audit-remediation-plan-2026-07-14.md b/docs/audit/audit-remediation-plan-2026-07-14.md similarity index 96% rename from docs/audit-remediation-plan-2026-07-14.md rename to docs/audit/audit-remediation-plan-2026-07-14.md index 4209f5f04a..a89dd32d1e 100644 --- a/docs/audit-remediation-plan-2026-07-14.md +++ b/docs/audit/audit-remediation-plan-2026-07-14.md @@ -1,7 +1,7 @@ # Audit remediation plan — 2026-07-14 Plan derived from the multi-skill repository audit of `main` @ `570e6ba` (ledger rows in -[`branch-review-ledger.md`](branch-review-ledger.md)). This document is the sequenced address plan for +[`branch-review-ledger.md`](../branch-review-ledger.md)). This document is the sequenced address plan for every finding: major blockers first, then P2 sub-issues, then P3 cleanup. **Findings handover (inventory + status):** [`audit-handover-2026-07-14.md`](audit-handover-2026-07-14.md). @@ -31,8 +31,8 @@ every finding against current `main` found the code side largely landed since th - Code fixes use `npm run verify:cheap` first, then the smallest domain check, then `npm run verify:pr-local` before handoff. - Provider/live actions are **operator-gated** (`⏸`). Do not run them without explicit confirmation. -- Reconcile [`operator-backlog.md`](operator-backlog.md) against - [`launch-operator-runbook.md`](launch-operator-runbook.md) before repeating any historical apply. +- Reconcile [`operator-backlog.md`](../operator-backlog.md) against + [`launch-operator-runbook.md`](../launch-operator-runbook.md) before repeating any historical apply. **Legend** @@ -102,48 +102,48 @@ Suggested PR granularity (one theme per PR): ### B1. Close PIA-1 APP 8 / overseas processing basis -| | | -| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Finding** | M1 — Railway Singapore + OpenAI US process incidental PHI queries | -| **Owner** | OWNER:LEGAL + OWNER:OPS | -| **Address** | Execute checklist in [`openai-cross-border-basis.md`](openai-cross-border-basis.md): OpenAI DPA, ZDR eligibility enablement where chosen, Railway DPA/processor record, update PIA status tables and `/privacy` copy only after counsel approval. | -| **Prove** | Status record rows move from `_no_` to dated `_yes_` / approved alternative; PIA-1 no longer High-open | +| | | +| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Finding** | M1 — Railway Singapore + OpenAI US process incidental PHI queries | +| **Owner** | OWNER:LEGAL + OWNER:OPS | +| **Address** | Execute checklist in [`openai-cross-border-basis.md`](../openai-cross-border-basis.md): OpenAI DPA, ZDR eligibility enablement where chosen, Railway DPA/processor record, update PIA status tables and `/privacy` copy only after counsel approval. | +| **Prove** | Status record rows move from `_no_` to dated `_yes_` / approved alternative; PIA-1 no longer High-open | ### B2. Verify Railway `RAG_QUERY_HASH_SECRET` (PIA-2) -| | | -| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Finding** | M2 — secret verified in GitHub CI, Railway runtime still `🔎 verify` | -| **Owner** | OWNER:OPS | -| **Address** | Set/confirm a ≥16-char value in Railway **production** that matches the GitHub Actions secret used for CI smoke. For staging, set a **separate** staging-only `RAG_QUERY_HASH_SECRET` per [`staging-setup.md`](staging-setup.md) — do not reuse the production HMAC key. Confirm boot smoke and deep readiness. | -| **Prove** | `⏸ npm run check:deployment-readiness` / production health boot; backlog → `✅` | +| | | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **Finding** | M2 — secret verified in GitHub CI, Railway runtime still `🔎 verify` | +| **Owner** | OWNER:OPS | +| **Address** | Set/confirm a ≥16-char value in Railway **production** that matches the GitHub Actions secret used for CI smoke. For staging, set a **separate** staging-only `RAG_QUERY_HASH_SECRET` per [`staging-setup.md`](../staging-setup.md) — do not reuse the production HMAC key. Confirm boot smoke and deep readiness. | +| **Prove** | `⏸ npm run check:deployment-readiness` / production health boot; backlog → `✅` | ### B3. Restore OpenAI quota and run release gates -| | | -| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Finding** | M3 — release gate + golden evals incomplete; prior quota exhaustion | -| **Owner** | OWNER:OPS | -| **Address** | Complete the runbook §0 identity preflight with `npm run check:supabase-project`, then restore embedding/completions quota → run `npm run eval:retrieval:quality` (36/36) → `npm run eval:quality -- --rag-only` → `npm run verify:release` per [`launch-operator-runbook.md`](launch-operator-runbook.md) §2. | -| **Prove** | Paste summaries into release notes / backlog; canary path in B4 | +| | | +| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Finding** | M3 — release gate + golden evals incomplete; prior quota exhaustion | +| **Owner** | OWNER:OPS | +| **Address** | Complete the runbook §0 identity preflight with `npm run check:supabase-project`, then restore embedding/completions quota → run `npm run eval:retrieval:quality` (36/36) → `npm run eval:quality -- --rag-only` → `npm run verify:release` per [`launch-operator-runbook.md`](../launch-operator-runbook.md) §2. | +| **Prove** | Paste summaries into release notes / backlog; canary path in B4 | ### B4. Eval Canary trust + staging soak -| | | -| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Finding** | M3 leftovers — canary not yet “two greens”; staging soak pending | -| **Owner** | OWNER:OPS | -| **Address** | Provision staging if absent ([`staging-setup.md`](staging-setup.md)); soak (`scripts/soak-test.ts --confirm-staging`, answer p95 ≤ 25 s); run two consecutive Eval Canary greens from `main`. | -| **Prove** | Soak log + two green workflow runs recorded in backlog | +| | | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **Finding** | M3 leftovers — canary not yet “two greens”; staging soak pending | +| **Owner** | OWNER:OPS | +| **Address** | Provision staging if absent ([`staging-setup.md`](../staging-setup.md)); soak (`scripts/soak-test.ts --confirm-staging`, answer p95 ≤ 25 s); run two consecutive Eval Canary greens from `main`. | +| **Prove** | Soak log + two green workflow runs recorded in backlog | ### B5. Worker image / secret / seed post-deploy confirm -| | | -| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Finding** | Worker redeploy, registry seed, `HEALTH_DEEP_PROBE_SECRET`, auth connection cap | -| **Owner** | OWNER:OPS | -| **Address** | Follow runbook §6 after B3: `reindex:health`, seed registry/differentials, wire ops-digest secrets if desired, flip auth connection allocation **before** vertical scale ([`auth-connection-cap-runbook.md`](auth-connection-cap-runbook.md)). | -| **Prove** | Non-empty Services/Forms; reindex health clear; optional ops-digest cron enabled | +| | | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Finding** | Worker redeploy, registry seed, `HEALTH_DEEP_PROBE_SECRET`, auth connection cap | +| **Owner** | OWNER:OPS | +| **Address** | Follow runbook §6 after B3: `reindex:health`, seed registry/differentials, wire ops-digest secrets if desired, flip auth connection allocation **before** vertical scale ([`auth-connection-cap-runbook.md`](../auth-connection-cap-runbook.md)). | +| **Prove** | Non-empty Services/Forms; reindex health clear; optional ops-digest cron enabled | --- @@ -447,7 +447,7 @@ After Waves B–H land (or are deferred with dated waiver): 4. `⏸ npm run eval:retrieval:quality` + `npm run eval:quality -- --rag-only` 5. `⏸ npm run verify:release` 6. Update PIA / backlog / this plan’s status column (add a “Status” column locally as work completes) -7. Record outcomes in [`branch-review-ledger.md`](branch-review-ledger.md) +7. Record outcomes in [`branch-review-ledger.md`](../branch-review-ledger.md) --- @@ -477,5 +477,5 @@ After Waves B–H land (or are deferred with dated waiver): ## Tracking Append progress to the review ledger when a wave completes, and flip matching rows in -[`operator-backlog.md`](operator-backlog.md). Prefer linking PRs back to issue IDs in this document +[`operator-backlog.md`](../operator-backlog.md). Prefer linking PRs back to issue IDs in this document (`Wave C1`, `Wave E2`, …) in the PR body. diff --git a/docs/design-audit-2026-07-17.md b/docs/audit/design-audit-2026-07-17.md similarity index 100% rename from docs/design-audit-2026-07-17.md rename to docs/audit/design-audit-2026-07-17.md diff --git a/docs/branch-review-ledger.md b/docs/branch-review-ledger.md index eb0d69902d..bec7792037 100644 --- a/docs/branch-review-ledger.md +++ b/docs/branch-review-ledger.md @@ -144,19 +144,11 @@ Records before 2026-07-28 were written by hand and had drifted: 146 lines carrie | 2026-07-30 | PR #1396 / claude/latency-findings-impl-s8g01v | 70e810b66881e17aa9f58126fdad970986bda911 | User ask: resolve comments + Production UI phone-scroll + main sync | FIXED: synced main (DIRTY was staleness); removed union ledger dup; adapted phone-scroll asserts for Answer strategy-overlay + overlay/reserve-only calculator budget + focus pre-scroll inside 8px reveal band. Codex P1s already on tip; 0 unresolved threads. Focused Chromium phone-scroll 9/9 green (system Chrome). | phone-scroll focused 9/9; check:branch-review-ledger PASS; merge-tree clean; prior Codex P1s retained | | 2026-07-30 | HEAD | 13c16cf07c854b50daa35a2ef2a2ea76d5e059e1 | ci-testing-approach | findings: UI-load flake #093 dominates PR reds; schedule full-sentinel blocks release-browser via audit; UI scope overfires on src/app/api; ~40% PR runs cancelled wasting ~12 UI-hrs; CI_TRIAGE inert; eval:rag:offline claimed-in-CI but only fixtures run | gh-ci-500-runs,ci.yml,ci-change-scope,testing.md,process-hardening,outstanding-issues-093-095-097-023,flake-ledger-empty | | 2026-07-30 | cursor/ci-testing-review-1bf5 | 13c16cf07c854b50daa35a2ef2a2ea76d5e059e1 | ci-testing-approach | Corrects the ref cell from the unresolved placeholder "HEAD" to the actual branch name, so ledger:lookup can match this review by branch (Codex P2 finding on PR #1406). | node scripts/branch-review-ledger.mjs lookup cursor/ci-testing-review-1bf5 --scope ci-testing-approach | -| 2026-07-30 | PR #1427 / claude/ci-testing-review-2l8klp | db8209be707b79142d1d228d8c4e04120f9cdeaa | ci-testing-review | Measured PR CI from the Actions API: Production UI is 15m26-16m31 of a 16.8-18.6min run (83-89% of wall clock; Playwright itself 339 passed (13.5m)), every other job done by minute 4; 25/60 completed runs in an 83min window were cancelled (42%). FIXED: sharded ui-critical across 3 runners (count measured - N=4 gives the same 121-test critical path, N=5/N=8 give empty shards which would go red without --pass-with-no-tests); root-caused the real red (ui-phone-scroll dragScrollBy clamped silently and returned nothing, so a 720px request could deliver a fraction and the correct assertion failed 10s later) and made the drag prove its delivery with assertions byte-identical; browser-cache restore-keys; codex-autofix job timeouts; visual config serialised; gate-count guard added and mutation-proven. DEFERRED as #125-#129: ui_changed over-firing on src/app/api, cold Next cache in the Playwright build, advisory-UI cost vs zero quarantine tests, inert CI_TRIAGE, dead changes outputs. | verify:cheap PASS (431 files / 4493 passed, 4 skipped); verify:pr-local PASS (same); prettier --check . PASS; check-gate-manifest PASS + mutation-proven red at stale count; shard balance measured via playwright --list; verify:ui NOT RUN - container cannot launch Chromium (issue #121, build 1234 vs 1194) so the phone-scroll fix and the sharded job are unexecuted, PR CI is first execution | | 2026-07-30 | cursor/ci-hygiene-gates-1bf5 | ad9da6a6f8ba3884b389fa78e678bb88ee72d9d1 | ci-hygiene-gates | implemented matrix unblock, scope narrow, cancelled≠failure, pinned gitleaks, critical-first UI, eval:rag:offline; skipped #093; verify:cheap 4471 pass | verify:cheap,check:ci-scope,check:gitleaks-pinned,check:gate-manifest,eval:rag:offline | | 2026-07-30 | cursor/ci-hygiene-gates-1bf5 | b660dbc5a10d7ca3da03541028017f0abc6b5bd3 | ci-hygiene-gates merge-readiness | findings | check:ci-scope;check:gitleaks-pinned;scope-classify PR files ui_changed=false;sim cancelled-as-neutral | | 2026-07-30 | cursor/ci-hygiene-gates-1bf5 | 8f3283d00da274dee507a1b8e9b611321d1f35be | pr-1413-merge-readiness | READY after main sync + cancel-to-green fix; draft until tip CI green; deferred #093 + CI_TRIAGE_ENABLED confirm | verify:cheap:4481-pass;format:outstanding-issues;merge-tree:clean;cancelled:!cancelled();hosted:awaiting-tip | | 2026-07-30 | cursor/ci-hygiene-gates-1bf5 | 0d70de480f370fec3e7f3774f13d906318a09b3c | pr-1413-merge-readiness | READY: synced with main/#1409; tip CI success incl PR required; draft; deferred #093 + CI_TRIAGE_ENABLED | merge-tree:clean;ci-cache-safety:13/13;hosted:30520195863:success;PR-required:pass | -| 2026-07-30 | origin/main | 3569e7888bba5d11f143f27c11eb9bfa58800e4f | dependency installation and CI reproducibility | no P0-P2 findings; corrected stale setup-ui-e2e cache description | manifest-lock parity; Actions pins; merge-marker scan; merged PR 1360 diff | -| 2026-07-30 | cursor/process-anti-conflict-speed-1edf / PR #1416 | 2a31fcee0ef2e330a4901481c0810103d89c96cf | process anti-conflict merge readiness | NOT READY. CI green on stale head, but merge-tree vs current main is CONFLICTING in ci.yml, package.json, and add/add on check-outstanding-issues.mjs after #1410 landed a stronger #112 gate. Keep unique value: AGENTS anti-conflict procedure, #116 PR mergeability workflow, merge=union on outstanding-issues (explicitly still open after #1410). Drop duplicate weaker outstanding-issues checker; re-verify after sync. | ledger:lookup NOT REVIEWED; merge-tree dirty vs origin/main; ManagePullRequest CI SUCCESS (15 ok / 0 fail, Production UI skipped as non-UI); local verify:pr-local earlier on pre-conflict head 4467 passed | -| 2026-07-30 | cursor/process-anti-conflict-speed-1edf / PR #1416 | 387ffd07887f1160fca8fe98c1c4809e852531ae | process anti-conflict merge readiness | READY after sync with main. Kept #1410 structural outstanding-issues gate; added merge=union + runtime attr check; retained #116 PR mergeability workflow and AGENTS anti-conflict playbook; dropped duplicate weaker checker/test. merge-tree clean vs origin/main. | merge-tree clean; check:outstanding-issues pass; check:pr-mergeability pass; check:gate-manifest pass; verify:pr-local pass | -| 2026-07-30 | cursor/process-anti-conflict-speed-1edf / PR #1416 | 38ae07b989e6414026235debad0e429ba64cf462 | process anti-conflict merge readiness | READY at final tip. Same as prior READY plus this ledger append only; merge-tree still clean vs origin/main. | merge-tree clean; verify:pr-local on 387ffd07 parent (4480 passed); tip is ledger-only follow-up | -| 2026-07-30 | codex/chat-dependency-pr-review-dependency-pr-review-20260730 | 2aee8c74e64bd09954fe1b474c73b25805063de0 | open PR changed-scope review | APPROVE: setup action description now matches clean npm install with npm-download caching; no behavior change. | check:github-actions PASS; diff review; no unresolved threads | -| 2026-07-30 | PR #1427 / claude/ci-testing-review-2l8klp | b9de34d40d2dc5ab164bb1eb582db1cfcd1009c3 | ci-testing-review | SUPERSEDES the 2026-07-30 db8209be record, which asserted a root cause now REFUTED. That record claimed dragScrollBy clamping made the ui-phone-scroll red; main's #127 carries trace evidence (PR #1404 run 30521269873) that the drag delivered in full (scrollTop 1272 = 552+720) with ~1300px runway spare and a 10s non-flip is a latched state. The change is a diagnostic and guard, NOT a fix, and is now labelled so in the docstring, commit, PR body and #127. Remaining candidates: scrollHidden false vs sharedChromePinned latched; they are indistinguishable from the DOM because only the composite data-scroll-hidden is exposed. Prime suspect in source: composerFocusPinsChrome has a still-the-active-owner guard, headerFocusPinsChrome has none (master-search-header.tsx:397-398). ALSO: this PR ran zero pull_request workflows for ~2h (no CI/Gitleaks/Semgrep, only pull_request_target) because a real conflict blocked refs/pull/1427/merge - issue #116, caught by main's new PR mergeability check. Merging main fixed it and CI ran green first try. | CI run 30530618838 SUCCESS (13m39). MEASURED shard result, correcting the ~7min prediction: Production UI (1) 121 tests 9m36, (2) 111 tests 6m54, (3) 110 tests 6m20 - per-test cost is NOT uniform, shard 1 holds the slow specs, so the largest shard is 9m36 not the predicted 6.8min. ui-critical-fast 3m14. PR required SUCCESS. verify:cheap on merged tree PASS (434 files / 4563 passed, 4 skipped); prettier --check . PASS; ui-phone-scroll ran locally 1x via PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH: 56 passed (5.3m) - three-run protocol NOT completed and not applicable, since this is not a flake fix. | -| 2026-07-30 | PR #1400 | e869cb9d7ab20939361b277d1c6fcc07bbb6ca45 | pr-1400-guard-push-band-adoption | MERGED — 17 review findings across guard-push.mjs and the band-adoption gate, all fixed and thread-resolved; each fix confirmed by reverting it and watching the guard fail. Guard now checks the pushed SHA in a git worktree (config, dynamic config, policy escalation incl. removal, lockfile Prettier parity); adoption gate replaced presence-matching with per-module reachability, closing six false greens of one root cause plus type-position edges found in self-review. Merge verified: all 8 commits ancestors of main, 4 changed files byte-identical. | verify:cheap 432 files / 4470 passed 4 skipped; format:check clean; PR required success; services+tools page gutting reports orphans; 6 push-guard scratch-repo cases with real exit codes; every fixture mutation-verified | -| 2026-07-30 | claude/top-search-design-mockups-w53znc | 939d5799b9999f3f63928e1b2c95d097f07eff90 | open PR changed-scope review | APPROVE: PR 1400 closeout and issue IDs 131-134 are unique, internally consistent, and preserve the append-only ledgers. | check:branch-review-ledger PASS; check:outstanding-issues PASS; diff review; no unresolved threads | +| 2026-07-30 | claude/organize-local-worktree-d22bc3 | 2f26a53b5aeb3df451cf7b1d04f80b07edf0d6fe | docs organisation: dated-record filing, docs index gaps, orientation maps | PR #1436 opened — 5 dated docs filed into docs/audit and docs/archive, root codex-cloud-review moved under docs/prompts, 17 docs README index gaps closed, root data/ documented in CLAUDE.md + codebase-index; no product code, schema or RAG surface touched | docs:check-links 1368 refs pass; docs:check-scripts 378 pass; docs:check-index OK; format:check whole-tree clean; verify:cheap 26 static gates + lint + typecheck pass, unit 4562 pass / 1 pre-existing Windows path-separator failure in tests/repo-hygiene.test.ts | | 2026-07-30 | origin/circleci-project-setup | 9a55990053e26c02703b1ec9f2523a7c85e21e14 | branch-cleanup | REJECTED and deleted remote. Unique tip only changed trailing newline on obsolete .circleci hello-world config; CircleCI removed from main in PR #1412. No open PR. | fetch --prune; three-dot + tip inspect; gh pr list open=0; main has no .circleci; GitHub reads explicitly authorized; no non-GitHub provider checks. | | 2026-07-30 | origin/execute-audit-code-remediation | 3470279fba23ad442d59d34552eb576e87f24141 | branch-cleanup | REJECTED and deleted remote. PR #1162 already merged; sole unique commit was a ledger CI-green row already present on main (edcd17a1…). No open PR; no unique product content. | fetch --prune; cherry-pick log; tip-to-tip/three-dot; grep ledger for edcd17a1; gh pr 1162 MERGED; open=0; GitHub reads explicitly authorized; no non-GitHub provider checks. | | 2026-07-30 | origin/apply-audit-remediation-protocol | 046cb38ad45411c5f539636d4c976b25195f7bbd | branch-cleanup | RETAIN. Closed PR #1338; tip still has unique files main lacks (motion-tokens.ts, use-overlay-presence.ts) plus stale sheet/globals diffs. Not empty vs main; do not delete. | ledger lookup; cherry-pick+three-dot; blob existence on main; gh PR #1338 CLOSED; GitHub reads explicitly authorized; no non-GitHub provider checks. | @@ -167,10 +159,21 @@ Records before 2026-07-28 were written by hand and had drifted: 146 lines carrie | 2026-07-30 | origin/execute-audit-remediation-tasks | bdcf8d5c1f14c927bf5b71aaacd34d006856da4f | branch-cleanup | RETAIN. Closed PR #1347; tip adds check-answer-quality-thresholds.ts and check-cost-cap-preflight.ts that main lacks, plus other diffs. Keep. | ledger lookup; cherry-pick; MAIN_LACKS path check; gh #1347 CLOSED; GitHub reads explicitly authorized; no non-GitHub provider checks. | | 2026-07-30 | origin/execute-typography-audit-fixes | dd641579f4cf54f82de89ef268ac8aa6acb439b5 | branch-cleanup | RETAIN. Closed PR #1185 (clean successor #1294 merged); tip blobs still differ from main on globals.css and mockup typography tweaks. Not empty; keep. | ledger lookup; cherry-pick; blob equality; gh #1185 CLOSED #1294 MERGED; GitHub reads explicitly authorized; no non-GitHub provider checks. | | 2026-07-30 | origin/implement-audit-design-fixes | dda4a42baa34e28f12d1e676fcabdbdfaef820c8 | branch-cleanup | RETAIN. Closed PR #1263; tip still carries unique not-found/error route files and a large three-dot diff vs main. Keep. | ledger lookup; cherry-pick; path existence; gh #1263 CLOSED; GitHub reads explicitly authorized; no non-GitHub provider checks. | +| 2026-07-30 | PR #1400 | e869cb9d7ab20939361b277d1c6fcc07bbb6ca45 | pr-1400-guard-push-band-adoption | MERGED — 17 review findings across guard-push.mjs and the band-adoption gate, all fixed and thread-resolved; each fix confirmed by reverting it and watching the guard fail. Guard now checks the pushed SHA in a git worktree (config, dynamic config, policy escalation incl. removal, lockfile Prettier parity); adoption gate replaced presence-matching with per-module reachability, closing six false greens of one root cause plus type-position edges found in self-review. Merge verified: all 8 commits ancestors of main, 4 changed files byte-identical. | verify:cheap 432 files / 4470 passed 4 skipped; format:check clean; PR required success; services+tools page gutting reports orphans; 6 push-guard scratch-repo cases with real exit codes; every fixture mutation-verified | +| 2026-07-30 | cursor/process-anti-conflict-speed-1edf / PR #1416 | 2a31fcee0ef2e330a4901481c0810103d89c96cf | process anti-conflict merge readiness | NOT READY. CI green on stale head, but merge-tree vs current main is CONFLICTING in ci.yml, package.json, and add/add on check-outstanding-issues.mjs after #1410 landed a stronger #112 gate. Keep unique value: AGENTS anti-conflict procedure, #116 PR mergeability workflow, merge=union on outstanding-issues (explicitly still open after #1410). Drop duplicate weaker outstanding-issues checker; re-verify after sync. | ledger:lookup NOT REVIEWED; merge-tree dirty vs origin/main; ManagePullRequest CI SUCCESS (15 ok / 0 fail, Production UI skipped as non-UI); local verify:pr-local earlier on pre-conflict head 4467 passed | +| 2026-07-30 | cursor/process-anti-conflict-speed-1edf / PR #1416 | 387ffd07887f1160fca8fe98c1c4809e852531ae | process anti-conflict merge readiness | READY after sync with main. Kept #1410 structural outstanding-issues gate; added merge=union + runtime attr check; retained #116 PR mergeability workflow and AGENTS anti-conflict playbook; dropped duplicate weaker checker/test. merge-tree clean vs origin/main. | merge-tree clean; check:outstanding-issues pass; check:pr-mergeability pass; check:gate-manifest pass; verify:pr-local pass | +| 2026-07-30 | cursor/process-anti-conflict-speed-1edf / PR #1416 | 38ae07b989e6414026235debad0e429ba64cf462 | process anti-conflict merge readiness | READY at final tip. Same as prior READY plus this ledger append only; merge-tree still clean vs origin/main. | merge-tree clean; verify:pr-local on 387ffd07 parent (4480 passed); tip is ledger-only follow-up | +| 2026-07-30 | origin/main | 3569e7888bba5d11f143f27c11eb9bfa58800e4f | dependency installation and CI reproducibility | no P0-P2 findings; corrected stale setup-ui-e2e cache description | manifest-lock parity; Actions pins; merge-marker scan; merged PR 1360 diff | +| 2026-07-30 | codex/chat-dependency-pr-review-dependency-pr-review-20260730 | 2aee8c74e64bd09954fe1b474c73b25805063de0 | open PR changed-scope review | APPROVE: setup action description now matches clean npm install with npm-download caching; no behavior change. | check:github-actions PASS; diff review; no unresolved threads | +| 2026-07-30 | claude/top-search-design-mockups-w53znc | 939d5799b9999f3f63928e1b2c95d097f07eff90 | open PR changed-scope review | APPROVE: PR 1400 closeout and issue IDs 131-134 are unique, internally consistent, and preserve the append-only ledgers. | check:branch-review-ledger PASS; check:outstanding-issues PASS; diff review; no unresolved threads | | 2026-07-30 | cursor/safe-branch-cleanup-78a8 | c5190f38834ef2e928edc4876d971aa9d5d69fe7 | open PR changed-scope review | APPROVE after fixes: cleanup refs are discoverable, provider evidence is accurate, and issue 108 closure is preserved against current main. | check:branch-review-ledger PASS; check:outstanding-issues PASS; two review threads resolved | | 2026-07-30 | claude/outstanding-issues-triage-24c8ow | 8d2710fd6cbdc84e8c50a6c9bc0a1e1a0cd612c8 | open PR changed-scope review | APPROVE: completed items 095, 096, 104, 109, and 115 move to archive with no deletion, duplicate ID, or stale next-id. | check:outstanding-issues PASS; check:branch-review-ledger PASS; diff review; no unresolved threads | | 2026-07-30 | claude/latency-findings-impl-s8g01v | e7ff5e933ba1f34d5adbd46dd77c38aced11ed44 | open PR changed-scope review | APPROVE: ordering-risk documentation is accurate and the near-bottom refusal guard now proves its geometry is non-vacuous before asserting no hide. | diff check PASS; focused test review; no unresolved threads; exact-head Production UI required | +| 2026-07-30 | PR #1427 / claude/ci-testing-review-2l8klp | db8209be707b79142d1d228d8c4e04120f9cdeaa | ci-testing-review | Measured PR CI from the Actions API: Production UI is 15m26-16m31 of a 16.8-18.6min run (83-89% of wall clock; Playwright itself 339 passed (13.5m)), every other job done by minute 4; 25/60 completed runs in an 83min window were cancelled (42%). FIXED: sharded ui-critical across 3 runners (count measured - N=4 gives the same 121-test critical path, N=5/N=8 give empty shards which would go red without --pass-with-no-tests); root-caused the real red (ui-phone-scroll dragScrollBy clamped silently and returned nothing, so a 720px request could deliver a fraction and the correct assertion failed 10s later) and made the drag prove its delivery with assertions byte-identical; browser-cache restore-keys; codex-autofix job timeouts; visual config serialised; gate-count guard added and mutation-proven. DEFERRED as #125-#129: ui_changed over-firing on src/app/api, cold Next cache in the Playwright build, advisory-UI cost vs zero quarantine tests, inert CI_TRIAGE, dead changes outputs. | verify:cheap PASS (431 files / 4493 passed, 4 skipped); verify:pr-local PASS (same); prettier --check . PASS; check-gate-manifest PASS + mutation-proven red at stale count; shard balance measured via playwright --list; verify:ui NOT RUN - container cannot launch Chromium (issue #121, build 1234 vs 1194) so the phone-scroll fix and the sharded job are unexecuted, PR CI is first execution | +| 2026-07-30 | PR #1427 / claude/ci-testing-review-2l8klp | b9de34d40d2dc5ab164bb1eb582db1cfcd1009c3 | ci-testing-review | SUPERSEDES the 2026-07-30 db8209be record, which asserted a root cause now REFUTED. That record claimed dragScrollBy clamping made the ui-phone-scroll red; main's #127 carries trace evidence (PR #1404 run 30521269873) that the drag delivered in full (scrollTop 1272 = 552+720) with ~1300px runway spare and a 10s non-flip is a latched state. The change is a diagnostic and guard, NOT a fix, and is now labelled so in the docstring, commit, PR body and #127. Remaining candidates: scrollHidden false vs sharedChromePinned latched; they are indistinguishable from the DOM because only the composite data-scroll-hidden is exposed. Prime suspect in source: composerFocusPinsChrome has a still-the-active-owner guard, headerFocusPinsChrome has none (master-search-header.tsx:397-398). ALSO: this PR ran zero pull_request workflows for ~2h (no CI/Gitleaks/Semgrep, only pull_request_target) because a real conflict blocked refs/pull/1427/merge - issue #116, caught by main's new PR mergeability check. Merging main fixed it and CI ran green first try. | CI run 30530618838 SUCCESS (13m39). MEASURED shard result, correcting the ~7min prediction: Production UI (1) 121 tests 9m36, (2) 111 tests 6m54, (3) 110 tests 6m20 - per-test cost is NOT uniform, shard 1 holds the slow specs, so the largest shard is 9m36 not the predicted 6.8min. ui-critical-fast 3m14. PR required SUCCESS. verify:cheap on merged tree PASS (434 files / 4563 passed, 4 skipped); prettier --check . PASS; ui-phone-scroll ran locally 1x via PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH: 56 passed (5.3m) - three-run protocol NOT completed and not applicable, since this is not a flake fix. | | 2026-07-30 | claude/ci-testing-review-2l8klp | 2e2160bc8b9d2d824209c217c67cb9cac1be3a8d | open PR changed-scope review | APPROVE: three-way UI sharding, critical-first gating, measured drag travel, and gate-manifest updates preserve required-check aggregation and deterministic Playwright settings. | check:github-actions PASS; check:ci-scope PASS; check:gate-manifest PASS; ledger guards PASS; exact-head sharded Production UI required | | 2026-07-30 | PR #1430 | a9ae22ac4915e86d51ee05787059382a39bd8ba8 | phone chrome diagnostics and merge repair | fixed and ready for CI | issues guard; ledger guard; 37 focused tests; phone-chrome dry-run | +| 2026-07-30 | PR-1436 | 9d8e081f3e7003d4f2210b00a7b7e54bf7ca2f0b | PR #1436 documentation organization and link repair | fixed stale no-driver wording and renumbered three union-collided issue records; no remaining findings | docs index, links, scripts, outstanding-issues, and ledger guards pass | +| 2026-07-30 | cursor/ci-hygiene-gates-1bf5 | b660dbc5a10d7ca3da03541028017f0abc6b5bd3 | ci-hygiene-gates-merge-readiness | NOT READY: cancel-to-green behavior still allowed required PR CI to pass incorrectly; fixed at subsequent head 8f3283d00da274dee507a1b8e9b611321d1f35be | check:ci-scope; check:gitleaks-pinned; scope-classify PR files ui_changed=false; cancelled-as-neutral simulation exposed #095 | | 2026-07-30 | PR-1440 | f7260cc6a0da87cb4df1ac95ef962967e667c3f0 | PR #1440 issue #102 ordering correction | accurately restores the two canary-gated retrieval ordering constraints; no findings | outstanding-issues and ledger guards pass; documentation-only diff | | 2026-07-30 | PR-1445 | 07933e08cff6c7d81345e02c03727032ccf522b6 | PR #1445 close duplicate issue | correctly archives duplicate #140 while preserving #133 as the surviving open conflict-frequency record; no findings | outstanding-issues and docs-link guards pass; docs-only diff | diff --git a/docs/codebase-index.md b/docs/codebase-index.md index 0af4904fe6..d0afc40070 100644 --- a/docs/codebase-index.md +++ b/docs/codebase-index.md @@ -32,6 +32,18 @@ Structured map for AI agents and onboarding. For live routes, see `docs/site-map | `public/` | Static assets (`public/llms.txt`) | | `.github/` | CI workflows, PR template (clinical governance preflight) | +Smaller top-level directories that are easy to miss: + +| Path | Purpose | +| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data/` | Committed clinical **snapshot exports** loaded at runtime by `src/lib/` (differentials, forms, medications, services, specifiers). Regenerate via the matching `scripts/import-*-export.ts` / `build-*-index.mjs`; do not hand-edit. Distinct from `src/data/`, which holds hand-authored static content. | +| `eslint-rules/` | Repo-specific lint rules enforced by `npm run lint` (button wiring, hardcoded hex, type/icon scale, z-index ladder) | +| `mockups/` | Notes for the design-scratch routes under `src/app/mockups/` (the routes themselves 404 in production) | +| `plugins/` | `plugins/clinical-kb/` Codex plugin manifest and workflow skill | +| `.agents/` | Single-word skill catalogue (`npm run skills`, validated by `npm run check:skills`) | +| `.claude/` | Claude Code agents, skills, hooks, settings — plus the `.claude/worktrees/` working copies | +| `.githooks/` | Installed by `npm install`; `pre-push` runs `scripts/guard-push.mjs` (format, auto-merge race, drift staleness) | + **Do not commit:** `.next/`, `node_modules/`, `coverage/`, `.env*`, `sample-documents/`, logs. --- diff --git a/docs/operator-backlog.md b/docs/operator-backlog.md index 383760ce92..84f1a16998 100644 --- a/docs/operator-backlog.md +++ b/docs/operator-backlog.md @@ -10,8 +10,8 @@ presence claims that must be verified before acting. Update the row (and its runbook) when an action lands. The sequenced flow with exact commands and approval gates is [launch-operator-runbook.md](launch-operator-runbook.md); this table is the index. Code + ops remediation waves from the 2026-07-14 multi-skill audit live in -[audit-remediation-plan-2026-07-14.md](audit-remediation-plan-2026-07-14.md). -Findings inventory for handover: [audit-handover-2026-07-14.md](audit-handover-2026-07-14.md). +[audit/audit-remediation-plan-2026-07-14.md](audit/audit-remediation-plan-2026-07-14.md). +Findings inventory for handover: [audit/audit-handover-2026-07-14.md](audit/audit-handover-2026-07-14.md). > Status column is seeded from repo runbooks + session memory and **must be confirmed against live > state** before acting — do not treat a `🔎 verify` row as authoritative. diff --git a/docs/outstanding-issues.md b/docs/outstanding-issues.md index 80e5a74024..ade9416b1d 100644 --- a/docs/outstanding-issues.md +++ b/docs/outstanding-issues.md @@ -1,4 +1,4 @@ -# Universal Task Ledger — Outstanding Issues, Recommendations & Tasks +# Universal Task Ledger — Outstanding Issues, Recommendations & Tasks Durable, cross-session repository memory of everything still outstanding: open **tasks**, **recommendations**, **issues**, ordered execution metadata, operator decisions, provider gates, and @@ -82,7 +82,7 @@ removed after current-main verification; it is not missing recommended work. | 34 | `#105` | Optional | High — browser/UI verification | When the heavy-run lock is free | 20–40 minutes | Run `verify:ui` over the ten `LoadingPanel` fallbacks and confirm the Supabase `preconnect` reaches `` on a live page. Implementation already shipped; this row is the outstanding verification only. | | 35 | `#126` | Optional | Standard — repository hygiene | Once per UTC calendar quarter, or when the live ledger grows large | 5–15 minutes | Run `npm run ledger:rotate -- --dry-run`, then `npm run ledger:rotate` if the preview looks right; commit the live+archive diff. Stop if dry-run shows unexpected mass moves or archive path collisions. | - + ## Open items @@ -159,6 +159,9 @@ removed after current-main verification; it is not missing recommended work. | #132 | P3 | issue | Both client-side push guards are inert for agent pushes | **Outcome:** the format and auto-merge guards protect every push, or their blind spot is explicit. **Detail:** `scripts/guard-push.mjs` printed `auto-merge: gh not available — auto-merge check skipped (fail-open)` for pushes from a remote agent environment, so the auto-merge race sentinel never evaluated; and `core.hooksPath` is set only by a local `npm install`, so an agent pushing from its own checkout bypasses `.githooks/pre-push` entirely. Both guards therefore protect exactly the environment least likely to break the rule, which is why the AGENTS.md format-before-push instruction is still load-bearing even though the tooling now exists. Observed directly on PR #1400: a push landed while auto-merge was armed with nothing to stop it. **Next:** provide `gh` (or a token-based equivalent) in agent environments so the sentinel can evaluate. **Do not move the format check into `pull_request_target`** — that context carries secrets and a write token, and a format check must execute PR-head code including this repo's now-loadable dynamic `prettier.config.*`, which is the classic privileged-context vector; `.github/workflows/pr-policy.yml` deliberately checks out only `github.workflow_sha` for exactly this reason. Formatting is already enforced server-side by `Static PR checks` running `format:check` on ordinary `pull_request` CI, so the guard's only unique value is failing fast before the push — nothing to duplicate. The auto-merge sentinel reads PR metadata only and could safely live in `pull_request_target` if it is ever worth moving. | PR #1400; session 2026-07-30 | 2026-07-30 | | #133 | P3 | rec | Ledger conflicts on nearly every `main` advance (union driver removed) | **Outcome:** two agents editing different rows of this ledger do not silently corrupt it. **Driver half RESOLVED 2026-07-30:** `merge=union` is removed from `.gitattributes` and `check:outstanding-issues` now requires that **no** driver is set, so a reappearance is a red gate (proved by reintroducing it: `must have NO merge driver (found merge=union)`). This row already recorded union as worse — "two sides each bumping the marker produce two `next-id` lines, corrupting the file silently where a conflict would fail loudly" — but the attribute stayed in place and the gate _mandated_ it, so the repo's own tested conclusion was contradicted by its own config. PR #1430 confirmed the cost at scale: four merges in one session, each reporting success while duplicating the **entire** open-items table (`#059 appears 2 times (lines 101, 166)` and so on), every one needing a manual rebuild from `origin/main`. Union also makes `git merge-tree` report a clean tree, so the pre-merge conflict check cannot warn. Unlike `docs/branch-review-ledger.md`, this file allocates IDs by read-modify-write, so concurrent appends need manual renumbering whatever the driver does — union bought nothing. `AGENTS.md`, `docs/process-hardening.md`, `.claude/skills/issues/SKILL.md` and `docs/scripts-index.md` are updated to match. **Still open — the conflict frequency itself:** the table is padded to fixed column widths, so one row's edit re-pads every open row and git sees the whole table as one changed hunk; on 2026-07-30 it conflicted twice within an hour on PR #1400, and each conflict silently stopped **all** CI on that PR (`#116`). **Next:** stop padding this table (Prettier still renders it readably, and one-row edits become one-line diffs), or split the open items into per-row files. **Stop:** do not reintroduce a merge driver here; if concurrent-append pain returns, write a dedupe driver like `merge=ledger`'s rather than stock union. | `.gitattributes`; `scripts/check-outstanding-issues.mjs`; PR #1400; PR #1430 | 2026-07-30 | | #134 | P2 | issue | Ledger union-merge driver is absent wherever `npm install` was skipped | **Outcome:** the ledger's union-merge protection is present wherever a merge happens, or its absence is loud. **Detail:** `.gitattributes` declares `docs/branch-review-ledger.md merge=ledger`, but the driver itself lives in git _config_, installed by `postinstall` -> `scripts/install-git-hooks.mjs`. A container that skips `npm install` (this repo's remote agent sessions do — the session hook reports "node_modules matches the lockfile, skipping install") therefore has the attribute without the driver, and git silently falls back to an ordinary merge. On 2026-07-30 a `git merge origin/main` on PR #1424 produced **conflict markers inside the append-only ledger** at three lines; `git merge` itself did not name the file, so only `npm run check:branch-review-ledger` caught it. Committing that would have corrupted the file the guard exists to protect. **Next:** make the absence loud — have `check:branch-review-ledger` (already in `verify:cheap` and `static-pr`) fail when `.gitattributes` declares `merge=ledger` but `git config merge.ledger.driver` is unset, so the environment is caught before a merge rather than after. `npm run hooks:install` is the one-line fix once detected. **Stop:** never trust a `merge=union`-style attribute to be active just because `.gitattributes` declares it; the driver is per-checkout config. | PR #1424; session 2026-07-30 | 2026-07-30 | +| #144 | P2 | issue | `check:docs-index` has no repo-root directory coverage | **Outcome:** a new top-level directory cannot stay absent from the orientation maps. **Detail:** `scripts/check-codebase-index-coverage.mjs` exists precisely to catch "a module that never gets added to the map, silently staling it", but its granularity is route groups, `src/lib` module dirs and schema tables — it never looks at repo-root directories. That blind spot is how root `data/` stayed undocumented in both `CLAUDE.md` and `docs/codebase-index.md` while seven `src/lib` modules loaded it at runtime (differentials, forms, medications, services, specifiers), and how it stayed easy to confuse with the unrelated `src/data/`. PR #1436 documented `data/`, `mockups/`, `plugins/`, `eslint-rules/`, `.agents/`, `.claude/` and `.githooks/` by hand, so the maps are correct today with nothing stopping the next one from drifting. **Next:** extend the checker with a repo-root pass plus an allowlist for directories that are deliberately unmapped (build output, `.git`, vendored dirs). Kept out of #1436 deliberately — widening a blocking gate that runs in `verify:cheap` and `static-pr` deserves its own PR and its own red-then-green proof. | PR #1436; `scripts/check-codebase-index-coverage.mjs:1-17`; session 2026-07-30 | 2026-07-30 | +| #142 | P3 | task | Four loose dated docs need source and migration edits before they can be filed | **Outcome:** every dated point-in-time doc lives in `docs/audit/` or `docs/archive/` as `docs/README.md` requires, not loose at the `docs/` top level. **Detail:** PR #1436 filed the five that were docs-only moves. These four are referenced from outside `docs/`, so relocating them means editing source, tests and migration SQL comments — a different risk class than a docs tidy, and not worth bundling into one: `capacity-review.md` (`scripts/soak-test.ts`), `tenancy-defense-in-depth-review.md` (`src/lib/owner-scope.ts`, `tests/owner-scope-guard.test.ts`, two migrations, `SECURITY.md`, `.claude/agents/clinical-governance-reviewer.md`), `operator-apply-july8-batch.md` (three migrations plus `supabase/schema.sql`), `scale-readiness-review.md` (one migration). Also note `forward-codify-retrieval-rpcs-workorder.md` is indexed as a completed workorder but live is still ahead of the repo on those RPCs, so archiving it would misrepresent open operator work. **Next:** treat as low priority — the docs are correctly indexed and reachable where they are; only file them if a pass is already editing those migrations. Editing applied migration SQL is subject to `npm run check:migration-role`'s immutability pin. | PR #1436; session 2026-07-30 | 2026-07-30 | +| #143 | P2 | issue | An uncommitted hook in the main checkout aborts commits in every worktree | **Outcome:** a worktree commit is not blocked by unfinished work sitting in a different checkout. **Detail:** `core.hooksPath` is an absolute path to the primary checkout's `.githooks` (`C:\Dev\Apps\Database\.githooks`), and it is shared by every linked worktree because `git config` writes to the common config file. That primary checkout currently has an **uncommitted** `.githooks/pre-commit` plus an `update-docs-inventory.mjs` under `scripts/`; neither is on `origin/main` (so that path deliberately appears un-linked here — it does not resolve in this repo). The hook therefore fires in worktrees whose branch does not contain the script and dies: `Error: Cannot find module '/scripts/update-docs-inventory.mjs'` — `[pre-commit] Synchronizing generated documentation...` then `MODULE_NOT_FOUND`, commit aborted. Hit directly on PR #1436, worked around per-command with `git -c core.hooksPath=/.githooks commit` (not `--no-verify`, and without touching the shared checkout). **Mitigated 2026-07-30, NOT closed:** the hook now fails open — if the inventory task is selected but its script is absent from the committing worktree it prints `skipping inventory sync`, drops that task, and re-checks the all-tasks-empty early exit (without that re-check an empty `docs_to_check` makes the trailing `git diff --name-only --` match every modified file in the tree). Proven by committing from a linked worktree with the shared `core.hooksPath` untouched: exit 0. **Why this is not a fix:** that hook file is _untracked in the primary checkout and committed on no branch_, so the mitigation is not version-controlled — it disappears on overwrite and is absent from any fresh clone or other machine. The script itself IS committed, on `codex/docs-sync-automation-pr` (3 commits ahead of `main`), so the durable fix is to commit `.githooks/pre-commit` alongside it on that branch and let `scripts/install-git-hooks.mjs` distribute it. Inverse blind spot to #132: there the hook never runs, here it runs from the wrong tree. | PR #1436 commit attempt; session 2026-07-30 | 2026-07-30 | | #135 | P2 | rec | UI scope overfires: `ui_changed` matches every `src/app` path | **Outcome:** a change that cannot alter a rendered journey stops paying the longest job in CI. **Detail:** `uiPatterns` in `scripts/ci-change-scope.mjs` matches all of `src/app`, so an edit confined to `src/app/api/**` sets `ui_changed` and runs the full Chromium gate — measured 2026-07-30 at 15m26 of an 18m36 run, the entire critical path. **Next:** decide whether API-only diffs can be excluded. **Not done blind, deliberately:** the journeys exercise a production build that serves those routes, so a naive exclusion can hide a real regression; this needs a decision plus a compensating check, not a quieter filter. Sharding `ui-critical` (PR #1427) cut the cost of over-firing but did not remove it. | `scripts/ci-change-scope.mjs`; CI runs 30520443076 / 30519912667; session 2026-07-30 | 2026-07-30 | | #136 | P2 | rec | Playwright's isolated production build cannot reuse Next's build cache | **Outcome:** the fixed ~2 min build stops being repaid on every UI job and every shard. **Detail:** `scripts/run-playwright.mjs` builds into `.next-playwright/${pid}-${Date.now()}/dist`, so Next's webpack filesystem cache (which lives under `distDir`) is cold every run — ~1m56 of the 15m26 `Chromium production journeys` step measured 2026-07-30, and a larger share of the sharded critical path. The `build` job already caches `.next/cache` correctly; this path simply cannot hit it. **Next:** allow the run root to be pinned via an env var (defaulting to today's behaviour) and cache it in `ui-critical`. **Blocker:** the runner removes the run root on every exit path, which `docs/testing.md` states as a contract, so caching needs an explicit keep flag and must not ship without executing the runner. | `scripts/run-playwright.mjs`; `docs/testing.md`; session 2026-07-30 | 2026-07-30 | | #137 | P3 | rec | Advisory UI spends ~3 min per UI PR on five mockup tests | **Outcome:** the advisory lane costs what its signal is worth. **Detail:** `ui-advisory` runs on every UI PR (3m14 measured 2026-07-30) to cover `@quarantine` plus `@mockup` journeys — but `tests/flake-ledger.json` is empty and there are **zero** `@quarantine` tests in the suite, so it executes 5 `@mockup` tests. It is `continue-on-error` and outside `pr-required`, so it can also rot unnoticed. **Next:** gate it on mockup-file scope, or accept the cost as the price of keeping the lane warm for future quarantines. Either is defensible; the current state is just unmeasured. | `.github/workflows/ci.yml` `ui-advisory`; `tests/flake-ledger.json`; session 2026-07-30 | 2026-07-30 | diff --git a/codex-cloud-review/1-codex-full-stack-master-review-prompt.md b/docs/prompts/codex-cloud-review/1-codex-full-stack-master-review-prompt.md similarity index 100% rename from codex-cloud-review/1-codex-full-stack-master-review-prompt.md rename to docs/prompts/codex-cloud-review/1-codex-full-stack-master-review-prompt.md diff --git a/codex-cloud-review/2-codex-full-stack-master-prompt-review-and-stress-test.md b/docs/prompts/codex-cloud-review/2-codex-full-stack-master-prompt-review-and-stress-test.md similarity index 100% rename from codex-cloud-review/2-codex-full-stack-master-prompt-review-and-stress-test.md rename to docs/prompts/codex-cloud-review/2-codex-full-stack-master-prompt-review-and-stress-test.md diff --git a/codex-cloud-review/3-codex-agents-md-companion.md b/docs/prompts/codex-cloud-review/3-codex-agents-md-companion.md similarity index 100% rename from codex-cloud-review/3-codex-agents-md-companion.md rename to docs/prompts/codex-cloud-review/3-codex-agents-md-companion.md diff --git a/docs/scripts-index.md b/docs/scripts-index.md index aaca65923f..e2c848a67e 100644 --- a/docs/scripts-index.md +++ b/docs/scripts-index.md @@ -1,9 +1,14 @@ # Scripts index -Curated map of `scripts/` (~135 files) and the `package.json` script surface (~166 entries), +Curated map of `scripts/` (188 files) and the `package.json` script surface (203 entries), grouped by purpose. This is orientation, not an exhaustive per-file listing — the authoritative command list is `package.json`, and `npm run docs:check-scripts` verifies every `npm run ` -referenced in docs resolves to a real script. +referenced in docs resolves to a real script. Every one of the 168 top-level `.mjs`/`.ts`/`.cjs` +scripts is named below; the rest of the 188 are fixtures, SQL and subfolder helpers, and small +shared helpers are grouped rather than itemised. + +> The two counts in the sentence above are generated facts, not prose. Keep them in the exact +> `(N files)` / `(N entries)` shape — tooling rewrites that sentence by regex. Legend: **[live]** routine tooling · **[infra]** runner/guard plumbing · **[one-shot]** completed migration/batch helper that is a candidate for an `archive/` subfolder under `scripts/` once its @@ -11,17 +16,22 @@ migration has shipped (see `docs/maturity-backlog-workorders.md` L1). ## Runner & guard infrastructure [infra] -| Script | Role | -| ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -| `run-heavy.mjs` | Acquires shared/exclusive cross-worktree leases (`test-run-lock.mjs`) so focused checks can overlap safely | -| `run-tsx.mjs`, `run-vitest.mjs`, `run-playwright.mjs`, `run-eval-safe.mjs` | Typed/test/e2e/eval entrypoint wrappers | -| `dev-free-port.mjs`, `ensure-local-server.mjs` | Project-stable localhost port selection + background server ensure | -| `check-node-engine.cjs`, `install-git-hooks.mjs`, `guard-push.mjs`, `guard-next-build.mjs` | Install/preflight guards | -| `ci-change-scope.mjs`, `ci-triage.mjs`, `pr-policy.mjs`, `pr-mergeability.mjs` | CI change classification + PR policy + conflict signal (self-tested via `check:ci-scope`/`check:ci-triage`/`check:pr-policy`/`check:pr-mergeability`) | -| `check-outstanding-issues.mjs`, `check-pr-mergeability-workflow.mjs` | Outstanding-issues ID/marker/no-driver guard + PR mergeability workflow contract | -| `check-installed-lock-parity.mjs`, `phone-chrome-plan.mjs`, `verify-phone-chrome.mjs` | Lock-trust preflight plus change-scoped phone contracts, ownership journeys, and smart full-UI escalation | -| `final-merge-audit.mjs` | Fail-closed local merge-tree audit; explicit provider mode adds PR/check/thread/tree/deployment proof | -| `child-process-result.mjs`, `cli-utils.ts`, `productivity-core.mjs` | Shared helpers | +| Script | Role | +| ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| `run-heavy.mjs` | Acquires shared/exclusive cross-worktree leases (`test-run-lock.mjs`) so focused checks can overlap safely | +| `run-tsx.mjs`, `run-vitest.mjs`, `run-playwright.mjs`, `run-eval-safe.mjs` | Typed/test/e2e/eval entrypoint wrappers | +| `dev-free-port.mjs`, `ensure-local-server.mjs` | Project-stable localhost port selection + background server ensure | +| `check-node-engine.cjs`, `install-git-hooks.mjs`, `guard-push.mjs`, `guard-next-build.mjs` | Install/preflight guards | +| `ci-change-scope.mjs`, `ci-triage.mjs`, `pr-policy.mjs`, `pr-mergeability.mjs` | CI change classification + PR policy + conflict signal (self-tested via `check:ci-scope`/`check:ci-triage`/`check:pr-policy`/`check:pr-mergeability`) | +| `check-outstanding-issues.mjs`, `check-pr-mergeability-workflow.mjs` | Outstanding-issues ID/marker/no-driver guard + PR mergeability workflow contract | +| `check-installed-lock-parity.mjs`, `phone-chrome-plan.mjs`, `verify-phone-chrome.mjs` | Lock-trust preflight plus change-scoped phone contracts, ownership journeys, and smart full-UI escalation | +| `final-merge-audit.mjs` | Fail-closed local merge-tree audit; explicit provider mode adds PR/check/thread/tree/deployment proof | +| `child-process-result.mjs`, `cli-utils.ts`, `productivity-core.mjs` | Shared helpers | +| `test-focused.mjs`, `test-run-selection.mjs`, `test-cache-path.mjs`, `test-environment.mjs` | Backs `npm run test:focused` — change-scoped selection, cache pathing, env setup; fails closed for deleted files and test infrastructure | +| `primary-checkout-lease.mjs`, `test-run-lock.mjs`, `clean-worktree.mjs` | Cross-worktree lease arbitration for the primary checkout, plus worktree cleanup | +| `resolve-tsx-cli.mjs`, `register-server-only.mjs`, `enable-server-only-stub.mjs` | tsx CLI resolution and `server-only` import shims | +| `check-format-changed.mjs`, `check-base-freshness.mjs`, `check-local-presence.mjs` | Push-time helpers behind `guard-push.mjs`: changed-file formatting, stale-base and local-presence checks | +| `yaml-contract.mjs`, `sensitive-text.mjs`, `design-system-contract-utils.mjs` | Shared parsing/redaction/contract helpers used by the gates | ## Verification gates [live] @@ -35,6 +45,13 @@ migration has shipped (see `docs/maturity-backlog-workorders.md` L1). `verify-release-offline.mjs`, `check-codex-cloud-setup.mjs`. `check-gate-manifest.mjs` cross-checks that every gate in the `verify:cheap:internal` chain also runs in CI's `static-pr` job, so the two lists can't drift. +Also in the gate set: `check-assets.mjs`, `check-branch-review-ledger.mjs`, +`check-hosted-migration-role.mjs` (`check:migration-role` — pins the immutable applied migration and +the `postgres` role), `check-edge-functions.mjs`, `check-env-parity.mjs`, `check-ci-env.mjs`, +`run-gitleaks-pinned.mjs`, `rag-offline-contract.mjs` + `test-rag-offline.mjs` (offline RAG +contract), `check-lighthouse-budget.mjs` + `run-lighthouse-budget.mjs`, and the workflow-contract +guards `check-pr-policy-workflow.mjs` and `check-codex-autofix-workflow.mjs`. +`audit-formatting-fixtures.ts` checks the formatting fixtures themselves. `setup-codex-cloud.sh` and `maintain-codex-cloud.sh` reproduce the provider-free Cloud runtime documented in `docs/codex-cloud.md`; `npm run check:codex-cloud` verifies that the runtime pins, install commands, offline defaults, and documentation stay aligned. @@ -61,9 +78,13 @@ For executable phone-chrome changes, use `verify:phone-chrome` before the broad `eval-rag.ts`, `eval-rag-offline.mjs`, `eval-retrieval.ts`, `eval-quality.ts`, `eval-answer-quality.ts`, `eval-search.ts`, `eval-search-api.ts`, `eval-assertions.ts`, `compare-retrieval-eval.ts`, `retrieval-health.ts`, `profile-retrieval-rpcs.ts`, -`warm-retrieval-cache.ts`, `tune-search-weights.ts`, `check-rag-fixtures.mjs`. Golden fixtures: +`warm-retrieval-cache.ts`, `tune-search-weights.ts`, `check-rag-fixtures.mjs`, `eval-trend.mjs` +(trend across runs), `eval-utils.ts` (shared harness helpers). Golden fixtures: `scripts/fixtures/rag-retrieval-golden.json`, `scripts/fixtures/assertion-golden.json`. +Editing anything in this section is a protected-surface change — read `docs/rag-behaviour/` and flag +the task before you start. + ## Registry / catalogue content [live] `seed-registry-records.ts`, `embed-registry-records.ts`, `reconcile-registry-governance.ts`, @@ -81,7 +102,32 @@ For executable phone-chrome changes, use `verify:phone-chrome` before the broad `cleanup-storage.ts`, `purge-query-logs.ts`, `audit-tables.ts`, `supabase-recovery-status.ts`, `promote-query-misses.ts`, `flake-ledger.mjs`, `sweep-branch-ledger.mjs`, `dependency-report.mjs`, -`set-site-administrator.ts`. +`set-site-administrator.ts`, `ops-digest.mjs`, `build-clinical-review-queue.ts`, +`verify-locality-metadata.ts`. + +### Review ledger, branches and skills [live] + +- `branch-review-ledger.mjs` — the **only** way to read or write `docs/branch-review-ledger.md` + (`ledger:lookup` / `ledger:append` / `ledger:dedupe` / `ledger:rotate`). Never hand-write a row. +- `merge-branch-review-ledger.mjs` — the `merge=ledger` union driver from `.gitattributes`; + `check-branch-review-ledger.mjs` fails if that protection is lost. +- `sync-open-pr-branches.mjs` (`sync:pr-branches`) — anti-churn sync for stale open PR heads; + refuses a missing or bot `gh` identity. `sweep-merged-branches.mjs` — merged-branch sweep. +- `reconciliation-preflight.mjs`, `reconciliation-evidence-pack.mjs` — broad chat/worktree + reconciliation entry point and its evidence bundle; see `docs/reconciliation-playbook.md`. +- `list-database-skills.mjs` (`skills` / `check:skills`), `sync-skills.mjs`, `skill-create.mjs` — + the `.agents/skills/` catalogue. + +### Live/staging verification [live] + +`soak-test.ts`, `test-cross-tenant-staging.ts` (the executable owner-boundary proof behind +`docs/staging-tenancy-release-evidence.md`), `deployment-boot-smoke.mjs`, `run-live-tests.mjs`. +These reach live providers — they need explicit confirmation before running. + +### Browser and performance capture [infra] + +`playwright-base-url.ts`, `classify-playwright-failures.mjs`, `capture-chrome-parity.ts`, +`summarise-web-vitals.mjs`. ## One-shot / dated — archive candidates [one-shot] @@ -96,7 +142,8 @@ out of the `tests/**` run. **Remaining candidates** (still in `scripts/`, retire once each is confirmed retired): `check-retrieval-owner-migration.ts`, `backfill-source-metadata.ts`, `backfill-text-normalization.ts`, `backfill-visual-intelligence.ts`, `backfill-document-tags.ts`, `backfill-enrichment.ts`, -`derive-unknown-status.ts`, `reindex-image-generation-metadata.ts`, `measure-wrapped-dose-prevalence.ts`. +`derive-unknown-status.ts`, `reindex-image-generation-metadata.ts`, `measure-wrapped-dose-prevalence.ts`, +`decompose-indexing-v3.mjs`, `repro-coalesce-poison-race.mjs` (a one-off race reproducer). ## Workflow planners [infra] diff --git a/scripts/check-docs-links.mjs b/scripts/check-docs-links.mjs index 4883994037..65b782bb74 100644 --- a/scripts/check-docs-links.mjs +++ b/scripts/check-docs-links.mjs @@ -11,10 +11,11 @@ * inside the repository. * * Scanned by default: README.md, AGENTS.md, and docs/**\/*.md excluding - * docs/archive/, docs/audit/, and dated point-in-time filenames + * docs/archive/, docs/audit/, dated point-in-time filenames * (docs/README.md classifies those as historical records that intentionally - * reference the repo as it was). Pass --all to scan those too - * (informational deeper sweep; still fails on missing paths). + * reference the repo as it was), and docs/prompts/codex-cloud-review/ (verbatim + * as-provided prompt inputs whose paths must not be edited). Pass --all to scan + * those too (informational deeper sweep; still fails on missing paths). * * Advisory tool: run `npm run docs:check-links` before doc handoffs. It is * deliberately NOT part of verify:cheap or CI so historical docs cannot @@ -57,6 +58,9 @@ const ALLOWLIST = new Set([ const DATED_DOC = /\b20\d{2}-\d{2}(-\d{2})?\b/; // Historical directories: only scanned with --all. const HISTORICAL_DIRS = new Set(["archive", "audit"]); +// Verbatim as-provided inputs: retained byte-for-byte, so their internal path +// references cannot be corrected. Only scanned with --all. +const VERBATIM_DIRS = new Set(["codex-cloud-review"]); const APP_ROUTE_GROUPS = ["(search-app)"]; function repoPathExists(repoRelative) { @@ -73,8 +77,8 @@ function collectDocs(dirRelative, targets) { for (const entry of readdirSync(absolute, { withFileTypes: true })) { const entryRelative = path.posix.join(dirRelative, entry.name); if (entry.isDirectory()) { - const isHistorical = HISTORICAL_DIRS.has(entry.name); - if (isHistorical && !scanAll) continue; + const isSkippable = HISTORICAL_DIRS.has(entry.name) || VERBATIM_DIRS.has(entry.name); + if (isSkippable && !scanAll) continue; collectDocs(entryRelative, targets); continue; }