zopu-code/docs/PRODUCT.md

# Zopu Work OS — Product Specification

> **Related:** `dev-loop.md` defines delivery; `slices.md` defines product increments; `evaluation.md` defines quality measurement.

> **Status:** Working source of truth  
> **Audience:** product, design, engineering, agents  
> **Normative words:** **MUST** = required, **SHOULD** = default, **MAY** = optional  
> **Product boundary:** this file defines *what and why*, not implementation details.

## 1. Thesis

Zopu is a **completion system for durable units of work**, not a chat wrapper and not a coding-agent launcher.

The product converts conversation and external events into verified outcomes:

```text
Talk/events → Signals → Work → Definition → Design → Slices
→ Resolution → Verification → Delivery → Observation → Learning
```

The core promise:

> Given an accepted unit of work, Zopu keeps advancing it until a verified outcome exists or a precise terminal blocker is recorded.

Agents may propose, plan, implement, review, and test. **The system decides completion from evidence.**

## 2. Initial customer and scope

### ICP v0

Technical founders and small engineering teams working in one Git repository.

### Supported v0 workflow

```text
Project chat
→ actionable Signal
→ approved Work Definition
→ lightweight Design Packet
→ vertical slices
→ isolated coding run
→ independent verification
→ branch + pull request
→ human merge
→ result assessment
```

### v0 constraints

- One user/organization/project/repository path first.
- Web interface only.
- One implementation harness first.
- One sandbox provider first.
- Manual merge.
- No autonomous production mutation.
- No arbitrary generated tools receiving immediate execution authority.
- No generic support for every founder workflow yet.

The domain must remain broader than Git, but the implementation should prove quality on software delivery first.

## 3. Product surfaces

The primary interface remains intentionally small:

```text
1. Continuous project conversation
2. Work cards
3. Human attention queue
```

### Continuous conversation

One project-level conversation is used to:

- discuss intent;
- create Signals;
- ask about Work;
- add evidence or constraints;
- change priorities;
- respond to agent questions.

Conversation is not the system of record for execution state.

### Work cards

A Work card is the durable, inspectable representation of one desired outcome. It exposes definition, design, execution, evidence, delivery, and result without forcing the user to inspect raw agent transcripts.

### Attention queue

All decisions requiring a human are first-class objects:

- clarify intent;
- approve definition/design;
- grant permission;
- select an alternative;
- review a slice;
- approve merge/release;
- accept risk.

## 4. Canonical domain

### Signal

Evidence that may require attention.

```text
Signal
├── exact source/provenance
├── extracted meaning
├── project context
├── confidence
├── related signals
└── candidate Work links
```

A Signal MUST preserve the original source. A model summary never replaces evidence.

### Work

A durable desired outcome, not a message, issue, session, branch, or PR.

```text
Work
├── objective
├── reason/user impact
├── source Signals
├── Work Definition
├── Design Packet
├── slices/steps
├── runs/attempts
├── questions/decisions
├── artifacts/evidence
├── delivery
└── result
```

### Work Definition

A testable contract before implementation:

- problem;
- desired outcome;
- affected users;
- in/out of scope;
- acceptance criteria;
- constraints;
- assumptions;
- unresolved questions;
- risk class;
- required artifacts;
- rollout/rollback requirements when applicable.

### Design Packet

A reviewable implementation intent:

- impact map;
- architecture summary/sequence;
- file-tree diff;
- call-flow diff;
- key types/interfaces;
- invariants;
- migration/security/operational concerns;
- vertical slice plan;
- explicit trade-offs and deviations.

### Vertical Slice

A bounded unit of implementation that produces observable, independently verifiable progress.

A valid slice answers:

- what behavior becomes observable;
- what code boundaries change;
- what artifacts must exist;
- what evidence proves completion;
- what review is required before continuation.

### Kit

A versioned executable configuration for resolving a class of Work:

- roles/agent definitions;
- tools and grants;
- skills/instructions;
- context policy;
- runtime requirements;
- harness policy;
- budgets;
- output contracts;
- verification recipes;
- escalation policy.

A Kit is not an agent and not a run. v0 uses one static Coding Kit; dynamic Kit Builder comes after the loop is reliable.

### Run and Attempt

A Run coordinates execution for Work or a slice. An Attempt is one bounded execution by one harness in one environment.

Attempt terminal classifications:

```text
Succeeded | RetryableFailure | NeedsInput | Blocked
| VerificationFailed | BudgetExhausted | Cancelled | PermanentFailure
```

“Agent working” is not a durable outcome.

### Artifact and Evidence

Examples:

- plan/design;
- diff;
- test report;
- screenshot/video;
- commit;
- PR;
- preview;
- deployment;
- runtime logs;
- performance/security reports.

Every artifact SHOULD include producer, Work/slice/run, source revision, environment, provenance, and verification status.

### Result

Delivery is not necessarily outcome. Result compares intended and actual impact:

```text
Achieved | PartiallyAchieved | NotAchieved | Regressed | Inconclusive
```

### Learning

Post-work observations that may propose updates to:

- project knowledge;
- architecture decisions;
- test recipes;
- skills;
- tools;
- Kit definitions;
- planning heuristics.

Canonical knowledge updates require review.

## 5. Quality doctrine

High-quality software is evaluated across:

| Dimension | Required question |
|---|---|
| Correctness | Does behavior satisfy the accepted criteria? |
| Regression safety | Did existing behavior remain valid? |
| Maintainability | Does the change preserve understandable boundaries? |
| Security | Are permissions, secrets, data, and dependencies safe? |
| Reliability | Are failures and edge cases handled? |
| Operability | Can it be deployed, observed, debugged, and rolled back? |
| Performance | Are expected resource limits preserved? |
| UX | Does the actual user path work? |
| Traceability | Can claims be tied to evidence and revisions? |
| Reversibility | Can risk be disabled or rolled back? |

### Completion rule

Work is complete only when:

1. accepted behavior is implemented on a known revision;
2. required checks pass in a known environment;
3. design deviations are visible;
4. required human gates are satisfied;
5. delivery artifacts exist;
6. post-release observation is completed when required.

A passing test suite is necessary but not sufficient for medium/high-risk work.

### Builder-verifier separation

The implementation worker MUST NOT be the sole authority on completion.

```text
Builder → candidate output
Verifier → independent evidence
Resolver → completion decision
Human → policy-defined approvals
```

### Risk lanes

#### Fast

Copy, docs, isolated styling, deterministic mechanical changes.

```text
short contract → implement → verify → PR
```

#### Standard

Normal features, APIs, workflows, changes spanning a few modules.

```text
definition → combined design → 1–3 slices → verify → review → PR
```

#### Critical

Auth, billing, permissions, migrations, shared infrastructure, destructive operations.

```text
definition approval → architecture approval → program-design approval
→ one slice at a time → staged release → observation/rollback gate
```

## 6. Resolver contract

The Work Resolver is the central product engine.

It MUST continuously answer:

- What remains incomplete?
- What is executable now?
- What capability can perform it?
- What evidence is missing?
- Should it retry, repair, replan, escalate, or stop?
- Has the Work reached a valid terminal state?

Resolver outcomes:

```text
VerifiedOutcomeDelivered
VerifiedPRReady
HumanDecisionRequired
ExternalDependencyBlocked
BudgetExhaustedWithEvidence
PermanentlyFailedWithDiagnosis
Cancelled
```

The Resolver MUST:

- operate from durable state;
- execute bounded attempts;
- enforce budgets and permissions;
- preserve provenance;
- recover after process failure;
- avoid duplicate side effects;
- require evidence before transitions;
- surface precise blockers;
- never silently stall.

## 7. Human operating model

Humans should spend attention on high-leverage decisions, not supervise tool calls.

Preferred gates:

- Work Definition approval;
- Design Packet approval for standard/critical work;
- slice review when risk requires it;
- merge/release approval;
- resolution of ambiguity or policy exceptions.

A human request must include:

```text
decision needed
why it is needed
recommended action
alternatives
consequences
urgency
affected Work/slice
```

## 8. External collaboration

Buzz, Slack-like systems, Git forges, monitoring, support, and analytics are interfaces and Signal sources.

They MAY:

- create Signals;
- carry status updates;
- present questions;
- receive review/preview links;
- report incidents and results.

They MUST NOT own canonical Work, Resolver, verification, or completion state.

## 9. Product success metrics

Primary:

- verified outcomes per unit of human attention;
- median time from accepted Work to verified PR/outcome;
- percentage of Work reaching an explicit terminal state;
- verification escape rate;
- post-merge rework rate;
- design-review-to-implementation deviation rate.

Secondary:

- retry count;
- human interruption count;
- stale Work count;
- duplicate Signal/Work rate;
- average review-package comprehension time;
- Kit/version performance by work type.

Avoid optimizing token volume, agent count, or code generated.

## 10. Non-goals for early versions

- Fully autonomous company operation.
- Lights-off merging/deployment.
- Universal dynamic tool creation.
- Large unbounded fleets.
- Replacing Git or CI.
- Encoding all product truth in chat.
- Making one model/harness part of the product domain.
- Automating maintainability judgment without human policy.