Sprint 5A: Task Workspace Records and Provisioning

.ai/active/SPRINT_PACKET.md

@@ -0,0 +1,123 @@
+# SPRINT_PACKET.md
+
+## Sprint Title
+
+Sprint 5A: Task Workspace Records and Provisioning
+
+## Sprint Type
+
+feature
+
+## 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.
+
+## 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.
+
+## Git Instructions
+
+- Branch Name: `codex/sprint-5a-task-workspaces`
+- 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
+
+## Why This Sprint
+
+- 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.
+
+## 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
+
+## 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.
+
+## Required Deliverables
+
+- 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.
+
+## 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/agents/.gitkeep

@@ -0,0 +1 @@
+

.ai/handoff/CURRENT_STATE.md

@@ -0,0 +1,53 @@
+# Current State
+
+## What Exists Today
+
+- 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.
+
+## Stable / Trusted Areas
+
+- 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`
+
+## Incomplete / At-Risk Areas
+
+- 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.
+
+## Current Milestone Position
+
+- 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.
+
+## Latest State Summary
+
+- 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.
+
+## Critical Constraints
+
+- 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.
+
+## Immediate Next Move
+
+- 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.

.ai/templates/.gitkeep

@@ -0,0 +1 @@
+

.env.example

@@ -0,0 +1,12 @@
+APP_ENV=development
+APP_HOST=127.0.0.1
+APP_PORT=8000
+DATABASE_URL=postgresql://alicebot_app:alicebot_app@localhost:5432/alicebot
+DATABASE_ADMIN_URL=postgresql://alicebot_admin:alicebot_admin@localhost:5432/alicebot
+REDIS_URL=redis://localhost:6379/0
+S3_ENDPOINT_URL=http://localhost:9000
+S3_ACCESS_KEY=alicebot
+S3_SECRET_KEY=alicebot-secret
+S3_BUCKET=alicebot-local
+HEALTHCHECK_TIMEOUT_SECONDS=2
+TASK_WORKSPACE_ROOT=/tmp/alicebot/task-workspaces

.gitignore

@@ -0,0 +1,9 @@
+.DS_Store
+.env
+.pytest_cache/
+.venv/
+*.egg-info/
+__pycache__/
+*.pyc
+apps/web/.next/
+apps/web/node_modules/