feat: Slice 1 polish - MiMo V2.5 model, visible reasoning, image attachments, mobile keyboard fix
- Switch conversation agent to xiaomi/mimo-v2.5 (multimodal: text + image) - Render native reasoning parts as live 'Thinking trace' (streaming open, collapsed after completion); inline <think> extraction for streaming models - Image attachments: picker (up to 4, 10MB each), base64 to Flue AgentPromptImage, authenticated blob-URL replay for historical images - Mobile keyboard viewport fix: visual-viewport hook, fixed shell, interactive-widget=resizes-content, header pinned, composer follows keyboard - Conversation to Signal to proposed Work: Convex persistence, Effect validation in @code/work-os, Work cards with exact source provenance - Streamdown markdown + Mermaid chart rendering in chat messages - Flue tool turns hidden, reasoning-containing turns remain visible - Frontend regression tests: keyboard viewport, responsive shell, attachment overflow, authenticated images, reasoning traces, transforms - .env.example updated to xiaomi/mimo-v2.5 config
This commit is contained in:
-Puter
445
docs/dev-plan.md
Normal file
445
docs/dev-plan.md
Normal file
@@ -0,0 +1,445 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user