zopu-code/docs/slices.md

# Zopu Work OS — Vertical Slices

> **Related:** `dev-loop.md` defines the software-building process; `dev-plan.md` defines implementation sequencing.

> **Purpose:** ordered product increments. Complete each slice end-to-end before starting the next.  
> **Reference task:** “Add `GET /health` returning status and current build commit.”  
> **Rule:** every slice must produce visible product behavior, durable state, and automated acceptance coverage.

## Global definition of done

For every slice:

- schema/state migrations applied;
- commands/events are idempotent;
- actor restart does not corrupt state;
- frontend handles loading/error/empty states;
- important actions are audited;
- unit/integration tests cover invariants;
- no provider-specific types leak into domain;
- docs updated when contracts change.

## Slice 1 — Conversation → Signal → Work card

### User outcome

A user message creates one actionable Signal and one proposed Work card with exact provenance.

### Backend

```text
Message
Signal
Work
WorkEvent
ProcessMessage → structured FLUE proposal → validated command
```

Implement:

- persist exact message;
- Signal fingerprint/idempotency;
- create vs attach decision;
- proposed Work state;
- Work event feed.

### Frontend

- continuous chat;
- inline Work creation notice;
- collapsed reactive Work card;
- source-message link.

### Acceptance

- duplicate processing creates no duplicate Signal/Work;
- casual message creates no Work;
- actionable message creates one Work;
- card survives refresh/restart;
- exact source text is recoverable.

### Explicitly exclude

Planning, sandboxes, Git, verification.

---

## Slice 2 — Work Definition and approval

### User outcome

The proposed Work becomes a testable outcome contract that can be edited and approved.

### Backend

Add:

```text
WorkDefinition(versioned)
DefinitionApproval
Question
RiskClass
```

FLUE compiles:

- problem;
- desired outcome;
- scope/non-goals;
- acceptance criteria;
- assumptions/questions;
- risk.

Work state:

```text
Proposed → Defining → AwaitingDefinitionApproval → Designing
```

### Frontend

Expanded Outcome section; edit/approve/request revision; unresolved-question cards.

### Acceptance

- high-impact unresolved question blocks approval;
- approval binds exact version;
- revision invalidates stale approval;
- risk lane is visible;
- definition can be reconstructed from event history.

---

## Slice 3 — Design Packet and vertical slices

### User outcome

The user can review expected architecture/code shape and approve a bounded slice plan before coding.

### Backend

Add versioned:

```text
ImpactMap
DesignPacket
VerticalSlice
VerificationPlan
DesignApproval
```

Required Design Packet fields:

- affected systems/files;
- architecture summary;
- expected file-tree/call-flow changes;
- key types/invariants;
- risks/trade-offs;
- 1–4 vertical slices;
- evidence requirements per slice.

### Frontend

Design section with diagram, file tree, call flow, slices, version diff, approval.

### Acceptance

- horizontal “backend/frontend/test later” plan rejected;
- each slice is independently observable/verifiable;
- approval binds definition+design versions;
- changed definition invalidates dependent design;
- Work reaches `Ready`.

---

## Slice 4 — Resolver state machine with fake harness

### User outcome

Starting Work visibly advances slices, retries bounded failures, and surfaces blockers without real code execution.

### Backend

Add:

```text
Run
Attempt
ResolverDecision
KitVersion
HarnessRuntime port
FakeHarnessLive
```

Static `CodingKitV0`.

Implement durable loop:

```text
Ready → ExecutingSlice → VerifyingSlice → NextSlice
```

Attempt outcomes:

```text
Succeeded | RetryableFailure | NeedsInput | Blocked
| VerificationFailed | BudgetExhausted | Cancelled | PermanentFailure
```

### Frontend

Slice progress, meaningful activity, retry count, stop/retry controls, question state.

### Acceptance

- injected transient failure retries up to policy;
- restart resumes from durable state;
- no executable step produces explicit failure;
- cancellation terminates attempt;
- no Work remains permanently “running.”

---

## Slice 5 — Real sandbox + implementation harness

### User outcome

Zopu implements one approved slice in an isolated repository environment and streams useful progress.

### Backend

Initial adapter choice:

```text
SandboxRuntime = AgentOsSandboxLive
HarnessRuntime = CodexHarnessLive
Durable orchestration = Convex Workflow
```

Flow:

```text
load the project's authenticated Git connection
→ start durable Convex workflow
→ create AgentOS execution environment
→ clone the single configured repo
→ inject context
→ run one slice
→ normalize events
→ collect diff/artifacts
→ pause/terminate
```

Security:

- GitHub OAuth or self-hosted Gitea PAT, scoped to one project;
- scoped Git/model tokens passed only to private execution;
- isolated HOME/worktree;
- one mutating attempt per worktree;
- timeout/cancel cleanup.

### Frontend

Project selector/settings, Git connection status, current activity, changed files, artifact links, expandable raw logs, cancel/retry, and manual Git delivery controls.

### Acceptance

- real repository file changes occur;
- another Work cannot see/modify checkout;
- cancellation stops process;
- provider failure becomes classified attempt outcome;
- exact base/candidate revision recorded.

Rivet Engine coordinates AgentOS actor placement through a normal runner, but does not own product orchestration; Convex Workflow remains canonical for the Run lifecycle. Cube/Kubernetes sandbox support remains behind `SandboxRuntime` and can be mounted through AgentOS incrementally.

---

## Slice 6 — Independent verification and repair

### User outcome

The card shows objective evidence; failed checks trigger a bounded repair loop.

### Backend

Implement `VerificationRuntime` and verifier role.

Initial checks:

```text
format/lint/typecheck
focused tests
service start
HTTP behavior
secret scan
expected vs actual files/interfaces
test weakening/deletion detection
```

Bind result to candidate SHA/environment.

Repair:

```text
failure evidence → repair attempt → clean rerun
```

### Frontend

Evidence checklist, exact failures, candidate SHA, repair status.

### Acceptance

- implementer cannot self-mark passed;
- failed check stores output/exit code;
- repair receives exact evidence;
- max attempts enforced;
- final verdict is Passed/Failed/Inconclusive.

---

## Slice 7 — Git publication and review package

### User outcome

A verified candidate becomes a real branch/commit/PR with an understandable review package.

### Backend

`SourceControl` adapter:

```text
commit → push → create PR
```

Idempotent artifact creation; verify PR head SHA equals verified SHA.

Generate review package:

- intent/definition/design;
- slice narrative;
- important diffs;
- screenshots/API evidence;
- checks;
- deviations/risks.

### Frontend

Delivery section, PR action, narrative review package.

### Acceptance

- no duplicate PR after retry;
- exact verified SHA published;
- PR link survives restart;
- merge remains human-controlled;
- request-changes action returns Work to appropriate state.

**Milestone:** first useful product.

---

## Slice 8 — Contextual human intervention

### User outcome

A blocked agent asks one precise question; the user answers from the Work card; the same Work resumes.

### Backend

Durable `Question`/`Decision`; map response to Work/slice/attempt/harness session.

### Frontend

Attention card with recommendation, alternatives, consequences; contextual composer.

### Acceptance

- answer persists before resume;
- harness restart does not lose decision;
- stale questions cannot mutate newer plan;
- response never creates unrelated thread;
- attention queue orders blockers correctly.

---

## Slice 9 — Multi-slice integration verification

### User outcome

Several passing slices are combined and tested as one exact candidate before PR readiness.

### Backend

Add `IntegrationActor`/use case:

```text
compose commits
detect overlap/conflict
rebase/resolve policy
run impacted checks on integrated SHA
```

### Frontend

Integration state, conflict blocker, combined evidence.

### Acceptance

- individually passing slices cannot skip combined checks;
- conflicts become explicit blockers;
- integrated SHA is the published SHA;
- failed integration can replan/repair.

---

## Slice 10 — Preview, release, and observation

### User outcome

The user can inspect a preview, approve delivery, and see whether the released behavior works.

### Backend

Provider-neutral `PreviewRuntime`/release adapter. Add:

```text
RolloutPlan
RollbackPlan
HealthSignal
ObservationWindow
WorkResult
```

### Frontend

Preview link, release gate, health state, expected-vs-actual result.

### Acceptance

- preview binds candidate SHA;
- release requires policy-defined approval;
- observation records actual behavior;
- rollback trigger is explicit for critical work;
- merged PR alone does not mark outcome achieved.

---

## Slice 11 — Learning and knowledge proposals

### User outcome

Completed Work produces reviewable improvements to project knowledge and execution policy.

### Backend

Synthesize:

- planning errors;
- missing context;
- useful/failing tools;
- escaped defects;
- Kit/test recommendations.

Create proposal artifacts, never direct canonical mutation.

### Frontend

Diffable learning cards: accept/edit/reject.

### Acceptance

- every proposal cites run/evidence;
- rejection is retained;
- accepted update is versioned;
- no autonomous rewrite of canonical docs.

---

## Slice 12 — Dynamic Kit Builder and controlled fleet

### User outcome

Zopu selects/composes the right roles, tools, runtime, and checks for different software Work while preserving policy.

### Backend

Kit compiler inputs:

```text
Work Definition + risk + Design Packet + project policy
+ runtime/tool registry + previous results
```

Outputs immutable/versioned `ExecutionKit`.

Add roles only with measurable value:

```text
investigator implementer verifier security-reviewer
browser-tester integration-coordinator
```

### Acceptance

- Kit is explainable/versioned;
- tool grants are least privilege;
- budgets enforced;
- role addition has evaluation evidence;
- dynamic tools are proposed/reviewed before trust;
- fallback static Kit remains available.

## Dependency graph

```text
1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10 → 11 → 12
```

Parallel engineering is allowed _within_ a slice after contracts land, but product release order remains sequential.