zopu-code/docs/agent-context.md

# Zopu Work OS — Agent Context

> **Purpose:** compact bootstrap context for Codex/OMP/OpenCode/FLUE workers contributing to Zopu.  
> **Usage:** read this first, then load only task-relevant documents and repository files.

## 1. Mission

Build Zopu: a Work OS that turns conversation and external Signals into durable, verified outcomes.

```text
Signal → Work → Definition → Design → Vertical Slices
→ Resolver → Attempts → Verification → Delivery → Result → Learning
```

The product is not chat threads, an issue tracker, a harness UI, or an autonomous PR factory.

## 2. Source-of-truth order

```text
1. current accepted Work/Question/Decision
2. approved Work Definition
3. approved Design Packet + current Slice
4. repository tests/types/code
5. product.md
6. tech.md
7. design.md
8. dev-loop.md
9. slices.md
10. dev-plan.md
11. glossary.md
12. evaluation.md
```

When sources conflict, report the conflict. Do not silently choose a convenient interpretation.

## 3. Current product target

Initial user:

```text
technical founder / small engineering team
one project + one Git repository
web chat + Work cards
manual merge
```

Initial complete loop:

```text
message
→ Signal
→ approved Work
→ approved Design Packet
→ one bounded coding slice
→ independent verification
→ exact verified commit
→ real PR
→ human intervention/resume
```

## 4. Non-negotiable invariants

1. Work is a durable outcome, not a chat/session/issue/PR.
2. Exact Signal provenance is preserved.
3. State transitions are explicit commands/events.
4. FLUE/model output is validated proposal data, not authority.
5. Rivet actors own serialized lifecycle/recovery.
6. Harnesses and runtimes are replaceable adapters.
7. One mutating Attempt owns one isolated worktree.
8. Every Attempt is bounded and terminally classified.
9. Builder output remains candidate output until independent verification.
10. Evidence binds to exact revision and environment.
11. Published PR head equals verified integrated SHA.
12. Human questions/approvals are durable objects.
13. Retry/restart must not duplicate Work, commits, PRs, or deployments.
14. Merge/deploy remain human-gated initially.
15. Completion requires outcome evidence, not an agent’s “done.”

## 5. System ownership

```text
Work OS       durable intent/state/evidence/policy
Rivet actors  identity, serialization, timers, recovery
FLUE          domain agents/workflows and typed proposals
Harness       bounded coding/tool loop
Sandbox       filesystem/process/network isolation
Git           source history
ArtifactStore durable output/evidence
UI/Buzz       interaction surfaces, not workflow truth
```

## 6. Initial actor shape

```text
ProjectActor
├── project config + active Work index

WorkActor
├── definition/design/slices
├── resolver state
├── questions/approvals
├── artifacts/result

AttemptActor
├── runtime lease
├── harness session
├── normalized events
├── timeout/cancellation/outcome
```

Add Verification/Integration/Result actors only when their lifecycles justify separation.

## 7. Initial adapters

Preferred first implementation:

```text
FLUE          definition/design/resolver support
Rivet         actors
CubeSandbox   full Linux runtime
OMP           first coding harness, replaceable
Git forge     branch/commit/PR
Convex        durable application data/projections where used
Effect        application ports/layers/errors/scopes/streams
```

Do not import provider-specific types into domain modules.

## 8. Working protocol for every code task

### Before editing

1. Identify current vertical slice and acceptance criteria.
2. Read relevant docs and repository rules.
3. Inspect current architecture, tests, and existing abstractions.
4. State impacted modules and risks.
5. Produce/confirm a small implementation plan.
6. Ask a Question only when ambiguity changes behavior, security, data, or architecture.

### During implementation

1. Stay within the current slice.
2. Preserve dependency direction.
3. Prefer existing patterns over parallel frameworks.
4. Add typed boundaries and tagged errors.
5. Make external effects idempotent.
6. Add cancellation/timeouts for long-running operations.
7. Record exact revisions/provider identifiers.
8. Add tests with the implementation.
9. Do not weaken unrelated tests or hide failures.
10. Explain intentional Design Packet deviations.

### Before declaring candidate ready

Run task-relevant checks:

```text
format/lint/typecheck
focused unit/integration tests
behavioral/live check
security/secret check where relevant
design-conformance review
```

Report:

```text
files changed
behavior implemented
checks run + results
known risks/deviations
artifacts/revision
remaining blockers
```

Never claim verified unless the independent verification path ran.

## 9. Code organization rule

Use logical separation:

```text
domain/       pure types/state/invariants
application/  use cases/commands
ports/        Effect services
adapters/     FLUE/Rivet/Cube/OMP/Git implementations
```

Keep the initial package count practical. A folder boundary is enough until independent reuse/lifecycle exists.

## 10. State modeling rule

Prefer explicit state machines over booleans.

Bad:

```ts
isRunning: boolean;
isDone: boolean;
hasError: boolean;
```

Good:

```ts
type AttemptStatus =
  | "queued"
  | "running"
  | "succeeded"
  | "retryable_failure"
  | "needs_input"
  | "blocked"
  | "verification_failed"
  | "budget_exhausted"
  | "cancelled"
  | "permanent_failure";
```

Transitions must validate current version/state.

## 11. Model/agent output rule

Agents return schemas such as:

```text
SignalProposal
WorkDefinitionProposal
DesignPacketProposal
ResolverDecisionProposal
VerificationAssessment
LearningProposal
```

Application code decodes, authorizes, and executes commands. Agents do not directly mutate arbitrary state.

## 12. Quality rule

For every behavior, identify:

```text
acceptance criterion
implementation evidence
independent check
exact candidate revision
review requirement
```

Tests prove immediate behavior. Design review protects maintainability and future change cost. Both matter.

## 13. UI rule

Expose:

```text
outcome
phase
latest meaningful update
next action/blocker
slice progress
evidence
delivery/result
```

Hide low-level harness noise by default. Preserve raw logs in diagnostics.

## 14. Scope control

Do not implement unless required by the current slice:

- dynamic Kit Builder;
- multiple harness providers;
- large fleets;
- autonomous merge/deploy;
- universal workflows;
- automatic canonical-memory mutation;
- sophisticated multi-tenancy.

Design replaceable boundaries, then ship one path.

## 15. Task completion template

```md
## Implemented

- ...

## Behavior

- ...

## Verification run

- `command` — pass/fail
- ...

## Evidence

- candidate SHA/artifacts
- ...

## Design deviations

- none / ...

## Remaining risks or blockers

- none / ...
```

## 16. Required reading by task type

| Task               | Read                                     |
| ------------------ | ---------------------------------------- |
| product/domain     | product.md, glossary.md                  |
| UI                 | design.md, product.md                    |
| actors/state       | tech.md, glossary.md                     |
| orchestration      | dev-loop.md, tech.md                     |
| current sequencing | slices.md, dev-plan.md                   |
| verification/evals | evaluation.md, dev-loop.md               |
| provider adapter   | tech.md plus provider docs               |
| broad feature      | agent-context.md + all relevant sections |

## 17. Stop and escalate when

- accepted definition/design is missing or contradictory;
- required permission is unavailable;
- worktree/revision identity is uncertain;
- a destructive action is outside policy;
- verification cannot bind to exact candidate;
- implementation requires expanding scope materially;
- a retry would repeat a non-transient failure;
- repository state suggests another active mutating owner.

Return a precise Question or blocker, not a guess.