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

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:

WorkDefinition(versioned)
DefinitionApproval
Question
RiskClass

FLUE compiles:

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

Work state:

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:

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:

Run
Attempt
ResolverDecision
KitVersion
HarnessRuntime port
FakeHarnessLive

Static CodingKitV0.

Implement durable loop:

Ready → ExecutingSlice → VerifyingSlice → NextSlice

Attempt outcomes:

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:

SandboxRuntime = AgentOsSandboxLive
HarnessRuntime = CodexHarnessLive
Durable orchestration = Convex Workflow

Flow:

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:

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:

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:

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:

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:

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:

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

Outputs immutable/versioned ExecutionKit.

Add roles only with measurable value:

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

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.