claude-mem/PATHFINDER-2026-04-22/_rewrite-plan.md

PATHFINDER-2026-04-22 Rewrite Plan

Purpose: Execute a clean rewrite of the claude-mem refactor corpus, replacing PATHFINDER-2026-04-21/ with a principle-driven 8-plan corpus. Each phase can be executed consecutively in a fresh chat context.

Inputs (already in this directory):

• _reference.md — verified current-code anchors + external API signatures
• _mapping.md — section-by-section migration map from old → new

Outputs (to be produced by executing this plan):

• 00-principles.md — unifying criteria every plan is measured against
• 01-data-integrity.md — UNIQUE constraints, idempotency, self-healing claim
• 02-process-lifecycle.md — delete supervisor, lazy-spawn, process groups
• 03-ingestion-path.md — fail-fast parser, direct ingest, recursive fs.watch
• 04-read-path.md — 1 renderer, 1 search path, delete SearchManager.findBy*
• 05-hook-surface.md — fail-loud hooks, blocking endpoint, cached alive
• 06-api-surface.md — Zod middleware, delete diagnostic endpoints
• 07-dead-code.md — TranscriptParser class, migration 19, @deprecated sweep
• 98-execution-order.md — DAG + preflight gates + post-landing greps
• 99-verification.md — grep targets, acceptance criteria, viewer lockdown

Target lines deleted across the corpus: ~3,800 LoC net, after double-count correction.

---

Global principles (cite in every plan)

1. No recovery code for fixable failures. If the primary path is correct, recovery never runs. If it's broken, recovery hides the bug.
2. Fail-fast over grace-degrade. Local code does not circuit-break, coerce, or silently fall back. It throws and lets the caller decide.
3. UNIQUE constraint over dedup window. DB schema prevents duplicates; don't time-gate them.
4. Event-driven over polling. fs.watch over setInterval rescan. Server-side wait over client-side poll. child.on('exit') over periodic scan.
5. OS-supervised process groups over hand-rolled reapers. detached: true + kill(-pgid) replaces orphan sweeps.
6. One helper, N callers. Not N copies of a helper. Not a strategy class for each config.
7. Delete code in the same PR it becomes unused. No @deprecated fence, no "remove next release."

These are repeated verbatim in 00-principles.md. Every other plan cites them.

---

Anti-pattern guards (check in every plan)

• No new setInterval in src/services/worker/ or the plan text (plan 99 greps for this)
• No new coerce*, recover*, heal*, repair*, reap*, kill*Orphans* function names
• No new try/catch that swallows errors and returns a fallback value
• No new schema column whose only purpose is to feed a recovery query
• No new strategy class when a config object would do
• No new HTTP endpoint for diagnostic / manual-repair purposes

---

Phase 0 — Documentation discovery (DONE)

Status: Complete. See _reference.md (API + code anchors) and _mapping.md (old→new section mapping). Phase 0 subagents verified 12 old plans, every audit-cited file:line, every external API in use.

---

Phase 1 — Write 00-principles.md

Task: Draft the principles document that every other plan cites.

Sections:

1. The seven principles (copy verbatim from "Global principles" section above)
2. The six anti-pattern guards (copy verbatim from "Anti-pattern guards" above)
3. The unifying diagnosis (one paragraph): missing primary-path correctness gets papered over with defensive code; defensive code hides bugs in the primary path; hidden bugs spawn more defensive code. Same disease, five organs.
4. Five cures table: one row per subsystem (lifecycle, data, search, ingestion, hooks) stating the concrete cure from the principles.
5. Glossary: "second-system effect," "lease pattern," "self-healing claim," "fail-fast contract" — one-sentence definitions with the canonical example.

Doc refs: none outside this plan — 00-principles.md is the anchor every other plan cites.

Verification:

• File exists at PATHFINDER-2026-04-22/00-principles.md
• Seven principles are numbered and quotable
• Five cures table has all five subsystems
• Glossary has one-sentence definitions for the four terms

Anti-pattern guards for this phase:

• Don't add principles that don't have a cure in the table
• Don't add cures for problems not in the audit
• Don't add a "see also" subsection — principles stand alone

---

Phase 2 — Write 01-data-integrity.md + 02-process-lifecycle.md

These two plans define the tectonic primitives other plans depend on. Both run in the same phase because they're the foundation.

2A. 01-data-integrity.md

Task: Draft the data-layer plan covering schema UNIQUE constraints, idempotency tokens, self-healing claim query, Chroma sync, migration cleanup.

Phases inside this plan:

1. Fresh schema.sql — regenerate from current migrations, remove started_processing_at_epoch column, add worker_pid INTEGER, add UNIQUE(session_id, tool_use_id) on pending_messages, add UNIQUE(memory_session_id, content_hash) on observations.
2. Migrate existing databases — ALTER TABLE for the new columns, backfill, create UNIQUE indexes.
3. Self-healing claim query — replace 60-s stale-reset-inside-claim with UPDATE pending_messages SET worker_pid=?, status='processing' WHERE status='pending' OR (status='processing' AND worker_pid NOT IN live_worker_pids) ORDER BY created_at_epoch LIMIT 1. Delete STALE_PROCESSING_THRESHOLD_MS, delete started_processing_at_epoch column.
4. Delete dedup window — remove DEDUP_WINDOW_MS + findDuplicateObservation; replace with INSERT … ON CONFLICT DO NOTHING.
5. Delete clearFailedOlderThan interval — failed rows are a retention policy question. Make them a query-time filter (WHERE status != 'failed' OR updated_at > now-1h) or just let them accumulate until a user explicitly purges.
6. Delete repairMalformedSchema Python subprocess — root-cause WAL corruption if it recurs; do not ship repair code.
7. Chroma sync — upsert semantics — document delete-then-add as a bridge pattern; gate behind CHROMA_SYNC_FALLBACK_ON_CONFLICT=true flag; remove once Chroma MCP adds upsert natively.
8. Delete migration 19 no-op — absorbed into the fresh schema.sql.

Doc refs: _reference.md Part 1 §Data layer + §Chroma sync; SQLite docs on ON CONFLICT DO NOTHING + UNIQUE on added columns; migration 22 precedent in runner.ts:658-837.

Verification:

• grep -n STALE_PROCESSING_THRESHOLD_MS src/ → 0
• grep -n started_processing_at_epoch src/ → 0
• grep -n DEDUP_WINDOW_MS src/ → 0
• grep -n findDuplicateObservation src/ → 0
• grep -n repairMalformedSchema src/ → 0
• grep -n clearFailedOlderThan src/services/worker-service.ts → 0 (interval deletion)
• Integration test: kill worker mid-claim; next worker's claim succeeds and row is re-processed

Anti-pattern guards:

• Do NOT keep recoverStuckProcessing() as a boot-once function. Self-healing claim replaces it entirely.
• Do NOT add a new timer for Chroma backfill. Backfill runs at boot-once OR on-demand when a downstream reader requests.
• Do NOT add "repair" CLI commands.

2B. 02-process-lifecycle.md

Task: Draft the lifecycle plan: delete src/supervisor/, lazy-spawn from hooks, process groups for SDK children, no reapers, no idle-shutdown.

Phases inside this plan:

1. Delete src/services/worker/ProcessRegistry.ts (the worker-side parallel registry). Consolidate to src/supervisor/process-registry.ts.
2. Change SDK spawn to use process groups — src/services/worker/ProcessRegistry.ts:452-465 (to be moved to supervisor): spawn(cmd, args, { detached: true, stdio: ['ignore','pipe','pipe'] }). Track pgid = proc.pid.
3. Change shutdown cascade to kill groups — src/supervisor/shutdown.ts:116, 163: process.kill(-record.pgid, 'SIGTERM') → wait 5s → process.kill(-record.pgid, 'SIGKILL').
4. Delete all reaper intervals — startOrphanReaper, staleSessionReaperInterval, clearFailedOlderThan interval at worker-service.ts:537, 547, 567. Delete killSystemOrphans, killIdleDaemonChildren, reapOrphanedProcesses, reapStaleSessions.
5. Delete the abandonedTimer per-session setTimeout — replace with synchronous cleanup in generatorPromise.finally at the session itself.
6. Delete idle-eviction — SessionManager.evictIdlestSession at :477-506. Pool backpressure via queue depth instead.
7. Delete fallback agent chain (Gemini → OpenRouter) in SessionManager. Fail-fast on SDK failure; surface to hook via exit 2.
8. Lazy-spawn wrapper — every hook's ensureWorkerRunning() (src/shared/worker-utils.ts:221-239): check port → if dead, spawn(bunPath, [workerPath], { detached: true, stdio: ['ignore','ignore','ignore'] }) → proc.unref() → return. Optional respawn dep for 3-attempt startup retry with backoff.
9. Delete worker self-shutdown — no idle timer. Worker runs until killed.

Doc refs: _reference.md Part 1 §Worker/lifecycle + Part 2 API verification rows 1-3 (Node detached, kill(-pgid)); commit 99060bac for PID-reuse pattern.

Verification:

• grep -rn setInterval src/services/worker/ → 0
• grep -rn startOrphanReaper src/ → 0
• grep -rn staleSessionReaperInterval src/ → 0
• grep -rn killSystemOrphans src/ → 0
• grep -rn killIdleDaemonChildren src/ → 0
• grep -rn reapStaleSessions src/ → 0
• grep -rn reapOrphanedProcesses src/ → 0
• grep -rn evictIdlestSession src/ → 0
• grep -rn abandonedTimer src/ → 0
• grep -rn "fallbackAgent\|Gemini\|OpenRouter" src/services/worker/SessionManager.ts → 0
• src/services/worker/ProcessRegistry.ts file does NOT exist
• src/supervisor/ directory DOES still exist (canonical registry + shutdown)
• Integration test: kill worker via kill -9 <pid>; next hook respawns worker; no orphan children remain
• Integration test: graceful SIGTERM to worker; all SDK children exit within 6s

Anti-pattern guards:

• Do NOT keep killSystemOrphans as a boot-once function — orphans are PREVENTED by process groups, not swept.
• Do NOT add idle-timer self-shutdown to the worker.
• Do NOT introduce a third process registry during the migration.

---

Phase 3 — Write 03-ingestion-path.md + 04-read-path.md

3A. 03-ingestion-path.md

Task: Draft the ingestion plan: fail-fast parser, direct ingestObservation() call, recursive fs.watch, DB-backed tool pairing, single-regex tag strip, delete TranscriptParser dead class.

Phases inside this plan: 0. Ingest helpers (prerequisite for plans 05, 06, 07) — ingestObservation(payload), ingestPrompt(payload), ingestSummary(payload) as direct functions on the worker. No HTTP loopback.

1. parseAgentXml — single entry point returning { valid: true, data } | { valid: false, reason } discriminated union. Replaces parseObservations + parseSummary + coerceObservationToSummary.
2. ResponseProcessor migration — call parseAgentXml once; on invalid, markFailed(messageId, reason). On valid summary, emit summaryStoredEvent (consumed by 05-hook-surface.md blocking endpoint).
3. Delete circuit breaker — consecutiveSummaryFailures, MAX_CONSECUTIVE_SUMMARY_FAILURES, SessionManager guards on it.
4. Delete coerce function — coerceObservationToSummary in src/sdk/parser.ts:222-259 removed entirely.
5. Recursive fs.watch — src/services/transcripts/watcher.ts:124-132 replaces 5-s rescan setInterval with fs.watch(transcriptsRoot, { recursive: true }). Preflight: engines.node >= 20.0.0.
6. DB-backed tool pairing — delete pendingTools Map at processor.ts:23. Insert both tool_use and tool_result rows into pending_messages with UNIQUE(session_id, tool_use_id) constraint. Pair by JOIN at read time.
7. Direct ingestObservation — processor.ts:252 calls the helper from Phase 0, not observationHandler.execute().
8. Single-regex tag strip — consolidate src/utils/tag-stripping.ts countTags/stripTagsInternal to one regex with alternation.
9. Delete dead TranscriptParser class — src/utils/transcript-parser.ts:28-90.

Doc refs: _reference.md Part 1 §Ingestion; old Plan 01/03/08 for prior work; fs.watch Node 20+ release notes.

Verification:

• grep -n coerceObservationToSummary src/ → 0
• grep -n consecutiveSummaryFailures src/ → 0
• grep -n "pendingTools" src/services/transcripts/ → 0
• grep -n "setInterval" src/services/transcripts/watcher.ts → 0
• grep -n "observationHandler.execute" src/services/transcripts/ → 0
• grep -n "TranscriptParser" src/utils/transcript-parser.ts → file does not exist
• package.json engines.node ≥ 20.0.0
• Fuzz test: drop JSONL with tool_use but no tool_result → row stays pending, no pair emitted, no crash
• Fuzz test: drop JSONL with tool_result referencing unknown tool_use_id → debug log, no crash, no phantom observation

Anti-pattern guards:

• Do NOT keep coercion as a "lenient mode" flag.
• Do NOT ship a polling fallback for fs.watch — Node 20+ handles recursive Linux natively.
• Do NOT preserve the in-memory Map behind a feature flag.

3B. 04-read-path.md

Task: Draft the read-path plan: one renderer with strategy config, one search path, delete SearchManager.findBy*, consolidate recency filter, throw 503 on Chroma failure.

Phases inside this plan:

1. renderObservations(obs, strategy: RenderStrategy) — single function replacing AgentFormatter, HumanFormatter, ResultFormatter, CorpusRenderer. RenderStrategy is a config object with knobs: header, grouping, rowDensity, colors, columns.
2. Delete four formatter classes — src/services/context/formatters/*.ts replaced by four configs passed to renderObservations.
3. Delete SearchManager duplicated methods — findByConcept, findByFile, findByType at SearchManager.ts:1209-1310, 1277, 1399. Route all calls through SearchOrchestrator.
4. Consolidate recency filter — import RECENCY_WINDOW_MS from types.ts:16 into every call site. Delete all seven hand-rolled copies in SearchManager.
5. Fail-fast Chroma — SearchOrchestrator.ts:85-110 throws 503 on Chroma error instead of stripping query and re-querying SQLite. ChromaSearchStrategy.ts:76-86 returns usedChroma: false only when Chroma is explicitly uninitialized; propagates real errors.
6. Delete hybrid silent fallbacks — HybridSearchStrategy.ts:82-95, 120-134, 161-173: propagate errors instead of returning metadata-only.
7. Delete @deprecated getExistingChromaIds — dead code fence removed in same PR.
8. Single estimateTokens utility — src/shared/estimate-tokens.ts. Delete duplicates in ResultFormatter.ts:264 and CorpusRenderer.ts:90.
9. Knowledge-corpus simplification — delete session_id persistence, prime/reprime operations, auto-reprime regex in KnowledgeAgent; rewrite /query to fresh SDK call with systemPrompt; rely on SDK prompt caching.

Doc refs: _reference.md Part 1 §Search + §Context; old Plans 05, 06, 10.

Verification:

• grep -n "SearchManager\.findBy" src/ → 0 (definitions deleted)
• grep -rn "RECENCY_WINDOW_MS" src/services/worker/SearchManager.ts → 0 (constants inlined in 7 places deleted)
• grep -n "fellBack: true" src/ → 0 (silent fallback flag deleted)
• grep -n "getExistingChromaIds" src/ → 0
• ls src/services/context/formatters/ → empty or deleted
• Integration test: Chroma down → request fails with 503 (not empty result)
• Snapshot test: renderObservations with agent config produces byte-identical output to the old AgentFormatter on the same input

Anti-pattern guards:

• Do NOT create a RenderStrategy class hierarchy. Config object only.
• Do NOT add a feature flag to "disable fail-fast Chroma" — callers either handle 503 or they don't.

---

Phase 4 — Write 05-hook-surface.md + 06-api-surface.md

4A. 05-hook-surface.md

Task: Draft the hook plan: consolidate worker HTTP plumbing, cache settings, delete shell retry loops, delete polling in summarize, fail-loud after N consecutive failures.

Phases inside this plan:

1. Delete shell retry loops — plugin/hooks/hooks.json:27, 32, 43 — remove the 20-iteration curl retry loops. ensureWorkerRunning() does the one check.
2. executeWithWorkerFallback(url, method, body) helper — consolidate the 8-handler copy of ensureWorkerRunning → workerHttpRequest → if (!ok) return { continue: true }. Move to src/shared/worker-utils.ts as a new export.
3. Blocking /api/session/end endpoint — server-side wait-for-summaryStoredEvent (emitted by 03-ingestion-path Phase 2). Single POST, single response. Delete src/cli/handlers/summarize.ts:117-150 polling loop.
4. Cache settings once per hook process — module-scope loadFromFileOnce() replaces per-handler SettingsDefaultsManager.loadFromFile(USER_SETTINGS_PATH) calls at context.ts:36, session-init.ts:57, observation.ts:58, file-context.ts:211.
5. shouldTrackProject(cwd) helper — consolidate the three duplicated isProjectExcluded(cwd, settings.CLAUDE_MEM_EXCLUDED_PROJECTS) call sites.
6. cwd validation at adapter boundary — move from file-edit.ts:50-51, observation.ts:53-54 to the adapter's normalizeInput() function. Validation happens once.
7. Always-init agent — delete conditional in session-init.ts:120-129. Agent init is idempotent.
8. Fail-loud after N consecutive failures — track consecutive ensureWorkerRunning == false in settings file; after N (e.g., 3), exit code 2 to surface to Claude. Reset on first success.
9. Delete cache alive heuristic duplication — single ensureWorkerAliveOnce() with module-scope cache.

Doc refs: _reference.md Part 1 §Hooks/CLI; old Plan 09 for endpoint consolidation (10 → 4).

Verification:

• grep -rn "for i in 1 2 3 4 5 6 7" plugin/hooks/hooks.json → 0
• grep -rn "SettingsDefaultsManager.loadFromFile" src/cli/handlers/ → 1 (cached location only)
• grep -rn "isProjectExcluded" src/cli/handlers/ → 1 (inside shouldTrackProject only)
• grep -rn "MAX_WAIT_FOR_SUMMARY_MS\|POLL_INTERVAL_MS" src/cli/handlers/ → 0
• Integration test: block worker port → hook exits 0 first time, exits 2 after 3 consecutive failures
• Integration test: session end hook blocks until summary stored (single POST, no polling)

Anti-pattern guards:

• Do NOT add a retry loop inside the hook (any kind).
• Do NOT add a timeout-and-exit-0 pattern.
• Do NOT keep the shell retry loops behind a feature flag.

4B. 06-api-surface.md

Task: Draft the API-surface plan: Zod middleware, delete rate limiter, delete diagnostic endpoints, cache static files, consolidate shutdown paths.

Phases inside this plan:

1. Preflight: npm install zod@^3.x.
2. validateBody middleware — single Express middleware using Zod safeParse. Returns 400 with field errors on failure.
3. Per-route Zod schemas — one per POST/PUT endpoint, defined at top of route file.
4. Delete hand-rolled validation — grep-and-delete validateRequired, inline typeof checks, coerce helpers across route files.
5. Delete rate limiter — worker is localhost-only; rate limiting is a second-system effect masking a real concurrency bug (if one exists, find it).
6. Cache viewer.html + /api/instructions — load at boot into Buffer, serve from memory. Per-process lifecycle.
7. Delete diagnostic endpoints — /api/pending-queue GET, /api/pending-queue/process, /api/pending-queue/failed DELETE, /api/pending-queue/all DELETE at DataRoutes.ts:475, 510, 529, 548. Keep /api/processing-status at :305 and /health at ViewerRoutes.ts:32.
8. Consolidate shutdown paths — delete WorkerService.shutdown, runShutdownCascade, stopSupervisor wrappers. Single performGracefulShutdown at GracefulShutdown.ts:52-86 is the only shutdown path.
9. Consolidate failure-marking paths — delete markSessionMessagesFailed at SessionRoutes.ts:256 and markAllSessionMessagesAbandoned at worker-service.ts:943. Single transitionMessagesTo(status) method on PendingMessageStore.

Doc refs: _reference.md Part 1 §API surface; old Plan 11 for Zod strategy.

Verification:

• grep -rn "validateRequired\|rateLimit" src/services/worker/http/ → 0
• grep -rn "/api/pending-queue" src/ → 0
• grep -rn "markSessionMessagesFailed\|markAllSessionMessagesAbandoned" src/ → 0 (or 1, only inside transitionMessagesTo)
• grep -rn "WorkerService.prototype.shutdown\|runShutdownCascade\|stopSupervisor" src/ → 0 (or 1 at the canonical call site)
• Integration test: POST /api/observations with malformed body → 400 with field errors (not 500)
• Integration test: viewer.html served from memory (no disk read after boot)

Anti-pattern guards:

• Do NOT add per-route middleware stacks; one middleware for all validated POST/PUT.
• Do NOT add a diagnostic endpoint "for debugging only."
• Do NOT keep a shutdown wrapper "for backward compat."

---

Phase 5 — Write 07-dead-code.md

Task: Draft the sweep plan that catches everything the other plans don't explicitly delete.

Scope:

• TranscriptParser class at src/utils/transcript-parser.ts:28-90 (no active importers)
• Migration 19 no-op at src/services/sqlite/migrations/runner.ts:621-628 (absorbed into fresh schema)
• @deprecated getExistingChromaIds (noted in 04-read-path but deleted here if missed)
• Any // removed or // old or // legacy commented-out blocks
• Any unused exports (grep for exports never imported)
• Any bun-resolver.ts, bun-path.ts, BranchManager.ts, runtime.ts spawn sites that are unused
• Migration logic duplicated in SessionStore.ts:52-70 (delegates to MigrationRunner)

Phases:

1. Run ts-prune or knip to identify unused exports.
2. Grep for commented-out code patterns.
3. Delete identified dead code with rationale in the commit message.
4. Re-run build + tests to verify no accidental removal.

Doc refs: _reference.md Part 1 §Data layer (SessionStore duplication), §Ingestion (TranscriptParser).

Verification:

• npx ts-prune or equivalent shows zero unused exports in src/
• Build passes
• Test suite passes
• grep -rn "// @deprecated\|// TODO remove\|// old\|// legacy" src/ → 0

Anti-pattern guards:

• Do NOT delete anything still imported by a test.
• Do NOT delete types still referenced by exported interfaces.

---

Phase 6 — Write 98-execution-order.md + 99-verification.md

6A. 98-execution-order.md

Task: Produce the dependency DAG, preflight gates, critical path, parallel branches, and blocking issues.

Contents:

1. DAG: 00 is the root (no deps). 01 + 02 are foundational. 03 depends on 01 (UNIQUE constraint) + 02 (process groups implied in spawn refactor). 04 depends on 01 (Chroma table shape). 05 depends on 02 (lazy-spawn), 03 (summaryStoredEvent). 06 depends on 05 (Zod schemas for hook endpoints). 07 runs last (sweep after everything else deletes its code). 99 runs alongside each plan (acceptance checks).
2. Preflight gates:
   • engines.node >= 20.0.0 bump
   • npm install zod@^3.x
   • Prompt-caching cost smoke test (for 04 knowledge-corpus phases)
   • Chroma MCP availability + error-text pattern documented
3. Critical path: 00 → 01 → 02 → 03 → 05 → 06 → 07 (seven sequential plans).
4. Parallel branches: 04 runs after 01 independently of 02. 07 runs after everything.
5. Blocking issues: carried forward from old 08-reconciliation.md Part 5.
6. Post-landing verification: grep chains from every plan's verification section.

Doc refs: _mapping.md Cross-plan coupling table; old 07-master-plan.md + 08-reconciliation.md.

6B. 99-verification.md

Task: The acceptance-criteria document for the whole refactor.

Contents:

1. Timer census: 3 → 0 repeating background timers.
2. Polling loops: 1 → 0.
3. Full grep target list: consolidated from every plan's verification section, grouped by pattern:
   • grep -rn "setInterval" src/services/worker/ → 0
   • grep -rn "coerceObservationToSummary\|consecutiveSummaryFailures" src/ → 0
   • grep -rn "recoverStuckProcessing\|killSystemOrphans\|reapStaleSessions\|reapOrphanedProcesses\|killIdleDaemonChildren" src/ → 0
   • grep -rn "ProcessRegistry" src/services/worker/ → 0
   • grep -rn "/api/pending-queue" src/ → 0
   • grep -rn "DEDUP_WINDOW_MS\|findDuplicateObservation" src/ → 0
   • grep -rn "abandonedTimer\|evictIdlestSession" src/ → 0
   • grep -rn "fallbackAgent\|Gemini\|OpenRouter" src/services/worker/ → 0
4. Prompt-caching cost smoke test: three sequential /api/corpus/:name/query calls assert cache_read_input_tokens > 0 on calls 2 and 3.
5. Viewer regression harness: 12 invariants (I1–I12), 11 tests (T1–T11), baseline capture + re-run schedule.
6. Integration tests (consolidated from per-plan verification):
   • Kill worker mid-claim → next worker picks up the row
   • SIGTERM worker → all SDK children exit within 6s (process-group teardown)
   • Chroma down → search returns 503 (no silent fallback)
   • Malformed POST → 400 with field errors (Zod)
   • Consecutive hook failures → exit 2 after N
7. Acceptance criteria — final net lines, full test pass, viewer regression pass, cost smoke pass.

Doc refs: Every other plan's verification section.

Verification:

• Every grep target is sourced from at least one plan
• Every integration test has a corresponding plan that introduces the behavior
• Viewer lockdown section cites tests/viewer-lockdown/ artifacts

---

Phase 7 — Principle cross-check

Task: Before the new corpus ships, verify each new plan passes its own principles. Run as a meta-review.

Checks:

1. grep -rn "recover\|reap\|heal\|repair\|orphan\|coerce\|fallback" PATHFINDER-2026-04-22/*.md — every hit must be in a "DELETE" or "NEVER add" context, never as an acceptable future pattern.
2. grep -rn "setInterval\|setTimeout" PATHFINDER-2026-04-22/*.md — every hit must be either a deletion target or a narrowly-justified per-operation timer.
3. grep -rn "strategy\|factory\|builder" PATHFINDER-2026-04-22/*.md — every hit must justify why a config object won't do.
4. grep -rn "for backward compat\|for one release\|@deprecated" PATHFINDER-2026-04-22/*.md — must be 0.
5. Verify every plan cites _reference.md Part 1 for its code anchors and Part 2 for its external APIs.
6. Verify _mapping.md accounts for every old section (no orphans).
7. Verify 98-execution-order.md DAG is acyclic and covers all plans.

Deliverable: A short _principle-crosscheck.md in the new corpus directory logging the results. If ANY check fails, the corresponding plan gets sent back for revision before ship.

---

Execution instructions

Each phase (1 through 7) can be executed in a fresh chat context. To execute phase N:

1. Open a new chat
2. Load PATHFINDER-2026-04-22/_reference.md and _mapping.md and this file
3. Scroll to "Phase N" and execute its tasks verbatim
4. Commit each new plan file as it's produced (git add PATHFINDER-2026-04-22/<plan>.md)
5. Run the verification checklist; if any check fails, revise the plan before moving on

Total estimated effort: 4 engineer-days for Phases 1–6 (plan authoring), 2 engineer-days for Phase 7 (cross-check + revisions), then the plans themselves execute the refactor over ~3 weeks.

---

Confidence + known gaps

Confidence: HIGH. Phase 0 agents verified every anchor against live code. The principle list is derived from five independent audits that independently converged on the same diagnosis. The DAG is internally consistent (every new plan has exactly one owner for each cross-plan invariant — see _mapping.md coupling table).

Known gaps:

1. Chroma upsert fallback is brittle — document the error-text pattern in 01-data-integrity.md §Chroma, gate behind a flag.
2. Prompt-caching TTL assumption — cost smoke test must pass before 04-read-path knowledge-corpus phases ship.
3. Windows process-group behavior — process.kill(-pgid) is Unix-only; document Windows Job Objects as a gap-to-fix in 02-process-lifecycle.md.
4. respawn dep decision — 02-process-lifecycle.md must decide: adopt respawn or hand-roll a 3-attempt retry in the lazy-spawn wrapper.
5. Snapshot tests for renderer collapse — 04-read-path.md §Phase 1 must freeze byte-equality snapshots BEFORE deleting the four formatters, otherwise regressions are undetectable.

---

Status: READY FOR PHASE 1. Next action: open a fresh chat, load this file + _reference.md + _mapping.md, execute Phase 1 to produce 00-principles.md.