zopu-code/docs/dev-loop.md

# 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.