[codex] Phase 12 closeout and v0.3.2 release prep (#157)

* Phase 12 closeout and v0.3.2 release prep

* Track control-doc truth gate files

---------

Co-authored-by: Sami Rusani <sr@samirusani>

Author: samrusani

.ai/active/SPRINT_PACKET.md

@@ -0,0 +1,93 @@
+# Sprint Packet
+
+## Sprint Title
+Phase 12 Closeout and `v0.3.2` Release Update
+
+## Activation Note
+- This packet is active.
+- `v0.2.0` is the latest published tag.
+- `v0.3.2` is the current release target for the completed Phase 12 boundary.
+- Phase 12 implementation scope is complete through `P12-S1` to `P12-S5`.
+
+## Sprint Type
+closeout
+
+## Sprint Reason
+Phase 12 implementation is complete. The remaining work is not another product sprint. It is closeout:
+- summarize the completed phase clearly
+- align canonical docs to Phase 12 completion
+- update release docs from the old `v0.2.0` boundary to the new `v0.3.2` target
+- prepare the repo for either a `v0.3.2` tag or next-phase planning
+
+## Git Instructions
+- Branch Name: `codex/phase12-closeout-v0-3-2`
+- Base Branch: `main`
+- PR Strategy: one docs/control branch, one PR
+- Merge Policy: squash merge after review `PASS` and explicit approval
+
+## Baseline To Preserve
+- shipped Phase 9 through Phase 11 baseline
+- shipped Bridge `B1` through `B4`
+- shipped Phase 12 `P12-S1` through `P12-S5`
+- current published tag remains `v0.2.0` until a new tag is cut
+
+## Exact Goal
+Close Phase 12 cleanly and move the documented release boundary to `v0.3.2` without falsely claiming that the `v0.3.2` tag has already been cut.
+
+## In Scope
+- Phase 12 closeout packet
+- Phase 12 closeout summary
+- current-state and roadmap alignment for completed Phase 12
+- `v0.3.2` release checklist, tag plan, and runbook
+- README and public-doc release-boundary updates
+- changelog update for completed Phase 12
+
+## Out Of Scope
+- new product or runtime features
+- reopening any Phase 12 implementation sprint
+- tagging or publishing `v0.3.2` without explicit approval
+- defining the next phase in detail
+
+## Proposed Files And Modules
+- `README.md`
+- `CHANGELOG.md`
+- `PRODUCT_BRIEF.md`
+- `ARCHITECTURE.md`
+- `ROADMAP.md`
+- `RULES.md`
+- `CURRENT_STATE.md`
+- `.ai/handoff/CURRENT_STATE.md`
+- `.ai/active/SPRINT_PACKET.md`
+- `docs/runbooks/phase12-closeout-packet.md`
+- `docs/phase12-closeout-summary.md`
+- `docs/release/v0.3.2-release-checklist.md`
+- `docs/release/v0.3.2-tag-plan.md`
+- `docs/runbooks/v0.3.2-public-release-runbook.md`
+- public docs that still hard-code the old `v0.2.0` release boundary
+- `scripts/check_control_doc_truth.py`
+
+## Planned Deliverables
+- Phase 12 closeout packet
+- Phase 12 closeout summary
+- `v0.3.2` release-target docs
+- canonical doc alignment to completed Phase 12
+- updated release-boundary references in public docs
+
+## Acceptance Criteria
+- Phase 12 is described as complete in canonical docs
+- The documented release target is `v0.3.2`
+- the docs do not falsely claim that `v0.3.2` is already tagged or published
+- closeout docs summarize what shipped in `P12-S1` through `P12-S5`
+- control-doc truth passes after the closeout update
+
+## Required Verification
+- `python3 scripts/check_control_doc_truth.py`
+- `./.venv/bin/python -m pytest tests/unit/test_control_doc_truth.py -q`
+
+## Control Tower Decisions Needed
+- whether to tag and publish `v0.3.2` immediately after closeout
+- whether to run a dedicated release-readiness pass before the `v0.3.2` tag
+- what the next planned phase is after Phase 12
+
+## Exit Condition
+This closeout packet is complete when Phase 12 is summarized cleanly, canonical docs reflect completed Phase 12 truth, and the documented release target is updated to `v0.3.2` without claiming a tag that has not yet been cut.

.ai/handoff/CURRENT_STATE.md

@@ -5,31 +5,32 @@
 - Phase 10 is shipped.
 - Phase 11 is shipped.
 - Bridge `B1` through `B4` are shipped.
-- `v0.2.0` is released.
+- `v0.2.0` is the latest published tag.
+- `v0.3.2` is the current release target.
 - Phase 12 Sprint 1 (`P12-S1`) is shipped.
 - Phase 12 Sprint 2 (`P12-S2`) is shipped.
 - Phase 12 Sprint 3 (`P12-S3`) is shipped.
 - Phase 12 Sprint 4 (`P12-S4`) is shipped.
-- Phase 12 Sprint 5 (`P12-S5`) is the active execution sprint.
+- Phase 12 Sprint 5 (`P12-S5`) is shipped.
+- Phase 12 closeout and `v0.3.2` release update are the active control packet.
 
 ## Current Baseline Truth
 - Alice has typed memory, provenance, trust classes, correction/supersession behavior, open loops, recall, resumption, and explainability.
 - Alice exposes CLI, MCP, hosted/product, provider-runtime, and Hermes bridge surfaces.
 - The codebase already includes semantic retrieval, embeddings, entities/entity edges, trusted-fact promotion, retrieval evaluation fixtures, deterministic resumption briefs, daily briefs, chief-of-staff briefing flows, and the shipped `P12-S1` hybrid retrieval/reranking foundation with retrieval traces.
-- The codebase also includes the shipped `P12-S2` memory mutation candidate and operation foundation, the shipped `P12-S3` contradiction/trust foundation, and the shipped `P12-S4` public eval harness.
-
-## Not Yet First-Class In Repo
+- The codebase also includes the shipped `P12-S2` memory mutation candidate and operation foundation, the shipped `P12-S3` contradiction/trust foundation, the shipped `P12-S4` public eval harness, and the shipped `P12-S5` task-adaptive briefing layer.
 
 ## Phase Transition Note
-- Phase 12 is active.
+- Phase 12 is complete.
 - `P12-S1` is complete and establishes the retrieval baseline.
 - `P12-S2` is complete and establishes the mutation baseline.
 - `P12-S3` is complete and establishes the contradiction/trust baseline.
 - `P12-S4` is complete and establishes the public-eval baseline.
-- `P12-S5` is the active sprint and should build briefing behavior on top of shipped retrieval, mutation, contradiction, and eval baselines without reopening those systems.
-- The current `P12-S5` branch implements task-adaptive brief generation, comparison, and model-pack briefing defaults, pending Control Tower merge approval.
+- `P12-S5` is complete and establishes the task-adaptive briefing baseline.
+- The active docs task is phase closeout, summary, and `v0.3.2` release-target alignment.
+- There are no remaining Phase 12 feature sprints.
 
 ## Immediate Control Tower Decisions Needed
-- Decide briefing modes and payload schema for user recall, resume, worker subtask, and agent handoff.
-- Decide provider/model-pack fields for briefing strategy and max brief tokens.
-- Decide whether `P12-S5` needs CLI-only, API, and MCP surfaces simultaneously or can stage them.
+- Decide when to cut the `v0.3.2` tag and release.
+- Decide whether a dedicated release-readiness pass is needed before the tag.
+- Decide the next planned phase after Phase 12 closeout.

.gitignore

@@ -10,14 +10,23 @@ apps/web/node_modules/
 artifacts/
 
 # Internal operating docs (keep local, exclude from public repo)
-.ai/
+.ai/*
+!.ai/active/
+!.ai/handoff/
+.ai/active/*
+!.ai/active/SPRINT_PACKET.md
+.ai/handoff/*
+!.ai/handoff/CURRENT_STATE.md
 BUILD_REPORT.md
 REVIEW_REPORT.md
 ARCHIVE_RECOMMENDATIONS.md
 RECOMMENDED_ADRS.md
 
 # Internal planning/process docs (keep local, exclude from public repo)
-docs/archive/planning/
+docs/archive/planning/*
+!docs/archive/planning/2026-04-08-context-compaction/
+docs/archive/planning/2026-04-08-context-compaction/*
+!docs/archive/planning/2026-04-08-context-compaction/README.md
 docs/archive/sprints/
 docs/phase5-sprint-17-20-plan.md
 docs/phase8-sprint-29-32-plan.md

ARCHITECTURE.md

@@ -2,8 +2,8 @@
 
 ## Scope Boundary
 - **Shipped baseline:** Phases 9-11 and Bridge `B1` through `B4`.
-- **Current repo execution posture:** `v0.2.0` is released; `P12-S1`, `P12-S2`, `P12-S3`, and `P12-S4` are shipped; `P12-S5` is the active sprint.
-- **Phase 12 delta:** retrieval quality, mutation explicitness, contradiction handling, public evals, and adaptive briefing.
+- **Current repo execution posture:** `v0.2.0` is the latest published tag; `v0.3.2` is the current release target; Phase 12 is complete.
+- **Active control-doc task:** Phase 12 closeout and `v0.3.2` release update.
 
 ## Current System Overview
 Alice is a modular continuity platform with shared continuity semantics across local, hosted, provider-runtime, MCP, and Hermes-integrated surfaces.
@@ -92,7 +92,7 @@ Shipped in `P12-S1`:
 - trust-aware reranking
 - persisted retrieval traces
 
-Planned additions:
+Delivered additions:
 - `retrieval_runs`
 - `retrieval_candidates`
 - debug surfaces for API, CLI, and MCP
@@ -135,13 +135,13 @@ Important baseline note: `P12-S4` is now the evaluation baseline for the rest of
 Source-of-truth note: the checked-in fixture catalog defines the authoritative suite/case set and ordering; persisted eval suite/case rows are synchronized snapshots for execution and audit, not an independent planning surface.
 
 ### P12-S5: Task-Adaptive Briefing
-Separate durable memory from output-specific briefing layers.
+Shipped in `P12-S5`:
 
-Planned additions:
+Delivered additions:
 - `task_briefs`
 - provider/model-pack briefing strategy fields
 
-Important baseline note: `P12-S5` should build on shipped retrieval, mutation, contradiction, and eval baselines. Existing resumption, daily-brief, and chief-of-staff briefing surfaces are starting points, not greenfield replacements.
+Important baseline note: `P12-S5` closes the planned Phase 12 implementation scope. Existing resumption, daily-brief, and chief-of-staff briefing surfaces remain the starting points rather than being replaced wholesale.
 
 ## Security And Reliability Rules
 - Keep user/workspace isolation intact for continuity, provider, and channel data.
@@ -169,7 +169,5 @@ Important baseline note: `P12-S5` should build on shipped retrieval, mutation, c
 - release/eval artifacts committed only when they correspond to exact commands and fixtures
 
 ## Control Tower Decisions Needed
-- Should Phase 12 retrieval ship behind a feature flag before it replaces the default recall path?
-- Should new endpoints use `/v1/retrieval/*`, `/v1/evals/*`, `/v1/briefs/*`, or extend existing continuity endpoints?
-- Should contradictions attach to continuity objects only, memories only, or both with a shared abstraction?
-- Should `DELETE` be restricted to logical deletion/tombstoning by default?
+- Whether `v0.3.2` should be tagged immediately or held until a dedicated release pass.
+- What the next planned phase is after the completed Phase 12 architecture baseline.

CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## 2026-04-14
 
+- Closed out Phase 12 after shipping all five planned sprints:
+  - `P12-S1` hybrid retrieval + reranking
+  - `P12-S2` automated memory operations
+  - `P12-S3` contradiction detection + trust calibration
+  - `P12-S4` public eval harness
+  - `P12-S5` task-adaptive briefing
+- Added Phase 12 closeout summary and closeout packet.
+- Updated the documented release target from `v0.2.0` to `v0.3.2` for the completed Phase 12 boundary.
+- Aligned Python, API, web, CLI, core-package, and Hermes plugin version metadata to `0.3.2`.
+- Added `v0.3.2` release checklist, tag plan, and public release runbook.
+- Kept the published release truth explicit: the latest published tag remains `v0.2.0` until `v0.3.2` is cut.
+
 - Prepared `R1` release-readiness package for `v0.2.0` as a pre-1.0 public release boundary.
 - Added `v0.2.0` release checklist, tag plan, and public release runbook.
 - Realigned launch-facing docs to shipped scope through Phase 11 and Bridge `B1` through `B4`.

CURRENT_STATE.md

@@ -8,31 +8,32 @@ Canonical handoff state lives at [.ai/handoff/CURRENT_STATE.md](.ai/handoff/CURR
 - Phase 10 is shipped.
 - Phase 11 is shipped.
 - Bridge `B1` through `B4` are shipped.
-- `v0.2.0` is released.
+- `v0.2.0` is the latest published tag.
+- `v0.3.2` is the current release target.
 - Phase 12 Sprint 1 (`P12-S1`) is shipped.
 - Phase 12 Sprint 2 (`P12-S2`) is shipped.
 - Phase 12 Sprint 3 (`P12-S3`) is shipped.
 - Phase 12 Sprint 4 (`P12-S4`) is shipped.
-- Phase 12 Sprint 5 (`P12-S5`) is the active execution sprint.
+- Phase 12 Sprint 5 (`P12-S5`) is shipped.
+- Phase 12 closeout and `v0.3.2` release update are the active control packet.
 
 ## Current Baseline Truth
 - Alice has typed memory, provenance, trust classes, correction/supersession behavior, open loops, recall, resumption, and explainability.
 - Alice exposes CLI, MCP, hosted/product, provider-runtime, and Hermes bridge surfaces.
 - The codebase already includes semantic retrieval, embeddings, entities/entity edges, trusted-fact promotion, retrieval evaluation fixtures, deterministic resumption briefs, daily briefs, chief-of-staff briefing flows, and the shipped `P12-S1` hybrid retrieval/reranking foundation with retrieval traces.
-- The codebase also includes the shipped `P12-S2` memory mutation candidate and operation foundation, the shipped `P12-S3` contradiction/trust foundation, and the shipped `P12-S4` public eval harness.
-
-## Not Yet First-Class In Repo
+- The codebase also includes the shipped `P12-S2` memory mutation candidate and operation foundation, the shipped `P12-S3` contradiction/trust foundation, the shipped `P12-S4` public eval harness, and the shipped `P12-S5` task-adaptive briefing layer.
 
 ## Phase Transition Note
-- Phase 12 is active.
+- Phase 12 is complete.
 - `P12-S1` is complete and establishes the retrieval baseline.
 - `P12-S2` is complete and establishes the mutation baseline.
 - `P12-S3` is complete and establishes the contradiction/trust baseline.
 - `P12-S4` is complete and establishes the public-eval baseline.
-- `P12-S5` is the active sprint and should build briefing behavior on top of shipped retrieval, mutation, contradiction, and eval baselines without reopening those systems.
-- The current `P12-S5` branch implements task-adaptive brief generation, comparison, and model-pack briefing defaults, pending Control Tower merge approval.
+- `P12-S5` is complete and establishes the task-adaptive briefing baseline.
+- The active docs task is phase closeout, summary, and `v0.3.2` release-target alignment.
+- There are no remaining Phase 12 feature sprints.
 
 ## Immediate Control Tower Decisions Needed
-- Decide briefing modes and payload schema for user recall, resume, worker subtask, and agent handoff.
-- Decide provider/model-pack fields for briefing strategy and max brief tokens.
-- Decide whether `P12-S5` needs CLI-only, API, and MCP surfaces simultaneously or can stage them.
+- Decide when to cut the `v0.3.2` tag and release.
+- Decide whether a dedicated release-readiness pass is needed before the tag.
+- Decide the next planned phase after Phase 12 closeout.

PRODUCT_BRIEF.md

@@ -11,15 +11,17 @@ Alice is a pre-1.0 continuity platform for AI agents and agent-assisted workflow
 
 ## Current Repo Posture
 - `v0.2.0` is tagged and released.
+- `v0.3.2` is the current release target for the completed Phase 12 boundary.
 - Release Sprint 1 (`R1`) is complete and now baseline truth.
-- Phase 12 is active.
+- Phase 12 is complete.
 - `P12-S1` Hybrid Retrieval + Reranking is shipped.
 - `P12-S2` Automated Memory Operations is shipped.
 - `P12-S3` Contradiction Detection + Trust Calibration is shipped.
 - `P12-S4` Public Eval Harness is shipped.
-- `P12-S5` Task-Adaptive Briefing is the active sprint.
+- `P12-S5` Task-Adaptive Briefing is shipped.
+- Phase 12 closeout and `v0.3.2` release update are the active control-doc task.
 
-## Next Phase
+## Completed Phase
 ### Phase 12: Retrieval Quality + Adaptive Continuity
 Raise Alice from a strong continuity substrate to a measurably better memory system by improving:
 - retrieval precision
@@ -61,5 +63,5 @@ Alice already has durable memory, provenance, trust classes, revision/supersessi
 - Worker-task briefs are smaller and sharper than generic recall context without degrading resumption quality.
 
 ## Control Tower Decisions Needed
-- Whether new Phase 12 APIs should live under new `/v1` feature namespaces or extend the existing continuity surface.
-- Whether `DELETE` in memory operations means hard delete, logical tombstone, or a restricted administrative path.
+- When to cut and publish the `v0.3.2` tag/release.
+- What the next planned phase is after Phase 12 closeout.

README.md

@@ -15,7 +15,7 @@ durable memory for agents, agent resumption, open loop tracking, local-first ai
 
 Alice helps agents **remember what matters, resume interrupted work, explain why something is true, and improve when corrected**.
 
-`v0.2.0` is a **pre-1.0 public release**. It packages shipped baseline scope through Phase 11 and Bridge `B1` through `B4` without claiming `v1.0.0` stability guarantees.
+`v0.3.2` is the current **pre-1.0 release target** for the completed Phase 12 boundary. The latest published tag remains `v0.2.0` until the `v0.3.2` release is cut.
 
 Most assistants are still good only in the moment. They can answer the current prompt, but they struggle to preserve decisions, track open loops, recover context across sessions, and stay aligned after memory corrections.
 
@@ -27,14 +27,20 @@ It provides a **local-first memory and continuity engine** for capture, recall,
 
 **Works across local, self-hosted, enterprise, and external-agent workflows via CLI, MCP, provider runtime, OpenClaw import, and Hermes integration.**
 
-## Release Boundary (`v0.2.0`)
+## Release Boundary (`v0.3.2` Target)
 
-Shipped baseline included in this pre-1.0 release:
+Completed baseline included in this pre-1.0 release target:
 
 - Phase 9 continuity core and deterministic local CLI/MCP/importer seams
 - Phase 10 hosted/product layer
 - Phase 11 provider runtime, adapters, and model packs
 - Bridge `B1` through `B4` provider contract, auto-capture flow, review/explainability flow, and bridge docs/smoke validation
+- Phase 12 retrieval quality stack:
+  - hybrid retrieval and reranking
+  - explicit memory mutation operations
+  - contradiction detection and trust calibration
+  - public eval harness and baseline reports
+  - task-adaptive briefing
 
 Historical planning/control artifacts remain available in:
 [docs/archive/planning/2026-04-08-context-compaction/README.md](docs/archive/planning/2026-04-08-context-compaction/README.md)
@@ -136,6 +142,11 @@ The current open-source surface includes:
 - scheduled archive maintenance, ops status reporting, and failure alerting
 - Hermes bridge with provider lifecycle hooks, always-on continuity prefetch, turn auto-capture, policy-based commit modes (`manual` / `assist` / `auto`), and reviewable explainable candidate memory flows
 - provider runtime abstraction with workspace-scoped provider registration, capability snapshots, OpenAI-compatible base adapter, local Ollama/llama.cpp, self-hosted vLLM, enterprise Azure, model packs, and external-agent integration paths
+- hybrid retrieval with persisted retrieval traces and debug visibility
+- explicit memory mutation operations with auditability and idempotent replay behavior
+- contradiction detection, contradiction-aware ranking penalties, and trust-signal inspection
+- public eval harness with fixture catalog and checked-in baseline report support
+- task-adaptive briefing for user recall, resume, worker subtask, and agent handoff
 - importers for OpenClaw, Markdown, and ChatGPT exports
 - OpenClaw adapter and demo path
 - evaluation harness and integration docs
@@ -301,15 +312,16 @@ That means the system behaves consistently across local workflows, MCP-connected
 
 ## Scope Notes
 
-Included in `v0.2.0`:
+Included in the `v0.3.2` target:
 
 - local-first continuity core
 - CLI and MCP surfaces
 - importer paths (OpenClaw, Markdown, ChatGPT exports)
 - provider runtime and model-pack support from Phase 11
 - Hermes provider-plus-MCP bridge path with MCP-only fallback
+- Phase 12 retrieval, mutation, contradiction/trust, public eval, and task-adaptive briefing surfaces
 
-Deferred beyond `v0.2.0`:
+Deferred beyond `v0.3.2`:
 
 - `v1.0.0` compatibility/support guarantees
 - managed cloud/SLA commitments