zopu-code/docs/dev-plan.md

# Zopu Work OS — Development Plan

> **Related:** `slices.md` defines product increments; `dev-loop.md` defines the normative delivery loop; `evaluation.md` defines promotion gates.

> **Purpose:** concrete implementation order for the repository.  
> **Strategy:** one vertical product loop, contracts first, provider adapters second, generalization last.

## 1. Target demonstration

Use one real repository and one deterministic Work:

> Add `GET /health` returning `{ status: "ok", commit: "<sha>" }`, with automated and live HTTP verification, then create a verified PR.

The first release is successful only when the full path works from chat to exact PR evidence.

## 2. Engineering rules

1. Land domain contracts before parallel adapter/UI work.
2. Keep FLUE, Rivet, Cube, AgentOS, and harness types behind ports.
3. One side effect has one idempotency key.
4. One mutating attempt owns one worktree.
5. Every state transition has a command, event, actor, timestamp, and evidence reference.
6. Every async process has timeout, cancellation, retry policy, and terminal classification.
7. Builder output is candidate output until independent verification passes.
8. Do not generalize until two real use cases require it.
9. Do not add an agent role without an evaluation showing quality gain.
10. Keep manual merge/deploy gates initially.

## 3. Repository workstreams

Recommended logical ownership:

```text
A. Domain/actors
B. FLUE definition/design agents
C. Resolver/runtime/harness
D. Verification/Git
E. Web experience
F. Deployment/operations
```

Only parallelize after shared schemas and event contracts are merged.

## 4. Phase 0 — Baseline and contracts

### Deliverables

- repository architecture inventory;
- one canonical glossary;
- schemas for Message, Signal, Work, WorkDefinition, DesignPacket, VerticalSlice, Run, Attempt, Artifact, Question;
- Work/Attempt state machines;
- command/event list;
- port interfaces;
- static `CodingKitV0`;
- deterministic fixture project/task.

### Tests

- schema round trips;
- state transition property/table tests;
- idempotency tests;
- fake adapters;
- actor restart/replay tests.

### Exit gate

A fake end-to-end test can create Work, approve definition/design, run fake slices, verify, and produce a fake PR artifact.

## 5. Milestone A — Work exists (Slices 1–2)

### Issue order

1. Persist project messages.
2. Implement `ProcessMessage`.
3. FLUE structured Signal/Work proposal.
4. Signal fingerprinting and attach/create rules.
5. WorkActor/projection.
6. Reactive Work card.
7. Work Definition schema/versioning.
8. Definition compiler agent.
9. definition edit/approval/questions UI.
10. approval invalidation tests.

### Release gate

```text
message → exact Signal → proposed card → approved Work Definition
```

No runtime integration.

## 6. Milestone B — Work is executable (Slices 3–5)

### Issue order

1. ImpactMap/DesignPacket schemas.
2. design compiler and slice planner.
3. design review/version UI.
4. Resolver decision function as pure domain logic.
5. WorkActor resolver commands/events.
6. FakeHarness/FakeSandbox adapters.
7. AttemptActor lifecycle.
8. CubeSandbox adapter.
9. selected harness adapter (OMP first unless spike rejects it).
10. Git worktree preparation.
11. normalized activity stream.
12. cancellation/timeout/cleanup.

### Contract freeze before adapter work

```text
HarnessEvent
SandboxLease
AttemptInput/Outcome
Artifact metadata
```

### Release gate

```text
approved design → one real slice → isolated repository changes
```

No PR claim yet.

## 7. Milestone C — Work is trustworthy (Slices 6–7)

### Issue order

1. VerificationPlan schema.
2. command-check runner.
3. HTTP-check runner.
4. revision/environment binding.
5. verifier role/process.
6. repair-attempt loop.
7. design-conformance evidence.
8. Git commit/push adapter.
9. PR creation adapter with idempotency.
10. review-package generator/UI.
11. exact-SHA invariant tests.

### Required quality fixture

For the health task, prove:

```text
new test fails on base
candidate passes focused tests
service starts
GET /health returns expected body
candidate SHA equals PR head SHA
```

### Release gate

A human can review and merge a real verified PR without reading raw agent logs.

## 8. Milestone D — Work is steerable (Slice 8)

### Issue order

1. Question/Decision lifecycle.
2. harness permission/question normalization.
3. attention UI.
4. contextual answer routing.
5. same-session resume and restarted-session recovery.
6. stale-question/version protections.

### Release gate

A deliberate ambiguity blocks Work, receives an answer, and resumes without duplicate execution.

## 9. Milestone E — Work survives complexity (Slices 9–10)

### Issue order

1. multi-slice commit model.
2. IntegrationActor/use case.
3. conflict/overlap analysis.
4. integrated verification.
5. preview adapter.
6. release/rollback policy.
7. observation and WorkResult.
8. incident/result-to-Signal loop.

### Release gate

Two slices pass independently, integrate on one SHA, publish preview, and produce an observed result.

## 10. Milestone F — System improvement (Slices 11–12)

### Issue order

1. post-run evaluation schema.
2. learning synthesis.
3. knowledge proposal/diff workflow.
4. Kit registry/versioning.
5. Kit compiler.
6. tool/skill registry.
7. role evaluation harness.
8. controlled parallel fleet.
9. policy fallback to static Kit.

### Release gate

A completed run proposes a reviewable Kit/knowledge improvement, and a second run demonstrably benefits.

## 11. Actor rollout

### Initial

```text
ProjectActor
WorkActor
AttemptActor
```

WorkActor contains Resolver state and verification orchestration initially.

### Split only when justified

```text
VerificationActor — independent check lifecycle becomes complex
IntegrationActor  — multi-branch/slice composition exists
ResultActor       — deployment observation exists
ResolverActor     — scheduling lifecycle needs independent ownership
```

Avoid actor-per-record designs.

## 12. Test architecture

### Domain

- transition tables;
- invariants;
- retry/budget logic;
- dependency graph readiness;
- approval/version invalidation;
- completion rules.

### Application

- command → event → projection;
- idempotent side effects;
- crash/restart recovery;
- timeout/cancellation;
- stale command rejection.

### Adapter contract tests

Run same suite against fake and live adapters:

```text
HarnessRuntime
SandboxRuntime
SourceControl
ArtifactStore
```

### End-to-end

Maintain fixtures:

```text
happy path
casual message/no Work
duplicate message
definition revision
design rejection
harness transient failure
human question/resume
verification repair
retry exhaustion
PR duplicate callback
actor restart mid-attempt
cancellation
```

### Quality evaluation

Before adding a new model/role/Kit, compare:

- success rate;
- escaped defect rate;
- review changes requested;
- retries;
- human attention;
- cost/time;
- design deviation.

## 13. Operational rollout

### Local

- fake adapters;
- local Rivet/AgentOS;
- one local repository fixture.

### Internal VPS

- deployed Rivet actors;
- Bun/Effect daemon;
- private Cube API;
- one OMP template;
- test forge repository.

### Dogfood repository

- real branch/PR;
- manual review;
- no production deploy;
- collect every failure.

### Controlled release

- one project/user;
- quotas;
- kill switch;
- audit trail;
- explicit external side-effect gates.

## 14. Security checklist before real repositories

```text
private control-plane networking
Cube/Rivet authentication
short-lived Git/model credentials
sandbox egress policy
no host HOME mounts
tool allowlist
artifact authorization
secret redaction
attempt timeout/cleanup
manual merge/deploy
audit approvals
```

## 15. Branch/PR sequencing

Suggested integration branch:

```text
dogfood/v0
```

Per-slice branches:

```text
dogfood/s01-work
dogfood/s02-definition
...
```

Within a slice, parallel branches may cover:

```text
contracts/domain
backend/actor
frontend
adapter
tests
```

Merge order:

```text
contracts → domain/actor → adapters/UI → integration tests
```

Every branch must target the current slice integration branch, not independently invent shared schemas.

## 16. First backlog

Execute exactly in this order:

```text
01 glossary + schemas
02 Work/Attempt state machines
03 commands/events/idempotency
04 fake E2E harness
05 message persistence
06 Signal extraction
07 Work card
08 Work Definition
09 definition approval
10 Design Packet
11 vertical-slice planner
12 design approval
13 Resolver with fake harness
14 AttemptActor
15 CubeSandbox adapter
16 OMP adapter/spike
17 real repository mutation
18 VerificationRuntime
19 repair loop
20 Git commit/push/PR
21 review package
22 contextual question/resume
23 integration verification
24 preview/release/result
25 learning proposals
26 dynamic Kit Builder
```

## 17. First production-quality acceptance test

```text
Given:
- one configured project/repository;
- one actionable user message;
- no pre-existing Work.

When:
- Zopu processes the message;
- the user approves definition/design;
- the Resolver executes all slices;
- verification passes;
- publication is requested.

Then:
- one Signal and one Work exist;
- exact provenance is preserved;
- every attempt has a terminal outcome;
- one verified candidate SHA exists;
- all required checks bind to that SHA;
- one PR exists at that SHA;
- the Work card explains intent, design, changes, evidence, and next action;
- actor/process restarts produce no duplicate Work, attempts, commits, or PRs.
```

## 18. Stop conditions

Pause feature expansion when any is true:

- stale “running” Work exists;
- duplicate external side effects occur;
- verification cannot identify exact SHA/environment;
- human cannot understand why a Work is “done”;
- retries are unbounded;
- agents bypass actor/application commands;
- provider-specific assumptions leak into domain;
- new roles add cost without measured quality improvement.

Fix the completion system before adding more autonomy.