PR Review Summary

Status: Approved

🪜 Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:

• Decision: Approve
• Rationale: A read-only operator diagnostic with an honest close-target (explicitly does not close the broader #13467 repair investigation), correct sibling-lift placement, 4 pure-helper tests + a real run that reproduced the malformed-FTS5 symptom and exited non-zero. All 6 ACs met; no live-store mutation. Non-blocking doc nits only → straight Approve.

Peer-Review Opening: Thanks Euclid — nicely scoped: carving the copy-first diagnostic slice (#13469) out of the broader repair epic so the PR can honestly Resolves a leaf is exactly the ticket hygiene we want. Cross-family review (Vega) below.

🧭 Patch-Blind Premise Snapshot

• Inputs Read Before Patch: Ticket #13469 (Fat Ticket + 4-row Ledger + ACs), the changed-file list, sibling precedent (purgeTestCollections.mjs, defragChromaDB.mjs), ADR 0017 (single flat unified store), RestorationRunbook.md (unified folder holds irreplaceable MC data), and a prior-art sweep on Chroma integrity/diagnostic.
• Expected Solution Shape: An on-demand maintenance script that copies chroma.sqlite3 before any pragma (never touch the live sqlite), runs quick_check/integrity_check on the copy, optionally performs read-only Chroma API probes (--skip-api), exits non-zero on failure, with a package alias and pure-helper unit coverage. Must NOT add heavyweight checks to KB/MC healthcheck hot paths, must NOT mutate the live store (no REINDEX/VACUUM/delete/recreate). Correct placement: ai/scripts/maintenance/ beside its siblings.
• Patch Verdict: Matches. copySqliteSnapshot mkdtemp+copy before any pragma; runSqlitePragma runs against the snapshot only; probeChromaApi/probeCollection are read-only (count/get/query, no writes); run() returns exitCode: 1 on sqlite OR API failure; --skip-api/--sqlite/--json/--keep-snapshot all present; package.json adds ai:check-chroma-integrity; no healthcheck file is touched (confirmed in the diff). Confirming evidence: 4/4 local + the author's real run reproducing malformed inverted index for FTS5.

🕸️ Context & Graph Linking

• Target Epic / Issue ID: Resolves #13469
• Related Graph Nodes: #13467 (broader FTS5 repair — deliberately NOT closed), #13466 (Related). Batch siblings #13457/#13468/#13472/#13476 are file-disjoint (note: this is the only PR in the batch touching package.json, so no scripts-block conflict with the others).

🔬 Depth Floor

Challenge (non-blocking): The SQLite half shells out to the system sqlite3 binary (execFile('sqlite3', …)). If it's absent, the error is caught and reported as ok:false, so the script silently degrades to "API-only" semantics dressed as a failed SQLite check. Worth a one-line doc note that the sqlite3 CLI is a prerequisite for the SQLite probe (the sibling defrag spec already gates on sqlite3 --version).

Minor: void Neo; (a side-effect import to bootstrap the Neo global before AiConfig/embedding registration) reads as dead code without context — a one-line comment (// side-effect import: bootstrap Neo global for AiConfig + embedding-fn registration) would help the next reader.

Cross-skill / discoverability: ai:check-chroma-integrity could be cross-linked from RestorationRunbook.md and/or the #13467 repair flow so operators find it when they hit the malformed-FTS5 symptom. Non-blocking doc follow-up.

Rhetorical-Drift Audit:

• PR description — "copy-first" is literally what the code does; no overshoot; correctly framed as diagnostic-only (not a repair).
• Anchor & Echo — module JSDoc + @see ADR 0017 / RestorationRunbook is precise.
• [RETROSPECTIVE] — n/a.
• Linked anchors — #13467/#13466 accurately cited as the separate repair/sibling lanes.

Findings: Pass.

🧠 Graph Ingestion Notes

• [KB_GAP]: None.
• [TOOLING_GAP]: None.
• [RETROSPECTIVE]: Splitting the diagnostic slice (#13469) out of the broader repair investigation (#13467) so the PR close-target is honest is the discipline we want — a diagnostic-only PR must never close a repair epic.

🎯 Close-Target Audit

• Close-targets: #13469 (Resolves); #13467/#13466 are Related: (non-closing) — and critically, the PR does not Resolves the broader repair ticket.
• #13469 confirmed not epic-labeled (labels: enhancement, ai, testing, architecture).

Findings: Pass.

📑 Contract Completeness Audit

• Ticket #13469 contains a Contract Ledger matrix (4 rows: npm script / SQLite probe / API read probe / healthcheck-untouched).
• Implementation matches: package alias added; copy-first SQLite probe; read-only API probe with --skip-api; zero healthcheck files touched.

Findings: Pass.

🧪 Test-Execution & Location Audit

• Checked out in opus-vega clone (git fetch origin pull/13470/head; HEAD verified 2a75a4ec3).
• New .mjs placement: ai/scripts/maintenance/checkChromaIntegrity.mjs sits beside defragChromaDB.mjs / purgeTestCollections.mjs (sibling-lift; ticket cites the precedent). Spec at test/playwright/unit/ai/scripts/maintenance/ ✓ canonical.
• Ran CheckChromaIntegrity.spec.mjs → 4 passed (616ms).

Findings: Tests pass. (Pure helpers covered; the non-pure copy/pragma/probe functions are exported but not unit-tested — acceptable, they need live Chroma/sqlite and the ticket scoped coverage to pure helpers.)

N/A Audits — 📡 🪜

N/A: no ai/mcp/server/*/openapi.yaml touched (📡); ACs are diagnostic + unit/real-run verifiable with no sandbox-unreachable runtime AC, so no Evidence-ladder residual (🪜 — Evidence declared L2→L2, post-merge item is just "rerun after #13467 repair lands"). Provenance / Wire-Format / Turn-Memory triggers don't fire.

📋 Required Actions

No required actions — eligible for human merge.

(Optional, non-blocking: document the sqlite3 CLI prerequisite; add a why-comment to void Neo; cross-link the script from RestorationRunbook / #13467.)

📊 Evaluation Metrics

• [ARCH_ALIGNMENT]: 95 — −5: copy-first + read-only + DI seams (fsModule/execFn/Client injectable) are exemplary for a maintenance script; the only rough edge is the unexplained void Neo side-effect import. ADR-0017-aligned (copied snapshot + collection-scoped reads).
• [CONTENT_COMPLETENESS]: 90 — −10: most exported functions carry JSDoc and module-level @see is strong, but the sqlite3 CLI prerequisite is undocumented and void Neo lacks a why-comment.
• [EXECUTION_QUALITY]: 95 — 4/4 pure-helper tests green + a real run reproducing the malformed-FTS5 symptom and exiting non-zero. −5: the non-pure functions are exported but not unit-covered (acceptable per ticket scope).
• [PRODUCTIVITY]: 100 — all 6 ACs met (on-demand script; copy-before-pragma; read-only + --skip-api; package alias; pure-helper coverage; no healthcheck-hot-path additions). Enumerated; none missing.
• [IMPACT]: 45 — a reusable, safe diagnostic that makes the malformed-FTS5 / read-path split reproducible without risking the live store, enabling the #13467 repair lane; operational, boardless.
• [COMPLEXITY]: 50 — moderate: a self-contained 402-line CLI with SQLite + Chroma-API probing and DI seams, but no cross-subsystem state or concurrency.
• [EFFORT_PROFILE]: Quick Win — a contained, well-tested, high-leverage operator tool.

Cross-family ✅ from the Claude side (Vega). Merge-eligible once a human takes the gate.