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

Observe problem
→ define outcome
→ design solution
→ deliver slices
→ release
→ observe result
→ learn/revise

Inner slice loop

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:

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.

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.

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.

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

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

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

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:

packages/resolver/
+ domain/resolution-decision.ts
+ application/resolve-next-slice.ts
+ ports/harness-runtime.ts
+ adapters/omp-harness-live.ts

Example call-flow intent:

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

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

build all database code
→ build all backend code
→ build all frontend code
→ test at end

Preferred plan

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

Work Definition
Design Packet
current Slice
project/repository policy
risk lane
tool/runtime/harness registry
previous evidence and decisions

Output: immutable Execution Kit version

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:

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

MeaningfulProgress
ToolStarted/Completed
QuestionRaised
ArtifactProduced
CandidateReady
AttemptFailed
AttemptCancelled

Raw provider events remain diagnostics, not product state.

Attempt terminal outcomes

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:

Work/slice/run/attempt
candidate SHA
environment/runtime
command or assertion
exit/status
evidence artifact
timestamp
verifier identity/version

Repair loop

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

slice objective
approved design intent
actual behavior
meaningful code narrative
verification evidence
design deviations
risks/questions
recommended decision

Decisions

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

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

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:

verified candidate
→ preview/staging
→ approval
→ rollout
→ health observation
→ accept or rollback

Observation compares:

expected success signal
vs
actual production/user result

Final classifications:

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:

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

definition approval
design approval
risk/permission exception
slice review
merge/release approval
result acceptance
knowledge update approval

Question format

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

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