CA-S430 — Workflow-Continuity Repair: Implementation Plan

Implementation Plan: CA-S430 Workflow-Continuity Repair

Overview

Repair the cross-session dev-workflow continuity breakdown: settled context (completed work, settled decisions, closed audits, durable facts) is written at close but never read at start, so the next session re-flags done work, re-implements existing functionality, and re-derives stale facts. This plan covers the remaining structural implementation after the s430 investigation + the quick wins already landed. It is sized for one focused implementation session (cmux O-of-O or worktree-Agent dispatch).

Source investigation: 18-agent fan-out + adversarial cross-critique (full results in the s430 session). Prose plan: scratchpad/ca-s430-continuity-repair-plan.md. Owner steers (s430) are folded into the architecture decisions below.

Already landed in s430 (do NOT re-plan — banked context)

Item	Commit
CLAUDE.md DB-topology + staging-host fix (re-land bl-390)	canonical 8974007e
reference/platform-context.md load-anchor + CLAUDE.md pointer	docs-site edf056a0 / canonical 9ef29c3d
s429 platform-prompt update (id-135 reuse-revisit + parallel-session coordination)	docs-site edf056a0
Registry dedup ε — deregistered the stale /procurement canonical index (worktree untouched; backup ~/.gitnexus/registry.json.bak-s430)	(global config)
list subcommand α — read-only list <ledger> (task snapshot + filters)	canonical ea68fff5 (22/22 tests; on the branch, in PR #107)
MemPalace CLI version-skew fix (C6) — pinned CLI to 3.5.0 to match the plugin; SessionEnd final-mine repaired	(global uv tool)
Branch pushed + PR #107 opened to main (audit-skill + s430 quick wins)	canonical chore/audit-skill-drift-sweep

Landed / decided in S431 (decision-register pivot)

Item	Where
Decision Register adopted (replaces per-prompt “Explicitly settled” sections) — durable read-at-start store for settled rulings; the ADR-half of the Pocock domain-modeling pattern, glossary-half skipped	docs-site reference/decision-register.md (DR-001–008 seeded from this PLAN + the s431 prompt)
MemPalace repaired — FTS5 inverted-index rebuild cleared the malformed inverted index integrity failure (CLI repair aborts pre-fix, upstream #1606); backup chroma.sqlite3.bak-20260630-pre-fts-rebuild	local ~/.mempalace/palace
MemPalace chronic-drift root cause confirmed — chromadb Rust HNSW thread-safety bug under concurrent mempalace-mcp writers → DR-009 + durable-fix backlog (Task λ)	upstream MemPalace/mempalace

Architecture decisions (deconflict + owner steers)

• ONE list subcommand serves both the owner’s task-snapshot need AND the reconciliation sweep + retro read-back (was A1/D1/D2 in three areas → merged; built in α).
• ONE start-session edit (Task β): five would-be edits (recall, reconciliation, retro read-back, state-of-product, worktree-prune) collapse into one coherent Step-2 revision. Edit start-session via /update-skill (owner constraint), not raw Edit.
• Reconciliation uses done-status as a don’t-re-flag signal ONLY — done-task details carry stale context that has repeatedly caused issues; never import done-task detail as current truth. Archived done-tasks are CLI-invisible (moved out of task-list.json); non-archived done-tasks are visible but stale.
• MemPalace recall must use lock-free read-only sqlite (WAL) against chroma.sqlite3 — a live MCP-server query at SessionStart is locked out (ChromaDB single-writer; proven).
• Reuse-framing (Area F) is NOT a skill/agent edit — “HARD RULE” was self-declared inside the id-135 spec chain only (0× in any skill/agent). Sole action already taken: the s429 prompt carries an id-135 reuse-revisit item. Do not edit shared-discipline/spec skills.
• friction-register does NOT duplicate retro read-back (different content/repo/lane) — the Step-2g retro read-back is non-duplicative.
• state-of-the-product.md is stale/unused — do not wire it load-side; platform-context.md is the load anchor.
• Settled decisions get a durable read-at-start home (the Decision Register), NOT a per-prompt section. The continuation prompt cites only NEW DR-IDs each session; the register (reference/decision-register.md) is read at start (β) and consulted by task-planner / workflow-orchestration (δ′). This completes the read/write symmetry — retros, MemPalace, ledger, and now decisions are all written-at-close AND read-at-start.

Task list

Phase 1: Foundation (CLI + context wiring)

Task α (LANDED/in-flight): list subcommand — see banked context above.

Task β: start-session Step-2 consolidation

Description: Add a single coherent reconciliation + recall block to start-session Step 2 so a session loads settled state before planning. Author via /update-skill. Acceptance criteria:

• Step 2a upgraded: branch/task-seeded unfiltered mempalace_search + mempalace_kg_query (reference the mempalace-recall skill; do NOT re-spell the #1665 workaround — it is already in CLAUDE.md).
• New Step 2f reconciliation sweep (prompt-independent): list task --status done --since <lastSessionDate> (don’t-re-flag signal — NOT trusted context) + list task --status in_progress sweep, cross-checked against prompt-named ids.
• New Step 2g retro read-back: list retro --recent 3 (track-seeded) → surface unresolved_questions + workflow_improvements + failed_assumptions. Do NOT present workflow_improvements as “ratified/in force” (they are observations).
• Load-side pointer to reference/platform-context.md.
• New DR read-step: surface in-force (accepted, non-superseded) entries from reference/decision-register.md (the settled-rulings guardrail; sits beside the retro read-back). Do NOT dump the whole file. Verification:
• /update-skill used (skill frontmatter/structure intact; no drift introduced).
• Dry-run the new commands resolve against the live ledger. Dependencies: α. Files: .claude/skills/start-session/SKILL.md. Scope: M.

Checkpoint: Foundation

• list works (snapshot + filters); start-session loads reconciliation + retro + platform-context. Review with owner.

Phase 2: Recall + handoff (file-disjoint → parallel-safe)

Task γ: MemPalace read-side recall + version-skew fix

Description: Close the write-only loop on MemPalace (the owner’s stated best recall tool). Acceptance criteria:

• SessionStart recall hook in project .claude/settings.json + new .claude/hooks/mempal-recall.sh: lock-free read-only sqlite (mode=ro, WAL) FTS query against chroma.sqlite3, seeded by branch + cwd basename + active task id, injected as additionalContext. Matcher startup|clear (NOT resume). Size-capped (~1.8KB). Graceful no-op when DB absent/locked.
• Filter diary checkpoint-noise rows (room=diary auto-checkpoints) — surface narrative, not CHECKPOINT:... dumps.
• CLAUDE.md “Always Do — Proactive Recall” directive (mirror the GitNexus MUST block; reference mempalace-recall, don’t triplicate the #1665 note).
• C6 version-skew fix — DONE in s430: CLI pinned to 3.5.0 (uv tool install 'mempalace==3.5.0' --force); the 3.5.0 plugin wrapper passes --hook session-end --harness claude-code (matches the CLI contract). Verify next session that the SessionEnd mine actually writes end-to-end. Verification:
• Hook fires on a fresh session start; injects a bounded digest; no-ops cleanly when the server holds the lock (read-only WAL read proven to work concurrently).
• mempalace hook run --hook session-end no longer errors post-upgrade. Dependencies: None (file-disjoint from β). Files: .claude/settings.json, .claude/hooks/mempal-recall.sh, CLAUDE.md. Scope: M.

⚠ KNOWN BUG in the s430 draft hook: paste -sd' OR ' does NOT join with ” OR ” (cyclic single-char delimiters) — build the FTS query string explicitly. Seed must include cwd basename + task id, not just $BRANCH.

Task δ: handoff Completed-section + DR-write + close-report generator

Description: Stop the deltas-only continuation prompt from silently dropping done-work and settled decisions — done-work stays an in-prompt section; settled decisions move to the Decision Register (durable, read-at-start). Acceptance criteria:

• handoff/SKILL.md Step-3 inline template (lines ~56-100 — the real template; NOT the IMS continuation-prompt-template.md) gains a mandatory “Completed this session (Tasks + SHAs)” section (ids + merge/PR SHA only; honour “never reproduce the ledger”).
• The old “Explicitly settled / won’t-fix” content becomes a DR-write: at close, append new settled rulings as DR-NNN entries to reference/decision-register.md; the continuation prompt then cites only the NEW DR-IDs this session (delta pointer), not the full settled list.
• New scripts/session-close-report.sh emits the mechanically-derivable state (orphaned worktrees via git worktree list, branch/SHA, open-PR/CI via gh-axi, stale-index status) → a ”## Mechanical state (auto-generated)” section.
• handoff references the generator (Step ~3.5). Verification:
• Running the generator on the current repo lists the live orphaned worktrees + branch state.
• handoff template renders the new sections. Dependencies: None (file-disjoint). Files: .claude/skills/handoff/SKILL.md, scripts/session-close-report.sh, reference/decision-register.md. Scope: M. Edit via /update-skill; /audit-skill after.

Task δ′: Decision-Register wiring across the SDLC skills

Description: Make the register actually prevent re-litigation by reading/writing it at the moments decisions get re-proposed — not just at session start. Acceptance criteria:

• Spec-authoring (write-product-spec / write-tech-spec / planning-and-task-breakdown + the task-planner agent): consult the register before authoring RESEARCH/PRODUCT/TECH (don’t re-propose settled things); emit a DR-intent when research yields a binding ruling.
• workflow-orchestration: surface relevant in-force DRs when composing subtask briefs; DR-write routing — workers return DR-intents, the Orchestrator writes on main (mirrors “workers never write the ledger in-branch”).
• workflow-curator / triage-finding: add DR as a 5th disposition (beside subtask / roadmap / backlog / no-action) for findings that are settled won’t-fix rulings.
• Register the cross-refs in reference/skill-interaction-matrix.md + reference/skill-routing-map.md. Verification:
• Each edited skill’s frontmatter/structure intact; /audit-skill clean on each. Dependencies: δ (register write-path exists). Files: the spec-authoring skills + task-planner agent, workflow-orchestration, triage-finding, reference/skill-interaction-matrix.md, reference/skill-routing-map.md. Scope: M. Edit via /update-skill; /audit-skill after each.

Checkpoint: Recall + handoff

• Recall hook + version-skew fixed; handoff carries Completed/Settled + mechanical state. Review with owner.

Phase 3: Deferred / decision-gated

• Task ζ — worktree-orphan cleanup (7 live agent-* worktrees, carried s423→s429). RISKY: cherry-picked SHAs → merged-branch detection misses them; verify each is fully landed (patch-id/git cherry) BEFORE git worktree remove --force. Scope S, risk M. Needs sandbox-off.
• Task η0 — *_PROJECT_REF env-var usage audit (PRECEDES the runbook refresh) — PLATFORM_PROJECT_REF / STAGING_PROJECT_REF / PROD_PROJECT_REF were introduced to replace hardcoded client-DB refs across the codebase/scripts when only ONE Platform DB existed (the origin of the old “acting as prod & staging” wording). When Platform staging was added, only .env.local’s PLATFORM_PROJECT_REF was repointed (→ rbwqew). The naming is now confusing/error-prone: STAGING_PROJECT_REF=client-staging (turayk), PROD_PROJECT_REF=client-prod (rovrym), PLATFORM_PROJECT_REF=Platform-staging (rbwqew). Grep every usage of these three vars across scripts/, lib/, CI workflows, and docs; confirm each call site targets the correct DB for its context; fix mis-uses. Do this BEFORE the runbook refresh to avoid documenting incorrect context. Scope M, owner-flagged.
• Task η — local-development.md runbook refresh (AFTER η0) — its default-DB section is stale: it shows local SUPABASE_URL=rovrym (client-prod) but the local-dev default is Platform staging rbwqew (owner-confirmed). Refresh once η0 has clarified the ref semantics; also flag github-environments.md §8 (superseded) + ci.md (Jun 10). Scope S.
• Task θ — wiki decision (DECIDED s430) — the cocoindex self-updating wiki is NOT the fix for “what’s getting missed”: that is decision/context continuity (addressed by platform-context.md + retro read-back + MemPalace recall), NOT code-structure. Agents already get live structure from gitnexus/ccc/ast-dataflow. Action: retire the static gitnexus gist (manual/stale/low-value, wired into nothing). The cocoindex self-updating wiki is an optional human-browse/onboarding aid only — defer; do not build it expecting it to fix continuity. Owner rotates the OpenRouter key (repo is public → the gist is not a leak). Also land E2 (a CLAUDE.md advisory: don’t index linked worktrees) so the registry collision ε fixed doesn’t recur.
• Task ι — skills — ADAPT cross-critique as a workflow-orchestration “contested-decision” subsection (the one deliberation skill); ADAPT deprecation-and-migration (opt-in, active-migration-gated). SKIP the rest (check-impl-against-spec → task-checker already covers; council/research/handoff-pocock → backport small assets). Scope S each.
• Task κ — gitnexus analyze guard (E2) — refuse to index a linked worktree (prevents the registry-collision recurrence ε just fixed). Add a CLAUDE.md advisory bullet (covers all analyze entry points, unlike a single-entry code guard). Scope S.
• Task λ — MemPalace durable concurrency fix (NEW S431) — the daily HNSW drift is an upstream chromadb Rust thread-safety bug under concurrent mempalace-mcp writers. Adopt a single-writer posture (opt-in daemon, or the SSE/HTTP transport #1646) so multi-session use stops corrupting the index; author a runbooks/mempalace-repair.md (FTS5-rebuild recipe for malformed inverted index; note CLI repair aborts pre-fix per #1606). DR-009 records the interim single-writer/read-only ruling. Backlog-tracked. Scope M.

Risks and mitigations

Risk	Impact	Mitigation
start-session edited by multiple concerns → drift/churn	Med	One coordinated β edit via /update-skill; no parallel start-session edits
MemPalace recall hook runs every session start	Med	Read-only WAL (no write risk, proven); strict size cap; graceful no-op; matcher `startup
Worktree cleanup removes un-landed work	High	Verify each orphan’s commits are on the track (patch-id) before removal
Reconciliation surfaces stale done-task context	Med	done-status is a don’t-re-flag signal ONLY; never import done detail as current
Parallel platform session collides on docs-site/shared files	Med	s429 prompt carries the coordination note; rebase before editing shared workflow files

Open questions (owner) — ALL RESOLVED s430

• Base branch RESOLVED: work from main next session (owner; the s429 platform track too — disjoint cmux work, low pre-launch risk). The s430 + audit work is in PR #107; merge it to main BEFORE the fresh session (it carries the list prereq + the platform-context pointer).
• Local-dev default DB RESOLVED: Platform staging rbwqew — but the real confusion is the *_PROJECT_REF naming → Task η0 audits usage before the runbook refresh.
• MemPalace upgrade DONE — CLI pinned to 3.5.0; SessionEnd mine repaired.
• Wiki RESOLVED — retire the static gist; cocoindex wiki = optional onboarding aid only, not the continuity fix (Task θ).