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
705
docs/dev-loop.md
Normal file
705
docs/dev-loop.md
Normal file
@@ -0,0 +1,705 @@
|
||||
# Zopu Work OS — Software Development Loop
|
||||
|
||||
> **Purpose:** canonical operating process for producing high-quality software with humans and agents.
|
||||
> **Applies to:** Zopu product development and software Work resolved by Zopu.
|
||||
> **Core principle:** accelerate implementation without removing design judgment, independent verification, or release learning.
|
||||
|
||||
## 1. The model
|
||||
|
||||
Software delivery contains two nested loops.
|
||||
|
||||
### Outer product loop
|
||||
|
||||
```text
|
||||
Observe problem
|
||||
→ define outcome
|
||||
→ design solution
|
||||
→ deliver slices
|
||||
→ release
|
||||
→ observe result
|
||||
→ learn/revise
|
||||
```
|
||||
|
||||
### Inner slice loop
|
||||
|
||||
```text
|
||||
Select approved slice
|
||||
→ prepare isolated candidate
|
||||
→ implement
|
||||
→ verify behavior
|
||||
→ verify design conformance
|
||||
→ review/resteer
|
||||
→ integrate
|
||||
```
|
||||
|
||||
The outer loop proves that the right problem was solved. The inner loop proves that each implementation increment is correct and preserves the intended system shape.
|
||||
|
||||
The system optimizes:
|
||||
|
||||
```text
|
||||
verified progress / human-attention minute
|
||||
```
|
||||
|
||||
It does not optimize commits, tokens, agents, PR count, or code volume.
|
||||
|
||||
## 2. Why this process exists
|
||||
|
||||
Agent harnesses compress implementation time but do not remove these failure modes:
|
||||
|
||||
- ambiguous requirements implemented literally;
|
||||
- locally correct code that damages system boundaries;
|
||||
- horizontal plans whose behavior is visible only at the end;
|
||||
- tests that pass while the user path is wrong;
|
||||
- builder self-certification;
|
||||
- parallel changes that fail when integrated;
|
||||
- merged code that does not solve the original problem;
|
||||
- lessons lost after delivery.
|
||||
|
||||
Therefore decisions move earlier and implementation is divided into reviewable vertical slices.
|
||||
|
||||
## 3. Delivery routes
|
||||
|
||||
Risk determines ceremony.
|
||||
|
||||
### Fast lane
|
||||
|
||||
Use for isolated, reversible, deterministic changes.
|
||||
|
||||
```text
|
||||
Work Definition
|
||||
→ compact design note
|
||||
→ implement
|
||||
→ automated verification
|
||||
→ PR
|
||||
```
|
||||
|
||||
Required human gate: merge or policy exception.
|
||||
|
||||
### Standard lane
|
||||
|
||||
Use for normal product behavior, APIs, UI flows, and multi-module changes.
|
||||
|
||||
```text
|
||||
Work Definition
|
||||
→ impact analysis
|
||||
→ program design
|
||||
→ 1–4 vertical slices
|
||||
→ slice verification/review
|
||||
→ integrated verification
|
||||
→ PR
|
||||
```
|
||||
|
||||
Required gates: definition/design approval and merge.
|
||||
|
||||
### Critical lane
|
||||
|
||||
Use for authentication, authorization, billing, migrations, destructive operations, secrets, shared infrastructure, or high blast radius.
|
||||
|
||||
```text
|
||||
Work Definition approval
|
||||
→ architecture approval
|
||||
→ program-design approval
|
||||
→ one slice at a time
|
||||
→ security/rollback verification
|
||||
→ staged release approval
|
||||
→ observation
|
||||
```
|
||||
|
||||
A risk classifier may recommend a lane; policy makes the final decision.
|
||||
|
||||
## 4. Phase A — Problem and product definition
|
||||
|
||||
### Inputs
|
||||
|
||||
- user conversation;
|
||||
- Signals and provenance;
|
||||
- incidents/analytics/support;
|
||||
- project strategy and constraints;
|
||||
- existing related Work.
|
||||
|
||||
### Required artifact: Work Definition
|
||||
|
||||
```text
|
||||
problem
|
||||
affected users
|
||||
desired observable outcome
|
||||
success signals
|
||||
in scope / out of scope
|
||||
acceptance criteria
|
||||
constraints
|
||||
assumptions
|
||||
unresolved questions
|
||||
risk lane
|
||||
required artifacts
|
||||
release/rollback requirements
|
||||
```
|
||||
|
||||
### Rules
|
||||
|
||||
- Acceptance criteria describe behavior, not implementation.
|
||||
- Assumptions are explicit and labeled.
|
||||
- Important ambiguity becomes a Question, not hidden prompt context.
|
||||
- The original Signal remains attached.
|
||||
- A changed definition creates a new version and invalidates dependent approvals.
|
||||
|
||||
### Gate
|
||||
|
||||
Proceed when the definition is testable, important questions are resolved, and required approval exists.
|
||||
|
||||
## 5. Phase B — System impact and architecture
|
||||
|
||||
### Goal
|
||||
|
||||
Determine how the change interacts with the existing system before code is generated.
|
||||
|
||||
### Required artifact: Impact Map
|
||||
|
||||
```text
|
||||
directly changed components
|
||||
potentially affected components
|
||||
data/security boundaries
|
||||
public contracts
|
||||
migrations and compatibility
|
||||
operational effects
|
||||
required verification categories
|
||||
```
|
||||
|
||||
### Architecture artifact
|
||||
|
||||
Use only the detail needed for the Work:
|
||||
|
||||
- component/sequence diagram;
|
||||
- API/event contracts;
|
||||
- data ownership;
|
||||
- trust and permission boundaries;
|
||||
- migration/rollout shape;
|
||||
- failure and recovery paths.
|
||||
|
||||
Architecture describes component interaction. It does not replace program design.
|
||||
|
||||
### Gate
|
||||
|
||||
Proceed when affected boundaries and externally visible contracts are understood.
|
||||
|
||||
## 6. Phase C — Program design
|
||||
|
||||
### Goal
|
||||
|
||||
Make implementation intent cheap to review before code volume exists.
|
||||
|
||||
### Required artifact: Design Packet
|
||||
|
||||
```text
|
||||
architecture summary
|
||||
expected file-tree delta
|
||||
expected call-flow delta
|
||||
key types/interfaces/signatures
|
||||
dependency direction
|
||||
invariants
|
||||
error model
|
||||
state transitions
|
||||
security/operational concerns
|
||||
trade-offs
|
||||
known deviations
|
||||
```
|
||||
|
||||
Example file-tree intent:
|
||||
|
||||
```diff
|
||||
packages/resolver/
|
||||
+ domain/resolution-decision.ts
|
||||
+ application/resolve-next-slice.ts
|
||||
+ ports/harness-runtime.ts
|
||||
+ adapters/omp-harness-live.ts
|
||||
```
|
||||
|
||||
Example call-flow intent:
|
||||
|
||||
```text
|
||||
WorkActor.start
|
||||
→ resolveNextSlice
|
||||
→ AttemptActor.start
|
||||
→ SandboxRuntime.create
|
||||
→ HarnessRuntime.open/prompt
|
||||
→ normalize outcome
|
||||
→ VerificationRuntime.execute
|
||||
→ WorkActor.transition
|
||||
```
|
||||
|
||||
### Review questions
|
||||
|
||||
- Is the dependency direction correct?
|
||||
- Does one module own each invariant?
|
||||
- Is the next likely change still local?
|
||||
- Is complexity introduced where it belongs?
|
||||
- Are persistence and external side effects idempotent?
|
||||
- Are failure, cancellation, and recovery explicit?
|
||||
- Can the behavior be verified independently?
|
||||
|
||||
### Gate
|
||||
|
||||
Standard/critical Work requires an approved Design Packet. Small fast-lane Work may use a compact design note.
|
||||
|
||||
## 7. Phase D — Vertical slice planning
|
||||
|
||||
### Goal
|
||||
|
||||
Turn design into increments that are observable, executable, and reviewable.
|
||||
|
||||
### Slice contract
|
||||
|
||||
```text
|
||||
objective
|
||||
user/system behavior exposed
|
||||
planned code boundaries
|
||||
inputs/dependencies
|
||||
expected outputs/artifacts
|
||||
verification checks
|
||||
review requirement
|
||||
budget/retry policy
|
||||
```
|
||||
|
||||
### Valid slice
|
||||
|
||||
A slice:
|
||||
|
||||
- crosses the layers needed to expose behavior;
|
||||
- produces evidence before later slices;
|
||||
- can be reverted or revised without discarding the full implementation;
|
||||
- is small enough for one focused review;
|
||||
- does not postpone all integration/testing until the end.
|
||||
|
||||
### Invalid horizontal plan
|
||||
|
||||
```text
|
||||
build all database code
|
||||
→ build all backend code
|
||||
→ build all frontend code
|
||||
→ test at end
|
||||
```
|
||||
|
||||
### Preferred plan
|
||||
|
||||
```text
|
||||
Slice 1: one durable Work transition visible in UI
|
||||
Slice 2: one isolated execution attempt visible in UI
|
||||
Slice 3: independent verification visible in UI
|
||||
Slice 4: verified PR artifact visible in UI
|
||||
```
|
||||
|
||||
Agents should receive only the current approved slice plus necessary surrounding context, not an invitation to redesign the whole system.
|
||||
|
||||
## 8. Phase E — Kit compilation
|
||||
|
||||
### Goal
|
||||
|
||||
Compile approved intent into an executable, policy-bound package.
|
||||
|
||||
### Inputs
|
||||
|
||||
```text
|
||||
Work Definition
|
||||
Design Packet
|
||||
current Slice
|
||||
project/repository policy
|
||||
risk lane
|
||||
tool/runtime/harness registry
|
||||
previous evidence and decisions
|
||||
```
|
||||
|
||||
### Output: immutable Execution Kit version
|
||||
|
||||
```text
|
||||
roles
|
||||
context selection
|
||||
skills/instructions
|
||||
tool grants
|
||||
runtime capabilities
|
||||
harness selection
|
||||
source-control policy
|
||||
output contracts
|
||||
verification recipe
|
||||
budgets/timeouts
|
||||
human gates
|
||||
escalation policy
|
||||
```
|
||||
|
||||
v0 uses a static Coding Kit. Dynamic selection/composition follows only after repeated runs establish useful patterns.
|
||||
|
||||
### Kit invariants
|
||||
|
||||
- least-privilege tools;
|
||||
- no self-granted capabilities;
|
||||
- explicit model/runtime/harness;
|
||||
- bounded compute and retries;
|
||||
- exact expected artifacts;
|
||||
- verifiers separated from builders;
|
||||
- version recorded on every Run.
|
||||
|
||||
## 9. Phase F — Slice execution
|
||||
|
||||
### Preparation
|
||||
|
||||
The Resolver:
|
||||
|
||||
1. confirms the slice and design versions are current;
|
||||
2. resolves dependencies;
|
||||
3. creates Run and Attempt records;
|
||||
4. prepares an isolated worktree/base SHA;
|
||||
5. provisions runtime;
|
||||
6. injects scoped context and credentials;
|
||||
7. starts the selected harness.
|
||||
|
||||
### Implementer contract
|
||||
|
||||
The implementer receives:
|
||||
|
||||
```text
|
||||
current slice only
|
||||
accepted Work Definition
|
||||
relevant Design Packet excerpt
|
||||
repository rules
|
||||
completion/evidence contract
|
||||
known previous failures/decisions
|
||||
explicit forbidden actions
|
||||
```
|
||||
|
||||
It may inspect surrounding code as needed but must not expand scope silently.
|
||||
|
||||
### Normalized execution events
|
||||
|
||||
```text
|
||||
MeaningfulProgress
|
||||
ToolStarted/Completed
|
||||
QuestionRaised
|
||||
ArtifactProduced
|
||||
CandidateReady
|
||||
AttemptFailed
|
||||
AttemptCancelled
|
||||
```
|
||||
|
||||
Raw provider events remain diagnostics, not product state.
|
||||
|
||||
### Attempt terminal outcomes
|
||||
|
||||
```text
|
||||
Succeeded
|
||||
RetryableFailure
|
||||
NeedsInput
|
||||
Blocked
|
||||
VerificationFailed
|
||||
BudgetExhausted
|
||||
Cancelled
|
||||
PermanentFailure
|
||||
```
|
||||
|
||||
No attempt remains indefinitely active. Timeouts and process death are classified outcomes.
|
||||
|
||||
## 10. Phase G — Independent verification
|
||||
|
||||
### Principle
|
||||
|
||||
Candidate output is not complete output.
|
||||
|
||||
### Verification layers
|
||||
|
||||
#### Static
|
||||
|
||||
- format/lint/typecheck;
|
||||
- dependency policy;
|
||||
- secret/security scan;
|
||||
- generated-file consistency.
|
||||
|
||||
#### Behavioral
|
||||
|
||||
- focused unit/integration/contract tests;
|
||||
- new tests fail on base and pass on candidate where practical;
|
||||
- service startup and live API assertions;
|
||||
- database/migration behavior.
|
||||
|
||||
#### Product
|
||||
|
||||
- real browser/user path;
|
||||
- screenshots/video;
|
||||
- accessibility/visual checks;
|
||||
- frontend/backend interaction.
|
||||
|
||||
#### Operational
|
||||
|
||||
- build/start/health;
|
||||
- logs and failure handling;
|
||||
- resource limits;
|
||||
- rollout/rollback checks.
|
||||
|
||||
#### Design
|
||||
|
||||
- expected vs actual files/interfaces/call paths;
|
||||
- dependency graph changes;
|
||||
- duplicated logic;
|
||||
- unjustified casts/exceptions;
|
||||
- explicit deviations from approved design.
|
||||
|
||||
### Verification record
|
||||
|
||||
Every check binds to:
|
||||
|
||||
```text
|
||||
Work/slice/run/attempt
|
||||
candidate SHA
|
||||
environment/runtime
|
||||
command or assertion
|
||||
exit/status
|
||||
evidence artifact
|
||||
timestamp
|
||||
verifier identity/version
|
||||
```
|
||||
|
||||
### Repair loop
|
||||
|
||||
```text
|
||||
failed evidence
|
||||
→ Resolver classifies
|
||||
→ bounded repair attempt
|
||||
→ implementer receives exact failure
|
||||
→ full required verification reruns
|
||||
```
|
||||
|
||||
Passing only the failed command is insufficient when the candidate changed.
|
||||
|
||||
## 11. Phase H — Slice review and resteering
|
||||
|
||||
Policy decides whether human review is required after each slice.
|
||||
|
||||
### Review package
|
||||
|
||||
```text
|
||||
slice objective
|
||||
approved design intent
|
||||
actual behavior
|
||||
meaningful code narrative
|
||||
verification evidence
|
||||
design deviations
|
||||
risks/questions
|
||||
recommended decision
|
||||
```
|
||||
|
||||
### Decisions
|
||||
|
||||
```text
|
||||
Accept slice
|
||||
Request repair
|
||||
Revise design
|
||||
Split/reorder slices
|
||||
Stop/cancel Work
|
||||
```
|
||||
|
||||
Resteering updates durable definition/design/slice versions. It is not an informal chat instruction lost inside a harness transcript.
|
||||
|
||||
## 12. Phase I — Integration
|
||||
|
||||
Individually valid slices may be invalid together.
|
||||
|
||||
### Integration flow
|
||||
|
||||
```text
|
||||
compose candidate commits
|
||||
→ resolve conflict/overlap
|
||||
→ produce integrated SHA
|
||||
→ run impacted + required checks
|
||||
→ generate integrated review package
|
||||
```
|
||||
|
||||
### Invariants
|
||||
|
||||
- the PR head equals the verified integrated SHA;
|
||||
- checks identify exact revision/environment;
|
||||
- overlapping assumptions are surfaced;
|
||||
- no slice bypasses integrated verification;
|
||||
- failures return to repair/replan, not silent merge.
|
||||
|
||||
## 13. Phase J — Delivery
|
||||
|
||||
### Delivery artifacts
|
||||
|
||||
```text
|
||||
commit
|
||||
branch
|
||||
pull request
|
||||
preview/staging URL
|
||||
release notes
|
||||
migration/rollback plan
|
||||
```
|
||||
|
||||
Creating a PR is a delivery transition, not completion of the original outcome.
|
||||
|
||||
### Human review
|
||||
|
||||
The review experience should explain:
|
||||
|
||||
1. original intent;
|
||||
2. accepted behavior;
|
||||
3. architecture/program design;
|
||||
4. slice narrative;
|
||||
5. important diffs;
|
||||
6. evidence;
|
||||
7. deviations/risks;
|
||||
8. exact revision and next action.
|
||||
|
||||
Manual merge remains the initial policy.
|
||||
|
||||
## 14. Phase K — Release and observation
|
||||
|
||||
For releasable Work:
|
||||
|
||||
```text
|
||||
verified candidate
|
||||
→ preview/staging
|
||||
→ approval
|
||||
→ rollout
|
||||
→ health observation
|
||||
→ accept or rollback
|
||||
```
|
||||
|
||||
Observation compares:
|
||||
|
||||
```text
|
||||
expected success signal
|
||||
vs
|
||||
actual production/user result
|
||||
```
|
||||
|
||||
Final classifications:
|
||||
|
||||
```text
|
||||
Achieved
|
||||
PartiallyAchieved
|
||||
NotAchieved
|
||||
Regressed
|
||||
Inconclusive
|
||||
```
|
||||
|
||||
Failure or unexpected behavior creates new Signals linked to the original Work.
|
||||
|
||||
## 15. Phase L — Learning
|
||||
|
||||
After terminal Work, evaluate both output and process.
|
||||
|
||||
### Questions
|
||||
|
||||
- Was intent captured correctly?
|
||||
- Did design predict implementation?
|
||||
- Which slice boundaries worked poorly?
|
||||
- Which attempts/retries occurred and why?
|
||||
- Which context/tools were missing?
|
||||
- Which verification found defects?
|
||||
- Which defects escaped?
|
||||
- Did human review request major changes?
|
||||
- Did release achieve the result?
|
||||
- Should project knowledge, a Kit, skill, tool, or policy change?
|
||||
|
||||
### Outputs
|
||||
|
||||
Reviewable proposals:
|
||||
|
||||
```text
|
||||
knowledge update
|
||||
architecture decision
|
||||
test recipe
|
||||
Kit/tool/skill revision
|
||||
planning heuristic
|
||||
follow-up Work
|
||||
```
|
||||
|
||||
No automatic mutation of canonical knowledge.
|
||||
|
||||
## 16. Human attention model
|
||||
|
||||
Humans intervene at policy-defined gates, not every tool action.
|
||||
|
||||
### High-value gates
|
||||
|
||||
```text
|
||||
definition approval
|
||||
design approval
|
||||
risk/permission exception
|
||||
slice review
|
||||
merge/release approval
|
||||
result acceptance
|
||||
knowledge update approval
|
||||
```
|
||||
|
||||
### Question format
|
||||
|
||||
```text
|
||||
decision required
|
||||
why it blocks progress
|
||||
recommended answer
|
||||
alternatives
|
||||
consequences
|
||||
affected Work/slice/version
|
||||
```
|
||||
|
||||
Answers are durable Decisions and resume the same Work.
|
||||
|
||||
## 17. Resolver decision table
|
||||
|
||||
| Condition | Resolver action |
|
||||
|---|---|
|
||||
| executable slice exists | start bounded Attempt |
|
||||
| transient infrastructure/model failure | retry by policy |
|
||||
| candidate fails checks | create repair Attempt with evidence |
|
||||
| design appears invalid | enter Replanning |
|
||||
| required information missing | open Question; enter NeedsInput |
|
||||
| dependency unavailable | enter Blocked with recheck/escalation |
|
||||
| budget exhausted | terminal outcome with evidence |
|
||||
| all slices pass | integrated verification |
|
||||
| integrated candidate passes | publish/review |
|
||||
| release requires observation | enter Observing |
|
||||
| result established | complete and synthesize learning |
|
||||
|
||||
## 18. Failure and recovery rules
|
||||
|
||||
- Durable state is written before external effects.
|
||||
- External provider IDs are persisted before acknowledging completion.
|
||||
- Commands are idempotent.
|
||||
- Actor/process restart resumes from checkpoints.
|
||||
- Leases expire and are reclaimed.
|
||||
- Sandbox/harness termination is best-effort plus reconciliation.
|
||||
- Stale callbacks are rejected by version/attempt identity.
|
||||
- Every terminal failure includes diagnosis, evidence, and recommended next action.
|
||||
|
||||
## 19. Anti-patterns
|
||||
|
||||
Do not:
|
||||
|
||||
- send a vague issue directly to a fleet;
|
||||
- let the harness own Work state;
|
||||
- equate tests passing with maintainability;
|
||||
- generate all layers before exposing behavior;
|
||||
- let the builder be sole verifier;
|
||||
- hide design changes inside implementation;
|
||||
- merge independently verified branches without integrated checks;
|
||||
- create duplicate PRs/deployments on retry;
|
||||
- mark Work complete at PR creation;
|
||||
- auto-update canonical knowledge from one run;
|
||||
- add agents because parallelism appears impressive.
|
||||
|
||||
## 20. Definition of a high-quality delivered Work
|
||||
|
||||
```text
|
||||
✓ original evidence preserved
|
||||
✓ outcome and acceptance criteria approved
|
||||
✓ risk lane correct
|
||||
✓ impact/design reviewed as required
|
||||
✓ vertical slices independently demonstrated
|
||||
✓ every Attempt terminal and auditable
|
||||
✓ candidate verified independently
|
||||
✓ design deviations explicit
|
||||
✓ integrated SHA verified
|
||||
✓ review package understandable
|
||||
✓ delivery/release policy satisfied
|
||||
✓ actual result assessed
|
||||
✓ learning captured as proposals
|
||||
```
|
||||
|
||||
This document is the normative delivery process. `slices.md` defines how Zopu itself is built incrementally; this file defines how Zopu and its agents should build software.
|
||||
Reference in New Issue
Block a user