Skip to content

docs: reconcile memory ledgers after task review + fix .env.example weak-OR footgun #720

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
BigSimmo merged 2 commits into from
Jul 17, 2026
+51 −12
Merged

docs: reconcile memory ledgers after task review + fix .env.example weak-OR footgun #720

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d6c26b8
docs: reconcile memory ledgers after task review + fix .env.example w…
claude Jul 17, 2026
3b75bb1
Merge branch 'main' into claude/memory-tasks-review-glmntq
BigSimmo Jul 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions .env.example
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,8 +99,10 @@ RAG_PROVIDER_MODE=auto
# Omit for current defaults. Example (enable diversity demotion + linear freshness):
# RAG_RANKING_CONFIG={"documentDiversityPenalty":0.03,"freshness":{"mode":"linear"}}
# Append OR-relaxed recall behind weak-but-nonzero strict text matches (P8b extension).
# Set false to restore relax-only-on-empty behaviour (golden retrieval eval kill switch).
RAG_TEXT_WEAK_OR_RELAXATION=true
# Opt-in experiment ONLY and OFF by default (matches the src/lib/env.ts default): it is known to
# regress the golden retrieval eval (buries some correct docs after re-ranking). Leave false;
# re-enable solely behind a fresh 36/36 golden retrieval run. false = relax-only-on-empty.
RAG_TEXT_WEAK_OR_RELAXATION=false
Comment on lines +102 to +105

@coderabbitai coderabbitai Bot Jul 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
rg -n '34/34|36/36|RAG_TEXT_WEAK_OR_RELAXATION' .env.example src/lib/env.ts docs

Repository: BigSimmo/Database

Length of output: 12310

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '\n== .env.example ==\n'
sed -n '98,108p' .env.example

printf '\n== src/lib/env.ts ==\n'
sed -n '118,132p' src/lib/env.ts

printf '\n== docs references ==\n'
rg -n '34/34|36/36|RAG_TEXT_WEAK_OR_RELAXATION' docs src/lib/env.ts .env.example

Repository: BigSimmo/Database

Length of output: 14075

Make the golden-run threshold consistent. .env.example and the runbooks say 36/36, but src/lib/env.ts:126 still says 34/34. Update the stale comment so operators see one release gate everywhere.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.env.example around lines 102 - 105, Update the stale golden retrieval
threshold comment associated with RAG_TEXT_WEAK_OR_RELAXATION in src/lib/env.ts
to require a 36/36 run, matching .env.example and the runbooks; change only the
documented release-gate value.

RAG_ANSWER_CACHE_TTL_MS=300000
RAG_ANSWER_CACHE_SIZE=100
RAG_SEARCH_CACHE_TTL_MS=60000
Expand Down
19 changes: 19 additions & 0 deletions docs/audit-remediation-plan-2026-07-14.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,25 @@ 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).

**Reconciliation — 2026-07-17 (`claude/memory-tasks-review-glmntq`):** a read-only cross-check of
every finding against current `main` found the code side largely landed since this plan was written.

- **DONE in code:** C1 (anon catalog rate-limit), D1 (public-doc DTO redaction), D5 (bulk error
redaction), E1 (unreachable commit fallback), E2 (recovery dedup), F4 (flake ledger emptied),
G1–G4 (full frontend a11y wave), H6 (`/api/jobs` auth-first + 503), F5 (`.env.example` weak-OR
default corrected to `false` to match the `src/lib/env.ts` default — this pass). The a11y wave
(G) and the ingestion recovery/commit wave (E1/E2) are fully closed.
- **Superseded:** F2 (CI RAG-eval scope) — the offline RAG-eval gate now runs unconditionally.
- **Still open — OWNER:CODE:** D2 (tenancy CI guard `check-owner-scope-api.mjs` still absent), D3
(`getSession()`→`getUser()` in `client.tsx`), E3 (wire `decideReindexGate` into `scripts/reindex.ts`),
F1 (CI UI-scope patterns miss `app-modes`/`ui-copy`), F3 (`@critical` safety assert still
conditional), F6 (bundle-budget `enforce:false`),
H1–H5 (API-contract hygiene: error envelopes, admin-route rate limits, list-offset cap,
upload Content-Length reserve, authed-summarize public scope). Biggest remaining cluster is H1–H5.
- **In flight (do not restart):** draft PRs **#708** (frontend a11y/layout P2s) and **#710**
(storage-bucket migration drift — "closes the audit's open P2 list").
- **Operator-pending (⏸):** Waves A/B/J and D4 (all live/legal/ops). Wave I (P3) untouched.

**Rules for executing this plan**

- Prefer the smallest safe change per finding; do not bundle unrelated domains in one PR.
Expand Down
21 changes: 19 additions & 2 deletions docs/ingestion-concurrency-fix-workorder.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,17 @@
# Ingestion-concurrency phase-3 — fix work-order

**Status refresh 2026-07-17:** the last remaining repository design item below —
deep-memory section ownership / delete-scoping — is now **RESOLVED**, so this document has
**no open repository items**. It shipped as the producer-scoped replacement model: migration
`20260713030000_producer_scoped_deep_memory.sql` adds `producer` + `artifact_generation_id`
columns with **disjoint** unique indexes (`document_sections_legacy_section_index_key` for
`artifact_generation_id is null` vs `document_sections_producer_generation_section_index_key`),
so the enrichment agent and deep-memory can no longer collide on `section_index`; the
service-role commit RPC removes only older artifacts owned by the same producer; and
`src/lib/deep-memory.ts` stages and deletes strictly scoped by `producer = local-deep-memory` +
`artifact_generation_id` (`cleanupStagedArtifacts`), with the commit body reconciled in #569. No
unscoped cross-producer delete remains. The design section at the bottom is retained as provenance.

**Status refresh 2026-07-15:** the July-8 migration batch is applied and verified live. The only
remaining repository design item in this document is deep-memory section ownership/delete scoping
(see the final section); it is intentionally blocked on an explicit ownership model and a
Expand Down Expand Up @@ -32,7 +44,9 @@ nothing here was applied to live at author time. **Historical status (2026-07-09

## Still open (not merged or needs design)

- **deep-memory delete-scoping** — design required (see bottom of this doc).
- _None._ **deep-memory delete-scoping** landed via the producer-scoped model (migration
`20260713030000` + commit #569 + `src/lib/deep-memory.ts`) — see the 2026-07-17 status refresh
at the top. The design section at the bottom of this doc is retained as provenance only.

## Global rules for this release

Expand Down Expand Up @@ -318,7 +332,10 @@ for live apply of R24e → RPC hardening → fail-closed → R5 → R17 (`202607

Remaining repo work:

1. **deep-memory scoping** — only after the section-ownership design is agreed.
1. ~~**deep-memory scoping**~~ — **DONE (2026-07-17)** via the producer-scoped model
(`20260713030000` + #569 + `src/lib/deep-memory.ts`). The section-ownership question was
settled by giving each producer a disjoint `(document_id, producer, artifact_generation_id,
section_index)` key. No remaining repo work in this document.

Every DB item ends with `npm run check:drift` green and (for retrieval-affecting
items) `npm run eval:retrieval:quality` unchanged.
17 changes: 9 additions & 8 deletions docs/operator-backlog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,14 +17,15 @@ Findings inventory for handover: [audit-handover-2026-07-14.md](audit-handover-2

## Launch-gating actions

| Action | Status | Blocked by | Verify command | Runbook |
| -------------------------------------------------------------------------- | ---------- | -------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| Apply July-8 migration batch (a–g) to live | ✅ done | — | `SUPABASE_ENVIRONMENT=production npm run check:july8-live-batch` (2026-07-13: 6 live, apply=no-op) | [operator-apply-july8-batch.md](operator-apply-july8-batch.md) |
| Apply drift-codify forward migration (step 1h) | ✅ done | — | Applied and drift/readiness verified 2026-07-13; verify only unless new reviewed drift is found | [database-drift-detection.md](database-drift-detection.md) |
| Full release gate (bounded OpenAI spend) | ⏳ pending | migrations 1 applied | `npm run verify:release`; `npm run eval:quality -- --rag-only` | [launch-operator-runbook.md §2](launch-operator-runbook.md) |
| Provision staging Supabase project (`Clinical KB Staging`, ap-southeast-2) | ⏳ pending | — | `npm run check:indexing` after `db push` | [staging-setup.md](staging-setup.md) |
| Staging soak + rollback rehearsal on Railway | ⏳ pending | staging provisioned | `scripts/soak-test.ts --confirm-staging` (answer p95 ≤ 25 s) | [launch-operator-runbook.md §4](launch-operator-runbook.md) · [capacity-review.md](capacity-review.md) |
| Production deploy to Railway | ✅ done | — | App deployment recorded live 2026-07-14; re-verify with `GET /api/health` and deployment readiness | [deployment-architecture.md](deployment-architecture.md) |
| Action | Status | Blocked by | Verify command | Runbook |
| -------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| Apply July-8 migration batch (a–g) to live | ✅ done | — | `SUPABASE_ENVIRONMENT=production npm run check:july8-live-batch` (2026-07-13: 6 live, apply=no-op) | [operator-apply-july8-batch.md](operator-apply-july8-batch.md) |
| Apply drift-codify forward migration (step 1h) | ✅ done | — | Applied and drift/readiness verified 2026-07-13; verify only unless new reviewed drift is found | [database-drift-detection.md](database-drift-detection.md) |
| Apply repo-ahead migrations to live (post-2026-07-13) | 🔎 verify | `20260713201542` · `20260714110000` · `20260717120000` committed, live-apply unconfirmed | `npm run check:drift`; then `eval:retrieval:quality` (36/36) for the corrector | [deploy-corrector-public-titles.md](deploy-corrector-public-titles.md) |

@coderabbitai coderabbitai Bot Jul 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '--- package.json scripts matching eval:retrieval:quality ---\n'
rg -n '"eval:retrieval:quality"|eval:retrieval:quality' package.json . -g 'package.json' -g '!node_modules' || true

printf '\n--- docs operator-backlog row ---\n'
sed -n '20,28p' docs/operator-backlog.md

Repository: BigSimmo/Database

Length of output: 246

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo '--- package.json scripts matching eval:retrieval:quality ---'
rg -n '"eval:retrieval:quality"|eval:retrieval:quality' package.json . -g 'package.json' -g '!node_modules' || true

echo
echo '--- docs operator-backlog row ---'
sed -n '20,28p' docs/operator-backlog.md

Repository: BigSimmo/Database

Length of output: 3992

Make the retrieval-quality check copy-pasteable. eval:retrieval:quality is an npm script, so the verify command should use npm run eval:retrieval:quality.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/operator-backlog.md` at line 24, Update the verify command in the
migration backlog row to invoke the retrieval-quality script as “npm run
eval:retrieval:quality” instead of the bare script name, while preserving the
existing drift check and evaluation details.

| Full release gate (bounded OpenAI spend) | ⏳ pending | migrations 1 applied | `npm run verify:release`; `npm run eval:quality -- --rag-only` | [launch-operator-runbook.md §2](launch-operator-runbook.md) |
| Provision staging Supabase project (`Clinical KB Staging`, ap-southeast-2) | ⏳ pending | — | `npm run check:indexing` after `db push` | [staging-setup.md](staging-setup.md) |
| Staging soak + rollback rehearsal on Railway | ⏳ pending | staging provisioned | `scripts/soak-test.ts --confirm-staging` (answer p95 ≤ 25 s) | [launch-operator-runbook.md §4](launch-operator-runbook.md) · [capacity-review.md](capacity-review.md) |
| Production deploy to Railway | ✅ done | — | App deployment recorded live 2026-07-14; re-verify with `GET /api/health` and deployment readiness | [deployment-architecture.md](deployment-architecture.md) |

## Post-deploy actions

Expand Down