Sprint 5B: Project Truth Compaction 01

.ai/active/SPRINT_PACKET.md

@@ -2,122 +2,115 @@
 
 ## Sprint Title
 
-Sprint 5A: Task Workspace Records and Provisioning
+Sprint 5B: Project Truth Compaction 01
 
 ## Sprint Type
 
-feature
+refactor
 
 ## Sprint Reason
 
-Milestone 5 should start at the workspace boundary, not at document ingestion or connectors. The repo now has the task and execution substrate needed to add one deterministic, user-scoped task workspace seam without expanding product scope.
+The live project-truth files are now materially stale and redundant relative to the accepted repo state through Sprint 5A. `ROADMAP.md` and `.ai/handoff/CURRENT_STATE.md` still describe the project as pre-Milestone-5 and pre-step-linked approval/execution/workspace work, which will degrade planning and review quality if not compacted now.
 
 ## Sprint Intent
 
-Begin Milestone 5 by adding user-scoped task workspace records plus deterministic local workspace provisioning, so later artifact handling, document ingestion, and read-only connectors have a governed workspace boundary to build on.
+Compact and synchronize the live project-truth files so Control Tower, builders, and reviewers operate from a smaller, current, non-redundant source-of-truth set without changing product scope or runtime behavior.
 
 ## Git Instructions
 
-- Branch Name: `codex/sprint-5a-task-workspaces`
+- Branch Name: `codex/refactor-project-truth-compaction-01`
 - Base Branch: `main`
-- PR Strategy: one sprint branch, one PR, no stacked PRs unless Control Tower explicitly opens a follow-up sprint on top of this branch
-- Merge Policy: squash merge only after reviewer `PASS`; if review fails, repair on the same branch until pass or explicit abandonment
+- PR Strategy: one sprint branch, one PR, no stacked PRs unless Control Tower explicitly opens a follow-up sprint
+- Merge Policy: squash merge only after reviewer `PASS` and explicit Control Tower merge approval
 
-## Why This Sprint
+## Why This Sprint Matters
 
-- Sprint 4S is implemented and passed: approvals and executions now both use explicit task-step linkage, so the Milestone 4 lifecycle substrate is in place.
-- The roadmap says workspace and artifact boundaries should land before document-heavy or connector-heavy flows rely on them.
-- The narrowest safe Milestone 5 entry slice is workspace provisioning only, not artifact indexing, document ingestion, or connectors.
-- This keeps sequencing boring and maintainable by establishing the workspace boundary first.
+- `ROADMAP.md` and `.ai/handoff/CURRENT_STATE.md` are behind the accepted repo state.
+- `ARCHITECTURE.md` now reflects Sprint 5A, so the other live truth artifacts need to catch up and shed stale milestone text.
+- A narrow compaction sprint is safer than letting outdated truth leak into future planning or review work.
+- This restores clean project truth without changing product scope.
 
 ## In Scope
 
-- Add schema and migration support for:
-  - `task_workspaces`
-- Define typed contracts for:
-  - workspace create responses
-  - workspace list responses
-  - workspace detail responses
-- Implement a minimal workspace seam that:
-  - provisions one deterministic local workspace path for a visible task
-  - persists one user-scoped workspace record linked to that task
-  - validates the workspace path is rooted under one configured workspace base directory
-  - prevents duplicate active workspace creation for the same task
-  - exposes deterministic list and detail reads
-- Implement the minimal API or service paths needed for:
-  - creating a workspace for a task
-  - listing workspaces
-  - reading one workspace by id
-- Add unit and integration tests for:
-  - workspace creation
-  - deterministic path generation
-  - duplicate-create rejection for the same task
-  - per-user isolation
-  - stable response shape
+- compact and synchronize `.ai/handoff/CURRENT_STATE.md`
+- compact and synchronize `ROADMAP.md`
+- prune `RULES.md` only if it contains stale or duplicate guidance after truth sync
+- slim `README.md` only if it duplicates active planning truth instead of onboarding
+- archive stale planning/history docs into `docs/archive/` when they are no longer appropriate as live context
+- update internal references so canonical files point to the right archive locations
+- update `ARCHITECTURE.md` only if a stale duplicate or outdated boundary statement remains after the Sprint 5A truth sync
 
 ## Out of Scope
 
-- No artifact inventory or artifact metadata table yet.
-- No document ingestion.
-- No chunking, embeddings, or document retrieval.
-- No Gmail or Calendar connector scope.
-- No runner-style orchestration.
-- No new proxy handlers or broader side-effect expansion.
+- new product features
+- source code changes unrelated to doc-link or archive-link integrity
+- UI improvements
+- backend refactors
+- new architecture decisions unless a current truth file is factually inaccurate
+- changing roadmap priorities beyond removing stale historical clutter
+- artifact, document, connector, or runner implementation work
 
-## Required Deliverables
+## Files / Modules In Scope
 
-- Migration for `task_workspaces`.
-- Stable workspace create/list/detail contracts.
-- Minimal deterministic task-workspace provisioning and persistence path.
-- Unit and integration coverage for provisioning, path safety, duplicate protection, and isolation.
-- Updated `BUILD_REPORT.md` with exact verification results and explicit deferred scope.
+- `.ai/handoff/CURRENT_STATE.md`
+- `ROADMAP.md`
+- `RULES.md` only if needed for stale/duplicate guidance cleanup
+- `README.md` only if needed for onboarding/truth separation
+- `docs/archive/**`
+- `ARCHITECTURE.md` only if duplicate or stale sections must be cleaned after truth sync
+
+## Constraints
+
+- do not delete information unless it is safely archived
+- preserve historical traceability
+- do not change product scope
+- do not change runtime behavior
+- keep canonical files concise, current, and durable
+- prefer archive over deletion
+- use `PRODUCT_BRIEF.md`, `ARCHITECTURE.md`, accepted build/review reports, and the implemented repo state as the truth basis
+
+## Relevant Rules
+
+- active sprint packet is the top scope boundary for implementation work
+- never represent planned architecture as implemented behavior
+- roadmap should be future-facing once historical milestone state has been distilled elsewhere
+- rules should contain only durable reusable guidance
+- when live context becomes noisy, reduce and archive instead of letting stale state accumulate
+
+## Design Source of Truth
+
+- `DESIGN_SYSTEM.md` if it is later introduced
+- otherwise N/A for this sprint
+
+## Architecture Source of Truth
+
+- `ARCHITECTURE.md`
 
 ## Acceptance Criteria
 
-- A client can provision one user-scoped workspace for a visible task.
-- Every workspace record stores a deterministic local path under the configured workspace root.
-- Duplicate active workspace creation for the same task is rejected deterministically.
-- Workspace list and detail reads are deterministic and user-scoped.
-- `./.venv/bin/python -m pytest tests/unit` passes.
-- `./.venv/bin/python -m pytest tests/integration` passes.
-- No artifact indexing, document ingestion, connector, runner, handler-expansion, or broader side-effect scope enters the sprint.
-
-## Implementation Constraints
-
-- Keep the workspace seam narrow and boring.
-- Provision only local workspace boundaries; do not invent remote storage abstractions in this sprint.
-- Keep workspace paths deterministic, explicit, and rooted under one configured base directory.
-- Reuse existing task ownership and isolation seams rather than creating a parallel authorization path.
-- Do not add artifact scanning, file sync, or document parsing in the same sprint.
-
-## Suggested Work Breakdown
-
-1. Add `task_workspaces` schema and migration.
-2. Define workspace create/list/detail contracts.
-3. Implement deterministic workspace path generation rooted under the configured base directory.
-4. Implement workspace create, list, and detail behavior with duplicate protection.
-5. Add unit and integration tests.
-6. Update `BUILD_REPORT.md` with executed verification.
-
-## Build Report Requirements
-
-`BUILD_REPORT.md` must include:
-- the exact workspace schema and contract changes introduced
-- the configured workspace root and path-generation rule used
-- exact commands run
-- unit and integration test results
-- one example workspace create response
-- one example workspace detail response
-- what remains intentionally deferred to later milestones
-
-## Review Focus
-
-`REVIEW_REPORT.md` should verify:
-- the sprint stayed limited to task workspace records and provisioning
-- workspace paths are deterministic, rooted safely, and user-scoped
-- duplicate protection, ordering, and isolation are test-backed
-- no hidden artifact indexing, document ingestion, connector, runner, handler-expansion, or broader side-effect scope entered the sprint
-
-## Exit Condition
-
-This sprint is complete when the repo can provision deterministic user-scoped task workspace records under a configured local workspace root, expose stable workspace reads, and verify the full path with Postgres-backed tests, while still deferring artifact handling, document ingestion, and connector work.
+- `.ai/handoff/CURRENT_STATE.md` is concise, current, and non-redundant through Sprint 5A.
+- `ROADMAP.md` no longer presents stale pre-Sprint-5 state and is future-facing from the current repo position.
+- `RULES.md` contains only durable rules and no stale scope-era leftovers.
+- Any stale planning/history material moved out of live context is archived under `docs/archive/`.
+- All archive links and references resolve correctly.
+- No product behavior, scope, or runtime code was changed.
+- Control Tower can plan from a smaller, cleaner active context set after this sprint.
+
+## Required Tests
+
+- manual review of canonical files for duplication, staleness, and truth alignment
+- link/path sanity check for moved archive files
+- confirm no runtime or schema behavior changed
+- run docs/path validation only if any existing tooling references moved files
+
+## Docs To Update
+
+- `.ai/handoff/CURRENT_STATE.md`
+- `ROADMAP.md`
+- `RULES.md` if needed
+- `README.md` if needed
+- `ARCHITECTURE.md` only if stale duplication remains
+
+## Definition of Done
+
+The live project-truth files are smaller, cleaner, and aligned to the accepted repo state through Sprint 5A; stale planning/history material is preserved in archive; and the next sprint can be planned from a trustworthy active context set.

.ai/handoff/CURRENT_STATE.md

@@ -1,53 +1,46 @@
 # Current State
 
-## What Exists Today
+## Canonical Truth
 
-- Canonical project docs now describe the shipped repo state through Sprint 4O.
-- `apps/api` implements the accepted backend seams for continuity, tracing, context compilation, governed memory, memory review, embeddings, semantic retrieval, entities, policies, tools, approvals, approved proxy execution, execution budgets, execution review, tasks, task steps, and explicit manual continuation lineage.
-- The live schema now includes continuity tables, trace tables, memory tables, embedding tables, entity tables, governance tables, plus `tasks` and `task_steps`.
-- `apps/web` and `workers` remain starter scaffolds only; no workspace UI, runner, or background-job orchestration is shipped.
+- The accepted repo state is current through Sprint 5A.
+- Use [PRODUCT_BRIEF.md](/Users/samirusani/Desktop/Codex/AliceBot/PRODUCT_BRIEF.md) for product scope, [ARCHITECTURE.md](/Users/samirusani/Desktop/Codex/AliceBot/ARCHITECTURE.md) for implemented technical boundaries, [ROADMAP.md](/Users/samirusani/Desktop/Codex/AliceBot/ROADMAP.md) for forward planning, and [RULES.md](/Users/samirusani/Desktop/Codex/AliceBot/RULES.md) for durable operating rules.
+- Historical build and review reports have been moved under [docs/archive/sprints](/Users/samirusani/Desktop/Codex/AliceBot/docs/archive/sprints).
 
-## Stable / Trusted Areas
+## Implemented Repo Slice
 
-- Immutable event log and persisted trace model with per-user isolation.
-- Deterministic context compilation and deterministic prompt assembly over durable sources.
-- Governed memory admission, narrow deterministic explicit-preference extraction, explicit embedding storage, semantic retrieval, and deterministic hybrid memory merge during compile.
-- Deterministic policy evaluation, tool allowlist evaluation, tool routing, approval persistence, approval resolution, approved-only `proxy.echo` execution, durable execution review, and execution-budget enforcement.
-- Durable task and task-step reads, deterministic task-step sequencing, explicit task-step transitions, and explicit manual continuation with lineage validated against the parent step outcome.
-- Sprint 4O review verification:
-  - `./.venv/bin/python -m pytest tests/unit` -> `284 passed`
-  - `./.venv/bin/python -m pytest tests/integration` -> `95 passed`
+- `apps/api` is the only shipped product surface. It implements continuity, tracing, deterministic context compilation, governed memory admission and review, embeddings, semantic retrieval, entities, policy and tool governance, approval persistence and resolution, approved-only `proxy.echo` execution, execution budgets, task/task-step lifecycle reads and mutations, explicit manual continuation lineage, explicit task-step linkage for approval and execution synchronization, and deterministic rooted local task-workspace provisioning.
+- The live schema includes continuity, trace, memory, embedding, entity, governance, `tasks`, `task_steps`, and `task_workspaces` tables with row-level security on user-owned data.
+- `apps/web` and `workers` remain starter scaffolds only.
 
-## Incomplete / At-Risk Areas
+## Current Boundaries
 
-- Auth beyond DB user context is still unimplemented.
-- Memory extraction and retrieval quality remain major ship-gating risks.
-- Document ingestion, scoped task workspaces, artifact handling, and read-only connectors have not started in code.
-- The current multi-step boundary is still narrow: approval-resolution and execution-synchronization helpers continue to target `task_steps.sequence_no = 1`, even though manual continuation is now implemented for later steps.
+- Task workspaces are implemented only as deterministic rooted local directories plus durable `task_workspaces` records.
+- The shipped multi-step task path is still explicit and narrow: later steps are appended manually with lineage, while approval and execution synchronization use explicit linked `task_step_id` references.
+- The only execution handler in the repo is the in-process no-external-I/O `proxy.echo` path.
 
-## Current Milestone Position
+## Not Implemented
 
-- The repo has completed the implementation planned through Milestone 4.
-- Milestone 5 has not started in shipped code.
-- The project is at a truth-sync checkpoint before Milestone 5 entry.
+- Artifact storage or indexing beyond the local workspace boundary.
+- Document ingestion, chunking, or document retrieval.
+- Read-only Gmail or Calendar connectors.
+- Runner-style orchestration or automatic multi-step progression.
+- Auth beyond the current database user-context model.
 
-## Latest State Summary
+## Active Risks
 
-- Local runtime assets exist for Docker Compose, Postgres bootstrap, API startup, migrations, and backend tests.
-- `POST /v0/approvals/requests` now creates one durable task plus one initial task step for each routed governed request, with task and task-step lifecycle traces.
-- `GET /v0/tasks`, `GET /v0/tasks/{task_id}`, `GET /v0/tasks/{task_id}/steps`, and `GET /v0/task-steps/{task_step_id}` expose durable task/task-step review reads with deterministic ordering.
-- `POST /v0/tasks/{task_id}/steps` now appends exactly one manual continuation step when the latest step is appendable and explicit lineage points to that latest visible parent step.
-- `POST /v0/task-steps/{task_step_id}/transition` now advances only the latest visible step through the explicit status graph and keeps the parent task status synchronized.
-- Task-step lineage is trace-visible through `task.step.continuation.request`, `task.step.continuation.lineage`, and `task.step.continuation.summary` events.
+- Memory extraction and retrieval quality remain the main product risk.
+- Auth is still incomplete beyond database user context.
+- Workspace provisioning is intentionally narrow and local; broader artifact and document flows still need their own accepted seams.
 
-## Critical Constraints
+## Latest Accepted Verification
 
-- Do not treat planned workspace, connector, runner, or broader side-effect work as implemented.
-- Do not bypass approval boundaries for consequential actions.
-- Do not replace compiled durable context with raw transcript stuffing.
-- Appended task steps must carry explicit lineage; do not infer provenance heuristically from task history.
-- Keep the current multi-step boundary explicit until the first-step lifecycle helpers are removed or constrained.
+- Sprint 5A review status: `PASS`.
+- Accepted verification on March 13, 2026:
+  - `./.venv/bin/python -m pytest tests/unit` -> `315 passed`
+  - `./.venv/bin/python -m pytest tests/integration` -> `99 passed`
 
-## Immediate Next Move
+## Planning Guardrails
 
-- Take the smallest follow-up sprint that removes or explicitly constrains the remaining `task_steps.sequence_no = 1` approval/execution synchronization assumptions before any runner, workspace, or connector work begins.
+- Plan from the implemented Sprint 5A repo state, not from older milestone narratives.
+- Do not describe Milestone 5 document, artifact, connector, or runner work as shipped.
+- Keep live truth files compact; archive historical detail instead of re-expanding the active context set.