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:

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

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

HarnessEvent
SandboxLease
AttemptInput/Outcome
Artifact metadata

Release gate

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:

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

ProjectActor
WorkActor
AttemptActor

WorkActor contains Resolver state and verification orchestration initially.

Split only when justified

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:

HarnessRuntime
SandboxRuntime
SourceControl
ArtifactStore

End-to-end

Maintain fixtures:

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

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:

dogfood/v0

Per-slice branches:

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

Within a slice, parallel branches may cover:

contracts/domain
backend/actor
frontend
adapter
tests

Merge order:

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:

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

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.