docs(spec) Phase 4 Wave 0 — § Scope + ADRs 0019-0024 + guardrails Per-phase gate#95
Merged
Conversation
Phase 4 design conversation locked the demonstrable artifact: full RAG architecture against a curated 7-machine subset, with full-corpus expansion deferred to Phase 4.5. Drafts § Phase 4 to mirror Phase 3's structure (24 scope items, 6 waves, 3 operational hand-offs), adds Phase 4.5 placeholder, and records three new deferred-features entries (full corpus, service bulletins, OCR fallback) that point at Phase 4.5 as the revisit trigger. Wave 0 PR W0-1 of the Phase 4 parallel plan; unblocks W0-2 (ADRs 0019-0023 batch).
W0-2 Wave 0 PR. Drafts six new ADRs (hybrid chunking, embedding model, AI Search index schema, tool-call-trace citation extraction, citation-required guardrail, two-stage re-ranking) and updates Phase 4 § Scope to absorb the customer-quality re-evaluation: - Service bulletins fold into Phase 4 for the curated subset's two Stern machines (Repair quality at launch); index schema (ADR-0021) supports document_type enum from v1; Change Feed Function trigger (item 18) extends to manual + service_bulletin. - ADR-0024 locks the Cohere Rerank cross-encoder path; implementation gates on H3 quality data (citation_precision < 0.65 AND ≥30% retrieval-side refusals) — decision recorded in repo even if code defers. - § Scope renumbered 1-25; references throughout (Key decisions, Exit criteria, Parallelism plan, Risks, Open design questions, Deferred features) updated to match. Wave 0 PR W0-2; closes Wave 0 except for the optional W0-3 (guardrails.md § Per-phase gate enhancement).
W0-3 Wave 0 PR. Adds an explicit README.md + docs/vision.md per-phase-close-review checkbox to the § Per-phase gate. Reason: post-Phase-3-close audit (PR #94) caught README/vision overclaims that PR-time review missed — and this is the second time the pattern repeated (Phase 1 close had a similar gap). The per-phase gate now enforces what per-PR review can't: checking customer-facing claim accuracy against the phase's actual deliverables before declaring exit. Closes Wave 0 of the Phase 4 parallel execution plan; unblocks Wave 1 (A-track inherited follow-ups + B-track foundations).
Pre-push /local-review surfaced 2 🔴 + 4⚠️ findings; all addressed: 🔴 Cross-reference sync after § Scope renumbering: - ADR-0019 References: items 1, 14 → 1, 15 - ADR-0020 References: items 2, 15 → 2, 15, 16 - ADR-0021 References: items 3, 14, 15 → 3, 16, 18, 20 - ADR-0022 body + References: items 9, 20 → 10, 21 - ADR-0023 body + References: items 22, 23 → 23, 24 - ADR-0024 body + References: item 23 → 24 🔴 ADR-0024 missing from docs/adr/README.md index — added.⚠️ ADR-0024: "Alternatives evaluated for the locked path" subsection folded into the main "Alternatives considered" section with two named sub-groups (Phase 4 stance / impl choice). Aligns with Phase 3 ADR template.⚠️ ADR-0024: clarified Rag:CrossEncoder:Enabled flag is part of deferred implementation surface, not Phase 4 v1 dead config (preempts dead-config-grep tripwire at impl time).⚠️ ADR-0023: added pinwiz.ai.tool_errors_total mitigation for the "tool-error vs agent-didn't-call-tool" telemetry indistinguishability; build-spec scope item 25 extended to define the instrument.⚠️ Build-spec: hand-off H1 framing fixed from "After Wave 1" to "Mid-Wave 1 (after PR W1-4)" — matches dependency core. Closes Wave 0 PR fix-up loop; ready for push.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Wave 0 of the Phase 4 parallel execution plan — pure docs/ADRs/spec, no code. Establishes the foundation for Phase 4 (Event-driven RAG against a curated 7-machine subset) so subsequent code waves have a target to aim at.
The Phase 4 design conversation (2026-05-07) locked the demonstrable artifact as full RAG architecture against a curated 7-machine subset, with full-corpus expansion deferred to Phase 4.5. Customer-quality re-evaluation mid-conversation also folded service bulletins for the curated subset's two Stern machines into Phase 4 (highest-leverage Repair-agent quality fix at minimal cost) and added ADR-0024 (two-stage re-ranking) to lock the cross-encoder path even though implementation defers behind an H3 quality gate.
Four commits:
fe4d21d— Phase 4 § Scope draft (25 items mirroring Phase 3 structure) + Phase 4.5 placeholder + 3 deferred-features entries050f201— ADRs 0019-0024 (chunking / embedding / index schema / citation extraction / citation-required guardrail / two-stage re-ranking) + bulletin fold-in3178285— guardrails.md § Per-phase gate enhancement: README.md + docs/vision.md per-phase-close-review checkbox (lesson from PR docs(spec) post-Phase-3-close audit fix-ups — README honesty pass + observability PinballMap inventory #94 — second time the pattern repeated)7bcbf97— /local-review fix-up (2 🔴 + 4Test Plan
Doc-only PR — no code, no tests added or modified.
grep "scope item" docs/adr/00{19,20,21,22,23,24}-*.md)docs/adr/README.mdindex includes all 6 new ADRs (0019-0024)git log -1 --format='%an <%ae>'shows personal noreplyOut of Scope
Wave 0 is doc-only by design. Implementation work begins in Wave 1 (Phase 4 § Scope items 7-14, sequenced per the parallelism plan). Specifically out of scope for this PR:
data/phase4/curated-subset.v1.jsonslate manifest (that lands in Wave 2 PR W2-4 per the plan)Checklist
docs/adr/— six new ADRs (0019-0024)~/.claude/projects/c--projects-PinballWizard/memory/is now stale (the parallel-execution-plan and design-kickoff handoff are honored, not contradicted)TODO/FIXME/ commented-out code committed<NoWarn>without a comment explaining why and the removal criterion — N/A (no code)Pre-push self-audit
Step 0 —
/local-review(qualitative)/local-reviewand addressed every 🔴 finding before pushStep 1 — Mechanical checklist
*Optionsproperty has at least one real getter call insrc/— N/A (no code)catch { }— N/A (no code)ISourceScraper? — N/A (no scrapers)git log -1 --format='%an <%ae>'shows personal noreply, not work email — confirmed94459922+jkeeley2073@users.noreply.github.com